--- /dev/null
+*.aux
+*.cp
+*.cps
+*.dvi
+*.fn
+*.fns
+*.ky
+*.kys
+*.log
+*.op
+*.ops
+*.pdf
+*.pg
+*.pgs
+*.ps
+*.tmp
+*.toc
+*.tp
+*.tps
+*.vr
+*.vrs
+Makefile
+makefile
--- /dev/null
+2007-09-06 Glenn Morris <rgm@gnu.org>
+
+ * Move manual sources from man/ to subdirectories of doc/.
+ Split into the Emacs manual in emacs/, and other manuals in misc/.
+ Change all setfilename commands to use ../../info.
+ * Makefile.in: Move the parts of the old man/Makefile.in that do not
+ refer to the Emacs manual here.
+ (infodir): New variable.
+ (INFO_TARGETS, info): Use infodir. Also used by all info targets.
+ (cc-mode.texi, faq.texi): Update references to source file locations.
+ * makefile.w32-in: Move the parts of the old man/makefile.w32-in that
+ do not refer to the Emacs manual here.
+ (infodir, MULTI_INSTALL_INFO, ENVADD): Go up one more level.
+
+ * Makefile.in: Add `basename' versions of all info targets, for
+ convenience when rebuilding just one manual.
+ (../etc/GNU): Delete obsolete target.
+ (.SUFFIXES): Use $(TEXI2DVI) rather than texi2dvi.
+ (mostlyclean): Add *.op, *.ops. Move *.aux *.cps *.fns *.kys *.pgs
+ *.vrs *.toc here...
+ (maintainer-clean): ...from here.
+
+ * makefile.w32-in (../etc/GNU): Delete obsolete target.
+
+;; Local Variables:
+;; coding: iso-2022-7bit
+;; fill-column: 79
+;; add-log-time-zone-rule: t
+;; End:
+
+ Copyright (C) 2007 Free Software Foundation, Inc.
+
+ This file is part of GNU Emacs.
+
+ GNU Emacs 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 3, or (at your option)
+ any later version.
+
+ GNU Emacs 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 GNU Emacs; see the file COPYING. If not, write to the
+ Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
+
--- /dev/null
+#### Makefile for the Emacs Manual and other documentation.
+
+# Copyright (C) 1994, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
+# 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+# This file is part of GNU Emacs.
+
+# GNU Emacs 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 3, or (at your option)
+# any later version.
+
+# GNU Emacs 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 GNU Emacs; see the file COPYING. If not, write to
+# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+# Boston, MA 02110-1301, USA.
+
+# Where to find the source code. $(srcdir) will be the man
+# subdirectory of the source tree. This is
+# set by the configure script's `--srcdir' option.
+srcdir=@srcdir@
+top_srcdir=@top_srcdir@
+
+# Tell make where to find source files; this is needed for the makefiles.
+VPATH=@srcdir@
+
+
+# The makeinfo program is part of the Texinfo distribution.
+# Use --force so that it generates output even if there are errors.
+MAKEINFO = makeinfo --force
+INFO_TARGETS = ../info/emacs ../info/ccmode ../info/cl \
+ ../info/dired-x ../info/ediff ../info/forms ../info/gnus \
+ ../info/message ../info/sieve ../info/pgg ../info/emacs-mime \
+ ../info/info ../info/mh-e ../info/reftex \
+ ../info/sc ../info/vip ../info/viper ../info/widget \
+ ../info/efaq ../info/ada-mode ../info/autotype ../info/calc \
+ ../info/idlwave ../info/eudc ../info/ebrowse ../info/pcl-cvs \
+ ../info/woman ../info/eshell ../info/org ../info/url \
+ ../info/speedbar ../info/tramp ../info/ses ../info/smtpmail \
+ ../info/flymake ../info/newsticker ../info/rcirc ../info/erc
+DVI_TARGETS = emacs.dvi calc.dvi cc-mode.dvi cl.dvi dired-x.dvi \
+ ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \
+ gnus.dvi message.dvi sieve.dvi pgg.dvi mh-e.dvi \
+ reftex.dvi sc.dvi vip.dvi viper.dvi widget.dvi faq.dvi \
+ ada-mode.dvi autotype.dvi idlwave.dvi eudc.dvi ebrowse.dvi \
+ pcl-cvs.dvi woman.dvi eshell.dvi org.dvi url.dvi \
+ speedbar.dvi tramp.dvi ses.dvi smtpmail.dvi flymake.dvi \
+ newsticker.dvi emacs-xtra.dvi rcirc.dvi erc.dvi
+INFOSOURCES = info.texi
+
+# The following rule does not work with all versions of `make'.
+.SUFFIXES: .texi .dvi
+.texi.dvi:
+ texi2dvi $<
+
+TEXI2DVI = texi2dvi
+ENVADD = TEXINPUTS="$(srcdir):$(TEXINPUTS)" MAKEINFO="$(MAKEINFO) -I$(srcdir)"
+
+EMACS_XTRA=\
+ $(srcdir)/arevert-xtra.texi \
+ $(srcdir)/cal-xtra.texi \
+ $(srcdir)/dired-xtra.texi \
+ $(srcdir)/picture-xtra.texi \
+ $(srcdir)/emerge-xtra.texi \
+ $(srcdir)/vc-xtra.texi \
+ $(srcdir)/vc1-xtra.texi \
+ $(srcdir)/vc2-xtra.texi \
+ $(srcdir)/fortran-xtra.texi \
+ $(srcdir)/msdog-xtra.texi
+
+EMACSSOURCES= \
+ ${srcdir}/emacs.texi \
+ ${srcdir}/doclicense.texi \
+ ${srcdir}/gpl.texi \
+ ${srcdir}/screen.texi \
+ ${srcdir}/commands.texi \
+ ${srcdir}/entering.texi \
+ ${srcdir}/basic.texi \
+ ${srcdir}/mini.texi \
+ ${srcdir}/m-x.texi \
+ ${srcdir}/help.texi \
+ ${srcdir}/mark.texi \
+ ${srcdir}/killing.texi \
+ ${srcdir}/regs.texi \
+ ${srcdir}/display.texi \
+ ${srcdir}/search.texi \
+ ${srcdir}/fixit.texi \
+ ${srcdir}/files.texi \
+ ${srcdir}/buffers.texi \
+ ${srcdir}/windows.texi \
+ ${srcdir}/frames.texi \
+ ${srcdir}/mule.texi \
+ ${srcdir}/major.texi \
+ ${srcdir}/indent.texi \
+ ${srcdir}/text.texi \
+ ${srcdir}/programs.texi \
+ ${srcdir}/building.texi \
+ ${srcdir}/maintaining.texi \
+ ${srcdir}/abbrevs.texi \
+ ${srcdir}/sending.texi \
+ ${srcdir}/rmail.texi \
+ ${srcdir}/dired.texi \
+ ${srcdir}/calendar.texi \
+ ${srcdir}/misc.texi \
+ ${srcdir}/custom.texi \
+ ${srcdir}/trouble.texi \
+ ${srcdir}/cmdargs.texi \
+ ${srcdir}/xresources.texi \
+ ${srcdir}/anti.texi \
+ ${srcdir}/macos.texi \
+ ${srcdir}/msdog.texi \
+ ${srcdir}/gnu.texi \
+ ${srcdir}/glossary.texi \
+ ${srcdir}/ack.texi \
+ ${srcdir}/kmacro.texi \
+ $(EMACS_XTRA)
+
+info: $(top_srcdir)/info $(INFO_TARGETS)
+
+$(top_srcdir)/info:
+ mkdir $@
+
+dvi: $(DVI_TARGETS)
+
+# Note that all the Info targets build the Info files
+# in srcdir. There is no provision for Info files
+# to exist in the build directory.
+# In a distribution of Emacs, the Info files should be up to date.
+
+# The following target uses an explicit -o switch to work around
+# the @setfilename directive in info.texi, which is required for
+# the Texinfo distribution.
+
+../info/info: ${INFOSOURCES}
+ cd $(srcdir); $(MAKEINFO) --no-split info.texi -o $@
+
+info.dvi: ${INFOSOURCES}
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/info.texi
+
+../info/emacs: ${EMACSSOURCES}
+ cd $(srcdir); $(MAKEINFO) emacs.texi
+
+emacs.dvi: ${EMACSSOURCES}
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs.texi
+
+# This target is here so you could easily get the list of the *.texi
+# files which belong to the Emacs manual (as opposed to the separate
+# manuals for CL, CC Mode, Ebrowse, etc.). With this target, you can
+# say things like "grep foo `make emacsman`".
+emacsman:
+ @echo $(EMACSSOURCES)
+
+../info/ccmode: cc-mode.texi
+ cd $(srcdir); $(MAKEINFO) cc-mode.texi
+cc-mode.dvi: cc-mode.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/cc-mode.texi
+
+../info/ada-mode: ada-mode.texi
+ cd $(srcdir); $(MAKEINFO) ada-mode.texi
+ada-mode.dvi: ada-mode.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/ada-mode.texi
+
+../info/pcl-cvs: pcl-cvs.texi
+ cd $(srcdir); $(MAKEINFO) pcl-cvs.texi
+pcl-cvs.dvi: pcl-cvs.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/pcl-cvs.texi
+
+../info/eshell: eshell.texi
+ cd $(srcdir); $(MAKEINFO) eshell.texi
+eshell.dvi: eshell.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/eshell.texi
+
+../info/cl: cl.texi
+ cd $(srcdir); $(MAKEINFO) cl.texi
+cl.dvi: cl.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/cl.texi
+
+../info/dired-x: dired-x.texi
+ cd $(srcdir); $(MAKEINFO) dired-x.texi
+dired-x.dvi: dired-x.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/dired-x.texi
+
+../info/ediff: ediff.texi
+ cd $(srcdir); $(MAKEINFO) ediff.texi
+ediff.dvi: ediff.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/ediff.texi
+
+emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA)
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-xtra.texi
+
+../info/forms: forms.texi
+ cd $(srcdir); $(MAKEINFO) forms.texi
+forms.dvi: forms.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/forms.texi
+
+# gnus/message/emacs-mime/sieve/pgg are part of Gnus:
+../info/gnus: gnus.texi gnus-faq.texi
+ cd $(srcdir); $(MAKEINFO) gnus.texi
+gnus.dvi: gnus.texi gnus-faq.texi
+ sed -e '/@iflatex/,/@end iflatex/d' ${srcdir}/gnus.texi > gnustmp.texi
+ $(ENVADD) $(TEXI2DVI) gnustmp.texi
+ cp gnustmp.dvi $*.dvi
+ rm gnustmp.*
+
+../info/message: message.texi
+ cd $(srcdir); $(MAKEINFO) message.texi
+message.dvi: message.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/message.texi
+
+../info/sieve: sieve.texi
+ cd $(srcdir); $(MAKEINFO) sieve.texi
+sieve.dvi: sieve.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/sieve.texi
+
+../info/emacs-mime: emacs-mime.texi
+ cd $(srcdir); $(MAKEINFO) --enable-encoding emacs-mime.texi
+emacs-mime.dvi: emacs-mime.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-mime.texi
+
+../info/pgg: pgg.texi
+ cd $(srcdir); $(MAKEINFO) pgg.texi
+pgg.dvi: pgg.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/pgg.texi
+
+../info/mh-e: mh-e.texi
+ cd $(srcdir); $(MAKEINFO) mh-e.texi
+mh-e.dvi: mh-e.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/mh-e.texi
+
+../info/reftex: reftex.texi
+ cd $(srcdir); $(MAKEINFO) reftex.texi
+reftex.dvi: reftex.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/reftex.texi
+
+../info/sc: sc.texi
+ cd $(srcdir); $(MAKEINFO) sc.texi
+sc.dvi: sc.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/sc.texi
+
+../info/vip: vip.texi
+ cd $(srcdir); $(MAKEINFO) vip.texi
+vip.dvi: vip.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/vip.texi
+
+../info/viper: viper.texi
+ cd $(srcdir); $(MAKEINFO) viper.texi
+viper.dvi: viper.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/viper.texi
+
+../info/widget: widget.texi
+ cd $(srcdir); $(MAKEINFO) widget.texi
+widget.dvi: widget.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/widget.texi
+
+../info/efaq: faq.texi
+ cd $(srcdir); $(MAKEINFO) faq.texi
+faq.dvi: faq.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/faq.texi
+
+../etc/GNU: gnu1.texi gnu.texi
+ cd $(srcdir) && makeinfo --no-headers -o ../etc/GNU gnu1.texi
+
+../info/autotype: autotype.texi
+ cd $(srcdir); $(MAKEINFO) autotype.texi
+autotype.dvi: autotype.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/autotype.texi
+
+../info/calc: calc.texi
+ cd $(srcdir); $(MAKEINFO) calc.texi
+
+calc.dvi: calc.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/calc.texi
+
+# This is produced with --no-split to avoid making files whose
+# names clash on DOS 8+3 filesystems
+../info/idlwave: idlwave.texi
+ cd $(srcdir); $(MAKEINFO) --no-split idlwave.texi
+idlwave.dvi: idlwave.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/idlwave.texi
+
+../info/eudc: eudc.texi
+ cd $(srcdir); $(MAKEINFO) eudc.texi
+eudc.dvi: eudc.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/eudc.texi
+
+../info/ebrowse: ebrowse.texi
+ cd $(srcdir); $(MAKEINFO) ebrowse.texi
+ebrowse.dvi: ebrowse.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/ebrowse.texi
+
+../info/woman: woman.texi
+ cd $(srcdir); $(MAKEINFO) woman.texi
+woman.dvi: woman.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/woman.texi
+
+../info/org: org.texi
+ cd $(srcdir); $(MAKEINFO) org.texi
+org.dvi: org.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/org.texi
+
+../info/url: url.texi
+ cd $(srcdir); $(MAKEINFO) url.texi
+url.dvi: url.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/url.texi
+
+../info/speedbar: speedbar.texi
+ cd $(srcdir); $(MAKEINFO) speedbar.texi
+speedbar.dvi: speedbar.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/speedbar.texi
+
+../info/tramp: tramp.texi trampver.texi
+ cd $(srcdir); $(MAKEINFO) -D emacs tramp.texi
+tramp.dvi: tramp.texi trampver.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/tramp.texi
+
+../info/ses: ses.texi
+ cd $(srcdir); $(MAKEINFO) ses.texi
+ses.dvi: ses.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/ses.texi
+
+../info/smtpmail: smtpmail.texi
+ cd $(srcdir); $(MAKEINFO) smtpmail.texi
+smtpmail.dvi: smtpmail.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/smtpmail.texi
+
+../info/flymake: flymake.texi
+ cd $(srcdir); $(MAKEINFO) flymake.texi
+flymake.dvi: flymake.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/flymake.texi
+
+../info/newsticker: newsticker.texi
+ cd $(srcdir); $(MAKEINFO) newsticker.texi
+newsticker.dvi: newsticker.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/newsticker.texi
+
+../info/rcirc: rcirc.texi
+ cd $(srcdir); $(MAKEINFO) rcirc.texi
+rcirc.dvi: rcirc.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/rcirc.texi
+
+../info/erc: erc.texi
+ cd $(srcdir); $(MAKEINFO) erc.texi
+erc.dvi: erc.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/erc.texi
+
+mostlyclean:
+ rm -f *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.*
+
+clean: mostlyclean
+ rm -f *.dvi
+
+distclean: clean
+
+maintainer-clean: distclean
+ rm -f *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc
+ for file in $(INFO_TARGETS); do rm -f $${file}*; done
+
+
+# Formerly this directory had texindex.c and getopt.c in it
+# and this makefile built them to make texindex.
+# That caused trouble because this is run entirely in the source directory.
+# Since we expect to get texi2dvi from elsewhere,
+# it is ok to expect texindex from elsewhere also.
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@setfilename ../info/ada-mode
+@settitle Ada Mode
+
+@copying
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
+``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code.
+@end direntry
+
+@titlepage
+@sp 10
+@title{Ada Mode}
+@sp 2
+@subtitle An Emacs major mode for programming in Ada
+@subtitle Ada Mode Version 3.7
+@sp 2
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@c fixme; title page doesn't show up in ada-mode.info; why bother with
+@c it?
+
+@node Top, Overview, (dir), (dir)
+
+@menu
+* Overview::
+* Installation:: Installing Ada mode on your system
+* Customization:: Setting up Ada mode to your taste
+* Compiling Executing:: Working with your application within Emacs
+* Project files:: Describing the organization of your project
+* Compiling Examples:: A small tutorial
+* Moving Through Ada Code:: Moving easily through Ada sources
+* Identifier completion:: Finishing words automatically
+* Automatic Smart Indentation:: Indenting your code automatically as you type
+* Formatting Parameter Lists:: Formatting subprograms' parameter lists
+ automatically
+* Automatic Casing:: Adjusting the case of words automatically
+* Statement Templates:: Inserting code templates
+* Comment Handling:: Reformatting comments easily
+* GNU Free Documentation License:: The license for this documentation.
+* Index::
+@end menu
+
+
+@node Overview, Installation, Top, Top
+@chapter Overview
+
+The Emacs mode for programming in Ada helps the user in understanding
+existing code and facilitates writing new code.
+
+When the Gnu Ada compiler GNAT is used, the cross-reference
+information output by the compiler is used to provide powerful code
+navigation (jump to definition, find all uses, etc).
+
+When you open a file with a file extension of @file{.ads} or
+@file{.adb}, Emacs will automatically load and activate Ada mode.
+
+Ada mode works without any customization, if you are using the GNAT
+compiler (@url{https://libre2.adacore.com/}) and the GNAT default
+naming convention.
+
+You must customize a few things if you are using a different compiler
+or file naming convention; @xref{Other compiler}, @xref{Non-standard
+file names}.
+
+In addition, you may want to customize the indentation,
+capitalization, and other things; @xref{Other customization}.
+
+Finally, for large Ada projects, you will want to set up an Emacs
+Ada mode project file for each project; @xref{Project files}. Note
+that these are different from the GNAT project files used by gnatmake
+and other GNAT commands.
+
+See the Emacs info manual, section 'Running Debuggers Under Emacs',
+for general information on debugging.
+
+@node Installation, Customization, Overview, Top
+@chapter Installation
+
+Ada mode is part of the standard Emacs distribution; if you use that,
+no files need to be installed.
+
+Ada mode is also available as a separate distribution, from the Emacs
+Ada mode website
+@uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}. The
+separate distribution may be more recent.
+
+For installing the separate distribution, see the @file{README} file
+in the distribution.
+
+To see what version of Ada mode you have installed, do @key{M-x
+ada-mode-version}.
+
+The following files are provided with the Ada mode distribution:
+
+@itemize @bullet
+
+@item
+@file{ada-mode.el}: The main file for Ada mode, providing indentation,
+formatting of parameter lists, moving through code, comment handling
+and automatic casing.
+
+@item
+@file{ada-prj.el}: GUI editing of Ada mode project files, using Emacs
+widgets.
+
+@item
+@file{ada-stmt.el}: Ada statement templates.
+
+@item
+@file{ada-xref.el}: GNAT cross-references, completion of identifiers,
+and compilation. Also provides project files (which are not
+GNAT-specific).
+
+@end itemize
+
+@node Customization, Compiling Executing, Installation, Top
+@chapter Customizing Ada mode
+
+Here we assume you are familiar with setting variables in Emacs,
+either thru 'customize' or in elisp (in your @file{.emacs} file). For
+a basic introduction to customize, elisp, and Emacs in general, see
+the tutorial in
+@iftex
+@cite{The GNU Emacs Manual}.
+@end iftex
+@ifhtml
+@cite{The GNU Emacs Manual}.
+@end ifhtml
+@ifinfo
+@ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}.
+@end ifinfo
+
+These global Emacs settings are strongly recommended (put them in your
+.emacs):
+
+@example
+(global-font-lock-mode t)
+(transient-mark-mode t)
+@end example
+
+@samp{(global-font-lock-mode t)} turns on syntax
+highlighting for all buffers (it is off by default because it may be
+too slow for some machines).
+
+@samp{(transient-mark-mode t)} highlights selected text.
+
+See the Emacs help for each of these variables for more information.
+
+@menu
+* Non-standard file names::
+* Other compiler::
+* Other customization::
+@end menu
+
+@node Non-standard file names, Other compiler, Customization, Customization
+@section Non-standard file names
+
+By default, Ada mode is configured to use the GNAT file naming
+convention, where file names are a simple modification of the Ada
+names, and the extension for specs and bodies are
+@samp{.ads} and @samp{.adb}, respectively.
+
+Ada mode uses the file extentions to allow moving from a package body
+to the corresponding spec and back.
+
+Ada mode supports a list of alternative file extensions for specs and bodies.
+
+For instance, if your spec and bodies files are called
+@file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you
+can add the following to your @file{.emacs} file:
+
+@example
+(ada-add-extensions "_s.ada" "_b.ada")
+@end example
+
+You can define additional extensions:
+
+@example
+(ada-add-extensions ".ads" "_b.ada")
+(ada-add-extensions ".ads" ".body")
+@end example
+
+This means that whenever Ada mode looks for the body for a file
+whose extension is @file{.ads}, it will take the first available file
+that ends with either @file{.adb}, @file{_b.ada} or
+@file{.body}.
+
+Simililarly, if Ada mode is looking for a spec, it will look for
+@file{.ads} or @file{_s.ada}.
+
+If the filename is not derived from the Ada name following the GNAT
+convention, things are a little more complicated. You then need to
+rewrite the function @code{ada-make-filename-from-adaname}. Doing that
+is beyond the scope of this manual; see the current definitions in
+@file{ada-mode.el} and @file{ada-xref.el} for examples.
+
+@node Other compiler, Other customization, Non-standard file names, Customization
+@section Other compiler
+
+By default, Ada mode is configured to use the Gnu Ada compiler GNAT.
+
+To use a different Ada compiler, you must specify the command lines
+used to run that compiler, either in lisp variables or in Emacs
+Ada mode project files. See @ref{Project file variables} for the list
+of project variables, and the corresponding lisp variables.
+
+@node Other customization, , Other compiler, Customization
+@section Other customization
+
+All user-settable Ada mode variables can be set via the menu
+@samp{Ada | Customize}. Click on the @samp{Help} button there for help
+on using customize.
+
+To modify a specific variable, you can directly call the function
+@code{customize-variable}; just type @kbd{M-x customize-variable
+@key{RET} @var{variable-name} @key{RET}}).
+
+Alternately, you can specify variable settings in the Emacs
+configuration file, @file{.emacs}. This file is coded in Emacs lisp,
+and the syntax to set a variable is the following:
+@example
+(setq variable-name value)
+@end example
+
+@node Compiling Executing, Project files, Customization, Top
+@chapter Compiling Executing
+
+Ada projects can be compiled, linked, and executed using commands on
+the Ada menu. All of these commands can be customized via a project
+file (@pxref{Project files}), but the defaults are sufficient for using
+the GNAT compiler for simple projects (single files, or several files
+in a single directory).
+
+Even when no project file is used, the GUI project editor (menu
+@key{Ada | Project | Edit}) shows the settings of the various project
+file variables referenced here.
+
+@menu
+* Compile commands::
+* Compiler errors::
+@end menu
+
+@node Compile commands, Compiler errors, Compiling Executing, Compiling Executing
+@section Compile commands
+
+Here are the commands for building and using an Ada project, as
+listed in the Ada menu.
+
+In multi-file projects, there must be one file that is the main
+program. That is given by the @code{main_unit} project file variable;
+it defaults to the current file if not yet set, but is also set by the
+``set main and build'' command.
+
+@table @code
+
+@item Check file
+Compiles the current file in syntax check mode, by running
+@code{check_cmd} defined in the current project file. This typically
+runs faster than full compile mode, speeding up finding and fixing
+compilation errors.
+
+This sets @code{main_unit} only if it has not been set yet.
+
+@item Compile file
+Compiles the current file, by running @code{comp_cmd} from the current
+project file.
+
+This does not set @code{main_unit}.
+
+@item Set main and Build
+Sets @code{main_unit} to the current file, then executes the Build
+command.
+
+@item Show main
+Display @code{main_unit} in the message buffer.
+
+@item Build
+Compiles all obsolete units of the current @code{main_unit}, and links
+@code{main_unit}, by running @code{make_cmd} from the current project.
+
+This sets @code{main_unit} only if it has not been set yet.
+
+@item Run
+Executes the main program in a shell, displayed in a separate Emacs
+buffer. This runs @code{run_cmd} from the current project. The
+execution buffer allows for interactive input/output.
+
+To modify the run command, in particular to provide or change the
+command line arguments, type @key{C-u} before invoking the command.
+
+This command is not available for a cross-compilation toolchain.
+
+@end table
+It is important when using these commands to understand how
+@code{main_unit} is used and changed.
+
+Build runs 'gnatmake' on the main unit. During a typical edit/compile
+session, this is the only command you need to invoke, which is why it
+is bound to @key{C-c C-c}. It will compile all files needed by the
+main unit, and display compilation errors in any of them.
+
+Note that Build can be invoked from any Ada buffer; typically you will
+be fixing errors in files other than the main, but you don't have to
+switch back to the main to invoke the compiler again.
+
+Novices and students typically work on single-file Ada projects. In
+this case, @key{C-c C-m} will normally be the only command needed; it
+will build the current file, rather than the last-built main.
+
+There are three ways to change @code{main_unit}:
+
+@enumerate
+@item
+Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
+the current file.
+
+@item
+Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
+@code{main}, and click @key{[save]}
+
+@item
+Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit}
+
+@end enumerate
+
+@node Compiler errors, , Compile commands, Compiling Executing
+@section Compiler errors
+
+The @code{Check file}, @code{Compile file}, and @code{Build} commands
+all place compilation errors in a separate buffer named
+@code{*compilation*}.
+
+Each line in this buffer will become active: you can simply click on
+it with the middle button of the mouse, or move point to it and press
+@key{RET}. Emacs will then display the relevant source file and put
+point on the line and column where the error was found.
+
+You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs
+will jump to the first error. If you press that key again, it will
+move you to the second error, and so on.
+
+Some error messages might also include references to other files. These
+references are also clickable in the same way, or put point after the
+line number and press @key{RET}.
+
+@node Project files, Compiling Examples, Compiling Executing, Top
+@chapter Project files
+
+An Emacs Ada mode project file specifies what directories hold sources
+for your project, and allows you to customize the compilation commands
+and other things on a per-project basis.
+
+Note that Ada mode project files @samp{*.adp} are different than GNAT
+compiler project files @samp{*.gpr}.
+
+@menu
+* Project File Overview::
+* GUI Editor::
+* Project file variables::
+@end menu
+
+@node Project File Overview, GUI Editor, Project files, Project files
+@section Project File Overview
+
+Project files have a simple syntax; they may be edited directly. Each
+line specifies a project variable name and its value, separated by ``='':
+@example
+src_dir=/Projects/my_project/src_1
+src_dir=/Projects/my_project/src_2
+@end example
+
+Some variables (like @code{src_dir}) are lists; multiple occurances
+are concatenated.
+
+There must be no space between the variable name and ``='', and no
+trailing spaces.
+
+Alternately, a GUI editor for project files is available (@pxref{GUI
+Editor}). It uses Emacs widgets, similar to Emacs customize.
+
+The GUI editor also provides a convenient way to view current project
+settings, if they have been modified using menu commands rather than
+by editing the project file.
+
+After the first Ada mode build command is invoked, there is always a
+current project file, given by the lisp variable
+@code{ada-prj-default-project-file}. Currently, the only way to show
+the current project file is to invoke the GUI editor.
+
+To find the project file the first time, Ada mode uses the following
+search algorithm:
+
+@itemize @bullet
+@item
+If @code{ada-prj-default-project-file} is set, use that.
+
+@item
+Otherwise, search for a file in the current directory with
+the same base name as the Ada file, but extension given by
+@code{ada-prj-file-extension} (default @code{".adp"}).
+
+@item
+If not found, search for @file{*.adp} in the current directory; if
+several are found, prompt the user to select one.
+
+@item
+If none are found, use @file{default.adp} in the current directory (even
+if it does not exist).
+
+@end itemize
+
+This algorithm always sets @code{ada-prj-default-project-file}, even
+when the file does not actually exist.
+
+To change the project file before or after the first one is found,
+invoke @key{Ada | Project | Load ...}.
+
+Or, in lisp, evaluate @code{ada-set-default-project-file "/path/file.adp"}.
+This sets @code{ada-prj-default-project-file}, and reads the project file.
+
+@node GUI Editor, Project file variables, Project File Overview, Project files
+@section GUI Editor
+
+The project file editor is invoked with the menu @samp{Ada | Projects
+| Edit}.
+
+Once in the buffer for editing the project file, you can save your
+modification using the @samp{[save]} button at the bottom of the
+buffer, or the @kbd{C-x C-s} binding. To cancel your modifications,
+kill the buffer or click on the @samp{[cancel]} button.
+
+@node Project file variables, , GUI Editor, Project files
+@section Project file variables
+
+The following variables can be defined in a project file; some can
+also be defined in lisp variables.
+
+To set a project variable that is a list, specify each element of the
+list on a separate line in the project file.
+
+Any project variable can be referenced in other project variables,
+using a shell-like notation. For instance, if the variable
+@code{comp_cmd} contains @code{$@{comp_opt@}}, the value of the
+@code{comp_opt} variable will be substituted when @code{comp_cmd} is
+used.
+
+Most project variables have defaults that can be changed by setting
+lisp variables; the table below identifies the lisp variable for each
+project variable. Lisp variables corresponding to project variables
+that are lists are lisp lists.
+
+Here is the list of variables. In the default values, the current
+directory @code{"."} is the project file directory.
+
+@c defined in ada-xref-set-default-prj-values; same order here
+@table @asis
+@item @code{build_dir} [default: @code{"."}]
+The compile commands will be issued in this directory.
+
+@item @code{src_dir} [default: @code{"."}]
+A list of directories to search for source files, both for compile
+commands and source navigation.
+
+@item @code{obj_dir} [default: @code{"."}]
+A list of directories to search for library files. Ada mode searches
+this list for the @samp{.ali} files generated by GNAT that contain
+cross-reference information.
+
+The compiler commands must place the @samp{.ali} files in one of these
+directories; the default commands do that.
+
+@item @code{casing} [default: @code{("~/.emacs_case_exceptions")}
+List of files containing casing exceptions. See the help on
+@code{ada-case-exception-file} for more info.
+@c FIXME: section on case exceptions
+
+Lisp variable: @code{ada-case-exception-file}.
+
+@item @code{comp_opt} [default: @code{"-gnatq -gnatQ"}]
+Holds user compiler options; used in the default compile commands. The
+default value tells gnatmake to generate library files for
+cross-referencing even when there are errors.
+
+If source code for the project is in multiple directories, the
+appropriate compiler options must be added here. @ref{Set source
+search path} for examples of this. Alternately, GNAT project files may
+be used; @ref{Use GNAT project file}.
+
+Lisp variable: @code{ada-prj-default-comp-opt}.
+
+@item @code{bind_opt} [default: @code{""}]
+Holds user binder options; used in the default build commands.
+
+Lisp variable: @code{ada-prj-default-bind-opt}.
+
+@item @code{link_opt} [default: @code{""}]
+Holds user linker options; used in the default build commands.
+
+Lisp variable: @code{ada-prj-default-link-opt}.
+
+@item @code{gnatmake_opt} [default: @code{"-g"}]
+Holds user gnatmake options; used in the default build commands.
+
+If a GNAT project file is used (for example @file{project.gpr}), this
+option should be set to @code{-Pproject.gpr}.
+
+Lisp variable: @code{ada-prj-default-gnatmake-opt}.
+
+@item @code{gnatfind_opt} [default: @code{"-rf"}]
+Holds user gnatfind options; used in the default find commands.
+
+Lisp variable: @code{ada-prj-gnatfind-switches}.
+
+@item @code{main} [default: current file]
+Specifies the name of the executable file for the project; used in the
+default build commands.
+
+@item @code{main_unit} [default: current Ada unit]
+Specifies the name of the main Ada unit for the project; used in the
+default build commands.
+
+@item @code{cross_prefix} [default: @code{""}]
+Name of target machine in a cross-compilation environment. Used in
+default compile and build commands.
+
+@item @code{remote_machine} [default: @code{""}]
+Name of the machine to log into before issuing the compile and build
+commands. If this variable is empty, the command will be run on the
+local machine.
+
+@item @code{comp_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}]
+Command used to compile a single file.
+The name of the file is substituted for @code{full_current}.
+
+Lisp variable: @code{ada-prj-default-comp-cmd}.
+
+@item @code{check_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c -gnatc $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}]
+Command used to syntax check a single file.
+The name of the file is substituted for @code{full_current}.
+
+Lisp variable: @code{ada-prj-default-check-cmd}
+
+@item @code{make_cmd} [default: @code{"$@{cross_prefix@}gnatmake -o $@{main@} $@{main_unit@} $@{gnatmake_opt@} -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"}]
+Command used to build the application.
+
+Lisp variable: @code{ada-prj-default-make-cmd}.
+
+@item @code{run_cmd} [default: @code{"./$@{main@}"}]
+Command used to run the application.
+
+@item @code{debug_pre_cmd} [default: @code{"cd $@{build_dir@}"}]
+Command executed before @code{debug_cmd}.
+
+@item @code{debug_cmd} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}]
+Command used to debug the application
+
+Lisp variable: @code{ada-prj-default-debugger}.
+
+@item @code{debug_post_cmd} [default: @code{""}]
+Command executed after @code{debug_cmd}.
+
+@end table
+
+@node Compiling Examples, Moving Through Ada Code, Project files, Top
+@chapter Compiling Examples
+
+We present several small projects, and walk thru the process of
+compiling, linking, and running them.
+
+The first example illustrates more Ada mode features than the others;
+you should work thru that example before doing the others.
+
+All of these examples assume you are using GNAT.
+
+The source for these examples is available on the Emacs Ada mode
+website mentioned in @xref{Installation}.
+
+@menu
+* No project files:: Just menus
+* Set compiler options:: A basic Ada mode project file
+* Set source search path:: Source in multiple directories
+* Use GNAT project file::
+@end menu
+
+@node No project files, Set compiler options, Compiling Examples, Compiling Examples
+@section No project files
+This example uses no project files.
+
+First, create a directory @file{Example_1}, containing:
+
+@file{hello.adb}:
+
+@example
+with Ada.Text_IO;
+procedure Hello
+is begin
+ Put_Line("Hello from hello.adb");
+end Hello;
+@end example
+
+Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate
+compiler error handling.
+
+@file{hello_2.adb}:
+
+@example
+with Hello_Pkg;
+procedure Hello_2
+is begin
+ Hello_Pkg.Say_Hello;
+end Hello_2;
+@end example
+
+@file{hello_pkg.ads}:
+
+@example
+package Hello_Pkg is
+ procedure Say_Hello;
+end Hello_Pkg;
+@end example
+
+@file{hello_pkg.adb}:
+
+@example
+with Ada.Text_IO;
+package Hello_Pkg is
+ procedure Say_Hello
+ is begin
+ Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
+ end Say_Hello;
+end Hello_Pkg;
+@end example
+
+Yes, this is missing the keyword @code{body}; another compiler error
+example.
+
+In buffer @file{hello.adb}, invoke @key{Ada | Check file}. You should
+get a @code{*compilation*} buffer containing something like (the
+directory paths will be different):
+
+@example
+cd c:/Examples/Example_1/
+gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ
+gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb
+hello.adb:4:04: "Put_Line" is not visible
+hello.adb:4:04: non-visible declaration at a-textio.ads:264
+hello.adb:4:04: non-visible declaration at a-textio.ads:260
+gnatmake: "c:/Examples/Example_1/hello.adb" compilation error
+@end example
+
+If you have enabled font-lock, the lines with actual errors (starting
+with @file{hello.adb}) are highlighted, with the file name in red.
+
+Now type @key{C-x `} (on a PC keyboard, @key{`} is next to @key{1}).
+Or you can click the middle mouse button on the first error line. The
+compilation buffer scrolls to put the first error on the top line, and
+point is put at the place of the error in the @file{hello.adb} buffer.
+
+To fix the error, change the line to be
+
+@example
+ Ada.Text_IO.Put_Line ("hello from hello.adb"):
+@end example
+
+Now invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello}.
+
+Now (in buffer @file{hello.adb}), invoke @key{Ada | Build}. You are
+prompted to save the file (if you haven't already). Then the
+compilation buffer is displayed again, containing:
+
+@example
+cd c:/Examples/Example_1/
+gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largs
+gcc -c -g -gnatq -gnatQ hello.adb
+gnatbind -x hello.ali
+gnatlink hello.ali -o hello.exe -g
+@end example
+
+The compilation has succeeded without errors; @file{hello.exe} now
+exists in the same directory as @file{hello.adb}.
+
+Now invoke @key{Ada | Run}. A @file{*run*} buffer is displayed,
+containing
+
+@example
+Hello from hello.adb
+
+Process run finished
+@end example
+
+That completes the first part of this example.
+
+Now we will compile a multi-file project. Open the file
+@file{hello_2.adb}, and invoke @key{Ada | Set main and Build}. This
+finds an error in @file{hello_pkg.adb}:
+
+@example
+cd c:/Examples/Example_1/
+gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largs
+gcc -c -g -gnatq -gnatQ hello_pkg.adb
+hello_pkg.adb:2:08: keyword "body" expected here [see file name]
+gnatmake: "hello_pkg.adb" compilation error
+@end example
+
+This demonstrates that gnatmake finds the files needed by the main
+program. However, it cannot find files in a different directory,
+unless you use an Emacs Ada mode project file to specify the other directories;
+@xref{Set source search path}, or a GNAT project file; @ref{Use GNAT
+project file}.
+
+Invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello_2}.
+
+Move to the error with @key{C-x `}, and fix the error by adding @code{body}:
+
+@example
+package body Hello_Pkg is
+@end example
+
+Now, while still in @file{hello_pkg.adb}, invoke @key{Ada | Build}.
+gnatmake successfully builds @file{hello_2}. This demonstrates that
+Emacs has remembered the main file, in the project variable
+@code{main_unit}, and used it for the Build command.
+
+Finally, again while in @file{hello_pkg.adb}, invoke @key{Ada | Run}.
+The @code{*run*} buffer displays @code{Hello from hello_pkg.adb}.
+
+One final point. If you switch back to buffer @file{hello.adb}, and
+invoke @key{Ada | Run}, @file{hello_2.exe} will be run. That is
+because @code{main_unit} is still set to @code{hello_2}, as you can
+see when you invoke @key{Ada | Project | Edit}.
+
+There are three ways to change @code{main_unit}:
+
+@enumerate
+@item
+Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
+the current file.
+
+@item
+Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
+@code{main}, and click @key{[save]}
+
+@item
+Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit}
+
+@end enumerate
+
+@node Set compiler options, Set source search path, No project files, Compiling Examples
+@section Set compiler options
+
+This example illustrates using an Emacs Ada mode project file to set a
+compiler option.
+
+If you have files from @file{Example_1} open in Emacs, you should
+close them so you don't get confused. Use menu @key{File | Close
+(current buffer)}.
+
+In directory @file{Example_2}, create these files:
+
+@file{hello.adb}:
+
+@example
+with Ada.Text_IO;
+procedure Hello
+is begin
+ Put_Line("Hello from hello.adb");
+end Hello;
+@end example
+
+This is the same as @file{hello.adb} from @file{Example_1}. It has two
+errors; missing ``use Ada.Text_IO;'', and no space between
+@code{Put_Line} and its argument list.
+
+@file{hello.adp}:
+
+@example
+comp_opt=-gnatyt
+@end example
+
+This tells the GNAT compiler to check for token spacing; in
+particular, there must be a space preceding a parenthesis.
+
+In buffer @file{hello.adb}, invoke @key{Ada | Project | Load...}, and
+select @file{Example_2/hello.adp}.
+
+Then, again in buffer @file{hello.adb}, invoke @key{Ada | Set main and
+Build}. You should get a @code{*compilation*} buffer containing
+something like (the directory paths will be different):
+
+@example
+cd c:/Examples/Example_2/
+gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs
+gcc -c -g -gnatyt hello.adb
+hello.adb:4:04: "Put_Line" is not visible
+hello.adb:4:04: non-visible declaration at a-textio.ads:264
+hello.adb:4:04: non-visible declaration at a-textio.ads:260
+hello.adb:4:12: (style) space required
+gnatmake: "hello.adb" compilation error
+@end example
+
+Compare this to the compiler output in @ref{No project files}; the
+gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by
+@code{-cargs -gnaty}, and an additional error is reported in
+@file{hello.adb} on line 4. This shows that @file{hello.adp} is being
+used to set the compiler options.
+
+Fixing the error, linking and running the code proceed as in @ref{No
+project files}.
+
+@node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples
+@section Set source search path
+
+In this example, we show how to deal with files in more than one
+directory. We start with the same code as in @ref{No project files}; create those
+files (with the errors present)
+
+Create the directory @file{Example_3}, containing:
+
+@file{hello_pkg.ads}:
+
+@example
+package Hello_Pkg is
+ procedure Say_Hello;
+end Hello_Pkg;
+@end example
+
+@file{hello_pkg.adb}:
+
+@example
+with Ada.Text_IO;
+package Hello_Pkg is
+ procedure Say_Hello
+ is begin
+ Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
+ end Say_Hello;
+end Hello_Pkg;
+@end example
+
+These are the same files from example 1; @file{hello_pkg.adb} has an
+error on line 2.
+
+In addition, create a directory @file{Example_3/Other}, containing these files:
+
+@file{Other/hello_3.adb}:
+
+@example
+with Hello_Pkg;
+with Ada.Text_IO; use Ada.Text_IO;
+procedure Hello_3
+is begin
+ Hello_Pkg.Say_Hello;
+ Put_Line ("From hello_3");
+end Hello_3;
+@end example
+
+There are no errors in this file.
+
+@file{Other/other.adp}:
+
+@example
+src_dir=..
+comp_opt=-I..
+@end example
+
+Note that there must be no trailing spaces.
+
+In buffer @file{hello_3.adb}, invoke @key{Ada | Project | Load...}, and
+select @file{Example_3/Other/other.adp}.
+
+Then, again in @file{hello_3.adb}, invoke @key{Ada | Set main and
+Build}. You should get a @code{*compilation*} buffer containing
+something like (the directory paths will be different):
+
+@example
+cd c:/Examples/Example_3/Other/
+gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs
+gcc -c -g -I.. hello_3.adb
+gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb
+hello_pkg.adb:2:08: keyword "body" expected here [see file name]
+gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error
+@end example
+
+Compare the @code{-cargs} option to the compiler output in @ref{Set
+compiler options}; this shows that @file{other.adp} is being used to
+set the compiler options.
+
+Move to the error with @key{C-x `}. Ada mode searches the list of
+directories given by @code{src_dir} for the file mentioned in the
+compiler error message.
+
+Fixing the error, linking and running the code proceed as in @ref{No
+project files}.
+
+@node Use GNAT project file, , Set source search path, Compiling Examples
+@section Use GNAT project file
+
+In this example, we show how to use a GNAT project file.
+
+Create the directory @file{Example_4}, containing:
+
+@file{hello_pkg.ads}:
+
+@example
+package Hello_Pkg is
+ procedure Say_Hello;
+end Hello_Pkg;
+@end example
+
+@file{hello_pkg.adb}:
+
+@example
+with Ada.Text_IO;
+package Hello_Pkg is
+ procedure Say_Hello
+ is begin
+ Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
+ end Say_Hello;
+end Hello_Pkg;
+@end example
+
+These are the same files from example 1; @file{hello_pkg.adb} has an
+error on line 2.
+
+In addition, create a directory @file{Example_4/Gnat_Project},
+containing these files:
+
+@file{Other/hello_4.adb}:
+
+@example
+with Hello_Pkg;
+with Ada.Text_IO; use Ada.Text_IO;
+procedure Hello_4
+is begin
+ Hello_Pkg.Say_Hello;
+ Put_Line ("From hello_4");
+end Hello_4;
+@end example
+
+There are no errors in this file.
+
+@file{Gnat_Project/hello_4.adp}:
+
+@example
+src_dir=..
+gnatmake_opt=-Phello_4.gpr
+@end example
+
+@file{Gnat_Project/hello_4.gpr}:
+
+@example
+Project Hello_4 is
+ for Source_Dirs use (".", "..");
+end Hello_4;
+@end example
+
+In buffer @file{hello_4.adb}, invoke @key{Ada | Project | Load...}, and
+select @file{Example_4/Gnat_Project/hello_4.adp}.
+
+Then, again in @file{hello_4.adb}, invoke @key{Ada | Set main and
+Build}. You should get a @code{*compilation*} buffer containing
+something like (the directory paths will be different):
+
+@example
+cd c:/Examples/Example_4/Gnat_Project/
+gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs
+gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb
+gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb
+hello_pkg.adb:2:08: keyword "body" expected here [see file name]
+gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error
+@end example
+
+Compare the @code{gcc} options to the compiler output in @ref{Set
+compiler options}; this shows that @file{hello_4.gpr} is being used to
+set the compiler options.
+
+Fixing the error, linking and running the code proceed as in @ref{No
+project files}.
+
+@node Moving Through Ada Code, Identifier completion, Compiling Examples, Top
+@chapter Moving Through Ada Code
+@c -----------------------------------------------------------------------
+
+There are several easy to use commands to navigate through Ada code. All
+these functions are available through the Ada menu, and you can also
+use the following key bindings or the command names. Some of these
+menu entries are available only if the GNAT compiler is used, since
+the implementation relies on the GNAT cross-referencing information.
+
+@table @kbd
+@item M-C-e
+@findex ada-next-procedure
+Move to the next function/procedure/task, which ever comes next
+(@code{ada-next-procedure}).
+@item M-C-a
+@findex ada-previous-procedure
+Move to previous function/procedure/task
+(@code{ada-previous-procedure}).
+@item M-x ada-next-package
+@findex ada-next-package
+Move to next package.
+@item M-x ada-previous-package
+@findex ada-previous-package
+Move to previous package.
+@item C-c C-a
+@findex ada-move-to-start
+Move to matching start of @code{end} (@code{ada-move-to-start}). If
+point is at the end of a subprogram, this command jumps to the
+corresponding @code{begin} if the user option
+@code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps to
+the subprogram declaration.
+@item C-c C-e
+@findex ada-move-to-end
+Move point to end of current block (@code{ada-move-to-end}).
+@item C-c o
+Switch between corresponding spec and body file
+(@code{ff-find-other-file}). If point is in a subprogram, position
+point on the corresponding declaration or body in the other file.
+@item C-c c-d
+@findex ada-goto-declaration
+Move from any reference to its declaration, for from a declaration to
+its body (for procedures, tasks, private and incomplete types).
+@item C-c C-r
+@findex ada-find-references
+Runs the @file{gnatfind} command to search for all references to the
+identifier surrounding point (@code{ada-find-references}). Use
+@kbd{C-x `} (@code{next-error}) to visit each reference (as for
+compilation errors).
+@end table
+
+If the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacs
+will try to run GNAT for you whenever cross-reference information is
+needed, and is older than the current source file.
+
+@node Identifier completion, Automatic Smart Indentation, Moving Through Ada Code, Top
+@chapter Identifier completion
+
+Emacs and Ada mode provide two general ways for the completion of
+identifiers. This is an easy way to type faster: you just have to type
+the first few letters of an identifiers, and then loop through all the
+possible completions.
+
+The first method is general for Emacs. It works by parsing all open
+files for possible completions.
+
+For instance, if the words @samp{my_identifier}, @samp{my_subprogram}
+are the only words starting with @samp{my} in any of the opened files,
+then you will have this scenario:
+
+@example
+You type: my@key{M-/}
+Emacs inserts: @samp{my_identifier}
+If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with
+@samp{my_subprogram}.
+Pressing @key{M-/} once more will bring you back to @samp{my_identifier}.
+@end example
+
+This is a very fast way to do completion, and the casing of words will
+also be respected.
+
+The second method (@key{C-TAB}) is specific to Ada mode and the GNAT
+compiler. Emacs will search the cross-information for possible
+completions.
+
+The main advantage is that this completion is more accurate: only
+existing identifier will be suggested.
+
+On the other hand, this completion is a little bit slower and requires
+that you have compiled your file at least once since you created that
+identifier.
+
+@table @kbd
+@item C-@key{TAB}
+@findex ada-complete-identifier
+Complete current identifier using cross-reference information.
+@item M-/
+Complete identifier using buffer information (not Ada-specific).
+@end table
+
+@node Automatic Smart Indentation, Formatting Parameter Lists, Identifier completion, Top
+@chapter Automatic Smart Indentation
+
+Ada mode comes with a full set of rules for automatic indentation. You
+can also configure the indentation, via the following variables:
+
+@table @asis
+@item @code{ada-broken-indent} (default value: 2)
+Number of columns to indent the continuation of a broken line.
+
+@item @code{ada-indent} (default value: 3)
+Number of columns for default indentation.
+
+@item @code{ada-indent-record-rel-type} (default value: 3)
+Indentation for @code{record} relative to @code{type} or @code{use}.
+
+@item @code{ada-indent-return} (default value: 0)
+Indentation for @code{return} relative to @code{function} (if
+@code{ada-indent-return} is greater than 0), or the open parenthesis
+(if @code{ada-indent-return} is negative or 0). Note that in the second
+case, when there is no open parenthesis, the indentation is done
+relative to @code{function} with the value of @code{ada-broken-indent}.
+
+@item @code{ada-label-indent} (default value: -4)
+Number of columns to indent a label.
+
+@item @code{ada-stmt-end-indent} (default value: 0)
+Number of columns to indent a statement @code{end} keyword on a separate line.
+
+@item @code{ada-when-indent} (default value: 3)
+Indentation for @code{when} relative to @code{exception} or @code{case}.
+
+@item @code{ada-indent-is-separate} (default value: t)
+Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line.
+
+@item @code{ada-indent-to-open-paren} (default value: t)
+Non-@code{nil} means indent according to the innermost open parenthesis.
+
+@item @code{ada-indent-after-return} (default value: t)
+Non-@code{nil} means that the current line will also be re-indented
+before inserting a newline, when you press @key{RET}.
+@end table
+
+Most of the time, the indentation will be automatic, i.e when you
+press @key{RET}, the cursor will move to the correct column on the
+next line.
+
+You can also indent single lines, or the current region, with @key{TAB}.
+
+Another mode of indentation exists that helps you to set up your
+indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do
+the following:
+
+@itemize @bullet
+@item
+Reindent the current line, as @key{TAB} would do.
+@item
+Temporarily move the cursor to a reference line, i.e., the line that
+was used to calculate the current indentation.
+@item
+Display in the message window the name of the variable that provided
+the offset for the indentation.
+@end itemize
+
+The exact indentation of the current line is the same as the one for the
+reference line, plus an offset given by the variable.
+
+@table @kbd
+@item @key{TAB}
+Indent the current line or the current region.
+@item C-M-\
+Indent lines in the current region.
+@item C-c @key{TAB}
+Indent the current line and display the name of the variable used for
+indentation.
+@end table
+
+@node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top
+@chapter Formatting Parameter Lists
+
+@table @kbd
+@item C-c C-f
+@findex ada-format-paramlist
+Format the parameter list (@code{ada-format-paramlist}).
+@end table
+
+This aligns the declarations on the colon (@samp{:}) separating
+argument names and argument types, and aligns the @code{in},
+@code{out} and @code{in out} keywords.
+
+@node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top
+@chapter Automatic Casing
+
+Casing of identifiers, attributes and keywords is automatically
+performed while typing when the variable @code{ada-auto-case} is set.
+Every time you press a word separator, the previous word is
+automatically cased.
+
+You can customize the automatic casing differently for keywords,
+attributes and identifiers. The relevant variables are the following:
+@code{ada-case-keyword}, @code{ada-case-attribute} and
+@code{ada-case-identifier}.
+
+All these variables can have one of the following values:
+
+@table @code
+@item downcase-word
+The word will be lowercase. For instance @code{My_vARIable} is
+converted to @code{my_variable}.
+
+@item upcase-word
+The word will be uppercase. For instance @code{My_vARIable} is
+converted to @code{MY_VARIABLE}.
+
+@item ada-capitalize-word
+The first letter and each letter following an underscore (@samp{_})
+are uppercase, others are lowercase. For instance @code{My_vARIable}
+is converted to @code{My_Variable}.
+
+@item ada-loose-case-word
+Characters after an underscore @samp{_} character are uppercase,
+others are not modified. For instance @code{My_vARIable} is converted
+to @code{My_VARIable}.
+@end table
+
+Ada mode allows you to define exceptions to these rules, in a file
+specified by the variable variable @code{ada-case-exception-file}
+(default @file{~/.emacs_case_exceptions}). Each line in this file
+specifies the casing of one word or word fragment. Comments may be
+included, separated from the word by a space.
+
+If the word starts with an asterisk (@key{*}), it defines the casing
+af a word fragemnt (or ``substring''); part of a word between two
+underscores or word boundary.
+
+For example:
+
+@example
+DOD Department of Defense
+*IO
+GNAT The GNAT compiler from Ada Core Technologies
+@end example
+
+The word fragment @code{*IO} applies to any word containing ``_io'';
+@code{Text_IO}, @code{Hardware_IO}, etc.
+
+@findex ada-create-case-exception
+There are two ways to add new items to this file: you can simply edit
+it as you would edit any text file. Or you can position point on the
+word you want to add, and select menu @samp{Ada | Edit | Create Case
+Exception}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}).
+The word will automatically be added to the current list of exceptions
+and to the file.
+
+To define a word fragment case exception, select the word fragment,
+then select menu @samp{Ada | Edit | Create Case Exception Substring}.
+
+It is sometimes useful to have multiple exception files around (for
+instance, one could be the standard Ada acronyms, the second some
+company specific exceptions, and the last one some project specific
+exceptions). If you set up the variable @code{ada-case-exception-file}
+as a list of files, each of them will be parsed and used in your emacs
+session. However, when you save a new exception through the menu, as
+described above, the new exception will be added to the first file in
+the list.
+
+@table @kbd
+@item C-c C-b
+@findex ada-adjust-case-buffer
+Adjust case in the whole buffer (@code{ada-adjust-case-buffer}).
+@item C-c C-y
+Create a new entry in the exception dictionary, with the word under
+the cursor (@code{ada-create-case-exception})
+@item C-c C-t
+@findex ada-case-read-exceptions
+Rereads the exception dictionary from the file
+@code{ada-case-exception-file} (@code{ada-case-read-exceptions}).
+@end table
+
+@node Statement Templates, Comment Handling, Automatic Casing, Top
+@chapter Statement Templates
+
+Templates are defined for most Ada statements, using the Emacs
+``skeleton'' package. They can be inserted in the buffer using the
+following commands:
+
+@table @kbd
+@item C-c t b
+@findex ada-exception-block
+exception Block (@code{ada-exception-block}).
+@item C-c t c
+@findex ada-case
+case (@code{ada-case}).
+@item C-c t d
+@findex ada-declare-block
+declare Block (@code{ada-declare-block}).
+@item C-c t e
+@findex ada-else
+else (@code{ada-else}).
+@item C-c t f
+@findex ada-for-loop
+for Loop (@code{ada-for-loop}).
+@item C-c t h
+@findex ada-header
+Header (@code{ada-header}).
+@item C-c t i
+@findex ada-if
+if (@code{ada-if}).
+@item C-c t k
+@findex ada-package-body
+package Body (@code{ada-package-body}).
+@item C-c t l
+@findex ada-loop
+loop (@code{ada-loop}).
+@item C-c p
+@findex ada-subprogram-body
+subprogram body (@code{ada-subprogram-body}).
+@item C-c t t
+@findex ada-task-body
+task Body (@code{ada-task-body}).
+@item C-c t w
+@findex ada-while
+while Loop (@code{ada-while}).
+@item C-c t u
+@findex ada-use
+use (@code{ada-use}).
+@item C-c t x
+@findex ada-exit
+exit (@code{ada-exit}).
+@item C-c t C-a
+@findex ada-array
+array (@code{ada-array}).
+@item C-c t C-e
+@findex ada-elsif
+elsif (@code{ada-elsif}).
+@item C-c t C-f
+@findex ada-function-spec
+function Spec (@code{ada-function-spec}).
+@item C-c t C-k
+@findex ada-package-spec
+package Spec (@code{ada-package-spec}).
+@item C-c t C-p
+@findex ada-procedure-spec
+procedure Spec (@code{ada-package-spec}.
+@item C-c t C-r
+@findex ada-record
+record (@code{ada-record}).
+@item C-c t C-s
+@findex ada-subtype
+subtype (@code{ada-subtype}).
+@item C-c t C-t
+@findex ada-task-spec
+task Spec (@code{ada-task-spec}).
+@item C-c t C-u
+@findex ada-with
+with (@code{ada-with}).
+@item C-c t C-v
+@findex ada-private
+private (@code{ada-private}).
+@item C-c t C-w
+@findex ada-when
+when (@code{ada-when}).
+@item C-c t C-x
+@findex ada-exception
+exception (@code{ada-exception}).
+@item C-c t C-y
+@findex ada-type
+type (@code{ada-type}).
+@end table
+
+@node Comment Handling, GNU Free Documentation License, Statement Templates, Top
+@chapter Comment Handling
+
+By default, comment lines get indented like Ada code. There are a few
+additional functions to handle comments:
+
+@table @kbd
+@item M-;
+Start a comment in default column.
+@item M-j
+Continue comment on next line.
+@item C-c ;
+Comment the selected region (add -- at the beginning of lines).
+@item C-c :
+Uncomment the selected region
+@item M-q
+autofill the current comment.
+@end table
+
+@node GNU Free Documentation License, Index, Comment Handling, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index, , GNU Free Documentation License, Top
+@unnumbered Index
+
+@printindex fn
+
+@contents
+@bye
+
+@ignore
+ arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e
+@end ignore
--- /dev/null
+\input texinfo
+@c This is an annex of the Emacs manual.
+@c Copyright (C) 1994, 1995, 2001, 2002, 2003, 2004,
+@c 2005, 2006, 2007 Free Software Foundation, Inc.
+@c Author: Daniel.Pfeiffer@Informatik.START.dbp.de, fax (+49 69) 7588-2389
+@setfilename ../info/autotype
+@c @node Autotypist, Picture, Abbrevs, Top
+@c @chapter Features for Automatic Typing
+@settitle Features for Automatic Typing
+@c @cindex text
+@c @cindex selfinserting text
+@c @cindex autotypist
+
+@copying
+Copyright @copyright{} 1994, 1995, 1999, 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
+``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Autotype: (autotype). Convenient features for text that you enter frequently
+ in Emacs.
+@end direntry
+
+@titlepage
+@sp 10
+
+@center @titlefont{Autotyping}
+@sp 2
+@center @subtitlefont{Convenient features for text that you enter
+frequently in Emacs}
+@sp 2
+@center Daniel Pfeiffer
+@center additions by Dave Love
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@node Top
+@top Autotyping
+
+ Under certain circumstances you will find yourself typing similar things
+over and over again. This is especially true of form letters and programming
+language constructs. Project-specific header comments, flow-control
+constructs or magic numbers are essentially the same every time. Emacs has
+various features for doing tedious and repetitive typing chores for you
+in addition to the Abbrev features (@pxref{(emacs)Abbrevs}).
+
+ One solution is using skeletons, flexible rules that say what to
+insert, and how to do it. Various programming language modes offer some
+ready-to-use skeletons, and you can adapt them to suit your needs or
+taste, or define new ones.
+
+ Another feature is automatic insertion of what you want into empty files,
+depending on the file-name or the mode as appropriate. You can have a file or
+a skeleton inserted, or you can call a function. Then there is the
+possibility to have Un*x interpreter scripts automatically take on a magic
+number and be executable as soon as they are saved. Or you can have a
+copyright notice's year updated, if necessary, every time you save a
+file. Similarly for time stamps in the file.
+
+ URLs can be inserted based on a word at point. Flexible templates can
+be defined for inserting and navigating between text more generally. A
+sort of meta-expansion facility can be used to try a set of alternative
+completions and expansions of text at point.
+
+@menu
+* Using Skeletons:: How to insert a skeleton into your text.
+* Wrapping Skeletons:: Putting existing text within a skeleton.
+* Skeletons as Abbrevs:: An alternative for issuing skeleton commands.
+* Skeleton Language:: Making skeleton commands insert what you want.
+* Inserting Pairs:: Typing one character and getting another
+ after point.
+* Autoinserting:: Filling up empty files as soon as you visit them.
+* Copyrights:: Inserting and updating copyrights.
+* Executables:: Turning interpreter scripts into executables.
+* Timestamps:: Updating dates and times in modified files.
+* QuickURL:: Inserting URLs based on text at point.
+* Tempo:: Flexible template insertion.
+* Hippie Expand:: Expansion of text trying various methods.
+
+* GNU Free Documentation License:: The license for this documentation.
+* Concept Index::
+* Command Index::
+* Variable Index::
+@end menu
+
+
+
+@node Using Skeletons
+@chapter Using Skeletons
+@cindex skeletons
+@cindex using skeletons
+
+ When you want Emacs to insert a form letter or a typical construct of the
+programming language you are using, skeletons are a means of accomplishing
+this. Normally skeletons each have a command of their own, that, when called,
+will insert the skeleton. These commands can be issued in the usual ways
+(@pxref{(emacs)Commands}). Modes that offer various skeletons will often
+bind these to key-sequences on the @kbd{C-c} prefix, as well as having
+an @cite{Insert} menu and maybe even predefined abbrevs for them
+(@pxref{Skeletons as Abbrevs}).
+
+ The simplest kind of skeleton will simply insert some text indented
+according to the major mode and leave the cursor at a likely place in the
+middle. Interactive skeletons may prompt you for a string that will be part
+of the inserted text.
+
+ Skeletons may ask for input several times. They even have a looping
+mechanism in which you will be asked for input as long as you are willing to
+furnish it. An example would be multiple ``else if'' conditions. You can
+recognize this situation by a prompt ending in @key{RET}, @kbd{C-g}
+or @kbd{C-h}. This
+means that entering an empty string will simply assume that you are finished.
+Typing quit on the other hand terminates the loop but also the rest of the
+skeleton, e.g. an ``else'' clause is skipped. Only a syntactically necessary
+termination still gets inserted.
+
+
+
+@node Wrapping Skeletons
+@chapter Wrapping Skeletons Around Existing Text
+@cindex wrapping skeletons
+
+ Often you will find yourself with some code that for whatever reason
+suddenly becomes conditional. Or you have written a bit of text and want to
+put it in the middle of a form letter. Skeletons provide a means for
+accomplishing this, and can even, in the case of programming languages,
+reindent the wrapped code for you.
+
+ Skeleton commands take an optional numeric prefix argument
+(@pxref{(emacs)Arguments}). This is interpreted in two different ways depending
+on whether the prefix is positive, i.e. forwards oriented or negative,
+i.e. backwards oriented.
+
+ A positive prefix means to wrap the skeleton around that many
+following words. This is accomplished by putting the words there where
+the point is normally left after that skeleton is inserted (@pxref{Using
+Skeletons}). The point (@pxref{(emacs)Point}) is left at the next
+interesting spot in the skeleton instead.
+
+ A negative prefix means to do something similar with that many precedingly
+marked interregions (@pxref{(emacs)Mark}). In the simplest case, if you type
+@kbd{M--} just before issuing the skeleton command, that will wrap the
+skeleton around the current region, just like a positive argument would have
+wrapped it around a number of words.
+
+ Smaller negative arguments will wrap that many interregions into successive
+interesting spots within the skeleton, again leaving the point at the next one.
+We speak about interregions rather than regions here, because we treat them in
+the order they appear in the buffer, which coincides with successive regions
+only if they were marked in order.
+
+ That is, if you marked in alphabetical order the points A B C [] (where []
+represents the point) and call a skeleton command with @kbd{M-- 3}, you will
+wrap the text from A to B into the first interesting spot of the skeleton, the
+text from B to C into the next one, the text from C to the point into the
+third one, and leave the point in the fourth one. If there are less marks in
+the buffer, or if the skeleton defines less interesting points, the surplus is
+ignored.
+
+ If, on the other hand, you marked in alphabetical order the points [] A C B,
+and call a skeleton command with @kbd{M-- 3}, you will wrap the text from
+point to A, then the text from A to C and finally the text from C to B. This
+is done because the regions overlap and Emacs would be helplessly lost if it
+tried to follow the order in which you marked these points.
+
+
+
+@node Skeletons as Abbrevs
+@chapter Skeletons as Abbrev Expansions
+@cindex skeletons as abbrevs
+
+ Rather than use a key binding for every skeleton command, you can also
+define an abbreviation (@pxref{(emacs)Defining Abbrevs}) that will expand
+(@pxref{(emacs)Expanding Abbrevs}) into the skeleton.
+
+ Say you want @samp{ifst} to be an abbreviation for the C language if
+statement. You will tell Emacs that @samp{ifst} expands to the empty string
+and then calls the skeleton command. In Emacs Lisp you can say something like
+@code{(define-abbrev c-mode-abbrev-table "ifst" "" 'c-if)}. Or you can edit
+the output from @kbd{M-x list-abbrevs} to make it look like this:
+
+@example
+(c-mode-abbrev-table)
+"if" 0 "" c-if
+@end example
+
+@noindent
+(Some blank lines of no semantic significance, and other abbrev tables,
+have been omitted.)
+
+
+
+@node Skeleton Language
+@chapter Skeleton Language
+@cindex skeleton language
+
+@findex skeleton-insert
+ Skeletons are an shorthand extension to the Lisp language, where various
+atoms directly perform either actions on the current buffer or rudimentary
+flow control mechanisms. Skeletons are interpreted by the function
+@code{skeleton-insert}.
+
+ A skeleton is a list starting with an interactor, which is usually a
+prompt-string, or @code{nil} when not needed, but can also be a Lisp
+expression for complex read functions or for returning some calculated value.
+The rest of the list are any number of elements as described in the following
+table:
+
+@table @asis
+@item @code{"@var{string}"}, @code{?@var{c}}, @code{?\@var{c}}
+@vindex skeleton-transformation
+Insert string or character. Literal strings and characters are passed through
+@code{skeleton-transformation} when that is non-@code{nil}.
+@item @code{?\n}
+@c ??? something seems very wrong here.
+Insert a newline and align under current line. Use newline character
+@code{?\n} to prevent alignment.
+@item @code{_}
+Interesting point. When wrapping skeletons around successive regions, they are
+put at these places. Point is left at first @code{_} where nothing is wrapped.
+@item @code{>}
+Indent line according to major mode. When following element is @code{_}, and
+there is a interregion that will be wrapped here, indent that interregion.
+@item @code{&}
+Logical and. Iff preceding element moved point, i.e. usually inserted
+something, do following element.
+@item @code{|}
+Logical xor. Iff preceding element didn't move point, i.e. usually inserted
+nothing, do following element.
+@item @code{-@var{number}}
+Delete preceding number characters. Depends on value of
+@code{skeleton-untabify}.
+@item @code{()} or @code{nil}
+Ignored.
+@item @var{lisp-expression}
+Evaluated, and the return value is again interpreted as a skeleton element.
+@item @code{str}
+A special variable that, when evaluated the first time, usually prompts
+for input according to the skeleton's interactor. It is then set to the
+return value resulting from the interactor. Each subskeleton has its local
+copy of this variable.
+@item @code{v1}, @code{v2}
+Skeleton-local user variables.
+@item @code{'@var{expression}}
+Evaluate following Lisp expression for its side-effect, but prevent it from
+being interpreted as a skeleton element.
+@item @var{skeleton}
+Subskeletons are inserted recursively, not once, but as often as the user
+enters something at the subskeletons interactor. Thus there must be a
+@code{str} in the subskeleton. They can also be used non-interactively, when
+prompt is a lisp-expression that returns successive list-elements.
+@item @code{resume:}
+Ignored. Execution resumes here if the user quits during skeleton
+interpretation.
+@item @code{quit}
+A constant which is non-@code{nil} when the @code{resume:} section was entered
+because the user quit.
+@end table
+
+@findex skeleton-further-elements
+ Some modes also use other skeleton elements they themselves defined. For
+example in shell script mode's skeletons you will find @code{<} which does a
+rigid indentation backwards, or in CC mode's skeletons you find the
+self-inserting elements @code{@{} and @code{@}}. These are defined by the
+buffer-local variable @code{skeleton-further-elements} which is a list of
+variables bound while interpreting a skeleton.
+
+@findex define-skeleton
+ The macro @code{define-skeleton} defines a command for interpreting a
+skeleton. The first argument is the command name, the second is a
+documentation string, and the rest is an interactor and any number of skeleton
+elements together forming a skeleton. This skeleton is assigned to a variable
+of the same name as the command and can thus be overridden from your
+@file{~/.emacs} file (@pxref{(emacs)Init File}).
+
+
+
+@node Inserting Pairs
+@chapter Inserting Matching Pairs of Characters
+@cindex inserting pairs
+@cindex pairs
+
+ Various characters usually appear in pairs. When, for example, you insert
+an open parenthesis, no matter whether you are programming or writing prose,
+you will surely enter a closing one later. By entering both at the same time
+and leaving the cursor inbetween, Emacs can guarantee you that such
+parentheses are always balanced. And if you have a non-qwerty keyboard, where
+typing some of the stranger programming language symbols makes you bend your
+fingers backwards, this can be quite relieving too.
+
+@findex skeleton-pair-insert-maybe
+@vindex skeleton-pair
+ This is done by binding the first key (@pxref{(emacs)Rebinding}) of
+the pair to @code{skeleton-pair-insert-maybe} instead of
+@code{self-insert-command}. The ``maybe'' comes from the fact that
+this at-first surprising behavior is initially turned off. To enable
+it, you must set @code{skeleton-pair} to some non-@code{nil} value.
+And even then, a positive argument (@pxref{(emacs)Arguments}) will
+make this key behave like a self-inserting key
+(@pxref{(emacs)Inserting Text}).
+
+@vindex skeleton-pair-on-word
+ While this breaks with the stated intention of always balancing pairs, it
+turns out that one often doesn't want pairing to occur, when the following
+character is part of a word. If you want pairing to occur even then, set
+@code{skeleton-pair-on-word} to some non-@code{nil} value.
+
+@vindex skeleton-pair-alist
+ Pairing is possible for all visible characters. By default the
+parenthesis @samp{(}, the square bracket @samp{[}, the brace
+@samp{@{}, the pointed bracket @samp{<} and the backquote @samp{`} all
+pair with the symmetrical character. All other characters pair
+themselves. This behavior can be modified by the variable
+@code{skeleton-pair-alist}. This is in fact an alist of skeletons
+(@pxref{Skeleton Language}), with the first part of each sublist
+matching the typed character. This is the position of the interactor,
+but since pairs don't need the @code{str} element, this is ignored.
+
+ Some modes have bound the command @code{skeleton-pair-insert-maybe}
+to relevant keys. These modes also configure the pairs as
+appropriate. For example, when typing english prose, you'd expect the
+backquote (@samp{`}) to pair with the quote (@samp{'}), while in Shell
+script mode it must pair to itself. They can also inhibit pairing in
+certain contexts. For example an escaped character stands for itself.
+
+
+
+@node Autoinserting
+@chapter Autoinserting Text in Empty Files
+@cindex autoinserting
+
+@findex auto-insert
+ @kbd{M-x auto-insert} will put some predefined text at the beginning of
+the buffer. The main application for this function, as its name suggests,
+is to have it be called automatically every time an empty, and only an
+empty file is visited. This is accomplished by putting @code{(add-hook
+'find-file-hook 'auto-insert)} into your @file{~/.emacs} file
+(@pxref{(emacs)Init File}).
+
+@vindex auto-insert-alist
+ What gets inserted, if anything, is determined by the variable
+@code{auto-insert-alist}. The @sc{car}s of this list are each either
+a mode name, making an element applicable when a buffer is in that
+mode. Or they can be a string, which is a regexp matched against the
+buffer's file name. In that way different kinds of files that have
+the same mode in Emacs can be distinguished. The @sc{car}s may also
+be cons cells consisting of mode name or regexp as above and an
+additional descriptive string.
+
+ When a matching element is found, the @sc{cdr} says what to do. It may
+be a string, which is a file name, whose contents are to be inserted, if
+that file is found in the directory @code{auto-insert-directory} or under a
+absolute file name. Or it can be a skeleton (@pxref{Skeleton Language}) to
+be inserted.
+
+ It can also be a function, which allows doing various things. The function
+can simply insert some text, indeed, it can be skeleton command (@pxref{Using
+Skeletons}). It can be a lambda function which will for example conditionally
+call another function. Or it can even reset the mode for the buffer. If you
+want to perform several such actions in order, you use a vector, i.e. several
+of the above elements between square brackets (@samp{[@r{@dots{}}]}).
+
+ By default C and C++ headers insert a definition of a symbol derived from
+the filename to prevent multiple inclusions. C and C++ sources insert an
+include of the header. Makefiles insert the file makefile.inc if it exists.
+
+ TeX and bibTeX mode files insert the file tex-insert.tex if it exists, while
+LaTeX mode files insert a typical @code{\documentclass} frame. Html
+files insert a skeleton with the usual frame.
+
+ Ada mode files call the Ada header skeleton command. Emacs lisp
+source files insert the usual header, with a copyright of your
+environment variable @env{$ORGANIZATION} or else the FSF, and prompt
+for valid keywords describing the contents. Files in a @file{bin}
+directory for which Emacs could determine no specialized mode
+(@pxref{(emacs)Choosing Modes}) are set to Shell script mode.
+
+@findex define-auto-insert
+ In Lisp (@pxref{(emacs)Init File}) you can use the function
+@code{define-auto-insert} to add to or modify
+@code{auto-insert-alist}. See its documentation with @kbd{C-h f
+define-auto-insert}.
+
+@vindex auto-insert
+ The variable @code{auto-insert} says what to do when @code{auto-insert} is
+called non-interactively, e.g. when a newly found file is empty (see above):
+@table @asis
+@item @code{nil}
+Do nothing.
+@item @code{t}
+Insert something if possible, i.e. there is a matching entry in
+@code{auto-insert-alist}.
+@item other
+Insert something if possible, but mark as unmodified.
+@end table
+
+@vindex auto-insert-query
+ The variable @code{auto-insert-query} controls whether to ask about
+inserting something. When this is @code{nil}, inserting is only done with
+@kbd{M-x auto-insert}. When this is @code{function}, you are queried
+whenever @code{auto-insert} is called as a function, such as when Emacs
+visits an empty file and you have set the above-mentioned hook. Otherwise
+you are alway queried.
+
+@vindex auto-insert-prompt
+ When querying, the variable @code{auto-insert-prompt}'s value is used as a
+prompt for a y-or-n-type question. If this includes a @samp{%s} construct,
+that is replaced by what caused the insertion rule to be chosen. This is
+either a descriptive text, the mode-name of the buffer or the regular
+expression that matched the filename.
+
+
+
+@node Copyrights
+@chapter Inserting and Updating Copyrights
+@cindex copyrights
+
+@findex copyright
+ @kbd{M-x copyright} is a skeleton inserting command, that adds a copyright
+notice at the point. The ``by'' part is taken from your environment variable
+@env{$ORGANIZATION} or if that isn't set you are prompted for it. If the
+buffer has a comment syntax (@pxref{(emacs)Comments}), this is inserted as a comment.
+
+@findex copyright-update
+@vindex copyright-limit
+@vindex copyright-current-year
+ @kbd{M-x copyright-update} looks for a copyright notice in the first
+@code{copyright-limit} characters of the buffer and updates it when necessary.
+The current year (variable @code{copyright-current-year}) is added to the
+existing ones, in the same format as the preceding year, i.e. 1994, '94 or 94.
+If a dash-separated year list up to last year is found, that is extended to
+current year, else the year is added separated by a comma. Or it replaces
+them when this is called with a prefix argument. If a header referring to a
+wrong version of the GNU General Public License (@pxref{(emacs)Copying}) is found,
+that is updated too.
+
+ An interesting application for this function is to have it be called
+automatically every time a file is saved. This is accomplished by
+putting @code{(add-hook 'before-save-hook 'copyright-update)} into
+your @file{~/.emacs} file (@pxref{(emacs)Init File}). Alternative,
+you can do @kbd{M-x customize-variable @key{RET} before-save-hook
+@key{RET}}. @code{copyright-update} is conveniently listed as an
+option in the customization buffer.
+
+@vindex copyright-query
+ The variable @code{copyright-query} controls whether to update the
+copyright or whether to ask about it. When this is @code{nil} updating is
+only done with @kbd{M-x copyright-update}. When this is @code{function}
+you are queried whenever @code{copyright-update} is called as a function,
+such as in the @code{before-save-hook} feature mentioned above. Otherwise
+you are always queried.
+
+
+
+@node Executables
+@chapter Making Interpreter Scripts Executable
+@cindex executables
+
+@vindex executable-prefix
+@vindex executable-chmod
+ Various interpreter modes such as Shell script mode or AWK mode will
+automatically insert or update the buffer's magic number, a special
+comment on the first line that makes the @code{exec} systemcall know
+how to execute the script. To this end the script is automatically
+made executable upon saving, with @code{executable-chmod} as argument
+to the system @code{chmod} command. The magic number is prefixed by
+the value of @code{executable-prefix}.
+
+@vindex executable-magicless-file-regexp
+ Any file whose name matches @code{executable-magicless-file-regexp} is not
+furnished with a magic number, nor is it made executable. This is mainly
+intended for resource files, which are only meant to be read in.
+
+@vindex executable-insert
+ The variable @code{executable-insert} says what to do when
+@code{executable-set-magic} is called non-interactively, e.g. when file has no
+or the wrong magic number:
+@table @asis
+@item @code{nil}
+Do nothing.
+@item @code{t}
+Insert or update magic number.
+@item other
+Insert or update magic number, but mark as unmodified.
+@end table
+
+@findex executable-set-magic
+@vindex executable-query
+ The variable @code{executable-query} controls whether to ask about
+inserting or updating the magic number. When this is @code{nil} updating
+is only done with @kbd{M-x executable-set-magic}. When this is
+@code{function} you are queried whenever @code{executable-set-magic} is
+called as a function, such as when Emacs puts a buffer in Shell script
+mode. Otherwise you are alway queried.
+
+@findex executable-self-display
+ @kbd{M-x executable-self-display} adds a magic number to the buffer, which
+will turn it into a self displaying text file, when called as a Un*x command.
+The ``interpreter'' used is @code{executable-self-display} with argument
+@samp{+2}.
+
+@node Timestamps
+@chapter Maintaining Timestamps in Modified Files
+@cindex timestamps
+
+@findex time-stamp
+@vindex before-save-hook
+The @code{time-stamp} command can be used to update automatically a
+template in a file with a new time stamp every time you save the file.
+Customize the hook @code{before-save-hook} to add the function
+@code{time-stamp} to arrange this. It you use Custom to do this,
+then @code{time-stamp} is conveniently listed as an option in the
+customization buffer.
+
+@vindex time-stamp-active
+@vindex time-stamp-format
+@vindex time-stamp-start
+The time stamp is updated only if the customizable variable
+@code{time-stamp-active} is on, which it is by default; the command
+@code{time-stamp-toggle-active} can be used to toggle it. The format of
+the time stamp is set by the customizable variable
+@code{time-stamp-format}.
+
+@vindex time-stamp-line-limit
+@vindex time-stamp-end
+@vindex time-stamp-count
+@vindex time-stamp-inserts-lines
+The variables @code{time-stamp-line-limit}, @code{time-stamp-start},
+@code{time-stamp-end}, @code{time-stamp-count}, and
+@code{time-stamp-inserts-lines} control finding the template. Do not
+change these in your init file or you will be incompatible with other
+people's files. If you must change them, do so only in the local
+variables section of the file itself.
+
+Normally the template must appear in the first 8 lines of a file and
+look like one of the following:
+
+@example
+Time-stamp: <>
+Time-stamp: " "
+@end example
+
+The time stamp is written between the brackets or quotes:
+
+@example
+Time-stamp: <1998-02-18 10:20:51 gildea>
+@end example
+
+@node QuickURL
+@chapter QuickURL: Inserting URLs Based on Text at Point
+
+@vindex quickurl-url-file
+@findex quickurl
+@cindex URLs
+@kbd{M-x quickurl} can be used to insert a URL into a buffer based on
+the text at point. The URLs are stored in an external file defined by
+the variable @code{quickurl-url-file} as a list of either cons cells of
+the form @code{(@var{key} . @var{URL})} or
+lists of the form @code{(@var{key} @var{URL} @var{comment})}. These
+specify that @kbd{M-x quickurl} should insert @var{URL} if the word
+@var{key} is at point, for example:
+
+@example
+(("FSF" "http://www.fsf.org/" "The Free Software Foundation")
+ ("emacs" . "http://www.emacs.org/")
+ ("hagbard" "http://www.hagbard.demon.co.uk" "Hagbard's World"))
+@end example
+
+@findex quickurl-add-url
+@findex quickurl-list
+@kbd{M-x quickurl-add-url} can be used to add a new @var{key}/@var{URL}
+pair. @kbd{M-x quickurl-list} provides interactive editing of the URL
+list.
+
+@node Tempo
+@chapter Tempo: Flexible Template Insertion
+
+@cindex templates
+The Tempo package provides a simple way to define powerful templates, or
+macros, if you wish. It is mainly intended for, but not limited to,
+programmers to be used for creating shortcuts for editing
+certain kinds of documents.
+
+@findex tempo-backward-mark
+@findex tempo-forward-mark
+A template is defined as a list of items to be inserted in the current
+buffer at point. Some can be simple strings, while others can control
+formatting or define special points of interest in the inserted text.
+@kbd{M-x tempo-backward-mark} and @kbd{M-x tempo-forward-mark} can be
+used to jump between such points.
+
+More flexible templates can be created by including Lisp symbols, which
+will be evaluated as variables, or lists, which will be evaluated
+as Lisp expressions. Automatic completion of specified tags to expanded
+templates can be provided.
+
+@findex tempo-define-template
+See the documentation for @code{tempo-define-template} for the different
+items that can be used to define a tempo template with a command for
+inserting it.
+
+See the commentary in @file{tempo.el} for more information on using the
+Tempo package.
+
+@node Hippie Expand
+@chapter `Hippie' Expansion
+
+@findex hippie-expand
+@kindex M-/
+@vindex hippie-expand-try-functions-list
+@kbd{M-x hippie-expand} is a single command providing a variety of
+completions and expansions. Called repeatedly, it tries all possible
+completions in succession.
+
+Which ones to try, and in which order, is determined by the contents of
+the customizable option @code{hippie-expand-try-functions-list}. Much
+customization of the expansion behavior can be made by changing the
+order of, removing, or inserting new functions in this list. Given a
+positive numeric argument, @kbd{M-x hippie-expand} jumps directly that
+number of functions forward in this list. Given some other argument (a
+negative argument or just @kbd{C-u}) it undoes the tried completion.
+
+See the commentary in @file{hippie-exp.el} for more information on the
+possibilities.
+
+Typically you would bind @code{hippie-expand} to @kbd{M-/} with
+@code{dabbrev-expand}, the standard binding of @kbd{M-/}, providing one
+of the expansion possibilities.
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
+
+@node Command Index
+@unnumbered Command Index
+@printindex fn
+
+@node Variable Index
+@unnumbered Variable Index
+@printindex vr
+
+@setchapternewpage odd
+@contents
+@bye
+
+@ignore
+ arch-tag: 54001b27-5ef8-4a9d-a199-905d650fafba
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@comment %**start of header (This is for running Texinfo on a region.)
+@c smallbook
+@setfilename ../info/calc
+@c [title]
+@settitle GNU Emacs Calc 2.1 Manual
+@setchapternewpage odd
+@comment %**end of header (This is for running Texinfo on a region.)
+
+@c The following macros are used for conditional output for single lines.
+@c @texline foo
+@c `foo' will appear only in TeX output
+@c @infoline foo
+@c `foo' will appear only in non-TeX output
+
+@c @expr{expr} will typeset an expression;
+@c $x$ in TeX, @samp{x} otherwise.
+
+@iftex
+@macro texline
+@end macro
+@alias infoline=comment
+@alias expr=math
+@alias tfn=code
+@alias mathit=expr
+@macro cpi{}
+@math{@pi{}}
+@end macro
+@macro cpiover{den}
+@math{@pi/\den\}
+@end macro
+@end iftex
+
+@ifnottex
+@alias texline=comment
+@macro infoline{stuff}
+\stuff\
+@end macro
+@alias expr=samp
+@alias tfn=t
+@alias mathit=i
+@macro cpi{}
+@expr{pi}
+@end macro
+@macro cpiover{den}
+@expr{pi/\den\}
+@end macro
+@end ifnottex
+
+
+@tex
+% Suggested by Karl Berry <karl@@freefriends.org>
+\gdef\!{\mskip-\thinmuskip}
+@end tex
+
+@c Fix some other things specifically for this manual.
+@iftex
+@finalout
+@mathcode`@:=`@: @c Make Calc fractions come out right in math mode
+@tex
+\gdef\coloneq{\mathrel{\mathord:\mathord=}}
+
+\gdef\beforedisplay{\vskip-10pt}
+\gdef\afterdisplay{\vskip-5pt}
+\gdef\beforedisplayh{\vskip-25pt}
+\gdef\afterdisplayh{\vskip-10pt}
+@end tex
+@newdimen@kyvpos @kyvpos=0pt
+@newdimen@kyhpos @kyhpos=0pt
+@newcount@calcclubpenalty @calcclubpenalty=1000
+@ignore
+@newcount@calcpageno
+@newtoks@calcoldeverypar @calcoldeverypar=@everypar
+@everypar={@calceverypar@the@calcoldeverypar}
+@ifx@turnoffactive@undefinedzzz@def@turnoffactive{}@fi
+@ifx@ninett@undefinedzzz@font@ninett=cmtt9@fi
+@catcode`@\=0 \catcode`\@=11
+\r@ggedbottomtrue
+\catcode`\@=0 @catcode`@\=@active
+@end ignore
+@end iftex
+
+@copying
+This file documents Calc, the GNU Emacs calculator.
+
+Copyright @copyright{} 1990, 1991, 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being just ``GNU GENERAL PUBLIC LICENSE'', with the
+Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover
+Texts as in (a) below. A copy of the license is included in the section
+entitled ``GNU Free Documentation License.''
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Calc: (calc). Advanced desk calculator and mathematical tool.
+@end direntry
+
+@titlepage
+@sp 6
+@center @titlefont{Calc Manual}
+@sp 4
+@center GNU Emacs Calc Version 2.1
+@c [volume]
+@sp 5
+@center Dave Gillespie
+@center daveg@@synaptics.com
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1990, 1991, 2001, 2002, 2003, 2004,
+ 2005, 2006, 2007 Free Software Foundation, Inc.
+@insertcopying
+@end titlepage
+
+
+@summarycontents
+
+@c [end]
+
+@contents
+
+@c [begin]
+@ifnottex
+@node Top, Getting Started, (dir), (dir)
+@chapter The GNU Emacs Calculator
+
+@noindent
+@dfn{Calc} is an advanced desk calculator and mathematical tool
+written by Dave Gillespie that runs as part of the GNU Emacs environment.
+
+This manual, also written (mostly) by Dave Gillespie, is divided into
+three major parts: ``Getting Started,'' the ``Calc Tutorial,'' and the
+``Calc Reference.'' The Tutorial introduces all the major aspects of
+Calculator use in an easy, hands-on way. The remainder of the manual is
+a complete reference to the features of the Calculator.
+@end ifnottex
+
+@ifinfo
+For help in the Emacs Info system (which you are using to read this
+file), type @kbd{?}. (You can also type @kbd{h} to run through a
+longer Info tutorial.)
+@end ifinfo
+
+@menu
+* Getting Started:: General description and overview.
+@ifinfo
+* Interactive Tutorial::
+@end ifinfo
+* Tutorial:: A step-by-step introduction for beginners.
+
+* Introduction:: Introduction to the Calc reference manual.
+* Data Types:: Types of objects manipulated by Calc.
+* Stack and Trail:: Manipulating the stack and trail buffers.
+* Mode Settings:: Adjusting display format and other modes.
+* Arithmetic:: Basic arithmetic functions.
+* Scientific Functions:: Transcendentals and other scientific functions.
+* Matrix Functions:: Operations on vectors and matrices.
+* Algebra:: Manipulating expressions algebraically.
+* Units:: Operations on numbers with units.
+* Store and Recall:: Storing and recalling variables.
+* Graphics:: Commands for making graphs of data.
+* Kill and Yank:: Moving data into and out of Calc.
+* Keypad Mode:: Operating Calc from a keypad.
+* Embedded Mode:: Working with formulas embedded in a file.
+* Programming:: Calc as a programmable calculator.
+
+* Copying:: How you can copy and share Calc.
+* GNU Free Documentation License:: The license for this documentation.
+* Customizing Calc:: Customizing Calc.
+* Reporting Bugs:: How to report bugs and make suggestions.
+
+* Summary:: Summary of Calc commands and functions.
+
+* Key Index:: The standard Calc key sequences.
+* Command Index:: The interactive Calc commands.
+* Function Index:: Functions (in algebraic formulas).
+* Concept Index:: General concepts.
+* Variable Index:: Variables used by Calc (both user and internal).
+* Lisp Function Index:: Internal Lisp math functions.
+@end menu
+
+@ifinfo
+@node Getting Started, Interactive Tutorial, Top, Top
+@end ifinfo
+@ifnotinfo
+@node Getting Started, Tutorial, Top, Top
+@end ifnotinfo
+@chapter Getting Started
+@noindent
+This chapter provides a general overview of Calc, the GNU Emacs
+Calculator: What it is, how to start it and how to exit from it,
+and what are the various ways that it can be used.
+
+@menu
+* What is Calc::
+* About This Manual::
+* Notations Used in This Manual::
+* Demonstration of Calc::
+* Using Calc::
+* History and Acknowledgements::
+@end menu
+
+@node What is Calc, About This Manual, Getting Started, Getting Started
+@section What is Calc?
+
+@noindent
+@dfn{Calc} is an advanced calculator and mathematical tool that runs as
+part of the GNU Emacs environment. Very roughly based on the HP-28/48
+series of calculators, its many features include:
+
+@itemize @bullet
+@item
+Choice of algebraic or RPN (stack-based) entry of calculations.
+
+@item
+Arbitrary precision integers and floating-point numbers.
+
+@item
+Arithmetic on rational numbers, complex numbers (rectangular and polar),
+error forms with standard deviations, open and closed intervals, vectors
+and matrices, dates and times, infinities, sets, quantities with units,
+and algebraic formulas.
+
+@item
+Mathematical operations such as logarithms and trigonometric functions.
+
+@item
+Programmer's features (bitwise operations, non-decimal numbers).
+
+@item
+Financial functions such as future value and internal rate of return.
+
+@item
+Number theoretical features such as prime factorization and arithmetic
+modulo @var{m} for any @var{m}.
+
+@item
+Algebraic manipulation features, including symbolic calculus.
+
+@item
+Moving data to and from regular editing buffers.
+
+@item
+Embedded mode for manipulating Calc formulas and data directly
+inside any editing buffer.
+
+@item
+Graphics using GNUPLOT, a versatile (and free) plotting program.
+
+@item
+Easy programming using keyboard macros, algebraic formulas,
+algebraic rewrite rules, or extended Emacs Lisp.
+@end itemize
+
+Calc tries to include a little something for everyone; as a result it is
+large and might be intimidating to the first-time user. If you plan to
+use Calc only as a traditional desk calculator, all you really need to
+read is the ``Getting Started'' chapter of this manual and possibly the
+first few sections of the tutorial. As you become more comfortable with
+the program you can learn its additional features. Calc does not
+have the scope and depth of a fully-functional symbolic math package,
+but Calc has the advantages of convenience, portability, and freedom.
+
+@node About This Manual, Notations Used in This Manual, What is Calc, Getting Started
+@section About This Manual
+
+@noindent
+This document serves as a complete description of the GNU Emacs
+Calculator. It works both as an introduction for novices, and as
+a reference for experienced users. While it helps to have some
+experience with GNU Emacs in order to get the most out of Calc,
+this manual ought to be readable even if you don't know or use Emacs
+regularly.
+
+The manual is divided into three major parts:@: the ``Getting
+Started'' chapter you are reading now, the Calc tutorial (chapter 2),
+and the Calc reference manual (the remaining chapters and appendices).
+@c [when-split]
+@c This manual has been printed in two volumes, the @dfn{Tutorial} and the
+@c @dfn{Reference}. Both volumes include a copy of the ``Getting Started''
+@c chapter.
+
+If you are in a hurry to use Calc, there is a brief ``demonstration''
+below which illustrates the major features of Calc in just a couple of
+pages. If you don't have time to go through the full tutorial, this
+will show you everything you need to know to begin.
+@xref{Demonstration of Calc}.
+
+The tutorial chapter walks you through the various parts of Calc
+with lots of hands-on examples and explanations. If you are new
+to Calc and you have some time, try going through at least the
+beginning of the tutorial. The tutorial includes about 70 exercises
+with answers. These exercises give you some guided practice with
+Calc, as well as pointing out some interesting and unusual ways
+to use its features.
+
+The reference section discusses Calc in complete depth. You can read
+the reference from start to finish if you want to learn every aspect
+of Calc. Or, you can look in the table of contents or the Concept
+Index to find the parts of the manual that discuss the things you
+need to know.
+
+@cindex Marginal notes
+Every Calc keyboard command is listed in the Calc Summary, and also
+in the Key Index. Algebraic functions, @kbd{M-x} commands, and
+variables also have their own indices.
+@texline Each
+@infoline In the printed manual, each
+paragraph that is referenced in the Key or Function Index is marked
+in the margin with its index entry.
+
+@c [fix-ref Help Commands]
+You can access this manual on-line at any time within Calc by
+pressing the @kbd{h i} key sequence. Outside of the Calc window,
+you can press @kbd{C-x * i} to read the manual on-line. Also, you
+can jump directly to the Tutorial by pressing @kbd{h t} or @kbd{C-x * t},
+or to the Summary by pressing @kbd{h s} or @kbd{C-x * s}. Within Calc,
+you can also go to the part of the manual describing any Calc key,
+function, or variable using @w{@kbd{h k}}, @kbd{h f}, or @kbd{h v},
+respectively. @xref{Help Commands}.
+
+@ifnottex
+The Calc manual can be printed, but because the manual is so large, you
+should only make a printed copy if you really need it. To print the
+manual, you will need the @TeX{} typesetting program (this is a free
+program by Donald Knuth at Stanford University) as well as the
+@file{texindex} program and @file{texinfo.tex} file, both of which can
+be obtained from the FSF as part of the @code{texinfo} package.
+To print the Calc manual in one huge tome, you will need the
+source code to this manual, @file{calc.texi}, available as part of the
+Emacs source. Once you have this file, type @kbd{texi2dvi calc.texi}.
+Alternatively, change to the @file{man} subdirectory of the Emacs
+source distribution, and type @kbd{make calc.dvi}. (Don't worry if you
+get some ``overfull box'' warnings while @TeX{} runs.)
+The result will be a device-independent output file called
+@file{calc.dvi}, which you must print in whatever way is right
+for your system. On many systems, the command is
+
+@example
+lpr -d calc.dvi
+@end example
+
+@noindent
+or
+
+@example
+dvips calc.dvi
+@end example
+@end ifnottex
+@c Printed copies of this manual are also available from the Free Software
+@c Foundation.
+
+@node Notations Used in This Manual, Demonstration of Calc, About This Manual, Getting Started
+@section Notations Used in This Manual
+
+@noindent
+This section describes the various notations that are used
+throughout the Calc manual.
+
+In keystroke sequences, uppercase letters mean you must hold down
+the shift key while typing the letter. Keys pressed with Control
+held down are shown as @kbd{C-x}. Keys pressed with Meta held down
+are shown as @kbd{M-x}. Other notations are @key{RET} for the
+Return key, @key{SPC} for the space bar, @key{TAB} for the Tab key,
+@key{DEL} for the Delete key, and @key{LFD} for the Line-Feed key.
+The @key{DEL} key is called Backspace on some keyboards, it is
+whatever key you would use to correct a simple typing error when
+regularly using Emacs.
+
+(If you don't have the @key{LFD} or @key{TAB} keys on your keyboard,
+the @kbd{C-j} and @kbd{C-i} keys are equivalent to them, respectively.
+If you don't have a Meta key, look for Alt or Extend Char. You can
+also press @key{ESC} or @kbd{C-[} first to get the same effect, so
+that @kbd{M-x}, @kbd{@key{ESC} x}, and @kbd{C-[ x} are all equivalent.)
+
+Sometimes the @key{RET} key is not shown when it is ``obvious''
+that you must press @key{RET} to proceed. For example, the @key{RET}
+is usually omitted in key sequences like @kbd{M-x calc-keypad @key{RET}}.
+
+Commands are generally shown like this: @kbd{p} (@code{calc-precision})
+or @kbd{C-x * k} (@code{calc-keypad}). This means that the command is
+normally used by pressing the @kbd{p} key or @kbd{C-x * k} key sequence,
+but it also has the full-name equivalent shown, e.g., @kbd{M-x calc-precision}.
+
+Commands that correspond to functions in algebraic notation
+are written: @kbd{C} (@code{calc-cos}) [@code{cos}]. This means
+the @kbd{C} key is equivalent to @kbd{M-x calc-cos}, and that
+the corresponding function in an algebraic-style formula would
+be @samp{cos(@var{x})}.
+
+A few commands don't have key equivalents: @code{calc-sincos}
+[@code{sincos}].
+
+@node Demonstration of Calc, Using Calc, Notations Used in This Manual, Getting Started
+@section A Demonstration of Calc
+
+@noindent
+@cindex Demonstration of Calc
+This section will show some typical small problems being solved with
+Calc. The focus is more on demonstration than explanation, but
+everything you see here will be covered more thoroughly in the
+Tutorial.
+
+To begin, start Emacs if necessary (usually the command @code{emacs}
+does this), and type @kbd{C-x * c} to start the
+Calculator. (You can also use @kbd{M-x calc} if this doesn't work.
+@xref{Starting Calc}, for various ways of starting the Calculator.)
+
+Be sure to type all the sample input exactly, especially noting the
+difference between lower-case and upper-case letters. Remember,
+@key{RET}, @key{TAB}, @key{DEL}, and @key{SPC} are the Return, Tab,
+Delete, and Space keys.
+
+@strong{RPN calculation.} In RPN, you type the input number(s) first,
+then the command to operate on the numbers.
+
+@noindent
+Type @kbd{2 @key{RET} 3 + Q} to compute
+@texline @math{\sqrt{2+3} = 2.2360679775}.
+@infoline the square root of 2+3, which is 2.2360679775.
+
+@noindent
+Type @kbd{P 2 ^} to compute
+@texline @math{\pi^2 = 9.86960440109}.
+@infoline the value of `pi' squared, 9.86960440109.
+
+@noindent
+Type @key{TAB} to exchange the order of these two results.
+
+@noindent
+Type @kbd{- I H S} to subtract these results and compute the Inverse
+Hyperbolic sine of the difference, 2.72996136574.
+
+@noindent
+Type @key{DEL} to erase this result.
+
+@strong{Algebraic calculation.} You can also enter calculations using
+conventional ``algebraic'' notation. To enter an algebraic formula,
+use the apostrophe key.
+
+@noindent
+Type @kbd{' sqrt(2+3) @key{RET}} to compute
+@texline @math{\sqrt{2+3}}.
+@infoline the square root of 2+3.
+
+@noindent
+Type @kbd{' pi^2 @key{RET}} to enter
+@texline @math{\pi^2}.
+@infoline `pi' squared.
+To evaluate this symbolic formula as a number, type @kbd{=}.
+
+@noindent
+Type @kbd{' arcsinh($ - $$) @key{RET}} to subtract the second-most-recent
+result from the most-recent and compute the Inverse Hyperbolic sine.
+
+@strong{Keypad mode.} If you are using the X window system, press
+@w{@kbd{C-x * k}} to get Keypad mode. (If you don't use X, skip to
+the next section.)
+
+@noindent
+Click on the @key{2}, @key{ENTER}, @key{3}, @key{+}, and @key{SQRT}
+``buttons'' using your left mouse button.
+
+@noindent
+Click on @key{PI}, @key{2}, and @tfn{y^x}.
+
+@noindent
+Click on @key{INV}, then @key{ENTER} to swap the two results.
+
+@noindent
+Click on @key{-}, @key{INV}, @key{HYP}, and @key{SIN}.
+
+@noindent
+Click on @key{<-} to erase the result, then click @key{OFF} to turn
+the Keypad Calculator off.
+
+@strong{Grabbing data.} Type @kbd{C-x * x} if necessary to exit Calc.
+Now select the following numbers as an Emacs region: ``Mark'' the
+front of the list by typing @kbd{C-@key{SPC}} or @kbd{C-@@} there,
+then move to the other end of the list. (Either get this list from
+the on-line copy of this manual, accessed by @w{@kbd{C-x * i}}, or just
+type these numbers into a scratch file.) Now type @kbd{C-x * g} to
+``grab'' these numbers into Calc.
+
+@example
+@group
+1.23 1.97
+1.6 2
+1.19 1.08
+@end group
+@end example
+
+@noindent
+The result @samp{[1.23, 1.97, 1.6, 2, 1.19, 1.08]} is a Calc ``vector.''
+Type @w{@kbd{V R +}} to compute the sum of these numbers.
+
+@noindent
+Type @kbd{U} to Undo this command, then type @kbd{V R *} to compute
+the product of the numbers.
+
+@noindent
+You can also grab data as a rectangular matrix. Place the cursor on
+the upper-leftmost @samp{1} and set the mark, then move to just after
+the lower-right @samp{8} and press @kbd{C-x * r}.
+
+@noindent
+Type @kbd{v t} to transpose this
+@texline @math{3\times2}
+@infoline 3x2
+matrix into a
+@texline @math{2\times3}
+@infoline 2x3
+matrix. Type @w{@kbd{v u}} to unpack the rows into two separate
+vectors. Now type @w{@kbd{V R + @key{TAB} V R +}} to compute the sums
+of the two original columns. (There is also a special
+grab-and-sum-columns command, @kbd{C-x * :}.)
+
+@strong{Units conversion.} Units are entered algebraically.
+Type @w{@kbd{' 43 mi/hr @key{RET}}} to enter the quantity 43 miles-per-hour.
+Type @w{@kbd{u c km/hr @key{RET}}}. Type @w{@kbd{u c m/s @key{RET}}}.
+
+@strong{Date arithmetic.} Type @kbd{t N} to get the current date and
+time. Type @kbd{90 +} to find the date 90 days from now. Type
+@kbd{' <25 dec 87> @key{RET}} to enter a date, then @kbd{- 7 /} to see how
+many weeks have passed since then.
+
+@strong{Algebra.} Algebraic entries can also include formulas
+or equations involving variables. Type @kbd{@w{' [x + y} = a, x y = 1] @key{RET}}
+to enter a pair of equations involving three variables.
+(Note the leading apostrophe in this example; also, note that the space
+between @samp{x y} is required.) Type @w{@kbd{a S x,y @key{RET}}} to solve
+these equations for the variables @expr{x} and @expr{y}.
+
+@noindent
+Type @kbd{d B} to view the solutions in more readable notation.
+Type @w{@kbd{d C}} to view them in C language notation, @kbd{d T}
+to view them in the notation for the @TeX{} typesetting system,
+and @kbd{d L} to view them in the notation for the La@TeX{} typesetting
+system. Type @kbd{d N} to return to normal notation.
+
+@noindent
+Type @kbd{7.5}, then @kbd{s l a @key{RET}} to let @expr{a = 7.5} in these formulas.
+(That's a letter @kbd{l}, not a numeral @kbd{1}.)
+
+@ifnotinfo
+@strong{Help functions.} You can read about any command in the on-line
+manual. Type @kbd{C-x * c} to return to Calc after each of these
+commands: @kbd{h k t N} to read about the @kbd{t N} command,
+@kbd{h f sqrt @key{RET}} to read about the @code{sqrt} function, and
+@kbd{h s} to read the Calc summary.
+@end ifnotinfo
+@ifinfo
+@strong{Help functions.} You can read about any command in the on-line
+manual. Remember to type the letter @kbd{l}, then @kbd{C-x * c}, to
+return here after each of these commands: @w{@kbd{h k t N}} to read
+about the @w{@kbd{t N}} command, @kbd{h f sqrt @key{RET}} to read about the
+@code{sqrt} function, and @kbd{h s} to read the Calc summary.
+@end ifinfo
+
+Press @key{DEL} repeatedly to remove any leftover results from the stack.
+To exit from Calc, press @kbd{q} or @kbd{C-x * c} again.
+
+@node Using Calc, History and Acknowledgements, Demonstration of Calc, Getting Started
+@section Using Calc
+
+@noindent
+Calc has several user interfaces that are specialized for
+different kinds of tasks. As well as Calc's standard interface,
+there are Quick mode, Keypad mode, and Embedded mode.
+
+@menu
+* Starting Calc::
+* The Standard Interface::
+* Quick Mode Overview::
+* Keypad Mode Overview::
+* Standalone Operation::
+* Embedded Mode Overview::
+* Other C-x * Commands::
+@end menu
+
+@node Starting Calc, The Standard Interface, Using Calc, Using Calc
+@subsection Starting Calc
+
+@noindent
+On most systems, you can type @kbd{C-x *} to start the Calculator.
+The key sequence @kbd{C-x *} is bound to the command @code{calc-dispatch},
+which can be rebound if convenient (@pxref{Customizing Calc}).
+
+When you press @kbd{C-x *}, Emacs waits for you to press a second key to
+complete the command. In this case, you will follow @kbd{C-x *} with a
+letter (upper- or lower-case, it doesn't matter for @kbd{C-x *}) that says
+which Calc interface you want to use.
+
+To get Calc's standard interface, type @kbd{C-x * c}. To get
+Keypad mode, type @kbd{C-x * k}. Type @kbd{C-x * ?} to get a brief
+list of the available options, and type a second @kbd{?} to get
+a complete list.
+
+To ease typing, @kbd{C-x * *} also works to start Calc. It starts the
+same interface (either @kbd{C-x * c} or @w{@kbd{C-x * k}}) that you last
+used, selecting the @kbd{C-x * c} interface by default.
+
+If @kbd{C-x *} doesn't work for you, you can always type explicit
+commands like @kbd{M-x calc} (for the standard user interface) or
+@w{@kbd{M-x calc-keypad}} (for Keypad mode). First type @kbd{M-x}
+(that's Meta with the letter @kbd{x}), then, at the prompt,
+type the full command (like @kbd{calc-keypad}) and press Return.
+
+The same commands (like @kbd{C-x * c} or @kbd{C-x * *}) that start
+the Calculator also turn it off if it is already on.
+
+@node The Standard Interface, Quick Mode Overview, Starting Calc, Using Calc
+@subsection The Standard Calc Interface
+
+@noindent
+@cindex Standard user interface
+Calc's standard interface acts like a traditional RPN calculator,
+operated by the normal Emacs keyboard. When you type @kbd{C-x * c}
+to start the Calculator, the Emacs screen splits into two windows
+with the file you were editing on top and Calc on the bottom.
+
+@smallexample
+@group
+
+...
+--**-Emacs: myfile (Fundamental)----All----------------------
+--- Emacs Calculator Mode --- |Emacs Calculator Trail
+2: 17.3 | 17.3
+1: -5 | 3
+ . | 2
+ | 4
+ | * 8
+ | ->-5
+ |
+--%%-Calc: 12 Deg (Calculator)----All----- --%%-Emacs: *Calc Trail*
+@end group
+@end smallexample
+
+In this figure, the mode-line for @file{myfile} has moved up and the
+``Calculator'' window has appeared below it. As you can see, Calc
+actually makes two windows side-by-side. The lefthand one is
+called the @dfn{stack window} and the righthand one is called the
+@dfn{trail window.} The stack holds the numbers involved in the
+calculation you are currently performing. The trail holds a complete
+record of all calculations you have done. In a desk calculator with
+a printer, the trail corresponds to the paper tape that records what
+you do.
+
+In this case, the trail shows that four numbers (17.3, 3, 2, and 4)
+were first entered into the Calculator, then the 2 and 4 were
+multiplied to get 8, then the 3 and 8 were subtracted to get @mathit{-5}.
+(The @samp{>} symbol shows that this was the most recent calculation.)
+The net result is the two numbers 17.3 and @mathit{-5} sitting on the stack.
+
+Most Calculator commands deal explicitly with the stack only, but
+there is a set of commands that allow you to search back through
+the trail and retrieve any previous result.
+
+Calc commands use the digits, letters, and punctuation keys.
+Shifted (i.e., upper-case) letters are different from lowercase
+letters. Some letters are @dfn{prefix} keys that begin two-letter
+commands. For example, @kbd{e} means ``enter exponent'' and shifted
+@kbd{E} means @expr{e^x}. With the @kbd{d} (``display modes'') prefix
+the letter ``e'' takes on very different meanings: @kbd{d e} means
+``engineering notation'' and @kbd{d E} means ``@dfn{eqn} language mode.''
+
+There is nothing stopping you from switching out of the Calc
+window and back into your editing window, say by using the Emacs
+@w{@kbd{C-x o}} (@code{other-window}) command. When the cursor is
+inside a regular window, Emacs acts just like normal. When the
+cursor is in the Calc stack or trail windows, keys are interpreted
+as Calc commands.
+
+When you quit by pressing @kbd{C-x * c} a second time, the Calculator
+windows go away but the actual Stack and Trail are not gone, just
+hidden. When you press @kbd{C-x * c} once again you will get the
+same stack and trail contents you had when you last used the
+Calculator.
+
+The Calculator does not remember its state between Emacs sessions.
+Thus if you quit Emacs and start it again, @kbd{C-x * c} will give you
+a fresh stack and trail. There is a command (@kbd{m m}) that lets
+you save your favorite mode settings between sessions, though.
+One of the things it saves is which user interface (standard or
+Keypad) you last used; otherwise, a freshly started Emacs will
+always treat @kbd{C-x * *} the same as @kbd{C-x * c}.
+
+The @kbd{q} key is another equivalent way to turn the Calculator off.
+
+If you type @kbd{C-x * b} first and then @kbd{C-x * c}, you get a
+full-screen version of Calc (@code{full-calc}) in which the stack and
+trail windows are still side-by-side but are now as tall as the whole
+Emacs screen. When you press @kbd{q} or @kbd{C-x * c} again to quit,
+the file you were editing before reappears. The @kbd{C-x * b} key
+switches back and forth between ``big'' full-screen mode and the
+normal partial-screen mode.
+
+Finally, @kbd{C-x * o} (@code{calc-other-window}) is like @kbd{C-x * c}
+except that the Calc window is not selected. The buffer you were
+editing before remains selected instead. @kbd{C-x * o} is a handy
+way to switch out of Calc momentarily to edit your file; type
+@kbd{C-x * c} to switch back into Calc when you are done.
+
+@node Quick Mode Overview, Keypad Mode Overview, The Standard Interface, Using Calc
+@subsection Quick Mode (Overview)
+
+@noindent
+@dfn{Quick mode} is a quick way to use Calc when you don't need the
+full complexity of the stack and trail. To use it, type @kbd{C-x * q}
+(@code{quick-calc}) in any regular editing buffer.
+
+Quick mode is very simple: It prompts you to type any formula in
+standard algebraic notation (like @samp{4 - 2/3}) and then displays
+the result at the bottom of the Emacs screen (@mathit{3.33333333333}
+in this case). You are then back in the same editing buffer you
+were in before, ready to continue editing or to type @kbd{C-x * q}
+again to do another quick calculation. The result of the calculation
+will also be in the Emacs ``kill ring'' so that a @kbd{C-y} command
+at this point will yank the result into your editing buffer.
+
+Calc mode settings affect Quick mode, too, though you will have to
+go into regular Calc (with @kbd{C-x * c}) to change the mode settings.
+
+@c [fix-ref Quick Calculator mode]
+@xref{Quick Calculator}, for further information.
+
+@node Keypad Mode Overview, Standalone Operation, Quick Mode Overview, Using Calc
+@subsection Keypad Mode (Overview)
+
+@noindent
+@dfn{Keypad mode} is a mouse-based interface to the Calculator.
+It is designed for use with terminals that support a mouse. If you
+don't have a mouse, you will have to operate Keypad mode with your
+arrow keys (which is probably more trouble than it's worth).
+
+Type @kbd{C-x * k} to turn Keypad mode on or off. Once again you
+get two new windows, this time on the righthand side of the screen
+instead of at the bottom. The upper window is the familiar Calc
+Stack; the lower window is a picture of a typical calculator keypad.
+
+@tex
+\dimen0=\pagetotal%
+\advance \dimen0 by 24\baselineskip%
+\ifdim \dimen0>\pagegoal \vfill\eject \fi%
+\medskip
+@end tex
+@smallexample
+@group
+|--- Emacs Calculator Mode ---
+|2: 17.3
+|1: -5
+| .
+|--%%-Calc: 12 Deg (Calcul
+|----+-----Calc 2.1------+----1
+|FLR |CEIL|RND |TRNC|CLN2|FLT |
+|----+----+----+----+----+----|
+| LN |EXP | |ABS |IDIV|MOD |
+|----+----+----+----+----+----|
+|SIN |COS |TAN |SQRT|y^x |1/x |
+|----+----+----+----+----+----|
+| ENTER |+/- |EEX |UNDO| <- |
+|-----+---+-+--+--+-+---++----|
+| INV | 7 | 8 | 9 | / |
+|-----+-----+-----+-----+-----|
+| HYP | 4 | 5 | 6 | * |
+|-----+-----+-----+-----+-----|
+|EXEC | 1 | 2 | 3 | - |
+|-----+-----+-----+-----+-----|
+| OFF | 0 | . | PI | + |
+|-----+-----+-----+-----+-----+
+@end group
+@end smallexample
+
+Keypad mode is much easier for beginners to learn, because there
+is no need to memorize lots of obscure key sequences. But not all
+commands in regular Calc are available on the Keypad. You can
+always switch the cursor into the Calc stack window to use
+standard Calc commands if you need. Serious Calc users, though,
+often find they prefer the standard interface over Keypad mode.
+
+To operate the Calculator, just click on the ``buttons'' of the
+keypad using your left mouse button. To enter the two numbers
+shown here you would click @w{@kbd{1 7 .@: 3 ENTER 5 +/- ENTER}}; to
+add them together you would then click @kbd{+} (to get 12.3 on
+the stack).
+
+If you click the right mouse button, the top three rows of the
+keypad change to show other sets of commands, such as advanced
+math functions, vector operations, and operations on binary
+numbers.
+
+Because Keypad mode doesn't use the regular keyboard, Calc leaves
+the cursor in your original editing buffer. You can type in
+this buffer in the usual way while also clicking on the Calculator
+keypad. One advantage of Keypad mode is that you don't need an
+explicit command to switch between editing and calculating.
+
+If you press @kbd{C-x * b} first, you get a full-screen Keypad mode
+(@code{full-calc-keypad}) with three windows: The keypad in the lower
+left, the stack in the lower right, and the trail on top.
+
+@c [fix-ref Keypad Mode]
+@xref{Keypad Mode}, for further information.
+
+@node Standalone Operation, Embedded Mode Overview, Keypad Mode Overview, Using Calc
+@subsection Standalone Operation
+
+@noindent
+@cindex Standalone Operation
+If you are not in Emacs at the moment but you wish to use Calc,
+you must start Emacs first. If all you want is to run Calc, you
+can give the commands:
+
+@example
+emacs -f full-calc
+@end example
+
+@noindent
+or
+
+@example
+emacs -f full-calc-keypad
+@end example
+
+@noindent
+which run a full-screen Calculator (as if by @kbd{C-x * b C-x * c}) or
+a full-screen X-based Calculator (as if by @kbd{C-x * b C-x * k}).
+In standalone operation, quitting the Calculator (by pressing
+@kbd{q} or clicking on the keypad @key{EXIT} button) quits Emacs
+itself.
+
+@node Embedded Mode Overview, Other C-x * Commands, Standalone Operation, Using Calc
+@subsection Embedded Mode (Overview)
+
+@noindent
+@dfn{Embedded mode} is a way to use Calc directly from inside an
+editing buffer. Suppose you have a formula written as part of a
+document like this:
+
+@smallexample
+@group
+The derivative of
+
+ ln(ln(x))
+
+is
+@end group
+@end smallexample
+
+@noindent
+and you wish to have Calc compute and format the derivative for
+you and store this derivative in the buffer automatically. To
+do this with Embedded mode, first copy the formula down to where
+you want the result to be:
+
+@smallexample
+@group
+The derivative of
+
+ ln(ln(x))
+
+is
+
+ ln(ln(x))
+@end group
+@end smallexample
+
+Now, move the cursor onto this new formula and press @kbd{C-x * e}.
+Calc will read the formula (using the surrounding blank lines to
+tell how much text to read), then push this formula (invisibly)
+onto the Calc stack. The cursor will stay on the formula in the
+editing buffer, but the buffer's mode line will change to look
+like the Calc mode line (with mode indicators like @samp{12 Deg}
+and so on). Even though you are still in your editing buffer,
+the keyboard now acts like the Calc keyboard, and any new result
+you get is copied from the stack back into the buffer. To take
+the derivative, you would type @kbd{a d x @key{RET}}.
+
+@smallexample
+@group
+The derivative of
+
+ ln(ln(x))
+
+is
+
+1 / ln(x) x
+@end group
+@end smallexample
+
+To make this look nicer, you might want to press @kbd{d =} to center
+the formula, and even @kbd{d B} to use Big display mode.
+
+@smallexample
+@group
+The derivative of
+
+ ln(ln(x))
+
+is
+% [calc-mode: justify: center]
+% [calc-mode: language: big]
+
+ 1
+ -------
+ ln(x) x
+@end group
+@end smallexample
+
+Calc has added annotations to the file to help it remember the modes
+that were used for this formula. They are formatted like comments
+in the @TeX{} typesetting language, just in case you are using @TeX{} or
+La@TeX{}. (In this example @TeX{} is not being used, so you might want
+to move these comments up to the top of the file or otherwise put them
+out of the way.)
+
+As an extra flourish, we can add an equation number using a
+righthand label: Type @kbd{d @} (1) @key{RET}}.
+
+@smallexample
+@group
+% [calc-mode: justify: center]
+% [calc-mode: language: big]
+% [calc-mode: right-label: " (1)"]
+
+ 1
+ ------- (1)
+ ln(x) x
+@end group
+@end smallexample
+
+To leave Embedded mode, type @kbd{C-x * e} again. The mode line
+and keyboard will revert to the way they were before.
+
+The related command @kbd{C-x * w} operates on a single word, which
+generally means a single number, inside text. It uses any
+non-numeric characters rather than blank lines to delimit the
+formula it reads. Here's an example of its use:
+
+@smallexample
+A slope of one-third corresponds to an angle of 1 degrees.
+@end smallexample
+
+Place the cursor on the @samp{1}, then type @kbd{C-x * w} to enable
+Embedded mode on that number. Now type @kbd{3 /} (to get one-third),
+and @kbd{I T} (the Inverse Tangent converts a slope into an angle),
+then @w{@kbd{C-x * w}} again to exit Embedded mode.
+
+@smallexample
+A slope of one-third corresponds to an angle of 18.4349488229 degrees.
+@end smallexample
+
+@c [fix-ref Embedded Mode]
+@xref{Embedded Mode}, for full details.
+
+@node Other C-x * Commands, , Embedded Mode Overview, Using Calc
+@subsection Other @kbd{C-x *} Commands
+
+@noindent
+Two more Calc-related commands are @kbd{C-x * g} and @kbd{C-x * r},
+which ``grab'' data from a selected region of a buffer into the
+Calculator. The region is defined in the usual Emacs way, by
+a ``mark'' placed at one end of the region, and the Emacs
+cursor or ``point'' placed at the other.
+
+The @kbd{C-x * g} command reads the region in the usual left-to-right,
+top-to-bottom order. The result is packaged into a Calc vector
+of numbers and placed on the stack. Calc (in its standard
+user interface) is then started. Type @kbd{v u} if you want
+to unpack this vector into separate numbers on the stack. Also,
+@kbd{C-u C-x * g} interprets the region as a single number or
+formula.
+
+The @kbd{C-x * r} command reads a rectangle, with the point and
+mark defining opposite corners of the rectangle. The result
+is a matrix of numbers on the Calculator stack.
+
+Complementary to these is @kbd{C-x * y}, which ``yanks'' the
+value at the top of the Calc stack back into an editing buffer.
+If you type @w{@kbd{C-x * y}} while in such a buffer, the value is
+yanked at the current position. If you type @kbd{C-x * y} while
+in the Calc buffer, Calc makes an educated guess as to which
+editing buffer you want to use. The Calc window does not have
+to be visible in order to use this command, as long as there
+is something on the Calc stack.
+
+Here, for reference, is the complete list of @kbd{C-x *} commands.
+The shift, control, and meta keys are ignored for the keystroke
+following @kbd{C-x *}.
+
+@noindent
+Commands for turning Calc on and off:
+
+@table @kbd
+@item *
+Turn Calc on or off, employing the same user interface as last time.
+
+@item =, +, -, /, \, &, #
+Alternatives for @kbd{*}.
+
+@item C
+Turn Calc on or off using its standard bottom-of-the-screen
+interface. If Calc is already turned on but the cursor is not
+in the Calc window, move the cursor into the window.
+
+@item O
+Same as @kbd{C}, but don't select the new Calc window. If
+Calc is already turned on and the cursor is in the Calc window,
+move it out of that window.
+
+@item B
+Control whether @kbd{C-x * c} and @kbd{C-x * k} use the full screen.
+
+@item Q
+Use Quick mode for a single short calculation.
+
+@item K
+Turn Calc Keypad mode on or off.
+
+@item E
+Turn Calc Embedded mode on or off at the current formula.
+
+@item J
+Turn Calc Embedded mode on or off, select the interesting part.
+
+@item W
+Turn Calc Embedded mode on or off at the current word (number).
+
+@item Z
+Turn Calc on in a user-defined way, as defined by a @kbd{Z I} command.
+
+@item X
+Quit Calc; turn off standard, Keypad, or Embedded mode if on.
+(This is like @kbd{q} or @key{OFF} inside of Calc.)
+@end table
+@iftex
+@sp 2
+@end iftex
+
+@noindent
+Commands for moving data into and out of the Calculator:
+
+@table @kbd
+@item G
+Grab the region into the Calculator as a vector.
+
+@item R
+Grab the rectangular region into the Calculator as a matrix.
+
+@item :
+Grab the rectangular region and compute the sums of its columns.
+
+@item _
+Grab the rectangular region and compute the sums of its rows.
+
+@item Y
+Yank a value from the Calculator into the current editing buffer.
+@end table
+@iftex
+@sp 2
+@end iftex
+
+@noindent
+Commands for use with Embedded mode:
+
+@table @kbd
+@item A
+``Activate'' the current buffer. Locate all formulas that
+contain @samp{:=} or @samp{=>} symbols and record their locations
+so that they can be updated automatically as variables are changed.
+
+@item D
+Duplicate the current formula immediately below and select
+the duplicate.
+
+@item F
+Insert a new formula at the current point.
+
+@item N
+Move the cursor to the next active formula in the buffer.
+
+@item P
+Move the cursor to the previous active formula in the buffer.
+
+@item U
+Update (i.e., as if by the @kbd{=} key) the formula at the current point.
+
+@item `
+Edit (as if by @code{calc-edit}) the formula at the current point.
+@end table
+@iftex
+@sp 2
+@end iftex
+
+@noindent
+Miscellaneous commands:
+
+@table @kbd
+@item I
+Run the Emacs Info system to read the Calc manual.
+(This is the same as @kbd{h i} inside of Calc.)
+
+@item T
+Run the Emacs Info system to read the Calc Tutorial.
+
+@item S
+Run the Emacs Info system to read the Calc Summary.
+
+@item L
+Load Calc entirely into memory. (Normally the various parts
+are loaded only as they are needed.)
+
+@item M
+Read a region of written keystroke names (like @kbd{C-n a b c @key{RET}})
+and record them as the current keyboard macro.
+
+@item 0
+(This is the ``zero'' digit key.) Reset the Calculator to
+its initial state: Empty stack, and initial mode settings.
+@end table
+
+@node History and Acknowledgements, , Using Calc, Getting Started
+@section History and Acknowledgements
+
+@noindent
+Calc was originally started as a two-week project to occupy a lull
+in the author's schedule. Basically, a friend asked if I remembered
+the value of
+@texline @math{2^{32}}.
+@infoline @expr{2^32}.
+I didn't offhand, but I said, ``that's easy, just call up an
+@code{xcalc}.'' @code{Xcalc} duly reported that the answer to our
+question was @samp{4.294967e+09}---with no way to see the full ten
+digits even though we knew they were there in the program's memory! I
+was so annoyed, I vowed to write a calculator of my own, once and for
+all.
+
+I chose Emacs Lisp, a) because I had always been curious about it
+and b) because, being only a text editor extension language after
+all, Emacs Lisp would surely reach its limits long before the project
+got too far out of hand.
+
+To make a long story short, Emacs Lisp turned out to be a distressingly
+solid implementation of Lisp, and the humble task of calculating
+turned out to be more open-ended than one might have expected.
+
+Emacs Lisp didn't have built-in floating point math (now it does), so
+this had to be
+simulated in software. In fact, Emacs integers will only comfortably
+fit six decimal digits or so---not enough for a decent calculator. So
+I had to write my own high-precision integer code as well, and once I had
+this I figured that arbitrary-size integers were just as easy as large
+integers. Arbitrary floating-point precision was the logical next step.
+Also, since the large integer arithmetic was there anyway it seemed only
+fair to give the user direct access to it, which in turn made it practical
+to support fractions as well as floats. All these features inspired me
+to look around for other data types that might be worth having.
+
+Around this time, my friend Rick Koshi showed me his nifty new HP-28
+calculator. It allowed the user to manipulate formulas as well as
+numerical quantities, and it could also operate on matrices. I
+decided that these would be good for Calc to have, too. And once
+things had gone this far, I figured I might as well take a look at
+serious algebra systems for further ideas. Since these systems did
+far more than I could ever hope to implement, I decided to focus on
+rewrite rules and other programming features so that users could
+implement what they needed for themselves.
+
+Rick complained that matrices were hard to read, so I put in code to
+format them in a 2D style. Once these routines were in place, Big mode
+was obligatory. Gee, what other language modes would be useful?
+
+Scott Hemphill and Allen Knutson, two friends with a strong mathematical
+bent, contributed ideas and algorithms for a number of Calc features
+including modulo forms, primality testing, and float-to-fraction conversion.
+
+Units were added at the eager insistence of Mass Sivilotti. Later,
+Ulrich Mueller at CERN and Przemek Klosowski at NIST provided invaluable
+expert assistance with the units table. As far as I can remember, the
+idea of using algebraic formulas and variables to represent units dates
+back to an ancient article in Byte magazine about muMath, an early
+algebra system for microcomputers.
+
+Many people have contributed to Calc by reporting bugs and suggesting
+features, large and small. A few deserve special mention: Tim Peters,
+who helped develop the ideas that led to the selection commands, rewrite
+rules, and many other algebra features;
+@texline Fran\c{c}ois
+@infoline Francois
+Pinard, who contributed an early prototype of the Calc Summary appendix
+as well as providing valuable suggestions in many other areas of Calc;
+Carl Witty, whose eagle eyes discovered many typographical and factual
+errors in the Calc manual; Tim Kay, who drove the development of
+Embedded mode; Ove Ewerlid, who made many suggestions relating to the
+algebra commands and contributed some code for polynomial operations;
+Randal Schwartz, who suggested the @code{calc-eval} function; Robert
+J. Chassell, who suggested the Calc Tutorial and exercises; and Juha
+Sarlin, who first worked out how to split Calc into quickly-loading
+parts. Bob Weiner helped immensely with the Lucid Emacs port.
+
+@cindex Bibliography
+@cindex Knuth, Art of Computer Programming
+@cindex Numerical Recipes
+@c Should these be expanded into more complete references?
+Among the books used in the development of Calc were Knuth's @emph{Art
+of Computer Programming} (especially volume II, @emph{Seminumerical
+Algorithms}); @emph{Numerical Recipes} by Press, Flannery, Teukolsky,
+and Vetterling; Bevington's @emph{Data Reduction and Error Analysis
+for the Physical Sciences}; @emph{Concrete Mathematics} by Graham,
+Knuth, and Patashnik; Steele's @emph{Common Lisp, the Language}; the
+@emph{CRC Standard Math Tables} (William H. Beyer, ed.); and
+Abramowitz and Stegun's venerable @emph{Handbook of Mathematical
+Functions}. Also, of course, Calc could not have been written without
+the excellent @emph{GNU Emacs Lisp Reference Manual}, by Bil Lewis and
+Dan LaLiberte.
+
+Final thanks go to Richard Stallman, without whose fine implementations
+of the Emacs editor, language, and environment, Calc would have been
+finished in two weeks.
+
+@c [tutorial]
+
+@ifinfo
+@c This node is accessed by the `C-x * t' command.
+@node Interactive Tutorial, Tutorial, Getting Started, Top
+@chapter Tutorial
+
+@noindent
+Some brief instructions on using the Emacs Info system for this tutorial:
+
+Press the space bar and Delete keys to go forward and backward in a
+section by screenfuls (or use the regular Emacs scrolling commands
+for this).
+
+Press @kbd{n} or @kbd{p} to go to the Next or Previous section.
+If the section has a @dfn{menu}, press a digit key like @kbd{1}
+or @kbd{2} to go to a sub-section from the menu. Press @kbd{u} to
+go back up from a sub-section to the menu it is part of.
+
+Exercises in the tutorial all have cross-references to the
+appropriate page of the ``answers'' section. Press @kbd{f}, then
+the exercise number, to see the answer to an exercise. After
+you have followed a cross-reference, you can press the letter
+@kbd{l} to return to where you were before.
+
+You can press @kbd{?} at any time for a brief summary of Info commands.
+
+Press @kbd{1} now to enter the first section of the Tutorial.
+
+@menu
+* Tutorial::
+@end menu
+
+@node Tutorial, Introduction, Interactive Tutorial, Top
+@end ifinfo
+@ifnotinfo
+@node Tutorial, Introduction, Getting Started, Top
+@end ifnotinfo
+@chapter Tutorial
+
+@noindent
+This chapter explains how to use Calc and its many features, in
+a step-by-step, tutorial way. You are encouraged to run Calc and
+work along with the examples as you read (@pxref{Starting Calc}).
+If you are already familiar with advanced calculators, you may wish
+@c [not-split]
+to skip on to the rest of this manual.
+@c [when-split]
+@c to skip on to volume II of this manual, the @dfn{Calc Reference}.
+
+@c [fix-ref Embedded Mode]
+This tutorial describes the standard user interface of Calc only.
+The Quick mode and Keypad mode interfaces are fairly
+self-explanatory. @xref{Embedded Mode}, for a description of
+the Embedded mode interface.
+
+The easiest way to read this tutorial on-line is to have two windows on
+your Emacs screen, one with Calc and one with the Info system. (If you
+have a printed copy of the manual you can use that instead.) Press
+@kbd{C-x * c} to turn Calc on or to switch into the Calc window, and
+press @kbd{C-x * i} to start the Info system or to switch into its window.
+
+This tutorial is designed to be done in sequence. But the rest of this
+manual does not assume you have gone through the tutorial. The tutorial
+does not cover everything in the Calculator, but it touches on most
+general areas.
+
+@ifnottex
+You may wish to print out a copy of the Calc Summary and keep notes on
+it as you learn Calc. @xref{About This Manual}, to see how to make a
+printed summary. @xref{Summary}.
+@end ifnottex
+@iftex
+The Calc Summary at the end of the reference manual includes some blank
+space for your own use. You may wish to keep notes there as you learn
+Calc.
+@end iftex
+
+@menu
+* Basic Tutorial::
+* Arithmetic Tutorial::
+* Vector/Matrix Tutorial::
+* Types Tutorial::
+* Algebra Tutorial::
+* Programming Tutorial::
+
+* Answers to Exercises::
+@end menu
+
+@node Basic Tutorial, Arithmetic Tutorial, Tutorial, Tutorial
+@section Basic Tutorial
+
+@noindent
+In this section, we learn how RPN and algebraic-style calculations
+work, how to undo and redo an operation done by mistake, and how
+to control various modes of the Calculator.
+
+@menu
+* RPN Tutorial:: Basic operations with the stack.
+* Algebraic Tutorial:: Algebraic entry; variables.
+* Undo Tutorial:: If you make a mistake: Undo and the trail.
+* Modes Tutorial:: Common mode-setting commands.
+@end menu
+
+@node RPN Tutorial, Algebraic Tutorial, Basic Tutorial, Basic Tutorial
+@subsection RPN Calculations and the Stack
+
+@cindex RPN notation
+@ifnottex
+@noindent
+Calc normally uses RPN notation. You may be familiar with the RPN
+system from Hewlett-Packard calculators, FORTH, or PostScript.
+(Reverse Polish Notation, RPN, is named after the Polish mathematician
+Jan Lukasiewicz.)
+@end ifnottex
+@tex
+\noindent
+Calc normally uses RPN notation. You may be familiar with the RPN
+system from Hewlett-Packard calculators, FORTH, or PostScript.
+(Reverse Polish Notation, RPN, is named after the Polish mathematician
+Jan \L ukasiewicz.)
+@end tex
+
+The central component of an RPN calculator is the @dfn{stack}. A
+calculator stack is like a stack of dishes. New dishes (numbers) are
+added at the top of the stack, and numbers are normally only removed
+from the top of the stack.
+
+@cindex Operators
+@cindex Operands
+In an operation like @expr{2+3}, the 2 and 3 are called the @dfn{operands}
+and the @expr{+} is the @dfn{operator}. In an RPN calculator you always
+enter the operands first, then the operator. Each time you type a
+number, Calc adds or @dfn{pushes} it onto the top of the Stack.
+When you press an operator key like @kbd{+}, Calc @dfn{pops} the appropriate
+number of operands from the stack and pushes back the result.
+
+Thus we could add the numbers 2 and 3 in an RPN calculator by typing:
+@kbd{2 @key{RET} 3 @key{RET} +}. (The @key{RET} key, Return, corresponds to
+the @key{ENTER} key on traditional RPN calculators.) Try this now if
+you wish; type @kbd{C-x * c} to switch into the Calc window (you can type
+@kbd{C-x * c} again or @kbd{C-x * o} to switch back to the Tutorial window).
+The first four keystrokes ``push'' the numbers 2 and 3 onto the stack.
+The @kbd{+} key ``pops'' the top two numbers from the stack, adds them,
+and pushes the result (5) back onto the stack. Here's how the stack
+will look at various points throughout the calculation:
+
+@smallexample
+@group
+ . 1: 2 2: 2 1: 5 .
+ . 1: 3 .
+ .
+
+ C-x * c 2 @key{RET} 3 @key{RET} + @key{DEL}
+@end group
+@end smallexample
+
+The @samp{.} symbol is a marker that represents the top of the stack.
+Note that the ``top'' of the stack is really shown at the bottom of
+the Stack window. This may seem backwards, but it turns out to be
+less distracting in regular use.
+
+@cindex Stack levels
+@cindex Levels of stack
+The numbers @samp{1:} and @samp{2:} on the left are @dfn{stack level
+numbers}. Old RPN calculators always had four stack levels called
+@expr{x}, @expr{y}, @expr{z}, and @expr{t}. Calc's stack can grow
+as large as you like, so it uses numbers instead of letters. Some
+stack-manipulation commands accept a numeric argument that says
+which stack level to work on. Normal commands like @kbd{+} always
+work on the top few levels of the stack.
+
+@c [fix-ref Truncating the Stack]
+The Stack buffer is just an Emacs buffer, and you can move around in
+it using the regular Emacs motion commands. But no matter where the
+cursor is, even if you have scrolled the @samp{.} marker out of
+view, most Calc commands always move the cursor back down to level 1
+before doing anything. It is possible to move the @samp{.} marker
+upwards through the stack, temporarily ``hiding'' some numbers from
+commands like @kbd{+}. This is called @dfn{stack truncation} and
+we will not cover it in this tutorial; @pxref{Truncating the Stack},
+if you are interested.
+
+You don't really need the second @key{RET} in @kbd{2 @key{RET} 3
+@key{RET} +}. That's because if you type any operator name or
+other non-numeric key when you are entering a number, the Calculator
+automatically enters that number and then does the requested command.
+Thus @kbd{2 @key{RET} 3 +} will work just as well.
+
+Examples in this tutorial will often omit @key{RET} even when the
+stack displays shown would only happen if you did press @key{RET}:
+
+@smallexample
+@group
+1: 2 2: 2 1: 5
+ . 1: 3 .
+ .
+
+ 2 @key{RET} 3 +
+@end group
+@end smallexample
+
+@noindent
+Here, after pressing @kbd{3} the stack would really show @samp{1: 2}
+with @samp{Calc:@: 3} in the minibuffer. In these situations, you can
+press the optional @key{RET} to see the stack as the figure shows.
+
+(@bullet{}) @strong{Exercise 1.} (This tutorial will include exercises
+at various points. Try them if you wish. Answers to all the exercises
+are located at the end of the Tutorial chapter. Each exercise will
+include a cross-reference to its particular answer. If you are
+reading with the Emacs Info system, press @kbd{f} and the
+exercise number to go to the answer, then the letter @kbd{l} to
+return to where you were.)
+
+@noindent
+Here's the first exercise: What will the keystrokes @kbd{1 @key{RET} 2
+@key{RET} 3 @key{RET} 4 + * -} compute? (@samp{*} is the symbol for
+multiplication.) Figure it out by hand, then try it with Calc to see
+if you're right. @xref{RPN Answer 1, 1}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 2.} Compute
+@texline @math{(2\times4) + (7\times9.4) + {5\over4}}
+@infoline @expr{2*4 + 7*9.5 + 5/4}
+using the stack. @xref{RPN Answer 2, 2}. (@bullet{})
+
+The @key{DEL} key is called Backspace on some keyboards. It is
+whatever key you would use to correct a simple typing error when
+regularly using Emacs. The @key{DEL} key pops and throws away the
+top value on the stack. (You can still get that value back from
+the Trail if you should need it later on.) There are many places
+in this tutorial where we assume you have used @key{DEL} to erase the
+results of the previous example at the beginning of a new example.
+In the few places where it is really important to use @key{DEL} to
+clear away old results, the text will remind you to do so.
+
+(It won't hurt to let things accumulate on the stack, except that
+whenever you give a display-mode-changing command Calc will have to
+spend a long time reformatting such a large stack.)
+
+Since the @kbd{-} key is also an operator (it subtracts the top two
+stack elements), how does one enter a negative number? Calc uses
+the @kbd{_} (underscore) key to act like the minus sign in a number.
+So, typing @kbd{-5 @key{RET}} won't work because the @kbd{-} key
+will try to do a subtraction, but @kbd{_5 @key{RET}} works just fine.
+
+You can also press @kbd{n}, which means ``change sign.'' It changes
+the number at the top of the stack (or the number being entered)
+from positive to negative or vice-versa: @kbd{5 n @key{RET}}.
+
+@cindex Duplicating a stack entry
+If you press @key{RET} when you're not entering a number, the effect
+is to duplicate the top number on the stack. Consider this calculation:
+
+@smallexample
+@group
+1: 3 2: 3 1: 9 2: 9 1: 81
+ . 1: 3 . 1: 9 .
+ . .
+
+ 3 @key{RET} @key{RET} * @key{RET} *
+@end group
+@end smallexample
+
+@noindent
+(Of course, an easier way to do this would be @kbd{3 @key{RET} 4 ^},
+to raise 3 to the fourth power.)
+
+The space-bar key (denoted @key{SPC} here) performs the same function
+as @key{RET}; you could replace all three occurrences of @key{RET} in
+the above example with @key{SPC} and the effect would be the same.
+
+@cindex Exchanging stack entries
+Another stack manipulation key is @key{TAB}. This exchanges the top
+two stack entries. Suppose you have computed @kbd{2 @key{RET} 3 +}
+to get 5, and then you realize what you really wanted to compute
+was @expr{20 / (2+3)}.
+
+@smallexample
+@group
+1: 5 2: 5 2: 20 1: 4
+ . 1: 20 1: 5 .
+ . .
+
+ 2 @key{RET} 3 + 20 @key{TAB} /
+@end group
+@end smallexample
+
+@noindent
+Planning ahead, the calculation would have gone like this:
+
+@smallexample
+@group
+1: 20 2: 20 3: 20 2: 20 1: 4
+ . 1: 2 2: 2 1: 5 .
+ . 1: 3 .
+ .
+
+ 20 @key{RET} 2 @key{RET} 3 + /
+@end group
+@end smallexample
+
+A related stack command is @kbd{M-@key{TAB}} (hold @key{META} and type
+@key{TAB}). It rotates the top three elements of the stack upward,
+bringing the object in level 3 to the top.
+
+@smallexample
+@group
+1: 10 2: 10 3: 10 3: 20 3: 30
+ . 1: 20 2: 20 2: 30 2: 10
+ . 1: 30 1: 10 1: 20
+ . . .
+
+ 10 @key{RET} 20 @key{RET} 30 @key{RET} M-@key{TAB} M-@key{TAB}
+@end group
+@end smallexample
+
+(@bullet{}) @strong{Exercise 3.} Suppose the numbers 10, 20, and 30 are
+on the stack. Figure out how to add one to the number in level 2
+without affecting the rest of the stack. Also figure out how to add
+one to the number in level 3. @xref{RPN Answer 3, 3}. (@bullet{})
+
+Operations like @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, and @kbd{^} pop two
+arguments from the stack and push a result. Operations like @kbd{n} and
+@kbd{Q} (square root) pop a single number and push the result. You can
+think of them as simply operating on the top element of the stack.
+
+@smallexample
+@group
+1: 3 1: 9 2: 9 1: 25 1: 5
+ . . 1: 16 . .
+ .
+
+ 3 @key{RET} @key{RET} * 4 @key{RET} @key{RET} * + Q
+@end group
+@end smallexample
+
+@noindent
+(Note that capital @kbd{Q} means to hold down the Shift key while
+typing @kbd{q}. Remember, plain unshifted @kbd{q} is the Quit command.)
+
+@cindex Pythagorean Theorem
+Here we've used the Pythagorean Theorem to determine the hypotenuse of a
+right triangle. Calc actually has a built-in command for that called
+@kbd{f h}, but let's suppose we can't remember the necessary keystrokes.
+We can still enter it by its full name using @kbd{M-x} notation:
+
+@smallexample
+@group
+1: 3 2: 3 1: 5
+ . 1: 4 .
+ .
+
+ 3 @key{RET} 4 @key{RET} M-x calc-hypot
+@end group
+@end smallexample
+
+All Calculator commands begin with the word @samp{calc-}. Since it
+gets tiring to type this, Calc provides an @kbd{x} key which is just
+like the regular Emacs @kbd{M-x} key except that it types the @samp{calc-}
+prefix for you:
+
+@smallexample
+@group
+1: 3 2: 3 1: 5
+ . 1: 4 .
+ .
+
+ 3 @key{RET} 4 @key{RET} x hypot
+@end group
+@end smallexample
+
+What happens if you take the square root of a negative number?
+
+@smallexample
+@group
+1: 4 1: -4 1: (0, 2)
+ . . .
+
+ 4 @key{RET} n Q
+@end group
+@end smallexample
+
+@noindent
+The notation @expr{(a, b)} represents a complex number.
+Complex numbers are more traditionally written @expr{a + b i};
+Calc can display in this format, too, but for now we'll stick to the
+@expr{(a, b)} notation.
+
+If you don't know how complex numbers work, you can safely ignore this
+feature. Complex numbers only arise from operations that would be
+errors in a calculator that didn't have complex numbers. (For example,
+taking the square root or logarithm of a negative number produces a
+complex result.)
+
+Complex numbers are entered in the notation shown. The @kbd{(} and
+@kbd{,} and @kbd{)} keys manipulate ``incomplete complex numbers.''
+
+@smallexample
+@group
+1: ( ... 2: ( ... 1: (2, ... 1: (2, ... 1: (2, 3)
+ . 1: 2 . 3 .
+ . .
+
+ ( 2 , 3 )
+@end group
+@end smallexample
+
+You can perform calculations while entering parts of incomplete objects.
+However, an incomplete object cannot actually participate in a calculation:
+
+@smallexample
+@group
+1: ( ... 2: ( ... 3: ( ... 1: ( ... 1: ( ...
+ . 1: 2 2: 2 5 5
+ . 1: 3 . .
+ .
+ (error)
+ ( 2 @key{RET} 3 + +
+@end group
+@end smallexample
+
+@noindent
+Adding 5 to an incomplete object makes no sense, so the last command
+produces an error message and leaves the stack the same.
+
+Incomplete objects can't participate in arithmetic, but they can be
+moved around by the regular stack commands.
+
+@smallexample
+@group
+2: 2 3: 2 3: 3 1: ( ... 1: (2, 3)
+1: 3 2: 3 2: ( ... 2 .
+ . 1: ( ... 1: 2 3
+ . . .
+
+2 @key{RET} 3 @key{RET} ( M-@key{TAB} M-@key{TAB} )
+@end group
+@end smallexample
+
+@noindent
+Note that the @kbd{,} (comma) key did not have to be used here.
+When you press @kbd{)} all the stack entries between the incomplete
+entry and the top are collected, so there's never really a reason
+to use the comma. It's up to you.
+
+(@bullet{}) @strong{Exercise 4.} To enter the complex number @expr{(2, 3)},
+your friend Joe typed @kbd{( 2 , @key{SPC} 3 )}. What happened?
+(Joe thought of a clever way to correct his mistake in only two
+keystrokes, but it didn't quite work. Try it to find out why.)
+@xref{RPN Answer 4, 4}. (@bullet{})
+
+Vectors are entered the same way as complex numbers, but with square
+brackets in place of parentheses. We'll meet vectors again later in
+the tutorial.
+
+Any Emacs command can be given a @dfn{numeric prefix argument} by
+typing a series of @key{META}-digits beforehand. If @key{META} is
+awkward for you, you can instead type @kbd{C-u} followed by the
+necessary digits. Numeric prefix arguments can be negative, as in
+@kbd{M-- M-3 M-5} or @w{@kbd{C-u - 3 5}}. Calc commands use numeric
+prefix arguments in a variety of ways. For example, a numeric prefix
+on the @kbd{+} operator adds any number of stack entries at once:
+
+@smallexample
+@group
+1: 10 2: 10 3: 10 3: 10 1: 60
+ . 1: 20 2: 20 2: 20 .
+ . 1: 30 1: 30
+ . .
+
+ 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u 3 +
+@end group
+@end smallexample
+
+For stack manipulation commands like @key{RET}, a positive numeric
+prefix argument operates on the top @var{n} stack entries at once. A
+negative argument operates on the entry in level @var{n} only. An
+argument of zero operates on the entire stack. In this example, we copy
+the second-to-top element of the stack:
+
+@smallexample
+@group
+1: 10 2: 10 3: 10 3: 10 4: 10
+ . 1: 20 2: 20 2: 20 3: 20
+ . 1: 30 1: 30 2: 30
+ . . 1: 20
+ .
+
+ 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u -2 @key{RET}
+@end group
+@end smallexample
+
+@cindex Clearing the stack
+@cindex Emptying the stack
+Another common idiom is @kbd{M-0 @key{DEL}}, which clears the stack.
+(The @kbd{M-0} numeric prefix tells @key{DEL} to operate on the
+entire stack.)
+
+@node Algebraic Tutorial, Undo Tutorial, RPN Tutorial, Basic Tutorial
+@subsection Algebraic-Style Calculations
+
+@noindent
+If you are not used to RPN notation, you may prefer to operate the
+Calculator in Algebraic mode, which is closer to the way
+non-RPN calculators work. In Algebraic mode, you enter formulas
+in traditional @expr{2+3} notation.
+
+@strong{Warning:} Note that @samp{/} has lower precedence than
+@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}. See
+below for details.
+
+You don't really need any special ``mode'' to enter algebraic formulas.
+You can enter a formula at any time by pressing the apostrophe (@kbd{'})
+key. Answer the prompt with the desired formula, then press @key{RET}.
+The formula is evaluated and the result is pushed onto the RPN stack.
+If you don't want to think in RPN at all, you can enter your whole
+computation as a formula, read the result from the stack, then press
+@key{DEL} to delete it from the stack.
+
+Try pressing the apostrophe key, then @kbd{2+3+4}, then @key{RET}.
+The result should be the number 9.
+
+Algebraic formulas use the operators @samp{+}, @samp{-}, @samp{*},
+@samp{/}, and @samp{^}. You can use parentheses to make the order
+of evaluation clear. In the absence of parentheses, @samp{^} is
+evaluated first, then @samp{*}, then @samp{/}, then finally
+@samp{+} and @samp{-}. For example, the expression
+
+@example
+2 + 3*4*5 / 6*7^8 - 9
+@end example
+
+@noindent
+is equivalent to
+
+@example
+2 + ((3*4*5) / (6*(7^8)) - 9
+@end example
+
+@noindent
+or, in large mathematical notation,
+
+@ifnottex
+@example
+@group
+ 3 * 4 * 5
+2 + --------- - 9
+ 8
+ 6 * 7
+@end group
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ 2 + { 3 \times 4 \times 5 \over 6 \times 7^8 } - 9 $$
+\afterdisplay
+@end tex
+
+@noindent
+The result of this expression will be the number @mathit{-6.99999826533}.
+
+Calc's order of evaluation is the same as for most computer languages,
+except that @samp{*} binds more strongly than @samp{/}, as the above
+example shows. As in normal mathematical notation, the @samp{*} symbol
+can often be omitted: @samp{2 a} is the same as @samp{2*a}.
+
+Operators at the same level are evaluated from left to right, except
+that @samp{^} is evaluated from right to left. Thus, @samp{2-3-4} is
+equivalent to @samp{(2-3)-4} or @mathit{-5}, whereas @samp{2^3^4} is equivalent
+to @samp{2^(3^4)} (a very large integer; try it!).
+
+If you tire of typing the apostrophe all the time, there is
+Algebraic mode, where Calc automatically senses
+when you are about to type an algebraic expression. To enter this
+mode, press the two letters @w{@kbd{m a}}. (An @samp{Alg} indicator
+should appear in the Calc window's mode line.)
+
+Press @kbd{m a}, then @kbd{2+3+4} with no apostrophe, then @key{RET}.
+
+In Algebraic mode, when you press any key that would normally begin
+entering a number (such as a digit, a decimal point, or the @kbd{_}
+key), or if you press @kbd{(} or @kbd{[}, Calc automatically begins
+an algebraic entry.
+
+Functions which do not have operator symbols like @samp{+} and @samp{*}
+must be entered in formulas using function-call notation. For example,
+the function name corresponding to the square-root key @kbd{Q} is
+@code{sqrt}. To compute a square root in a formula, you would use
+the notation @samp{sqrt(@var{x})}.
+
+Press the apostrophe, then type @kbd{sqrt(5*2) - 3}. The result should
+be @expr{0.16227766017}.
+
+Note that if the formula begins with a function name, you need to use
+the apostrophe even if you are in Algebraic mode. If you type @kbd{arcsin}
+out of the blue, the @kbd{a r} will be taken as an Algebraic Rewrite
+command, and the @kbd{csin} will be taken as the name of the rewrite
+rule to use!
+
+Some people prefer to enter complex numbers and vectors in algebraic
+form because they find RPN entry with incomplete objects to be too
+distracting, even though they otherwise use Calc as an RPN calculator.
+
+Still in Algebraic mode, type:
+
+@smallexample
+@group
+1: (2, 3) 2: (2, 3) 1: (8, -1) 2: (8, -1) 1: (9, -1)
+ . 1: (1, -2) . 1: 1 .
+ . .
+
+ (2,3) @key{RET} (1,-2) @key{RET} * 1 @key{RET} +
+@end group
+@end smallexample
+
+Algebraic mode allows us to enter complex numbers without pressing
+an apostrophe first, but it also means we need to press @key{RET}
+after every entry, even for a simple number like @expr{1}.
+
+(You can type @kbd{C-u m a} to enable a special Incomplete Algebraic
+mode in which the @kbd{(} and @kbd{[} keys use algebraic entry even
+though regular numeric keys still use RPN numeric entry. There is also
+Total Algebraic mode, started by typing @kbd{m t}, in which all
+normal keys begin algebraic entry. You must then use the @key{META} key
+to type Calc commands: @kbd{M-m t} to get back out of Total Algebraic
+mode, @kbd{M-q} to quit, etc.)
+
+If you're still in Algebraic mode, press @kbd{m a} again to turn it off.
+
+Actual non-RPN calculators use a mixture of algebraic and RPN styles.
+In general, operators of two numbers (like @kbd{+} and @kbd{*})
+use algebraic form, but operators of one number (like @kbd{n} and @kbd{Q})
+use RPN form. Also, a non-RPN calculator allows you to see the
+intermediate results of a calculation as you go along. You can
+accomplish this in Calc by performing your calculation as a series
+of algebraic entries, using the @kbd{$} sign to tie them together.
+In an algebraic formula, @kbd{$} represents the number on the top
+of the stack. Here, we perform the calculation
+@texline @math{\sqrt{2\times4+1}},
+@infoline @expr{sqrt(2*4+1)},
+which on a traditional calculator would be done by pressing
+@kbd{2 * 4 + 1 =} and then the square-root key.
+
+@smallexample
+@group
+1: 8 1: 9 1: 3
+ . . .
+
+ ' 2*4 @key{RET} $+1 @key{RET} Q
+@end group
+@end smallexample
+
+@noindent
+Notice that we didn't need to press an apostrophe for the @kbd{$+1},
+because the dollar sign always begins an algebraic entry.
+
+(@bullet{}) @strong{Exercise 1.} How could you get the same effect as
+pressing @kbd{Q} but using an algebraic entry instead? How about
+if the @kbd{Q} key on your keyboard were broken?
+@xref{Algebraic Answer 1, 1}. (@bullet{})
+
+The notations @kbd{$$}, @kbd{$$$}, and so on stand for higher stack
+entries. For example, @kbd{' $$+$ @key{RET}} is just like typing @kbd{+}.
+
+Algebraic formulas can include @dfn{variables}. To store in a
+variable, press @kbd{s s}, then type the variable name, then press
+@key{RET}. (There are actually two flavors of store command:
+@kbd{s s} stores a number in a variable but also leaves the number
+on the stack, while @w{@kbd{s t}} removes a number from the stack and
+stores it in the variable.) A variable name should consist of one
+or more letters or digits, beginning with a letter.
+
+@smallexample
+@group
+1: 17 . 1: a + a^2 1: 306
+ . . .
+
+ 17 s t a @key{RET} ' a+a^2 @key{RET} =
+@end group
+@end smallexample
+
+@noindent
+The @kbd{=} key @dfn{evaluates} a formula by replacing all its
+variables by the values that were stored in them.
+
+For RPN calculations, you can recall a variable's value on the
+stack either by entering its name as a formula and pressing @kbd{=},
+or by using the @kbd{s r} command.
+
+@smallexample
+@group
+1: 17 2: 17 3: 17 2: 17 1: 306
+ . 1: 17 2: 17 1: 289 .
+ . 1: 2 .
+ .
+
+ s r a @key{RET} ' a @key{RET} = 2 ^ +
+@end group
+@end smallexample
+
+If you press a single digit for a variable name (as in @kbd{s t 3}, you
+get one of ten @dfn{quick variables} @code{q0} through @code{q9}.
+They are ``quick'' simply because you don't have to type the letter
+@code{q} or the @key{RET} after their names. In fact, you can type
+simply @kbd{s 3} as a shorthand for @kbd{s s 3}, and likewise for
+@kbd{t 3} and @w{@kbd{r 3}}.
+
+Any variables in an algebraic formula for which you have not stored
+values are left alone, even when you evaluate the formula.
+
+@smallexample
+@group
+1: 2 a + 2 b 1: 34 + 2 b
+ . .
+
+ ' 2a+2b @key{RET} =
+@end group
+@end smallexample
+
+Calls to function names which are undefined in Calc are also left
+alone, as are calls for which the value is undefined.
+
+@smallexample
+@group
+1: 2 + log10(0) + log10(x) + log10(5, 6) + foo(3)
+ .
+
+ ' log10(100) + log10(0) + log10(x) + log10(5,6) + foo(3) @key{RET}
+@end group
+@end smallexample
+
+@noindent
+In this example, the first call to @code{log10} works, but the other
+calls are not evaluated. In the second call, the logarithm is
+undefined for that value of the argument; in the third, the argument
+is symbolic, and in the fourth, there are too many arguments. In the
+fifth case, there is no function called @code{foo}. You will see a
+``Wrong number of arguments'' message referring to @samp{log10(5,6)}.
+Press the @kbd{w} (``why'') key to see any other messages that may
+have arisen from the last calculation. In this case you will get
+``logarithm of zero,'' then ``number expected: @code{x}''. Calc
+automatically displays the first message only if the message is
+sufficiently important; for example, Calc considers ``wrong number
+of arguments'' and ``logarithm of zero'' to be important enough to
+report automatically, while a message like ``number expected: @code{x}''
+will only show up if you explicitly press the @kbd{w} key.
+
+(@bullet{}) @strong{Exercise 2.} Joe entered the formula @samp{2 x y},
+stored 5 in @code{x}, pressed @kbd{=}, and got the expected result,
+@samp{10 y}. He then tried the same for the formula @samp{2 x (1+y)},
+expecting @samp{10 (1+y)}, but it didn't work. Why not?
+@xref{Algebraic Answer 2, 2}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 3.} What result would you expect
+@kbd{1 @key{RET} 0 /} to give? What if you then type @kbd{0 *}?
+@xref{Algebraic Answer 3, 3}. (@bullet{})
+
+One interesting way to work with variables is to use the
+@dfn{evaluates-to} (@samp{=>}) operator. It works like this:
+Enter a formula algebraically in the usual way, but follow
+the formula with an @samp{=>} symbol. (There is also an @kbd{s =}
+command which builds an @samp{=>} formula using the stack.) On
+the stack, you will see two copies of the formula with an @samp{=>}
+between them. The lefthand formula is exactly like you typed it;
+the righthand formula has been evaluated as if by typing @kbd{=}.
+
+@smallexample
+@group
+2: 2 + 3 => 5 2: 2 + 3 => 5
+1: 2 a + 2 b => 34 + 2 b 1: 2 a + 2 b => 20 + 2 b
+ . .
+
+' 2+3 => @key{RET} ' 2a+2b @key{RET} s = 10 s t a @key{RET}
+@end group
+@end smallexample
+
+@noindent
+Notice that the instant we stored a new value in @code{a}, all
+@samp{=>} operators already on the stack that referred to @expr{a}
+were updated to use the new value. With @samp{=>}, you can push a
+set of formulas on the stack, then change the variables experimentally
+to see the effects on the formulas' values.
+
+You can also ``unstore'' a variable when you are through with it:
+
+@smallexample
+@group
+2: 2 + 5 => 5
+1: 2 a + 2 b => 2 a + 2 b
+ .
+
+ s u a @key{RET}
+@end group
+@end smallexample
+
+We will encounter formulas involving variables and functions again
+when we discuss the algebra and calculus features of the Calculator.
+
+@node Undo Tutorial, Modes Tutorial, Algebraic Tutorial, Basic Tutorial
+@subsection Undo and Redo
+
+@noindent
+If you make a mistake, you can usually correct it by pressing shift-@kbd{U},
+the ``undo'' command. First, clear the stack (@kbd{M-0 @key{DEL}}) and exit
+and restart Calc (@kbd{C-x * * C-x * *}) to make sure things start off
+with a clean slate. Now:
+
+@smallexample
+@group
+1: 2 2: 2 1: 8 2: 2 1: 6
+ . 1: 3 . 1: 3 .
+ . .
+
+ 2 @key{RET} 3 ^ U *
+@end group
+@end smallexample
+
+You can undo any number of times. Calc keeps a complete record of
+all you have done since you last opened the Calc window. After the
+above example, you could type:
+
+@smallexample
+@group
+1: 6 2: 2 1: 2 . .
+ . 1: 3 .
+ .
+ (error)
+ U U U U
+@end group
+@end smallexample
+
+You can also type @kbd{D} to ``redo'' a command that you have undone
+mistakenly.
+
+@smallexample
+@group
+ . 1: 2 2: 2 1: 6 1: 6
+ . 1: 3 . .
+ .
+ (error)
+ D D D D
+@end group
+@end smallexample
+
+@noindent
+It was not possible to redo past the @expr{6}, since that was placed there
+by something other than an undo command.
+
+@cindex Time travel
+You can think of undo and redo as a sort of ``time machine.'' Press
+@kbd{U} to go backward in time, @kbd{D} to go forward. If you go
+backward and do something (like @kbd{*}) then, as any science fiction
+reader knows, you have changed your future and you cannot go forward
+again. Thus, the inability to redo past the @expr{6} even though there
+was an earlier undo command.
+
+You can always recall an earlier result using the Trail. We've ignored
+the trail so far, but it has been faithfully recording everything we
+did since we loaded the Calculator. If the Trail is not displayed,
+press @kbd{t d} now to turn it on.
+
+Let's try grabbing an earlier result. The @expr{8} we computed was
+undone by a @kbd{U} command, and was lost even to Redo when we pressed
+@kbd{*}, but it's still there in the trail. There should be a little
+@samp{>} arrow (the @dfn{trail pointer}) resting on the last trail
+entry. If there isn't, press @kbd{t ]} to reset the trail pointer.
+Now, press @w{@kbd{t p}} to move the arrow onto the line containing
+@expr{8}, and press @w{@kbd{t y}} to ``yank'' that number back onto the
+stack.
+
+If you press @kbd{t ]} again, you will see that even our Yank command
+went into the trail.
+
+Let's go further back in time. Earlier in the tutorial we computed
+a huge integer using the formula @samp{2^3^4}. We don't remember
+what it was, but the first digits were ``241''. Press @kbd{t r}
+(which stands for trail-search-reverse), then type @kbd{241}.
+The trail cursor will jump back to the next previous occurrence of
+the string ``241'' in the trail. This is just a regular Emacs
+incremental search; you can now press @kbd{C-s} or @kbd{C-r} to
+continue the search forwards or backwards as you like.
+
+To finish the search, press @key{RET}. This halts the incremental
+search and leaves the trail pointer at the thing we found. Now we
+can type @kbd{t y} to yank that number onto the stack. If we hadn't
+remembered the ``241'', we could simply have searched for @kbd{2^3^4},
+then pressed @kbd{@key{RET} t n} to halt and then move to the next item.
+
+You may have noticed that all the trail-related commands begin with
+the letter @kbd{t}. (The store-and-recall commands, on the other hand,
+all began with @kbd{s}.) Calc has so many commands that there aren't
+enough keys for all of them, so various commands are grouped into
+two-letter sequences where the first letter is called the @dfn{prefix}
+key. If you type a prefix key by accident, you can press @kbd{C-g}
+to cancel it. (In fact, you can press @kbd{C-g} to cancel almost
+anything in Emacs.) To get help on a prefix key, press that key
+followed by @kbd{?}. Some prefixes have several lines of help,
+so you need to press @kbd{?} repeatedly to see them all.
+You can also type @kbd{h h} to see all the help at once.
+
+Try pressing @kbd{t ?} now. You will see a line of the form,
+
+@smallexample
+trail/time: Display; Fwd, Back; Next, Prev, Here, [, ]; Yank: [MORE] t-
+@end smallexample
+
+@noindent
+The word ``trail'' indicates that the @kbd{t} prefix key contains
+trail-related commands. Each entry on the line shows one command,
+with a single capital letter showing which letter you press to get
+that command. We have used @kbd{t n}, @kbd{t p}, @kbd{t ]}, and
+@kbd{t y} so far. The @samp{[MORE]} means you can press @kbd{?}
+again to see more @kbd{t}-prefix commands. Notice that the commands
+are roughly divided (by semicolons) into related groups.
+
+When you are in the help display for a prefix key, the prefix is
+still active. If you press another key, like @kbd{y} for example,
+it will be interpreted as a @kbd{t y} command. If all you wanted
+was to look at the help messages, press @kbd{C-g} afterwards to cancel
+the prefix.
+
+One more way to correct an error is by editing the stack entries.
+The actual Stack buffer is marked read-only and must not be edited
+directly, but you can press @kbd{`} (the backquote or accent grave)
+to edit a stack entry.
+
+Try entering @samp{3.141439} now. If this is supposed to represent
+@cpi{}, it's got several errors. Press @kbd{`} to edit this number.
+Now use the normal Emacs cursor motion and editing keys to change
+the second 4 to a 5, and to transpose the 3 and the 9. When you
+press @key{RET}, the number on the stack will be replaced by your
+new number. This works for formulas, vectors, and all other types
+of values you can put on the stack. The @kbd{`} key also works
+during entry of a number or algebraic formula.
+
+@node Modes Tutorial, , Undo Tutorial, Basic Tutorial
+@subsection Mode-Setting Commands
+
+@noindent
+Calc has many types of @dfn{modes} that affect the way it interprets
+your commands or the way it displays data. We have already seen one
+mode, namely Algebraic mode. There are many others, too; we'll
+try some of the most common ones here.
+
+Perhaps the most fundamental mode in Calc is the current @dfn{precision}.
+Notice the @samp{12} on the Calc window's mode line:
+
+@smallexample
+--%%-Calc: 12 Deg (Calculator)----All------
+@end smallexample
+
+@noindent
+Most of the symbols there are Emacs things you don't need to worry
+about, but the @samp{12} and the @samp{Deg} are mode indicators.
+The @samp{12} means that calculations should always be carried to
+12 significant figures. That is why, when we type @kbd{1 @key{RET} 7 /},
+we get @expr{0.142857142857} with exactly 12 digits, not counting
+leading and trailing zeros.
+
+You can set the precision to anything you like by pressing @kbd{p},
+then entering a suitable number. Try pressing @kbd{p 30 @key{RET}},
+then doing @kbd{1 @key{RET} 7 /} again:
+
+@smallexample
+@group
+1: 0.142857142857
+2: 0.142857142857142857142857142857
+ .
+@end group
+@end smallexample
+
+Although the precision can be set arbitrarily high, Calc always
+has to have @emph{some} value for the current precision. After
+all, the true value @expr{1/7} is an infinitely repeating decimal;
+Calc has to stop somewhere.
+
+Of course, calculations are slower the more digits you request.
+Press @w{@kbd{p 12}} now to set the precision back down to the default.
+
+Calculations always use the current precision. For example, even
+though we have a 30-digit value for @expr{1/7} on the stack, if
+we use it in a calculation in 12-digit mode it will be rounded
+down to 12 digits before it is used. Try it; press @key{RET} to
+duplicate the number, then @w{@kbd{1 +}}. Notice that the @key{RET}
+key didn't round the number, because it doesn't do any calculation.
+But the instant we pressed @kbd{+}, the number was rounded down.
+
+@smallexample
+@group
+1: 0.142857142857
+2: 0.142857142857142857142857142857
+3: 1.14285714286
+ .
+@end group
+@end smallexample
+
+@noindent
+In fact, since we added a digit on the left, we had to lose one
+digit on the right from even the 12-digit value of @expr{1/7}.
+
+How did we get more than 12 digits when we computed @samp{2^3^4}? The
+answer is that Calc makes a distinction between @dfn{integers} and
+@dfn{floating-point} numbers, or @dfn{floats}. An integer is a number
+that does not contain a decimal point. There is no such thing as an
+``infinitely repeating fraction integer,'' so Calc doesn't have to limit
+itself. If you asked for @samp{2^10000} (don't try this!), you would
+have to wait a long time but you would eventually get an exact answer.
+If you ask for @samp{2.^10000}, you will quickly get an answer which is
+correct only to 12 places. The decimal point tells Calc that it should
+use floating-point arithmetic to get the answer, not exact integer
+arithmetic.
+
+You can use the @kbd{F} (@code{calc-floor}) command to convert a
+floating-point value to an integer, and @kbd{c f} (@code{calc-float})
+to convert an integer to floating-point form.
+
+Let's try entering that last calculation:
+
+@smallexample
+@group
+1: 2. 2: 2. 1: 1.99506311689e3010
+ . 1: 10000 .
+ .
+
+ 2.0 @key{RET} 10000 @key{RET} ^
+@end group
+@end smallexample
+
+@noindent
+@cindex Scientific notation, entry of
+Notice the letter @samp{e} in there. It represents ``times ten to the
+power of,'' and is used by Calc automatically whenever writing the
+number out fully would introduce more extra zeros than you probably
+want to see. You can enter numbers in this notation, too.
+
+@smallexample
+@group
+1: 2. 2: 2. 1: 1.99506311678e3010
+ . 1: 10000. .
+ .
+
+ 2.0 @key{RET} 1e4 @key{RET} ^
+@end group
+@end smallexample
+
+@cindex Round-off errors
+@noindent
+Hey, the answer is different! Look closely at the middle columns
+of the two examples. In the first, the stack contained the
+exact integer @expr{10000}, but in the second it contained
+a floating-point value with a decimal point. When you raise a
+number to an integer power, Calc uses repeated squaring and
+multiplication to get the answer. When you use a floating-point
+power, Calc uses logarithms and exponentials. As you can see,
+a slight error crept in during one of these methods. Which
+one should we trust? Let's raise the precision a bit and find
+out:
+
+@smallexample
+@group
+ . 1: 2. 2: 2. 1: 1.995063116880828e3010
+ . 1: 10000. .
+ .
+
+ p 16 @key{RET} 2. @key{RET} 1e4 ^ p 12 @key{RET}
+@end group
+@end smallexample
+
+@noindent
+@cindex Guard digits
+Presumably, it doesn't matter whether we do this higher-precision
+calculation using an integer or floating-point power, since we
+have added enough ``guard digits'' to trust the first 12 digits
+no matter what. And the verdict is@dots{} Integer powers were more
+accurate; in fact, the result was only off by one unit in the
+last place.
+
+@cindex Guard digits
+Calc does many of its internal calculations to a slightly higher
+precision, but it doesn't always bump the precision up enough.
+In each case, Calc added about two digits of precision during
+its calculation and then rounded back down to 12 digits
+afterward. In one case, it was enough; in the other, it
+wasn't. If you really need @var{x} digits of precision, it
+never hurts to do the calculation with a few extra guard digits.
+
+What if we want guard digits but don't want to look at them?
+We can set the @dfn{float format}. Calc supports four major
+formats for floating-point numbers, called @dfn{normal},
+@dfn{fixed-point}, @dfn{scientific notation}, and @dfn{engineering
+notation}. You get them by pressing @w{@kbd{d n}}, @kbd{d f},
+@kbd{d s}, and @kbd{d e}, respectively. In each case, you can
+supply a numeric prefix argument which says how many digits
+should be displayed. As an example, let's put a few numbers
+onto the stack and try some different display modes. First,
+use @kbd{M-0 @key{DEL}} to clear the stack, then enter the four
+numbers shown here:
+
+@smallexample
+@group
+4: 12345 4: 12345 4: 12345 4: 12345 4: 12345
+3: 12345. 3: 12300. 3: 1.2345e4 3: 1.23e4 3: 12345.000
+2: 123.45 2: 123. 2: 1.2345e2 2: 1.23e2 2: 123.450
+1: 12.345 1: 12.3 1: 1.2345e1 1: 1.23e1 1: 12.345
+ . . . . .
+
+ d n M-3 d n d s M-3 d s M-3 d f
+@end group
+@end smallexample
+
+@noindent
+Notice that when we typed @kbd{M-3 d n}, the numbers were rounded down
+to three significant digits, but then when we typed @kbd{d s} all
+five significant figures reappeared. The float format does not
+affect how numbers are stored, it only affects how they are
+displayed. Only the current precision governs the actual rounding
+of numbers in the Calculator's memory.
+
+Engineering notation, not shown here, is like scientific notation
+except the exponent (the power-of-ten part) is always adjusted to be
+a multiple of three (as in ``kilo,'' ``micro,'' etc.). As a result
+there will be one, two, or three digits before the decimal point.
+
+Whenever you change a display-related mode, Calc redraws everything
+in the stack. This may be slow if there are many things on the stack,
+so Calc allows you to type shift-@kbd{H} before any mode command to
+prevent it from updating the stack. Anything Calc displays after the
+mode-changing command will appear in the new format.
+
+@smallexample
+@group
+4: 12345 4: 12345 4: 12345 4: 12345 4: 12345
+3: 12345.000 3: 12345.000 3: 12345.000 3: 1.2345e4 3: 12345.
+2: 123.450 2: 123.450 2: 1.2345e1 2: 1.2345e1 2: 123.45
+1: 12.345 1: 1.2345e1 1: 1.2345e2 1: 1.2345e2 1: 12.345
+ . . . . .
+
+ H d s @key{DEL} U @key{TAB} d @key{SPC} d n
+@end group
+@end smallexample
+
+@noindent
+Here the @kbd{H d s} command changes to scientific notation but without
+updating the screen. Deleting the top stack entry and undoing it back
+causes it to show up in the new format; swapping the top two stack
+entries reformats both entries. The @kbd{d @key{SPC}} command refreshes the
+whole stack. The @kbd{d n} command changes back to the normal float
+format; since it doesn't have an @kbd{H} prefix, it also updates all
+the stack entries to be in @kbd{d n} format.
+
+Notice that the integer @expr{12345} was not affected by any
+of the float formats. Integers are integers, and are always
+displayed exactly.
+
+@cindex Large numbers, readability
+Large integers have their own problems. Let's look back at
+the result of @kbd{2^3^4}.
+
+@example
+2417851639229258349412352
+@end example
+
+@noindent
+Quick---how many digits does this have? Try typing @kbd{d g}:
+
+@example
+2,417,851,639,229,258,349,412,352
+@end example
+
+@noindent
+Now how many digits does this have? It's much easier to tell!
+We can actually group digits into clumps of any size. Some
+people prefer @kbd{M-5 d g}:
+
+@example
+24178,51639,22925,83494,12352
+@end example
+
+Let's see what happens to floating-point numbers when they are grouped.
+First, type @kbd{p 25 @key{RET}} to make sure we have enough precision
+to get ourselves into trouble. Now, type @kbd{1e13 /}:
+
+@example
+24,17851,63922.9258349412352
+@end example
+
+@noindent
+The integer part is grouped but the fractional part isn't. Now try
+@kbd{M-- M-5 d g} (that's meta-minus-sign, meta-five):
+
+@example
+24,17851,63922.92583,49412,352
+@end example
+
+If you find it hard to tell the decimal point from the commas, try
+changing the grouping character to a space with @kbd{d , @key{SPC}}:
+
+@example
+24 17851 63922.92583 49412 352
+@end example
+
+Type @kbd{d , ,} to restore the normal grouping character, then
+@kbd{d g} again to turn grouping off. Also, press @kbd{p 12} to
+restore the default precision.
+
+Press @kbd{U} enough times to get the original big integer back.
+(Notice that @kbd{U} does not undo each mode-setting command; if
+you want to undo a mode-setting command, you have to do it yourself.)
+Now, type @kbd{d r 16 @key{RET}}:
+
+@example
+16#200000000000000000000
+@end example
+
+@noindent
+The number is now displayed in @dfn{hexadecimal}, or ``base-16'' form.
+Suddenly it looks pretty simple; this should be no surprise, since we
+got this number by computing a power of two, and 16 is a power of 2.
+In fact, we can use @w{@kbd{d r 2 @key{RET}}} to see it in actual binary
+form:
+
+@example
+2#1000000000000000000000000000000000000000000000000000000 @dots{}
+@end example
+
+@noindent
+We don't have enough space here to show all the zeros! They won't
+fit on a typical screen, either, so you will have to use horizontal
+scrolling to see them all. Press @kbd{<} and @kbd{>} to scroll the
+stack window left and right by half its width. Another way to view
+something large is to press @kbd{`} (back-quote) to edit the top of
+stack in a separate window. (Press @kbd{C-c C-c} when you are done.)
+
+You can enter non-decimal numbers using the @kbd{#} symbol, too.
+Let's see what the hexadecimal number @samp{5FE} looks like in
+binary. Type @kbd{16#5FE} (the letters can be typed in upper or
+lower case; they will always appear in upper case). It will also
+help to turn grouping on with @kbd{d g}:
+
+@example
+2#101,1111,1110
+@end example
+
+Notice that @kbd{d g} groups by fours by default if the display radix
+is binary or hexadecimal, but by threes if it is decimal, octal, or any
+other radix.
+
+Now let's see that number in decimal; type @kbd{d r 10}:
+
+@example
+1,534
+@end example
+
+Numbers are not @emph{stored} with any particular radix attached. They're
+just numbers; they can be entered in any radix, and are always displayed
+in whatever radix you've chosen with @kbd{d r}. The current radix applies
+to integers, fractions, and floats.
+
+@cindex Roundoff errors, in non-decimal numbers
+(@bullet{}) @strong{Exercise 1.} Your friend Joe tried to enter one-third
+as @samp{3#0.1} in @kbd{d r 3} mode with a precision of 12. He got
+@samp{3#0.0222222...} (with 25 2's) in the display. When he multiplied
+that by three, he got @samp{3#0.222222...} instead of the expected
+@samp{3#1}. Next, Joe entered @samp{3#0.2} and, to his great relief,
+saw @samp{3#0.2} on the screen. But when he typed @kbd{2 /}, he got
+@samp{3#0.10000001} (some zeros omitted). What's going on here?
+@xref{Modes Answer 1, 1}. (@bullet{})
+
+@cindex Scientific notation, in non-decimal numbers
+(@bullet{}) @strong{Exercise 2.} Scientific notation works in non-decimal
+modes in the natural way (the exponent is a power of the radix instead of
+a power of ten, although the exponent itself is always written in decimal).
+Thus @samp{8#1.23e3 = 8#1230.0}. Suppose we have the hexadecimal number
+@samp{f.e8f} times 16 to the 15th power: We write @samp{16#f.e8fe15}.
+What is wrong with this picture? What could we write instead that would
+work better? @xref{Modes Answer 2, 2}. (@bullet{})
+
+The @kbd{m} prefix key has another set of modes, relating to the way
+Calc interprets your inputs and does computations. Whereas @kbd{d}-prefix
+modes generally affect the way things look, @kbd{m}-prefix modes affect
+the way they are actually computed.
+
+The most popular @kbd{m}-prefix mode is the @dfn{angular mode}. Notice
+the @samp{Deg} indicator in the mode line. This means that if you use
+a command that interprets a number as an angle, it will assume the
+angle is measured in degrees. For example,
+
+@smallexample
+@group
+1: 45 1: 0.707106781187 1: 0.500000000001 1: 0.5
+ . . . .
+
+ 45 S 2 ^ c 1
+@end group
+@end smallexample
+
+@noindent
+The shift-@kbd{S} command computes the sine of an angle. The sine
+of 45 degrees is
+@texline @math{\sqrt{2}/2};
+@infoline @expr{sqrt(2)/2};
+squaring this yields @expr{2/4 = 0.5}. However, there has been a slight
+roundoff error because the representation of
+@texline @math{\sqrt{2}/2}
+@infoline @expr{sqrt(2)/2}
+wasn't exact. The @kbd{c 1} command is a handy way to clean up numbers
+in this case; it temporarily reduces the precision by one digit while it
+re-rounds the number on the top of the stack.
+
+@cindex Roundoff errors, examples
+(@bullet{}) @strong{Exercise 3.} Your friend Joe computed the sine
+of 45 degrees as shown above, then, hoping to avoid an inexact
+result, he increased the precision to 16 digits before squaring.
+What happened? @xref{Modes Answer 3, 3}. (@bullet{})
+
+To do this calculation in radians, we would type @kbd{m r} first.
+(The indicator changes to @samp{Rad}.) 45 degrees corresponds to
+@cpiover{4} radians. To get @cpi{}, press the @kbd{P} key. (Once
+again, this is a shifted capital @kbd{P}. Remember, unshifted
+@kbd{p} sets the precision.)
+
+@smallexample
+@group
+1: 3.14159265359 1: 0.785398163398 1: 0.707106781187
+ . . .
+
+ P 4 / m r S
+@end group
+@end smallexample
+
+Likewise, inverse trigonometric functions generate results in
+either radians or degrees, depending on the current angular mode.
+
+@smallexample
+@group
+1: 0.707106781187 1: 0.785398163398 1: 45.
+ . . .
+
+ .5 Q m r I S m d U I S
+@end group
+@end smallexample
+
+@noindent
+Here we compute the Inverse Sine of
+@texline @math{\sqrt{0.5}},
+@infoline @expr{sqrt(0.5)},
+first in radians, then in degrees.
+
+Use @kbd{c d} and @kbd{c r} to convert a number from radians to degrees
+and vice-versa.
+
+@smallexample
+@group
+1: 45 1: 0.785398163397 1: 45.
+ . . .
+
+ 45 c r c d
+@end group
+@end smallexample
+
+Another interesting mode is @dfn{Fraction mode}. Normally,
+dividing two integers produces a floating-point result if the
+quotient can't be expressed as an exact integer. Fraction mode
+causes integer division to produce a fraction, i.e., a rational
+number, instead.
+
+@smallexample
+@group
+2: 12 1: 1.33333333333 1: 4:3
+1: 9 . .
+ .
+
+ 12 @key{RET} 9 / m f U / m f
+@end group
+@end smallexample
+
+@noindent
+In the first case, we get an approximate floating-point result.
+In the second case, we get an exact fractional result (four-thirds).
+
+You can enter a fraction at any time using @kbd{:} notation.
+(Calc uses @kbd{:} instead of @kbd{/} as the fraction separator
+because @kbd{/} is already used to divide the top two stack
+elements.) Calculations involving fractions will always
+produce exact fractional results; Fraction mode only says
+what to do when dividing two integers.
+
+@cindex Fractions vs. floats
+@cindex Floats vs. fractions
+(@bullet{}) @strong{Exercise 4.} If fractional arithmetic is exact,
+why would you ever use floating-point numbers instead?
+@xref{Modes Answer 4, 4}. (@bullet{})
+
+Typing @kbd{m f} doesn't change any existing values in the stack.
+In the above example, we had to Undo the division and do it over
+again when we changed to Fraction mode. But if you use the
+evaluates-to operator you can get commands like @kbd{m f} to
+recompute for you.
+
+@smallexample
+@group
+1: 12 / 9 => 1.33333333333 1: 12 / 9 => 1.333 1: 12 / 9 => 4:3
+ . . .
+
+ ' 12/9 => @key{RET} p 4 @key{RET} m f
+@end group
+@end smallexample
+
+@noindent
+In this example, the righthand side of the @samp{=>} operator
+on the stack is recomputed when we change the precision, then
+again when we change to Fraction mode. All @samp{=>} expressions
+on the stack are recomputed every time you change any mode that
+might affect their values.
+
+@node Arithmetic Tutorial, Vector/Matrix Tutorial, Basic Tutorial, Tutorial
+@section Arithmetic Tutorial
+
+@noindent
+In this section, we explore the arithmetic and scientific functions
+available in the Calculator.
+
+The standard arithmetic commands are @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/},
+and @kbd{^}. Each normally takes two numbers from the top of the stack
+and pushes back a result. The @kbd{n} and @kbd{&} keys perform
+change-sign and reciprocal operations, respectively.
+
+@smallexample
+@group
+1: 5 1: 0.2 1: 5. 1: -5. 1: 5.
+ . . . . .
+
+ 5 & & n n
+@end group
+@end smallexample
+
+@cindex Binary operators
+You can apply a ``binary operator'' like @kbd{+} across any number of
+stack entries by giving it a numeric prefix. You can also apply it
+pairwise to several stack elements along with the top one if you use
+a negative prefix.
+
+@smallexample
+@group
+3: 2 1: 9 3: 2 4: 2 3: 12
+2: 3 . 2: 3 3: 3 2: 13
+1: 4 1: 4 2: 4 1: 14
+ . . 1: 10 .
+ .
+
+2 @key{RET} 3 @key{RET} 4 M-3 + U 10 M-- M-3 +
+@end group
+@end smallexample
+
+@cindex Unary operators
+You can apply a ``unary operator'' like @kbd{&} to the top @var{n}
+stack entries with a numeric prefix, too.
+
+@smallexample
+@group
+3: 2 3: 0.5 3: 0.5
+2: 3 2: 0.333333333333 2: 3.
+1: 4 1: 0.25 1: 4.
+ . . .
+
+2 @key{RET} 3 @key{RET} 4 M-3 & M-2 &
+@end group
+@end smallexample
+
+Notice that the results here are left in floating-point form.
+We can convert them back to integers by pressing @kbd{F}, the
+``floor'' function. This function rounds down to the next lower
+integer. There is also @kbd{R}, which rounds to the nearest
+integer.
+
+@smallexample
+@group
+7: 2. 7: 2 7: 2
+6: 2.4 6: 2 6: 2
+5: 2.5 5: 2 5: 3
+4: 2.6 4: 2 4: 3
+3: -2. 3: -2 3: -2
+2: -2.4 2: -3 2: -2
+1: -2.6 1: -3 1: -3
+ . . .
+
+ M-7 F U M-7 R
+@end group
+@end smallexample
+
+Since dividing-and-flooring (i.e., ``integer quotient'') is such a
+common operation, Calc provides a special command for that purpose, the
+backslash @kbd{\}. Another common arithmetic operator is @kbd{%}, which
+computes the remainder that would arise from a @kbd{\} operation, i.e.,
+the ``modulo'' of two numbers. For example,
+
+@smallexample
+@group
+2: 1234 1: 12 2: 1234 1: 34
+1: 100 . 1: 100 .
+ . .
+
+1234 @key{RET} 100 \ U %
+@end group
+@end smallexample
+
+These commands actually work for any real numbers, not just integers.
+
+@smallexample
+@group
+2: 3.1415 1: 3 2: 3.1415 1: 0.1415
+1: 1 . 1: 1 .
+ . .
+
+3.1415 @key{RET} 1 \ U %
+@end group
+@end smallexample
+
+(@bullet{}) @strong{Exercise 1.} The @kbd{\} command would appear to be a
+frill, since you could always do the same thing with @kbd{/ F}. Think
+of a situation where this is not true---@kbd{/ F} would be inadequate.
+Now think of a way you could get around the problem if Calc didn't
+provide a @kbd{\} command. @xref{Arithmetic Answer 1, 1}. (@bullet{})
+
+We've already seen the @kbd{Q} (square root) and @kbd{S} (sine)
+commands. Other commands along those lines are @kbd{C} (cosine),
+@kbd{T} (tangent), @kbd{E} (@expr{e^x}) and @kbd{L} (natural
+logarithm). These can be modified by the @kbd{I} (inverse) and
+@kbd{H} (hyperbolic) prefix keys.
+
+Let's compute the sine and cosine of an angle, and verify the
+identity
+@texline @math{\sin^2x + \cos^2x = 1}.
+@infoline @expr{sin(x)^2 + cos(x)^2 = 1}.
+We'll arbitrarily pick @mathit{-64} degrees as a good value for @expr{x}.
+With the angular mode set to degrees (type @w{@kbd{m d}}), do:
+
+@smallexample
+@group
+2: -64 2: -64 2: -0.89879 2: -0.89879 1: 1.
+1: -64 1: -0.89879 1: -64 1: 0.43837 .
+ . . . .
+
+ 64 n @key{RET} @key{RET} S @key{TAB} C f h
+@end group
+@end smallexample
+
+@noindent
+(For brevity, we're showing only five digits of the results here.
+You can of course do these calculations to any precision you like.)
+
+Remember, @kbd{f h} is the @code{calc-hypot}, or square-root of sum
+of squares, command.
+
+Another identity is
+@texline @math{\displaystyle\tan x = {\sin x \over \cos x}}.
+@infoline @expr{tan(x) = sin(x) / cos(x)}.
+@smallexample
+@group
+
+2: -0.89879 1: -2.0503 1: -64.
+1: 0.43837 . .
+ .
+
+ U / I T
+@end group
+@end smallexample
+
+A physical interpretation of this calculation is that if you move
+@expr{0.89879} units downward and @expr{0.43837} units to the right,
+your direction of motion is @mathit{-64} degrees from horizontal. Suppose
+we move in the opposite direction, up and to the left:
+
+@smallexample
+@group
+2: -0.89879 2: 0.89879 1: -2.0503 1: -64.
+1: 0.43837 1: -0.43837 . .
+ . .
+
+ U U M-2 n / I T
+@end group
+@end smallexample
+
+@noindent
+How can the angle be the same? The answer is that the @kbd{/} operation
+loses information about the signs of its inputs. Because the quotient
+is negative, we know exactly one of the inputs was negative, but we
+can't tell which one. There is an @kbd{f T} [@code{arctan2}] function which
+computes the inverse tangent of the quotient of a pair of numbers.
+Since you feed it the two original numbers, it has enough information
+to give you a full 360-degree answer.
+
+@smallexample
+@group
+2: 0.89879 1: 116. 3: 116. 2: 116. 1: 180.
+1: -0.43837 . 2: -0.89879 1: -64. .
+ . 1: 0.43837 .
+ .
+
+ U U f T M-@key{RET} M-2 n f T -
+@end group
+@end smallexample
+
+@noindent
+The resulting angles differ by 180 degrees; in other words, they
+point in opposite directions, just as we would expect.
+
+The @key{META}-@key{RET} we used in the third step is the
+``last-arguments'' command. It is sort of like Undo, except that it
+restores the arguments of the last command to the stack without removing
+the command's result. It is useful in situations like this one,
+where we need to do several operations on the same inputs. We could
+have accomplished the same thing by using @kbd{M-2 @key{RET}} to duplicate
+the top two stack elements right after the @kbd{U U}, then a pair of
+@kbd{M-@key{TAB}} commands to cycle the 116 up around the duplicates.
+
+A similar identity is supposed to hold for hyperbolic sines and cosines,
+except that it is the @emph{difference}
+@texline @math{\cosh^2x - \sinh^2x}
+@infoline @expr{cosh(x)^2 - sinh(x)^2}
+that always equals one. Let's try to verify this identity.
+
+@smallexample
+@group
+2: -64 2: -64 2: -64 2: 9.7192e54 2: 9.7192e54
+1: -64 1: -3.1175e27 1: 9.7192e54 1: -64 1: 9.7192e54
+ . . . . .
+
+ 64 n @key{RET} @key{RET} H C 2 ^ @key{TAB} H S 2 ^
+@end group
+@end smallexample
+
+@noindent
+@cindex Roundoff errors, examples
+Something's obviously wrong, because when we subtract these numbers
+the answer will clearly be zero! But if you think about it, if these
+numbers @emph{did} differ by one, it would be in the 55th decimal
+place. The difference we seek has been lost entirely to roundoff
+error.
+
+We could verify this hypothesis by doing the actual calculation with,
+say, 60 decimal places of precision. This will be slow, but not
+enormously so. Try it if you wish; sure enough, the answer is
+0.99999, reasonably close to 1.
+
+Of course, a more reasonable way to verify the identity is to use
+a more reasonable value for @expr{x}!
+
+@cindex Common logarithm
+Some Calculator commands use the Hyperbolic prefix for other purposes.
+The logarithm and exponential functions, for example, work to the base
+@expr{e} normally but use base-10 instead if you use the Hyperbolic
+prefix.
+
+@smallexample
+@group
+1: 1000 1: 6.9077 1: 1000 1: 3
+ . . . .
+
+ 1000 L U H L
+@end group
+@end smallexample
+
+@noindent
+First, we mistakenly compute a natural logarithm. Then we undo
+and compute a common logarithm instead.
+
+The @kbd{B} key computes a general base-@var{b} logarithm for any
+value of @var{b}.
+
+@smallexample
+@group
+2: 1000 1: 3 1: 1000. 2: 1000. 1: 6.9077
+1: 10 . . 1: 2.71828 .
+ . .
+
+ 1000 @key{RET} 10 B H E H P B
+@end group
+@end smallexample
+
+@noindent
+Here we first use @kbd{B} to compute the base-10 logarithm, then use
+the ``hyperbolic'' exponential as a cheap hack to recover the number
+1000, then use @kbd{B} again to compute the natural logarithm. Note
+that @kbd{P} with the hyperbolic prefix pushes the constant @expr{e}
+onto the stack.
+
+You may have noticed that both times we took the base-10 logarithm
+of 1000, we got an exact integer result. Calc always tries to give
+an exact rational result for calculations involving rational numbers
+where possible. But when we used @kbd{H E}, the result was a
+floating-point number for no apparent reason. In fact, if we had
+computed @kbd{10 @key{RET} 3 ^} we @emph{would} have gotten an
+exact integer 1000. But the @kbd{H E} command is rigged to generate
+a floating-point result all of the time so that @kbd{1000 H E} will
+not waste time computing a thousand-digit integer when all you
+probably wanted was @samp{1e1000}.
+
+(@bullet{}) @strong{Exercise 2.} Find a pair of integer inputs to
+the @kbd{B} command for which Calc could find an exact rational
+result but doesn't. @xref{Arithmetic Answer 2, 2}. (@bullet{})
+
+The Calculator also has a set of functions relating to combinatorics
+and statistics. You may be familiar with the @dfn{factorial} function,
+which computes the product of all the integers up to a given number.
+
+@smallexample
+@group
+1: 100 1: 93326215443... 1: 100. 1: 9.3326e157
+ . . . .
+
+ 100 ! U c f !
+@end group
+@end smallexample
+
+@noindent
+Recall, the @kbd{c f} command converts the integer or fraction at the
+top of the stack to floating-point format. If you take the factorial
+of a floating-point number, you get a floating-point result
+accurate to the current precision. But if you give @kbd{!} an
+exact integer, you get an exact integer result (158 digits long
+in this case).
+
+If you take the factorial of a non-integer, Calc uses a generalized
+factorial function defined in terms of Euler's Gamma function
+@texline @math{\Gamma(n)}
+@infoline @expr{gamma(n)}
+(which is itself available as the @kbd{f g} command).
+
+@smallexample
+@group
+3: 4. 3: 24. 1: 5.5 1: 52.342777847
+2: 4.5 2: 52.3427777847 . .
+1: 5. 1: 120.
+ . .
+
+ M-3 ! M-0 @key{DEL} 5.5 f g
+@end group
+@end smallexample
+
+@noindent
+Here we verify the identity
+@texline @math{n! = \Gamma(n+1)}.
+@infoline @expr{@var{n}!@: = gamma(@var{n}+1)}.
+
+The binomial coefficient @var{n}-choose-@var{m}
+@texline or @math{\displaystyle {n \choose m}}
+is defined by
+@texline @math{\displaystyle {n! \over m! \, (n-m)!}}
+@infoline @expr{n!@: / m!@: (n-m)!}
+for all reals @expr{n} and @expr{m}. The intermediate results in this
+formula can become quite large even if the final result is small; the
+@kbd{k c} command computes a binomial coefficient in a way that avoids
+large intermediate values.
+
+The @kbd{k} prefix key defines several common functions out of
+combinatorics and number theory. Here we compute the binomial
+coefficient 30-choose-20, then determine its prime factorization.
+
+@smallexample
+@group
+2: 30 1: 30045015 1: [3, 3, 5, 7, 11, 13, 23, 29]
+1: 20 . .
+ .
+
+ 30 @key{RET} 20 k c k f
+@end group
+@end smallexample
+
+@noindent
+You can verify these prime factors by using @kbd{v u} to ``unpack''
+this vector into 8 separate stack entries, then @kbd{M-8 *} to
+multiply them back together. The result is the original number,
+30045015.
+
+@cindex Hash tables
+Suppose a program you are writing needs a hash table with at least
+10000 entries. It's best to use a prime number as the actual size
+of a hash table. Calc can compute the next prime number after 10000:
+
+@smallexample
+@group
+1: 10000 1: 10007 1: 9973
+ . . .
+
+ 10000 k n I k n
+@end group
+@end smallexample
+
+@noindent
+Just for kicks we've also computed the next prime @emph{less} than
+10000.
+
+@c [fix-ref Financial Functions]
+@xref{Financial Functions}, for a description of the Calculator
+commands that deal with business and financial calculations (functions
+like @code{pv}, @code{rate}, and @code{sln}).
+
+@c [fix-ref Binary Number Functions]
+@xref{Binary Functions}, to read about the commands for operating
+on binary numbers (like @code{and}, @code{xor}, and @code{lsh}).
+
+@node Vector/Matrix Tutorial, Types Tutorial, Arithmetic Tutorial, Tutorial
+@section Vector/Matrix Tutorial
+
+@noindent
+A @dfn{vector} is a list of numbers or other Calc data objects.
+Calc provides a large set of commands that operate on vectors. Some
+are familiar operations from vector analysis. Others simply treat
+a vector as a list of objects.
+
+@menu
+* Vector Analysis Tutorial::
+* Matrix Tutorial::
+* List Tutorial::
+@end menu
+
+@node Vector Analysis Tutorial, Matrix Tutorial, Vector/Matrix Tutorial, Vector/Matrix Tutorial
+@subsection Vector Analysis
+
+@noindent
+If you add two vectors, the result is a vector of the sums of the
+elements, taken pairwise.
+
+@smallexample
+@group
+1: [1, 2, 3] 2: [1, 2, 3] 1: [8, 8, 3]
+ . 1: [7, 6, 0] .
+ .
+
+ [1,2,3] s 1 [7 6 0] s 2 +
+@end group
+@end smallexample
+
+@noindent
+Note that we can separate the vector elements with either commas or
+spaces. This is true whether we are using incomplete vectors or
+algebraic entry. The @kbd{s 1} and @kbd{s 2} commands save these
+vectors so we can easily reuse them later.
+
+If you multiply two vectors, the result is the sum of the products
+of the elements taken pairwise. This is called the @dfn{dot product}
+of the vectors.
+
+@smallexample
+@group
+2: [1, 2, 3] 1: 19
+1: [7, 6, 0] .
+ .
+
+ r 1 r 2 *
+@end group
+@end smallexample
+
+@cindex Dot product
+The dot product of two vectors is equal to the product of their
+lengths times the cosine of the angle between them. (Here the vector
+is interpreted as a line from the origin @expr{(0,0,0)} to the
+specified point in three-dimensional space.) The @kbd{A}
+(absolute value) command can be used to compute the length of a
+vector.
+
+@smallexample
+@group
+3: 19 3: 19 1: 0.550782 1: 56.579
+2: [1, 2, 3] 2: 3.741657 . .
+1: [7, 6, 0] 1: 9.219544
+ . .
+
+ M-@key{RET} M-2 A * / I C
+@end group
+@end smallexample
+
+@noindent
+First we recall the arguments to the dot product command, then
+we compute the absolute values of the top two stack entries to
+obtain the lengths of the vectors, then we divide the dot product
+by the product of the lengths to get the cosine of the angle.
+The inverse cosine finds that the angle between the vectors
+is about 56 degrees.
+
+@cindex Cross product
+@cindex Perpendicular vectors
+The @dfn{cross product} of two vectors is a vector whose length
+is the product of the lengths of the inputs times the sine of the
+angle between them, and whose direction is perpendicular to both
+input vectors. Unlike the dot product, the cross product is
+defined only for three-dimensional vectors. Let's double-check
+our computation of the angle using the cross product.
+
+@smallexample
+@group
+2: [1, 2, 3] 3: [-18, 21, -8] 1: [-0.52, 0.61, -0.23] 1: 56.579
+1: [7, 6, 0] 2: [1, 2, 3] . .
+ . 1: [7, 6, 0]
+ .
+
+ r 1 r 2 V C s 3 M-@key{RET} M-2 A * / A I S
+@end group
+@end smallexample
+
+@noindent
+First we recall the original vectors and compute their cross product,
+which we also store for later reference. Now we divide the vector
+by the product of the lengths of the original vectors. The length of
+this vector should be the sine of the angle; sure enough, it is!
+
+@c [fix-ref General Mode Commands]
+Vector-related commands generally begin with the @kbd{v} prefix key.
+Some are uppercase letters and some are lowercase. To make it easier
+to type these commands, the shift-@kbd{V} prefix key acts the same as
+the @kbd{v} key. (@xref{General Mode Commands}, for a way to make all
+prefix keys have this property.)
+
+If we take the dot product of two perpendicular vectors we expect
+to get zero, since the cosine of 90 degrees is zero. Let's check
+that the cross product is indeed perpendicular to both inputs:
+
+@smallexample
+@group
+2: [1, 2, 3] 1: 0 2: [7, 6, 0] 1: 0
+1: [-18, 21, -8] . 1: [-18, 21, -8] .
+ . .
+
+ r 1 r 3 * @key{DEL} r 2 r 3 *
+@end group
+@end smallexample
+
+@cindex Normalizing a vector
+@cindex Unit vectors
+(@bullet{}) @strong{Exercise 1.} Given a vector on the top of the
+stack, what keystrokes would you use to @dfn{normalize} the
+vector, i.e., to reduce its length to one without changing its
+direction? @xref{Vector Answer 1, 1}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 2.} Suppose a certain particle can be
+at any of several positions along a ruler. You have a list of
+those positions in the form of a vector, and another list of the
+probabilities for the particle to be at the corresponding positions.
+Find the average position of the particle.
+@xref{Vector Answer 2, 2}. (@bullet{})
+
+@node Matrix Tutorial, List Tutorial, Vector Analysis Tutorial, Vector/Matrix Tutorial
+@subsection Matrices
+
+@noindent
+A @dfn{matrix} is just a vector of vectors, all the same length.
+This means you can enter a matrix using nested brackets. You can
+also use the semicolon character to enter a matrix. We'll show
+both methods here:
+
+@smallexample
+@group
+1: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ]
+ [ 4, 5, 6 ] ] [ 4, 5, 6 ] ]
+ . .
+
+ [[1 2 3] [4 5 6]] ' [1 2 3; 4 5 6] @key{RET}
+@end group
+@end smallexample
+
+@noindent
+We'll be using this matrix again, so type @kbd{s 4} to save it now.
+
+Note that semicolons work with incomplete vectors, but they work
+better in algebraic entry. That's why we use the apostrophe in
+the second example.
+
+When two matrices are multiplied, the lefthand matrix must have
+the same number of columns as the righthand matrix has rows.
+Row @expr{i}, column @expr{j} of the result is effectively the
+dot product of row @expr{i} of the left matrix by column @expr{j}
+of the right matrix.
+
+If we try to duplicate this matrix and multiply it by itself,
+the dimensions are wrong and the multiplication cannot take place:
+
+@smallexample
+@group
+1: [ [ 1, 2, 3 ] * [ [ 1, 2, 3 ]
+ [ 4, 5, 6 ] ] [ 4, 5, 6 ] ]
+ .
+
+ @key{RET} *
+@end group
+@end smallexample
+
+@noindent
+Though rather hard to read, this is a formula which shows the product
+of two matrices. The @samp{*} function, having invalid arguments, has
+been left in symbolic form.
+
+We can multiply the matrices if we @dfn{transpose} one of them first.
+
+@smallexample
+@group
+2: [ [ 1, 2, 3 ] 1: [ [ 14, 32 ] 1: [ [ 17, 22, 27 ]
+ [ 4, 5, 6 ] ] [ 32, 77 ] ] [ 22, 29, 36 ]
+1: [ [ 1, 4 ] . [ 27, 36, 45 ] ]
+ [ 2, 5 ] .
+ [ 3, 6 ] ]
+ .
+
+ U v t * U @key{TAB} *
+@end group
+@end smallexample
+
+Matrix multiplication is not commutative; indeed, switching the
+order of the operands can even change the dimensions of the result
+matrix, as happened here!
+
+If you multiply a plain vector by a matrix, it is treated as a
+single row or column depending on which side of the matrix it is
+on. The result is a plain vector which should also be interpreted
+as a row or column as appropriate.
+
+@smallexample
+@group
+2: [ [ 1, 2, 3 ] 1: [14, 32]
+ [ 4, 5, 6 ] ] .
+1: [1, 2, 3]
+ .
+
+ r 4 r 1 *
+@end group
+@end smallexample
+
+Multiplying in the other order wouldn't work because the number of
+rows in the matrix is different from the number of elements in the
+vector.
+
+(@bullet{}) @strong{Exercise 1.} Use @samp{*} to sum along the rows
+of the above
+@texline @math{2\times3}
+@infoline 2x3
+matrix to get @expr{[6, 15]}. Now use @samp{*} to sum along the columns
+to get @expr{[5, 7, 9]}.
+@xref{Matrix Answer 1, 1}. (@bullet{})
+
+@cindex Identity matrix
+An @dfn{identity matrix} is a square matrix with ones along the
+diagonal and zeros elsewhere. It has the property that multiplication
+by an identity matrix, on the left or on the right, always produces
+the original matrix.
+
+@smallexample
+@group
+1: [ [ 1, 2, 3 ] 2: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ]
+ [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] [ 4, 5, 6 ] ]
+ . 1: [ [ 1, 0, 0 ] .
+ [ 0, 1, 0 ]
+ [ 0, 0, 1 ] ]
+ .
+
+ r 4 v i 3 @key{RET} *
+@end group
+@end smallexample
+
+If a matrix is square, it is often possible to find its @dfn{inverse},
+that is, a matrix which, when multiplied by the original matrix, yields
+an identity matrix. The @kbd{&} (reciprocal) key also computes the
+inverse of a matrix.
+
+@smallexample
+@group
+1: [ [ 1, 2, 3 ] 1: [ [ -2.4, 1.2, -0.2 ]
+ [ 4, 5, 6 ] [ 2.8, -1.4, 0.4 ]
+ [ 7, 6, 0 ] ] [ -0.73333, 0.53333, -0.2 ] ]
+ . .
+
+ r 4 r 2 | s 5 &
+@end group
+@end smallexample
+
+@noindent
+The vertical bar @kbd{|} @dfn{concatenates} numbers, vectors, and
+matrices together. Here we have used it to add a new row onto
+our matrix to make it square.
+
+We can multiply these two matrices in either order to get an identity.
+
+@smallexample
+@group
+1: [ [ 1., 0., 0. ] 1: [ [ 1., 0., 0. ]
+ [ 0., 1., 0. ] [ 0., 1., 0. ]
+ [ 0., 0., 1. ] ] [ 0., 0., 1. ] ]
+ . .
+
+ M-@key{RET} * U @key{TAB} *
+@end group
+@end smallexample
+
+@cindex Systems of linear equations
+@cindex Linear equations, systems of
+Matrix inverses are related to systems of linear equations in algebra.
+Suppose we had the following set of equations:
+
+@ifnottex
+@group
+@example
+ a + 2b + 3c = 6
+ 4a + 5b + 6c = 2
+ 7a + 6b = 3
+@end example
+@end group
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplayh
+$$ \openup1\jot \tabskip=0pt plus1fil
+\halign to\displaywidth{\tabskip=0pt
+ $\hfil#$&$\hfil{}#{}$&
+ $\hfil#$&$\hfil{}#{}$&
+ $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr
+ a&+&2b&+&3c&=6 \cr
+ 4a&+&5b&+&6c&=2 \cr
+ 7a&+&6b& & &=3 \cr}
+$$
+\afterdisplayh
+@end tex
+
+@noindent
+This can be cast into the matrix equation,
+
+@ifnottex
+@group
+@example
+ [ [ 1, 2, 3 ] [ [ a ] [ [ 6 ]
+ [ 4, 5, 6 ] * [ b ] = [ 2 ]
+ [ 7, 6, 0 ] ] [ c ] ] [ 3 ] ]
+@end example
+@end group
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ \pmatrix{ 1 & 2 & 3 \cr 4 & 5 & 6 \cr 7 & 6 & 0 }
+ \times
+ \pmatrix{ a \cr b \cr c } = \pmatrix{ 6 \cr 2 \cr 3 }
+$$
+\afterdisplay
+@end tex
+
+We can solve this system of equations by multiplying both sides by the
+inverse of the matrix. Calc can do this all in one step:
+
+@smallexample
+@group
+2: [6, 2, 3] 1: [-12.6, 15.2, -3.93333]
+1: [ [ 1, 2, 3 ] .
+ [ 4, 5, 6 ]
+ [ 7, 6, 0 ] ]
+ .
+
+ [6,2,3] r 5 /
+@end group
+@end smallexample
+
+@noindent
+The result is the @expr{[a, b, c]} vector that solves the equations.
+(Dividing by a square matrix is equivalent to multiplying by its
+inverse.)
+
+Let's verify this solution:
+
+@smallexample
+@group
+2: [ [ 1, 2, 3 ] 1: [6., 2., 3.]
+ [ 4, 5, 6 ] .
+ [ 7, 6, 0 ] ]
+1: [-12.6, 15.2, -3.93333]
+ .
+
+ r 5 @key{TAB} *
+@end group
+@end smallexample
+
+@noindent
+Note that we had to be careful about the order in which we multiplied
+the matrix and vector. If we multiplied in the other order, Calc would
+assume the vector was a row vector in order to make the dimensions
+come out right, and the answer would be incorrect. If you
+don't feel safe letting Calc take either interpretation of your
+vectors, use explicit
+@texline @math{N\times1}
+@infoline Nx1
+or
+@texline @math{1\times N}
+@infoline 1xN
+matrices instead. In this case, you would enter the original column
+vector as @samp{[[6], [2], [3]]} or @samp{[6; 2; 3]}.
+
+(@bullet{}) @strong{Exercise 2.} Algebraic entry allows you to make
+vectors and matrices that include variables. Solve the following
+system of equations to get expressions for @expr{x} and @expr{y}
+in terms of @expr{a} and @expr{b}.
+
+@ifnottex
+@group
+@example
+ x + a y = 6
+ x + b y = 10
+@end example
+@end group
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ \eqalign{ x &+ a y = 6 \cr
+ x &+ b y = 10}
+$$
+\afterdisplay
+@end tex
+
+@noindent
+@xref{Matrix Answer 2, 2}. (@bullet{})
+
+@cindex Least-squares for over-determined systems
+@cindex Over-determined systems of equations
+(@bullet{}) @strong{Exercise 3.} A system of equations is ``over-determined''
+if it has more equations than variables. It is often the case that
+there are no values for the variables that will satisfy all the
+equations at once, but it is still useful to find a set of values
+which ``nearly'' satisfy all the equations. In terms of matrix equations,
+you can't solve @expr{A X = B} directly because the matrix @expr{A}
+is not square for an over-determined system. Matrix inversion works
+only for square matrices. One common trick is to multiply both sides
+on the left by the transpose of @expr{A}:
+@ifnottex
+@samp{trn(A)*A*X = trn(A)*B}.
+@end ifnottex
+@tex
+\turnoffactive
+$A^T A \, X = A^T B$, where $A^T$ is the transpose \samp{trn(A)}.
+@end tex
+Now
+@texline @math{A^T A}
+@infoline @expr{trn(A)*A}
+is a square matrix so a solution is possible. It turns out that the
+@expr{X} vector you compute in this way will be a ``least-squares''
+solution, which can be regarded as the ``closest'' solution to the set
+of equations. Use Calc to solve the following over-determined
+system:
+
+@ifnottex
+@group
+@example
+ a + 2b + 3c = 6
+ 4a + 5b + 6c = 2
+ 7a + 6b = 3
+ 2a + 4b + 6c = 11
+@end example
+@end group
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplayh
+$$ \openup1\jot \tabskip=0pt plus1fil
+\halign to\displaywidth{\tabskip=0pt
+ $\hfil#$&$\hfil{}#{}$&
+ $\hfil#$&$\hfil{}#{}$&
+ $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr
+ a&+&2b&+&3c&=6 \cr
+ 4a&+&5b&+&6c&=2 \cr
+ 7a&+&6b& & &=3 \cr
+ 2a&+&4b&+&6c&=11 \cr}
+$$
+\afterdisplayh
+@end tex
+
+@noindent
+@xref{Matrix Answer 3, 3}. (@bullet{})
+
+@node List Tutorial, , Matrix Tutorial, Vector/Matrix Tutorial
+@subsection Vectors as Lists
+
+@noindent
+@cindex Lists
+Although Calc has a number of features for manipulating vectors and
+matrices as mathematical objects, you can also treat vectors as
+simple lists of values. For example, we saw that the @kbd{k f}
+command returns a vector which is a list of the prime factors of a
+number.
+
+You can pack and unpack stack entries into vectors:
+
+@smallexample
+@group
+3: 10 1: [10, 20, 30] 3: 10
+2: 20 . 2: 20
+1: 30 1: 30
+ . .
+
+ M-3 v p v u
+@end group
+@end smallexample
+
+You can also build vectors out of consecutive integers, or out
+of many copies of a given value:
+
+@smallexample
+@group
+1: [1, 2, 3, 4] 2: [1, 2, 3, 4] 2: [1, 2, 3, 4]
+ . 1: 17 1: [17, 17, 17, 17]
+ . .
+
+ v x 4 @key{RET} 17 v b 4 @key{RET}
+@end group
+@end smallexample
+
+You can apply an operator to every element of a vector using the
+@dfn{map} command.
+
+@smallexample
+@group
+1: [17, 34, 51, 68] 1: [289, 1156, 2601, 4624] 1: [17, 34, 51, 68]
+ . . .
+
+ V M * 2 V M ^ V M Q
+@end group
+@end smallexample
+
+@noindent
+In the first step, we multiply the vector of integers by the vector
+of 17's elementwise. In the second step, we raise each element to
+the power two. (The general rule is that both operands must be
+vectors of the same length, or else one must be a vector and the
+other a plain number.) In the final step, we take the square root
+of each element.
+
+(@bullet{}) @strong{Exercise 1.} Compute a vector of powers of two
+from
+@texline @math{2^{-4}}
+@infoline @expr{2^-4}
+to @expr{2^4}. @xref{List Answer 1, 1}. (@bullet{})
+
+You can also @dfn{reduce} a binary operator across a vector.
+For example, reducing @samp{*} computes the product of all the
+elements in the vector:
+
+@smallexample
+@group
+1: 123123 1: [3, 7, 11, 13, 41] 1: 123123
+ . . .
+
+ 123123 k f V R *
+@end group
+@end smallexample
+
+@noindent
+In this example, we decompose 123123 into its prime factors, then
+multiply those factors together again to yield the original number.
+
+We could compute a dot product ``by hand'' using mapping and
+reduction:
+
+@smallexample
+@group
+2: [1, 2, 3] 1: [7, 12, 0] 1: 19
+1: [7, 6, 0] . .
+ .
+
+ r 1 r 2 V M * V R +
+@end group
+@end smallexample
+
+@noindent
+Recalling two vectors from the previous section, we compute the
+sum of pairwise products of the elements to get the same answer
+for the dot product as before.
+
+A slight variant of vector reduction is the @dfn{accumulate} operation,
+@kbd{V U}. This produces a vector of the intermediate results from
+a corresponding reduction. Here we compute a table of factorials:
+
+@smallexample
+@group
+1: [1, 2, 3, 4, 5, 6] 1: [1, 2, 6, 24, 120, 720]
+ . .
+
+ v x 6 @key{RET} V U *
+@end group
+@end smallexample
+
+Calc allows vectors to grow as large as you like, although it gets
+rather slow if vectors have more than about a hundred elements.
+Actually, most of the time is spent formatting these large vectors
+for display, not calculating on them. Try the following experiment
+(if your computer is very fast you may need to substitute a larger
+vector size).
+
+@smallexample
+@group
+1: [1, 2, 3, 4, ... 1: [2, 3, 4, 5, ...
+ . .
+
+ v x 500 @key{RET} 1 V M +
+@end group
+@end smallexample
+
+Now press @kbd{v .} (the letter @kbd{v}, then a period) and try the
+experiment again. In @kbd{v .} mode, long vectors are displayed
+``abbreviated'' like this:
+
+@smallexample
+@group
+1: [1, 2, 3, ..., 500] 1: [2, 3, 4, ..., 501]
+ . .
+
+ v x 500 @key{RET} 1 V M +
+@end group
+@end smallexample
+
+@noindent
+(where now the @samp{...} is actually part of the Calc display).
+You will find both operations are now much faster. But notice that
+even in @w{@kbd{v .}} mode, the full vectors are still shown in the Trail.
+Type @w{@kbd{t .}} to cause the trail to abbreviate as well, and try the
+experiment one more time. Operations on long vectors are now quite
+fast! (But of course if you use @kbd{t .} you will lose the ability
+to get old vectors back using the @kbd{t y} command.)
+
+An easy way to view a full vector when @kbd{v .} mode is active is
+to press @kbd{`} (back-quote) to edit the vector; editing always works
+with the full, unabbreviated value.
+
+@cindex Least-squares for fitting a straight line
+@cindex Fitting data to a line
+@cindex Line, fitting data to
+@cindex Data, extracting from buffers
+@cindex Columns of data, extracting
+As a larger example, let's try to fit a straight line to some data,
+using the method of least squares. (Calc has a built-in command for
+least-squares curve fitting, but we'll do it by hand here just to
+practice working with vectors.) Suppose we have the following list
+of values in a file we have loaded into Emacs:
+
+@smallexample
+ x y
+ --- ---
+ 1.34 0.234
+ 1.41 0.298
+ 1.49 0.402
+ 1.56 0.412
+ 1.64 0.466
+ 1.73 0.473
+ 1.82 0.601
+ 1.91 0.519
+ 2.01 0.603
+ 2.11 0.637
+ 2.22 0.645
+ 2.33 0.705
+ 2.45 0.917
+ 2.58 1.009
+ 2.71 0.971
+ 2.85 1.062
+ 3.00 1.148
+ 3.15 1.157
+ 3.32 1.354
+@end smallexample
+
+@noindent
+If you are reading this tutorial in printed form, you will find it
+easiest to press @kbd{C-x * i} to enter the on-line Info version of
+the manual and find this table there. (Press @kbd{g}, then type
+@kbd{List Tutorial}, to jump straight to this section.)
+
+Position the cursor at the upper-left corner of this table, just
+to the left of the @expr{1.34}. Press @kbd{C-@@} to set the mark.
+(On your system this may be @kbd{C-2}, @kbd{C-@key{SPC}}, or @kbd{NUL}.)
+Now position the cursor to the lower-right, just after the @expr{1.354}.
+You have now defined this region as an Emacs ``rectangle.'' Still
+in the Info buffer, type @kbd{C-x * r}. This command
+(@code{calc-grab-rectangle}) will pop you back into the Calculator, with
+the contents of the rectangle you specified in the form of a matrix.
+
+@smallexample
+@group
+1: [ [ 1.34, 0.234 ]
+ [ 1.41, 0.298 ]
+ @dots{}
+@end group
+@end smallexample
+
+@noindent
+(You may wish to use @kbd{v .} mode to abbreviate the display of this
+large matrix.)
+
+We want to treat this as a pair of lists. The first step is to
+transpose this matrix into a pair of rows. Remember, a matrix is
+just a vector of vectors. So we can unpack the matrix into a pair
+of row vectors on the stack.
+
+@smallexample
+@group
+1: [ [ 1.34, 1.41, 1.49, ... ] 2: [1.34, 1.41, 1.49, ... ]
+ [ 0.234, 0.298, 0.402, ... ] ] 1: [0.234, 0.298, 0.402, ... ]
+ . .
+
+ v t v u
+@end group
+@end smallexample
+
+@noindent
+Let's store these in quick variables 1 and 2, respectively.
+
+@smallexample
+@group
+1: [1.34, 1.41, 1.49, ... ] .
+ .
+
+ t 2 t 1
+@end group
+@end smallexample
+
+@noindent
+(Recall that @kbd{t 2} is a variant of @kbd{s 2} that removes the
+stored value from the stack.)
+
+In a least squares fit, the slope @expr{m} is given by the formula
+
+@ifnottex
+@example
+m = (N sum(x y) - sum(x) sum(y)) / (N sum(x^2) - sum(x)^2)
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ m = {N \sum x y - \sum x \sum y \over
+ N \sum x^2 - \left( \sum x \right)^2} $$
+\afterdisplay
+@end tex
+
+@noindent
+where
+@texline @math{\sum x}
+@infoline @expr{sum(x)}
+represents the sum of all the values of @expr{x}. While there is an
+actual @code{sum} function in Calc, it's easier to sum a vector using a
+simple reduction. First, let's compute the four different sums that
+this formula uses.
+
+@smallexample
+@group
+1: 41.63 1: 98.0003
+ . .
+
+ r 1 V R + t 3 r 1 2 V M ^ V R + t 4
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: 13.613 1: 33.36554
+ . .
+
+ r 2 V R + t 5 r 1 r 2 V M * V R + t 6
+@end group
+@end smallexample
+
+@ifnottex
+@noindent
+These are @samp{sum(x)}, @samp{sum(x^2)}, @samp{sum(y)}, and @samp{sum(x y)},
+respectively. (We could have used @kbd{*} to compute @samp{sum(x^2)} and
+@samp{sum(x y)}.)
+@end ifnottex
+@tex
+\turnoffactive
+These are $\sum x$, $\sum x^2$, $\sum y$, and $\sum x y$,
+respectively. (We could have used \kbd{*} to compute $\sum x^2$ and
+$\sum x y$.)
+@end tex
+
+Finally, we also need @expr{N}, the number of data points. This is just
+the length of either of our lists.
+
+@smallexample
+@group
+1: 19
+ .
+
+ r 1 v l t 7
+@end group
+@end smallexample
+
+@noindent
+(That's @kbd{v} followed by a lower-case @kbd{l}.)
+
+Now we grind through the formula:
+
+@smallexample
+@group
+1: 633.94526 2: 633.94526 1: 67.23607
+ . 1: 566.70919 .
+ .
+
+ r 7 r 6 * r 3 r 5 * -
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+2: 67.23607 3: 67.23607 2: 67.23607 1: 0.52141679
+1: 1862.0057 2: 1862.0057 1: 128.9488 .
+ . 1: 1733.0569 .
+ .
+
+ r 7 r 4 * r 3 2 ^ - / t 8
+@end group
+@end smallexample
+
+That gives us the slope @expr{m}. The y-intercept @expr{b} can now
+be found with the simple formula,
+
+@ifnottex
+@example
+b = (sum(y) - m sum(x)) / N
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ b = {\sum y - m \sum x \over N} $$
+\afterdisplay
+\vskip10pt
+@end tex
+
+@smallexample
+@group
+1: 13.613 2: 13.613 1: -8.09358 1: -0.425978
+ . 1: 21.70658 . .
+ .
+
+ r 5 r 8 r 3 * - r 7 / t 9
+@end group
+@end smallexample
+
+Let's ``plot'' this straight line approximation,
+@texline @math{y \approx m x + b},
+@infoline @expr{m x + b},
+and compare it with the original data.
+
+@smallexample
+@group
+1: [0.699, 0.735, ... ] 1: [0.273, 0.309, ... ]
+ . .
+
+ r 1 r 8 * r 9 + s 0
+@end group
+@end smallexample
+
+@noindent
+Notice that multiplying a vector by a constant, and adding a constant
+to a vector, can be done without mapping commands since these are
+common operations from vector algebra. As far as Calc is concerned,
+we've just been doing geometry in 19-dimensional space!
+
+We can subtract this vector from our original @expr{y} vector to get
+a feel for the error of our fit. Let's find the maximum error:
+
+@smallexample
+@group
+1: [0.0387, 0.0112, ... ] 1: [0.0387, 0.0112, ... ] 1: 0.0897
+ . . .
+
+ r 2 - V M A V R X
+@end group
+@end smallexample
+
+@noindent
+First we compute a vector of differences, then we take the absolute
+values of these differences, then we reduce the @code{max} function
+across the vector. (The @code{max} function is on the two-key sequence
+@kbd{f x}; because it is so common to use @code{max} in a vector
+operation, the letters @kbd{X} and @kbd{N} are also accepted for
+@code{max} and @code{min} in this context. In general, you answer
+the @kbd{V M} or @kbd{V R} prompt with the actual key sequence that
+invokes the function you want. You could have typed @kbd{V R f x} or
+even @kbd{V R x max @key{RET}} if you had preferred.)
+
+If your system has the GNUPLOT program, you can see graphs of your
+data and your straight line to see how well they match. (If you have
+GNUPLOT 3.0 or higher, the following instructions will work regardless
+of the kind of display you have. Some GNUPLOT 2.0, non-X-windows systems
+may require additional steps to view the graphs.)
+
+Let's start by plotting the original data. Recall the ``@var{x}'' and ``@var{y}''
+vectors onto the stack and press @kbd{g f}. This ``fast'' graphing
+command does everything you need to do for simple, straightforward
+plotting of data.
+
+@smallexample
+@group
+2: [1.34, 1.41, 1.49, ... ]
+1: [0.234, 0.298, 0.402, ... ]
+ .
+
+ r 1 r 2 g f
+@end group
+@end smallexample
+
+If all goes well, you will shortly get a new window containing a graph
+of the data. (If not, contact your GNUPLOT or Calc installer to find
+out what went wrong.) In the X window system, this will be a separate
+graphics window. For other kinds of displays, the default is to
+display the graph in Emacs itself using rough character graphics.
+Press @kbd{q} when you are done viewing the character graphics.
+
+Next, let's add the line we got from our least-squares fit.
+@ifinfo
+(If you are reading this tutorial on-line while running Calc, typing
+@kbd{g a} may cause the tutorial to disappear from its window and be
+replaced by a buffer named @samp{*Gnuplot Commands*}. The tutorial
+will reappear when you terminate GNUPLOT by typing @kbd{g q}.)
+@end ifinfo
+
+@smallexample
+@group
+2: [1.34, 1.41, 1.49, ... ]
+1: [0.273, 0.309, 0.351, ... ]
+ .
+
+ @key{DEL} r 0 g a g p
+@end group
+@end smallexample
+
+It's not very useful to get symbols to mark the data points on this
+second curve; you can type @kbd{g S g p} to remove them. Type @kbd{g q}
+when you are done to remove the X graphics window and terminate GNUPLOT.
+
+(@bullet{}) @strong{Exercise 2.} An earlier exercise showed how to do
+least squares fitting to a general system of equations. Our 19 data
+points are really 19 equations of the form @expr{y_i = m x_i + b} for
+different pairs of @expr{(x_i,y_i)}. Use the matrix-transpose method
+to solve for @expr{m} and @expr{b}, duplicating the above result.
+@xref{List Answer 2, 2}. (@bullet{})
+
+@cindex Geometric mean
+(@bullet{}) @strong{Exercise 3.} If the input data do not form a
+rectangle, you can use @w{@kbd{C-x * g}} (@code{calc-grab-region})
+to grab the data the way Emacs normally works with regions---it reads
+left-to-right, top-to-bottom, treating line breaks the same as spaces.
+Use this command to find the geometric mean of the following numbers.
+(The geometric mean is the @var{n}th root of the product of @var{n} numbers.)
+
+@example
+2.3 6 22 15.1 7
+ 15 14 7.5
+ 2.5
+@end example
+
+@noindent
+The @kbd{C-x * g} command accepts numbers separated by spaces or commas,
+with or without surrounding vector brackets.
+@xref{List Answer 3, 3}. (@bullet{})
+
+@ifnottex
+As another example, a theorem about binomial coefficients tells
+us that the alternating sum of binomial coefficients
+@var{n}-choose-0 minus @var{n}-choose-1 plus @var{n}-choose-2, and so
+on up to @var{n}-choose-@var{n},
+always comes out to zero. Let's verify this
+for @expr{n=6}.
+@end ifnottex
+@tex
+As another example, a theorem about binomial coefficients tells
+us that the alternating sum of binomial coefficients
+${n \choose 0} - {n \choose 1} + {n \choose 2} - \cdots \pm {n \choose n}$
+always comes out to zero. Let's verify this
+for \cite{n=6}.
+@end tex
+
+@smallexample
+@group
+1: [1, 2, 3, 4, 5, 6, 7] 1: [0, 1, 2, 3, 4, 5, 6]
+ . .
+
+ v x 7 @key{RET} 1 -
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: [1, -6, 15, -20, 15, -6, 1] 1: 0
+ . .
+
+ V M ' (-1)^$ choose(6,$) @key{RET} V R +
+@end group
+@end smallexample
+
+The @kbd{V M '} command prompts you to enter any algebraic expression
+to define the function to map over the vector. The symbol @samp{$}
+inside this expression represents the argument to the function.
+The Calculator applies this formula to each element of the vector,
+substituting each element's value for the @samp{$} sign(s) in turn.
+
+To define a two-argument function, use @samp{$$} for the first
+argument and @samp{$} for the second: @kbd{V M ' $$-$ @key{RET}} is
+equivalent to @kbd{V M -}. This is analogous to regular algebraic
+entry, where @samp{$$} would refer to the next-to-top stack entry
+and @samp{$} would refer to the top stack entry, and @kbd{' $$-$ @key{RET}}
+would act exactly like @kbd{-}.
+
+Notice that the @kbd{V M '} command has recorded two things in the
+trail: The result, as usual, and also a funny-looking thing marked
+@samp{oper} that represents the operator function you typed in.
+The function is enclosed in @samp{< >} brackets, and the argument is
+denoted by a @samp{#} sign. If there were several arguments, they
+would be shown as @samp{#1}, @samp{#2}, and so on. (For example,
+@kbd{V M ' $$-$} will put the function @samp{<#1 - #2>} on the
+trail.) This object is a ``nameless function''; you can use nameless
+@w{@samp{< >}} notation to answer the @kbd{V M '} prompt if you like.
+Nameless function notation has the interesting, occasionally useful
+property that a nameless function is not actually evaluated until
+it is used. For example, @kbd{V M ' $+random(2.0)} evaluates
+@samp{random(2.0)} once and adds that random number to all elements
+of the vector, but @kbd{V M ' <#+random(2.0)>} evaluates the
+@samp{random(2.0)} separately for each vector element.
+
+Another group of operators that are often useful with @kbd{V M} are
+the relational operators: @kbd{a =}, for example, compares two numbers
+and gives the result 1 if they are equal, or 0 if not. Similarly,
+@w{@kbd{a <}} checks for one number being less than another.
+
+Other useful vector operations include @kbd{v v}, to reverse a
+vector end-for-end; @kbd{V S}, to sort the elements of a vector
+into increasing order; and @kbd{v r} and @w{@kbd{v c}}, to extract
+one row or column of a matrix, or (in both cases) to extract one
+element of a plain vector. With a negative argument, @kbd{v r}
+and @kbd{v c} instead delete one row, column, or vector element.
+
+@cindex Divisor functions
+(@bullet{}) @strong{Exercise 4.} The @expr{k}th @dfn{divisor function}
+@tex
+$\sigma_k(n)$
+@end tex
+is the sum of the @expr{k}th powers of all the divisors of an
+integer @expr{n}. Figure out a method for computing the divisor
+function for reasonably small values of @expr{n}. As a test,
+the 0th and 1st divisor functions of 30 are 8 and 72, respectively.
+@xref{List Answer 4, 4}. (@bullet{})
+
+@cindex Square-free numbers
+@cindex Duplicate values in a list
+(@bullet{}) @strong{Exercise 5.} The @kbd{k f} command produces a
+list of prime factors for a number. Sometimes it is important to
+know that a number is @dfn{square-free}, i.e., that no prime occurs
+more than once in its list of prime factors. Find a sequence of
+keystrokes to tell if a number is square-free; your method should
+leave 1 on the stack if it is, or 0 if it isn't.
+@xref{List Answer 5, 5}. (@bullet{})
+
+@cindex Triangular lists
+(@bullet{}) @strong{Exercise 6.} Build a list of lists that looks
+like the following diagram. (You may wish to use the @kbd{v /}
+command to enable multi-line display of vectors.)
+
+@smallexample
+@group
+1: [ [1],
+ [1, 2],
+ [1, 2, 3],
+ [1, 2, 3, 4],
+ [1, 2, 3, 4, 5],
+ [1, 2, 3, 4, 5, 6] ]
+@end group
+@end smallexample
+
+@noindent
+@xref{List Answer 6, 6}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 7.} Build the following list of lists.
+
+@smallexample
+@group
+1: [ [0],
+ [1, 2],
+ [3, 4, 5],
+ [6, 7, 8, 9],
+ [10, 11, 12, 13, 14],
+ [15, 16, 17, 18, 19, 20] ]
+@end group
+@end smallexample
+
+@noindent
+@xref{List Answer 7, 7}. (@bullet{})
+
+@cindex Maximizing a function over a list of values
+@c [fix-ref Numerical Solutions]
+(@bullet{}) @strong{Exercise 8.} Compute a list of values of Bessel's
+@texline @math{J_1(x)}
+@infoline @expr{J1}
+function @samp{besJ(1,x)} for @expr{x} from 0 to 5 in steps of 0.25.
+Find the value of @expr{x} (from among the above set of values) for
+which @samp{besJ(1,x)} is a maximum. Use an ``automatic'' method,
+i.e., just reading along the list by hand to find the largest value
+is not allowed! (There is an @kbd{a X} command which does this kind
+of thing automatically; @pxref{Numerical Solutions}.)
+@xref{List Answer 8, 8}. (@bullet{})
+
+@cindex Digits, vectors of
+(@bullet{}) @strong{Exercise 9.} You are given an integer in the range
+@texline @math{0 \le N < 10^m}
+@infoline @expr{0 <= N < 10^m}
+for @expr{m=12} (i.e., an integer of less than
+twelve digits). Convert this integer into a vector of @expr{m}
+digits, each in the range from 0 to 9. In vector-of-digits notation,
+add one to this integer to produce a vector of @expr{m+1} digits
+(since there could be a carry out of the most significant digit).
+Convert this vector back into a regular integer. A good integer
+to try is 25129925999. @xref{List Answer 9, 9}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 10.} Your friend Joe tried to use
+@kbd{V R a =} to test if all numbers in a list were equal. What
+happened? How would you do this test? @xref{List Answer 10, 10}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 11.} The area of a circle of radius one
+is @cpi{}. The area of the
+@texline @math{2\times2}
+@infoline 2x2
+square that encloses that circle is 4. So if we throw @var{n} darts at
+random points in the square, about @cpiover{4} of them will land inside
+the circle. This gives us an entertaining way to estimate the value of
+@cpi{}. The @w{@kbd{k r}}
+command picks a random number between zero and the value on the stack.
+We could get a random floating-point number between @mathit{-1} and 1 by typing
+@w{@kbd{2.0 k r 1 -}}. Build a vector of 100 random @expr{(x,y)} points in
+this square, then use vector mapping and reduction to count how many
+points lie inside the unit circle. Hint: Use the @kbd{v b} command.
+@xref{List Answer 11, 11}. (@bullet{})
+
+@cindex Matchstick problem
+(@bullet{}) @strong{Exercise 12.} The @dfn{matchstick problem} provides
+another way to calculate @cpi{}. Say you have an infinite field
+of vertical lines with a spacing of one inch. Toss a one-inch matchstick
+onto the field. The probability that the matchstick will land crossing
+a line turns out to be
+@texline @math{2/\pi}.
+@infoline @expr{2/pi}.
+Toss 100 matchsticks to estimate @cpi{}. (If you want still more fun,
+the probability that the GCD (@w{@kbd{k g}}) of two large integers is
+one turns out to be
+@texline @math{6/\pi^2}.
+@infoline @expr{6/pi^2}.
+That provides yet another way to estimate @cpi{}.)
+@xref{List Answer 12, 12}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 13.} An algebraic entry of a string in
+double-quote marks, @samp{"hello"}, creates a vector of the numerical
+(ASCII) codes of the characters (here, @expr{[104, 101, 108, 108, 111]}).
+Sometimes it is convenient to compute a @dfn{hash code} of a string,
+which is just an integer that represents the value of that string.
+Two equal strings have the same hash code; two different strings
+@dfn{probably} have different hash codes. (For example, Calc has
+over 400 function names, but Emacs can quickly find the definition for
+any given name because it has sorted the functions into ``buckets'' by
+their hash codes. Sometimes a few names will hash into the same bucket,
+but it is easier to search among a few names than among all the names.)
+One popular hash function is computed as follows: First set @expr{h = 0}.
+Then, for each character from the string in turn, set @expr{h = 3h + c_i}
+where @expr{c_i} is the character's ASCII code. If we have 511 buckets,
+we then take the hash code modulo 511 to get the bucket number. Develop a
+simple command or commands for converting string vectors into hash codes.
+The hash code for @samp{"Testing, 1, 2, 3"} is 1960915098, which modulo
+511 is 121. @xref{List Answer 13, 13}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 14.} The @kbd{H V R} and @kbd{H V U}
+commands do nested function evaluations. @kbd{H V U} takes a starting
+value and a number of steps @var{n} from the stack; it then applies the
+function you give to the starting value 0, 1, 2, up to @var{n} times
+and returns a vector of the results. Use this command to create a
+``random walk'' of 50 steps. Start with the two-dimensional point
+@expr{(0,0)}; then take one step a random distance between @mathit{-1} and 1
+in both @expr{x} and @expr{y}; then take another step, and so on. Use the
+@kbd{g f} command to display this random walk. Now modify your random
+walk to walk a unit distance, but in a random direction, at each step.
+(Hint: The @code{sincos} function returns a vector of the cosine and
+sine of an angle.) @xref{List Answer 14, 14}. (@bullet{})
+
+@node Types Tutorial, Algebra Tutorial, Vector/Matrix Tutorial, Tutorial
+@section Types Tutorial
+
+@noindent
+Calc understands a variety of data types as well as simple numbers.
+In this section, we'll experiment with each of these types in turn.
+
+The numbers we've been using so far have mainly been either @dfn{integers}
+or @dfn{floats}. We saw that floats are usually a good approximation to
+the mathematical concept of real numbers, but they are only approximations
+and are susceptible to roundoff error. Calc also supports @dfn{fractions},
+which can exactly represent any rational number.
+
+@smallexample
+@group
+1: 3628800 2: 3628800 1: 518400:7 1: 518414:7 1: 7:518414
+ . 1: 49 . . .
+ .
+
+ 10 ! 49 @key{RET} : 2 + &
+@end group
+@end smallexample
+
+@noindent
+The @kbd{:} command divides two integers to get a fraction; @kbd{/}
+would normally divide integers to get a floating-point result.
+Notice we had to type @key{RET} between the @kbd{49} and the @kbd{:}
+since the @kbd{:} would otherwise be interpreted as part of a
+fraction beginning with 49.
+
+You can convert between floating-point and fractional format using
+@kbd{c f} and @kbd{c F}:
+
+@smallexample
+@group
+1: 1.35027217629e-5 1: 7:518414
+ . .
+
+ c f c F
+@end group
+@end smallexample
+
+The @kbd{c F} command replaces a floating-point number with the
+``simplest'' fraction whose floating-point representation is the
+same, to within the current precision.
+
+@smallexample
+@group
+1: 3.14159265359 1: 1146408:364913 1: 3.1416 1: 355:113
+ . . . .
+
+ P c F @key{DEL} p 5 @key{RET} P c F
+@end group
+@end smallexample
+
+(@bullet{}) @strong{Exercise 1.} A calculation has produced the
+result 1.26508260337. You suspect it is the square root of the
+product of @cpi{} and some rational number. Is it? (Be sure
+to allow for roundoff error!) @xref{Types Answer 1, 1}. (@bullet{})
+
+@dfn{Complex numbers} can be stored in both rectangular and polar form.
+
+@smallexample
+@group
+1: -9 1: (0, 3) 1: (3; 90.) 1: (6; 90.) 1: (2.4495; 45.)
+ . . . . .
+
+ 9 n Q c p 2 * Q
+@end group
+@end smallexample
+
+@noindent
+The square root of @mathit{-9} is by default rendered in rectangular form
+(@w{@expr{0 + 3i}}), but we can convert it to polar form (3 with a
+phase angle of 90 degrees). All the usual arithmetic and scientific
+operations are defined on both types of complex numbers.
+
+Another generalized kind of number is @dfn{infinity}. Infinity
+isn't really a number, but it can sometimes be treated like one.
+Calc uses the symbol @code{inf} to represent positive infinity,
+i.e., a value greater than any real number. Naturally, you can
+also write @samp{-inf} for minus infinity, a value less than any
+real number. The word @code{inf} can only be input using
+algebraic entry.
+
+@smallexample
+@group
+2: inf 2: -inf 2: -inf 2: -inf 1: nan
+1: -17 1: -inf 1: -inf 1: inf .
+ . . . .
+
+' inf @key{RET} 17 n * @key{RET} 72 + A +
+@end group
+@end smallexample
+
+@noindent
+Since infinity is infinitely large, multiplying it by any finite
+number (like @mathit{-17}) has no effect, except that since @mathit{-17}
+is negative, it changes a plus infinity to a minus infinity.
+(``A huge positive number, multiplied by @mathit{-17}, yields a huge
+negative number.'') Adding any finite number to infinity also
+leaves it unchanged. Taking an absolute value gives us plus
+infinity again. Finally, we add this plus infinity to the minus
+infinity we had earlier. If you work it out, you might expect
+the answer to be @mathit{-72} for this. But the 72 has been completely
+lost next to the infinities; by the time we compute @w{@samp{inf - inf}}
+the finite difference between them, if any, is undetectable.
+So we say the result is @dfn{indeterminate}, which Calc writes
+with the symbol @code{nan} (for Not A Number).
+
+Dividing by zero is normally treated as an error, but you can get
+Calc to write an answer in terms of infinity by pressing @kbd{m i}
+to turn on Infinite mode.
+
+@smallexample
+@group
+3: nan 2: nan 2: nan 2: nan 1: nan
+2: 1 1: 1 / 0 1: uinf 1: uinf .
+1: 0 . . .
+ .
+
+ 1 @key{RET} 0 / m i U / 17 n * +
+@end group
+@end smallexample
+
+@noindent
+Dividing by zero normally is left unevaluated, but after @kbd{m i}
+it instead gives an infinite result. The answer is actually
+@code{uinf}, ``undirected infinity.'' If you look at a graph of
+@expr{1 / x} around @w{@expr{x = 0}}, you'll see that it goes toward
+plus infinity as you approach zero from above, but toward minus
+infinity as you approach from below. Since we said only @expr{1 / 0},
+Calc knows that the answer is infinite but not in which direction.
+That's what @code{uinf} means. Notice that multiplying @code{uinf}
+by a negative number still leaves plain @code{uinf}; there's no
+point in saying @samp{-uinf} because the sign of @code{uinf} is
+unknown anyway. Finally, we add @code{uinf} to our @code{nan},
+yielding @code{nan} again. It's easy to see that, because
+@code{nan} means ``totally unknown'' while @code{uinf} means
+``unknown sign but known to be infinite,'' the more mysterious
+@code{nan} wins out when it is combined with @code{uinf}, or, for
+that matter, with anything else.
+
+(@bullet{}) @strong{Exercise 2.} Predict what Calc will answer
+for each of these formulas: @samp{inf / inf}, @samp{exp(inf)},
+@samp{exp(-inf)}, @samp{sqrt(-inf)}, @samp{sqrt(uinf)},
+@samp{abs(uinf)}, @samp{ln(0)}.
+@xref{Types Answer 2, 2}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 3.} We saw that @samp{inf - inf = nan},
+which stands for an unknown value. Can @code{nan} stand for
+a complex number? Can it stand for infinity?
+@xref{Types Answer 3, 3}. (@bullet{})
+
+@dfn{HMS forms} represent a value in terms of hours, minutes, and
+seconds.
+
+@smallexample
+@group
+1: 2@@ 30' 0" 1: 3@@ 30' 0" 2: 3@@ 30' 0" 1: 2.
+ . . 1: 1@@ 45' 0." .
+ .
+
+ 2@@ 30' @key{RET} 1 + @key{RET} 2 / /
+@end group
+@end smallexample
+
+HMS forms can also be used to hold angles in degrees, minutes, and
+seconds.
+
+@smallexample
+@group
+1: 0.5 1: 26.56505 1: 26@@ 33' 54.18" 1: 0.44721
+ . . . .
+
+ 0.5 I T c h S
+@end group
+@end smallexample
+
+@noindent
+First we convert the inverse tangent of 0.5 to degrees-minutes-seconds
+form, then we take the sine of that angle. Note that the trigonometric
+functions will accept HMS forms directly as input.
+
+@cindex Beatles
+(@bullet{}) @strong{Exercise 4.} The Beatles' @emph{Abbey Road} is
+47 minutes and 26 seconds long, and contains 17 songs. What is the
+average length of a song on @emph{Abbey Road}? If the Extended Disco
+Version of @emph{Abbey Road} added 20 seconds to the length of each
+song, how long would the album be? @xref{Types Answer 4, 4}. (@bullet{})
+
+A @dfn{date form} represents a date, or a date and time. Dates must
+be entered using algebraic entry. Date forms are surrounded by
+@samp{< >} symbols; most standard formats for dates are recognized.
+
+@smallexample
+@group
+2: <Sun Jan 13, 1991> 1: 2.25
+1: <6:00pm Thu Jan 10, 1991> .
+ .
+
+' <13 Jan 1991>, <1/10/91, 6pm> @key{RET} -
+@end group
+@end smallexample
+
+@noindent
+In this example, we enter two dates, then subtract to find the
+number of days between them. It is also possible to add an
+HMS form or a number (of days) to a date form to get another
+date form.
+
+@smallexample
+@group
+1: <4:45:59pm Mon Jan 14, 1991> 1: <2:50:59am Thu Jan 17, 1991>
+ . .
+
+ t N 2 + 10@@ 5' +
+@end group
+@end smallexample
+
+@c [fix-ref Date Arithmetic]
+@noindent
+The @kbd{t N} (``now'') command pushes the current date and time on the
+stack; then we add two days, ten hours and five minutes to the date and
+time. Other date-and-time related commands include @kbd{t J}, which
+does Julian day conversions, @kbd{t W}, which finds the beginning of
+the week in which a date form lies, and @kbd{t I}, which increments a
+date by one or several months. @xref{Date Arithmetic}, for more.
+
+(@bullet{}) @strong{Exercise 5.} How many days until the next
+Friday the 13th? @xref{Types Answer 5, 5}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 6.} How many leap years will there be
+between now and the year 10001 A.D.? @xref{Types Answer 6, 6}. (@bullet{})
+
+@cindex Slope and angle of a line
+@cindex Angle and slope of a line
+An @dfn{error form} represents a mean value with an attached standard
+deviation, or error estimate. Suppose our measurements indicate that
+a certain telephone pole is about 30 meters away, with an estimated
+error of 1 meter, and 8 meters tall, with an estimated error of 0.2
+meters. What is the slope of a line from here to the top of the
+pole, and what is the equivalent angle in degrees?
+
+@smallexample
+@group
+1: 8 +/- 0.2 2: 8 +/- 0.2 1: 0.266 +/- 0.011 1: 14.93 +/- 0.594
+ . 1: 30 +/- 1 . .
+ .
+
+ 8 p .2 @key{RET} 30 p 1 / I T
+@end group
+@end smallexample
+
+@noindent
+This means that the angle is about 15 degrees, and, assuming our
+original error estimates were valid standard deviations, there is about
+a 60% chance that the result is correct within 0.59 degrees.
+
+@cindex Torus, volume of
+(@bullet{}) @strong{Exercise 7.} The volume of a torus (a donut shape) is
+@texline @math{2 \pi^2 R r^2}
+@infoline @w{@expr{2 pi^2 R r^2}}
+where @expr{R} is the radius of the circle that
+defines the center of the tube and @expr{r} is the radius of the tube
+itself. Suppose @expr{R} is 20 cm and @expr{r} is 4 cm, each known to
+within 5 percent. What is the volume and the relative uncertainty of
+the volume? @xref{Types Answer 7, 7}. (@bullet{})
+
+An @dfn{interval form} represents a range of values. While an
+error form is best for making statistical estimates, intervals give
+you exact bounds on an answer. Suppose we additionally know that
+our telephone pole is definitely between 28 and 31 meters away,
+and that it is between 7.7 and 8.1 meters tall.
+
+@smallexample
+@group
+1: [7.7 .. 8.1] 2: [7.7 .. 8.1] 1: [0.24 .. 0.28] 1: [13.9 .. 16.1]
+ . 1: [28 .. 31] . .
+ .
+
+ [ 7.7 .. 8.1 ] [ 28 .. 31 ] / I T
+@end group
+@end smallexample
+
+@noindent
+If our bounds were correct, then the angle to the top of the pole
+is sure to lie in the range shown.
+
+The square brackets around these intervals indicate that the endpoints
+themselves are allowable values. In other words, the distance to the
+telephone pole is between 28 and 31, @emph{inclusive}. You can also
+make an interval that is exclusive of its endpoints by writing
+parentheses instead of square brackets. You can even make an interval
+which is inclusive (``closed'') on one end and exclusive (``open'') on
+the other.
+
+@smallexample
+@group
+1: [1 .. 10) 1: (0.1 .. 1] 2: (0.1 .. 1] 1: (0.2 .. 3)
+ . . 1: [2 .. 3) .
+ .
+
+ [ 1 .. 10 ) & [ 2 .. 3 ) *
+@end group
+@end smallexample
+
+@noindent
+The Calculator automatically keeps track of which end values should
+be open and which should be closed. You can also make infinite or
+semi-infinite intervals by using @samp{-inf} or @samp{inf} for one
+or both endpoints.
+
+(@bullet{}) @strong{Exercise 8.} What answer would you expect from
+@samp{@w{1 /} @w{(0 .. 10)}}? What about @samp{@w{1 /} @w{(-10 .. 0)}}? What
+about @samp{@w{1 /} @w{[0 .. 10]}} (where the interval actually includes
+zero)? What about @samp{@w{1 /} @w{(-10 .. 10)}}?
+@xref{Types Answer 8, 8}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 9.} Two easy ways of squaring a number
+are @kbd{@key{RET} *} and @w{@kbd{2 ^}}. Normally these produce the same
+answer. Would you expect this still to hold true for interval forms?
+If not, which of these will result in a larger interval?
+@xref{Types Answer 9, 9}. (@bullet{})
+
+A @dfn{modulo form} is used for performing arithmetic modulo @var{m}.
+For example, arithmetic involving time is generally done modulo 12
+or 24 hours.
+
+@smallexample
+@group
+1: 17 mod 24 1: 3 mod 24 1: 21 mod 24 1: 9 mod 24
+ . . . .
+
+ 17 M 24 @key{RET} 10 + n 5 /
+@end group
+@end smallexample
+
+@noindent
+In this last step, Calc has divided by 5 modulo 24; i.e., it has found a
+new number which, when multiplied by 5 modulo 24, produces the original
+number, 21. If @var{m} is prime and the divisor is not a multiple of
+@var{m}, it is always possible to find such a number. For non-prime
+@var{m} like 24, it is only sometimes possible.
+
+@smallexample
+@group
+1: 10 mod 24 1: 16 mod 24 1: 1000000... 1: 16
+ . . . .
+
+ 10 M 24 @key{RET} 100 ^ 10 @key{RET} 100 ^ 24 %
+@end group
+@end smallexample
+
+@noindent
+These two calculations get the same answer, but the first one is
+much more efficient because it avoids the huge intermediate value
+that arises in the second one.
+
+@cindex Fermat, primality test of
+(@bullet{}) @strong{Exercise 10.} A theorem of Pierre de Fermat
+says that
+@texline @w{@math{x^{n-1} \bmod n = 1}}
+@infoline @expr{x^(n-1) mod n = 1}
+if @expr{n} is a prime number and @expr{x} is an integer less than
+@expr{n}. If @expr{n} is @emph{not} a prime number, this will
+@emph{not} be true for most values of @expr{x}. Thus we can test
+informally if a number is prime by trying this formula for several
+values of @expr{x}. Use this test to tell whether the following numbers
+are prime: 811749613, 15485863. @xref{Types Answer 10, 10}. (@bullet{})
+
+It is possible to use HMS forms as parts of error forms, intervals,
+modulo forms, or as the phase part of a polar complex number.
+For example, the @code{calc-time} command pushes the current time
+of day on the stack as an HMS/modulo form.
+
+@smallexample
+@group
+1: 17@@ 34' 45" mod 24@@ 0' 0" 1: 6@@ 22' 15" mod 24@@ 0' 0"
+ . .
+
+ x time @key{RET} n
+@end group
+@end smallexample
+
+@noindent
+This calculation tells me it is six hours and 22 minutes until midnight.
+
+(@bullet{}) @strong{Exercise 11.} A rule of thumb is that one year
+is about
+@texline @math{\pi \times 10^7}
+@infoline @w{@expr{pi * 10^7}}
+seconds. What time will it be that many seconds from right now?
+@xref{Types Answer 11, 11}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 12.} You are preparing to order packaging
+for the CD release of the Extended Disco Version of @emph{Abbey Road}.
+You are told that the songs will actually be anywhere from 20 to 60
+seconds longer than the originals. One CD can hold about 75 minutes
+of music. Should you order single or double packages?
+@xref{Types Answer 12, 12}. (@bullet{})
+
+Another kind of data the Calculator can manipulate is numbers with
+@dfn{units}. This isn't strictly a new data type; it's simply an
+application of algebraic expressions, where we use variables with
+suggestive names like @samp{cm} and @samp{in} to represent units
+like centimeters and inches.
+
+@smallexample
+@group
+1: 2 in 1: 5.08 cm 1: 0.027778 fath 1: 0.0508 m
+ . . . .
+
+ ' 2in @key{RET} u c cm @key{RET} u c fath @key{RET} u b
+@end group
+@end smallexample
+
+@noindent
+We enter the quantity ``2 inches'' (actually an algebraic expression
+which means two times the variable @samp{in}), then we convert it
+first to centimeters, then to fathoms, then finally to ``base'' units,
+which in this case means meters.
+
+@smallexample
+@group
+1: 9 acre 1: 3 sqrt(acre) 1: 190.84 m 1: 190.84 m + 30 cm
+ . . . .
+
+ ' 9 acre @key{RET} Q u s ' $+30 cm @key{RET}
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: 191.14 m 1: 36536.3046 m^2 1: 365363046 cm^2
+ . . .
+
+ u s 2 ^ u c cgs
+@end group
+@end smallexample
+
+@noindent
+Since units expressions are really just formulas, taking the square
+root of @samp{acre} is undefined. After all, @code{acre} might be an
+algebraic variable that you will someday assign a value. We use the
+``units-simplify'' command to simplify the expression with variables
+being interpreted as unit names.
+
+In the final step, we have converted not to a particular unit, but to a
+units system. The ``cgs'' system uses centimeters instead of meters
+as its standard unit of length.
+
+There is a wide variety of units defined in the Calculator.
+
+@smallexample
+@group
+1: 55 mph 1: 88.5139 kph 1: 88.5139 km / hr 1: 8.201407e-8 c
+ . . . .
+
+ ' 55 mph @key{RET} u c kph @key{RET} u c km/hr @key{RET} u c c @key{RET}
+@end group
+@end smallexample
+
+@noindent
+We express a speed first in miles per hour, then in kilometers per
+hour, then again using a slightly more explicit notation, then
+finally in terms of fractions of the speed of light.
+
+Temperature conversions are a bit more tricky. There are two ways to
+interpret ``20 degrees Fahrenheit''---it could mean an actual
+temperature, or it could mean a change in temperature. For normal
+units there is no difference, but temperature units have an offset
+as well as a scale factor and so there must be two explicit commands
+for them.
+
+@smallexample
+@group
+1: 20 degF 1: 11.1111 degC 1: -20:3 degC 1: -6.666 degC
+ . . . .
+
+ ' 20 degF @key{RET} u c degC @key{RET} U u t degC @key{RET} c f
+@end group
+@end smallexample
+
+@noindent
+First we convert a change of 20 degrees Fahrenheit into an equivalent
+change in degrees Celsius (or Centigrade). Then, we convert the
+absolute temperature 20 degrees Fahrenheit into Celsius. Since
+this comes out as an exact fraction, we then convert to floating-point
+for easier comparison with the other result.
+
+For simple unit conversions, you can put a plain number on the stack.
+Then @kbd{u c} and @kbd{u t} will prompt for both old and new units.
+When you use this method, you're responsible for remembering which
+numbers are in which units:
+
+@smallexample
+@group
+1: 55 1: 88.5139 1: 8.201407e-8
+ . . .
+
+ 55 u c mph @key{RET} kph @key{RET} u c km/hr @key{RET} c @key{RET}
+@end group
+@end smallexample
+
+To see a complete list of built-in units, type @kbd{u v}. Press
+@w{@kbd{C-x * c}} again to re-enter the Calculator when you're done looking
+at the units table.
+
+(@bullet{}) @strong{Exercise 13.} How many seconds are there really
+in a year? @xref{Types Answer 13, 13}. (@bullet{})
+
+@cindex Speed of light
+(@bullet{}) @strong{Exercise 14.} Supercomputer designs are limited by
+the speed of light (and of electricity, which is nearly as fast).
+Suppose a computer has a 4.1 ns (nanosecond) clock cycle, and its
+cabinet is one meter across. Is speed of light going to be a
+significant factor in its design? @xref{Types Answer 14, 14}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 15.} Sam the Slug normally travels about
+five yards in an hour. He has obtained a supply of Power Pills; each
+Power Pill he eats doubles his speed. How many Power Pills can he
+swallow and still travel legally on most US highways?
+@xref{Types Answer 15, 15}. (@bullet{})
+
+@node Algebra Tutorial, Programming Tutorial, Types Tutorial, Tutorial
+@section Algebra and Calculus Tutorial
+
+@noindent
+This section shows how to use Calc's algebra facilities to solve
+equations, do simple calculus problems, and manipulate algebraic
+formulas.
+
+@menu
+* Basic Algebra Tutorial::
+* Rewrites Tutorial::
+@end menu
+
+@node Basic Algebra Tutorial, Rewrites Tutorial, Algebra Tutorial, Algebra Tutorial
+@subsection Basic Algebra
+
+@noindent
+If you enter a formula in Algebraic mode that refers to variables,
+the formula itself is pushed onto the stack. You can manipulate
+formulas as regular data objects.
+
+@smallexample
+@group
+1: 2 x^2 - 6 1: 6 - 2 x^2 1: (6 - 2 x^2) (3 x^2 + y)
+ . . .
+
+ ' 2x^2-6 @key{RET} n ' 3x^2+y @key{RET} *
+@end group
+@end smallexample
+
+(@bullet{}) @strong{Exercise 1.} Do @kbd{' x @key{RET} Q 2 ^} and
+@kbd{' x @key{RET} 2 ^ Q} both wind up with the same result (@samp{x})?
+Why or why not? @xref{Algebra Answer 1, 1}. (@bullet{})
+
+There are also commands for doing common algebraic operations on
+formulas. Continuing with the formula from the last example,
+
+@smallexample
+@group
+1: 18 x^2 + 6 y - 6 x^4 - 2 x^2 y 1: (18 - 2 y) x^2 - 6 x^4 + 6 y
+ . .
+
+ a x a c x @key{RET}
+@end group
+@end smallexample
+
+@noindent
+First we ``expand'' using the distributive law, then we ``collect''
+terms involving like powers of @expr{x}.
+
+Let's find the value of this expression when @expr{x} is 2 and @expr{y}
+is one-half.
+
+@smallexample
+@group
+1: 17 x^2 - 6 x^4 + 3 1: -25
+ . .
+
+ 1:2 s l y @key{RET} 2 s l x @key{RET}
+@end group
+@end smallexample
+
+@noindent
+The @kbd{s l} command means ``let''; it takes a number from the top of
+the stack and temporarily assigns it as the value of the variable
+you specify. It then evaluates (as if by the @kbd{=} key) the
+next expression on the stack. After this command, the variable goes
+back to its original value, if any.
+
+(An earlier exercise in this tutorial involved storing a value in the
+variable @code{x}; if this value is still there, you will have to
+unstore it with @kbd{s u x @key{RET}} before the above example will work
+properly.)
+
+@cindex Maximum of a function using Calculus
+Let's find the maximum value of our original expression when @expr{y}
+is one-half and @expr{x} ranges over all possible values. We can
+do this by taking the derivative with respect to @expr{x} and examining
+values of @expr{x} for which the derivative is zero. If the second
+derivative of the function at that value of @expr{x} is negative,
+the function has a local maximum there.
+
+@smallexample
+@group
+1: 17 x^2 - 6 x^4 + 3 1: 34 x - 24 x^3
+ . .
+
+ U @key{DEL} s 1 a d x @key{RET} s 2
+@end group
+@end smallexample
+
+@noindent
+Well, the derivative is clearly zero when @expr{x} is zero. To find
+the other root(s), let's divide through by @expr{x} and then solve:
+
+@smallexample
+@group
+1: (34 x - 24 x^3) / x 1: 34 x / x - 24 x^3 / x 1: 34 - 24 x^2
+ . . .
+
+ ' x @key{RET} / a x a s
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: 34 - 24 x^2 = 0 1: x = 1.19023
+ . .
+
+ 0 a = s 3 a S x @key{RET}
+@end group
+@end smallexample
+
+@noindent
+Notice the use of @kbd{a s} to ``simplify'' the formula. When the
+default algebraic simplifications don't do enough, you can use
+@kbd{a s} to tell Calc to spend more time on the job.
+
+Now we compute the second derivative and plug in our values of @expr{x}:
+
+@smallexample
+@group
+1: 1.19023 2: 1.19023 2: 1.19023
+ . 1: 34 x - 24 x^3 1: 34 - 72 x^2
+ . .
+
+ a . r 2 a d x @key{RET} s 4
+@end group
+@end smallexample
+
+@noindent
+(The @kbd{a .} command extracts just the righthand side of an equation.
+Another method would have been to use @kbd{v u} to unpack the equation
+@w{@samp{x = 1.19}} to @samp{x} and @samp{1.19}, then use @kbd{M-- M-2 @key{DEL}}
+to delete the @samp{x}.)
+
+@smallexample
+@group
+2: 34 - 72 x^2 1: -68. 2: 34 - 72 x^2 1: 34
+1: 1.19023 . 1: 0 .
+ . .
+
+ @key{TAB} s l x @key{RET} U @key{DEL} 0 s l x @key{RET}
+@end group
+@end smallexample
+
+@noindent
+The first of these second derivatives is negative, so we know the function
+has a maximum value at @expr{x = 1.19023}. (The function also has a
+local @emph{minimum} at @expr{x = 0}.)
+
+When we solved for @expr{x}, we got only one value even though
+@expr{34 - 24 x^2 = 0} is a quadratic equation that ought to have
+two solutions. The reason is that @w{@kbd{a S}} normally returns a
+single ``principal'' solution. If it needs to come up with an
+arbitrary sign (as occurs in the quadratic formula) it picks @expr{+}.
+If it needs an arbitrary integer, it picks zero. We can get a full
+solution by pressing @kbd{H} (the Hyperbolic flag) before @kbd{a S}.
+
+@smallexample
+@group
+1: 34 - 24 x^2 = 0 1: x = 1.19023 s1 1: x = -1.19023
+ . . .
+
+ r 3 H a S x @key{RET} s 5 1 n s l s1 @key{RET}
+@end group
+@end smallexample
+
+@noindent
+Calc has invented the variable @samp{s1} to represent an unknown sign;
+it is supposed to be either @mathit{+1} or @mathit{-1}. Here we have used
+the ``let'' command to evaluate the expression when the sign is negative.
+If we plugged this into our second derivative we would get the same,
+negative, answer, so @expr{x = -1.19023} is also a maximum.
+
+To find the actual maximum value, we must plug our two values of @expr{x}
+into the original formula.
+
+@smallexample
+@group
+2: 17 x^2 - 6 x^4 + 3 1: 24.08333 s1^2 - 12.04166 s1^4 + 3
+1: x = 1.19023 s1 .
+ .
+
+ r 1 r 5 s l @key{RET}
+@end group
+@end smallexample
+
+@noindent
+(Here we see another way to use @kbd{s l}; if its input is an equation
+with a variable on the lefthand side, then @kbd{s l} treats the equation
+like an assignment to that variable if you don't give a variable name.)
+
+It's clear that this will have the same value for either sign of
+@code{s1}, but let's work it out anyway, just for the exercise:
+
+@smallexample
+@group
+2: [-1, 1] 1: [15.04166, 15.04166]
+1: 24.08333 s1^2 ... .
+ .
+
+ [ 1 n , 1 ] @key{TAB} V M $ @key{RET}
+@end group
+@end smallexample
+
+@noindent
+Here we have used a vector mapping operation to evaluate the function
+at several values of @samp{s1} at once. @kbd{V M $} is like @kbd{V M '}
+except that it takes the formula from the top of the stack. The
+formula is interpreted as a function to apply across the vector at the
+next-to-top stack level. Since a formula on the stack can't contain
+@samp{$} signs, Calc assumes the variables in the formula stand for
+different arguments. It prompts you for an @dfn{argument list}, giving
+the list of all variables in the formula in alphabetical order as the
+default list. In this case the default is @samp{(s1)}, which is just
+what we want so we simply press @key{RET} at the prompt.
+
+If there had been several different values, we could have used
+@w{@kbd{V R X}} to find the global maximum.
+
+Calc has a built-in @kbd{a P} command that solves an equation using
+@w{@kbd{H a S}} and returns a vector of all the solutions. It simply
+automates the job we just did by hand. Applied to our original
+cubic polynomial, it would produce the vector of solutions
+@expr{[1.19023, -1.19023, 0]}. (There is also an @kbd{a X} command
+which finds a local maximum of a function. It uses a numerical search
+method rather than examining the derivatives, and thus requires you
+to provide some kind of initial guess to show it where to look.)
+
+(@bullet{}) @strong{Exercise 2.} Given a vector of the roots of a
+polynomial (such as the output of an @kbd{a P} command), what
+sequence of commands would you use to reconstruct the original
+polynomial? (The answer will be unique to within a constant
+multiple; choose the solution where the leading coefficient is one.)
+@xref{Algebra Answer 2, 2}. (@bullet{})
+
+The @kbd{m s} command enables Symbolic mode, in which formulas
+like @samp{sqrt(5)} that can't be evaluated exactly are left in
+symbolic form rather than giving a floating-point approximate answer.
+Fraction mode (@kbd{m f}) is also useful when doing algebra.
+
+@smallexample
+@group
+2: 34 x - 24 x^3 2: 34 x - 24 x^3
+1: 34 x - 24 x^3 1: [sqrt(51) / 6, sqrt(51) / -6, 0]
+ . .
+
+ r 2 @key{RET} m s m f a P x @key{RET}
+@end group
+@end smallexample
+
+One more mode that makes reading formulas easier is Big mode.
+
+@smallexample
+@group
+ 3
+2: 34 x - 24 x
+
+ ____ ____
+ V 51 V 51
+1: [-----, -----, 0]
+ 6 -6
+
+ .
+
+ d B
+@end group
+@end smallexample
+
+Here things like powers, square roots, and quotients and fractions
+are displayed in a two-dimensional pictorial form. Calc has other
+language modes as well, such as C mode, FORTRAN mode, @TeX{} mode
+and La@TeX{} mode.
+
+@smallexample
+@group
+2: 34*x - 24*pow(x, 3) 2: 34*x - 24*x**3
+1: @{sqrt(51) / 6, sqrt(51) / -6, 0@} 1: /sqrt(51) / 6, sqrt(51) / -6, 0/
+ . .
+
+ d C d F
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+3: 34 x - 24 x^3
+2: [@{\sqrt@{51@} \over 6@}, @{\sqrt@{51@} \over -6@}, 0]
+1: @{2 \over 3@} \sqrt@{5@}
+ .
+
+ d T ' 2 \sqrt@{5@} \over 3 @key{RET}
+@end group
+@end smallexample
+
+@noindent
+As you can see, language modes affect both entry and display of
+formulas. They affect such things as the names used for built-in
+functions, the set of arithmetic operators and their precedences,
+and notations for vectors and matrices.
+
+Notice that @samp{sqrt(51)} may cause problems with older
+implementations of C and FORTRAN, which would require something more
+like @samp{sqrt(51.0)}. It is always wise to check over the formulas
+produced by the various language modes to make sure they are fully
+correct.
+
+Type @kbd{m s}, @kbd{m f}, and @kbd{d N} to reset these modes. (You
+may prefer to remain in Big mode, but all the examples in the tutorial
+are shown in normal mode.)
+
+@cindex Area under a curve
+What is the area under the portion of this curve from @expr{x = 1} to @expr{2}?
+This is simply the integral of the function:
+
+@smallexample
+@group
+1: 17 x^2 - 6 x^4 + 3 1: 5.6666 x^3 - 1.2 x^5 + 3 x
+ . .
+
+ r 1 a i x
+@end group
+@end smallexample
+
+@noindent
+We want to evaluate this at our two values for @expr{x} and subtract.
+One way to do it is again with vector mapping and reduction:
+
+@smallexample
+@group
+2: [2, 1] 1: [12.93333, 7.46666] 1: 5.46666
+1: 5.6666 x^3 ... . .
+
+ [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R -
+@end group
+@end smallexample
+
+(@bullet{}) @strong{Exercise 3.} Find the integral from 1 to @expr{y}
+of
+@texline @math{x \sin \pi x}
+@infoline @w{@expr{x sin(pi x)}}
+(where the sine is calculated in radians). Find the values of the
+integral for integers @expr{y} from 1 to 5. @xref{Algebra Answer 3,
+3}. (@bullet{})
+
+Calc's integrator can do many simple integrals symbolically, but many
+others are beyond its capabilities. Suppose we wish to find the area
+under the curve
+@texline @math{\sin x \ln x}
+@infoline @expr{sin(x) ln(x)}
+over the same range of @expr{x}. If you entered this formula and typed
+@kbd{a i x @key{RET}} (don't bother to try this), Calc would work for a
+long time but would be unable to find a solution. In fact, there is no
+closed-form solution to this integral. Now what do we do?
+
+@cindex Integration, numerical
+@cindex Numerical integration
+One approach would be to do the integral numerically. It is not hard
+to do this by hand using vector mapping and reduction. It is rather
+slow, though, since the sine and logarithm functions take a long time.
+We can save some time by reducing the working precision.
+
+@smallexample
+@group
+3: 10 1: [1, 1.1, 1.2, ... , 1.8, 1.9]
+2: 1 .
+1: 0.1
+ .
+
+ 10 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x
+@end group
+@end smallexample
+
+@noindent
+(Note that we have used the extended version of @kbd{v x}; we could
+also have used plain @kbd{v x} as follows: @kbd{v x 10 @key{RET} 9 + .1 *}.)
+
+@smallexample
+@group
+2: [1, 1.1, ... ] 1: [0., 0.084941, 0.16993, ... ]
+1: sin(x) ln(x) .
+ .
+
+ ' sin(x) ln(x) @key{RET} s 1 m r p 5 @key{RET} V M $ @key{RET}
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: 3.4195 0.34195
+ . .
+
+ V R + 0.1 *
+@end group
+@end smallexample
+
+@noindent
+(If you got wildly different results, did you remember to switch
+to Radians mode?)
+
+Here we have divided the curve into ten segments of equal width;
+approximating these segments as rectangular boxes (i.e., assuming
+the curve is nearly flat at that resolution), we compute the areas
+of the boxes (height times width), then sum the areas. (It is
+faster to sum first, then multiply by the width, since the width
+is the same for every box.)
+
+The true value of this integral turns out to be about 0.374, so
+we're not doing too well. Let's try another approach.
+
+@smallexample
+@group
+1: sin(x) ln(x) 1: 0.84147 x - 0.84147 + 0.11957 (x - 1)^2 - ...
+ . .
+
+ r 1 a t x=1 @key{RET} 4 @key{RET}
+@end group
+@end smallexample
+
+@noindent
+Here we have computed the Taylor series expansion of the function
+about the point @expr{x=1}. We can now integrate this polynomial
+approximation, since polynomials are easy to integrate.
+
+@smallexample
+@group
+1: 0.42074 x^2 + ... 1: [-0.0446, -0.42073] 1: 0.3761
+ . . .
+
+ a i x @key{RET} [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R -
+@end group
+@end smallexample
+
+@noindent
+Better! By increasing the precision and/or asking for more terms
+in the Taylor series, we can get a result as accurate as we like.
+(Taylor series converge better away from singularities in the
+function such as the one at @code{ln(0)}, so it would also help to
+expand the series about the points @expr{x=2} or @expr{x=1.5} instead
+of @expr{x=1}.)
+
+@cindex Simpson's rule
+@cindex Integration by Simpson's rule
+(@bullet{}) @strong{Exercise 4.} Our first method approximated the
+curve by stairsteps of width 0.1; the total area was then the sum
+of the areas of the rectangles under these stairsteps. Our second
+method approximated the function by a polynomial, which turned out
+to be a better approximation than stairsteps. A third method is
+@dfn{Simpson's rule}, which is like the stairstep method except
+that the steps are not required to be flat. Simpson's rule boils
+down to the formula,
+
+@ifnottex
+@example
+(h/3) * (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + ...
+ + 2 f(a+(n-2)*h) + 4 f(a+(n-1)*h) + f(a+n*h))
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ \displaylines{
+ \qquad {h \over 3} (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + \cdots
+ \hfill \cr \hfill {} + 2 f(a+(n-2)h) + 4 f(a+(n-1)h) + f(a+n h)) \qquad
+} $$
+\afterdisplay
+@end tex
+
+@noindent
+where @expr{n} (which must be even) is the number of slices and @expr{h}
+is the width of each slice. These are 10 and 0.1 in our example.
+For reference, here is the corresponding formula for the stairstep
+method:
+
+@ifnottex
+@example
+h * (f(a) + f(a+h) + f(a+2h) + f(a+3h) + ...
+ + f(a+(n-2)*h) + f(a+(n-1)*h))
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ h (f(a) + f(a+h) + f(a+2h) + f(a+3h) + \cdots
+ + f(a+(n-2)h) + f(a+(n-1)h)) $$
+\afterdisplay
+@end tex
+
+Compute the integral from 1 to 2 of
+@texline @math{\sin x \ln x}
+@infoline @expr{sin(x) ln(x)}
+using Simpson's rule with 10 slices.
+@xref{Algebra Answer 4, 4}. (@bullet{})
+
+Calc has a built-in @kbd{a I} command for doing numerical integration.
+It uses @dfn{Romberg's method}, which is a more sophisticated cousin
+of Simpson's rule. In particular, it knows how to keep refining the
+result until the current precision is satisfied.
+
+@c [fix-ref Selecting Sub-Formulas]
+Aside from the commands we've seen so far, Calc also provides a
+large set of commands for operating on parts of formulas. You
+indicate the desired sub-formula by placing the cursor on any part
+of the formula before giving a @dfn{selection} command. Selections won't
+be covered in the tutorial; @pxref{Selecting Subformulas}, for
+details and examples.
+
+@c hard exercise: simplify (2^(n r) - 2^(r*(n - 1))) / (2^r - 1) 2^(n - 1)
+@c to 2^((n-1)*(r-1)).
+
+@node Rewrites Tutorial, , Basic Algebra Tutorial, Algebra Tutorial
+@subsection Rewrite Rules
+
+@noindent
+No matter how many built-in commands Calc provided for doing algebra,
+there would always be something you wanted to do that Calc didn't have
+in its repertoire. So Calc also provides a @dfn{rewrite rule} system
+that you can use to define your own algebraic manipulations.
+
+Suppose we want to simplify this trigonometric formula:
+
+@smallexample
+@group
+1: 1 / cos(x) - sin(x) tan(x)
+ .
+
+ ' 1/cos(x) - sin(x) tan(x) @key{RET} s 1
+@end group
+@end smallexample
+
+@noindent
+If we were simplifying this by hand, we'd probably replace the
+@samp{tan} with a @samp{sin/cos} first, then combine over a common
+denominator. There is no Calc command to do the former; the @kbd{a n}
+algebra command will do the latter but we'll do both with rewrite
+rules just for practice.
+
+Rewrite rules are written with the @samp{:=} symbol.
+
+@smallexample
+@group
+1: 1 / cos(x) - sin(x)^2 / cos(x)
+ .
+
+ a r tan(a) := sin(a)/cos(a) @key{RET}
+@end group
+@end smallexample
+
+@noindent
+(The ``assignment operator'' @samp{:=} has several uses in Calc. All
+by itself the formula @samp{tan(a) := sin(a)/cos(a)} doesn't do anything,
+but when it is given to the @kbd{a r} command, that command interprets
+it as a rewrite rule.)
+
+The lefthand side, @samp{tan(a)}, is called the @dfn{pattern} of the
+rewrite rule. Calc searches the formula on the stack for parts that
+match the pattern. Variables in a rewrite pattern are called
+@dfn{meta-variables}, and when matching the pattern each meta-variable
+can match any sub-formula. Here, the meta-variable @samp{a} matched
+the actual variable @samp{x}.
+
+When the pattern part of a rewrite rule matches a part of the formula,
+that part is replaced by the righthand side with all the meta-variables
+substituted with the things they matched. So the result is
+@samp{sin(x) / cos(x)}. Calc's normal algebraic simplifications then
+mix this in with the rest of the original formula.
+
+To merge over a common denominator, we can use another simple rule:
+
+@smallexample
+@group
+1: (1 - sin(x)^2) / cos(x)
+ .
+
+ a r a/x + b/x := (a+b)/x @key{RET}
+@end group
+@end smallexample
+
+This rule points out several interesting features of rewrite patterns.
+First, if a meta-variable appears several times in a pattern, it must
+match the same thing everywhere. This rule detects common denominators
+because the same meta-variable @samp{x} is used in both of the
+denominators.
+
+Second, meta-variable names are independent from variables in the
+target formula. Notice that the meta-variable @samp{x} here matches
+the subformula @samp{cos(x)}; Calc never confuses the two meanings of
+@samp{x}.
+
+And third, rewrite patterns know a little bit about the algebraic
+properties of formulas. The pattern called for a sum of two quotients;
+Calc was able to match a difference of two quotients by matching
+@samp{a = 1}, @samp{b = -sin(x)^2}, and @samp{x = cos(x)}.
+
+@c [fix-ref Algebraic Properties of Rewrite Rules]
+We could just as easily have written @samp{a/x - b/x := (a-b)/x} for
+the rule. It would have worked just the same in all cases. (If we
+really wanted the rule to apply only to @samp{+} or only to @samp{-},
+we could have used the @code{plain} symbol. @xref{Algebraic Properties
+of Rewrite Rules}, for some examples of this.)
+
+One more rewrite will complete the job. We want to use the identity
+@samp{sin(x)^2 + cos(x)^2 = 1}, but of course we must first rearrange
+the identity in a way that matches our formula. The obvious rule
+would be @samp{@w{1 - sin(x)^2} := cos(x)^2}, but a little thought shows
+that the rule @samp{sin(x)^2 := 1 - cos(x)^2} will also work. The
+latter rule has a more general pattern so it will work in many other
+situations, too.
+
+@smallexample
+@group
+1: (1 + cos(x)^2 - 1) / cos(x) 1: cos(x)
+ . .
+
+ a r sin(x)^2 := 1 - cos(x)^2 @key{RET} a s
+@end group
+@end smallexample
+
+You may ask, what's the point of using the most general rule if you
+have to type it in every time anyway? The answer is that Calc allows
+you to store a rewrite rule in a variable, then give the variable
+name in the @kbd{a r} command. In fact, this is the preferred way to
+use rewrites. For one, if you need a rule once you'll most likely
+need it again later. Also, if the rule doesn't work quite right you
+can simply Undo, edit the variable, and run the rule again without
+having to retype it.
+
+@smallexample
+@group
+' tan(x) := sin(x)/cos(x) @key{RET} s t tsc @key{RET}
+' a/x + b/x := (a+b)/x @key{RET} s t merge @key{RET}
+' sin(x)^2 := 1 - cos(x)^2 @key{RET} s t sinsqr @key{RET}
+
+1: 1 / cos(x) - sin(x) tan(x) 1: cos(x)
+ . .
+
+ r 1 a r tsc @key{RET} a r merge @key{RET} a r sinsqr @key{RET} a s
+@end group
+@end smallexample
+
+To edit a variable, type @kbd{s e} and the variable name, use regular
+Emacs editing commands as necessary, then type @kbd{C-c C-c} to store
+the edited value back into the variable.
+You can also use @w{@kbd{s e}} to create a new variable if you wish.
+
+Notice that the first time you use each rule, Calc puts up a ``compiling''
+message briefly. The pattern matcher converts rules into a special
+optimized pattern-matching language rather than using them directly.
+This allows @kbd{a r} to apply even rather complicated rules very
+efficiently. If the rule is stored in a variable, Calc compiles it
+only once and stores the compiled form along with the variable. That's
+another good reason to store your rules in variables rather than
+entering them on the fly.
+
+(@bullet{}) @strong{Exercise 1.} Type @kbd{m s} to get Symbolic
+mode, then enter the formula @samp{@w{(2 + sqrt(2))} / @w{(1 + sqrt(2))}}.
+Using a rewrite rule, simplify this formula by multiplying the top and
+bottom by the conjugate @w{@samp{1 - sqrt(2)}}. The result will have
+to be expanded by the distributive law; do this with another
+rewrite. @xref{Rewrites Answer 1, 1}. (@bullet{})
+
+The @kbd{a r} command can also accept a vector of rewrite rules, or
+a variable containing a vector of rules.
+
+@smallexample
+@group
+1: [tsc, merge, sinsqr] 1: [tan(x) := sin(x) / cos(x), ... ]
+ . .
+
+ ' [tsc,merge,sinsqr] @key{RET} =
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: 1 / cos(x) - sin(x) tan(x) 1: cos(x)
+ . .
+
+ s t trig @key{RET} r 1 a r trig @key{RET} a s
+@end group
+@end smallexample
+
+@c [fix-ref Nested Formulas with Rewrite Rules]
+Calc tries all the rules you give against all parts of the formula,
+repeating until no further change is possible. (The exact order in
+which things are tried is rather complex, but for simple rules like
+the ones we've used here the order doesn't really matter.
+@xref{Nested Formulas with Rewrite Rules}.)
+
+Calc actually repeats only up to 100 times, just in case your rule set
+has gotten into an infinite loop. You can give a numeric prefix argument
+to @kbd{a r} to specify any limit. In particular, @kbd{M-1 a r} does
+only one rewrite at a time.
+
+@smallexample
+@group
+1: 1 / cos(x) - sin(x)^2 / cos(x) 1: (1 - sin(x)^2) / cos(x)
+ . .
+
+ r 1 M-1 a r trig @key{RET} M-1 a r trig @key{RET}
+@end group
+@end smallexample
+
+You can type @kbd{M-0 a r} if you want no limit at all on the number
+of rewrites that occur.
+
+Rewrite rules can also be @dfn{conditional}. Simply follow the rule
+with a @samp{::} symbol and the desired condition. For example,
+
+@smallexample
+@group
+1: exp(2 pi i) + exp(3 pi i) + exp(4 pi i)
+ .
+
+ ' exp(2 pi i) + exp(3 pi i) + exp(4 pi i) @key{RET}
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: 1 + exp(3 pi i) + 1
+ .
+
+ a r exp(k pi i) := 1 :: k % 2 = 0 @key{RET}
+@end group
+@end smallexample
+
+@noindent
+(Recall, @samp{k % 2} is the remainder from dividing @samp{k} by 2,
+which will be zero only when @samp{k} is an even integer.)
+
+An interesting point is that the variables @samp{pi} and @samp{i}
+were matched literally rather than acting as meta-variables.
+This is because they are special-constant variables. The special
+constants @samp{e}, @samp{phi}, and so on also match literally.
+A common error with rewrite
+rules is to write, say, @samp{f(a,b,c,d,e) := g(a+b+c+d+e)}, expecting
+to match any @samp{f} with five arguments but in fact matching
+only when the fifth argument is literally @samp{e}!
+
+@cindex Fibonacci numbers
+@ignore
+@starindex
+@end ignore
+@tindex fib
+Rewrite rules provide an interesting way to define your own functions.
+Suppose we want to define @samp{fib(n)} to produce the @var{n}th
+Fibonacci number. The first two Fibonacci numbers are each 1;
+later numbers are formed by summing the two preceding numbers in
+the sequence. This is easy to express in a set of three rules:
+
+@smallexample
+@group
+' [fib(1) := 1, fib(2) := 1, fib(n) := fib(n-1) + fib(n-2)] @key{RET} s t fib
+
+1: fib(7) 1: 13
+ . .
+
+ ' fib(7) @key{RET} a r fib @key{RET}
+@end group
+@end smallexample
+
+One thing that is guaranteed about the order that rewrites are tried
+is that, for any given subformula, earlier rules in the rule set will
+be tried for that subformula before later ones. So even though the
+first and third rules both match @samp{fib(1)}, we know the first will
+be used preferentially.
+
+This rule set has one dangerous bug: Suppose we apply it to the
+formula @samp{fib(x)}? (Don't actually try this.) The third rule
+will match @samp{fib(x)} and replace it with @w{@samp{fib(x-1) + fib(x-2)}}.
+Each of these will then be replaced to get @samp{fib(x-2) + 2 fib(x-3) +
+fib(x-4)}, and so on, expanding forever. What we really want is to apply
+the third rule only when @samp{n} is an integer greater than two. Type
+@w{@kbd{s e fib @key{RET}}}, then edit the third rule to:
+
+@smallexample
+fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2
+@end smallexample
+
+@noindent
+Now:
+
+@smallexample
+@group
+1: fib(6) + fib(x) + fib(0) 1: 8 + fib(x) + fib(0)
+ . .
+
+ ' fib(6)+fib(x)+fib(0) @key{RET} a r fib @key{RET}
+@end group
+@end smallexample
+
+@noindent
+We've created a new function, @code{fib}, and a new command,
+@w{@kbd{a r fib @key{RET}}}, which means ``evaluate all @code{fib} calls in
+this formula.'' To make things easier still, we can tell Calc to
+apply these rules automatically by storing them in the special
+variable @code{EvalRules}.
+
+@smallexample
+@group
+1: [fib(1) := ...] . 1: [8, 13]
+ . .
+
+ s r fib @key{RET} s t EvalRules @key{RET} ' [fib(6), fib(7)] @key{RET}
+@end group
+@end smallexample
+
+It turns out that this rule set has the problem that it does far
+more work than it needs to when @samp{n} is large. Consider the
+first few steps of the computation of @samp{fib(6)}:
+
+@smallexample
+@group
+fib(6) =
+fib(5) + fib(4) =
+fib(4) + fib(3) + fib(3) + fib(2) =
+fib(3) + fib(2) + fib(2) + fib(1) + fib(2) + fib(1) + 1 = ...
+@end group
+@end smallexample
+
+@noindent
+Note that @samp{fib(3)} appears three times here. Unless Calc's
+algebraic simplifier notices the multiple @samp{fib(3)}s and combines
+them (and, as it happens, it doesn't), this rule set does lots of
+needless recomputation. To cure the problem, type @code{s e EvalRules}
+to edit the rules (or just @kbd{s E}, a shorthand command for editing
+@code{EvalRules}) and add another condition:
+
+@smallexample
+fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 :: remember
+@end smallexample
+
+@noindent
+If a @samp{:: remember} condition appears anywhere in a rule, then if
+that rule succeeds Calc will add another rule that describes that match
+to the front of the rule set. (Remembering works in any rule set, but
+for technical reasons it is most effective in @code{EvalRules}.) For
+example, if the rule rewrites @samp{fib(7)} to something that evaluates
+to 13, then the rule @samp{fib(7) := 13} will be added to the rule set.
+
+Type @kbd{' fib(8) @key{RET}} to compute the eighth Fibonacci number, then
+type @kbd{s E} again to see what has happened to the rule set.
+
+With the @code{remember} feature, our rule set can now compute
+@samp{fib(@var{n})} in just @var{n} steps. In the process it builds
+up a table of all Fibonacci numbers up to @var{n}. After we have
+computed the result for a particular @var{n}, we can get it back
+(and the results for all smaller @var{n}) later in just one step.
+
+All Calc operations will run somewhat slower whenever @code{EvalRules}
+contains any rules. You should type @kbd{s u EvalRules @key{RET}} now to
+un-store the variable.
+
+(@bullet{}) @strong{Exercise 2.} Sometimes it is possible to reformulate
+a problem to reduce the amount of recursion necessary to solve it.
+Create a rule that, in about @var{n} simple steps and without recourse
+to the @code{remember} option, replaces @samp{fib(@var{n}, 1, 1)} with
+@samp{fib(1, @var{x}, @var{y})} where @var{x} and @var{y} are the
+@var{n}th and @var{n+1}st Fibonacci numbers, respectively. This rule is
+rather clunky to use, so add a couple more rules to make the ``user
+interface'' the same as for our first version: enter @samp{fib(@var{n})},
+get back a plain number. @xref{Rewrites Answer 2, 2}. (@bullet{})
+
+There are many more things that rewrites can do. For example, there
+are @samp{&&&} and @samp{|||} pattern operators that create ``and''
+and ``or'' combinations of rules. As one really simple example, we
+could combine our first two Fibonacci rules thusly:
+
+@example
+[fib(1 ||| 2) := 1, fib(n) := ... ]
+@end example
+
+@noindent
+That means ``@code{fib} of something matching either 1 or 2 rewrites
+to 1.''
+
+You can also make meta-variables optional by enclosing them in @code{opt}.
+For example, the pattern @samp{a + b x} matches @samp{2 + 3 x} but not
+@samp{2 + x} or @samp{3 x} or @samp{x}. The pattern @samp{opt(a) + opt(b) x}
+matches all of these forms, filling in a default of zero for @samp{a}
+and one for @samp{b}.
+
+(@bullet{}) @strong{Exercise 3.} Your friend Joe had @samp{2 + 3 x}
+on the stack and tried to use the rule
+@samp{opt(a) + opt(b) x := f(a, b, x)}. What happened?
+@xref{Rewrites Answer 3, 3}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 4.} Starting with a positive integer @expr{a},
+divide @expr{a} by two if it is even, otherwise compute @expr{3 a + 1}.
+Now repeat this step over and over. A famous unproved conjecture
+is that for any starting @expr{a}, the sequence always eventually
+reaches 1. Given the formula @samp{seq(@var{a}, 0)}, write a set of
+rules that convert this into @samp{seq(1, @var{n})} where @var{n}
+is the number of steps it took the sequence to reach the value 1.
+Now enhance the rules to accept @samp{seq(@var{a})} as a starting
+configuration, and to stop with just the number @var{n} by itself.
+Now make the result be a vector of values in the sequence, from @var{a}
+to 1. (The formula @samp{@var{x}|@var{y}} appends the vectors @var{x}
+and @var{y}.) For example, rewriting @samp{seq(6)} should yield the
+vector @expr{[6, 3, 10, 5, 16, 8, 4, 2, 1]}.
+@xref{Rewrites Answer 4, 4}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 5.} Define, using rewrite rules, a function
+@samp{nterms(@var{x})} that returns the number of terms in the sum
+@var{x}, or 1 if @var{x} is not a sum. (A @dfn{sum} for our purposes
+is one or more non-sum terms separated by @samp{+} or @samp{-} signs,
+so that @expr{2 - 3 (x + y) + x y} is a sum of three terms.)
+@xref{Rewrites Answer 5, 5}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 6.} A Taylor series for a function is an
+infinite series that exactly equals the value of that function at
+values of @expr{x} near zero.
+
+@ifnottex
+@example
+cos(x) = 1 - x^2 / 2! + x^4 / 4! - x^6 / 6! + ...
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ \cos x = 1 - {x^2 \over 2!} + {x^4 \over 4!} - {x^6 \over 6!} + \cdots $$
+\afterdisplay
+@end tex
+
+The @kbd{a t} command produces a @dfn{truncated Taylor series} which
+is obtained by dropping all the terms higher than, say, @expr{x^2}.
+Calc represents the truncated Taylor series as a polynomial in @expr{x}.
+Mathematicians often write a truncated series using a ``big-O'' notation
+that records what was the lowest term that was truncated.
+
+@ifnottex
+@example
+cos(x) = 1 - x^2 / 2! + O(x^3)
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ \cos x = 1 - {x^2 \over 2!} + O(x^3) $$
+\afterdisplay
+@end tex
+
+@noindent
+The meaning of @expr{O(x^3)} is ``a quantity which is negligibly small
+if @expr{x^3} is considered negligibly small as @expr{x} goes to zero.''
+
+The exercise is to create rewrite rules that simplify sums and products of
+power series represented as @samp{@var{polynomial} + O(@var{var}^@var{n})}.
+For example, given @samp{1 - x^2 / 2 + O(x^3)} and @samp{x - x^3 / 6 + O(x^4)}
+on the stack, we want to be able to type @kbd{*} and get the result
+@samp{x - 2:3 x^3 + O(x^4)}. Don't worry if the terms of the sum are
+rearranged or if @kbd{a s} needs to be typed after rewriting. (This one
+is rather tricky; the solution at the end of this chapter uses 6 rewrite
+rules. Hint: The @samp{constant(x)} condition tests whether @samp{x} is
+a number.) @xref{Rewrites Answer 6, 6}. (@bullet{})
+
+Just for kicks, try adding the rule @code{2+3 := 6} to @code{EvalRules}.
+What happens? (Be sure to remove this rule afterward, or you might get
+a nasty surprise when you use Calc to balance your checkbook!)
+
+@xref{Rewrite Rules}, for the whole story on rewrite rules.
+
+@node Programming Tutorial, Answers to Exercises, Algebra Tutorial, Tutorial
+@section Programming Tutorial
+
+@noindent
+The Calculator is written entirely in Emacs Lisp, a highly extensible
+language. If you know Lisp, you can program the Calculator to do
+anything you like. Rewrite rules also work as a powerful programming
+system. But Lisp and rewrite rules take a while to master, and often
+all you want to do is define a new function or repeat a command a few
+times. Calc has features that allow you to do these things easily.
+
+One very limited form of programming is defining your own functions.
+Calc's @kbd{Z F} command allows you to define a function name and
+key sequence to correspond to any formula. Programming commands use
+the shift-@kbd{Z} prefix; the user commands they create use the lower
+case @kbd{z} prefix.
+
+@smallexample
+@group
+1: 1 + x + x^2 / 2 + x^3 / 6 1: 1 + x + x^2 / 2 + x^3 / 6
+ . .
+
+ ' 1 + x + x^2/2! + x^3/3! @key{RET} Z F e myexp @key{RET} @key{RET} @key{RET} y
+@end group
+@end smallexample
+
+This polynomial is a Taylor series approximation to @samp{exp(x)}.
+The @kbd{Z F} command asks a number of questions. The above answers
+say that the key sequence for our function should be @kbd{z e}; the
+@kbd{M-x} equivalent should be @code{calc-myexp}; the name of the
+function in algebraic formulas should also be @code{myexp}; the
+default argument list @samp{(x)} is acceptable; and finally @kbd{y}
+answers the question ``leave it in symbolic form for non-constant
+arguments?''
+
+@smallexample
+@group
+1: 1.3495 2: 1.3495 3: 1.3495
+ . 1: 1.34986 2: 1.34986
+ . 1: myexp(a + 1)
+ .
+
+ .3 z e .3 E ' a+1 @key{RET} z e
+@end group
+@end smallexample
+
+@noindent
+First we call our new @code{exp} approximation with 0.3 as an
+argument, and compare it with the true @code{exp} function. Then
+we note that, as requested, if we try to give @kbd{z e} an
+argument that isn't a plain number, it leaves the @code{myexp}
+function call in symbolic form. If we had answered @kbd{n} to the
+final question, @samp{myexp(a + 1)} would have evaluated by plugging
+in @samp{a + 1} for @samp{x} in the defining formula.
+
+@cindex Sine integral Si(x)
+@ignore
+@starindex
+@end ignore
+@tindex Si
+(@bullet{}) @strong{Exercise 1.} The ``sine integral'' function
+@texline @math{{\rm Si}(x)}
+@infoline @expr{Si(x)}
+is defined as the integral of @samp{sin(t)/t} for
+@expr{t = 0} to @expr{x} in radians. (It was invented because this
+integral has no solution in terms of basic functions; if you give it
+to Calc's @kbd{a i} command, it will ponder it for a long time and then
+give up.) We can use the numerical integration command, however,
+which in algebraic notation is written like @samp{ninteg(f(t), t, 0, x)}
+with any integrand @samp{f(t)}. Define a @kbd{z s} command and
+@code{Si} function that implement this. You will need to edit the
+default argument list a bit. As a test, @samp{Si(1)} should return
+0.946083. (If you don't get this answer, you might want to check that
+Calc is in Radians mode. Also, @code{ninteg} will run a lot faster if
+you reduce the precision to, say, six digits beforehand.)
+@xref{Programming Answer 1, 1}. (@bullet{})
+
+The simplest way to do real ``programming'' of Emacs is to define a
+@dfn{keyboard macro}. A keyboard macro is simply a sequence of
+keystrokes which Emacs has stored away and can play back on demand.
+For example, if you find yourself typing @kbd{H a S x @key{RET}} often,
+you may wish to program a keyboard macro to type this for you.
+
+@smallexample
+@group
+1: y = sqrt(x) 1: x = y^2
+ . .
+
+ ' y=sqrt(x) @key{RET} C-x ( H a S x @key{RET} C-x )
+
+1: y = cos(x) 1: x = s1 arccos(y) + 2 pi n1
+ . .
+
+ ' y=cos(x) @key{RET} X
+@end group
+@end smallexample
+
+@noindent
+When you type @kbd{C-x (}, Emacs begins recording. But it is also
+still ready to execute your keystrokes, so you're really ``training''
+Emacs by walking it through the procedure once. When you type
+@w{@kbd{C-x )}}, the macro is recorded. You can now type @kbd{X} to
+re-execute the same keystrokes.
+
+You can give a name to your macro by typing @kbd{Z K}.
+
+@smallexample
+@group
+1: . 1: y = x^4 1: x = s2 sqrt(s1 sqrt(y))
+ . .
+
+ Z K x @key{RET} ' y=x^4 @key{RET} z x
+@end group
+@end smallexample
+
+@noindent
+Notice that we use shift-@kbd{Z} to define the command, and lower-case
+@kbd{z} to call it up.
+
+Keyboard macros can call other macros.
+
+@smallexample
+@group
+1: abs(x) 1: x = s1 y 1: 2 / x 1: x = 2 / y
+ . . . .
+
+ ' abs(x) @key{RET} C-x ( ' y @key{RET} a = z x C-x ) ' 2/x @key{RET} X
+@end group
+@end smallexample
+
+(@bullet{}) @strong{Exercise 2.} Define a keyboard macro to negate
+the item in level 3 of the stack, without disturbing the rest of
+the stack. @xref{Programming Answer 2, 2}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 3.} Define keyboard macros to compute
+the following functions:
+
+@enumerate
+@item
+Compute
+@texline @math{\displaystyle{\sin x \over x}},
+@infoline @expr{sin(x) / x},
+where @expr{x} is the number on the top of the stack.
+
+@item
+Compute the base-@expr{b} logarithm, just like the @kbd{B} key except
+the arguments are taken in the opposite order.
+
+@item
+Produce a vector of integers from 1 to the integer on the top of
+the stack.
+@end enumerate
+@noindent
+@xref{Programming Answer 3, 3}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 4.} Define a keyboard macro to compute
+the average (mean) value of a list of numbers.
+@xref{Programming Answer 4, 4}. (@bullet{})
+
+In many programs, some of the steps must execute several times.
+Calc has @dfn{looping} commands that allow this. Loops are useful
+inside keyboard macros, but actually work at any time.
+
+@smallexample
+@group
+1: x^6 2: x^6 1: 360 x^2
+ . 1: 4 .
+ .
+
+ ' x^6 @key{RET} 4 Z < a d x @key{RET} Z >
+@end group
+@end smallexample
+
+@noindent
+Here we have computed the fourth derivative of @expr{x^6} by
+enclosing a derivative command in a ``repeat loop'' structure.
+This structure pops a repeat count from the stack, then
+executes the body of the loop that many times.
+
+If you make a mistake while entering the body of the loop,
+type @w{@kbd{Z C-g}} to cancel the loop command.
+
+@cindex Fibonacci numbers
+Here's another example:
+
+@smallexample
+@group
+3: 1 2: 10946
+2: 1 1: 17711
+1: 20 .
+ .
+
+1 @key{RET} @key{RET} 20 Z < @key{TAB} C-j + Z >
+@end group
+@end smallexample
+
+@noindent
+The numbers in levels 2 and 1 should be the 21st and 22nd Fibonacci
+numbers, respectively. (To see what's going on, try a few repetitions
+of the loop body by hand; @kbd{C-j}, also on the Line-Feed or @key{LFD}
+key if you have one, makes a copy of the number in level 2.)
+
+@cindex Golden ratio
+@cindex Phi, golden ratio
+A fascinating property of the Fibonacci numbers is that the @expr{n}th
+Fibonacci number can be found directly by computing
+@texline @math{\phi^n / \sqrt{5}}
+@infoline @expr{phi^n / sqrt(5)}
+and then rounding to the nearest integer, where
+@texline @math{\phi} (``phi''),
+@infoline @expr{phi},
+the ``golden ratio,'' is
+@texline @math{(1 + \sqrt{5}) / 2}.
+@infoline @expr{(1 + sqrt(5)) / 2}.
+(For convenience, this constant is available from the @code{phi}
+variable, or the @kbd{I H P} command.)
+
+@smallexample
+@group
+1: 1.61803 1: 24476.0000409 1: 10945.9999817 1: 10946
+ . . . .
+
+ I H P 21 ^ 5 Q / R
+@end group
+@end smallexample
+
+@cindex Continued fractions
+(@bullet{}) @strong{Exercise 5.} The @dfn{continued fraction}
+representation of
+@texline @math{\phi}
+@infoline @expr{phi}
+is
+@texline @math{1 + 1/(1 + 1/(1 + 1/( \ldots )))}.
+@infoline @expr{1 + 1/(1 + 1/(1 + 1/( ...@: )))}.
+We can compute an approximate value by carrying this however far
+and then replacing the innermost
+@texline @math{1/( \ldots )}
+@infoline @expr{1/( ...@: )}
+by 1. Approximate
+@texline @math{\phi}
+@infoline @expr{phi}
+using a twenty-term continued fraction.
+@xref{Programming Answer 5, 5}. (@bullet{})
+
+(@bullet{}) @strong{Exercise 6.} Linear recurrences like the one for
+Fibonacci numbers can be expressed in terms of matrices. Given a
+vector @w{@expr{[a, b]}} determine a matrix which, when multiplied by this
+vector, produces the vector @expr{[b, c]}, where @expr{a}, @expr{b} and
+@expr{c} are three successive Fibonacci numbers. Now write a program
+that, given an integer @expr{n}, computes the @expr{n}th Fibonacci number
+using matrix arithmetic. @xref{Programming Answer 6, 6}. (@bullet{})
+
+@cindex Harmonic numbers
+A more sophisticated kind of loop is the @dfn{for} loop. Suppose
+we wish to compute the 20th ``harmonic'' number, which is equal to
+the sum of the reciprocals of the integers from 1 to 20.
+
+@smallexample
+@group
+3: 0 1: 3.597739
+2: 1 .
+1: 20
+ .
+
+0 @key{RET} 1 @key{RET} 20 Z ( & + 1 Z )
+@end group
+@end smallexample
+
+@noindent
+The ``for'' loop pops two numbers, the lower and upper limits, then
+repeats the body of the loop as an internal counter increases from
+the lower limit to the upper one. Just before executing the loop
+body, it pushes the current loop counter. When the loop body
+finishes, it pops the ``step,'' i.e., the amount by which to
+increment the loop counter. As you can see, our loop always
+uses a step of one.
+
+This harmonic number function uses the stack to hold the running
+total as well as for the various loop housekeeping functions. If
+you find this disorienting, you can sum in a variable instead:
+
+@smallexample
+@group
+1: 0 2: 1 . 1: 3.597739
+ . 1: 20 .
+ .
+
+ 0 t 7 1 @key{RET} 20 Z ( & s + 7 1 Z ) r 7
+@end group
+@end smallexample
+
+@noindent
+The @kbd{s +} command adds the top-of-stack into the value in a
+variable (and removes that value from the stack).
+
+It's worth noting that many jobs that call for a ``for'' loop can
+also be done more easily by Calc's high-level operations. Two
+other ways to compute harmonic numbers are to use vector mapping
+and reduction (@kbd{v x 20}, then @w{@kbd{V M &}}, then @kbd{V R +}),
+or to use the summation command @kbd{a +}. Both of these are
+probably easier than using loops. However, there are some
+situations where loops really are the way to go:
+
+(@bullet{}) @strong{Exercise 7.} Use a ``for'' loop to find the first
+harmonic number which is greater than 4.0.
+@xref{Programming Answer 7, 7}. (@bullet{})
+
+Of course, if we're going to be using variables in our programs,
+we have to worry about the programs clobbering values that the
+caller was keeping in those same variables. This is easy to
+fix, though:
+
+@smallexample
+@group
+ . 1: 0.6667 1: 0.6667 3: 0.6667
+ . . 2: 3.597739
+ 1: 0.6667
+ .
+
+ Z ` p 4 @key{RET} 2 @key{RET} 3 / s 7 s s a @key{RET} Z ' r 7 s r a @key{RET}
+@end group
+@end smallexample
+
+@noindent
+When we type @kbd{Z `} (that's a back-quote character), Calc saves
+its mode settings and the contents of the ten ``quick variables''
+for later reference. When we type @kbd{Z '} (that's an apostrophe
+now), Calc restores those saved values. Thus the @kbd{p 4} and
+@kbd{s 7} commands have no effect outside this sequence. Wrapping
+this around the body of a keyboard macro ensures that it doesn't
+interfere with what the user of the macro was doing. Notice that
+the contents of the stack, and the values of named variables,
+survive past the @kbd{Z '} command.
+
+@cindex Bernoulli numbers, approximate
+The @dfn{Bernoulli numbers} are a sequence with the interesting
+property that all of the odd Bernoulli numbers are zero, and the
+even ones, while difficult to compute, can be roughly approximated
+by the formula
+@texline @math{\displaystyle{2 n! \over (2 \pi)^n}}.
+@infoline @expr{2 n!@: / (2 pi)^n}.
+Let's write a keyboard macro to compute (approximate) Bernoulli numbers.
+(Calc has a command, @kbd{k b}, to compute exact Bernoulli numbers, but
+this command is very slow for large @expr{n} since the higher Bernoulli
+numbers are very large fractions.)
+
+@smallexample
+@group
+1: 10 1: 0.0756823
+ . .
+
+ 10 C-x ( @key{RET} 2 % Z [ @key{DEL} 0 Z : ' 2 $! / (2 pi)^$ @key{RET} = Z ] C-x )
+@end group
+@end smallexample
+
+@noindent
+You can read @kbd{Z [} as ``then,'' @kbd{Z :} as ``else,'' and
+@kbd{Z ]} as ``end-if.'' There is no need for an explicit ``if''
+command. For the purposes of @w{@kbd{Z [}}, the condition is ``true''
+if the value it pops from the stack is a nonzero number, or ``false''
+if it pops zero or something that is not a number (like a formula).
+Here we take our integer argument modulo 2; this will be nonzero
+if we're asking for an odd Bernoulli number.
+
+The actual tenth Bernoulli number is @expr{5/66}.
+
+@smallexample
+@group
+3: 0.0756823 1: 0 1: 0.25305 1: 0 1: 1.16659
+2: 5:66 . . . .
+1: 0.0757575
+ .
+
+10 k b @key{RET} c f M-0 @key{DEL} 11 X @key{DEL} 12 X @key{DEL} 13 X @key{DEL} 14 X
+@end group
+@end smallexample
+
+Just to exercise loops a bit more, let's compute a table of even
+Bernoulli numbers.
+
+@smallexample
+@group
+3: [] 1: [0.10132, 0.03079, 0.02340, 0.033197, ...]
+2: 2 .
+1: 30
+ .
+
+ [ ] 2 @key{RET} 30 Z ( X | 2 Z )
+@end group
+@end smallexample
+
+@noindent
+The vertical-bar @kbd{|} is the vector-concatenation command. When
+we execute it, the list we are building will be in stack level 2
+(initially this is an empty list), and the next Bernoulli number
+will be in level 1. The effect is to append the Bernoulli number
+onto the end of the list. (To create a table of exact fractional
+Bernoulli numbers, just replace @kbd{X} with @kbd{k b} in the above
+sequence of keystrokes.)
+
+With loops and conditionals, you can program essentially anything
+in Calc. One other command that makes looping easier is @kbd{Z /},
+which takes a condition from the stack and breaks out of the enclosing
+loop if the condition is true (non-zero). You can use this to make
+``while'' and ``until'' style loops.
+
+If you make a mistake when entering a keyboard macro, you can edit
+it using @kbd{Z E}. First, you must attach it to a key with @kbd{Z K}.
+One technique is to enter a throwaway dummy definition for the macro,
+then enter the real one in the edit command.
+
+@smallexample
+@group
+1: 3 1: 3 Calc Macro Edit Mode.
+ . . Original keys: 1 <return> 2 +
+
+ 1 ;; calc digits
+ RET ;; calc-enter
+ 2 ;; calc digits
+ + ;; calc-plus
+
+C-x ( 1 @key{RET} 2 + C-x ) Z K h @key{RET} Z E h
+@end group
+@end smallexample
+
+@noindent
+A keyboard macro is stored as a pure keystroke sequence. The
+@file{edmacro} package (invoked by @kbd{Z E}) scans along the
+macro and tries to decode it back into human-readable steps.
+Descriptions of the keystrokes are given as comments, which begin with
+@samp{;;}, and which are ignored when the edited macro is saved.
+Spaces and line breaks are also ignored when the edited macro is saved.
+To enter a space into the macro, type @code{SPC}. All the special
+characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, @code{DEL},
+and @code{NUL} must be written in all uppercase, as must the prefixes
+@code{C-} and @code{M-}.
+
+Let's edit in a new definition, for computing harmonic numbers.
+First, erase the four lines of the old definition. Then, type
+in the new definition (or use Emacs @kbd{M-w} and @kbd{C-y} commands
+to copy it from this page of the Info file; you can of course skip
+typing the comments, which begin with @samp{;;}).
+
+@smallexample
+Z` ;; calc-kbd-push (Save local values)
+0 ;; calc digits (Push a zero onto the stack)
+st ;; calc-store-into (Store it in the following variable)
+1 ;; calc quick variable (Quick variable q1)
+1 ;; calc digits (Initial value for the loop)
+TAB ;; calc-roll-down (Swap initial and final)
+Z( ;; calc-kbd-for (Begin the "for" loop)
+& ;; calc-inv (Take the reciprocal)
+s+ ;; calc-store-plus (Add to the following variable)
+1 ;; calc quick variable (Quick variable q1)
+1 ;; calc digits (The loop step is 1)
+Z) ;; calc-kbd-end-for (End the "for" loop)
+sr ;; calc-recall (Recall the final accumulated value)
+1 ;; calc quick variable (Quick variable q1)
+Z' ;; calc-kbd-pop (Restore values)
+@end smallexample
+
+@noindent
+Press @kbd{C-c C-c} to finish editing and return to the Calculator.
+
+@smallexample
+@group
+1: 20 1: 3.597739
+ . .
+
+ 20 z h
+@end group
+@end smallexample
+
+The @file{edmacro} package defines a handy @code{read-kbd-macro} command
+which reads the current region of the current buffer as a sequence of
+keystroke names, and defines that sequence on the @kbd{X}
+(and @kbd{C-x e}) key. Because this is so useful, Calc puts this
+command on the @kbd{C-x * m} key. Try reading in this macro in the
+following form: Press @kbd{C-@@} (or @kbd{C-@key{SPC}}) at
+one end of the text below, then type @kbd{C-x * m} at the other.
+
+@example
+@group
+Z ` 0 t 1
+ 1 TAB
+ Z ( & s + 1 1 Z )
+ r 1
+Z '
+@end group
+@end example
+
+(@bullet{}) @strong{Exercise 8.} A general algorithm for solving
+equations numerically is @dfn{Newton's Method}. Given the equation
+@expr{f(x) = 0} for any function @expr{f}, and an initial guess
+@expr{x_0} which is reasonably close to the desired solution, apply
+this formula over and over:
+
+@ifnottex
+@example
+new_x = x - f(x)/f'(x)
+@end example
+@end ifnottex
+@tex
+\beforedisplay
+$$ x_{\rm new} = x - {f(x) \over f'(x)} $$
+\afterdisplay
+@end tex
+
+@noindent
+where @expr{f'(x)} is the derivative of @expr{f}. The @expr{x}
+values will quickly converge to a solution, i.e., eventually
+@texline @math{x_{\rm new}}
+@infoline @expr{new_x}
+and @expr{x} will be equal to within the limits
+of the current precision. Write a program which takes a formula
+involving the variable @expr{x}, and an initial guess @expr{x_0},
+on the stack, and produces a value of @expr{x} for which the formula
+is zero. Use it to find a solution of
+@texline @math{\sin(\cos x) = 0.5}
+@infoline @expr{sin(cos(x)) = 0.5}
+near @expr{x = 4.5}. (Use angles measured in radians.) Note that
+the built-in @w{@kbd{a R}} (@code{calc-find-root}) command uses Newton's
+method when it is able. @xref{Programming Answer 8, 8}. (@bullet{})
+
+@cindex Digamma function
+@cindex Gamma constant, Euler's
+@cindex Euler's gamma constant
+(@bullet{}) @strong{Exercise 9.} The @dfn{digamma} function
+@texline @math{\psi(z) (``psi'')}
+@infoline @expr{psi(z)}
+is defined as the derivative of
+@texline @math{\ln \Gamma(z)}.
+@infoline @expr{ln(gamma(z))}.
+For large values of @expr{z}, it can be approximated by the infinite sum
+
+@ifnottex
+@example
+psi(z) ~= ln(z) - 1/2z - sum(bern(2 n) / 2 n z^(2 n), n, 1, inf)
+@end example
+@end ifnottex
+@tex
+\beforedisplay
+$$ \psi(z) \approx \ln z - {1\over2z} -
+ \sum_{n=1}^\infty {\code{bern}(2 n) \over 2 n z^{2n}}
+$$
+\afterdisplay
+@end tex
+
+@noindent
+where
+@texline @math{\sum}
+@infoline @expr{sum}
+represents the sum over @expr{n} from 1 to infinity
+(or to some limit high enough to give the desired accuracy), and
+the @code{bern} function produces (exact) Bernoulli numbers.
+While this sum is not guaranteed to converge, in practice it is safe.
+An interesting mathematical constant is Euler's gamma, which is equal
+to about 0.5772. One way to compute it is by the formula,
+@texline @math{\gamma = -\psi(1)}.
+@infoline @expr{gamma = -psi(1)}.
+Unfortunately, 1 isn't a large enough argument
+for the above formula to work (5 is a much safer value for @expr{z}).
+Fortunately, we can compute
+@texline @math{\psi(1)}
+@infoline @expr{psi(1)}
+from
+@texline @math{\psi(5)}
+@infoline @expr{psi(5)}
+using the recurrence
+@texline @math{\psi(z+1) = \psi(z) + {1 \over z}}.
+@infoline @expr{psi(z+1) = psi(z) + 1/z}.
+Your task: Develop a program to compute
+@texline @math{\psi(z)};
+@infoline @expr{psi(z)};
+it should ``pump up'' @expr{z}
+if necessary to be greater than 5, then use the above summation
+formula. Use looping commands to compute the sum. Use your function
+to compute
+@texline @math{\gamma}
+@infoline @expr{gamma}
+to twelve decimal places. (Calc has a built-in command
+for Euler's constant, @kbd{I P}, which you can use to check your answer.)
+@xref{Programming Answer 9, 9}. (@bullet{})
+
+@cindex Polynomial, list of coefficients
+(@bullet{}) @strong{Exercise 10.} Given a polynomial in @expr{x} and
+a number @expr{m} on the stack, where the polynomial is of degree
+@expr{m} or less (i.e., does not have any terms higher than @expr{x^m}),
+write a program to convert the polynomial into a list-of-coefficients
+notation. For example, @expr{5 x^4 + (x + 1)^2} with @expr{m = 6}
+should produce the list @expr{[1, 2, 1, 0, 5, 0, 0]}. Also develop
+a way to convert from this form back to the standard algebraic form.
+@xref{Programming Answer 10, 10}. (@bullet{})
+
+@cindex Recursion
+(@bullet{}) @strong{Exercise 11.} The @dfn{Stirling numbers of the
+first kind} are defined by the recurrences,
+
+@ifnottex
+@example
+s(n,n) = 1 for n >= 0,
+s(n,0) = 0 for n > 0,
+s(n+1,m) = s(n,m-1) - n s(n,m) for n >= m >= 1.
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ \eqalign{ s(n,n) &= 1 \qquad \hbox{for } n \ge 0, \cr
+ s(n,0) &= 0 \qquad \hbox{for } n > 0, \cr
+ s(n+1,m) &= s(n,m-1) - n \, s(n,m) \qquad
+ \hbox{for } n \ge m \ge 1.}
+$$
+\afterdisplay
+\vskip5pt
+(These numbers are also sometimes written $\displaystyle{n \brack m}$.)
+@end tex
+
+This can be implemented using a @dfn{recursive} program in Calc; the
+program must invoke itself in order to calculate the two righthand
+terms in the general formula. Since it always invokes itself with
+``simpler'' arguments, it's easy to see that it must eventually finish
+the computation. Recursion is a little difficult with Emacs keyboard
+macros since the macro is executed before its definition is complete.
+So here's the recommended strategy: Create a ``dummy macro'' and assign
+it to a key with, e.g., @kbd{Z K s}. Now enter the true definition,
+using the @kbd{z s} command to call itself recursively, then assign it
+to the same key with @kbd{Z K s}. Now the @kbd{z s} command will run
+the complete recursive program. (Another way is to use @w{@kbd{Z E}}
+or @kbd{C-x * m} (@code{read-kbd-macro}) to read the whole macro at once,
+thus avoiding the ``training'' phase.) The task: Write a program
+that computes Stirling numbers of the first kind, given @expr{n} and
+@expr{m} on the stack. Test it with @emph{small} inputs like
+@expr{s(4,2)}. (There is a built-in command for Stirling numbers,
+@kbd{k s}, which you can use to check your answers.)
+@xref{Programming Answer 11, 11}. (@bullet{})
+
+The programming commands we've seen in this part of the tutorial
+are low-level, general-purpose operations. Often you will find
+that a higher-level function, such as vector mapping or rewrite
+rules, will do the job much more easily than a detailed, step-by-step
+program can:
+
+(@bullet{}) @strong{Exercise 12.} Write another program for
+computing Stirling numbers of the first kind, this time using
+rewrite rules. Once again, @expr{n} and @expr{m} should be taken
+from the stack. @xref{Programming Answer 12, 12}. (@bullet{})
+
+@example
+
+@end example
+This ends the tutorial section of the Calc manual. Now you know enough
+about Calc to use it effectively for many kinds of calculations. But
+Calc has many features that were not even touched upon in this tutorial.
+@c [not-split]
+The rest of this manual tells the whole story.
+@c [when-split]
+@c Volume II of this manual, the @dfn{Calc Reference}, tells the whole story.
+
+@page
+@node Answers to Exercises, , Programming Tutorial, Tutorial
+@section Answers to Exercises
+
+@noindent
+This section includes answers to all the exercises in the Calc tutorial.
+
+@menu
+* RPN Answer 1:: 1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * -
+* RPN Answer 2:: 2*4 + 7*9.5 + 5/4
+* RPN Answer 3:: Operating on levels 2 and 3
+* RPN Answer 4:: Joe's complex problems
+* Algebraic Answer 1:: Simulating Q command
+* Algebraic Answer 2:: Joe's algebraic woes
+* Algebraic Answer 3:: 1 / 0
+* Modes Answer 1:: 3#0.1 = 3#0.0222222?
+* Modes Answer 2:: 16#f.e8fe15
+* Modes Answer 3:: Joe's rounding bug
+* Modes Answer 4:: Why floating point?
+* Arithmetic Answer 1:: Why the \ command?
+* Arithmetic Answer 2:: Tripping up the B command
+* Vector Answer 1:: Normalizing a vector
+* Vector Answer 2:: Average position
+* Matrix Answer 1:: Row and column sums
+* Matrix Answer 2:: Symbolic system of equations
+* Matrix Answer 3:: Over-determined system
+* List Answer 1:: Powers of two
+* List Answer 2:: Least-squares fit with matrices
+* List Answer 3:: Geometric mean
+* List Answer 4:: Divisor function
+* List Answer 5:: Duplicate factors
+* List Answer 6:: Triangular list
+* List Answer 7:: Another triangular list
+* List Answer 8:: Maximum of Bessel function
+* List Answer 9:: Integers the hard way
+* List Answer 10:: All elements equal
+* List Answer 11:: Estimating pi with darts
+* List Answer 12:: Estimating pi with matchsticks
+* List Answer 13:: Hash codes
+* List Answer 14:: Random walk
+* Types Answer 1:: Square root of pi times rational
+* Types Answer 2:: Infinities
+* Types Answer 3:: What can "nan" be?
+* Types Answer 4:: Abbey Road
+* Types Answer 5:: Friday the 13th
+* Types Answer 6:: Leap years
+* Types Answer 7:: Erroneous donut
+* Types Answer 8:: Dividing intervals
+* Types Answer 9:: Squaring intervals
+* Types Answer 10:: Fermat's primality test
+* Types Answer 11:: pi * 10^7 seconds
+* Types Answer 12:: Abbey Road on CD
+* Types Answer 13:: Not quite pi * 10^7 seconds
+* Types Answer 14:: Supercomputers and c
+* Types Answer 15:: Sam the Slug
+* Algebra Answer 1:: Squares and square roots
+* Algebra Answer 2:: Building polynomial from roots
+* Algebra Answer 3:: Integral of x sin(pi x)
+* Algebra Answer 4:: Simpson's rule
+* Rewrites Answer 1:: Multiplying by conjugate
+* Rewrites Answer 2:: Alternative fib rule
+* Rewrites Answer 3:: Rewriting opt(a) + opt(b) x
+* Rewrites Answer 4:: Sequence of integers
+* Rewrites Answer 5:: Number of terms in sum
+* Rewrites Answer 6:: Truncated Taylor series
+* Programming Answer 1:: Fresnel's C(x)
+* Programming Answer 2:: Negate third stack element
+* Programming Answer 3:: Compute sin(x) / x, etc.
+* Programming Answer 4:: Average value of a list
+* Programming Answer 5:: Continued fraction phi
+* Programming Answer 6:: Matrix Fibonacci numbers
+* Programming Answer 7:: Harmonic number greater than 4
+* Programming Answer 8:: Newton's method
+* Programming Answer 9:: Digamma function
+* Programming Answer 10:: Unpacking a polynomial
+* Programming Answer 11:: Recursive Stirling numbers
+* Programming Answer 12:: Stirling numbers with rewrites
+@end menu
+
+@c The following kludgery prevents the individual answers from
+@c being entered on the table of contents.
+@tex
+\global\let\oldwrite=\write
+\gdef\skipwrite#1#2{\let\write=\oldwrite}
+\global\let\oldchapternofonts=\chapternofonts
+\gdef\chapternofonts{\let\write=\skipwrite\oldchapternofonts}
+@end tex
+
+@node RPN Answer 1, RPN Answer 2, Answers to Exercises, Answers to Exercises
+@subsection RPN Tutorial Exercise 1
+
+@noindent
+@kbd{1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * -}
+
+The result is
+@texline @math{1 - (2 \times (3 + 4)) = -13}.
+@infoline @expr{1 - (2 * (3 + 4)) = -13}.
+
+@node RPN Answer 2, RPN Answer 3, RPN Answer 1, Answers to Exercises
+@subsection RPN Tutorial Exercise 2
+
+@noindent
+@texline @math{2\times4 + 7\times9.5 + {5\over4} = 75.75}
+@infoline @expr{2*4 + 7*9.5 + 5/4 = 75.75}
+
+After computing the intermediate term
+@texline @math{2\times4 = 8},
+@infoline @expr{2*4 = 8},
+you can leave that result on the stack while you compute the second
+term. With both of these results waiting on the stack you can then
+compute the final term, then press @kbd{+ +} to add everything up.
+
+@smallexample
+@group
+2: 2 1: 8 3: 8 2: 8
+1: 4 . 2: 7 1: 66.5
+ . 1: 9.5 .
+ .
+
+ 2 @key{RET} 4 * 7 @key{RET} 9.5 *
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+4: 8 3: 8 2: 8 1: 75.75
+3: 66.5 2: 66.5 1: 67.75 .
+2: 5 1: 1.25 .
+1: 4 .
+ .
+
+ 5 @key{RET} 4 / + +
+@end group
+@end smallexample
+
+Alternatively, you could add the first two terms before going on
+with the third term.
+
+@smallexample
+@group
+2: 8 1: 74.5 3: 74.5 2: 74.5 1: 75.75
+1: 66.5 . 2: 5 1: 1.25 .
+ . 1: 4 .
+ .
+
+ ... + 5 @key{RET} 4 / +
+@end group
+@end smallexample
+
+On an old-style RPN calculator this second method would have the
+advantage of using only three stack levels. But since Calc's stack
+can grow arbitrarily large this isn't really an issue. Which method
+you choose is purely a matter of taste.
+
+@node RPN Answer 3, RPN Answer 4, RPN Answer 2, Answers to Exercises
+@subsection RPN Tutorial Exercise 3
+
+@noindent
+The @key{TAB} key provides a way to operate on the number in level 2.
+
+@smallexample
+@group
+3: 10 3: 10 4: 10 3: 10 3: 10
+2: 20 2: 30 3: 30 2: 30 2: 21
+1: 30 1: 20 2: 20 1: 21 1: 30
+ . . 1: 1 . .
+ .
+
+ @key{TAB} 1 + @key{TAB}
+@end group
+@end smallexample
+
+Similarly, @kbd{M-@key{TAB}} gives you access to the number in level 3.
+
+@smallexample
+@group
+3: 10 3: 21 3: 21 3: 30 3: 11
+2: 21 2: 30 2: 30 2: 11 2: 21
+1: 30 1: 10 1: 11 1: 21 1: 30
+ . . . . .
+
+ M-@key{TAB} 1 + M-@key{TAB} M-@key{TAB}
+@end group
+@end smallexample
+
+@node RPN Answer 4, Algebraic Answer 1, RPN Answer 3, Answers to Exercises
+@subsection RPN Tutorial Exercise 4
+
+@noindent
+Either @kbd{( 2 , 3 )} or @kbd{( 2 @key{SPC} 3 )} would have worked,
+but using both the comma and the space at once yields:
+
+@smallexample
+@group
+1: ( ... 2: ( ... 1: (2, ... 2: (2, ... 2: (2, ...
+ . 1: 2 . 1: (2, ... 1: (2, 3)
+ . . .
+
+ ( 2 , @key{SPC} 3 )
+@end group
+@end smallexample
+
+Joe probably tried to type @kbd{@key{TAB} @key{DEL}} to swap the
+extra incomplete object to the top of the stack and delete it.
+But a feature of Calc is that @key{DEL} on an incomplete object
+deletes just one component out of that object, so he had to press
+@key{DEL} twice to finish the job.
+
+@smallexample
+@group
+2: (2, ... 2: (2, 3) 2: (2, 3) 1: (2, 3)
+1: (2, 3) 1: (2, ... 1: ( ... .
+ . . .
+
+ @key{TAB} @key{DEL} @key{DEL}
+@end group
+@end smallexample
+
+(As it turns out, deleting the second-to-top stack entry happens often
+enough that Calc provides a special key, @kbd{M-@key{DEL}}, to do just that.
+@kbd{M-@key{DEL}} is just like @kbd{@key{TAB} @key{DEL}}, except that it doesn't exhibit
+the ``feature'' that tripped poor Joe.)
+
+@node Algebraic Answer 1, Algebraic Answer 2, RPN Answer 4, Answers to Exercises
+@subsection Algebraic Entry Tutorial Exercise 1
+
+@noindent
+Type @kbd{' sqrt($) @key{RET}}.
+
+If the @kbd{Q} key is broken, you could use @kbd{' $^0.5 @key{RET}}.
+Or, RPN style, @kbd{0.5 ^}.
+
+(Actually, @samp{$^1:2}, using the fraction one-half as the power, is
+a closer equivalent, since @samp{9^0.5} yields @expr{3.0} whereas
+@samp{sqrt(9)} and @samp{9^1:2} yield the exact integer @expr{3}.)
+
+@node Algebraic Answer 2, Algebraic Answer 3, Algebraic Answer 1, Answers to Exercises
+@subsection Algebraic Entry Tutorial Exercise 2
+
+@noindent
+In the formula @samp{2 x (1+y)}, @samp{x} was interpreted as a function
+name with @samp{1+y} as its argument. Assigning a value to a variable
+has no relation to a function by the same name. Joe needed to use an
+explicit @samp{*} symbol here: @samp{2 x*(1+y)}.
+
+@node Algebraic Answer 3, Modes Answer 1, Algebraic Answer 2, Answers to Exercises
+@subsection Algebraic Entry Tutorial Exercise 3
+
+@noindent
+The result from @kbd{1 @key{RET} 0 /} will be the formula @expr{1 / 0}.
+The ``function'' @samp{/} cannot be evaluated when its second argument
+is zero, so it is left in symbolic form. When you now type @kbd{0 *},
+the result will be zero because Calc uses the general rule that ``zero
+times anything is zero.''
+
+@c [fix-ref Infinities]
+The @kbd{m i} command enables an @dfn{Infinite mode} in which @expr{1 / 0}
+results in a special symbol that represents ``infinity.'' If you
+multiply infinity by zero, Calc uses another special new symbol to
+show that the answer is ``indeterminate.'' @xref{Infinities}, for
+further discussion of infinite and indeterminate values.
+
+@node Modes Answer 1, Modes Answer 2, Algebraic Answer 3, Answers to Exercises
+@subsection Modes Tutorial Exercise 1
+
+@noindent
+Calc always stores its numbers in decimal, so even though one-third has
+an exact base-3 representation (@samp{3#0.1}), it is still stored as
+0.3333333 (chopped off after 12 or however many decimal digits) inside
+the calculator's memory. When this inexact number is converted back
+to base 3 for display, it may still be slightly inexact. When we
+multiply this number by 3, we get 0.999999, also an inexact value.
+
+When Calc displays a number in base 3, it has to decide how many digits
+to show. If the current precision is 12 (decimal) digits, that corresponds
+to @samp{12 / log10(3) = 25.15} base-3 digits. Because 25.15 is not an
+exact integer, Calc shows only 25 digits, with the result that stored
+numbers carry a little bit of extra information that may not show up on
+the screen. When Joe entered @samp{3#0.2}, the stored number 0.666666
+happened to round to a pleasing value when it lost that last 0.15 of a
+digit, but it was still inexact in Calc's memory. When he divided by 2,
+he still got the dreaded inexact value 0.333333. (Actually, he divided
+0.666667 by 2 to get 0.333334, which is why he got something a little
+higher than @code{3#0.1} instead of a little lower.)
+
+If Joe didn't want to be bothered with all this, he could have typed
+@kbd{M-24 d n} to display with one less digit than the default. (If
+you give @kbd{d n} a negative argument, it uses default-minus-that,
+so @kbd{M-- d n} would be an easier way to get the same effect.) Those
+inexact results would still be lurking there, but they would now be
+rounded to nice, natural-looking values for display purposes. (Remember,
+@samp{0.022222} in base 3 is like @samp{0.099999} in base 10; rounding
+off one digit will round the number up to @samp{0.1}.) Depending on the
+nature of your work, this hiding of the inexactness may be a benefit or
+a danger. With the @kbd{d n} command, Calc gives you the choice.
+
+Incidentally, another consequence of all this is that if you type
+@kbd{M-30 d n} to display more digits than are ``really there,''
+you'll see garbage digits at the end of the number. (In decimal
+display mode, with decimally-stored numbers, these garbage digits are
+always zero so they vanish and you don't notice them.) Because Calc
+rounds off that 0.15 digit, there is the danger that two numbers could
+be slightly different internally but still look the same. If you feel
+uneasy about this, set the @kbd{d n} precision to be a little higher
+than normal; you'll get ugly garbage digits, but you'll always be able
+to tell two distinct numbers apart.
+
+An interesting side note is that most computers store their
+floating-point numbers in binary, and convert to decimal for display.
+Thus everyday programs have the same problem: Decimal 0.1 cannot be
+represented exactly in binary (try it: @kbd{0.1 d 2}), so @samp{0.1 * 10}
+comes out as an inexact approximation to 1 on some machines (though
+they generally arrange to hide it from you by rounding off one digit as
+we did above). Because Calc works in decimal instead of binary, you can
+be sure that numbers that look exact @emph{are} exact as long as you stay
+in decimal display mode.
+
+It's not hard to show that any number that can be represented exactly
+in binary, octal, or hexadecimal is also exact in decimal, so the kinds
+of problems we saw in this exercise are likely to be severe only when
+you use a relatively unusual radix like 3.
+
+@node Modes Answer 2, Modes Answer 3, Modes Answer 1, Answers to Exercises
+@subsection Modes Tutorial Exercise 2
+
+If the radix is 15 or higher, we can't use the letter @samp{e} to mark
+the exponent because @samp{e} is interpreted as a digit. When Calc
+needs to display scientific notation in a high radix, it writes
+@samp{16#F.E8F*16.^15}. You can enter a number like this as an
+algebraic entry. Also, pressing @kbd{e} without any digits before it
+normally types @kbd{1e}, but in a high radix it types @kbd{16.^} and
+puts you in algebraic entry: @kbd{16#f.e8f @key{RET} e 15 @key{RET} *} is another
+way to enter this number.
+
+The reason Calc puts a decimal point in the @samp{16.^} is to prevent
+huge integers from being generated if the exponent is large (consider
+@samp{16#1.23*16^1000}, where we compute @samp{16^1000} as a giant
+exact integer and then throw away most of the digits when we multiply
+it by the floating-point @samp{16#1.23}). While this wouldn't normally
+matter for display purposes, it could give you a nasty surprise if you
+copied that number into a file and later moved it back into Calc.
+
+@node Modes Answer 3, Modes Answer 4, Modes Answer 2, Answers to Exercises
+@subsection Modes Tutorial Exercise 3
+
+@noindent
+The answer he got was @expr{0.5000000000006399}.
+
+The problem is not that the square operation is inexact, but that the
+sine of 45 that was already on the stack was accurate to only 12 places.
+Arbitrary-precision calculations still only give answers as good as
+their inputs.
+
+The real problem is that there is no 12-digit number which, when
+squared, comes out to 0.5 exactly. The @kbd{f [} and @kbd{f ]}
+commands decrease or increase a number by one unit in the last
+place (according to the current precision). They are useful for
+determining facts like this.
+
+@smallexample
+@group
+1: 0.707106781187 1: 0.500000000001
+ . .
+
+ 45 S 2 ^
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: 0.707106781187 1: 0.707106781186 1: 0.499999999999
+ . . .
+
+ U @key{DEL} f [ 2 ^
+@end group
+@end smallexample
+
+A high-precision calculation must be carried out in high precision
+all the way. The only number in the original problem which was known
+exactly was the quantity 45 degrees, so the precision must be raised
+before anything is done after the number 45 has been entered in order
+for the higher precision to be meaningful.
+
+@node Modes Answer 4, Arithmetic Answer 1, Modes Answer 3, Answers to Exercises
+@subsection Modes Tutorial Exercise 4
+
+@noindent
+Many calculations involve real-world quantities, like the width and
+height of a piece of wood or the volume of a jar. Such quantities
+can't be measured exactly anyway, and if the data that is input to
+a calculation is inexact, doing exact arithmetic on it is a waste
+of time.
+
+Fractions become unwieldy after too many calculations have been
+done with them. For example, the sum of the reciprocals of the
+integers from 1 to 10 is 7381:2520. The sum from 1 to 30 is
+9304682830147:2329089562800. After a point it will take a long
+time to add even one more term to this sum, but a floating-point
+calculation of the sum will not have this problem.
+
+Also, rational numbers cannot express the results of all calculations.
+There is no fractional form for the square root of two, so if you type
+@w{@kbd{2 Q}}, Calc has no choice but to give you a floating-point answer.
+
+@node Arithmetic Answer 1, Arithmetic Answer 2, Modes Answer 4, Answers to Exercises
+@subsection Arithmetic Tutorial Exercise 1
+
+@noindent
+Dividing two integers that are larger than the current precision may
+give a floating-point result that is inaccurate even when rounded
+down to an integer. Consider @expr{123456789 / 2} when the current
+precision is 6 digits. The true answer is @expr{61728394.5}, but
+with a precision of 6 this will be rounded to
+@texline @math{12345700.0/2.0 = 61728500.0}.
+@infoline @expr{12345700.@: / 2.@: = 61728500.}.
+The result, when converted to an integer, will be off by 106.
+
+Here are two solutions: Raise the precision enough that the
+floating-point round-off error is strictly to the right of the
+decimal point. Or, convert to Fraction mode so that @expr{123456789 / 2}
+produces the exact fraction @expr{123456789:2}, which can be rounded
+down by the @kbd{F} command without ever switching to floating-point
+format.
+
+@node Arithmetic Answer 2, Vector Answer 1, Arithmetic Answer 1, Answers to Exercises
+@subsection Arithmetic Tutorial Exercise 2
+
+@noindent
+@kbd{27 @key{RET} 9 B} could give the exact result @expr{3:2}, but it
+does a floating-point calculation instead and produces @expr{1.5}.
+
+Calc will find an exact result for a logarithm if the result is an integer
+or (when in Fraction mode) the reciprocal of an integer. But there is
+no efficient way to search the space of all possible rational numbers
+for an exact answer, so Calc doesn't try.
+
+@node Vector Answer 1, Vector Answer 2, Arithmetic Answer 2, Answers to Exercises
+@subsection Vector Tutorial Exercise 1
+
+@noindent
+Duplicate the vector, compute its length, then divide the vector
+by its length: @kbd{@key{RET} A /}.
+
+@smallexample
+@group
+1: [1, 2, 3] 2: [1, 2, 3] 1: [0.27, 0.53, 0.80] 1: 1.
+ . 1: 3.74165738677 . .
+ .
+
+ r 1 @key{RET} A / A
+@end group
+@end smallexample
+
+The final @kbd{A} command shows that the normalized vector does
+indeed have unit length.
+
+@node Vector Answer 2, Matrix Answer 1, Vector Answer 1, Answers to Exercises
+@subsection Vector Tutorial Exercise 2
+
+@noindent
+The average position is equal to the sum of the products of the
+positions times their corresponding probabilities. This is the
+definition of the dot product operation. So all you need to do
+is to put the two vectors on the stack and press @kbd{*}.
+
+@node Matrix Answer 1, Matrix Answer 2, Vector Answer 2, Answers to Exercises
+@subsection Matrix Tutorial Exercise 1
+
+@noindent
+The trick is to multiply by a vector of ones. Use @kbd{r 4 [1 1 1] *} to
+get the row sum. Similarly, use @kbd{[1 1] r 4 *} to get the column sum.
+
+@node Matrix Answer 2, Matrix Answer 3, Matrix Answer 1, Answers to Exercises
+@subsection Matrix Tutorial Exercise 2
+
+@ifnottex
+@example
+@group
+ x + a y = 6
+ x + b y = 10
+@end group
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ \eqalign{ x &+ a y = 6 \cr
+ x &+ b y = 10}
+$$
+\afterdisplay
+@end tex
+
+Just enter the righthand side vector, then divide by the lefthand side
+matrix as usual.
+
+@smallexample
+@group
+1: [6, 10] 2: [6, 10] 1: [6 - 4 a / (b - a), 4 / (b - a) ]
+ . 1: [ [ 1, a ] .
+ [ 1, b ] ]
+ .
+
+' [6 10] @key{RET} ' [1 a; 1 b] @key{RET} /
+@end group
+@end smallexample
+
+This can be made more readable using @kbd{d B} to enable Big display
+mode:
+
+@smallexample
+@group
+ 4 a 4
+1: [6 - -----, -----]
+ b - a b - a
+@end group
+@end smallexample
+
+Type @kbd{d N} to return to Normal display mode afterwards.
+
+@node Matrix Answer 3, List Answer 1, Matrix Answer 2, Answers to Exercises
+@subsection Matrix Tutorial Exercise 3
+
+@noindent
+To solve
+@texline @math{A^T A \, X = A^T B},
+@infoline @expr{trn(A) * A * X = trn(A) * B},
+first we compute
+@texline @math{A' = A^T A}
+@infoline @expr{A2 = trn(A) * A}
+and
+@texline @math{B' = A^T B};
+@infoline @expr{B2 = trn(A) * B};
+now, we have a system
+@texline @math{A' X = B'}
+@infoline @expr{A2 * X = B2}
+which we can solve using Calc's @samp{/} command.
+
+@ifnottex
+@example
+@group
+ a + 2b + 3c = 6
+ 4a + 5b + 6c = 2
+ 7a + 6b = 3
+ 2a + 4b + 6c = 11
+@end group
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplayh
+$$ \openup1\jot \tabskip=0pt plus1fil
+\halign to\displaywidth{\tabskip=0pt
+ $\hfil#$&$\hfil{}#{}$&
+ $\hfil#$&$\hfil{}#{}$&
+ $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr
+ a&+&2b&+&3c&=6 \cr
+ 4a&+&5b&+&6c&=2 \cr
+ 7a&+&6b& & &=3 \cr
+ 2a&+&4b&+&6c&=11 \cr}
+$$
+\afterdisplayh
+@end tex
+
+The first step is to enter the coefficient matrix. We'll store it in
+quick variable number 7 for later reference. Next, we compute the
+@texline @math{B'}
+@infoline @expr{B2}
+vector.
+
+@smallexample
+@group
+1: [ [ 1, 2, 3 ] 2: [ [ 1, 4, 7, 2 ] 1: [57, 84, 96]
+ [ 4, 5, 6 ] [ 2, 5, 6, 4 ] .
+ [ 7, 6, 0 ] [ 3, 6, 0, 6 ] ]
+ [ 2, 4, 6 ] ] 1: [6, 2, 3, 11]
+ . .
+
+' [1 2 3; 4 5 6; 7 6 0; 2 4 6] @key{RET} s 7 v t [6 2 3 11] *
+@end group
+@end smallexample
+
+@noindent
+Now we compute the matrix
+@texline @math{A'}
+@infoline @expr{A2}
+and divide.
+
+@smallexample
+@group
+2: [57, 84, 96] 1: [-11.64, 14.08, -3.64]
+1: [ [ 70, 72, 39 ] .
+ [ 72, 81, 60 ]
+ [ 39, 60, 81 ] ]
+ .
+
+ r 7 v t r 7 * /
+@end group
+@end smallexample
+
+@noindent
+(The actual computed answer will be slightly inexact due to
+round-off error.)
+
+Notice that the answers are similar to those for the
+@texline @math{3\times3}
+@infoline 3x3
+system solved in the text. That's because the fourth equation that was
+added to the system is almost identical to the first one multiplied
+by two. (If it were identical, we would have gotten the exact same
+answer since the
+@texline @math{4\times3}
+@infoline 4x3
+system would be equivalent to the original
+@texline @math{3\times3}
+@infoline 3x3
+system.)
+
+Since the first and fourth equations aren't quite equivalent, they
+can't both be satisfied at once. Let's plug our answers back into
+the original system of equations to see how well they match.
+
+@smallexample
+@group
+2: [-11.64, 14.08, -3.64] 1: [5.6, 2., 3., 11.2]
+1: [ [ 1, 2, 3 ] .
+ [ 4, 5, 6 ]
+ [ 7, 6, 0 ]
+ [ 2, 4, 6 ] ]
+ .
+
+ r 7 @key{TAB} *
+@end group
+@end smallexample
+
+@noindent
+This is reasonably close to our original @expr{B} vector,
+@expr{[6, 2, 3, 11]}.
+
+@node List Answer 1, List Answer 2, Matrix Answer 3, Answers to Exercises
+@subsection List Tutorial Exercise 1
+
+@noindent
+We can use @kbd{v x} to build a vector of integers. This needs to be
+adjusted to get the range of integers we desire. Mapping @samp{-}
+across the vector will accomplish this, although it turns out the
+plain @samp{-} key will work just as well.
+
+@smallexample
+@group
+2: 2 2: 2
+1: [1, 2, 3, 4, 5, 6, 7, 8, 9] 1: [-4, -3, -2, -1, 0, 1, 2, 3, 4]
+ . .
+
+ 2 v x 9 @key{RET} 5 V M - or 5 -
+@end group
+@end smallexample
+
+@noindent
+Now we use @kbd{V M ^} to map the exponentiation operator across the
+vector.
+
+@smallexample
+@group
+1: [0.0625, 0.125, 0.25, 0.5, 1, 2, 4, 8, 16]
+ .
+
+ V M ^
+@end group
+@end smallexample
+
+@node List Answer 2, List Answer 3, List Answer 1, Answers to Exercises
+@subsection List Tutorial Exercise 2
+
+@noindent
+Given @expr{x} and @expr{y} vectors in quick variables 1 and 2 as before,
+the first job is to form the matrix that describes the problem.
+
+@ifnottex
+@example
+ m*x + b*1 = y
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ m \times x + b \times 1 = y $$
+\afterdisplay
+@end tex
+
+Thus we want a
+@texline @math{19\times2}
+@infoline 19x2
+matrix with our @expr{x} vector as one column and
+ones as the other column. So, first we build the column of ones, then
+we combine the two columns to form our @expr{A} matrix.
+
+@smallexample
+@group
+2: [1.34, 1.41, 1.49, ... ] 1: [ [ 1.34, 1 ]
+1: [1, 1, 1, ...] [ 1.41, 1 ]
+ . [ 1.49, 1 ]
+ @dots{}
+
+ r 1 1 v b 19 @key{RET} M-2 v p v t s 3
+@end group
+@end smallexample
+
+@noindent
+Now we compute
+@texline @math{A^T y}
+@infoline @expr{trn(A) * y}
+and
+@texline @math{A^T A}
+@infoline @expr{trn(A) * A}
+and divide.
+
+@smallexample
+@group
+1: [33.36554, 13.613] 2: [33.36554, 13.613]
+ . 1: [ [ 98.0003, 41.63 ]
+ [ 41.63, 19 ] ]
+ .
+
+ v t r 2 * r 3 v t r 3 *
+@end group
+@end smallexample
+
+@noindent
+(Hey, those numbers look familiar!)
+
+@smallexample
+@group
+1: [0.52141679, -0.425978]
+ .
+
+ /
+@end group
+@end smallexample
+
+Since we were solving equations of the form
+@texline @math{m \times x + b \times 1 = y},
+@infoline @expr{m*x + b*1 = y},
+these numbers should be @expr{m} and @expr{b}, respectively. Sure
+enough, they agree exactly with the result computed using @kbd{V M} and
+@kbd{V R}!
+
+The moral of this story: @kbd{V M} and @kbd{V R} will probably solve
+your problem, but there is often an easier way using the higher-level
+arithmetic functions!
+
+@c [fix-ref Curve Fitting]
+In fact, there is a built-in @kbd{a F} command that does least-squares
+fits. @xref{Curve Fitting}.
+
+@node List Answer 3, List Answer 4, List Answer 2, Answers to Exercises
+@subsection List Tutorial Exercise 3
+
+@noindent
+Move to one end of the list and press @kbd{C-@@} (or @kbd{C-@key{SPC}} or
+whatever) to set the mark, then move to the other end of the list
+and type @w{@kbd{C-x * g}}.
+
+@smallexample
+@group
+1: [2.3, 6, 22, 15.1, 7, 15, 14, 7.5, 2.5]
+ .
+@end group
+@end smallexample
+
+To make things interesting, let's assume we don't know at a glance
+how many numbers are in this list. Then we could type:
+
+@smallexample
+@group
+2: [2.3, 6, 22, ... ] 2: [2.3, 6, 22, ... ]
+1: [2.3, 6, 22, ... ] 1: 126356422.5
+ . .
+
+ @key{RET} V R *
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+2: 126356422.5 2: 126356422.5 1: 7.94652913734
+1: [2.3, 6, 22, ... ] 1: 9 .
+ . .
+
+ @key{TAB} v l I ^
+@end group
+@end smallexample
+
+@noindent
+(The @kbd{I ^} command computes the @var{n}th root of a number.
+You could also type @kbd{& ^} to take the reciprocal of 9 and
+then raise the number to that power.)
+
+@node List Answer 4, List Answer 5, List Answer 3, Answers to Exercises
+@subsection List Tutorial Exercise 4
+
+@noindent
+A number @expr{j} is a divisor of @expr{n} if
+@texline @math{n \mathbin{\hbox{\code{\%}}} j = 0}.
+@infoline @samp{n % j = 0}.
+The first step is to get a vector that identifies the divisors.
+
+@smallexample
+@group
+2: 30 2: [0, 0, 0, 2, ...] 1: [1, 1, 1, 0, ...]
+1: [1, 2, 3, 4, ...] 1: 0 .
+ . .
+
+ 30 @key{RET} v x 30 @key{RET} s 1 V M % 0 V M a = s 2
+@end group
+@end smallexample
+
+@noindent
+This vector has 1's marking divisors of 30 and 0's marking non-divisors.
+
+The zeroth divisor function is just the total number of divisors.
+The first divisor function is the sum of the divisors.
+
+@smallexample
+@group
+1: 8 3: 8 2: 8 2: 8
+ 2: [1, 2, 3, 4, ...] 1: [1, 2, 3, 0, ...] 1: 72
+ 1: [1, 1, 1, 0, ...] . .
+ .
+
+ V R + r 1 r 2 V M * V R +
+@end group
+@end smallexample
+
+@noindent
+Once again, the last two steps just compute a dot product for which
+a simple @kbd{*} would have worked equally well.
+
+@node List Answer 5, List Answer 6, List Answer 4, Answers to Exercises
+@subsection List Tutorial Exercise 5
+
+@noindent
+The obvious first step is to obtain the list of factors with @kbd{k f}.
+This list will always be in sorted order, so if there are duplicates
+they will be right next to each other. A suitable method is to compare
+the list with a copy of itself shifted over by one.
+
+@smallexample
+@group
+1: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19, 0]
+ . 1: [3, 7, 7, 7, 19, 0] 1: [0, 3, 7, 7, 7, 19]
+ . .
+
+ 19551 k f @key{RET} 0 | @key{TAB} 0 @key{TAB} |
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: [0, 0, 1, 1, 0, 0] 1: 2 1: 0
+ . . .
+
+ V M a = V R + 0 a =
+@end group
+@end smallexample
+
+@noindent
+Note that we have to arrange for both vectors to have the same length
+so that the mapping operation works; no prime factor will ever be
+zero, so adding zeros on the left and right is safe. From then on
+the job is pretty straightforward.
+
+Incidentally, Calc provides the
+@texline @dfn{M@"obius} @math{\mu}
+@infoline @dfn{Moebius mu}
+function which is zero if and only if its argument is square-free. It
+would be a much more convenient way to do the above test in practice.
+
+@node List Answer 6, List Answer 7, List Answer 5, Answers to Exercises
+@subsection List Tutorial Exercise 6
+
+@noindent
+First use @kbd{v x 6 @key{RET}} to get a list of integers, then @kbd{V M v x}
+to get a list of lists of integers!
+
+@node List Answer 7, List Answer 8, List Answer 6, Answers to Exercises
+@subsection List Tutorial Exercise 7
+
+@noindent
+Here's one solution. First, compute the triangular list from the previous
+exercise and type @kbd{1 -} to subtract one from all the elements.
+
+@smallexample
+@group
+1: [ [0],
+ [0, 1],
+ [0, 1, 2],
+ @dots{}
+
+ 1 -
+@end group
+@end smallexample
+
+The numbers down the lefthand edge of the list we desire are called
+the ``triangular numbers'' (now you know why!). The @expr{n}th
+triangular number is the sum of the integers from 1 to @expr{n}, and
+can be computed directly by the formula
+@texline @math{n (n+1) \over 2}.
+@infoline @expr{n * (n+1) / 2}.
+
+@smallexample
+@group
+2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ]
+1: [0, 1, 2, 3, 4, 5] 1: [0, 1, 3, 6, 10, 15]
+ . .
+
+ v x 6 @key{RET} 1 - V M ' $ ($+1)/2 @key{RET}
+@end group
+@end smallexample
+
+@noindent
+Adding this list to the above list of lists produces the desired
+result:
+
+@smallexample
+@group
+1: [ [0],
+ [1, 2],
+ [3, 4, 5],
+ [6, 7, 8, 9],
+ [10, 11, 12, 13, 14],
+ [15, 16, 17, 18, 19, 20] ]
+ .
+
+ V M +
+@end group
+@end smallexample
+
+If we did not know the formula for triangular numbers, we could have
+computed them using a @kbd{V U +} command. We could also have
+gotten them the hard way by mapping a reduction across the original
+triangular list.
+
+@smallexample
+@group
+2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ]
+1: [ [0], [0, 1], ... ] 1: [0, 1, 3, 6, 10, 15]
+ . .
+
+ @key{RET} V M V R +
+@end group
+@end smallexample
+
+@noindent
+(This means ``map a @kbd{V R +} command across the vector,'' and
+since each element of the main vector is itself a small vector,
+@kbd{V R +} computes the sum of its elements.)
+
+@node List Answer 8, List Answer 9, List Answer 7, Answers to Exercises
+@subsection List Tutorial Exercise 8
+
+@noindent
+The first step is to build a list of values of @expr{x}.
+
+@smallexample
+@group
+1: [1, 2, 3, ..., 21] 1: [0, 1, 2, ..., 20] 1: [0, 0.25, 0.5, ..., 5]
+ . . .
+
+ v x 21 @key{RET} 1 - 4 / s 1
+@end group
+@end smallexample
+
+Next, we compute the Bessel function values.
+
+@smallexample
+@group
+1: [0., 0.124, 0.242, ..., -0.328]
+ .
+
+ V M ' besJ(1,$) @key{RET}
+@end group
+@end smallexample
+
+@noindent
+(Another way to do this would be @kbd{1 @key{TAB} V M f j}.)
+
+A way to isolate the maximum value is to compute the maximum using
+@kbd{V R X}, then compare all the Bessel values with that maximum.
+
+@smallexample
+@group
+2: [0., 0.124, 0.242, ... ] 1: [0, 0, 0, ... ] 2: [0, 0, 0, ... ]
+1: 0.5801562 . 1: 1
+ . .
+
+ @key{RET} V R X V M a = @key{RET} V R + @key{DEL}
+@end group
+@end smallexample
+
+@noindent
+It's a good idea to verify, as in the last step above, that only
+one value is equal to the maximum. (After all, a plot of
+@texline @math{\sin x}
+@infoline @expr{sin(x)}
+might have many points all equal to the maximum value, 1.)
+
+The vector we have now has a single 1 in the position that indicates
+the maximum value of @expr{x}. Now it is a simple matter to convert
+this back into the corresponding value itself.
+
+@smallexample
+@group
+2: [0, 0, 0, ... ] 1: [0, 0., 0., ... ] 1: 1.75
+1: [0, 0.25, 0.5, ... ] . .
+ .
+
+ r 1 V M * V R +
+@end group
+@end smallexample
+
+If @kbd{a =} had produced more than one @expr{1} value, this method
+would have given the sum of all maximum @expr{x} values; not very
+useful! In this case we could have used @kbd{v m} (@code{calc-mask-vector})
+instead. This command deletes all elements of a ``data'' vector that
+correspond to zeros in a ``mask'' vector, leaving us with, in this
+example, a vector of maximum @expr{x} values.
+
+The built-in @kbd{a X} command maximizes a function using more
+efficient methods. Just for illustration, let's use @kbd{a X}
+to maximize @samp{besJ(1,x)} over this same interval.
+
+@smallexample
+@group
+2: besJ(1, x) 1: [1.84115, 0.581865]
+1: [0 .. 5] .
+ .
+
+' besJ(1,x), [0..5] @key{RET} a X x @key{RET}
+@end group
+@end smallexample
+
+@noindent
+The output from @kbd{a X} is a vector containing the value of @expr{x}
+that maximizes the function, and the function's value at that maximum.
+As you can see, our simple search got quite close to the right answer.
+
+@node List Answer 9, List Answer 10, List Answer 8, Answers to Exercises
+@subsection List Tutorial Exercise 9
+
+@noindent
+Step one is to convert our integer into vector notation.
+
+@smallexample
+@group
+1: 25129925999 3: 25129925999
+ . 2: 10
+ 1: [11, 10, 9, ..., 1, 0]
+ .
+
+ 25129925999 @key{RET} 10 @key{RET} 12 @key{RET} v x 12 @key{RET} -
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: 25129925999 1: [0, 2, 25, 251, 2512, ... ]
+2: [100000000000, ... ] .
+ .
+
+ V M ^ s 1 V M \
+@end group
+@end smallexample
+
+@noindent
+(Recall, the @kbd{\} command computes an integer quotient.)
+
+@smallexample
+@group
+1: [0, 2, 5, 1, 2, 9, 9, 2, 5, 9, 9, 9]
+ .
+
+ 10 V M % s 2
+@end group
+@end smallexample
+
+Next we must increment this number. This involves adding one to
+the last digit, plus handling carries. There is a carry to the
+left out of a digit if that digit is a nine and all the digits to
+the right of it are nines.
+
+@smallexample
+@group
+1: [0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 1, 1] 1: [1, 1, 1, 0, 0, 1, ... ]
+ . .
+
+ 9 V M a = v v
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: [1, 1, 1, 0, 0, 0, ... ] 1: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1]
+ . .
+
+ V U * v v 1 |
+@end group
+@end smallexample
+
+@noindent
+Accumulating @kbd{*} across a vector of ones and zeros will preserve
+only the initial run of ones. These are the carries into all digits
+except the rightmost digit. Concatenating a one on the right takes
+care of aligning the carries properly, and also adding one to the
+rightmost digit.
+
+@smallexample
+@group
+2: [0, 0, 0, 0, ... ] 1: [0, 0, 2, 5, 1, 2, 9, 9, 2, 6, 0, 0, 0]
+1: [0, 0, 2, 5, ... ] .
+ .
+
+ 0 r 2 | V M + 10 V M %
+@end group
+@end smallexample
+
+@noindent
+Here we have concatenated 0 to the @emph{left} of the original number;
+this takes care of shifting the carries by one with respect to the
+digits that generated them.
+
+Finally, we must convert this list back into an integer.
+
+@smallexample
+@group
+3: [0, 0, 2, 5, ... ] 2: [0, 0, 2, 5, ... ]
+2: 1000000000000 1: [1000000000000, 100000000000, ... ]
+1: [100000000000, ... ] .
+ .
+
+ 10 @key{RET} 12 ^ r 1 |
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: [0, 0, 20000000000, 5000000000, ... ] 1: 25129926000
+ . .
+
+ V M * V R +
+@end group
+@end smallexample
+
+@noindent
+Another way to do this final step would be to reduce the formula
+@w{@samp{10 $$ + $}} across the vector of digits.
+
+@smallexample
+@group
+1: [0, 0, 2, 5, ... ] 1: 25129926000
+ . .
+
+ V R ' 10 $$ + $ @key{RET}
+@end group
+@end smallexample
+
+@node List Answer 10, List Answer 11, List Answer 9, Answers to Exercises
+@subsection List Tutorial Exercise 10
+
+@noindent
+For the list @expr{[a, b, c, d]}, the result is @expr{((a = b) = c) = d},
+which will compare @expr{a} and @expr{b} to produce a 1 or 0, which is
+then compared with @expr{c} to produce another 1 or 0, which is then
+compared with @expr{d}. This is not at all what Joe wanted.
+
+Here's a more correct method:
+
+@smallexample
+@group
+1: [7, 7, 7, 8, 7] 2: [7, 7, 7, 8, 7]
+ . 1: 7
+ .
+
+ ' [7,7,7,8,7] @key{RET} @key{RET} v r 1 @key{RET}
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: [1, 1, 1, 0, 1] 1: 0
+ . .
+
+ V M a = V R *
+@end group
+@end smallexample
+
+@node List Answer 11, List Answer 12, List Answer 10, Answers to Exercises
+@subsection List Tutorial Exercise 11
+
+@noindent
+The circle of unit radius consists of those points @expr{(x,y)} for which
+@expr{x^2 + y^2 < 1}. We start by generating a vector of @expr{x^2}
+and a vector of @expr{y^2}.
+
+We can make this go a bit faster by using the @kbd{v .} and @kbd{t .}
+commands.
+
+@smallexample
+@group
+2: [2., 2., ..., 2.] 2: [2., 2., ..., 2.]
+1: [2., 2., ..., 2.] 1: [1.16, 1.98, ..., 0.81]
+ . .
+
+ v . t . 2. v b 100 @key{RET} @key{RET} V M k r
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+2: [2., 2., ..., 2.] 1: [0.026, 0.96, ..., 0.036]
+1: [0.026, 0.96, ..., 0.036] 2: [0.53, 0.81, ..., 0.094]
+ . .
+
+ 1 - 2 V M ^ @key{TAB} V M k r 1 - 2 V M ^
+@end group
+@end smallexample
+
+Now we sum the @expr{x^2} and @expr{y^2} values, compare with 1 to
+get a vector of 1/0 truth values, then sum the truth values.
+
+@smallexample
+@group
+1: [0.56, 1.78, ..., 0.13] 1: [1, 0, ..., 1] 1: 84
+ . . .
+
+ + 1 V M a < V R +
+@end group
+@end smallexample
+
+@noindent
+The ratio @expr{84/100} should approximate the ratio @cpiover{4}.
+
+@smallexample
+@group
+1: 0.84 1: 3.36 2: 3.36 1: 1.0695
+ . . 1: 3.14159 .
+
+ 100 / 4 * P /
+@end group
+@end smallexample
+
+@noindent
+Our estimate, 3.36, is off by about 7%. We could get a better estimate
+by taking more points (say, 1000), but it's clear that this method is
+not very efficient!
+
+(Naturally, since this example uses random numbers your own answer
+will be slightly different from the one shown here!)
+
+If you typed @kbd{v .} and @kbd{t .} before, type them again to
+return to full-sized display of vectors.
+
+@node List Answer 12, List Answer 13, List Answer 11, Answers to Exercises
+@subsection List Tutorial Exercise 12
+
+@noindent
+This problem can be made a lot easier by taking advantage of some
+symmetries. First of all, after some thought it's clear that the
+@expr{y} axis can be ignored altogether. Just pick a random @expr{x}
+component for one end of the match, pick a random direction
+@texline @math{\theta},
+@infoline @expr{theta},
+and see if @expr{x} and
+@texline @math{x + \cos \theta}
+@infoline @expr{x + cos(theta)}
+(which is the @expr{x} coordinate of the other endpoint) cross a line.
+The lines are at integer coordinates, so this happens when the two
+numbers surround an integer.
+
+Since the two endpoints are equivalent, we may as well choose the leftmost
+of the two endpoints as @expr{x}. Then @expr{theta} is an angle pointing
+to the right, in the range -90 to 90 degrees. (We could use radians, but
+it would feel like cheating to refer to @cpiover{2} radians while trying
+to estimate @cpi{}!)
+
+In fact, since the field of lines is infinite we can choose the
+coordinates 0 and 1 for the lines on either side of the leftmost
+endpoint. The rightmost endpoint will be between 0 and 1 if the
+match does not cross a line, or between 1 and 2 if it does. So:
+Pick random @expr{x} and
+@texline @math{\theta},
+@infoline @expr{theta},
+compute
+@texline @math{x + \cos \theta},
+@infoline @expr{x + cos(theta)},
+and count how many of the results are greater than one. Simple!
+
+We can make this go a bit faster by using the @kbd{v .} and @kbd{t .}
+commands.
+
+@smallexample
+@group
+1: [0.52, 0.71, ..., 0.72] 2: [0.52, 0.71, ..., 0.72]
+ . 1: [78.4, 64.5, ..., -42.9]
+ .
+
+v . t . 1. v b 100 @key{RET} V M k r 180. v b 100 @key{RET} V M k r 90 -
+@end group
+@end smallexample
+
+@noindent
+(The next step may be slow, depending on the speed of your computer.)
+
+@smallexample
+@group
+2: [0.52, 0.71, ..., 0.72] 1: [0.72, 1.14, ..., 1.45]
+1: [0.20, 0.43, ..., 0.73] .
+ .
+
+ m d V M C +
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: [0, 1, ..., 1] 1: 0.64 1: 3.125
+ . . .
+
+ 1 V M a > V R + 100 / 2 @key{TAB} /
+@end group
+@end smallexample
+
+Let's try the third method, too. We'll use random integers up to
+one million. The @kbd{k r} command with an integer argument picks
+a random integer.
+
+@smallexample
+@group
+2: [1000000, 1000000, ..., 1000000] 2: [78489, 527587, ..., 814975]
+1: [1000000, 1000000, ..., 1000000] 1: [324014, 358783, ..., 955450]
+ . .
+
+ 1000000 v b 100 @key{RET} @key{RET} V M k r @key{TAB} V M k r
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: [1, 1, ..., 25] 1: [1, 1, ..., 0] 1: 0.56
+ . . .
+
+ V M k g 1 V M a = V R + 100 /
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: 10.714 1: 3.273
+ . .
+
+ 6 @key{TAB} / Q
+@end group
+@end smallexample
+
+For a proof of this property of the GCD function, see section 4.5.2,
+exercise 10, of Knuth's @emph{Art of Computer Programming}, volume II.
+
+If you typed @kbd{v .} and @kbd{t .} before, type them again to
+return to full-sized display of vectors.
+
+@node List Answer 13, List Answer 14, List Answer 12, Answers to Exercises
+@subsection List Tutorial Exercise 13
+
+@noindent
+First, we put the string on the stack as a vector of ASCII codes.
+
+@smallexample
+@group
+1: [84, 101, 115, ..., 51]
+ .
+
+ "Testing, 1, 2, 3 @key{RET}
+@end group
+@end smallexample
+
+@noindent
+Note that the @kbd{"} key, like @kbd{$}, initiates algebraic entry so
+there was no need to type an apostrophe. Also, Calc didn't mind that
+we omitted the closing @kbd{"}. (The same goes for all closing delimiters
+like @kbd{)} and @kbd{]} at the end of a formula.
+
+We'll show two different approaches here. In the first, we note that
+if the input vector is @expr{[a, b, c, d]}, then the hash code is
+@expr{3 (3 (3a + b) + c) + d = 27a + 9b + 3c + d}. In other words,
+it's a sum of descending powers of three times the ASCII codes.
+
+@smallexample
+@group
+2: [84, 101, 115, ..., 51] 2: [84, 101, 115, ..., 51]
+1: 16 1: [15, 14, 13, ..., 0]
+ . .
+
+ @key{RET} v l v x 16 @key{RET} -
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+2: [84, 101, 115, ..., 51] 1: 1960915098 1: 121
+1: [14348907, ..., 1] . .
+ .
+
+ 3 @key{TAB} V M ^ * 511 %
+@end group
+@end smallexample
+
+@noindent
+Once again, @kbd{*} elegantly summarizes most of the computation.
+But there's an even more elegant approach: Reduce the formula
+@kbd{3 $$ + $} across the vector. Recall that this represents a
+function of two arguments that computes its first argument times three
+plus its second argument.
+
+@smallexample
+@group
+1: [84, 101, 115, ..., 51] 1: 1960915098
+ . .
+
+ "Testing, 1, 2, 3 @key{RET} V R ' 3$$+$ @key{RET}
+@end group
+@end smallexample
+
+@noindent
+If you did the decimal arithmetic exercise, this will be familiar.
+Basically, we're turning a base-3 vector of digits into an integer,
+except that our ``digits'' are much larger than real digits.
+
+Instead of typing @kbd{511 %} again to reduce the result, we can be
+cleverer still and notice that rather than computing a huge integer
+and taking the modulo at the end, we can take the modulo at each step
+without affecting the result. While this means there are more
+arithmetic operations, the numbers we operate on remain small so
+the operations are faster.
+
+@smallexample
+@group
+1: [84, 101, 115, ..., 51] 1: 121
+ . .
+
+ "Testing, 1, 2, 3 @key{RET} V R ' (3$$+$)%511 @key{RET}
+@end group
+@end smallexample
+
+Why does this work? Think about a two-step computation:
+@w{@expr{3 (3a + b) + c}}. Taking a result modulo 511 basically means
+subtracting off enough 511's to put the result in the desired range.
+So the result when we take the modulo after every step is,
+
+@ifnottex
+@example
+3 (3 a + b - 511 m) + c - 511 n
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ 3 (3 a + b - 511 m) + c - 511 n $$
+\afterdisplay
+@end tex
+
+@noindent
+for some suitable integers @expr{m} and @expr{n}. Expanding out by
+the distributive law yields
+
+@ifnottex
+@example
+9 a + 3 b + c - 511*3 m - 511 n
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ 9 a + 3 b + c - 511\times3 m - 511 n $$
+\afterdisplay
+@end tex
+
+@noindent
+The @expr{m} term in the latter formula is redundant because any
+contribution it makes could just as easily be made by the @expr{n}
+term. So we can take it out to get an equivalent formula with
+@expr{n' = 3m + n},
+
+@ifnottex
+@example
+9 a + 3 b + c - 511 n'
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ 9 a + 3 b + c - 511 n' $$
+\afterdisplay
+@end tex
+
+@noindent
+which is just the formula for taking the modulo only at the end of
+the calculation. Therefore the two methods are essentially the same.
+
+Later in the tutorial we will encounter @dfn{modulo forms}, which
+basically automate the idea of reducing every intermediate result
+modulo some value @var{m}.
+
+@node List Answer 14, Types Answer 1, List Answer 13, Answers to Exercises
+@subsection List Tutorial Exercise 14
+
+We want to use @kbd{H V U} to nest a function which adds a random
+step to an @expr{(x,y)} coordinate. The function is a bit long, but
+otherwise the problem is quite straightforward.
+
+@smallexample
+@group
+2: [0, 0] 1: [ [ 0, 0 ]
+1: 50 [ 0.4288, -0.1695 ]
+ . [ -0.4787, -0.9027 ]
+ ...
+
+ [0,0] 50 H V U ' <# + [random(2.0)-1, random(2.0)-1]> @key{RET}
+@end group
+@end smallexample
+
+Just as the text recommended, we used @samp{< >} nameless function
+notation to keep the two @code{random} calls from being evaluated
+before nesting even begins.
+
+We now have a vector of @expr{[x, y]} sub-vectors, which by Calc's
+rules acts like a matrix. We can transpose this matrix and unpack
+to get a pair of vectors, @expr{x} and @expr{y}, suitable for graphing.
+
+@smallexample
+@group
+2: [ 0, 0.4288, -0.4787, ... ]
+1: [ 0, -0.1696, -0.9027, ... ]
+ .
+
+ v t v u g f
+@end group
+@end smallexample
+
+Incidentally, because the @expr{x} and @expr{y} are completely
+independent in this case, we could have done two separate commands
+to create our @expr{x} and @expr{y} vectors of numbers directly.
+
+To make a random walk of unit steps, we note that @code{sincos} of
+a random direction exactly gives us an @expr{[x, y]} step of unit
+length; in fact, the new nesting function is even briefer, though
+we might want to lower the precision a bit for it.
+
+@smallexample
+@group
+2: [0, 0] 1: [ [ 0, 0 ]
+1: 50 [ 0.1318, 0.9912 ]
+ . [ -0.5965, 0.3061 ]
+ ...
+
+ [0,0] 50 m d p 6 @key{RET} H V U ' <# + sincos(random(360.0))> @key{RET}
+@end group
+@end smallexample
+
+Another @kbd{v t v u g f} sequence will graph this new random walk.
+
+An interesting twist on these random walk functions would be to use
+complex numbers instead of 2-vectors to represent points on the plane.
+In the first example, we'd use something like @samp{random + random*(0,1)},
+and in the second we could use polar complex numbers with random phase
+angles. (This exercise was first suggested in this form by Randal
+Schwartz.)
+
+@node Types Answer 1, Types Answer 2, List Answer 14, Answers to Exercises
+@subsection Types Tutorial Exercise 1
+
+@noindent
+If the number is the square root of @cpi{} times a rational number,
+then its square, divided by @cpi{}, should be a rational number.
+
+@smallexample
+@group
+1: 1.26508260337 1: 0.509433962268 1: 2486645810:4881193627
+ . . .
+
+ 2 ^ P / c F
+@end group
+@end smallexample
+
+@noindent
+Technically speaking this is a rational number, but not one that is
+likely to have arisen in the original problem. More likely, it just
+happens to be the fraction which most closely represents some
+irrational number to within 12 digits.
+
+But perhaps our result was not quite exact. Let's reduce the
+precision slightly and try again:
+
+@smallexample
+@group
+1: 0.509433962268 1: 27:53
+ . .
+
+ U p 10 @key{RET} c F
+@end group
+@end smallexample
+
+@noindent
+Aha! It's unlikely that an irrational number would equal a fraction
+this simple to within ten digits, so our original number was probably
+@texline @math{\sqrt{27 \pi / 53}}.
+@infoline @expr{sqrt(27 pi / 53)}.
+
+Notice that we didn't need to re-round the number when we reduced the
+precision. Remember, arithmetic operations always round their inputs
+to the current precision before they begin.
+
+@node Types Answer 2, Types Answer 3, Types Answer 1, Answers to Exercises
+@subsection Types Tutorial Exercise 2
+
+@noindent
+@samp{inf / inf = nan}. Perhaps @samp{1} is the ``obvious'' answer.
+But if @w{@samp{17 inf = inf}}, then @samp{17 inf / inf = inf / inf = 17}, too.
+
+@samp{exp(inf) = inf}. It's tempting to say that the exponential
+of infinity must be ``bigger'' than ``regular'' infinity, but as
+far as Calc is concerned all infinities are as just as big.
+In other words, as @expr{x} goes to infinity, @expr{e^x} also goes
+to infinity, but the fact the @expr{e^x} grows much faster than
+@expr{x} is not relevant here.
+
+@samp{exp(-inf) = 0}. Here we have a finite answer even though
+the input is infinite.
+
+@samp{sqrt(-inf) = (0, 1) inf}. Remember that @expr{(0, 1)}
+represents the imaginary number @expr{i}. Here's a derivation:
+@samp{sqrt(-inf) = @w{sqrt((-1) * inf)} = sqrt(-1) * sqrt(inf)}.
+The first part is, by definition, @expr{i}; the second is @code{inf}
+because, once again, all infinities are the same size.
+
+@samp{sqrt(uinf) = uinf}. In fact, we do know something about the
+direction because @code{sqrt} is defined to return a value in the
+right half of the complex plane. But Calc has no notation for this,
+so it settles for the conservative answer @code{uinf}.
+
+@samp{abs(uinf) = inf}. No matter which direction @expr{x} points,
+@samp{abs(x)} always points along the positive real axis.
+
+@samp{ln(0) = -inf}. Here we have an infinite answer to a finite
+input. As in the @expr{1 / 0} case, Calc will only use infinities
+here if you have turned on Infinite mode. Otherwise, it will
+treat @samp{ln(0)} as an error.
+
+@node Types Answer 3, Types Answer 4, Types Answer 2, Answers to Exercises
+@subsection Types Tutorial Exercise 3
+
+@noindent
+We can make @samp{inf - inf} be any real number we like, say,
+@expr{a}, just by claiming that we added @expr{a} to the first
+infinity but not to the second. This is just as true for complex
+values of @expr{a}, so @code{nan} can stand for a complex number.
+(And, similarly, @code{uinf} can stand for an infinity that points
+in any direction in the complex plane, such as @samp{(0, 1) inf}).
+
+In fact, we can multiply the first @code{inf} by two. Surely
+@w{@samp{2 inf - inf = inf}}, but also @samp{2 inf - inf = inf - inf = nan}.
+So @code{nan} can even stand for infinity. Obviously it's just
+as easy to make it stand for minus infinity as for plus infinity.
+
+The moral of this story is that ``infinity'' is a slippery fish
+indeed, and Calc tries to handle it by having a very simple model
+for infinities (only the direction counts, not the ``size''); but
+Calc is careful to write @code{nan} any time this simple model is
+unable to tell what the true answer is.
+
+@node Types Answer 4, Types Answer 5, Types Answer 3, Answers to Exercises
+@subsection Types Tutorial Exercise 4
+
+@smallexample
+@group
+2: 0@@ 47' 26" 1: 0@@ 2' 47.411765"
+1: 17 .
+ .
+
+ 0@@ 47' 26" @key{RET} 17 /
+@end group
+@end smallexample
+
+@noindent
+The average song length is two minutes and 47.4 seconds.
+
+@smallexample
+@group
+2: 0@@ 2' 47.411765" 1: 0@@ 3' 7.411765" 1: 0@@ 53' 6.000005"
+1: 0@@ 0' 20" . .
+ .
+
+ 20" + 17 *
+@end group
+@end smallexample
+
+@noindent
+The album would be 53 minutes and 6 seconds long.
+
+@node Types Answer 5, Types Answer 6, Types Answer 4, Answers to Exercises
+@subsection Types Tutorial Exercise 5
+
+@noindent
+Let's suppose it's January 14, 1991. The easiest thing to do is
+to keep trying 13ths of months until Calc reports a Friday.
+We can do this by manually entering dates, or by using @kbd{t I}:
+
+@smallexample
+@group
+1: <Wed Feb 13, 1991> 1: <Wed Mar 13, 1991> 1: <Sat Apr 13, 1991>
+ . . .
+
+ ' <2/13> @key{RET} @key{DEL} ' <3/13> @key{RET} t I
+@end group
+@end smallexample
+
+@noindent
+(Calc assumes the current year if you don't say otherwise.)
+
+This is getting tedious---we can keep advancing the date by typing
+@kbd{t I} over and over again, but let's automate the job by using
+vector mapping. The @kbd{t I} command actually takes a second
+``how-many-months'' argument, which defaults to one. This
+argument is exactly what we want to map over:
+
+@smallexample
+@group
+2: <Sat Apr 13, 1991> 1: [<Mon May 13, 1991>, <Thu Jun 13, 1991>,
+1: [1, 2, 3, 4, 5, 6] <Sat Jul 13, 1991>, <Tue Aug 13, 1991>,
+ . <Fri Sep 13, 1991>, <Sun Oct 13, 1991>]
+ .
+
+ v x 6 @key{RET} V M t I
+@end group
+@end smallexample
+
+@noindent
+Et voil@`a, September 13, 1991 is a Friday.
+
+@smallexample
+@group
+1: 242
+ .
+
+' <sep 13> - <jan 14> @key{RET}
+@end group
+@end smallexample
+
+@noindent
+And the answer to our original question: 242 days to go.
+
+@node Types Answer 6, Types Answer 7, Types Answer 5, Answers to Exercises
+@subsection Types Tutorial Exercise 6
+
+@noindent
+The full rule for leap years is that they occur in every year divisible
+by four, except that they don't occur in years divisible by 100, except
+that they @emph{do} in years divisible by 400. We could work out the
+answer by carefully counting the years divisible by four and the
+exceptions, but there is a much simpler way that works even if we
+don't know the leap year rule.
+
+Let's assume the present year is 1991. Years have 365 days, except
+that leap years (whenever they occur) have 366 days. So let's count
+the number of days between now and then, and compare that to the
+number of years times 365. The number of extra days we find must be
+equal to the number of leap years there were.
+
+@smallexample
+@group
+1: <Mon Jan 1, 10001> 2: <Mon Jan 1, 10001> 1: 2925593
+ . 1: <Tue Jan 1, 1991> .
+ .
+
+ ' <jan 1 10001> @key{RET} ' <jan 1 1991> @key{RET} -
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+3: 2925593 2: 2925593 2: 2925593 1: 1943
+2: 10001 1: 8010 1: 2923650 .
+1: 1991 . .
+ .
+
+ 10001 @key{RET} 1991 - 365 * -
+@end group
+@end smallexample
+
+@c [fix-ref Date Forms]
+@noindent
+There will be 1943 leap years before the year 10001. (Assuming,
+of course, that the algorithm for computing leap years remains
+unchanged for that long. @xref{Date Forms}, for some interesting
+background information in that regard.)
+
+@node Types Answer 7, Types Answer 8, Types Answer 6, Answers to Exercises
+@subsection Types Tutorial Exercise 7
+
+@noindent
+The relative errors must be converted to absolute errors so that
+@samp{+/-} notation may be used.
+
+@smallexample
+@group
+1: 1. 2: 1.
+ . 1: 0.2
+ .
+
+ 20 @key{RET} .05 * 4 @key{RET} .05 *
+@end group
+@end smallexample
+
+Now we simply chug through the formula.
+
+@smallexample
+@group
+1: 19.7392088022 1: 394.78 +/- 19.739 1: 6316.5 +/- 706.21
+ . . .
+
+ 2 P 2 ^ * 20 p 1 * 4 p .2 @key{RET} 2 ^ *
+@end group
+@end smallexample
+
+It turns out the @kbd{v u} command will unpack an error form as
+well as a vector. This saves us some retyping of numbers.
+
+@smallexample
+@group
+3: 6316.5 +/- 706.21 2: 6316.5 +/- 706.21
+2: 6316.5 1: 0.1118
+1: 706.21 .
+ .
+
+ @key{RET} v u @key{TAB} /
+@end group
+@end smallexample
+
+@noindent
+Thus the volume is 6316 cubic centimeters, within about 11 percent.
+
+@node Types Answer 8, Types Answer 9, Types Answer 7, Answers to Exercises
+@subsection Types Tutorial Exercise 8
+
+@noindent
+The first answer is pretty simple: @samp{1 / (0 .. 10) = (0.1 .. inf)}.
+Since a number in the interval @samp{(0 .. 10)} can get arbitrarily
+close to zero, its reciprocal can get arbitrarily large, so the answer
+is an interval that effectively means, ``any number greater than 0.1''
+but with no upper bound.
+
+The second answer, similarly, is @samp{1 / (-10 .. 0) = (-inf .. -0.1)}.
+
+Calc normally treats division by zero as an error, so that the formula
+@w{@samp{1 / 0}} is left unsimplified. Our third problem,
+@w{@samp{1 / [0 .. 10]}}, also (potentially) divides by zero because zero
+is now a member of the interval. So Calc leaves this one unevaluated, too.
+
+If you turn on Infinite mode by pressing @kbd{m i}, you will
+instead get the answer @samp{[0.1 .. inf]}, which includes infinity
+as a possible value.
+
+The fourth calculation, @samp{1 / (-10 .. 10)}, has the same problem.
+Zero is buried inside the interval, but it's still a possible value.
+It's not hard to see that the actual result of @samp{1 / (-10 .. 10)}
+will be either greater than @mathit{0.1}, or less than @mathit{-0.1}. Thus
+the interval goes from minus infinity to plus infinity, with a ``hole''
+in it from @mathit{-0.1} to @mathit{0.1}. Calc doesn't have any way to
+represent this, so it just reports @samp{[-inf .. inf]} as the answer.
+It may be disappointing to hear ``the answer lies somewhere between
+minus infinity and plus infinity, inclusive,'' but that's the best
+that interval arithmetic can do in this case.
+
+@node Types Answer 9, Types Answer 10, Types Answer 8, Answers to Exercises
+@subsection Types Tutorial Exercise 9
+
+@smallexample
+@group
+1: [-3 .. 3] 2: [-3 .. 3] 2: [0 .. 9]
+ . 1: [0 .. 9] 1: [-9 .. 9]
+ . .
+
+ [ 3 n .. 3 ] @key{RET} 2 ^ @key{TAB} @key{RET} *
+@end group
+@end smallexample
+
+@noindent
+In the first case the result says, ``if a number is between @mathit{-3} and
+3, its square is between 0 and 9.'' The second case says, ``the product
+of two numbers each between @mathit{-3} and 3 is between @mathit{-9} and 9.''
+
+An interval form is not a number; it is a symbol that can stand for
+many different numbers. Two identical-looking interval forms can stand
+for different numbers.
+
+The same issue arises when you try to square an error form.
+
+@node Types Answer 10, Types Answer 11, Types Answer 9, Answers to Exercises
+@subsection Types Tutorial Exercise 10
+
+@noindent
+Testing the first number, we might arbitrarily choose 17 for @expr{x}.
+
+@smallexample
+@group
+1: 17 mod 811749613 2: 17 mod 811749613 1: 533694123 mod 811749613
+ . 811749612 .
+ .
+
+ 17 M 811749613 @key{RET} 811749612 ^
+@end group
+@end smallexample
+
+@noindent
+Since 533694123 is (considerably) different from 1, the number 811749613
+must not be prime.
+
+It's awkward to type the number in twice as we did above. There are
+various ways to avoid this, and algebraic entry is one. In fact, using
+a vector mapping operation we can perform several tests at once. Let's
+use this method to test the second number.
+
+@smallexample
+@group
+2: [17, 42, 100000] 1: [1 mod 15485863, 1 mod ... ]
+1: 15485863 .
+ .
+
+ [17 42 100000] 15485863 @key{RET} V M ' ($$ mod $)^($-1) @key{RET}
+@end group
+@end smallexample
+
+@noindent
+The result is three ones (modulo @expr{n}), so it's very probable that
+15485863 is prime. (In fact, this number is the millionth prime.)
+
+Note that the functions @samp{($$^($-1)) mod $} or @samp{$$^($-1) % $}
+would have been hopelessly inefficient, since they would have calculated
+the power using full integer arithmetic.
+
+Calc has a @kbd{k p} command that does primality testing. For small
+numbers it does an exact test; for large numbers it uses a variant
+of the Fermat test we used here. You can use @kbd{k p} repeatedly
+to prove that a large integer is prime with any desired probability.
+
+@node Types Answer 11, Types Answer 12, Types Answer 10, Answers to Exercises
+@subsection Types Tutorial Exercise 11
+
+@noindent
+There are several ways to insert a calculated number into an HMS form.
+One way to convert a number of seconds to an HMS form is simply to
+multiply the number by an HMS form representing one second:
+
+@smallexample
+@group
+1: 31415926.5359 2: 31415926.5359 1: 8726@@ 38' 46.5359"
+ . 1: 0@@ 0' 1" .
+ .
+
+ P 1e7 * 0@@ 0' 1" *
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+2: 8726@@ 38' 46.5359" 1: 6@@ 6' 2.5359" mod 24@@ 0' 0"
+1: 15@@ 27' 16" mod 24@@ 0' 0" .
+ .
+
+ x time @key{RET} +
+@end group
+@end smallexample
+
+@noindent
+It will be just after six in the morning.
+
+The algebraic @code{hms} function can also be used to build an
+HMS form:
+
+@smallexample
+@group
+1: hms(0, 0, 10000000. pi) 1: 8726@@ 38' 46.5359"
+ . .
+
+ ' hms(0, 0, 1e7 pi) @key{RET} =
+@end group
+@end smallexample
+
+@noindent
+The @kbd{=} key is necessary to evaluate the symbol @samp{pi} to
+the actual number 3.14159...
+
+@node Types Answer 12, Types Answer 13, Types Answer 11, Answers to Exercises
+@subsection Types Tutorial Exercise 12
+
+@noindent
+As we recall, there are 17 songs of about 2 minutes and 47 seconds
+each.
+
+@smallexample
+@group
+2: 0@@ 2' 47" 1: [0@@ 3' 7" .. 0@@ 3' 47"]
+1: [0@@ 0' 20" .. 0@@ 1' 0"] .
+ .
+
+ [ 0@@ 20" .. 0@@ 1' ] +
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: [0@@ 52' 59." .. 1@@ 4' 19."]
+ .
+
+ 17 *
+@end group
+@end smallexample
+
+@noindent
+No matter how long it is, the album will fit nicely on one CD.
+
+@node Types Answer 13, Types Answer 14, Types Answer 12, Answers to Exercises
+@subsection Types Tutorial Exercise 13
+
+@noindent
+Type @kbd{' 1 yr @key{RET} u c s @key{RET}}. The answer is 31557600 seconds.
+
+@node Types Answer 14, Types Answer 15, Types Answer 13, Answers to Exercises
+@subsection Types Tutorial Exercise 14
+
+@noindent
+How long will it take for a signal to get from one end of the computer
+to the other?
+
+@smallexample
+@group
+1: m / c 1: 3.3356 ns
+ . .
+
+ ' 1 m / c @key{RET} u c ns @key{RET}
+@end group
+@end smallexample
+
+@noindent
+(Recall, @samp{c} is a ``unit'' corresponding to the speed of light.)
+
+@smallexample
+@group
+1: 3.3356 ns 1: 0.81356 ns / ns 1: 0.81356
+2: 4.1 ns . .
+ .
+
+ ' 4.1 ns @key{RET} / u s
+@end group
+@end smallexample
+
+@noindent
+Thus a signal could take up to 81 percent of a clock cycle just to
+go from one place to another inside the computer, assuming the signal
+could actually attain the full speed of light. Pretty tight!
+
+@node Types Answer 15, Algebra Answer 1, Types Answer 14, Answers to Exercises
+@subsection Types Tutorial Exercise 15
+
+@noindent
+The speed limit is 55 miles per hour on most highways. We want to
+find the ratio of Sam's speed to the US speed limit.
+
+@smallexample
+@group
+1: 55 mph 2: 55 mph 3: 11 hr mph / yd
+ . 1: 5 yd / hr .
+ .
+
+ ' 55 mph @key{RET} ' 5 yd/hr @key{RET} /
+@end group
+@end smallexample
+
+The @kbd{u s} command cancels out these units to get a plain
+number. Now we take the logarithm base two to find the final
+answer, assuming that each successive pill doubles his speed.
+
+@smallexample
+@group
+1: 19360. 2: 19360. 1: 14.24
+ . 1: 2 .
+ .
+
+ u s 2 B
+@end group
+@end smallexample
+
+@noindent
+Thus Sam can take up to 14 pills without a worry.
+
+@node Algebra Answer 1, Algebra Answer 2, Types Answer 15, Answers to Exercises
+@subsection Algebra Tutorial Exercise 1
+
+@noindent
+@c [fix-ref Declarations]
+The result @samp{sqrt(x)^2} is simplified back to @expr{x} by the
+Calculator, but @samp{sqrt(x^2)} is not. (Consider what happens
+if @w{@expr{x = -4}}.) If @expr{x} is real, this formula could be
+simplified to @samp{abs(x)}, but for general complex arguments even
+that is not safe. (@xref{Declarations}, for a way to tell Calc
+that @expr{x} is known to be real.)
+
+@node Algebra Answer 2, Algebra Answer 3, Algebra Answer 1, Answers to Exercises
+@subsection Algebra Tutorial Exercise 2
+
+@noindent
+Suppose our roots are @expr{[a, b, c]}. We want a polynomial which
+is zero when @expr{x} is any of these values. The trivial polynomial
+@expr{x-a} is zero when @expr{x=a}, so the product @expr{(x-a)(x-b)(x-c)}
+will do the job. We can use @kbd{a c x} to write this in a more
+familiar form.
+
+@smallexample
+@group
+1: 34 x - 24 x^3 1: [1.19023, -1.19023, 0]
+ . .
+
+ r 2 a P x @key{RET}
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: [x - 1.19023, x + 1.19023, x] 1: (x - 1.19023) (x + 1.19023) x
+ . .
+
+ V M ' x-$ @key{RET} V R *
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: x^3 - 1.41666 x 1: 34 x - 24 x^3
+ . .
+
+ a c x @key{RET} 24 n * a x
+@end group
+@end smallexample
+
+@noindent
+Sure enough, our answer (multiplied by a suitable constant) is the
+same as the original polynomial.
+
+@node Algebra Answer 3, Algebra Answer 4, Algebra Answer 2, Answers to Exercises
+@subsection Algebra Tutorial Exercise 3
+
+@smallexample
+@group
+1: x sin(pi x) 1: (sin(pi x) - pi x cos(pi x)) / pi^2
+ . .
+
+ ' x sin(pi x) @key{RET} m r a i x @key{RET}
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: [y, 1]
+2: (sin(pi x) - pi x cos(pi x)) / pi^2
+ .
+
+ ' [y,1] @key{RET} @key{TAB}
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: [(sin(pi y) - pi y cos(pi y)) / pi^2, (sin(pi) - pi cos(pi)) / pi^2]
+ .
+
+ V M $ @key{RET}
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: (sin(pi y) - pi y cos(pi y)) / pi^2 + (pi cos(pi) - sin(pi)) / pi^2
+ .
+
+ V R -
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: (sin(3.14159 y) - 3.14159 y cos(3.14159 y)) / 9.8696 - 0.3183
+ .
+
+ =
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: [0., -0.95493, 0.63662, -1.5915, 1.2732]
+ .
+
+ v x 5 @key{RET} @key{TAB} V M $ @key{RET}
+@end group
+@end smallexample
+
+@node Algebra Answer 4, Rewrites Answer 1, Algebra Answer 3, Answers to Exercises
+@subsection Algebra Tutorial Exercise 4
+
+@noindent
+The hard part is that @kbd{V R +} is no longer sufficient to add up all
+the contributions from the slices, since the slices have varying
+coefficients. So first we must come up with a vector of these
+coefficients. Here's one way:
+
+@smallexample
+@group
+2: -1 2: 3 1: [4, 2, ..., 4]
+1: [1, 2, ..., 9] 1: [-1, 1, ..., -1] .
+ . .
+
+ 1 n v x 9 @key{RET} V M ^ 3 @key{TAB} -
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: [4, 2, ..., 4, 1] 1: [1, 4, 2, ..., 4, 1]
+ . .
+
+ 1 | 1 @key{TAB} |
+@end group
+@end smallexample
+
+@noindent
+Now we compute the function values. Note that for this method we need
+eleven values, including both endpoints of the desired interval.
+
+@smallexample
+@group
+2: [1, 4, 2, ..., 4, 1]
+1: [1, 1.1, 1.2, ... , 1.8, 1.9, 2.]
+ .
+
+ 11 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+2: [1, 4, 2, ..., 4, 1]
+1: [0., 0.084941, 0.16993, ... ]
+ .
+
+ ' sin(x) ln(x) @key{RET} m r p 5 @key{RET} V M $ @key{RET}
+@end group
+@end smallexample
+
+@noindent
+Once again this calls for @kbd{V M * V R +}; a simple @kbd{*} does the
+same thing.
+
+@smallexample
+@group
+1: 11.22 1: 1.122 1: 0.374
+ . . .
+
+ * .1 * 3 /
+@end group
+@end smallexample
+
+@noindent
+Wow! That's even better than the result from the Taylor series method.
+
+@node Rewrites Answer 1, Rewrites Answer 2, Algebra Answer 4, Answers to Exercises
+@subsection Rewrites Tutorial Exercise 1
+
+@noindent
+We'll use Big mode to make the formulas more readable.
+
+@smallexample
+@group
+ ___
+ 2 + V 2
+1: (2 + sqrt(2)) / (1 + sqrt(2)) 1: --------
+ . ___
+ 1 + V 2
+
+ .
+
+ ' (2+sqrt(2)) / (1+sqrt(2)) @key{RET} d B
+@end group
+@end smallexample
+
+@noindent
+Multiplying by the conjugate helps because @expr{(a+b) (a-b) = a^2 - b^2}.
+
+@smallexample
+@group
+ ___ ___
+1: (2 + V 2 ) (V 2 - 1)
+ .
+
+ a r a/(b+c) := a*(b-c) / (b^2-c^2) @key{RET}
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+ ___ ___
+1: 2 + V 2 - 2 1: V 2
+ . .
+
+ a r a*(b+c) := a*b + a*c a s
+@end group
+@end smallexample
+
+@noindent
+(We could have used @kbd{a x} instead of a rewrite rule for the
+second step.)
+
+The multiply-by-conjugate rule turns out to be useful in many
+different circumstances, such as when the denominator involves
+sines and cosines or the imaginary constant @code{i}.
+
+@node Rewrites Answer 2, Rewrites Answer 3, Rewrites Answer 1, Answers to Exercises
+@subsection Rewrites Tutorial Exercise 2
+
+@noindent
+Here is the rule set:
+
+@smallexample
+@group
+[ fib(n) := fib(n, 1, 1) :: integer(n) :: n >= 1,
+ fib(1, x, y) := x,
+ fib(n, x, y) := fib(n-1, y, x+y) ]
+@end group
+@end smallexample
+
+@noindent
+The first rule turns a one-argument @code{fib} that people like to write
+into a three-argument @code{fib} that makes computation easier. The
+second rule converts back from three-argument form once the computation
+is done. The third rule does the computation itself. It basically
+says that if @expr{x} and @expr{y} are two consecutive Fibonacci numbers,
+then @expr{y} and @expr{x+y} are the next (overlapping) pair of Fibonacci
+numbers.
+
+Notice that because the number @expr{n} was ``validated'' by the
+conditions on the first rule, there is no need to put conditions on
+the other rules because the rule set would never get that far unless
+the input were valid. That further speeds computation, since no
+extra conditions need to be checked at every step.
+
+Actually, a user with a nasty sense of humor could enter a bad
+three-argument @code{fib} call directly, say, @samp{fib(0, 1, 1)},
+which would get the rules into an infinite loop. One thing that would
+help keep this from happening by accident would be to use something like
+@samp{ZzFib} instead of @code{fib} as the name of the three-argument
+function.
+
+@node Rewrites Answer 3, Rewrites Answer 4, Rewrites Answer 2, Answers to Exercises
+@subsection Rewrites Tutorial Exercise 3
+
+@noindent
+He got an infinite loop. First, Calc did as expected and rewrote
+@w{@samp{2 + 3 x}} to @samp{f(2, 3, x)}. Then it looked for ways to
+apply the rule again, and found that @samp{f(2, 3, x)} looks like
+@samp{a + b x} with @w{@samp{a = 0}} and @samp{b = 1}, so it rewrote to
+@samp{f(0, 1, f(2, 3, x))}. It then wrapped another @samp{f(0, 1, ...)}
+around that, and so on, ad infinitum. Joe should have used @kbd{M-1 a r}
+to make sure the rule applied only once.
+
+(Actually, even the first step didn't work as he expected. What Calc
+really gives for @kbd{M-1 a r} in this situation is @samp{f(3 x, 1, 2)},
+treating 2 as the ``variable,'' and @samp{3 x} as a constant being added
+to it. While this may seem odd, it's just as valid a solution as the
+``obvious'' one. One way to fix this would be to add the condition
+@samp{:: variable(x)} to the rule, to make sure the thing that matches
+@samp{x} is indeed a variable, or to change @samp{x} to @samp{quote(x)}
+on the lefthand side, so that the rule matches the actual variable
+@samp{x} rather than letting @samp{x} stand for something else.)
+
+@node Rewrites Answer 4, Rewrites Answer 5, Rewrites Answer 3, Answers to Exercises
+@subsection Rewrites Tutorial Exercise 4
+
+@noindent
+@ignore
+@starindex
+@end ignore
+@tindex seq
+Here is a suitable set of rules to solve the first part of the problem:
+
+@smallexample
+@group
+[ seq(n, c) := seq(n/2, c+1) :: n%2 = 0,
+ seq(n, c) := seq(3n+1, c+1) :: n%2 = 1 :: n > 1 ]
+@end group
+@end smallexample
+
+Given the initial formula @samp{seq(6, 0)}, application of these
+rules produces the following sequence of formulas:
+
+@example
+seq( 3, 1)
+seq(10, 2)
+seq( 5, 3)
+seq(16, 4)
+seq( 8, 5)
+seq( 4, 6)
+seq( 2, 7)
+seq( 1, 8)
+@end example
+
+@noindent
+whereupon neither of the rules match, and rewriting stops.
+
+We can pretty this up a bit with a couple more rules:
+
+@smallexample
+@group
+[ seq(n) := seq(n, 0),
+ seq(1, c) := c,
+ ... ]
+@end group
+@end smallexample
+
+@noindent
+Now, given @samp{seq(6)} as the starting configuration, we get 8
+as the result.
+
+The change to return a vector is quite simple:
+
+@smallexample
+@group
+[ seq(n) := seq(n, []) :: integer(n) :: n > 0,
+ seq(1, v) := v | 1,
+ seq(n, v) := seq(n/2, v | n) :: n%2 = 0,
+ seq(n, v) := seq(3n+1, v | n) :: n%2 = 1 ]
+@end group
+@end smallexample
+
+@noindent
+Given @samp{seq(6)}, the result is @samp{[6, 3, 10, 5, 16, 8, 4, 2, 1]}.
+
+Notice that the @expr{n > 1} guard is no longer necessary on the last
+rule since the @expr{n = 1} case is now detected by another rule.
+But a guard has been added to the initial rule to make sure the
+initial value is suitable before the computation begins.
+
+While still a good idea, this guard is not as vitally important as it
+was for the @code{fib} function, since calling, say, @samp{seq(x, [])}
+will not get into an infinite loop. Calc will not be able to prove
+the symbol @samp{x} is either even or odd, so none of the rules will
+apply and the rewrites will stop right away.
+
+@node Rewrites Answer 5, Rewrites Answer 6, Rewrites Answer 4, Answers to Exercises
+@subsection Rewrites Tutorial Exercise 5
+
+@noindent
+@ignore
+@starindex
+@end ignore
+@tindex nterms
+If @expr{x} is the sum @expr{a + b}, then `@tfn{nterms(}@var{x}@tfn{)}' must
+be `@tfn{nterms(}@var{a}@tfn{)}' plus `@tfn{nterms(}@var{b}@tfn{)}'. If @expr{x}
+is not a sum, then `@tfn{nterms(}@var{x}@tfn{)}' = 1.
+
+@smallexample
+@group
+[ nterms(a + b) := nterms(a) + nterms(b),
+ nterms(x) := 1 ]
+@end group
+@end smallexample
+
+@noindent
+Here we have taken advantage of the fact that earlier rules always
+match before later rules; @samp{nterms(x)} will only be tried if we
+already know that @samp{x} is not a sum.
+
+@node Rewrites Answer 6, Programming Answer 1, Rewrites Answer 5, Answers to Exercises
+@subsection Rewrites Tutorial Exercise 6
+
+@noindent
+Here is a rule set that will do the job:
+
+@smallexample
+@group
+[ a*(b + c) := a*b + a*c,
+ opt(a) O(x^n) + opt(b) O(x^m) := O(x^n) :: n <= m
+ :: constant(a) :: constant(b),
+ opt(a) O(x^n) + opt(b) x^m := O(x^n) :: n <= m
+ :: constant(a) :: constant(b),
+ a O(x^n) := O(x^n) :: constant(a),
+ x^opt(m) O(x^n) := O(x^(n+m)),
+ O(x^n) O(x^m) := O(x^(n+m)) ]
+@end group
+@end smallexample
+
+If we really want the @kbd{+} and @kbd{*} keys to operate naturally
+on power series, we should put these rules in @code{EvalRules}. For
+testing purposes, it is better to put them in a different variable,
+say, @code{O}, first.
+
+The first rule just expands products of sums so that the rest of the
+rules can assume they have an expanded-out polynomial to work with.
+Note that this rule does not mention @samp{O} at all, so it will
+apply to any product-of-sum it encounters---this rule may surprise
+you if you put it into @code{EvalRules}!
+
+In the second rule, the sum of two O's is changed to the smaller O.
+The optional constant coefficients are there mostly so that
+@samp{O(x^2) - O(x^3)} and @samp{O(x^3) - O(x^2)} are handled
+as well as @samp{O(x^2) + O(x^3)}.
+
+The third rule absorbs higher powers of @samp{x} into O's.
+
+The fourth rule says that a constant times a negligible quantity
+is still negligible. (This rule will also match @samp{O(x^3) / 4},
+with @samp{a = 1/4}.)
+
+The fifth rule rewrites, for example, @samp{x^2 O(x^3)} to @samp{O(x^5)}.
+(It is easy to see that if one of these forms is negligible, the other
+is, too.) Notice the @samp{x^opt(m)} to pick up terms like
+@w{@samp{x O(x^3)}}. Optional powers will match @samp{x} as @samp{x^1}
+but not 1 as @samp{x^0}. This turns out to be exactly what we want here.
+
+The sixth rule is the corresponding rule for products of two O's.
+
+Another way to solve this problem would be to create a new ``data type''
+that represents truncated power series. We might represent these as
+function calls @samp{series(@var{coefs}, @var{x})} where @var{coefs} is
+a vector of coefficients for @expr{x^0}, @expr{x^1}, @expr{x^2}, and so
+on. Rules would exist for sums and products of such @code{series}
+objects, and as an optional convenience could also know how to combine a
+@code{series} object with a normal polynomial. (With this, and with a
+rule that rewrites @samp{O(x^n)} to the equivalent @code{series} form,
+you could still enter power series in exactly the same notation as
+before.) Operations on such objects would probably be more efficient,
+although the objects would be a bit harder to read.
+
+@c [fix-ref Compositions]
+Some other symbolic math programs provide a power series data type
+similar to this. Mathematica, for example, has an object that looks
+like @samp{PowerSeries[@var{x}, @var{x0}, @var{coefs}, @var{nmin},
+@var{nmax}, @var{den}]}, where @var{x0} is the point about which the
+power series is taken (we've been assuming this was always zero),
+and @var{nmin}, @var{nmax}, and @var{den} allow pseudo-power-series
+with fractional or negative powers. Also, the @code{PowerSeries}
+objects have a special display format that makes them look like
+@samp{2 x^2 + O(x^4)} when they are printed out. (@xref{Compositions},
+for a way to do this in Calc, although for something as involved as
+this it would probably be better to write the formatting routine
+in Lisp.)
+
+@node Programming Answer 1, Programming Answer 2, Rewrites Answer 6, Answers to Exercises
+@subsection Programming Tutorial Exercise 1
+
+@noindent
+Just enter the formula @samp{ninteg(sin(t)/t, t, 0, x)}, type
+@kbd{Z F}, and answer the questions. Since this formula contains two
+variables, the default argument list will be @samp{(t x)}. We want to
+change this to @samp{(x)} since @expr{t} is really a dummy variable
+to be used within @code{ninteg}.
+
+The exact keystrokes are @kbd{Z F s Si @key{RET} @key{RET} C-b C-b @key{DEL} @key{DEL} @key{RET} y}.
+(The @kbd{C-b C-b @key{DEL} @key{DEL}} are what fix the argument list.)
+
+@node Programming Answer 2, Programming Answer 3, Programming Answer 1, Answers to Exercises
+@subsection Programming Tutorial Exercise 2
+
+@noindent
+One way is to move the number to the top of the stack, operate on
+it, then move it back: @kbd{C-x ( M-@key{TAB} n M-@key{TAB} M-@key{TAB} C-x )}.
+
+Another way is to negate the top three stack entries, then negate
+again the top two stack entries: @kbd{C-x ( M-3 n M-2 n C-x )}.
+
+Finally, it turns out that a negative prefix argument causes a
+command like @kbd{n} to operate on the specified stack entry only,
+which is just what we want: @kbd{C-x ( M-- 3 n C-x )}.
+
+Just for kicks, let's also do it algebraically:
+@w{@kbd{C-x ( ' -$$$, $$, $ @key{RET} C-x )}}.
+
+@node Programming Answer 3, Programming Answer 4, Programming Answer 2, Answers to Exercises
+@subsection Programming Tutorial Exercise 3
+
+@noindent
+Each of these functions can be computed using the stack, or using
+algebraic entry, whichever way you prefer:
+
+@noindent
+Computing
+@texline @math{\displaystyle{\sin x \over x}}:
+@infoline @expr{sin(x) / x}:
+
+Using the stack: @kbd{C-x ( @key{RET} S @key{TAB} / C-x )}.
+
+Using algebraic entry: @kbd{C-x ( ' sin($)/$ @key{RET} C-x )}.
+
+@noindent
+Computing the logarithm:
+
+Using the stack: @kbd{C-x ( @key{TAB} B C-x )}
+
+Using algebraic entry: @kbd{C-x ( ' log($,$$) @key{RET} C-x )}.
+
+@noindent
+Computing the vector of integers:
+
+Using the stack: @kbd{C-x ( 1 @key{RET} 1 C-u v x C-x )}. (Recall that
+@kbd{C-u v x} takes the vector size, starting value, and increment
+from the stack.)
+
+Alternatively: @kbd{C-x ( ~ v x C-x )}. (The @kbd{~} key pops a
+number from the stack and uses it as the prefix argument for the
+next command.)
+
+Using algebraic entry: @kbd{C-x ( ' index($) @key{RET} C-x )}.
+
+@node Programming Answer 4, Programming Answer 5, Programming Answer 3, Answers to Exercises
+@subsection Programming Tutorial Exercise 4
+
+@noindent
+Here's one way: @kbd{C-x ( @key{RET} V R + @key{TAB} v l / C-x )}.
+
+@node Programming Answer 5, Programming Answer 6, Programming Answer 4, Answers to Exercises
+@subsection Programming Tutorial Exercise 5
+
+@smallexample
+@group
+2: 1 1: 1.61803398502 2: 1.61803398502
+1: 20 . 1: 1.61803398875
+ . .
+
+ 1 @key{RET} 20 Z < & 1 + Z > I H P
+@end group
+@end smallexample
+
+@noindent
+This answer is quite accurate.
+
+@node Programming Answer 6, Programming Answer 7, Programming Answer 5, Answers to Exercises
+@subsection Programming Tutorial Exercise 6
+
+@noindent
+Here is the matrix:
+
+@example
+[ [ 0, 1 ] * [a, b] = [b, a + b]
+ [ 1, 1 ] ]
+@end example
+
+@noindent
+Thus @samp{[0, 1; 1, 1]^n * [1, 1]} computes Fibonacci numbers @expr{n+1}
+and @expr{n+2}. Here's one program that does the job:
+
+@example
+C-x ( ' [0, 1; 1, 1] ^ ($-1) * [1, 1] @key{RET} v u @key{DEL} C-x )
+@end example
+
+@noindent
+This program is quite efficient because Calc knows how to raise a
+matrix (or other value) to the power @expr{n} in only
+@texline @math{\log_2 n}
+@infoline @expr{log(n,2)}
+steps. For example, this program can compute the 1000th Fibonacci
+number (a 209-digit integer!) in about 10 steps; even though the
+@kbd{Z < ... Z >} solution had much simpler steps, it would have
+required so many steps that it would not have been practical.
+
+@node Programming Answer 7, Programming Answer 8, Programming Answer 6, Answers to Exercises
+@subsection Programming Tutorial Exercise 7
+
+@noindent
+The trick here is to compute the harmonic numbers differently, so that
+the loop counter itself accumulates the sum of reciprocals. We use
+a separate variable to hold the integer counter.
+
+@smallexample
+@group
+1: 1 2: 1 1: .
+ . 1: 4
+ .
+
+ 1 t 1 1 @key{RET} 4 Z ( t 2 r 1 1 + s 1 & Z )
+@end group
+@end smallexample
+
+@noindent
+The body of the loop goes as follows: First save the harmonic sum
+so far in variable 2. Then delete it from the stack; the for loop
+itself will take care of remembering it for us. Next, recall the
+count from variable 1, add one to it, and feed its reciprocal to
+the for loop to use as the step value. The for loop will increase
+the ``loop counter'' by that amount and keep going until the
+loop counter exceeds 4.
+
+@smallexample
+@group
+2: 31 3: 31
+1: 3.99498713092 2: 3.99498713092
+ . 1: 4.02724519544
+ .
+
+ r 1 r 2 @key{RET} 31 & +
+@end group
+@end smallexample
+
+Thus we find that the 30th harmonic number is 3.99, and the 31st
+harmonic number is 4.02.
+
+@node Programming Answer 8, Programming Answer 9, Programming Answer 7, Answers to Exercises
+@subsection Programming Tutorial Exercise 8
+
+@noindent
+The first step is to compute the derivative @expr{f'(x)} and thus
+the formula
+@texline @math{\displaystyle{x - {f(x) \over f'(x)}}}.
+@infoline @expr{x - f(x)/f'(x)}.
+
+(Because this definition is long, it will be repeated in concise form
+below. You can use @w{@kbd{C-x * m}} to load it from there. While you are
+entering a @kbd{Z ` Z '} body in a macro, Calc simply collects
+keystrokes without executing them. In the following diagrams we'll
+pretend Calc actually executed the keystrokes as you typed them,
+just for purposes of illustration.)
+
+@smallexample
+@group
+2: sin(cos(x)) - 0.5 3: 4.5
+1: 4.5 2: sin(cos(x)) - 0.5
+ . 1: -(sin(x) cos(cos(x)))
+ .
+
+' sin(cos(x))-0.5 @key{RET} 4.5 m r C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET}
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+2: 4.5
+1: x + (sin(cos(x)) - 0.5) / sin(x) cos(cos(x))
+ .
+
+ / ' x @key{RET} @key{TAB} - t 1
+@end group
+@end smallexample
+
+Now, we enter the loop. We'll use a repeat loop with a 20-repetition
+limit just in case the method fails to converge for some reason.
+(Normally, the @w{@kbd{Z /}} command will stop the loop before all 20
+repetitions are done.)
+
+@smallexample
+@group
+1: 4.5 3: 4.5 2: 4.5
+ . 2: x + (sin(cos(x)) ... 1: 5.24196456928
+ 1: 4.5 .
+ .
+
+ 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET}
+@end group
+@end smallexample
+
+This is the new guess for @expr{x}. Now we compare it with the
+old one to see if we've converged.
+
+@smallexample
+@group
+3: 5.24196 2: 5.24196 1: 5.24196 1: 5.26345856348
+2: 5.24196 1: 0 . .
+1: 4.5 .
+ .
+
+ @key{RET} M-@key{TAB} a = Z / Z > Z ' C-x )
+@end group
+@end smallexample
+
+The loop converges in just a few steps to this value. To check
+the result, we can simply substitute it back into the equation.
+
+@smallexample
+@group
+2: 5.26345856348
+1: 0.499999999997
+ .
+
+ @key{RET} ' sin(cos($)) @key{RET}
+@end group
+@end smallexample
+
+Let's test the new definition again:
+
+@smallexample
+@group
+2: x^2 - 9 1: 3.
+1: 1 .
+ .
+
+ ' x^2-9 @key{RET} 1 X
+@end group
+@end smallexample
+
+Once again, here's the full Newton's Method definition:
+
+@example
+@group
+C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET} / ' x @key{RET} @key{TAB} - t 1
+ 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET}
+ @key{RET} M-@key{TAB} a = Z /
+ Z >
+ Z '
+C-x )
+@end group
+@end example
+
+@c [fix-ref Nesting and Fixed Points]
+It turns out that Calc has a built-in command for applying a formula
+repeatedly until it converges to a number. @xref{Nesting and Fixed Points},
+to see how to use it.
+
+@c [fix-ref Root Finding]
+Also, of course, @kbd{a R} is a built-in command that uses Newton's
+method (among others) to look for numerical solutions to any equation.
+@xref{Root Finding}.
+
+@node Programming Answer 9, Programming Answer 10, Programming Answer 8, Answers to Exercises
+@subsection Programming Tutorial Exercise 9
+
+@noindent
+The first step is to adjust @expr{z} to be greater than 5. A simple
+``for'' loop will do the job here. If @expr{z} is less than 5, we
+reduce the problem using
+@texline @math{\psi(z) = \psi(z+1) - 1/z}.
+@infoline @expr{psi(z) = psi(z+1) - 1/z}. We go
+on to compute
+@texline @math{\psi(z+1)},
+@infoline @expr{psi(z+1)},
+and remember to add back a factor of @expr{-1/z} when we're done. This
+step is repeated until @expr{z > 5}.
+
+(Because this definition is long, it will be repeated in concise form
+below. You can use @w{@kbd{C-x * m}} to load it from there. While you are
+entering a @kbd{Z ` Z '} body in a macro, Calc simply collects
+keystrokes without executing them. In the following diagrams we'll
+pretend Calc actually executed the keystrokes as you typed them,
+just for purposes of illustration.)
+
+@smallexample
+@group
+1: 1. 1: 1.
+ . .
+
+ 1.0 @key{RET} C-x ( Z ` s 1 0 t 2
+@end group
+@end smallexample
+
+Here, variable 1 holds @expr{z} and variable 2 holds the adjustment
+factor. If @expr{z < 5}, we use a loop to increase it.
+
+(By the way, we started with @samp{1.0} instead of the integer 1 because
+otherwise the calculation below will try to do exact fractional arithmetic,
+and will never converge because fractions compare equal only if they
+are exactly equal, not just equal to within the current precision.)
+
+@smallexample
+@group
+3: 1. 2: 1. 1: 6.
+2: 1. 1: 1 .
+1: 5 .
+ .
+
+ @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ]
+@end group
+@end smallexample
+
+Now we compute the initial part of the sum:
+@texline @math{\ln z - {1 \over 2z}}
+@infoline @expr{ln(z) - 1/2z}
+minus the adjustment factor.
+
+@smallexample
+@group
+2: 1.79175946923 2: 1.7084261359 1: -0.57490719743
+1: 0.0833333333333 1: 2.28333333333 .
+ . .
+
+ L r 1 2 * & - r 2 -
+@end group
+@end smallexample
+
+Now we evaluate the series. We'll use another ``for'' loop counting
+up the value of @expr{2 n}. (Calc does have a summation command,
+@kbd{a +}, but we'll use loops just to get more practice with them.)
+
+@smallexample
+@group
+3: -0.5749 3: -0.5749 4: -0.5749 2: -0.5749
+2: 2 2: 1:6 3: 1:6 1: 2.3148e-3
+1: 40 1: 2 2: 2 .
+ . . 1: 36.
+ .
+
+ 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * /
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+3: -0.5749 3: -0.5772 2: -0.5772 1: -0.577215664892
+2: -0.5749 2: -0.5772 1: 0 .
+1: 2.3148e-3 1: -0.5749 .
+ . .
+
+ @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z / 2 Z ) Z ' C-x )
+@end group
+@end smallexample
+
+This is the value of
+@texline @math{-\gamma},
+@infoline @expr{- gamma},
+with a slight bit of roundoff error. To get a full 12 digits, let's use
+a higher precision:
+
+@smallexample
+@group
+2: -0.577215664892 2: -0.577215664892
+1: 1. 1: -0.577215664901532
+
+ 1. @key{RET} p 16 @key{RET} X
+@end group
+@end smallexample
+
+Here's the complete sequence of keystrokes:
+
+@example
+@group
+C-x ( Z ` s 1 0 t 2
+ @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ]
+ L r 1 2 * & - r 2 -
+ 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * /
+ @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z /
+ 2 Z )
+ Z '
+C-x )
+@end group
+@end example
+
+@node Programming Answer 10, Programming Answer 11, Programming Answer 9, Answers to Exercises
+@subsection Programming Tutorial Exercise 10
+
+@noindent
+Taking the derivative of a term of the form @expr{x^n} will produce
+a term like
+@texline @math{n x^{n-1}}.
+@infoline @expr{n x^(n-1)}.
+Taking the derivative of a constant
+produces zero. From this it is easy to see that the @expr{n}th
+derivative of a polynomial, evaluated at @expr{x = 0}, will equal the
+coefficient on the @expr{x^n} term times @expr{n!}.
+
+(Because this definition is long, it will be repeated in concise form
+below. You can use @w{@kbd{C-x * m}} to load it from there. While you are
+entering a @kbd{Z ` Z '} body in a macro, Calc simply collects
+keystrokes without executing them. In the following diagrams we'll
+pretend Calc actually executed the keystrokes as you typed them,
+just for purposes of illustration.)
+
+@smallexample
+@group
+2: 5 x^4 + (x + 1)^2 3: 5 x^4 + (x + 1)^2
+1: 6 2: 0
+ . 1: 6
+ .
+
+ ' 5 x^4 + (x+1)^2 @key{RET} 6 C-x ( Z ` [ ] t 1 0 @key{TAB}
+@end group
+@end smallexample
+
+@noindent
+Variable 1 will accumulate the vector of coefficients.
+
+@smallexample
+@group
+2: 0 3: 0 2: 5 x^4 + ...
+1: 5 x^4 + ... 2: 5 x^4 + ... 1: 1
+ . 1: 1 .
+ .
+
+ Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1
+@end group
+@end smallexample
+
+@noindent
+Note that @kbd{s | 1} appends the top-of-stack value to the vector
+in a variable; it is completely analogous to @kbd{s + 1}. We could
+have written instead, @kbd{r 1 @key{TAB} | t 1}.
+
+@smallexample
+@group
+1: 20 x^3 + 2 x + 2 1: 0 1: [1, 2, 1, 0, 5, 0, 0]
+ . . .
+
+ a d x @key{RET} 1 Z ) @key{DEL} r 1 Z ' C-x )
+@end group
+@end smallexample
+
+To convert back, a simple method is just to map the coefficients
+against a table of powers of @expr{x}.
+
+@smallexample
+@group
+2: [1, 2, 1, 0, 5, 0, 0] 2: [1, 2, 1, 0, 5, 0, 0]
+1: 6 1: [0, 1, 2, 3, 4, 5, 6]
+ . .
+
+ 6 @key{RET} 1 + 0 @key{RET} 1 C-u v x
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+2: [1, 2, 1, 0, 5, 0, 0] 2: 1 + 2 x + x^2 + 5 x^4
+1: [1, x, x^2, x^3, ... ] .
+ .
+
+ ' x @key{RET} @key{TAB} V M ^ *
+@end group
+@end smallexample
+
+Once again, here are the whole polynomial to/from vector programs:
+
+@example
+@group
+C-x ( Z ` [ ] t 1 0 @key{TAB}
+ Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1
+ a d x @key{RET}
+ 1 Z ) r 1
+ Z '
+C-x )
+
+C-x ( 1 + 0 @key{RET} 1 C-u v x ' x @key{RET} @key{TAB} V M ^ * C-x )
+@end group
+@end example
+
+@node Programming Answer 11, Programming Answer 12, Programming Answer 10, Answers to Exercises
+@subsection Programming Tutorial Exercise 11
+
+@noindent
+First we define a dummy program to go on the @kbd{z s} key. The true
+@w{@kbd{z s}} key is supposed to take two numbers from the stack and
+return one number, so @key{DEL} as a dummy definition will make
+sure the stack comes out right.
+
+@smallexample
+@group
+2: 4 1: 4 2: 4
+1: 2 . 1: 2
+ . .
+
+ 4 @key{RET} 2 C-x ( @key{DEL} C-x ) Z K s @key{RET} 2
+@end group
+@end smallexample
+
+The last step replaces the 2 that was eaten during the creation
+of the dummy @kbd{z s} command. Now we move on to the real
+definition. The recurrence needs to be rewritten slightly,
+to the form @expr{s(n,m) = s(n-1,m-1) - (n-1) s(n-1,m)}.
+
+(Because this definition is long, it will be repeated in concise form
+below. You can use @kbd{C-x * m} to load it from there.)
+
+@smallexample
+@group
+2: 4 4: 4 3: 4 2: 4
+1: 2 3: 2 2: 2 1: 2
+ . 2: 4 1: 0 .
+ 1: 2 .
+ .
+
+ C-x ( M-2 @key{RET} a = Z [ @key{DEL} @key{DEL} 1 Z :
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+4: 4 2: 4 2: 3 4: 3 4: 3 3: 3
+3: 2 1: 2 1: 2 3: 2 3: 2 2: 2
+2: 2 . . 2: 3 2: 3 1: 3
+1: 0 1: 2 1: 1 .
+ . . .
+
+ @key{RET} 0 a = Z [ @key{DEL} @key{DEL} 0 Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s
+@end group
+@end smallexample
+
+@noindent
+(Note that the value 3 that our dummy @kbd{z s} produces is not correct;
+it is merely a placeholder that will do just as well for now.)
+
+@smallexample
+@group
+3: 3 4: 3 3: 3 2: 3 1: -6
+2: 3 3: 3 2: 3 1: 9 .
+1: 2 2: 3 1: 3 .
+ . 1: 2 .
+ .
+
+ M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * -
+
+@end group
+@end smallexample
+@noindent
+@smallexample
+@group
+1: -6 2: 4 1: 11 2: 11
+ . 1: 2 . 1: 11
+ . .
+
+ Z ] Z ] C-x ) Z K s @key{RET} @key{DEL} 4 @key{RET} 2 z s M-@key{RET} k s
+@end group
+@end smallexample
+
+Even though the result that we got during the definition was highly
+bogus, once the definition is complete the @kbd{z s} command gets
+the right answers.
+
+Here's the full program once again:
+
+@example
+@group
+C-x ( M-2 @key{RET} a =
+ Z [ @key{DEL} @key{DEL} 1
+ Z : @key{RET} 0 a =
+ Z [ @key{DEL} @key{DEL} 0
+ Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s
+ M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * -
+ Z ]
+ Z ]
+C-x )
+@end group
+@end example
+
+You can read this definition using @kbd{C-x * m} (@code{read-kbd-macro})
+followed by @kbd{Z K s}, without having to make a dummy definition
+first, because @code{read-kbd-macro} doesn't need to execute the
+definition as it reads it in. For this reason, @code{C-x * m} is often
+the easiest way to create recursive programs in Calc.
+
+@node Programming Answer 12, , Programming Answer 11, Answers to Exercises
+@subsection Programming Tutorial Exercise 12
+
+@noindent
+This turns out to be a much easier way to solve the problem. Let's
+denote Stirling numbers as calls of the function @samp{s}.
+
+First, we store the rewrite rules corresponding to the definition of
+Stirling numbers in a convenient variable:
+
+@smallexample
+s e StirlingRules @key{RET}
+[ s(n,n) := 1 :: n >= 0,
+ s(n,0) := 0 :: n > 0,
+ s(n,m) := s(n-1,m-1) - (n-1) s(n-1,m) :: n >= m :: m >= 1 ]
+C-c C-c
+@end smallexample
+
+Now, it's just a matter of applying the rules:
+
+@smallexample
+@group
+2: 4 1: s(4, 2) 1: 11
+1: 2 . .
+ .
+
+ 4 @key{RET} 2 C-x ( ' s($$,$) @key{RET} a r StirlingRules @key{RET} C-x )
+@end group
+@end smallexample
+
+As in the case of the @code{fib} rules, it would be useful to put these
+rules in @code{EvalRules} and to add a @samp{:: remember} condition to
+the last rule.
+
+@c This ends the table-of-contents kludge from above:
+@tex
+\global\let\chapternofonts=\oldchapternofonts
+@end tex
+
+@c [reference]
+
+@node Introduction, Data Types, Tutorial, Top
+@chapter Introduction
+
+@noindent
+This chapter is the beginning of the Calc reference manual.
+It covers basic concepts such as the stack, algebraic and
+numeric entry, undo, numeric prefix arguments, etc.
+
+@c [when-split]
+@c (Chapter 2, the Tutorial, has been printed in a separate volume.)
+
+@menu
+* Basic Commands::
+* Help Commands::
+* Stack Basics::
+* Numeric Entry::
+* Algebraic Entry::
+* Quick Calculator::
+* Prefix Arguments::
+* Undo::
+* Error Messages::
+* Multiple Calculators::
+* Troubleshooting Commands::
+@end menu
+
+@node Basic Commands, Help Commands, Introduction, Introduction
+@section Basic Commands
+
+@noindent
+@pindex calc
+@pindex calc-mode
+@cindex Starting the Calculator
+@cindex Running the Calculator
+To start the Calculator in its standard interface, type @kbd{M-x calc}.
+By default this creates a pair of small windows, @samp{*Calculator*}
+and @samp{*Calc Trail*}. The former displays the contents of the
+Calculator stack and is manipulated exclusively through Calc commands.
+It is possible (though not usually necessary) to create several Calc
+mode buffers each of which has an independent stack, undo list, and
+mode settings. There is exactly one Calc Trail buffer; it records a
+list of the results of all calculations that have been done. The
+Calc Trail buffer uses a variant of Calc mode, so Calculator commands
+still work when the trail buffer's window is selected. It is possible
+to turn the trail window off, but the @samp{*Calc Trail*} buffer itself
+still exists and is updated silently. @xref{Trail Commands}.
+
+@kindex C-x * c
+@kindex C-x * *
+@ignore
+@mindex @null
+@end ignore
+In most installations, the @kbd{C-x * c} key sequence is a more
+convenient way to start the Calculator. Also, @kbd{C-x * *}
+is a synonym for @kbd{C-x * c} unless you last used Calc
+in its Keypad mode.
+
+@kindex x
+@kindex M-x
+@pindex calc-execute-extended-command
+Most Calc commands use one or two keystrokes. Lower- and upper-case
+letters are distinct. Commands may also be entered in full @kbd{M-x} form;
+for some commands this is the only form. As a convenience, the @kbd{x}
+key (@code{calc-execute-extended-command})
+is like @kbd{M-x} except that it enters the initial string @samp{calc-}
+for you. For example, the following key sequences are equivalent:
+@kbd{S}, @kbd{M-x calc-sin @key{RET}}, @kbd{x sin @key{RET}}.
+
+@cindex Extensions module
+@cindex @file{calc-ext} module
+The Calculator exists in many parts. When you type @kbd{C-x * c}, the
+Emacs ``auto-load'' mechanism will bring in only the first part, which
+contains the basic arithmetic functions. The other parts will be
+auto-loaded the first time you use the more advanced commands like trig
+functions or matrix operations. This is done to improve the response time
+of the Calculator in the common case when all you need to do is a
+little arithmetic. If for some reason the Calculator fails to load an
+extension module automatically, you can force it to load all the
+extensions by using the @kbd{C-x * L} (@code{calc-load-everything})
+command. @xref{Mode Settings}.
+
+If you type @kbd{M-x calc} or @kbd{C-x * c} with any numeric prefix argument,
+the Calculator is loaded if necessary, but it is not actually started.
+If the argument is positive, the @file{calc-ext} extensions are also
+loaded if necessary. User-written Lisp code that wishes to make use
+of Calc's arithmetic routines can use @samp{(calc 0)} or @samp{(calc 1)}
+to auto-load the Calculator.
+
+@kindex C-x * b
+@pindex full-calc
+If you type @kbd{C-x * b}, then next time you use @kbd{C-x * c} you
+will get a Calculator that uses the full height of the Emacs screen.
+When full-screen mode is on, @kbd{C-x * c} runs the @code{full-calc}
+command instead of @code{calc}. From the Unix shell you can type
+@samp{emacs -f full-calc} to start a new Emacs specifically for use
+as a calculator. When Calc is started from the Emacs command line
+like this, Calc's normal ``quit'' commands actually quit Emacs itself.
+
+@kindex C-x * o
+@pindex calc-other-window
+The @kbd{C-x * o} command is like @kbd{C-x * c} except that the Calc
+window is not actually selected. If you are already in the Calc
+window, @kbd{C-x * o} switches you out of it. (The regular Emacs
+@kbd{C-x o} command would also work for this, but it has a
+tendency to drop you into the Calc Trail window instead, which
+@kbd{C-x * o} takes care not to do.)
+
+@ignore
+@mindex C-x * q
+@end ignore
+For one quick calculation, you can type @kbd{C-x * q} (@code{quick-calc})
+which prompts you for a formula (like @samp{2+3/4}). The result is
+displayed at the bottom of the Emacs screen without ever creating
+any special Calculator windows. @xref{Quick Calculator}.
+
+@ignore
+@mindex C-x * k
+@end ignore
+Finally, if you are using the X window system you may want to try
+@kbd{C-x * k} (@code{calc-keypad}) which runs Calc with a
+``calculator keypad'' picture as well as a stack display. Click on
+the keys with the mouse to operate the calculator. @xref{Keypad Mode}.
+
+@kindex q
+@pindex calc-quit
+@cindex Quitting the Calculator
+@cindex Exiting the Calculator
+The @kbd{q} key (@code{calc-quit}) exits Calc mode and closes the
+Calculator's window(s). It does not delete the Calculator buffers.
+If you type @kbd{M-x calc} again, the Calculator will reappear with the
+contents of the stack intact. Typing @kbd{C-x * c} or @kbd{C-x * *}
+again from inside the Calculator buffer is equivalent to executing
+@code{calc-quit}; you can think of @kbd{C-x * *} as toggling the
+Calculator on and off.
+
+@kindex C-x * x
+The @kbd{C-x * x} command also turns the Calculator off, no matter which
+user interface (standard, Keypad, or Embedded) is currently active.
+It also cancels @code{calc-edit} mode if used from there.
+
+@kindex d @key{SPC}
+@pindex calc-refresh
+@cindex Refreshing a garbled display
+@cindex Garbled displays, refreshing
+The @kbd{d @key{SPC}} key sequence (@code{calc-refresh}) redraws the contents
+of the Calculator buffer from memory. Use this if the contents of the
+buffer have been damaged somehow.
+
+@ignore
+@mindex o
+@end ignore
+The @kbd{o} key (@code{calc-realign}) moves the cursor back to its
+``home'' position at the bottom of the Calculator buffer.
+
+@kindex <
+@kindex >
+@pindex calc-scroll-left
+@pindex calc-scroll-right
+@cindex Horizontal scrolling
+@cindex Scrolling
+@cindex Wide text, scrolling
+The @kbd{<} and @kbd{>} keys are bound to @code{calc-scroll-left} and
+@code{calc-scroll-right}. These are just like the normal horizontal
+scrolling commands except that they scroll one half-screen at a time by
+default. (Calc formats its output to fit within the bounds of the
+window whenever it can.)
+
+@kindex @{
+@kindex @}
+@pindex calc-scroll-down
+@pindex calc-scroll-up
+@cindex Vertical scrolling
+The @kbd{@{} and @kbd{@}} keys are bound to @code{calc-scroll-down}
+and @code{calc-scroll-up}. They scroll up or down by one-half the
+height of the Calc window.
+
+@kindex C-x * 0
+@pindex calc-reset
+The @kbd{C-x * 0} command (@code{calc-reset}; that's @kbd{C-x *} followed
+by a zero) resets the Calculator to its initial state. This clears
+the stack, resets all the modes to their initial values (the values
+that were saved with @kbd{m m} (@code{calc-save-modes})), clears the
+caches (@pxref{Caches}), and so on. (It does @emph{not} erase the
+values of any variables.) With an argument of 0, Calc will be reset to
+its default state; namely, the modes will be given their default values.
+With a positive prefix argument, @kbd{C-x * 0} preserves the contents of
+the stack but resets everything else to its initial state; with a
+negative prefix argument, @kbd{C-x * 0} preserves the contents of the
+stack but resets everything else to its default state.
+
+@pindex calc-version
+The @kbd{M-x calc-version} command displays the current version number
+of Calc and the name of the person who installed it on your system.
+(This information is also present in the @samp{*Calc Trail*} buffer,
+and in the output of the @kbd{h h} command.)
+
+@node Help Commands, Stack Basics, Basic Commands, Introduction
+@section Help Commands
+
+@noindent
+@cindex Help commands
+@kindex ?
+@pindex calc-help
+The @kbd{?} key (@code{calc-help}) displays a series of brief help messages.
+Some keys (such as @kbd{b} and @kbd{d}) are prefix keys, like Emacs'
+@key{ESC} and @kbd{C-x} prefixes. You can type
+@kbd{?} after a prefix to see a list of commands beginning with that
+prefix. (If the message includes @samp{[MORE]}, press @kbd{?} again
+to see additional commands for that prefix.)
+
+@kindex h h
+@pindex calc-full-help
+The @kbd{h h} (@code{calc-full-help}) command displays all the @kbd{?}
+responses at once. When printed, this makes a nice, compact (three pages)
+summary of Calc keystrokes.
+
+In general, the @kbd{h} key prefix introduces various commands that
+provide help within Calc. Many of the @kbd{h} key functions are
+Calc-specific analogues to the @kbd{C-h} functions for Emacs help.
+
+@kindex h i
+@kindex C-x * i
+@kindex i
+@pindex calc-info
+The @kbd{h i} (@code{calc-info}) command runs the Emacs Info system
+to read this manual on-line. This is basically the same as typing
+@kbd{C-h i} (the regular way to run the Info system), then, if Info
+is not already in the Calc manual, selecting the beginning of the
+manual. The @kbd{C-x * i} command is another way to read the Calc
+manual; it is different from @kbd{h i} in that it works any time,
+not just inside Calc. The plain @kbd{i} key is also equivalent to
+@kbd{h i}, though this key is obsolete and may be replaced with a
+different command in a future version of Calc.
+
+@kindex h t
+@kindex C-x * t
+@pindex calc-tutorial
+The @kbd{h t} (@code{calc-tutorial}) command runs the Info system on
+the Tutorial section of the Calc manual. It is like @kbd{h i},
+except that it selects the starting node of the tutorial rather
+than the beginning of the whole manual. (It actually selects the
+node ``Interactive Tutorial'' which tells a few things about
+using the Info system before going on to the actual tutorial.)
+The @kbd{C-x * t} key is equivalent to @kbd{h t} (but it works at
+all times).
+
+@kindex h s
+@kindex C-x * s
+@pindex calc-info-summary
+The @kbd{h s} (@code{calc-info-summary}) command runs the Info system
+on the Summary node of the Calc manual. @xref{Summary}. The @kbd{C-x * s}
+key is equivalent to @kbd{h s}.
+
+@kindex h k
+@pindex calc-describe-key
+The @kbd{h k} (@code{calc-describe-key}) command looks up a key
+sequence in the Calc manual. For example, @kbd{h k H a S} looks
+up the documentation on the @kbd{H a S} (@code{calc-solve-for})
+command. This works by looking up the textual description of
+the key(s) in the Key Index of the manual, then jumping to the
+node indicated by the index.
+
+Most Calc commands do not have traditional Emacs documentation
+strings, since the @kbd{h k} command is both more convenient and
+more instructive. This means the regular Emacs @kbd{C-h k}
+(@code{describe-key}) command will not be useful for Calc keystrokes.
+
+@kindex h c
+@pindex calc-describe-key-briefly
+The @kbd{h c} (@code{calc-describe-key-briefly}) command reads a
+key sequence and displays a brief one-line description of it at
+the bottom of the screen. It looks for the key sequence in the
+Summary node of the Calc manual; if it doesn't find the sequence
+there, it acts just like its regular Emacs counterpart @kbd{C-h c}
+(@code{describe-key-briefly}). For example, @kbd{h c H a S}
+gives the description:
+
+@smallexample
+H a S runs calc-solve-for: a `H a S' v => fsolve(a,v) (?=notes)
+@end smallexample
+
+@noindent
+which means the command @kbd{H a S} or @kbd{H M-x calc-solve-for}
+takes a value @expr{a} from the stack, prompts for a value @expr{v},
+then applies the algebraic function @code{fsolve} to these values.
+The @samp{?=notes} message means you can now type @kbd{?} to see
+additional notes from the summary that apply to this command.
+
+@kindex h f
+@pindex calc-describe-function
+The @kbd{h f} (@code{calc-describe-function}) command looks up an
+algebraic function or a command name in the Calc manual. Enter an
+algebraic function name to look up that function in the Function
+Index or enter a command name beginning with @samp{calc-} to look it
+up in the Command Index. This command will also look up operator
+symbols that can appear in algebraic formulas, like @samp{%} and
+@samp{=>}.
+
+@kindex h v
+@pindex calc-describe-variable
+The @kbd{h v} (@code{calc-describe-variable}) command looks up a
+variable in the Calc manual. Enter a variable name like @code{pi} or
+@code{PlotRejects}.
+
+@kindex h b
+@pindex describe-bindings
+The @kbd{h b} (@code{calc-describe-bindings}) command is just like
+@kbd{C-h b}, except that only local (Calc-related) key bindings are
+listed.
+
+@kindex h n
+The @kbd{h n} or @kbd{h C-n} (@code{calc-view-news}) command displays
+the ``news'' or change history of Calc. This is kept in the file
+@file{README}, which Calc looks for in the same directory as the Calc
+source files.
+
+@kindex h C-c
+@kindex h C-d
+@kindex h C-w
+The @kbd{h C-c}, @kbd{h C-d}, and @kbd{h C-w} keys display copying,
+distribution, and warranty information about Calc. These work by
+pulling up the appropriate parts of the ``Copying'' or ``Reporting
+Bugs'' sections of the manual.
+
+@node Stack Basics, Numeric Entry, Help Commands, Introduction
+@section Stack Basics
+
+@noindent
+@cindex Stack basics
+@c [fix-tut RPN Calculations and the Stack]
+Calc uses RPN notation. If you are not familiar with RPN, @pxref{RPN
+Tutorial}.
+
+To add the numbers 1 and 2 in Calc you would type the keys:
+@kbd{1 @key{RET} 2 +}.
+(@key{RET} corresponds to the @key{ENTER} key on most calculators.)
+The first three keystrokes ``push'' the numbers 1 and 2 onto the stack. The
+@kbd{+} key always ``pops'' the top two numbers from the stack, adds them,
+and pushes the result (3) back onto the stack. This number is ready for
+further calculations: @kbd{5 -} pushes 5 onto the stack, then pops the
+3 and 5, subtracts them, and pushes the result (@mathit{-2}).
+
+Note that the ``top'' of the stack actually appears at the @emph{bottom}
+of the buffer. A line containing a single @samp{.} character signifies
+the end of the buffer; Calculator commands operate on the number(s)
+directly above this line. The @kbd{d t} (@code{calc-truncate-stack})
+command allows you to move the @samp{.} marker up and down in the stack;
+@pxref{Truncating the Stack}.
+
+@kindex d l
+@pindex calc-line-numbering
+Stack elements are numbered consecutively, with number 1 being the top of
+the stack. These line numbers are ordinarily displayed on the lefthand side
+of the window. The @kbd{d l} (@code{calc-line-numbering}) command controls
+whether these numbers appear. (Line numbers may be turned off since they
+slow the Calculator down a bit and also clutter the display.)
+
+@kindex o
+@pindex calc-realign
+The unshifted letter @kbd{o} (@code{calc-realign}) command repositions
+the cursor to its top-of-stack ``home'' position. It also undoes any
+horizontal scrolling in the window. If you give it a numeric prefix
+argument, it instead moves the cursor to the specified stack element.
+
+The @key{RET} (or equivalent @key{SPC}) key is only required to separate
+two consecutive numbers.
+(After all, if you typed @kbd{1 2} by themselves the Calculator
+would enter the number 12.) If you press @key{RET} or @key{SPC} @emph{not}
+right after typing a number, the key duplicates the number on the top of
+the stack. @kbd{@key{RET} *} is thus a handy way to square a number.
+
+The @key{DEL} key pops and throws away the top number on the stack.
+The @key{TAB} key swaps the top two objects on the stack.
+@xref{Stack and Trail}, for descriptions of these and other stack-related
+commands.
+
+@node Numeric Entry, Algebraic Entry, Stack Basics, Introduction
+@section Numeric Entry
+
+@noindent
+@kindex 0-9
+@kindex .
+@kindex e
+@cindex Numeric entry
+@cindex Entering numbers
+Pressing a digit or other numeric key begins numeric entry using the
+minibuffer. The number is pushed on the stack when you press the @key{RET}
+or @key{SPC} keys. If you press any other non-numeric key, the number is
+pushed onto the stack and the appropriate operation is performed. If
+you press a numeric key which is not valid, the key is ignored.
+
+@cindex Minus signs
+@cindex Negative numbers, entering
+@kindex _
+There are three different concepts corresponding to the word ``minus,''
+typified by @expr{a-b} (subtraction), @expr{-x}
+(change-sign), and @expr{-5} (negative number). Calc uses three
+different keys for these operations, respectively:
+@kbd{-}, @kbd{n}, and @kbd{_} (the underscore). The @kbd{-} key subtracts
+the two numbers on the top of the stack. The @kbd{n} key changes the sign
+of the number on the top of the stack or the number currently being entered.
+The @kbd{_} key begins entry of a negative number or changes the sign of
+the number currently being entered. The following sequences all enter the
+number @mathit{-5} onto the stack: @kbd{0 @key{RET} 5 -}, @kbd{5 n @key{RET}},
+@kbd{5 @key{RET} n}, @kbd{_ 5 @key{RET}}, @kbd{5 _ @key{RET}}.
+
+Some other keys are active during numeric entry, such as @kbd{#} for
+non-decimal numbers, @kbd{:} for fractions, and @kbd{@@} for HMS forms.
+These notations are described later in this manual with the corresponding
+data types. @xref{Data Types}.
+
+During numeric entry, the only editing key available is @key{DEL}.
+
+@node Algebraic Entry, Quick Calculator, Numeric Entry, Introduction
+@section Algebraic Entry
+
+@noindent
+@kindex '
+@pindex calc-algebraic-entry
+@cindex Algebraic notation
+@cindex Formulas, entering
+Calculations can also be entered in algebraic form. This is accomplished
+by typing the apostrophe key, ', followed by the expression in
+standard format:
+
+@example
+' 2+3*4 @key{RET}.
+@end example
+
+@noindent
+This will compute
+@texline @math{2+(3\times4) = 14}
+@infoline @expr{2+(3*4) = 14}
+and push it on the stack. If you wish you can
+ignore the RPN aspect of Calc altogether and simply enter algebraic
+expressions in this way. You may want to use @key{DEL} every so often to
+clear previous results off the stack.
+
+You can press the apostrophe key during normal numeric entry to switch
+the half-entered number into Algebraic entry mode. One reason to do this
+would be to use the full Emacs cursor motion and editing keys, which are
+available during algebraic entry but not during numeric entry.
+
+In the same vein, during either numeric or algebraic entry you can
+press @kbd{`} (backquote) to switch to @code{calc-edit} mode, where
+you complete your half-finished entry in a separate buffer.
+@xref{Editing Stack Entries}.
+
+@kindex m a
+@pindex calc-algebraic-mode
+@cindex Algebraic Mode
+If you prefer algebraic entry, you can use the command @kbd{m a}
+(@code{calc-algebraic-mode}) to set Algebraic mode. In this mode,
+digits and other keys that would normally start numeric entry instead
+start full algebraic entry; as long as your formula begins with a digit
+you can omit the apostrophe. Open parentheses and square brackets also
+begin algebraic entry. You can still do RPN calculations in this mode,
+but you will have to press @key{RET} to terminate every number:
+@kbd{2 @key{RET} 3 @key{RET} * 4 @key{RET} +} would accomplish the same
+thing as @kbd{2*3+4 @key{RET}}.
+
+@cindex Incomplete Algebraic Mode
+If you give a numeric prefix argument like @kbd{C-u} to the @kbd{m a}
+command, it enables Incomplete Algebraic mode; this is like regular
+Algebraic mode except that it applies to the @kbd{(} and @kbd{[} keys
+only. Numeric keys still begin a numeric entry in this mode.
+
+@kindex m t
+@pindex calc-total-algebraic-mode
+@cindex Total Algebraic Mode
+The @kbd{m t} (@code{calc-total-algebraic-mode}) gives you an even
+stronger algebraic-entry mode, in which @emph{all} regular letter and
+punctuation keys begin algebraic entry. Use this if you prefer typing
+@w{@kbd{sqrt( )}} instead of @kbd{Q}, @w{@kbd{factor( )}} instead of
+@kbd{a f}, and so on. To type regular Calc commands when you are in
+Total Algebraic mode, hold down the @key{META} key. Thus @kbd{M-q}
+is the command to quit Calc, @kbd{M-p} sets the precision, and
+@kbd{M-m t} (or @kbd{M-m M-t}, if you prefer) turns Total Algebraic
+mode back off again. Meta keys also terminate algebraic entry, so
+that @kbd{2+3 M-S} is equivalent to @kbd{2+3 @key{RET} M-S}. The symbol
+@samp{Alg*} will appear in the mode line whenever you are in this mode.
+
+Pressing @kbd{'} (the apostrophe) a second time re-enters the previous
+algebraic formula. You can then use the normal Emacs editing keys to
+modify this formula to your liking before pressing @key{RET}.
+
+@kindex $
+@cindex Formulas, referring to stack
+Within a formula entered from the keyboard, the symbol @kbd{$}
+represents the number on the top of the stack. If an entered formula
+contains any @kbd{$} characters, the Calculator replaces the top of
+stack with that formula rather than simply pushing the formula onto the
+stack. Thus, @kbd{' 1+2 @key{RET}} pushes 3 on the stack, and @kbd{$*2
+@key{RET}} replaces it with 6. Note that the @kbd{$} key always
+initiates algebraic entry; the @kbd{'} is unnecessary if @kbd{$} is the
+first character in the new formula.
+
+Higher stack elements can be accessed from an entered formula with the
+symbols @kbd{$$}, @kbd{$$$}, and so on. The number of stack elements
+removed (to be replaced by the entered values) equals the number of dollar
+signs in the longest such symbol in the formula. For example, @samp{$$+$$$}
+adds the second and third stack elements, replacing the top three elements
+with the answer. (All information about the top stack element is thus lost
+since no single @samp{$} appears in this formula.)
+
+A slightly different way to refer to stack elements is with a dollar
+sign followed by a number: @samp{$1}, @samp{$2}, and so on are much
+like @samp{$}, @samp{$$}, etc., except that stack entries referred
+to numerically are not replaced by the algebraic entry. That is, while
+@samp{$+1} replaces 5 on the stack with 6, @samp{$1+1} leaves the 5
+on the stack and pushes an additional 6.
+
+If a sequence of formulas are entered separated by commas, each formula
+is pushed onto the stack in turn. For example, @samp{1,2,3} pushes
+those three numbers onto the stack (leaving the 3 at the top), and
+@samp{$+1,$-1} replaces a 5 on the stack with 4 followed by 6. Also,
+@samp{$,$$} exchanges the top two elements of the stack, just like the
+@key{TAB} key.
+
+You can finish an algebraic entry with @kbd{M-=} or @kbd{M-@key{RET}} instead
+of @key{RET}. This uses @kbd{=} to evaluate the variables in each
+formula that goes onto the stack. (Thus @kbd{' pi @key{RET}} pushes
+the variable @samp{pi}, but @kbd{' pi M-@key{RET}} pushes 3.1415.)
+
+If you finish your algebraic entry by pressing @key{LFD} (or @kbd{C-j})
+instead of @key{RET}, Calc disables the default simplifications
+(as if by @kbd{m O}; @pxref{Simplification Modes}) while the entry
+is being pushed on the stack. Thus @kbd{' 1+2 @key{RET}} pushes 3
+on the stack, but @kbd{' 1+2 @key{LFD}} pushes the formula @expr{1+2};
+you might then press @kbd{=} when it is time to evaluate this formula.
+
+@node Quick Calculator, Prefix Arguments, Algebraic Entry, Introduction
+@section ``Quick Calculator'' Mode
+
+@noindent
+@kindex C-x * q
+@pindex quick-calc
+@cindex Quick Calculator
+There is another way to invoke the Calculator if all you need to do
+is make one or two quick calculations. Type @kbd{C-x * q} (or
+@kbd{M-x quick-calc}), then type any formula as an algebraic entry.
+The Calculator will compute the result and display it in the echo
+area, without ever actually putting up a Calc window.
+
+You can use the @kbd{$} character in a Quick Calculator formula to
+refer to the previous Quick Calculator result. Older results are
+not retained; the Quick Calculator has no effect on the full
+Calculator's stack or trail. If you compute a result and then
+forget what it was, just run @code{C-x * q} again and enter
+@samp{$} as the formula.
+
+If this is the first time you have used the Calculator in this Emacs
+session, the @kbd{C-x * q} command will create the @code{*Calculator*}
+buffer and perform all the usual initializations; it simply will
+refrain from putting that buffer up in a new window. The Quick
+Calculator refers to the @code{*Calculator*} buffer for all mode
+settings. Thus, for example, to set the precision that the Quick
+Calculator uses, simply run the full Calculator momentarily and use
+the regular @kbd{p} command.
+
+If you use @code{C-x * q} from inside the Calculator buffer, the
+effect is the same as pressing the apostrophe key (algebraic entry).
+
+The result of a Quick calculation is placed in the Emacs ``kill ring''
+as well as being displayed. A subsequent @kbd{C-y} command will
+yank the result into the editing buffer. You can also use this
+to yank the result into the next @kbd{C-x * q} input line as a more
+explicit alternative to @kbd{$} notation, or to yank the result
+into the Calculator stack after typing @kbd{C-x * c}.
+
+If you finish your formula by typing @key{LFD} (or @kbd{C-j}) instead
+of @key{RET}, the result is inserted immediately into the current
+buffer rather than going into the kill ring.
+
+Quick Calculator results are actually evaluated as if by the @kbd{=}
+key (which replaces variable names by their stored values, if any).
+If the formula you enter is an assignment to a variable using the
+@samp{:=} operator, say, @samp{foo := 2 + 3} or @samp{foo := foo + 1},
+then the result of the evaluation is stored in that Calc variable.
+@xref{Store and Recall}.
+
+If the result is an integer and the current display radix is decimal,
+the number will also be displayed in hex, octal and binary formats. If
+the integer is in the range from 1 to 126, it will also be displayed as
+an ASCII character.
+
+For example, the quoted character @samp{"x"} produces the vector
+result @samp{[120]} (because 120 is the ASCII code of the lower-case
+`x'; @pxref{Strings}). Since this is a vector, not an integer, it
+is displayed only according to the current mode settings. But
+running Quick Calc again and entering @samp{120} will produce the
+result @samp{120 (16#78, 8#170, x)} which shows the number in its
+decimal, hexadecimal, octal, and ASCII forms.
+
+Please note that the Quick Calculator is not any faster at loading
+or computing the answer than the full Calculator; the name ``quick''
+merely refers to the fact that it's much less hassle to use for
+small calculations.
+
+@node Prefix Arguments, Undo, Quick Calculator, Introduction
+@section Numeric Prefix Arguments
+
+@noindent
+Many Calculator commands use numeric prefix arguments. Some, such as
+@kbd{d s} (@code{calc-sci-notation}), set a parameter to the value of
+the prefix argument or use a default if you don't use a prefix.
+Others (like @kbd{d f} (@code{calc-fix-notation})) require an argument
+and prompt for a number if you don't give one as a prefix.
+
+As a rule, stack-manipulation commands accept a numeric prefix argument
+which is interpreted as an index into the stack. A positive argument
+operates on the top @var{n} stack entries; a negative argument operates
+on the @var{n}th stack entry in isolation; and a zero argument operates
+on the entire stack.
+
+Most commands that perform computations (such as the arithmetic and
+scientific functions) accept a numeric prefix argument that allows the
+operation to be applied across many stack elements. For unary operations
+(that is, functions of one argument like absolute value or complex
+conjugate), a positive prefix argument applies that function to the top
+@var{n} stack entries simultaneously, and a negative argument applies it
+to the @var{n}th stack entry only. For binary operations (functions of
+two arguments like addition, GCD, and vector concatenation), a positive
+prefix argument ``reduces'' the function across the top @var{n}
+stack elements (for example, @kbd{C-u 5 +} sums the top 5 stack entries;
+@pxref{Reducing and Mapping}), and a negative argument maps the next-to-top
+@var{n} stack elements with the top stack element as a second argument
+(for example, @kbd{7 c-u -5 +} adds 7 to the top 5 stack elements).
+This feature is not available for operations which use the numeric prefix
+argument for some other purpose.
+
+Numeric prefixes are specified the same way as always in Emacs: Press
+a sequence of @key{META}-digits, or press @key{ESC} followed by digits,
+or press @kbd{C-u} followed by digits. Some commands treat plain
+@kbd{C-u} (without any actual digits) specially.
+
+@kindex ~
+@pindex calc-num-prefix
+You can type @kbd{~} (@code{calc-num-prefix}) to pop an integer from the
+top of the stack and enter it as the numeric prefix for the next command.
+For example, @kbd{C-u 16 p} sets the precision to 16 digits; an alternate
+(silly) way to do this would be @kbd{2 @key{RET} 4 ^ ~ p}, i.e., compute 2
+to the fourth power and set the precision to that value.
+
+Conversely, if you have typed a numeric prefix argument the @kbd{~} key
+pushes it onto the stack in the form of an integer.
+
+@node Undo, Error Messages, Prefix Arguments, Introduction
+@section Undoing Mistakes
+
+@noindent
+@kindex U
+@kindex C-_
+@pindex calc-undo
+@cindex Mistakes, undoing
+@cindex Undoing mistakes
+@cindex Errors, undoing
+The shift-@kbd{U} key (@code{calc-undo}) undoes the most recent operation.
+If that operation added or dropped objects from the stack, those objects
+are removed or restored. If it was a ``store'' operation, you are
+queried whether or not to restore the variable to its original value.
+The @kbd{U} key may be pressed any number of times to undo successively
+farther back in time; with a numeric prefix argument it undoes a
+specified number of operations. The undo history is cleared only by the
+@kbd{q} (@code{calc-quit}) command. (Recall that @kbd{C-x * c} is
+synonymous with @code{calc-quit} while inside the Calculator; this
+also clears the undo history.)
+
+Currently the mode-setting commands (like @code{calc-precision}) are not
+undoable. You can undo past a point where you changed a mode, but you
+will need to reset the mode yourself.
+
+@kindex D
+@pindex calc-redo
+@cindex Redoing after an Undo
+The shift-@kbd{D} key (@code{calc-redo}) redoes an operation that was
+mistakenly undone. Pressing @kbd{U} with a negative prefix argument is
+equivalent to executing @code{calc-redo}. You can redo any number of
+times, up to the number of recent consecutive undo commands. Redo
+information is cleared whenever you give any command that adds new undo
+information, i.e., if you undo, then enter a number on the stack or make
+any other change, then it will be too late to redo.
+
+@kindex M-@key{RET}
+@pindex calc-last-args
+@cindex Last-arguments feature
+@cindex Arguments, restoring
+The @kbd{M-@key{RET}} key (@code{calc-last-args}) is like undo in that
+it restores the arguments of the most recent command onto the stack;
+however, it does not remove the result of that command. Given a numeric
+prefix argument, this command applies to the @expr{n}th most recent
+command which removed items from the stack; it pushes those items back
+onto the stack.
+
+The @kbd{K} (@code{calc-keep-args}) command provides a related function
+to @kbd{M-@key{RET}}. @xref{Stack and Trail}.
+
+It is also possible to recall previous results or inputs using the trail.
+@xref{Trail Commands}.
+
+The standard Emacs @kbd{C-_} undo key is recognized as a synonym for @kbd{U}.
+
+@node Error Messages, Multiple Calculators, Undo, Introduction
+@section Error Messages
+
+@noindent
+@kindex w
+@pindex calc-why
+@cindex Errors, messages
+@cindex Why did an error occur?
+Many situations that would produce an error message in other calculators
+simply create unsimplified formulas in the Emacs Calculator. For example,
+@kbd{1 @key{RET} 0 /} pushes the formula @expr{1 / 0}; @w{@kbd{0 L}} pushes
+the formula @samp{ln(0)}. Floating-point overflow and underflow are also
+reasons for this to happen.
+
+When a function call must be left in symbolic form, Calc usually
+produces a message explaining why. Messages that are probably
+surprising or indicative of user errors are displayed automatically.
+Other messages are simply kept in Calc's memory and are displayed only
+if you type @kbd{w} (@code{calc-why}). You can also press @kbd{w} if
+the same computation results in several messages. (The first message
+will end with @samp{[w=more]} in this case.)
+
+@kindex d w
+@pindex calc-auto-why
+The @kbd{d w} (@code{calc-auto-why}) command controls when error messages
+are displayed automatically. (Calc effectively presses @kbd{w} for you
+after your computation finishes.) By default, this occurs only for
+``important'' messages. The other possible modes are to report
+@emph{all} messages automatically, or to report none automatically (so
+that you must always press @kbd{w} yourself to see the messages).
+
+@node Multiple Calculators, Troubleshooting Commands, Error Messages, Introduction
+@section Multiple Calculators
+
+@noindent
+@pindex another-calc
+It is possible to have any number of Calc mode buffers at once.
+Usually this is done by executing @kbd{M-x another-calc}, which
+is similar to @kbd{C-x * c} except that if a @samp{*Calculator*}
+buffer already exists, a new, independent one with a name of the
+form @samp{*Calculator*<@var{n}>} is created. You can also use the
+command @code{calc-mode} to put any buffer into Calculator mode, but
+this would ordinarily never be done.
+
+The @kbd{q} (@code{calc-quit}) command does not destroy a Calculator buffer;
+it only closes its window. Use @kbd{M-x kill-buffer} to destroy a
+Calculator buffer.
+
+Each Calculator buffer keeps its own stack, undo list, and mode settings
+such as precision, angular mode, and display formats. In Emacs terms,
+variables such as @code{calc-stack} are buffer-local variables. The
+global default values of these variables are used only when a new
+Calculator buffer is created. The @code{calc-quit} command saves
+the stack and mode settings of the buffer being quit as the new defaults.
+
+There is only one trail buffer, @samp{*Calc Trail*}, used by all
+Calculator buffers.
+
+@node Troubleshooting Commands, , Multiple Calculators, Introduction
+@section Troubleshooting Commands
+
+@noindent
+This section describes commands you can use in case a computation
+incorrectly fails or gives the wrong answer.
+
+@xref{Reporting Bugs}, if you find a problem that appears to be due
+to a bug or deficiency in Calc.
+
+@menu
+* Autoloading Problems::
+* Recursion Depth::
+* Caches::
+* Debugging Calc::
+@end menu
+
+@node Autoloading Problems, Recursion Depth, Troubleshooting Commands, Troubleshooting Commands
+@subsection Autoloading Problems
+
+@noindent
+The Calc program is split into many component files; components are
+loaded automatically as you use various commands that require them.
+Occasionally Calc may lose track of when a certain component is
+necessary; typically this means you will type a command and it won't
+work because some function you've never heard of was undefined.
+
+@kindex C-x * L
+@pindex calc-load-everything
+If this happens, the easiest workaround is to type @kbd{C-x * L}
+(@code{calc-load-everything}) to force all the parts of Calc to be
+loaded right away. This will cause Emacs to take up a lot more
+memory than it would otherwise, but it's guaranteed to fix the problem.
+
+@node Recursion Depth, Caches, Autoloading Problems, Troubleshooting Commands
+@subsection Recursion Depth
+
+@noindent
+@kindex M
+@kindex I M
+@pindex calc-more-recursion-depth
+@pindex calc-less-recursion-depth
+@cindex Recursion depth
+@cindex ``Computation got stuck'' message
+@cindex @code{max-lisp-eval-depth}
+@cindex @code{max-specpdl-size}
+Calc uses recursion in many of its calculations. Emacs Lisp keeps a
+variable @code{max-lisp-eval-depth} which limits the amount of recursion
+possible in an attempt to recover from program bugs. If a calculation
+ever halts incorrectly with the message ``Computation got stuck or
+ran too long,'' use the @kbd{M} command (@code{calc-more-recursion-depth})
+to increase this limit. (Of course, this will not help if the
+calculation really did get stuck due to some problem inside Calc.)
+
+The limit is always increased (multiplied) by a factor of two. There
+is also an @kbd{I M} (@code{calc-less-recursion-depth}) command which
+decreases this limit by a factor of two, down to a minimum value of 200.
+The default value is 1000.
+
+These commands also double or halve @code{max-specpdl-size}, another
+internal Lisp recursion limit. The minimum value for this limit is 600.
+
+@node Caches, Debugging Calc, Recursion Depth, Troubleshooting Commands
+@subsection Caches
+
+@noindent
+@cindex Caches
+@cindex Flushing caches
+Calc saves certain values after they have been computed once. For
+example, the @kbd{P} (@code{calc-pi}) command initially ``knows'' the
+constant @cpi{} to about 20 decimal places; if the current precision
+is greater than this, it will recompute @cpi{} using a series
+approximation. This value will not need to be recomputed ever again
+unless you raise the precision still further. Many operations such as
+logarithms and sines make use of similarly cached values such as
+@cpiover{4} and
+@texline @math{\ln 2}.
+@infoline @expr{ln(2)}.
+The visible effect of caching is that
+high-precision computations may seem to do extra work the first time.
+Other things cached include powers of two (for the binary arithmetic
+functions), matrix inverses and determinants, symbolic integrals, and
+data points computed by the graphing commands.
+
+@pindex calc-flush-caches
+If you suspect a Calculator cache has become corrupt, you can use the
+@code{calc-flush-caches} command to reset all caches to the empty state.
+(This should only be necessary in the event of bugs in the Calculator.)
+The @kbd{C-x * 0} (with the zero key) command also resets caches along
+with all other aspects of the Calculator's state.
+
+@node Debugging Calc, , Caches, Troubleshooting Commands
+@subsection Debugging Calc
+
+@noindent
+A few commands exist to help in the debugging of Calc commands.
+@xref{Programming}, to see the various ways that you can write
+your own Calc commands.
+
+@kindex Z T
+@pindex calc-timing
+The @kbd{Z T} (@code{calc-timing}) command turns on and off a mode
+in which the timing of slow commands is reported in the Trail.
+Any Calc command that takes two seconds or longer writes a line
+to the Trail showing how many seconds it took. This value is
+accurate only to within one second.
+
+All steps of executing a command are included; in particular, time
+taken to format the result for display in the stack and trail is
+counted. Some prompts also count time taken waiting for them to
+be answered, while others do not; this depends on the exact
+implementation of the command. For best results, if you are timing
+a sequence that includes prompts or multiple commands, define a
+keyboard macro to run the whole sequence at once. Calc's @kbd{X}
+command (@pxref{Keyboard Macros}) will then report the time taken
+to execute the whole macro.
+
+Another advantage of the @kbd{X} command is that while it is
+executing, the stack and trail are not updated from step to step.
+So if you expect the output of your test sequence to leave a result
+that may take a long time to format and you don't wish to count
+this formatting time, end your sequence with a @key{DEL} keystroke
+to clear the result from the stack. When you run the sequence with
+@kbd{X}, Calc will never bother to format the large result.
+
+Another thing @kbd{Z T} does is to increase the Emacs variable
+@code{gc-cons-threshold} to a much higher value (two million; the
+usual default in Calc is 250,000) for the duration of each command.
+This generally prevents garbage collection during the timing of
+the command, though it may cause your Emacs process to grow
+abnormally large. (Garbage collection time is a major unpredictable
+factor in the timing of Emacs operations.)
+
+Another command that is useful when debugging your own Lisp
+extensions to Calc is @kbd{M-x calc-pass-errors}, which disables
+the error handler that changes the ``@code{max-lisp-eval-depth}
+exceeded'' message to the much more friendly ``Computation got
+stuck or ran too long.'' This handler interferes with the Emacs
+Lisp debugger's @code{debug-on-error} mode. Errors are reported
+in the handler itself rather than at the true location of the
+error. After you have executed @code{calc-pass-errors}, Lisp
+errors will be reported correctly but the user-friendly message
+will be lost.
+
+@node Data Types, Stack and Trail, Introduction, Top
+@chapter Data Types
+
+@noindent
+This chapter discusses the various types of objects that can be placed
+on the Calculator stack, how they are displayed, and how they are
+entered. (@xref{Data Type Formats}, for information on how these data
+types are represented as underlying Lisp objects.)
+
+Integers, fractions, and floats are various ways of describing real
+numbers. HMS forms also for many purposes act as real numbers. These
+types can be combined to form complex numbers, modulo forms, error forms,
+or interval forms. (But these last four types cannot be combined
+arbitrarily:@: error forms may not contain modulo forms, for example.)
+Finally, all these types of numbers may be combined into vectors,
+matrices, or algebraic formulas.
+
+@menu
+* Integers:: The most basic data type.
+* Fractions:: This and above are called @dfn{rationals}.
+* Floats:: This and above are called @dfn{reals}.
+* Complex Numbers:: This and above are called @dfn{numbers}.
+* Infinities::
+* Vectors and Matrices::
+* Strings::
+* HMS Forms::
+* Date Forms::
+* Modulo Forms::
+* Error Forms::
+* Interval Forms::
+* Incomplete Objects::
+* Variables::
+* Formulas::
+@end menu
+
+@node Integers, Fractions, Data Types, Data Types
+@section Integers
+
+@noindent
+@cindex Integers
+The Calculator stores integers to arbitrary precision. Addition,
+subtraction, and multiplication of integers always yields an exact
+integer result. (If the result of a division or exponentiation of
+integers is not an integer, it is expressed in fractional or
+floating-point form according to the current Fraction mode.
+@xref{Fraction Mode}.)
+
+A decimal integer is represented as an optional sign followed by a
+sequence of digits. Grouping (@pxref{Grouping Digits}) can be used to
+insert a comma at every third digit for display purposes, but you
+must not type commas during the entry of numbers.
+
+@kindex #
+A non-decimal integer is represented as an optional sign, a radix
+between 2 and 36, a @samp{#} symbol, and one or more digits. For radix 11
+and above, the letters A through Z (upper- or lower-case) count as
+digits and do not terminate numeric entry mode. @xref{Radix Modes}, for how
+to set the default radix for display of integers. Numbers of any radix
+may be entered at any time. If you press @kbd{#} at the beginning of a
+number, the current display radix is used.
+
+@node Fractions, Floats, Integers, Data Types
+@section Fractions
+
+@noindent
+@cindex Fractions
+A @dfn{fraction} is a ratio of two integers. Fractions are traditionally
+written ``2/3'' but Calc uses the notation @samp{2:3}. (The @kbd{/} key
+performs RPN division; the following two sequences push the number
+@samp{2:3} on the stack: @kbd{2 :@: 3 @key{RET}}, or @kbd{2 @key{RET} 3 /}
+assuming Fraction mode has been enabled.)
+When the Calculator produces a fractional result it always reduces it to
+simplest form, which may in fact be an integer.
+
+Fractions may also be entered in a three-part form, where @samp{2:3:4}
+represents two-and-three-quarters. @xref{Fraction Formats}, for fraction
+display formats.
+
+Non-decimal fractions are entered and displayed as
+@samp{@var{radix}#@var{num}:@var{denom}} (or in the analogous three-part
+form). The numerator and denominator always use the same radix.
+
+@node Floats, Complex Numbers, Fractions, Data Types
+@section Floats
+
+@noindent
+@cindex Floating-point numbers
+A floating-point number or @dfn{float} is a number stored in scientific
+notation. The number of significant digits in the fractional part is
+governed by the current floating precision (@pxref{Precision}). The
+range of acceptable values is from
+@texline @math{10^{-3999999}}
+@infoline @expr{10^-3999999}
+(inclusive) to
+@texline @math{10^{4000000}}
+@infoline @expr{10^4000000}
+(exclusive), plus the corresponding negative values and zero.
+
+Calculations that would exceed the allowable range of values (such
+as @samp{exp(exp(20))}) are left in symbolic form by Calc. The
+messages ``floating-point overflow'' or ``floating-point underflow''
+indicate that during the calculation a number would have been produced
+that was too large or too close to zero, respectively, to be represented
+by Calc. This does not necessarily mean the final result would have
+overflowed, just that an overflow occurred while computing the result.
+(In fact, it could report an underflow even though the final result
+would have overflowed!)
+
+If a rational number and a float are mixed in a calculation, the result
+will in general be expressed as a float. Commands that require an integer
+value (such as @kbd{k g} [@code{gcd}]) will also accept integer-valued
+floats, i.e., floating-point numbers with nothing after the decimal point.
+
+Floats are identified by the presence of a decimal point and/or an
+exponent. In general a float consists of an optional sign, digits
+including an optional decimal point, and an optional exponent consisting
+of an @samp{e}, an optional sign, and up to seven exponent digits.
+For example, @samp{23.5e-2} is 23.5 times ten to the minus-second power,
+or 0.235.
+
+Floating-point numbers are normally displayed in decimal notation with
+all significant figures shown. Exceedingly large or small numbers are
+displayed in scientific notation. Various other display options are
+available. @xref{Float Formats}.
+
+@cindex Accuracy of calculations
+Floating-point numbers are stored in decimal, not binary. The result
+of each operation is rounded to the nearest value representable in the
+number of significant digits specified by the current precision,
+rounding away from zero in the case of a tie. Thus (in the default
+display mode) what you see is exactly what you get. Some operations such
+as square roots and transcendental functions are performed with several
+digits of extra precision and then rounded down, in an effort to make the
+final result accurate to the full requested precision. However,
+accuracy is not rigorously guaranteed. If you suspect the validity of a
+result, try doing the same calculation in a higher precision. The
+Calculator's arithmetic is not intended to be IEEE-conformant in any
+way.
+
+While floats are always @emph{stored} in decimal, they can be entered
+and displayed in any radix just like integers and fractions. Since a
+float that is entered in a radix other that 10 will be converted to
+decimal, the number that Calc stores may not be exactly the number that
+was entered, it will be the closest decimal approximation given the
+current precison. The notation @samp{@var{radix}#@var{ddd}.@var{ddd}}
+is a floating-point number whose digits are in the specified radix.
+Note that the @samp{.} is more aptly referred to as a ``radix point''
+than as a decimal point in this case. The number @samp{8#123.4567} is
+defined as @samp{8#1234567 * 8^-4}. If the radix is 14 or less, you can
+use @samp{e} notation to write a non-decimal number in scientific
+notation. The exponent is written in decimal, and is considered to be a
+power of the radix: @samp{8#1234567e-4}. If the radix is 15 or above,
+the letter @samp{e} is a digit, so scientific notation must be written
+out, e.g., @samp{16#123.4567*16^2}. The first two exercises of the
+Modes Tutorial explore some of the properties of non-decimal floats.
+
+@node Complex Numbers, Infinities, Floats, Data Types
+@section Complex Numbers
+
+@noindent
+@cindex Complex numbers
+There are two supported formats for complex numbers: rectangular and
+polar. The default format is rectangular, displayed in the form
+@samp{(@var{real},@var{imag})} where @var{real} is the real part and
+@var{imag} is the imaginary part, each of which may be any real number.
+Rectangular complex numbers can also be displayed in @samp{@var{a}+@var{b}i}
+notation; @pxref{Complex Formats}.
+
+Polar complex numbers are displayed in the form
+@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}'
+@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}'
+where @var{r} is the nonnegative magnitude and
+@texline @math{\theta}
+@infoline @var{theta}
+is the argument or phase angle. The range of
+@texline @math{\theta}
+@infoline @var{theta}
+depends on the current angular mode (@pxref{Angular Modes}); it is
+generally between @mathit{-180} and @mathit{+180} degrees or the equivalent range
+in radians.
+
+Complex numbers are entered in stages using incomplete objects.
+@xref{Incomplete Objects}.
+
+Operations on rectangular complex numbers yield rectangular complex
+results, and similarly for polar complex numbers. Where the two types
+are mixed, or where new complex numbers arise (as for the square root of
+a negative real), the current @dfn{Polar mode} is used to determine the
+type. @xref{Polar Mode}.
+
+A complex result in which the imaginary part is zero (or the phase angle
+is 0 or 180 degrees or @cpi{} radians) is automatically converted to a real
+number.
+
+@node Infinities, Vectors and Matrices, Complex Numbers, Data Types
+@section Infinities
+
+@noindent
+@cindex Infinity
+@cindex @code{inf} variable
+@cindex @code{uinf} variable
+@cindex @code{nan} variable
+@vindex inf
+@vindex uinf
+@vindex nan
+The word @code{inf} represents the mathematical concept of @dfn{infinity}.
+Calc actually has three slightly different infinity-like values:
+@code{inf}, @code{uinf}, and @code{nan}. These are just regular
+variable names (@pxref{Variables}); you should avoid using these
+names for your own variables because Calc gives them special
+treatment. Infinities, like all variable names, are normally
+entered using algebraic entry.
+
+Mathematically speaking, it is not rigorously correct to treat
+``infinity'' as if it were a number, but mathematicians often do
+so informally. When they say that @samp{1 / inf = 0}, what they
+really mean is that @expr{1 / x}, as @expr{x} becomes larger and
+larger, becomes arbitrarily close to zero. So you can imagine
+that if @expr{x} got ``all the way to infinity,'' then @expr{1 / x}
+would go all the way to zero. Similarly, when they say that
+@samp{exp(inf) = inf}, they mean that
+@texline @math{e^x}
+@infoline @expr{exp(x)}
+grows without bound as @expr{x} grows. The symbol @samp{-inf} likewise
+stands for an infinitely negative real value; for example, we say that
+@samp{exp(-inf) = 0}. You can have an infinity pointing in any
+direction on the complex plane: @samp{sqrt(-inf) = i inf}.
+
+The same concept of limits can be used to define @expr{1 / 0}. We
+really want the value that @expr{1 / x} approaches as @expr{x}
+approaches zero. But if all we have is @expr{1 / 0}, we can't
+tell which direction @expr{x} was coming from. If @expr{x} was
+positive and decreasing toward zero, then we should say that
+@samp{1 / 0 = inf}. But if @expr{x} was negative and increasing
+toward zero, the answer is @samp{1 / 0 = -inf}. In fact, @expr{x}
+could be an imaginary number, giving the answer @samp{i inf} or
+@samp{-i inf}. Calc uses the special symbol @samp{uinf} to mean
+@dfn{undirected infinity}, i.e., a value which is infinitely
+large but with an unknown sign (or direction on the complex plane).
+
+Calc actually has three modes that say how infinities are handled.
+Normally, infinities never arise from calculations that didn't
+already have them. Thus, @expr{1 / 0} is treated simply as an
+error and left unevaluated. The @kbd{m i} (@code{calc-infinite-mode})
+command (@pxref{Infinite Mode}) enables a mode in which
+@expr{1 / 0} evaluates to @code{uinf} instead. There is also
+an alternative type of infinite mode which says to treat zeros
+as if they were positive, so that @samp{1 / 0 = inf}. While this
+is less mathematically correct, it may be the answer you want in
+some cases.
+
+Since all infinities are ``as large'' as all others, Calc simplifies,
+e.g., @samp{5 inf} to @samp{inf}. Another example is
+@samp{5 - inf = -inf}, where the @samp{-inf} is so large that
+adding a finite number like five to it does not affect it.
+Note that @samp{a - inf} also results in @samp{-inf}; Calc assumes
+that variables like @code{a} always stand for finite quantities.
+Just to show that infinities really are all the same size,
+note that @samp{sqrt(inf) = inf^2 = exp(inf) = inf} in Calc's
+notation.
+
+It's not so easy to define certain formulas like @samp{0 * inf} and
+@samp{inf / inf}. Depending on where these zeros and infinities
+came from, the answer could be literally anything. The latter
+formula could be the limit of @expr{x / x} (giving a result of one),
+or @expr{2 x / x} (giving two), or @expr{x^2 / x} (giving @code{inf}),
+or @expr{x / x^2} (giving zero). Calc uses the symbol @code{nan}
+to represent such an @dfn{indeterminate} value. (The name ``nan''
+comes from analogy with the ``NAN'' concept of IEEE standard
+arithmetic; it stands for ``Not A Number.'' This is somewhat of a
+misnomer, since @code{nan} @emph{does} stand for some number or
+infinity, it's just that @emph{which} number it stands for
+cannot be determined.) In Calc's notation, @samp{0 * inf = nan}
+and @samp{inf / inf = nan}. A few other common indeterminate
+expressions are @samp{inf - inf} and @samp{inf ^ 0}. Also,
+@samp{0 / 0 = nan} if you have turned on Infinite mode
+(as described above).
+
+Infinities are especially useful as parts of @dfn{intervals}.
+@xref{Interval Forms}.
+
+@node Vectors and Matrices, Strings, Infinities, Data Types
+@section Vectors and Matrices
+
+@noindent
+@cindex Vectors
+@cindex Plain vectors
+@cindex Matrices
+The @dfn{vector} data type is flexible and general. A vector is simply a
+list of zero or more data objects. When these objects are numbers, the
+whole is a vector in the mathematical sense. When these objects are
+themselves vectors of equal (nonzero) length, the whole is a @dfn{matrix}.
+A vector which is not a matrix is referred to here as a @dfn{plain vector}.
+
+A vector is displayed as a list of values separated by commas and enclosed
+in square brackets: @samp{[1, 2, 3]}. Thus the following is a 2 row by
+3 column matrix: @samp{[[1, 2, 3], [4, 5, 6]]}. Vectors, like complex
+numbers, are entered as incomplete objects. @xref{Incomplete Objects}.
+During algebraic entry, vectors are entered all at once in the usual
+brackets-and-commas form. Matrices may be entered algebraically as nested
+vectors, or using the shortcut notation @w{@samp{[1, 2, 3; 4, 5, 6]}},
+with rows separated by semicolons. The commas may usually be omitted
+when entering vectors: @samp{[1 2 3]}. Curly braces may be used in
+place of brackets: @samp{@{1, 2, 3@}}, but the commas are required in
+this case.
+
+Traditional vector and matrix arithmetic is also supported;
+@pxref{Basic Arithmetic} and @pxref{Matrix Functions}.
+Many other operations are applied to vectors element-wise. For example,
+the complex conjugate of a vector is a vector of the complex conjugates
+of its elements.
+
+@ignore
+@starindex
+@end ignore
+@tindex vec
+Algebraic functions for building vectors include @samp{vec(a, b, c)}
+to build @samp{[a, b, c]}, @samp{cvec(a, n, m)} to build an
+@texline @math{n\times m}
+@infoline @var{n}x@var{m}
+matrix of @samp{a}s, and @samp{index(n)} to build a vector of integers
+from 1 to @samp{n}.
+
+@node Strings, HMS Forms, Vectors and Matrices, Data Types
+@section Strings
+
+@noindent
+@kindex "
+@cindex Strings
+@cindex Character strings
+Character strings are not a special data type in the Calculator.
+Rather, a string is represented simply as a vector all of whose
+elements are integers in the range 0 to 255 (ASCII codes). You can
+enter a string at any time by pressing the @kbd{"} key. Quotation
+marks and backslashes are written @samp{\"} and @samp{\\}, respectively,
+inside strings. Other notations introduced by backslashes are:
+
+@example
+@group
+\a 7 \^@@ 0
+\b 8 \^a-z 1-26
+\e 27 \^[ 27
+\f 12 \^\\ 28
+\n 10 \^] 29
+\r 13 \^^ 30
+\t 9 \^_ 31
+ \^? 127
+@end group
+@end example
+
+@noindent
+Finally, a backslash followed by three octal digits produces any
+character from its ASCII code.
+
+@kindex d "
+@pindex calc-display-strings
+Strings are normally displayed in vector-of-integers form. The
+@w{@kbd{d "}} (@code{calc-display-strings}) command toggles a mode in
+which any vectors of small integers are displayed as quoted strings
+instead.
+
+The backslash notations shown above are also used for displaying
+strings. Characters 128 and above are not translated by Calc; unless
+you have an Emacs modified for 8-bit fonts, these will show up in
+backslash-octal-digits notation. For characters below 32, and
+for character 127, Calc uses the backslash-letter combination if
+there is one, or otherwise uses a @samp{\^} sequence.
+
+The only Calc feature that uses strings is @dfn{compositions};
+@pxref{Compositions}. Strings also provide a convenient
+way to do conversions between ASCII characters and integers.
+
+@ignore
+@starindex
+@end ignore
+@tindex string
+There is a @code{string} function which provides a different display
+format for strings. Basically, @samp{string(@var{s})}, where @var{s}
+is a vector of integers in the proper range, is displayed as the
+corresponding string of characters with no surrounding quotation
+marks or other modifications. Thus @samp{string("ABC")} (or
+@samp{string([65 66 67])}) will look like @samp{ABC} on the stack.
+This happens regardless of whether @w{@kbd{d "}} has been used. The
+only way to turn it off is to use @kbd{d U} (unformatted language
+mode) which will display @samp{string("ABC")} instead.
+
+Control characters are displayed somewhat differently by @code{string}.
+Characters below 32, and character 127, are shown using @samp{^} notation
+(same as shown above, but without the backslash). The quote and
+backslash characters are left alone, as are characters 128 and above.
+
+@ignore
+@starindex
+@end ignore
+@tindex bstring
+The @code{bstring} function is just like @code{string} except that
+the resulting string is breakable across multiple lines if it doesn't
+fit all on one line. Potential break points occur at every space
+character in the string.
+
+@node HMS Forms, Date Forms, Strings, Data Types
+@section HMS Forms
+
+@noindent
+@cindex Hours-minutes-seconds forms
+@cindex Degrees-minutes-seconds forms
+@dfn{HMS} stands for Hours-Minutes-Seconds; when used as an angular
+argument, the interpretation is Degrees-Minutes-Seconds. All functions
+that operate on angles accept HMS forms. These are interpreted as
+degrees regardless of the current angular mode. It is also possible to
+use HMS as the angular mode so that calculated angles are expressed in
+degrees, minutes, and seconds.
+
+@kindex @@
+@ignore
+@mindex @null
+@end ignore
+@kindex ' (HMS forms)
+@ignore
+@mindex @null
+@end ignore
+@kindex " (HMS forms)
+@ignore
+@mindex @null
+@end ignore
+@kindex h (HMS forms)
+@ignore
+@mindex @null
+@end ignore
+@kindex o (HMS forms)
+@ignore
+@mindex @null
+@end ignore
+@kindex m (HMS forms)
+@ignore
+@mindex @null
+@end ignore
+@kindex s (HMS forms)
+The default format for HMS values is
+@samp{@var{hours}@@ @var{mins}' @var{secs}"}. During entry, the letters
+@samp{h} (for ``hours'') or
+@samp{o} (approximating the ``degrees'' symbol) are accepted as well as
+@samp{@@}, @samp{m} is accepted in place of @samp{'}, and @samp{s} is
+accepted in place of @samp{"}.
+The @var{hours} value is an integer (or integer-valued float).
+The @var{mins} value is an integer or integer-valued float between 0 and 59.
+The @var{secs} value is a real number between 0 (inclusive) and 60
+(exclusive). A positive HMS form is interpreted as @var{hours} +
+@var{mins}/60 + @var{secs}/3600. A negative HMS form is interpreted
+as @mathit{- @var{hours}} @mathit{-} @var{mins}/60 @mathit{-} @var{secs}/3600.
+Display format for HMS forms is quite flexible. @xref{HMS Formats}.
+
+HMS forms can be added and subtracted. When they are added to numbers,
+the numbers are interpreted according to the current angular mode. HMS
+forms can also be multiplied and divided by real numbers. Dividing
+two HMS forms produces a real-valued ratio of the two angles.
+
+@pindex calc-time
+@cindex Time of day
+Just for kicks, @kbd{M-x calc-time} pushes the current time of day on
+the stack as an HMS form.
+
+@node Date Forms, Modulo Forms, HMS Forms, Data Types
+@section Date Forms
+
+@noindent
+@cindex Date forms
+A @dfn{date form} represents a date and possibly an associated time.
+Simple date arithmetic is supported: Adding a number to a date
+produces a new date shifted by that many days; adding an HMS form to
+a date shifts it by that many hours. Subtracting two date forms
+computes the number of days between them (represented as a simple
+number). Many other operations, such as multiplying two date forms,
+are nonsensical and are not allowed by Calc.
+
+Date forms are entered and displayed enclosed in @samp{< >} brackets.
+The default format is, e.g., @samp{<Wed Jan 9, 1991>} for dates,
+or @samp{<3:32:20pm Wed Jan 9, 1991>} for dates with times.
+Input is flexible; date forms can be entered in any of the usual
+notations for dates and times. @xref{Date Formats}.
+
+Date forms are stored internally as numbers, specifically the number
+of days since midnight on the morning of January 1 of the year 1 AD.
+If the internal number is an integer, the form represents a date only;
+if the internal number is a fraction or float, the form represents
+a date and time. For example, @samp{<6:00am Wed Jan 9, 1991>}
+is represented by the number 726842.25. The standard precision of
+12 decimal digits is enough to ensure that a (reasonable) date and
+time can be stored without roundoff error.
+
+If the current precision is greater than 12, date forms will keep
+additional digits in the seconds position. For example, if the
+precision is 15, the seconds will keep three digits after the
+decimal point. Decreasing the precision below 12 may cause the
+time part of a date form to become inaccurate. This can also happen
+if astronomically high years are used, though this will not be an
+issue in everyday (or even everymillennium) use. Note that date
+forms without times are stored as exact integers, so roundoff is
+never an issue for them.
+
+You can use the @kbd{v p} (@code{calc-pack}) and @kbd{v u}
+(@code{calc-unpack}) commands to get at the numerical representation
+of a date form. @xref{Packing and Unpacking}.
+
+Date forms can go arbitrarily far into the future or past. Negative
+year numbers represent years BC. Calc uses a combination of the
+Gregorian and Julian calendars, following the history of Great
+Britain and the British colonies. This is the same calendar that
+is used by the @code{cal} program in most Unix implementations.
+
+@cindex Julian calendar
+@cindex Gregorian calendar
+Some historical background: The Julian calendar was created by
+Julius Caesar in the year 46 BC as an attempt to fix the gradual
+drift caused by the lack of leap years in the calendar used
+until that time. The Julian calendar introduced an extra day in
+all years divisible by four. After some initial confusion, the
+calendar was adopted around the year we call 8 AD. Some centuries
+later it became apparent that the Julian year of 365.25 days was
+itself not quite right. In 1582 Pope Gregory XIII introduced the
+Gregorian calendar, which added the new rule that years divisible
+by 100, but not by 400, were not to be considered leap years
+despite being divisible by four. Many countries delayed adoption
+of the Gregorian calendar because of religious differences;
+in Britain it was put off until the year 1752, by which time
+the Julian calendar had fallen eleven days behind the true
+seasons. So the switch to the Gregorian calendar in early
+September 1752 introduced a discontinuity: The day after
+Sep 2, 1752 is Sep 14, 1752. Calc follows this convention.
+To take another example, Russia waited until 1918 before
+adopting the new calendar, and thus needed to remove thirteen
+days (between Feb 1, 1918 and Feb 14, 1918). This means that
+Calc's reckoning will be inconsistent with Russian history between
+1752 and 1918, and similarly for various other countries.
+
+Today's timekeepers introduce an occasional ``leap second'' as
+well, but Calc does not take these minor effects into account.
+(If it did, it would have to report a non-integer number of days
+between, say, @samp{<12:00am Mon Jan 1, 1900>} and
+@samp{<12:00am Sat Jan 1, 2000>}.)
+
+Calc uses the Julian calendar for all dates before the year 1752,
+including dates BC when the Julian calendar technically had not
+yet been invented. Thus the claim that day number @mathit{-10000} is
+called ``August 16, 28 BC'' should be taken with a grain of salt.
+
+Please note that there is no ``year 0''; the day before
+@samp{<Sat Jan 1, +1>} is @samp{<Fri Dec 31, -1>}. These are
+days 0 and @mathit{-1} respectively in Calc's internal numbering scheme.
+
+@cindex Julian day counting
+Another day counting system in common use is, confusingly, also called
+``Julian.'' The Julian day number is the numbers of days since
+12:00 noon (GMT) on Jan 1, 4713 BC, which in Calc's scheme (in GMT)
+is @mathit{-1721423.5} (recall that Calc starts at midnight instead
+of noon). Thus to convert a Calc date code obtained by unpacking a
+date form into a Julian day number, simply add 1721423.5 after
+compensating for the time zone difference. The built-in @kbd{t J}
+command performs this conversion for you.
+
+The Julian day number is based on the Julian cycle, which was invented
+in 1583 by Joseph Justus Scaliger. Scaliger named it the Julian cycle
+since it is involves the Julian calendar, but some have suggested that
+Scaliger named it in honor of his father, Julius Caesar Scaliger. The
+Julian cycle is based it on three other cycles: the indiction cycle,
+the Metonic cycle, and the solar cycle. The indiction cycle is a 15
+year cycle originally used by the Romans for tax purposes but later
+used to date medieval documents. The Metonic cycle is a 19 year
+cycle; 19 years is close to being a common multiple of a solar year
+and a lunar month, and so every 19 years the phases of the moon will
+occur on the same days of the year. The solar cycle is a 28 year
+cycle; the Julian calendar repeats itself every 28 years. The
+smallest time period which contains multiples of all three cycles is
+the least common multiple of 15 years, 19 years and 28 years, which
+(since they're pairwise relatively prime) is
+@texline @math{15\times 19\times 28 = 7980} years.
+@infoline 15*19*28 = 7980 years.
+This is the length of a Julian cycle. Working backwards, the previous
+year in which all three cycles began was 4713 BC, and so Scalinger
+chose that year as the beginning of a Julian cycle. Since at the time
+there were no historical records from before 4713 BC, using this year
+as a starting point had the advantage of avoiding negative year
+numbers. In 1849, the astronomer John Herschel (son of William
+Herschel) suggested using the number of days since the beginning of
+the Julian cycle as an astronomical dating system; this idea was taken
+up by other astronomers. (At the time, noon was the start of the
+astronomical day. Herschel originally suggested counting the days
+since Jan 1, 4713 BC at noon Alexandria time; this was later amended to
+noon GMT.) Julian day numbering is largely used in astronomy.
+
+@cindex Unix time format
+The Unix operating system measures time as an integer number of
+seconds since midnight, Jan 1, 1970. To convert a Calc date
+value into a Unix time stamp, first subtract 719164 (the code
+for @samp{<Jan 1, 1970>}), then multiply by 86400 (the number of
+seconds in a day) and press @kbd{R} to round to the nearest
+integer. If you have a date form, you can simply subtract the
+day @samp{<Jan 1, 1970>} instead of unpacking and subtracting
+719164. Likewise, divide by 86400 and add @samp{<Jan 1, 1970>}
+to convert from Unix time to a Calc date form. (Note that
+Unix normally maintains the time in the GMT time zone; you may
+need to subtract five hours to get New York time, or eight hours
+for California time. The same is usually true of Julian day
+counts.) The built-in @kbd{t U} command performs these
+conversions.
+
+@node Modulo Forms, Error Forms, Date Forms, Data Types
+@section Modulo Forms
+
+@noindent
+@cindex Modulo forms
+A @dfn{modulo form} is a real number which is taken modulo (i.e., within
+an integer multiple of) some value @var{M}. Arithmetic modulo @var{M}
+often arises in number theory. Modulo forms are written
+`@var{a} @tfn{mod} @var{M}',
+where @var{a} and @var{M} are real numbers or HMS forms, and
+@texline @math{0 \le a < M}.
+@infoline @expr{0 <= a < @var{M}}.
+In many applications @expr{a} and @expr{M} will be
+integers but this is not required.
+
+@ignore
+@mindex M
+@end ignore
+@kindex M (modulo forms)
+@ignore
+@mindex mod
+@end ignore
+@tindex mod (operator)
+To create a modulo form during numeric entry, press the shift-@kbd{M}
+key to enter the word @samp{mod}. As a special convenience, pressing
+shift-@kbd{M} a second time automatically enters the value of @expr{M}
+that was most recently used before. During algebraic entry, either
+type @samp{mod} by hand or press @kbd{M-m} (that's @kbd{@key{META}-m}).
+Once again, pressing this a second time enters the current modulo.
+
+Modulo forms are not to be confused with the modulo operator @samp{%}.
+The expression @samp{27 % 10} means to compute 27 modulo 10 to produce
+the result 7. Further computations treat this 7 as just a regular integer.
+The expression @samp{27 mod 10} produces the result @samp{7 mod 10};
+further computations with this value are again reduced modulo 10 so that
+the result always lies in the desired range.
+
+When two modulo forms with identical @expr{M}'s are added or multiplied,
+the Calculator simply adds or multiplies the values, then reduces modulo
+@expr{M}. If one argument is a modulo form and the other a plain number,
+the plain number is treated like a compatible modulo form. It is also
+possible to raise modulo forms to powers; the result is the value raised
+to the power, then reduced modulo @expr{M}. (When all values involved
+are integers, this calculation is done much more efficiently than
+actually computing the power and then reducing.)
+
+@cindex Modulo division
+Two modulo forms `@var{a} @tfn{mod} @var{M}' and `@var{b} @tfn{mod} @var{M}'
+can be divided if @expr{a}, @expr{b}, and @expr{M} are all
+integers. The result is the modulo form which, when multiplied by
+`@var{b} @tfn{mod} @var{M}', produces `@var{a} @tfn{mod} @var{M}'. If
+there is no solution to this equation (which can happen only when
+@expr{M} is non-prime), or if any of the arguments are non-integers, the
+division is left in symbolic form. Other operations, such as square
+roots, are not yet supported for modulo forms. (Note that, although
+@w{`@tfn{(}@var{a} @tfn{mod} @var{M}@tfn{)^.5}'} will compute a ``modulo square root''
+in the sense of reducing
+@texline @math{\sqrt a}
+@infoline @expr{sqrt(a)}
+modulo @expr{M}, this is not a useful definition from the
+number-theoretical point of view.)
+
+It is possible to mix HMS forms and modulo forms. For example, an
+HMS form modulo 24 could be used to manipulate clock times; an HMS
+form modulo 360 would be suitable for angles. Making the modulo @expr{M}
+also be an HMS form eliminates troubles that would arise if the angular
+mode were inadvertently set to Radians, in which case
+@w{@samp{2@@ 0' 0" mod 24}} would be interpreted as two degrees modulo
+24 radians!
+
+Modulo forms cannot have variables or formulas for components. If you
+enter the formula @samp{(x + 2) mod 5}, Calc propagates the modulus
+to each of the coefficients: @samp{(1 mod 5) x + (2 mod 5)}.
+
+You can use @kbd{v p} and @kbd{%} to modify modulo forms.
+@xref{Packing and Unpacking}. @xref{Basic Arithmetic}.
+
+@ignore
+@starindex
+@end ignore
+@tindex makemod
+The algebraic function @samp{makemod(a, m)} builds the modulo form
+@w{@samp{a mod m}}.
+
+@node Error Forms, Interval Forms, Modulo Forms, Data Types
+@section Error Forms
+
+@noindent
+@cindex Error forms
+@cindex Standard deviations
+An @dfn{error form} is a number with an associated standard
+deviation, as in @samp{2.3 +/- 0.12}. The notation
+@texline `@var{x} @tfn{+/-} @math{\sigma}'
+@infoline `@var{x} @tfn{+/-} sigma'
+stands for an uncertain value which follows
+a normal or Gaussian distribution of mean @expr{x} and standard
+deviation or ``error''
+@texline @math{\sigma}.
+@infoline @expr{sigma}.
+Both the mean and the error can be either numbers or
+formulas. Generally these are real numbers but the mean may also be
+complex. If the error is negative or complex, it is changed to its
+absolute value. An error form with zero error is converted to a
+regular number by the Calculator.
+
+All arithmetic and transcendental functions accept error forms as input.
+Operations on the mean-value part work just like operations on regular
+numbers. The error part for any function @expr{f(x)} (such as
+@texline @math{\sin x}
+@infoline @expr{sin(x)})
+is defined by the error of @expr{x} times the derivative of @expr{f}
+evaluated at the mean value of @expr{x}. For a two-argument function
+@expr{f(x,y)} (such as addition) the error is the square root of the sum
+of the squares of the errors due to @expr{x} and @expr{y}.
+@tex
+$$ \eqalign{
+ f(x \hbox{\code{ +/- }} \sigma)
+ &= f(x) \hbox{\code{ +/- }} \sigma \left| {df(x) \over dx} \right| \cr
+ f(x \hbox{\code{ +/- }} \sigma_x, y \hbox{\code{ +/- }} \sigma_y)
+ &= f(x,y) \hbox{\code{ +/- }}
+ \sqrt{\left(\sigma_x \left| {\partial f(x,y) \over \partial x}
+ \right| \right)^2
+ +\left(\sigma_y \left| {\partial f(x,y) \over \partial y}
+ \right| \right)^2 } \cr
+} $$
+@end tex
+Note that this
+definition assumes the errors in @expr{x} and @expr{y} are uncorrelated.
+A side effect of this definition is that @samp{(2 +/- 1) * (2 +/- 1)}
+is not the same as @samp{(2 +/- 1)^2}; the former represents the product
+of two independent values which happen to have the same probability
+distributions, and the latter is the product of one random value with itself.
+The former will produce an answer with less error, since on the average
+the two independent errors can be expected to cancel out.
+
+Consult a good text on error analysis for a discussion of the proper use
+of standard deviations. Actual errors often are neither Gaussian-distributed
+nor uncorrelated, and the above formulas are valid only when errors
+are small. As an example, the error arising from
+@texline `@tfn{sin(}@var{x} @tfn{+/-} @math{\sigma}@tfn{)}'
+@infoline `@tfn{sin(}@var{x} @tfn{+/-} @var{sigma}@tfn{)}'
+is
+@texline `@math{\sigma} @tfn{abs(cos(}@var{x}@tfn{))}'.
+@infoline `@var{sigma} @tfn{abs(cos(}@var{x}@tfn{))}'.
+When @expr{x} is close to zero,
+@texline @math{\cos x}
+@infoline @expr{cos(x)}
+is close to one so the error in the sine is close to
+@texline @math{\sigma};
+@infoline @expr{sigma};
+this makes sense, since
+@texline @math{\sin x}
+@infoline @expr{sin(x)}
+is approximately @expr{x} near zero, so a given error in @expr{x} will
+produce about the same error in the sine. Likewise, near 90 degrees
+@texline @math{\cos x}
+@infoline @expr{cos(x)}
+is nearly zero and so the computed error is
+small: The sine curve is nearly flat in that region, so an error in @expr{x}
+has relatively little effect on the value of
+@texline @math{\sin x}.
+@infoline @expr{sin(x)}.
+However, consider @samp{sin(90 +/- 1000)}. The cosine of 90 is zero, so
+Calc will report zero error! We get an obviously wrong result because
+we have violated the small-error approximation underlying the error
+analysis. If the error in @expr{x} had been small, the error in
+@texline @math{\sin x}
+@infoline @expr{sin(x)}
+would indeed have been negligible.
+
+@ignore
+@mindex p
+@end ignore
+@kindex p (error forms)
+@tindex +/-
+To enter an error form during regular numeric entry, use the @kbd{p}
+(``plus-or-minus'') key to type the @samp{+/-} symbol. (If you try actually
+typing @samp{+/-} the @kbd{+} key will be interpreted as the Calculator's
+@kbd{+} command!) Within an algebraic formula, you can press @kbd{M-+} to
+type the @samp{+/-} symbol, or type it out by hand.
+
+Error forms and complex numbers can be mixed; the formulas shown above
+are used for complex numbers, too; note that if the error part evaluates
+to a complex number its absolute value (or the square root of the sum of
+the squares of the absolute values of the two error contributions) is
+used. Mathematically, this corresponds to a radially symmetric Gaussian
+distribution of numbers on the complex plane. However, note that Calc
+considers an error form with real components to represent a real number,
+not a complex distribution around a real mean.
+
+Error forms may also be composed of HMS forms. For best results, both
+the mean and the error should be HMS forms if either one is.
+
+@ignore
+@starindex
+@end ignore
+@tindex sdev
+The algebraic function @samp{sdev(a, b)} builds the error form @samp{a +/- b}.
+
+@node Interval Forms, Incomplete Objects, Error Forms, Data Types
+@section Interval Forms
+
+@noindent
+@cindex Interval forms
+An @dfn{interval} is a subset of consecutive real numbers. For example,
+the interval @samp{[2 ..@: 4]} represents all the numbers from 2 to 4,
+inclusive. If you multiply it by the interval @samp{[0.5 ..@: 2]} you
+obtain @samp{[1 ..@: 8]}. This calculation represents the fact that if
+you multiply some number in the range @samp{[2 ..@: 4]} by some other
+number in the range @samp{[0.5 ..@: 2]}, your result will lie in the range
+from 1 to 8. Interval arithmetic is used to get a worst-case estimate
+of the possible range of values a computation will produce, given the
+set of possible values of the input.
+
+@ifnottex
+Calc supports several varieties of intervals, including @dfn{closed}
+intervals of the type shown above, @dfn{open} intervals such as
+@samp{(2 ..@: 4)}, which represents the range of numbers from 2 to 4
+@emph{exclusive}, and @dfn{semi-open} intervals in which one end
+uses a round parenthesis and the other a square bracket. In mathematical
+terms,
+@samp{[2 ..@: 4]} means @expr{2 <= x <= 4}, whereas
+@samp{[2 ..@: 4)} represents @expr{2 <= x < 4},
+@samp{(2 ..@: 4]} represents @expr{2 < x <= 4}, and
+@samp{(2 ..@: 4)} represents @expr{2 < x < 4}.
+@end ifnottex
+@tex
+Calc supports several varieties of intervals, including \dfn{closed}
+intervals of the type shown above, \dfn{open} intervals such as
+\samp{(2 ..\: 4)}, which represents the range of numbers from 2 to 4
+\emph{exclusive}, and \dfn{semi-open} intervals in which one end
+uses a round parenthesis and the other a square bracket. In mathematical
+terms,
+$$ \eqalign{
+ [2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 \le x \le 4 \cr
+ [2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 \le x < 4 \cr
+ (2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 < x \le 4 \cr
+ (2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 < x < 4 \cr
+} $$
+@end tex
+
+The lower and upper limits of an interval must be either real numbers
+(or HMS or date forms), or symbolic expressions which are assumed to be
+real-valued, or @samp{-inf} and @samp{inf}. In general the lower limit
+must be less than the upper limit. A closed interval containing only
+one value, @samp{[3 ..@: 3]}, is converted to a plain number (3)
+automatically. An interval containing no values at all (such as
+@samp{[3 ..@: 2]} or @samp{[2 ..@: 2)}) can be represented but is not
+guaranteed to behave well when used in arithmetic. Note that the
+interval @samp{[3 .. inf)} represents all real numbers greater than
+or equal to 3, and @samp{(-inf .. inf)} represents all real numbers.
+In fact, @samp{[-inf .. inf]} represents all real numbers including
+the real infinities.
+
+Intervals are entered in the notation shown here, either as algebraic
+formulas, or using incomplete forms. (@xref{Incomplete Objects}.)
+In algebraic formulas, multiple periods in a row are collected from
+left to right, so that @samp{1...1e2} is interpreted as @samp{1.0 ..@: 1e2}
+rather than @samp{1 ..@: 0.1e2}. Add spaces or zeros if you want to
+get the other interpretation. If you omit the lower or upper limit,
+a default of @samp{-inf} or @samp{inf} (respectively) is furnished.
+
+Infinite mode also affects operations on intervals
+(@pxref{Infinities}). Calc will always introduce an open infinity,
+as in @samp{1 / (0 .. 2] = [0.5 .. inf)}. But closed infinities,
+@w{@samp{1 / [0 .. 2] = [0.5 .. inf]}}, arise only in Infinite mode;
+otherwise they are left unevaluated. Note that the ``direction'' of
+a zero is not an issue in this case since the zero is always assumed
+to be continuous with the rest of the interval. For intervals that
+contain zero inside them Calc is forced to give the result,
+@samp{1 / (-2 .. 2) = [-inf .. inf]}.
+
+While it may seem that intervals and error forms are similar, they are
+based on entirely different concepts of inexact quantities. An error
+form
+@texline `@var{x} @tfn{+/-} @math{\sigma}'
+@infoline `@var{x} @tfn{+/-} @var{sigma}'
+means a variable is random, and its value could
+be anything but is ``probably'' within one
+@texline @math{\sigma}
+@infoline @var{sigma}
+of the mean value @expr{x}. An interval
+`@tfn{[}@var{a} @tfn{..@:} @var{b}@tfn{]}' means a
+variable's value is unknown, but guaranteed to lie in the specified
+range. Error forms are statistical or ``average case'' approximations;
+interval arithmetic tends to produce ``worst case'' bounds on an
+answer.
+
+Intervals may not contain complex numbers, but they may contain
+HMS forms or date forms.
+
+@xref{Set Operations}, for commands that interpret interval forms
+as subsets of the set of real numbers.
+
+@ignore
+@starindex
+@end ignore
+@tindex intv
+The algebraic function @samp{intv(n, a, b)} builds an interval form
+from @samp{a} to @samp{b}; @samp{n} is an integer code which must
+be 0 for @samp{(..)}, 1 for @samp{(..]}, 2 for @samp{[..)}, or
+3 for @samp{[..]}.
+
+Please note that in fully rigorous interval arithmetic, care would be
+taken to make sure that the computation of the lower bound rounds toward
+minus infinity, while upper bound computations round toward plus
+infinity. Calc's arithmetic always uses a round-to-nearest mode,
+which means that roundoff errors could creep into an interval
+calculation to produce intervals slightly smaller than they ought to
+be. For example, entering @samp{[1..2]} and pressing @kbd{Q 2 ^}
+should yield the interval @samp{[1..2]} again, but in fact it yields the
+(slightly too small) interval @samp{[1..1.9999999]} due to roundoff
+error.
+
+@node Incomplete Objects, Variables, Interval Forms, Data Types
+@section Incomplete Objects
+
+@noindent
+@ignore
+@mindex [ ]
+@end ignore
+@kindex [
+@ignore
+@mindex ( )
+@end ignore
+@kindex (
+@kindex ,
+@ignore
+@mindex @null
+@end ignore
+@kindex ]
+@ignore
+@mindex @null
+@end ignore
+@kindex )
+@cindex Incomplete vectors
+@cindex Incomplete complex numbers
+@cindex Incomplete interval forms
+When @kbd{(} or @kbd{[} is typed to begin entering a complex number or
+vector, respectively, the effect is to push an @dfn{incomplete} complex
+number or vector onto the stack. The @kbd{,} key adds the value(s) at
+the top of the stack onto the current incomplete object. The @kbd{)}
+and @kbd{]} keys ``close'' the incomplete object after adding any values
+on the top of the stack in front of the incomplete object.
+
+As a result, the sequence of keystrokes @kbd{[ 2 , 3 @key{RET} 2 * , 9 ]}
+pushes the vector @samp{[2, 6, 9]} onto the stack. Likewise, @kbd{( 1 , 2 Q )}
+pushes the complex number @samp{(1, 1.414)} (approximately).
+
+If several values lie on the stack in front of the incomplete object,
+all are collected and appended to the object. Thus the @kbd{,} key
+is redundant: @kbd{[ 2 @key{RET} 3 @key{RET} 2 * 9 ]}. Some people
+prefer the equivalent @key{SPC} key to @key{RET}.
+
+As a special case, typing @kbd{,} immediately after @kbd{(}, @kbd{[}, or
+@kbd{,} adds a zero or duplicates the preceding value in the list being
+formed. Typing @key{DEL} during incomplete entry removes the last item
+from the list.
+
+@kindex ;
+The @kbd{;} key is used in the same way as @kbd{,} to create polar complex
+numbers: @kbd{( 1 ; 2 )}. When entering a vector, @kbd{;} is useful for
+creating a matrix. In particular, @kbd{[ [ 1 , 2 ; 3 , 4 ; 5 , 6 ] ]} is
+equivalent to @kbd{[ [ 1 , 2 ] , [ 3 , 4 ] , [ 5 , 6 ] ]}.
+
+@kindex ..
+@pindex calc-dots
+Incomplete entry is also used to enter intervals. For example,
+@kbd{[ 2 ..@: 4 )} enters a semi-open interval. Note that when you type
+the first period, it will be interpreted as a decimal point, but when
+you type a second period immediately afterward, it is re-interpreted as
+part of the interval symbol. Typing @kbd{..} corresponds to executing
+the @code{calc-dots} command.
+
+If you find incomplete entry distracting, you may wish to enter vectors
+and complex numbers as algebraic formulas by pressing the apostrophe key.
+
+@node Variables, Formulas, Incomplete Objects, Data Types
+@section Variables
+
+@noindent
+@cindex Variables, in formulas
+A @dfn{variable} is somewhere between a storage register on a conventional
+calculator, and a variable in a programming language. (In fact, a Calc
+variable is really just an Emacs Lisp variable that contains a Calc number
+or formula.) A variable's name is normally composed of letters and digits.
+Calc also allows apostrophes and @code{#} signs in variable names.
+(The Calc variable @code{foo} corresponds to the Emacs Lisp variable
+@code{var-foo}, but unless you access the variable from within Emacs
+Lisp, you don't need to worry about it. Variable names in algebraic
+formulas implicitly have @samp{var-} prefixed to their names. The
+@samp{#} character in variable names used in algebraic formulas
+corresponds to a dash @samp{-} in the Lisp variable name. If the name
+contains any dashes, the prefix @samp{var-} is @emph{not} automatically
+added. Thus the two formulas @samp{foo + 1} and @samp{var#foo + 1} both
+refer to the same variable.)
+
+In a command that takes a variable name, you can either type the full
+name of a variable, or type a single digit to use one of the special
+convenience variables @code{q0} through @code{q9}. For example,
+@kbd{3 s s 2} stores the number 3 in variable @code{q2}, and
+@w{@kbd{3 s s foo @key{RET}}} stores that number in variable
+@code{foo}.
+
+To push a variable itself (as opposed to the variable's value) on the
+stack, enter its name as an algebraic expression using the apostrophe
+(@key{'}) key.
+
+@kindex =
+@pindex calc-evaluate
+@cindex Evaluation of variables in a formula
+@cindex Variables, evaluation
+@cindex Formulas, evaluation
+The @kbd{=} (@code{calc-evaluate}) key ``evaluates'' a formula by
+replacing all variables in the formula which have been given values by a
+@code{calc-store} or @code{calc-let} command by their stored values.
+Other variables are left alone. Thus a variable that has not been
+stored acts like an abstract variable in algebra; a variable that has
+been stored acts more like a register in a traditional calculator.
+With a positive numeric prefix argument, @kbd{=} evaluates the top
+@var{n} stack entries; with a negative argument, @kbd{=} evaluates
+the @var{n}th stack entry.
+
+@cindex @code{e} variable
+@cindex @code{pi} variable
+@cindex @code{i} variable
+@cindex @code{phi} variable
+@cindex @code{gamma} variable
+@vindex e
+@vindex pi
+@vindex i
+@vindex phi
+@vindex gamma
+A few variables are called @dfn{special constants}. Their names are
+@samp{e}, @samp{pi}, @samp{i}, @samp{phi}, and @samp{gamma}.
+(@xref{Scientific Functions}.) When they are evaluated with @kbd{=},
+their values are calculated if necessary according to the current precision
+or complex polar mode. If you wish to use these symbols for other purposes,
+simply undefine or redefine them using @code{calc-store}.
+
+The variables @samp{inf}, @samp{uinf}, and @samp{nan} stand for
+infinite or indeterminate values. It's best not to use them as
+regular variables, since Calc uses special algebraic rules when
+it manipulates them. Calc displays a warning message if you store
+a value into any of these special variables.
+
+@xref{Store and Recall}, for a discussion of commands dealing with variables.
+
+@node Formulas, , Variables, Data Types
+@section Formulas
+
+@noindent
+@cindex Formulas
+@cindex Expressions
+@cindex Operators in formulas
+@cindex Precedence of operators
+When you press the apostrophe key you may enter any expression or formula
+in algebraic form. (Calc uses the terms ``expression'' and ``formula''
+interchangeably.) An expression is built up of numbers, variable names,
+and function calls, combined with various arithmetic operators.
+Parentheses may
+be used to indicate grouping. Spaces are ignored within formulas, except
+that spaces are not permitted within variable names or numbers.
+Arithmetic operators, in order from highest to lowest precedence, and
+with their equivalent function names, are:
+
+@samp{_} [@code{subscr}] (subscripts);
+
+postfix @samp{%} [@code{percent}] (as in @samp{25% = 0.25});
+
+prefix @samp{+} and @samp{-} [@code{neg}] (as in @samp{-x})
+and prefix @samp{!} [@code{lnot}] (logical ``not,'' as in @samp{!x});
+
+@samp{+/-} [@code{sdev}] (the standard deviation symbol) and
+@samp{mod} [@code{makemod}] (the symbol for modulo forms);
+
+postfix @samp{!} [@code{fact}] (factorial, as in @samp{n!})
+and postfix @samp{!!} [@code{dfact}] (double factorial);
+
+@samp{^} [@code{pow}] (raised-to-the-power-of);
+
+@samp{*} [@code{mul}];
+
+@samp{/} [@code{div}], @samp{%} [@code{mod}] (modulo), and
+@samp{\} [@code{idiv}] (integer division);
+
+infix @samp{+} [@code{add}] and @samp{-} [@code{sub}] (as in @samp{x-y});
+
+@samp{|} [@code{vconcat}] (vector concatenation);
+
+relations @samp{=} [@code{eq}], @samp{!=} [@code{neq}], @samp{<} [@code{lt}],
+@samp{>} [@code{gt}], @samp{<=} [@code{leq}], and @samp{>=} [@code{geq}];
+
+@samp{&&} [@code{land}] (logical ``and'');
+
+@samp{||} [@code{lor}] (logical ``or'');
+
+the C-style ``if'' operator @samp{a?b:c} [@code{if}];
+
+@samp{!!!} [@code{pnot}] (rewrite pattern ``not'');
+
+@samp{&&&} [@code{pand}] (rewrite pattern ``and'');
+
+@samp{|||} [@code{por}] (rewrite pattern ``or'');
+
+@samp{:=} [@code{assign}] (for assignments and rewrite rules);
+
+@samp{::} [@code{condition}] (rewrite pattern condition);
+
+@samp{=>} [@code{evalto}].
+
+Note that, unlike in usual computer notation, multiplication binds more
+strongly than division: @samp{a*b/c*d} is equivalent to
+@texline @math{a b \over c d}.
+@infoline @expr{(a*b)/(c*d)}.
+
+@cindex Multiplication, implicit
+@cindex Implicit multiplication
+The multiplication sign @samp{*} may be omitted in many cases. In particular,
+if the righthand side is a number, variable name, or parenthesized
+expression, the @samp{*} may be omitted. Implicit multiplication has the
+same precedence as the explicit @samp{*} operator. The one exception to
+the rule is that a variable name followed by a parenthesized expression,
+as in @samp{f(x)},
+is interpreted as a function call, not an implicit @samp{*}. In many
+cases you must use a space if you omit the @samp{*}: @samp{2a} is the
+same as @samp{2*a}, and @samp{a b} is the same as @samp{a*b}, but @samp{ab}
+is a variable called @code{ab}, @emph{not} the product of @samp{a} and
+@samp{b}! Also note that @samp{f (x)} is still a function call.
+
+@cindex Implicit comma in vectors
+The rules are slightly different for vectors written with square brackets.
+In vectors, the space character is interpreted (like the comma) as a
+separator of elements of the vector. Thus @w{@samp{[ 2a b+c d ]}} is
+equivalent to @samp{[2*a, b+c, d]}, whereas @samp{2a b+c d} is equivalent
+to @samp{2*a*b + c*d}.
+Note that spaces around the brackets, and around explicit commas, are
+ignored. To force spaces to be interpreted as multiplication you can
+enclose a formula in parentheses as in @samp{[(a b) 2(c d)]}, which is
+interpreted as @samp{[a*b, 2*c*d]}. An implicit comma is also inserted
+between @samp{][}, as in the matrix @samp{[[1 2][3 4]]}.
+
+Vectors that contain commas (not embedded within nested parentheses or
+brackets) do not treat spaces specially: @samp{[a b, 2 c d]} is a vector
+of two elements. Also, if it would be an error to treat spaces as
+separators, but not otherwise, then Calc will ignore spaces:
+@w{@samp{[a - b]}} is a vector of one element, but @w{@samp{[a -b]}} is
+a vector of two elements. Finally, vectors entered with curly braces
+instead of square brackets do not give spaces any special treatment.
+When Calc displays a vector that does not contain any commas, it will
+insert parentheses if necessary to make the meaning clear:
+@w{@samp{[(a b)]}}.
+
+The expression @samp{5%-2} is ambiguous; is this five-percent minus two,
+or five modulo minus-two? Calc always interprets the leftmost symbol as
+an infix operator preferentially (modulo, in this case), so you would
+need to write @samp{(5%)-2} to get the former interpretation.
+
+@cindex Function call notation
+A function call is, e.g., @samp{sin(1+x)}. (The Calc algebraic function
+@code{foo} corresponds to the Emacs Lisp function @code{calcFunc-foo},
+but unless you access the function from within Emacs Lisp, you don't
+need to worry about it.) Most mathematical Calculator commands like
+@code{calc-sin} have function equivalents like @code{sin}.
+If no Lisp function is defined for a function called by a formula, the
+call is left as it is during algebraic manipulation: @samp{f(x+y)} is
+left alone. Beware that many innocent-looking short names like @code{in}
+and @code{re} have predefined meanings which could surprise you; however,
+single letters or single letters followed by digits are always safe to
+use for your own function names. @xref{Function Index}.
+
+In the documentation for particular commands, the notation @kbd{H S}
+(@code{calc-sinh}) [@code{sinh}] means that the key sequence @kbd{H S}, the
+command @kbd{M-x calc-sinh}, and the algebraic function @code{sinh(x)} all
+represent the same operation.
+
+Commands that interpret (``parse'') text as algebraic formulas include
+algebraic entry (@kbd{'}), editing commands like @kbd{`} which parse
+the contents of the editing buffer when you finish, the @kbd{C-x * g}
+and @w{@kbd{C-x * r}} commands, the @kbd{C-y} command, the X window system
+``paste'' mouse operation, and Embedded mode. All of these operations
+use the same rules for parsing formulas; in particular, language modes
+(@pxref{Language Modes}) affect them all in the same way.
+
+When you read a large amount of text into the Calculator (say a vector
+which represents a big set of rewrite rules; @pxref{Rewrite Rules}),
+you may wish to include comments in the text. Calc's formula parser
+ignores the symbol @samp{%%} and anything following it on a line:
+
+@example
+[ a + b, %% the sum of "a" and "b"
+ c + d,
+ %% last line is coming up:
+ e + f ]
+@end example
+
+@noindent
+This is parsed exactly the same as @samp{[ a + b, c + d, e + f ]}.
+
+@xref{Syntax Tables}, for a way to create your own operators and other
+input notations. @xref{Compositions}, for a way to create new display
+formats.
+
+@xref{Algebra}, for commands for manipulating formulas symbolically.
+
+@node Stack and Trail, Mode Settings, Data Types, Top
+@chapter Stack and Trail Commands
+
+@noindent
+This chapter describes the Calc commands for manipulating objects on the
+stack and in the trail buffer. (These commands operate on objects of any
+type, such as numbers, vectors, formulas, and incomplete objects.)
+
+@menu
+* Stack Manipulation::
+* Editing Stack Entries::
+* Trail Commands::
+* Keep Arguments::
+@end menu
+
+@node Stack Manipulation, Editing Stack Entries, Stack and Trail, Stack and Trail
+@section Stack Manipulation Commands
+
+@noindent
+@kindex @key{RET}
+@kindex @key{SPC}
+@pindex calc-enter
+@cindex Duplicating stack entries
+To duplicate the top object on the stack, press @key{RET} or @key{SPC}
+(two equivalent keys for the @code{calc-enter} command).
+Given a positive numeric prefix argument, these commands duplicate
+several elements at the top of the stack.
+Given a negative argument,
+these commands duplicate the specified element of the stack.
+Given an argument of zero, they duplicate the entire stack.
+For example, with @samp{10 20 30} on the stack,
+@key{RET} creates @samp{10 20 30 30},
+@kbd{C-u 2 @key{RET}} creates @samp{10 20 30 20 30},
+@kbd{C-u - 2 @key{RET}} creates @samp{10 20 30 20}, and
+@kbd{C-u 0 @key{RET}} creates @samp{10 20 30 10 20 30}.
+
+@kindex @key{LFD}
+@pindex calc-over
+The @key{LFD} (@code{calc-over}) command (on a key marked Line-Feed if you
+have it, else on @kbd{C-j}) is like @code{calc-enter}
+except that the sign of the numeric prefix argument is interpreted
+oppositely. Also, with no prefix argument the default argument is 2.
+Thus with @samp{10 20 30} on the stack, @key{LFD} and @kbd{C-u 2 @key{LFD}}
+are both equivalent to @kbd{C-u - 2 @key{RET}}, producing
+@samp{10 20 30 20}.
+
+@kindex @key{DEL}
+@kindex C-d
+@pindex calc-pop
+@cindex Removing stack entries
+@cindex Deleting stack entries
+To remove the top element from the stack, press @key{DEL} (@code{calc-pop}).
+The @kbd{C-d} key is a synonym for @key{DEL}.
+(If the top element is an incomplete object with at least one element, the
+last element is removed from it.) Given a positive numeric prefix argument,
+several elements are removed. Given a negative argument, the specified
+element of the stack is deleted. Given an argument of zero, the entire
+stack is emptied.
+For example, with @samp{10 20 30} on the stack,
+@key{DEL} leaves @samp{10 20},
+@kbd{C-u 2 @key{DEL}} leaves @samp{10},
+@kbd{C-u - 2 @key{DEL}} leaves @samp{10 30}, and
+@kbd{C-u 0 @key{DEL}} leaves an empty stack.
+
+@kindex M-@key{DEL}
+@pindex calc-pop-above
+The @kbd{M-@key{DEL}} (@code{calc-pop-above}) command is to @key{DEL} what
+@key{LFD} is to @key{RET}: It interprets the sign of the numeric
+prefix argument in the opposite way, and the default argument is 2.
+Thus @kbd{M-@key{DEL}} by itself removes the second-from-top stack element,
+leaving the first, third, fourth, and so on; @kbd{M-3 M-@key{DEL}} deletes
+the third stack element.
+
+@kindex @key{TAB}
+@pindex calc-roll-down
+To exchange the top two elements of the stack, press @key{TAB}
+(@code{calc-roll-down}). Given a positive numeric prefix argument, the
+specified number of elements at the top of the stack are rotated downward.
+Given a negative argument, the entire stack is rotated downward the specified
+number of times. Given an argument of zero, the entire stack is reversed
+top-for-bottom.
+For example, with @samp{10 20 30 40 50} on the stack,
+@key{TAB} creates @samp{10 20 30 50 40},
+@kbd{C-u 3 @key{TAB}} creates @samp{10 20 50 30 40},
+@kbd{C-u - 2 @key{TAB}} creates @samp{40 50 10 20 30}, and
+@kbd{C-u 0 @key{TAB}} creates @samp{50 40 30 20 10}.
+
+@kindex M-@key{TAB}
+@pindex calc-roll-up
+The command @kbd{M-@key{TAB}} (@code{calc-roll-up}) is analogous to @key{TAB}
+except that it rotates upward instead of downward. Also, the default
+with no prefix argument is to rotate the top 3 elements.
+For example, with @samp{10 20 30 40 50} on the stack,
+@kbd{M-@key{TAB}} creates @samp{10 20 40 50 30},
+@kbd{C-u 4 M-@key{TAB}} creates @samp{10 30 40 50 20},
+@kbd{C-u - 2 M-@key{TAB}} creates @samp{30 40 50 10 20}, and
+@kbd{C-u 0 M-@key{TAB}} creates @samp{50 40 30 20 10}.
+
+A good way to view the operation of @key{TAB} and @kbd{M-@key{TAB}} is in
+terms of moving a particular element to a new position in the stack.
+With a positive argument @var{n}, @key{TAB} moves the top stack
+element down to level @var{n}, making room for it by pulling all the
+intervening stack elements toward the top. @kbd{M-@key{TAB}} moves the
+element at level @var{n} up to the top. (Compare with @key{LFD},
+which copies instead of moving the element in level @var{n}.)
+
+With a negative argument @mathit{-@var{n}}, @key{TAB} rotates the stack
+to move the object in level @var{n} to the deepest place in the
+stack, and the object in level @mathit{@var{n}+1} to the top. @kbd{M-@key{TAB}}
+rotates the deepest stack element to be in level @mathit{n}, also
+putting the top stack element in level @mathit{@var{n}+1}.
+
+@xref{Selecting Subformulas}, for a way to apply these commands to
+any portion of a vector or formula on the stack.
+
+@node Editing Stack Entries, Trail Commands, Stack Manipulation, Stack and Trail
+@section Editing Stack Entries
+
+@noindent
+@kindex `
+@pindex calc-edit
+@pindex calc-edit-finish
+@cindex Editing the stack with Emacs
+The backquote, @kbd{`} (@code{calc-edit}) command creates a temporary
+buffer (@samp{*Calc Edit*}) for editing the top-of-stack value using
+regular Emacs commands. With a numeric prefix argument, it edits the
+specified number of stack entries at once. (An argument of zero edits
+the entire stack; a negative argument edits one specific stack entry.)
+
+When you are done editing, press @kbd{C-c C-c} to finish and return
+to Calc. The @key{RET} and @key{LFD} keys also work to finish most
+sorts of editing, though in some cases Calc leaves @key{RET} with its
+usual meaning (``insert a newline'') if it's a situation where you
+might want to insert new lines into the editing buffer.
+
+When you finish editing, the Calculator parses the lines of text in
+the @samp{*Calc Edit*} buffer as numbers or formulas, replaces the
+original stack elements in the original buffer with these new values,
+then kills the @samp{*Calc Edit*} buffer. The original Calculator buffer
+continues to exist during editing, but for best results you should be
+careful not to change it until you have finished the edit. You can
+also cancel the edit by killing the buffer with @kbd{C-x k}.
+
+The formula is normally reevaluated as it is put onto the stack.
+For example, editing @samp{a + 2} to @samp{3 + 2} and pressing
+@kbd{C-c C-c} will push 5 on the stack. If you use @key{LFD} to
+finish, Calc will put the result on the stack without evaluating it.
+
+If you give a prefix argument to @kbd{C-c C-c},
+Calc will not kill the @samp{*Calc Edit*} buffer. You can switch
+back to that buffer and continue editing if you wish. However, you
+should understand that if you initiated the edit with @kbd{`}, the
+@kbd{C-c C-c} operation will be programmed to replace the top of the
+stack with the new edited value, and it will do this even if you have
+rearranged the stack in the meanwhile. This is not so much of a problem
+with other editing commands, though, such as @kbd{s e}
+(@code{calc-edit-variable}; @pxref{Operations on Variables}).
+
+If the @code{calc-edit} command involves more than one stack entry,
+each line of the @samp{*Calc Edit*} buffer is interpreted as a
+separate formula. Otherwise, the entire buffer is interpreted as
+one formula, with line breaks ignored. (You can use @kbd{C-o} or
+@kbd{C-q C-j} to insert a newline in the buffer without pressing @key{RET}.)
+
+The @kbd{`} key also works during numeric or algebraic entry. The
+text entered so far is moved to the @code{*Calc Edit*} buffer for
+more extensive editing than is convenient in the minibuffer.
+
+@node Trail Commands, Keep Arguments, Editing Stack Entries, Stack and Trail
+@section Trail Commands
+
+@noindent
+@cindex Trail buffer
+The commands for manipulating the Calc Trail buffer are two-key sequences
+beginning with the @kbd{t} prefix.
+
+@kindex t d
+@pindex calc-trail-display
+The @kbd{t d} (@code{calc-trail-display}) command turns display of the
+trail on and off. Normally the trail display is toggled on if it was off,
+off if it was on. With a numeric prefix of zero, this command always
+turns the trail off; with a prefix of one, it always turns the trail on.
+The other trail-manipulation commands described here automatically turn
+the trail on. Note that when the trail is off values are still recorded
+there; they are simply not displayed. To set Emacs to turn the trail
+off by default, type @kbd{t d} and then save the mode settings with
+@kbd{m m} (@code{calc-save-modes}).
+
+@kindex t i
+@pindex calc-trail-in
+@kindex t o
+@pindex calc-trail-out
+The @kbd{t i} (@code{calc-trail-in}) and @kbd{t o}
+(@code{calc-trail-out}) commands switch the cursor into and out of the
+Calc Trail window. In practice they are rarely used, since the commands
+shown below are a more convenient way to move around in the
+trail, and they work ``by remote control'' when the cursor is still
+in the Calculator window.
+
+@cindex Trail pointer
+There is a @dfn{trail pointer} which selects some entry of the trail at
+any given time. The trail pointer looks like a @samp{>} symbol right
+before the selected number. The following commands operate on the
+trail pointer in various ways.
+
+@kindex t y
+@pindex calc-trail-yank
+@cindex Retrieving previous results
+The @kbd{t y} (@code{calc-trail-yank}) command reads the selected value in
+the trail and pushes it onto the Calculator stack. It allows you to
+re-use any previously computed value without retyping. With a numeric
+prefix argument @var{n}, it yanks the value @var{n} lines above the current
+trail pointer.
+
+@kindex t <
+@pindex calc-trail-scroll-left
+@kindex t >
+@pindex calc-trail-scroll-right
+The @kbd{t <} (@code{calc-trail-scroll-left}) and @kbd{t >}
+(@code{calc-trail-scroll-right}) commands horizontally scroll the trail
+window left or right by one half of its width.
+
+@kindex t n
+@pindex calc-trail-next
+@kindex t p
+@pindex calc-trail-previous
+@kindex t f
+@pindex calc-trail-forward
+@kindex t b
+@pindex calc-trail-backward
+The @kbd{t n} (@code{calc-trail-next}) and @kbd{t p}
+(@code{calc-trail-previous)} commands move the trail pointer down or up
+one line. The @kbd{t f} (@code{calc-trail-forward}) and @kbd{t b}
+(@code{calc-trail-backward}) commands move the trail pointer down or up
+one screenful at a time. All of these commands accept numeric prefix
+arguments to move several lines or screenfuls at a time.
+
+@kindex t [
+@pindex calc-trail-first
+@kindex t ]
+@pindex calc-trail-last
+@kindex t h
+@pindex calc-trail-here
+The @kbd{t [} (@code{calc-trail-first}) and @kbd{t ]}
+(@code{calc-trail-last}) commands move the trail pointer to the first or
+last line of the trail. The @kbd{t h} (@code{calc-trail-here}) command
+moves the trail pointer to the cursor position; unlike the other trail
+commands, @kbd{t h} works only when Calc Trail is the selected window.
+
+@kindex t s
+@pindex calc-trail-isearch-forward
+@kindex t r
+@pindex calc-trail-isearch-backward
+@ifnottex
+The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r}
+(@code{calc-trail-isearch-backward}) commands perform an incremental
+search forward or backward through the trail. You can press @key{RET}
+to terminate the search; the trail pointer moves to the current line.
+If you cancel the search with @kbd{C-g}, the trail pointer stays where
+it was when the search began.
+@end ifnottex
+@tex
+The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r}
+(@code{calc-trail-isearch-backward}) com\-mands perform an incremental
+search forward or backward through the trail. You can press @key{RET}
+to terminate the search; the trail pointer moves to the current line.
+If you cancel the search with @kbd{C-g}, the trail pointer stays where
+it was when the search began.
+@end tex
+
+@kindex t m
+@pindex calc-trail-marker
+The @kbd{t m} (@code{calc-trail-marker}) command allows you to enter a
+line of text of your own choosing into the trail. The text is inserted
+after the line containing the trail pointer; this usually means it is
+added to the end of the trail. Trail markers are useful mainly as the
+targets for later incremental searches in the trail.
+
+@kindex t k
+@pindex calc-trail-kill
+The @kbd{t k} (@code{calc-trail-kill}) command removes the selected line
+from the trail. The line is saved in the Emacs kill ring suitable for
+yanking into another buffer, but it is not easy to yank the text back
+into the trail buffer. With a numeric prefix argument, this command
+kills the @var{n} lines below or above the selected one.
+
+The @kbd{t .} (@code{calc-full-trail-vectors}) command is described
+elsewhere; @pxref{Vector and Matrix Formats}.
+
+@node Keep Arguments, , Trail Commands, Stack and Trail
+@section Keep Arguments
+
+@noindent
+@kindex K
+@pindex calc-keep-args
+The @kbd{K} (@code{calc-keep-args}) command acts like a prefix for
+the following command. It prevents that command from removing its
+arguments from the stack. For example, after @kbd{2 @key{RET} 3 +},
+the stack contains the sole number 5, but after @kbd{2 @key{RET} 3 K +},
+the stack contains the arguments and the result: @samp{2 3 5}.
+
+With the exception of keyboard macros, this works for all commands that
+take arguments off the stack. (To avoid potentially unpleasant behavior,
+a @kbd{K} prefix before a keyboard macro will be ignored. A @kbd{K}
+prefix called @emph{within} the keyboard macro will still take effect.)
+As another example, @kbd{K a s} simplifies a formula, pushing the
+simplified version of the formula onto the stack after the original
+formula (rather than replacing the original formula). Note that you
+could get the same effect by typing @kbd{@key{RET} a s}, copying the
+formula and then simplifying the copy. One difference is that for a very
+large formula the time taken to format the intermediate copy in
+@kbd{@key{RET} a s} could be noticeable; @kbd{K a s} would avoid this
+extra work.
+
+Even stack manipulation commands are affected. @key{TAB} works by
+popping two values and pushing them back in the opposite order,
+so @kbd{2 @key{RET} 3 K @key{TAB}} produces @samp{2 3 3 2}.
+
+A few Calc commands provide other ways of doing the same thing.
+For example, @kbd{' sin($)} replaces the number on the stack with
+its sine using algebraic entry; to push the sine and keep the
+original argument you could use either @kbd{' sin($1)} or
+@kbd{K ' sin($)}. @xref{Algebraic Entry}. Also, the @kbd{s s}
+command is effectively the same as @kbd{K s t}. @xref{Storing Variables}.
+
+If you execute a command and then decide you really wanted to keep
+the argument, you can press @kbd{M-@key{RET}} (@code{calc-last-args}).
+This command pushes the last arguments that were popped by any command
+onto the stack. Note that the order of things on the stack will be
+different than with @kbd{K}: @kbd{2 @key{RET} 3 + M-@key{RET}} leaves
+@samp{5 2 3} on the stack instead of @samp{2 3 5}. @xref{Undo}.
+
+@node Mode Settings, Arithmetic, Stack and Trail, Top
+@chapter Mode Settings
+
+@noindent
+This chapter describes commands that set modes in the Calculator.
+They do not affect the contents of the stack, although they may change
+the @emph{appearance} or @emph{interpretation} of the stack's contents.
+
+@menu
+* General Mode Commands::
+* Precision::
+* Inverse and Hyperbolic::
+* Calculation Modes::
+* Simplification Modes::
+* Declarations::
+* Display Modes::
+* Language Modes::
+* Modes Variable::
+* Calc Mode Line::
+@end menu
+
+@node General Mode Commands, Precision, Mode Settings, Mode Settings
+@section General Mode Commands
+
+@noindent
+@kindex m m
+@pindex calc-save-modes
+@cindex Continuous memory
+@cindex Saving mode settings
+@cindex Permanent mode settings
+@cindex Calc init file, mode settings
+You can save all of the current mode settings in your Calc init file
+(the file given by the variable @code{calc-settings-file}, typically
+@file{~/.calc.el}) with the @kbd{m m} (@code{calc-save-modes}) command.
+This will cause Emacs to reestablish these modes each time it starts up.
+The modes saved in the file include everything controlled by the @kbd{m}
+and @kbd{d} prefix keys, the current precision and binary word size,
+whether or not the trail is displayed, the current height of the Calc
+window, and more. The current interface (used when you type @kbd{C-x * *})
+is also saved. If there were already saved mode settings in the
+file, they are replaced. Otherwise, the new mode information is
+appended to the end of the file.
+
+@kindex m R
+@pindex calc-mode-record-mode
+The @kbd{m R} (@code{calc-mode-record-mode}) command tells Calc to
+record all the mode settings (as if by pressing @kbd{m m}) every
+time a mode setting changes. If the modes are saved this way, then this
+``automatic mode recording'' mode is also saved.
+Type @kbd{m R} again to disable this method of recording the mode
+settings. To turn it off permanently, the @kbd{m m} command will also be
+necessary. (If Embedded mode is enabled, other options for recording
+the modes are available; @pxref{Mode Settings in Embedded Mode}.)
+
+@kindex m F
+@pindex calc-settings-file-name
+The @kbd{m F} (@code{calc-settings-file-name}) command allows you to
+choose a different file than the current value of @code{calc-settings-file}
+for @kbd{m m}, @kbd{Z P}, and similar commands to save permanent information.
+You are prompted for a file name. All Calc modes are then reset to
+their default values, then settings from the file you named are loaded
+if this file exists, and this file becomes the one that Calc will
+use in the future for commands like @kbd{m m}. The default settings
+file name is @file{~/.calc.el}. You can see the current file name by
+giving a blank response to the @kbd{m F} prompt. See also the
+discussion of the @code{calc-settings-file} variable; @pxref{Customizing Calc}.
+
+If the file name you give is your user init file (typically
+@file{~/.emacs}), @kbd{m F} will not automatically load the new file. This
+is because your user init file may contain other things you don't want
+to reread. You can give
+a numeric prefix argument of 1 to @kbd{m F} to force it to read the
+file no matter what. Conversely, an argument of @mathit{-1} tells
+@kbd{m F} @emph{not} to read the new file. An argument of 2 or @mathit{-2}
+tells @kbd{m F} not to reset the modes to their defaults beforehand,
+which is useful if you intend your new file to have a variant of the
+modes present in the file you were using before.
+
+@kindex m x
+@pindex calc-always-load-extensions
+The @kbd{m x} (@code{calc-always-load-extensions}) command enables a mode
+in which the first use of Calc loads the entire program, including all
+extensions modules. Otherwise, the extensions modules will not be loaded
+until the various advanced Calc features are used. Since this mode only
+has effect when Calc is first loaded, @kbd{m x} is usually followed by
+@kbd{m m} to make the mode-setting permanent. To load all of Calc just
+once, rather than always in the future, you can press @kbd{C-x * L}.
+
+@kindex m S
+@pindex calc-shift-prefix
+The @kbd{m S} (@code{calc-shift-prefix}) command enables a mode in which
+all of Calc's letter prefix keys may be typed shifted as well as unshifted.
+If you are typing, say, @kbd{a S} (@code{calc-solve-for}) quite often
+you might find it easier to turn this mode on so that you can type
+@kbd{A S} instead. When this mode is enabled, the commands that used to
+be on those single shifted letters (e.g., @kbd{A} (@code{calc-abs})) can
+now be invoked by pressing the shifted letter twice: @kbd{A A}. Note
+that the @kbd{v} prefix key always works both shifted and unshifted, and
+the @kbd{z} and @kbd{Z} prefix keys are always distinct. Also, the @kbd{h}
+prefix is not affected by this mode. Press @kbd{m S} again to disable
+shifted-prefix mode.
+
+@node Precision, Inverse and Hyperbolic, General Mode Commands, Mode Settings
+@section Precision
+
+@noindent
+@kindex p
+@pindex calc-precision
+@cindex Precision of calculations
+The @kbd{p} (@code{calc-precision}) command controls the precision to
+which floating-point calculations are carried. The precision must be
+at least 3 digits and may be arbitrarily high, within the limits of
+memory and time. This affects only floats: Integer and rational
+calculations are always carried out with as many digits as necessary.
+
+The @kbd{p} key prompts for the current precision. If you wish you
+can instead give the precision as a numeric prefix argument.
+
+Many internal calculations are carried to one or two digits higher
+precision than normal. Results are rounded down afterward to the
+current precision. Unless a special display mode has been selected,
+floats are always displayed with their full stored precision, i.e.,
+what you see is what you get. Reducing the current precision does not
+round values already on the stack, but those values will be rounded
+down before being used in any calculation. The @kbd{c 0} through
+@kbd{c 9} commands (@pxref{Conversions}) can be used to round an
+existing value to a new precision.
+
+@cindex Accuracy of calculations
+It is important to distinguish the concepts of @dfn{precision} and
+@dfn{accuracy}. In the normal usage of these words, the number
+123.4567 has a precision of 7 digits but an accuracy of 4 digits.
+The precision is the total number of digits not counting leading
+or trailing zeros (regardless of the position of the decimal point).
+The accuracy is simply the number of digits after the decimal point
+(again not counting trailing zeros). In Calc you control the precision,
+not the accuracy of computations. If you were to set the accuracy
+instead, then calculations like @samp{exp(100)} would generate many
+more digits than you would typically need, while @samp{exp(-100)} would
+probably round to zero! In Calc, both these computations give you
+exactly 12 (or the requested number of) significant digits.
+
+The only Calc features that deal with accuracy instead of precision
+are fixed-point display mode for floats (@kbd{d f}; @pxref{Float Formats}),
+and the rounding functions like @code{floor} and @code{round}
+(@pxref{Integer Truncation}). Also, @kbd{c 0} through @kbd{c 9}
+deal with both precision and accuracy depending on the magnitudes
+of the numbers involved.
+
+If you need to work with a particular fixed accuracy (say, dollars and
+cents with two digits after the decimal point), one solution is to work
+with integers and an ``implied'' decimal point. For example, $8.99
+divided by 6 would be entered @kbd{899 @key{RET} 6 /}, yielding 149.833
+(actually $1.49833 with our implied decimal point); pressing @kbd{R}
+would round this to 150 cents, i.e., $1.50.
+
+@xref{Floats}, for still more on floating-point precision and related
+issues.
+
+@node Inverse and Hyperbolic, Calculation Modes, Precision, Mode Settings
+@section Inverse and Hyperbolic Flags
+
+@noindent
+@kindex I
+@pindex calc-inverse
+There is no single-key equivalent to the @code{calc-arcsin} function.
+Instead, you must first press @kbd{I} (@code{calc-inverse}) to set
+the @dfn{Inverse Flag}, then press @kbd{S} (@code{calc-sin}).
+The @kbd{I} key actually toggles the Inverse Flag. When this flag
+is set, the word @samp{Inv} appears in the mode line.
+
+@kindex H
+@pindex calc-hyperbolic
+Likewise, the @kbd{H} key (@code{calc-hyperbolic}) sets or clears the
+Hyperbolic Flag, which transforms @code{calc-sin} into @code{calc-sinh}.
+If both of these flags are set at once, the effect will be
+@code{calc-arcsinh}. (The Hyperbolic flag is also used by some
+non-trigonometric commands; for example @kbd{H L} computes a base-10,
+instead of base-@mathit{e}, logarithm.)
+
+Command names like @code{calc-arcsin} are provided for completeness, and
+may be executed with @kbd{x} or @kbd{M-x}. Their effect is simply to
+toggle the Inverse and/or Hyperbolic flags and then execute the
+corresponding base command (@code{calc-sin} in this case).
+
+The Inverse and Hyperbolic flags apply only to the next Calculator
+command, after which they are automatically cleared. (They are also
+cleared if the next keystroke is not a Calc command.) Digits you
+type after @kbd{I} or @kbd{H} (or @kbd{K}) are treated as prefix
+arguments for the next command, not as numeric entries. The same
+is true of @kbd{C-u}, but not of the minus sign (@kbd{K -} means to
+subtract and keep arguments).
+
+The third Calc prefix flag, @kbd{K} (keep-arguments), is discussed
+elsewhere. @xref{Keep Arguments}.
+
+@node Calculation Modes, Simplification Modes, Inverse and Hyperbolic, Mode Settings
+@section Calculation Modes
+
+@noindent
+The commands in this section are two-key sequences beginning with
+the @kbd{m} prefix. (That's the letter @kbd{m}, not the @key{META} key.)
+The @samp{m a} (@code{calc-algebraic-mode}) command is described elsewhere
+(@pxref{Algebraic Entry}).
+
+@menu
+* Angular Modes::
+* Polar Mode::
+* Fraction Mode::
+* Infinite Mode::
+* Symbolic Mode::
+* Matrix Mode::
+* Automatic Recomputation::
+* Working Message::
+@end menu
+
+@node Angular Modes, Polar Mode, Calculation Modes, Calculation Modes
+@subsection Angular Modes
+
+@noindent
+@cindex Angular mode
+The Calculator supports three notations for angles: radians, degrees,
+and degrees-minutes-seconds. When a number is presented to a function
+like @code{sin} that requires an angle, the current angular mode is
+used to interpret the number as either radians or degrees. If an HMS
+form is presented to @code{sin}, it is always interpreted as
+degrees-minutes-seconds.
+
+Functions that compute angles produce a number in radians, a number in
+degrees, or an HMS form depending on the current angular mode. If the
+result is a complex number and the current mode is HMS, the number is
+instead expressed in degrees. (Complex-number calculations would
+normally be done in Radians mode, though. Complex numbers are converted
+to degrees by calculating the complex result in radians and then
+multiplying by 180 over @cpi{}.)
+
+@kindex m r
+@pindex calc-radians-mode
+@kindex m d
+@pindex calc-degrees-mode
+@kindex m h
+@pindex calc-hms-mode
+The @kbd{m r} (@code{calc-radians-mode}), @kbd{m d} (@code{calc-degrees-mode}),
+and @kbd{m h} (@code{calc-hms-mode}) commands control the angular mode.
+The current angular mode is displayed on the Emacs mode line.
+The default angular mode is Degrees.
+
+@node Polar Mode, Fraction Mode, Angular Modes, Calculation Modes
+@subsection Polar Mode
+
+@noindent
+@cindex Polar mode
+The Calculator normally ``prefers'' rectangular complex numbers in the
+sense that rectangular form is used when the proper form can not be
+decided from the input. This might happen by multiplying a rectangular
+number by a polar one, by taking the square root of a negative real
+number, or by entering @kbd{( 2 @key{SPC} 3 )}.
+
+@kindex m p
+@pindex calc-polar-mode
+The @kbd{m p} (@code{calc-polar-mode}) command toggles complex-number
+preference between rectangular and polar forms. In Polar mode, all
+of the above example situations would produce polar complex numbers.
+
+@node Fraction Mode, Infinite Mode, Polar Mode, Calculation Modes
+@subsection Fraction Mode
+
+@noindent
+@cindex Fraction mode
+@cindex Division of integers
+Division of two integers normally yields a floating-point number if the
+result cannot be expressed as an integer. In some cases you would
+rather get an exact fractional answer. One way to accomplish this is
+to use the @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command, which
+divides the two integers on the top of the stack to produce a fraction:
+@kbd{6 @key{RET} 4 :} produces @expr{3:2} even though
+@kbd{6 @key{RET} 4 /} produces @expr{1.5}.
+
+@kindex m f
+@pindex calc-frac-mode
+To set the Calculator to produce fractional results for normal integer
+divisions, use the @kbd{m f} (@code{calc-frac-mode}) command.
+For example, @expr{8/4} produces @expr{2} in either mode,
+but @expr{6/4} produces @expr{3:2} in Fraction mode, @expr{1.5} in
+Float mode.
+
+At any time you can use @kbd{c f} (@code{calc-float}) to convert a
+fraction to a float, or @kbd{c F} (@code{calc-fraction}) to convert a
+float to a fraction. @xref{Conversions}.
+
+@node Infinite Mode, Symbolic Mode, Fraction Mode, Calculation Modes
+@subsection Infinite Mode
+
+@noindent
+@cindex Infinite mode
+The Calculator normally treats results like @expr{1 / 0} as errors;
+formulas like this are left in unsimplified form. But Calc can be
+put into a mode where such calculations instead produce ``infinite''
+results.
+
+@kindex m i
+@pindex calc-infinite-mode
+The @kbd{m i} (@code{calc-infinite-mode}) command turns this mode
+on and off. When the mode is off, infinities do not arise except
+in calculations that already had infinities as inputs. (One exception
+is that infinite open intervals like @samp{[0 .. inf)} can be
+generated; however, intervals closed at infinity (@samp{[0 .. inf]})
+will not be generated when Infinite mode is off.)
+
+With Infinite mode turned on, @samp{1 / 0} will generate @code{uinf},
+an undirected infinity. @xref{Infinities}, for a discussion of the
+difference between @code{inf} and @code{uinf}. Also, @expr{0 / 0}
+evaluates to @code{nan}, the ``indeterminate'' symbol. Various other
+functions can also return infinities in this mode; for example,
+@samp{ln(0) = -inf}, and @samp{gamma(-7) = uinf}. Once again,
+note that @samp{exp(inf) = inf} regardless of Infinite mode because
+this calculation has infinity as an input.
+
+@cindex Positive Infinite mode
+The @kbd{m i} command with a numeric prefix argument of zero,
+i.e., @kbd{C-u 0 m i}, turns on a Positive Infinite mode in
+which zero is treated as positive instead of being directionless.
+Thus, @samp{1 / 0 = inf} and @samp{-1 / 0 = -inf} in this mode.
+Note that zero never actually has a sign in Calc; there are no
+separate representations for @mathit{+0} and @mathit{-0}. Positive
+Infinite mode merely changes the interpretation given to the
+single symbol, @samp{0}. One consequence of this is that, while
+you might expect @samp{1 / -0 = -inf}, actually @samp{1 / -0}
+is equivalent to @samp{1 / 0}, which is equal to positive @code{inf}.
+
+@node Symbolic Mode, Matrix Mode, Infinite Mode, Calculation Modes
+@subsection Symbolic Mode
+
+@noindent
+@cindex Symbolic mode
+@cindex Inexact results
+Calculations are normally performed numerically wherever possible.
+For example, the @code{calc-sqrt} command, or @code{sqrt} function in an
+algebraic expression, produces a numeric answer if the argument is a
+number or a symbolic expression if the argument is an expression:
+@kbd{2 Q} pushes 1.4142 but @kbd{@key{'} x+1 @key{RET} Q} pushes @samp{sqrt(x+1)}.
+
+@kindex m s
+@pindex calc-symbolic-mode
+In @dfn{Symbolic mode}, controlled by the @kbd{m s} (@code{calc-symbolic-mode})
+command, functions which would produce inexact, irrational results are
+left in symbolic form. Thus @kbd{16 Q} pushes 4, but @kbd{2 Q} pushes
+@samp{sqrt(2)}.
+
+@kindex N
+@pindex calc-eval-num
+The shift-@kbd{N} (@code{calc-eval-num}) command evaluates numerically
+the expression at the top of the stack, by temporarily disabling
+@code{calc-symbolic-mode} and executing @kbd{=} (@code{calc-evaluate}).
+Given a numeric prefix argument, it also
+sets the floating-point precision to the specified value for the duration
+of the command.
+
+To evaluate a formula numerically without expanding the variables it
+contains, you can use the key sequence @kbd{m s a v m s} (this uses
+@code{calc-alg-evaluate}, which resimplifies but doesn't evaluate
+variables.)
+
+@node Matrix Mode, Automatic Recomputation, Symbolic Mode, Calculation Modes
+@subsection Matrix and Scalar Modes
+
+@noindent
+@cindex Matrix mode
+@cindex Scalar mode
+Calc sometimes makes assumptions during algebraic manipulation that
+are awkward or incorrect when vectors and matrices are involved.
+Calc has two modes, @dfn{Matrix mode} and @dfn{Scalar mode}, which
+modify its behavior around vectors in useful ways.
+
+@kindex m v
+@pindex calc-matrix-mode
+Press @kbd{m v} (@code{calc-matrix-mode}) once to enter Matrix mode.
+In this mode, all objects are assumed to be matrices unless provably
+otherwise. One major effect is that Calc will no longer consider
+multiplication to be commutative. (Recall that in matrix arithmetic,
+@samp{A*B} is not the same as @samp{B*A}.) This assumption affects
+rewrite rules and algebraic simplification. Another effect of this
+mode is that calculations that would normally produce constants like
+0 and 1 (e.g., @expr{a - a} and @expr{a / a}, respectively) will now
+produce function calls that represent ``generic'' zero or identity
+matrices: @samp{idn(0)}, @samp{idn(1)}. The @code{idn} function
+@samp{idn(@var{a},@var{n})} returns @var{a} times an @var{n}x@var{n}
+identity matrix; if @var{n} is omitted, it doesn't know what
+dimension to use and so the @code{idn} call remains in symbolic
+form. However, if this generic identity matrix is later combined
+with a matrix whose size is known, it will be converted into
+a true identity matrix of the appropriate size. On the other hand,
+if it is combined with a scalar (as in @samp{idn(1) + 2}), Calc
+will assume it really was a scalar after all and produce, e.g., 3.
+
+Press @kbd{m v} a second time to get Scalar mode. Here, objects are
+assumed @emph{not} to be vectors or matrices unless provably so.
+For example, normally adding a variable to a vector, as in
+@samp{[x, y, z] + a}, will leave the sum in symbolic form because
+as far as Calc knows, @samp{a} could represent either a number or
+another 3-vector. In Scalar mode, @samp{a} is assumed to be a
+non-vector, and the addition is evaluated to @samp{[x+a, y+a, z+a]}.
+
+Press @kbd{m v} a third time to return to the normal mode of operation.
+
+If you press @kbd{m v} with a numeric prefix argument @var{n}, you
+get a special ``dimensioned'' Matrix mode in which matrices of
+unknown size are assumed to be @var{n}x@var{n} square matrices.
+Then, the function call @samp{idn(1)} will expand into an actual
+matrix rather than representing a ``generic'' matrix. Simply typing
+@kbd{C-u m v} will get you a square Matrix mode, in which matrices of
+unknown size are assumed to be square matrices of unspecified size.
+
+@cindex Declaring scalar variables
+Of course these modes are approximations to the true state of
+affairs, which is probably that some quantities will be matrices
+and others will be scalars. One solution is to ``declare''
+certain variables or functions to be scalar-valued.
+@xref{Declarations}, to see how to make declarations in Calc.
+
+There is nothing stopping you from declaring a variable to be
+scalar and then storing a matrix in it; however, if you do, the
+results you get from Calc may not be valid. Suppose you let Calc
+get the result @samp{[x+a, y+a, z+a]} shown above, and then stored
+@samp{[1, 2, 3]} in @samp{a}. The result would not be the same as
+for @samp{[x, y, z] + [1, 2, 3]}, but that's because you have broken
+your earlier promise to Calc that @samp{a} would be scalar.
+
+Another way to mix scalars and matrices is to use selections
+(@pxref{Selecting Subformulas}). Use Matrix mode when operating on
+your formula normally; then, to apply Scalar mode to a certain part
+of the formula without affecting the rest just select that part,
+change into Scalar mode and press @kbd{=} to resimplify the part
+under this mode, then change back to Matrix mode before deselecting.
+
+@node Automatic Recomputation, Working Message, Matrix Mode, Calculation Modes
+@subsection Automatic Recomputation
+
+@noindent
+The @dfn{evaluates-to} operator, @samp{=>}, has the special
+property that any @samp{=>} formulas on the stack are recomputed
+whenever variable values or mode settings that might affect them
+are changed. @xref{Evaluates-To Operator}.
+
+@kindex m C
+@pindex calc-auto-recompute
+The @kbd{m C} (@code{calc-auto-recompute}) command turns this
+automatic recomputation on and off. If you turn it off, Calc will
+not update @samp{=>} operators on the stack (nor those in the
+attached Embedded mode buffer, if there is one). They will not
+be updated unless you explicitly do so by pressing @kbd{=} or until
+you press @kbd{m C} to turn recomputation back on. (While automatic
+recomputation is off, you can think of @kbd{m C m C} as a command
+to update all @samp{=>} operators while leaving recomputation off.)
+
+To update @samp{=>} operators in an Embedded buffer while
+automatic recomputation is off, use @w{@kbd{C-x * u}}.
+@xref{Embedded Mode}.
+
+@node Working Message, , Automatic Recomputation, Calculation Modes
+@subsection Working Messages
+
+@noindent
+@cindex Performance
+@cindex Working messages
+Since the Calculator is written entirely in Emacs Lisp, which is not
+designed for heavy numerical work, many operations are quite slow.
+The Calculator normally displays the message @samp{Working...} in the
+echo area during any command that may be slow. In addition, iterative
+operations such as square roots and trigonometric functions display the
+intermediate result at each step. Both of these types of messages can
+be disabled if you find them distracting.
+
+@kindex m w
+@pindex calc-working
+Type @kbd{m w} (@code{calc-working}) with a numeric prefix of 0 to
+disable all ``working'' messages. Use a numeric prefix of 1 to enable
+only the plain @samp{Working...} message. Use a numeric prefix of 2 to
+see intermediate results as well. With no numeric prefix this displays
+the current mode.
+
+While it may seem that the ``working'' messages will slow Calc down
+considerably, experiments have shown that their impact is actually
+quite small. But if your terminal is slow you may find that it helps
+to turn the messages off.
+
+@node Simplification Modes, Declarations, Calculation Modes, Mode Settings
+@section Simplification Modes
+
+@noindent
+The current @dfn{simplification mode} controls how numbers and formulas
+are ``normalized'' when being taken from or pushed onto the stack.
+Some normalizations are unavoidable, such as rounding floating-point
+results to the current precision, and reducing fractions to simplest
+form. Others, such as simplifying a formula like @expr{a+a} (or @expr{2+3}),
+are done by default but can be turned off when necessary.
+
+When you press a key like @kbd{+} when @expr{2} and @expr{3} are on the
+stack, Calc pops these numbers, normalizes them, creates the formula
+@expr{2+3}, normalizes it, and pushes the result. Of course the standard
+rules for normalizing @expr{2+3} will produce the result @expr{5}.
+
+Simplification mode commands consist of the lower-case @kbd{m} prefix key
+followed by a shifted letter.
+
+@kindex m O
+@pindex calc-no-simplify-mode
+The @kbd{m O} (@code{calc-no-simplify-mode}) command turns off all optional
+simplifications. These would leave a formula like @expr{2+3} alone. In
+fact, nothing except simple numbers are ever affected by normalization
+in this mode.
+
+@kindex m N
+@pindex calc-num-simplify-mode
+The @kbd{m N} (@code{calc-num-simplify-mode}) command turns off simplification
+of any formulas except those for which all arguments are constants. For
+example, @expr{1+2} is simplified to @expr{3}, and @expr{a+(2-2)} is
+simplified to @expr{a+0} but no further, since one argument of the sum
+is not a constant. Unfortunately, @expr{(a+2)-2} is @emph{not} simplified
+because the top-level @samp{-} operator's arguments are not both
+constant numbers (one of them is the formula @expr{a+2}).
+A constant is a number or other numeric object (such as a constant
+error form or modulo form), or a vector all of whose
+elements are constant.
+
+@kindex m D
+@pindex calc-default-simplify-mode
+The @kbd{m D} (@code{calc-default-simplify-mode}) command restores the
+default simplifications for all formulas. This includes many easy and
+fast algebraic simplifications such as @expr{a+0} to @expr{a}, and
+@expr{a + 2 a} to @expr{3 a}, as well as evaluating functions like
+@expr{@tfn{deriv}(x^2, x)} to @expr{2 x}.
+
+@kindex m B
+@pindex calc-bin-simplify-mode
+The @kbd{m B} (@code{calc-bin-simplify-mode}) mode applies the default
+simplifications to a result and then, if the result is an integer,
+uses the @kbd{b c} (@code{calc-clip}) command to clip the integer according
+to the current binary word size. @xref{Binary Functions}. Real numbers
+are rounded to the nearest integer and then clipped; other kinds of
+results (after the default simplifications) are left alone.
+
+@kindex m A
+@pindex calc-alg-simplify-mode
+The @kbd{m A} (@code{calc-alg-simplify-mode}) mode does algebraic
+simplification; it applies all the default simplifications, and also
+the more powerful (and slower) simplifications made by @kbd{a s}
+(@code{calc-simplify}). @xref{Algebraic Simplifications}.
+
+@kindex m E
+@pindex calc-ext-simplify-mode
+The @kbd{m E} (@code{calc-ext-simplify-mode}) mode does ``extended''
+algebraic simplification, as by the @kbd{a e} (@code{calc-simplify-extended})
+command. @xref{Unsafe Simplifications}.
+
+@kindex m U
+@pindex calc-units-simplify-mode
+The @kbd{m U} (@code{calc-units-simplify-mode}) mode does units
+simplification; it applies the command @kbd{u s}
+(@code{calc-simplify-units}), which in turn
+is a superset of @kbd{a s}. In this mode, variable names which
+are identifiable as unit names (like @samp{mm} for ``millimeters'')
+are simplified with their unit definitions in mind.
+
+A common technique is to set the simplification mode down to the lowest
+amount of simplification you will allow to be applied automatically, then
+use manual commands like @kbd{a s} and @kbd{c c} (@code{calc-clean}) to
+perform higher types of simplifications on demand. @xref{Algebraic
+Definitions}, for another sample use of No-Simplification mode.
+
+@node Declarations, Display Modes, Simplification Modes, Mode Settings
+@section Declarations
+
+@noindent
+A @dfn{declaration} is a statement you make that promises you will
+use a certain variable or function in a restricted way. This may
+give Calc the freedom to do things that it couldn't do if it had to
+take the fully general situation into account.
+
+@menu
+* Declaration Basics::
+* Kinds of Declarations::
+* Functions for Declarations::
+@end menu
+
+@node Declaration Basics, Kinds of Declarations, Declarations, Declarations
+@subsection Declaration Basics
+
+@noindent
+@kindex s d
+@pindex calc-declare-variable
+The @kbd{s d} (@code{calc-declare-variable}) command is the easiest
+way to make a declaration for a variable. This command prompts for
+the variable name, then prompts for the declaration. The default
+at the declaration prompt is the previous declaration, if any.
+You can edit this declaration, or press @kbd{C-k} to erase it and
+type a new declaration. (Or, erase it and press @key{RET} to clear
+the declaration, effectively ``undeclaring'' the variable.)
+
+A declaration is in general a vector of @dfn{type symbols} and
+@dfn{range} values. If there is only one type symbol or range value,
+you can write it directly rather than enclosing it in a vector.
+For example, @kbd{s d foo @key{RET} real @key{RET}} declares @code{foo} to
+be a real number, and @kbd{s d bar @key{RET} [int, const, [1..6]] @key{RET}}
+declares @code{bar} to be a constant integer between 1 and 6.
+(Actually, you can omit the outermost brackets and Calc will
+provide them for you: @kbd{s d bar @key{RET} int, const, [1..6] @key{RET}}.)
+
+@cindex @code{Decls} variable
+@vindex Decls
+Declarations in Calc are kept in a special variable called @code{Decls}.
+This variable encodes the set of all outstanding declarations in
+the form of a matrix. Each row has two elements: A variable or
+vector of variables declared by that row, and the declaration
+specifier as described above. You can use the @kbd{s D} command to
+edit this variable if you wish to see all the declarations at once.
+@xref{Operations on Variables}, for a description of this command
+and the @kbd{s p} command that allows you to save your declarations
+permanently if you wish.
+
+Items being declared can also be function calls. The arguments in
+the call are ignored; the effect is to say that this function returns
+values of the declared type for any valid arguments. The @kbd{s d}
+command declares only variables, so if you wish to make a function
+declaration you will have to edit the @code{Decls} matrix yourself.
+
+For example, the declaration matrix
+
+@smallexample
+@group
+[ [ foo, real ]
+ [ [j, k, n], int ]
+ [ f(1,2,3), [0 .. inf) ] ]
+@end group
+@end smallexample
+
+@noindent
+declares that @code{foo} represents a real number, @code{j}, @code{k}
+and @code{n} represent integers, and the function @code{f} always
+returns a real number in the interval shown.
+
+@vindex All
+If there is a declaration for the variable @code{All}, then that
+declaration applies to all variables that are not otherwise declared.
+It does not apply to function names. For example, using the row
+@samp{[All, real]} says that all your variables are real unless they
+are explicitly declared without @code{real} in some other row.
+The @kbd{s d} command declares @code{All} if you give a blank
+response to the variable-name prompt.
+
+@node Kinds of Declarations, Functions for Declarations, Declaration Basics, Declarations
+@subsection Kinds of Declarations
+
+@noindent
+The type-specifier part of a declaration (that is, the second prompt
+in the @kbd{s d} command) can be a type symbol, an interval, or a
+vector consisting of zero or more type symbols followed by zero or
+more intervals or numbers that represent the set of possible values
+for the variable.
+
+@smallexample
+@group
+[ [ a, [1, 2, 3, 4, 5] ]
+ [ b, [1 .. 5] ]
+ [ c, [int, 1 .. 5] ] ]
+@end group
+@end smallexample
+
+Here @code{a} is declared to contain one of the five integers shown;
+@code{b} is any number in the interval from 1 to 5 (any real number
+since we haven't specified), and @code{c} is any integer in that
+interval. Thus the declarations for @code{a} and @code{c} are
+nearly equivalent (see below).
+
+The type-specifier can be the empty vector @samp{[]} to say that
+nothing is known about a given variable's value. This is the same
+as not declaring the variable at all except that it overrides any
+@code{All} declaration which would otherwise apply.
+
+The initial value of @code{Decls} is the empty vector @samp{[]}.
+If @code{Decls} has no stored value or if the value stored in it
+is not valid, it is ignored and there are no declarations as far
+as Calc is concerned. (The @kbd{s d} command will replace such a
+malformed value with a fresh empty matrix, @samp{[]}, before recording
+the new declaration.) Unrecognized type symbols are ignored.
+
+The following type symbols describe what sorts of numbers will be
+stored in a variable:
+
+@table @code
+@item int
+Integers.
+@item numint
+Numerical integers. (Integers or integer-valued floats.)
+@item frac
+Fractions. (Rational numbers which are not integers.)
+@item rat
+Rational numbers. (Either integers or fractions.)
+@item float
+Floating-point numbers.
+@item real
+Real numbers. (Integers, fractions, or floats. Actually,
+intervals and error forms with real components also count as
+reals here.)
+@item pos
+Positive real numbers. (Strictly greater than zero.)
+@item nonneg
+Nonnegative real numbers. (Greater than or equal to zero.)
+@item number
+Numbers. (Real or complex.)
+@end table
+
+Calc uses this information to determine when certain simplifications
+of formulas are safe. For example, @samp{(x^y)^z} cannot be
+simplified to @samp{x^(y z)} in general; for example,
+@samp{((-3)^2)^1:2} is 3, but @samp{(-3)^(2*1:2) = (-3)^1} is @mathit{-3}.
+However, this simplification @emph{is} safe if @code{z} is known
+to be an integer, or if @code{x} is known to be a nonnegative
+real number. If you have given declarations that allow Calc to
+deduce either of these facts, Calc will perform this simplification
+of the formula.
+
+Calc can apply a certain amount of logic when using declarations.
+For example, @samp{(x^y)^(2n+1)} will be simplified if @code{n}
+has been declared @code{int}; Calc knows that an integer times an
+integer, plus an integer, must always be an integer. (In fact,
+Calc would simplify @samp{(-x)^(2n+1)} to @samp{-(x^(2n+1))} since
+it is able to determine that @samp{2n+1} must be an odd integer.)
+
+Similarly, @samp{(abs(x)^y)^z} will be simplified to @samp{abs(x)^(y z)}
+because Calc knows that the @code{abs} function always returns a
+nonnegative real. If you had a @code{myabs} function that also had
+this property, you could get Calc to recognize it by adding the row
+@samp{[myabs(), nonneg]} to the @code{Decls} matrix.
+
+One instance of this simplification is @samp{sqrt(x^2)} (since the
+@code{sqrt} function is effectively a one-half power). Normally
+Calc leaves this formula alone. After the command
+@kbd{s d x @key{RET} real @key{RET}}, however, it can simplify the formula to
+@samp{abs(x)}. And after @kbd{s d x @key{RET} nonneg @key{RET}}, Calc can
+simplify this formula all the way to @samp{x}.
+
+If there are any intervals or real numbers in the type specifier,
+they comprise the set of possible values that the variable or
+function being declared can have. In particular, the type symbol
+@code{real} is effectively the same as the range @samp{[-inf .. inf]}
+(note that infinity is included in the range of possible values);
+@code{pos} is the same as @samp{(0 .. inf]}, and @code{nonneg} is
+the same as @samp{[0 .. inf]}. Saying @samp{[real, [-5 .. 5]]} is
+redundant because the fact that the variable is real can be
+deduced just from the interval, but @samp{[int, [-5 .. 5]]} and
+@samp{[rat, [-5 .. 5]]} are useful combinations.
+
+Note that the vector of intervals or numbers is in the same format
+used by Calc's set-manipulation commands. @xref{Set Operations}.
+
+The type specifier @samp{[1, 2, 3]} is equivalent to
+@samp{[numint, 1, 2, 3]}, @emph{not} to @samp{[int, 1, 2, 3]}.
+In other words, the range of possible values means only that
+the variable's value must be numerically equal to a number in
+that range, but not that it must be equal in type as well.
+Calc's set operations act the same way; @samp{in(2, [1., 2., 3.])}
+and @samp{in(1.5, [1:2, 3:2, 5:2])} both report ``true.''
+
+If you use a conflicting combination of type specifiers, the
+results are unpredictable. An example is @samp{[pos, [0 .. 5]]},
+where the interval does not lie in the range described by the
+type symbol.
+
+``Real'' declarations mostly affect simplifications involving powers
+like the one described above. Another case where they are used
+is in the @kbd{a P} command which returns a list of all roots of a
+polynomial; if the variable has been declared real, only the real
+roots (if any) will be included in the list.
+
+``Integer'' declarations are used for simplifications which are valid
+only when certain values are integers (such as @samp{(x^y)^z}
+shown above).
+
+Another command that makes use of declarations is @kbd{a s}, when
+simplifying equations and inequalities. It will cancel @code{x}
+from both sides of @samp{a x = b x} only if it is sure @code{x}
+is non-zero, say, because it has a @code{pos} declaration.
+To declare specifically that @code{x} is real and non-zero,
+use @samp{[[-inf .. 0), (0 .. inf]]}. (There is no way in the
+current notation to say that @code{x} is nonzero but not necessarily
+real.) The @kbd{a e} command does ``unsafe'' simplifications,
+including cancelling @samp{x} from the equation when @samp{x} is
+not known to be nonzero.
+
+Another set of type symbols distinguish between scalars and vectors.
+
+@table @code
+@item scalar
+The value is not a vector.
+@item vector
+The value is a vector.
+@item matrix
+The value is a matrix (a rectangular vector of vectors).
+@item sqmatrix
+The value is a square matrix.
+@end table
+
+These type symbols can be combined with the other type symbols
+described above; @samp{[int, matrix]} describes an object which
+is a matrix of integers.
+
+Scalar/vector declarations are used to determine whether certain
+algebraic operations are safe. For example, @samp{[a, b, c] + x}
+is normally not simplified to @samp{[a + x, b + x, c + x]}, but
+it will be if @code{x} has been declared @code{scalar}. On the
+other hand, multiplication is usually assumed to be commutative,
+but the terms in @samp{x y} will never be exchanged if both @code{x}
+and @code{y} are known to be vectors or matrices. (Calc currently
+never distinguishes between @code{vector} and @code{matrix}
+declarations.)
+
+@xref{Matrix Mode}, for a discussion of Matrix mode and
+Scalar mode, which are similar to declaring @samp{[All, matrix]}
+or @samp{[All, scalar]} but much more convenient.
+
+One more type symbol that is recognized is used with the @kbd{H a d}
+command for taking total derivatives of a formula. @xref{Calculus}.
+
+@table @code
+@item const
+The value is a constant with respect to other variables.
+@end table
+
+Calc does not check the declarations for a variable when you store
+a value in it. However, storing @mathit{-3.5} in a variable that has
+been declared @code{pos}, @code{int}, or @code{matrix} may have
+unexpected effects; Calc may evaluate @samp{sqrt(x^2)} to @expr{3.5}
+if it substitutes the value first, or to @expr{-3.5} if @code{x}
+was declared @code{pos} and the formula @samp{sqrt(x^2)} is
+simplified to @samp{x} before the value is substituted. Before
+using a variable for a new purpose, it is best to use @kbd{s d}
+or @kbd{s D} to check to make sure you don't still have an old
+declaration for the variable that will conflict with its new meaning.
+
+@node Functions for Declarations, , Kinds of Declarations, Declarations
+@subsection Functions for Declarations
+
+@noindent
+Calc has a set of functions for accessing the current declarations
+in a convenient manner. These functions return 1 if the argument
+can be shown to have the specified property, or 0 if the argument
+can be shown @emph{not} to have that property; otherwise they are
+left unevaluated. These functions are suitable for use with rewrite
+rules (@pxref{Conditional Rewrite Rules}) or programming constructs
+(@pxref{Conditionals in Macros}). They can be entered only using
+algebraic notation. @xref{Logical Operations}, for functions
+that perform other tests not related to declarations.
+
+For example, @samp{dint(17)} returns 1 because 17 is an integer, as
+do @samp{dint(n)} and @samp{dint(2 n - 3)} if @code{n} has been declared
+@code{int}, but @samp{dint(2.5)} and @samp{dint(n + 0.5)} return 0.
+Calc consults knowledge of its own built-in functions as well as your
+own declarations: @samp{dint(floor(x))} returns 1.
+
+@ignore
+@starindex
+@end ignore
+@tindex dint
+@ignore
+@starindex
+@end ignore
+@tindex dnumint
+@ignore
+@starindex
+@end ignore
+@tindex dnatnum
+The @code{dint} function checks if its argument is an integer.
+The @code{dnatnum} function checks if its argument is a natural
+number, i.e., a nonnegative integer. The @code{dnumint} function
+checks if its argument is numerically an integer, i.e., either an
+integer or an integer-valued float. Note that these and the other
+data type functions also accept vectors or matrices composed of
+suitable elements, and that real infinities @samp{inf} and @samp{-inf}
+are considered to be integers for the purposes of these functions.
+
+@ignore
+@starindex
+@end ignore
+@tindex drat
+The @code{drat} function checks if its argument is rational, i.e.,
+an integer or fraction. Infinities count as rational, but intervals
+and error forms do not.
+
+@ignore
+@starindex
+@end ignore
+@tindex dreal
+The @code{dreal} function checks if its argument is real. This
+includes integers, fractions, floats, real error forms, and intervals.
+
+@ignore
+@starindex
+@end ignore
+@tindex dimag
+The @code{dimag} function checks if its argument is imaginary,
+i.e., is mathematically equal to a real number times @expr{i}.
+
+@ignore
+@starindex
+@end ignore
+@tindex dpos
+@ignore
+@starindex
+@end ignore
+@tindex dneg
+@ignore
+@starindex
+@end ignore
+@tindex dnonneg
+The @code{dpos} function checks for positive (but nonzero) reals.
+The @code{dneg} function checks for negative reals. The @code{dnonneg}
+function checks for nonnegative reals, i.e., reals greater than or
+equal to zero. Note that the @kbd{a s} command can simplify an
+expression like @expr{x > 0} to 1 or 0 using @code{dpos}, and that
+@kbd{a s} is effectively applied to all conditions in rewrite rules,
+so the actual functions @code{dpos}, @code{dneg}, and @code{dnonneg}
+are rarely necessary.
+
+@ignore
+@starindex
+@end ignore
+@tindex dnonzero
+The @code{dnonzero} function checks that its argument is nonzero.
+This includes all nonzero real or complex numbers, all intervals that
+do not include zero, all nonzero modulo forms, vectors all of whose
+elements are nonzero, and variables or formulas whose values can be
+deduced to be nonzero. It does not include error forms, since they
+represent values which could be anything including zero. (This is
+also the set of objects considered ``true'' in conditional contexts.)
+
+@ignore
+@starindex
+@end ignore
+@tindex deven
+@ignore
+@starindex
+@end ignore
+@tindex dodd
+The @code{deven} function returns 1 if its argument is known to be
+an even integer (or integer-valued float); it returns 0 if its argument
+is known not to be even (because it is known to be odd or a non-integer).
+The @kbd{a s} command uses this to simplify a test of the form
+@samp{x % 2 = 0}. There is also an analogous @code{dodd} function.
+
+@ignore
+@starindex
+@end ignore
+@tindex drange
+The @code{drange} function returns a set (an interval or a vector
+of intervals and/or numbers; @pxref{Set Operations}) that describes
+the set of possible values of its argument. If the argument is
+a variable or a function with a declaration, the range is copied
+from the declaration. Otherwise, the possible signs of the
+expression are determined using a method similar to @code{dpos},
+etc., and a suitable set like @samp{[0 .. inf]} is returned. If
+the expression is not provably real, the @code{drange} function
+remains unevaluated.
+
+@ignore
+@starindex
+@end ignore
+@tindex dscalar
+The @code{dscalar} function returns 1 if its argument is provably
+scalar, or 0 if its argument is provably non-scalar. It is left
+unevaluated if this cannot be determined. (If Matrix mode or Scalar
+mode is in effect, this function returns 1 or 0, respectively,
+if it has no other information.) When Calc interprets a condition
+(say, in a rewrite rule) it considers an unevaluated formula to be
+``false.'' Thus, @samp{dscalar(a)} is ``true'' only if @code{a} is
+provably scalar, and @samp{!dscalar(a)} is ``true'' only if @code{a}
+is provably non-scalar; both are ``false'' if there is insufficient
+information to tell.
+
+@node Display Modes, Language Modes, Declarations, Mode Settings
+@section Display Modes
+
+@noindent
+The commands in this section are two-key sequences beginning with the
+@kbd{d} prefix. The @kbd{d l} (@code{calc-line-numbering}) and @kbd{d b}
+(@code{calc-line-breaking}) commands are described elsewhere;
+@pxref{Stack Basics} and @pxref{Normal Language Modes}, respectively.
+Display formats for vectors and matrices are also covered elsewhere;
+@pxref{Vector and Matrix Formats}.
+
+One thing all display modes have in common is their treatment of the
+@kbd{H} prefix. This prefix causes any mode command that would normally
+refresh the stack to leave the stack display alone. The word ``Dirty''
+will appear in the mode line when Calc thinks the stack display may not
+reflect the latest mode settings.
+
+@kindex d @key{RET}
+@pindex calc-refresh-top
+The @kbd{d @key{RET}} (@code{calc-refresh-top}) command reformats the
+top stack entry according to all the current modes. Positive prefix
+arguments reformat the top @var{n} entries; negative prefix arguments
+reformat the specified entry, and a prefix of zero is equivalent to
+@kbd{d @key{SPC}} (@code{calc-refresh}), which reformats the entire stack.
+For example, @kbd{H d s M-2 d @key{RET}} changes to scientific notation
+but reformats only the top two stack entries in the new mode.
+
+The @kbd{I} prefix has another effect on the display modes. The mode
+is set only temporarily; the top stack entry is reformatted according
+to that mode, then the original mode setting is restored. In other
+words, @kbd{I d s} is equivalent to @kbd{H d s d @key{RET} H d (@var{old mode})}.
+
+@menu
+* Radix Modes::
+* Grouping Digits::
+* Float Formats::
+* Complex Formats::
+* Fraction Formats::
+* HMS Formats::
+* Date Formats::
+* Truncating the Stack::
+* Justification::
+* Labels::
+@end menu
+
+@node Radix Modes, Grouping Digits, Display Modes, Display Modes
+@subsection Radix Modes
+
+@noindent
+@cindex Radix display
+@cindex Non-decimal numbers
+@cindex Decimal and non-decimal numbers
+Calc normally displays numbers in decimal (@dfn{base-10} or @dfn{radix-10})
+notation. Calc can actually display in any radix from two (binary) to 36.
+When the radix is above 10, the letters @code{A} to @code{Z} are used as
+digits. When entering such a number, letter keys are interpreted as
+potential digits rather than terminating numeric entry mode.
+
+@kindex d 2
+@kindex d 8
+@kindex d 6
+@kindex d 0
+@cindex Hexadecimal integers
+@cindex Octal integers
+The key sequences @kbd{d 2}, @kbd{d 8}, @kbd{d 6}, and @kbd{d 0} select
+binary, octal, hexadecimal, and decimal as the current display radix,
+respectively. Numbers can always be entered in any radix, though the
+current radix is used as a default if you press @kbd{#} without any initial
+digits. A number entered without a @kbd{#} is @emph{always} interpreted
+as decimal.
+
+@kindex d r
+@pindex calc-radix
+To set the radix generally, use @kbd{d r} (@code{calc-radix}) and enter
+an integer from 2 to 36. You can specify the radix as a numeric prefix
+argument; otherwise you will be prompted for it.
+
+@kindex d z
+@pindex calc-leading-zeros
+@cindex Leading zeros
+Integers normally are displayed with however many digits are necessary to
+represent the integer and no more. The @kbd{d z} (@code{calc-leading-zeros})
+command causes integers to be padded out with leading zeros according to the
+current binary word size. (@xref{Binary Functions}, for a discussion of
+word size.) If the absolute value of the word size is @expr{w}, all integers
+are displayed with at least enough digits to represent
+@texline @math{2^w-1}
+@infoline @expr{(2^w)-1}
+in the current radix. (Larger integers will still be displayed in their
+entirety.)
+
+@node Grouping Digits, Float Formats, Radix Modes, Display Modes
+@subsection Grouping Digits
+
+@noindent
+@kindex d g
+@pindex calc-group-digits
+@cindex Grouping digits
+@cindex Digit grouping
+Long numbers can be hard to read if they have too many digits. For
+example, the factorial of 30 is 33 digits long! Press @kbd{d g}
+(@code{calc-group-digits}) to enable @dfn{Grouping} mode, in which digits
+are displayed in clumps of 3 or 4 (depending on the current radix)
+separated by commas.
+
+The @kbd{d g} command toggles grouping on and off.
+With a numeric prefix of 0, this command displays the current state of
+the grouping flag; with an argument of minus one it disables grouping;
+with a positive argument @expr{N} it enables grouping on every @expr{N}
+digits. For floating-point numbers, grouping normally occurs only
+before the decimal point. A negative prefix argument @expr{-N} enables
+grouping every @expr{N} digits both before and after the decimal point.
+
+@kindex d ,
+@pindex calc-group-char
+The @kbd{d ,} (@code{calc-group-char}) command allows you to choose any
+character as the grouping separator. The default is the comma character.
+If you find it difficult to read vectors of large integers grouped with
+commas, you may wish to use spaces or some other character instead.
+This command takes the next character you type, whatever it is, and
+uses it as the digit separator. As a special case, @kbd{d , \} selects
+@samp{\,} (@TeX{}'s thin-space symbol) as the digit separator.
+
+Please note that grouped numbers will not generally be parsed correctly
+if re-read in textual form, say by the use of @kbd{C-x * y} and @kbd{C-x * g}.
+(@xref{Kill and Yank}, for details on these commands.) One exception is
+the @samp{\,} separator, which doesn't interfere with parsing because it
+is ignored by @TeX{} language mode.
+
+@node Float Formats, Complex Formats, Grouping Digits, Display Modes
+@subsection Float Formats
+
+@noindent
+Floating-point quantities are normally displayed in standard decimal
+form, with scientific notation used if the exponent is especially high
+or low. All significant digits are normally displayed. The commands
+in this section allow you to choose among several alternative display
+formats for floats.
+
+@kindex d n
+@pindex calc-normal-notation
+The @kbd{d n} (@code{calc-normal-notation}) command selects the normal
+display format. All significant figures in a number are displayed.
+With a positive numeric prefix, numbers are rounded if necessary to
+that number of significant digits. With a negative numerix prefix,
+the specified number of significant digits less than the current
+precision is used. (Thus @kbd{C-u -2 d n} displays 10 digits if the
+current precision is 12.)
+
+@kindex d f
+@pindex calc-fix-notation
+The @kbd{d f} (@code{calc-fix-notation}) command selects fixed-point
+notation. The numeric argument is the number of digits after the
+decimal point, zero or more. This format will relax into scientific
+notation if a nonzero number would otherwise have been rounded all the
+way to zero. Specifying a negative number of digits is the same as
+for a positive number, except that small nonzero numbers will be rounded
+to zero rather than switching to scientific notation.
+
+@kindex d s
+@pindex calc-sci-notation
+@cindex Scientific notation, display of
+The @kbd{d s} (@code{calc-sci-notation}) command selects scientific
+notation. A positive argument sets the number of significant figures
+displayed, of which one will be before and the rest after the decimal
+point. A negative argument works the same as for @kbd{d n} format.
+The default is to display all significant digits.
+
+@kindex d e
+@pindex calc-eng-notation
+@cindex Engineering notation, display of
+The @kbd{d e} (@code{calc-eng-notation}) command selects engineering
+notation. This is similar to scientific notation except that the
+exponent is rounded down to a multiple of three, with from one to three
+digits before the decimal point. An optional numeric prefix sets the
+number of significant digits to display, as for @kbd{d s}.
+
+It is important to distinguish between the current @emph{precision} and
+the current @emph{display format}. After the commands @kbd{C-u 10 p}
+and @kbd{C-u 6 d n} the Calculator computes all results to ten
+significant figures but displays only six. (In fact, intermediate
+calculations are often carried to one or two more significant figures,
+but values placed on the stack will be rounded down to ten figures.)
+Numbers are never actually rounded to the display precision for storage,
+except by commands like @kbd{C-k} and @kbd{C-x * y} which operate on the
+actual displayed text in the Calculator buffer.
+
+@kindex d .
+@pindex calc-point-char
+The @kbd{d .} (@code{calc-point-char}) command selects the character used
+as a decimal point. Normally this is a period; users in some countries
+may wish to change this to a comma. Note that this is only a display
+style; on entry, periods must always be used to denote floating-point
+numbers, and commas to separate elements in a list.
+
+@node Complex Formats, Fraction Formats, Float Formats, Display Modes
+@subsection Complex Formats
+
+@noindent
+@kindex d c
+@pindex calc-complex-notation
+There are three supported notations for complex numbers in rectangular
+form. The default is as a pair of real numbers enclosed in parentheses
+and separated by a comma: @samp{(a,b)}. The @kbd{d c}
+(@code{calc-complex-notation}) command selects this style.
+
+@kindex d i
+@pindex calc-i-notation
+@kindex d j
+@pindex calc-j-notation
+The other notations are @kbd{d i} (@code{calc-i-notation}), in which
+numbers are displayed in @samp{a+bi} form, and @kbd{d j}
+(@code{calc-j-notation}) which displays the form @samp{a+bj} preferred
+in some disciplines.
+
+@cindex @code{i} variable
+@vindex i
+Complex numbers are normally entered in @samp{(a,b)} format.
+If you enter @samp{2+3i} as an algebraic formula, it will be stored as
+the formula @samp{2 + 3 * i}. However, if you use @kbd{=} to evaluate
+this formula and you have not changed the variable @samp{i}, the @samp{i}
+will be interpreted as @samp{(0,1)} and the formula will be simplified
+to @samp{(2,3)}. Other commands (like @code{calc-sin}) will @emph{not}
+interpret the formula @samp{2 + 3 * i} as a complex number.
+@xref{Variables}, under ``special constants.''
+
+@node Fraction Formats, HMS Formats, Complex Formats, Display Modes
+@subsection Fraction Formats
+
+@noindent
+@kindex d o
+@pindex calc-over-notation
+Display of fractional numbers is controlled by the @kbd{d o}
+(@code{calc-over-notation}) command. By default, a number like
+eight thirds is displayed in the form @samp{8:3}. The @kbd{d o} command
+prompts for a one- or two-character format. If you give one character,
+that character is used as the fraction separator. Common separators are
+@samp{:} and @samp{/}. (During input of numbers, the @kbd{:} key must be
+used regardless of the display format; in particular, the @kbd{/} is used
+for RPN-style division, @emph{not} for entering fractions.)
+
+If you give two characters, fractions use ``integer-plus-fractional-part''
+notation. For example, the format @samp{+/} would display eight thirds
+as @samp{2+2/3}. If two colons are present in a number being entered,
+the number is interpreted in this form (so that the entries @kbd{2:2:3}
+and @kbd{8:3} are equivalent).
+
+It is also possible to follow the one- or two-character format with
+a number. For example: @samp{:10} or @samp{+/3}. In this case,
+Calc adjusts all fractions that are displayed to have the specified
+denominator, if possible. Otherwise it adjusts the denominator to
+be a multiple of the specified value. For example, in @samp{:6} mode
+the fraction @expr{1:6} will be unaffected, but @expr{2:3} will be
+displayed as @expr{4:6}, @expr{1:2} will be displayed as @expr{3:6},
+and @expr{1:8} will be displayed as @expr{3:24}. Integers are also
+affected by this mode: 3 is displayed as @expr{18:6}. Note that the
+format @samp{:1} writes fractions the same as @samp{:}, but it writes
+integers as @expr{n:1}.
+
+The fraction format does not affect the way fractions or integers are
+stored, only the way they appear on the screen. The fraction format
+never affects floats.
+
+@node HMS Formats, Date Formats, Fraction Formats, Display Modes
+@subsection HMS Formats
+
+@noindent
+@kindex d h
+@pindex calc-hms-notation
+The @kbd{d h} (@code{calc-hms-notation}) command controls the display of
+HMS (hours-minutes-seconds) forms. It prompts for a string which
+consists basically of an ``hours'' marker, optional punctuation, a
+``minutes'' marker, more optional punctuation, and a ``seconds'' marker.
+Punctuation is zero or more spaces, commas, or semicolons. The hours
+marker is one or more non-punctuation characters. The minutes and
+seconds markers must be single non-punctuation characters.
+
+The default HMS format is @samp{@@ ' "}, producing HMS values of the form
+@samp{23@@ 30' 15.75"}. The format @samp{deg, ms} would display this same
+value as @samp{23deg, 30m15.75s}. During numeric entry, the @kbd{h} or @kbd{o}
+keys are recognized as synonyms for @kbd{@@} regardless of display format.
+The @kbd{m} and @kbd{s} keys are recognized as synonyms for @kbd{'} and
+@kbd{"}, respectively, but only if an @kbd{@@} (or @kbd{h} or @kbd{o}) has
+already been typed; otherwise, they have their usual meanings
+(@kbd{m-} prefix and @kbd{s-} prefix). Thus, @kbd{5 "}, @kbd{0 @@ 5 "}, and
+@kbd{0 h 5 s} are some of the ways to enter the quantity ``five seconds.''
+The @kbd{'} key is recognized as ``minutes'' only if @kbd{@@} (or @kbd{h} or
+@kbd{o}) has already been pressed; otherwise it means to switch to algebraic
+entry.
+
+@node Date Formats, Truncating the Stack, HMS Formats, Display Modes
+@subsection Date Formats
+
+@noindent
+@kindex d d
+@pindex calc-date-notation
+The @kbd{d d} (@code{calc-date-notation}) command controls the display
+of date forms (@pxref{Date Forms}). It prompts for a string which
+contains letters that represent the various parts of a date and time.
+To show which parts should be omitted when the form represents a pure
+date with no time, parts of the string can be enclosed in @samp{< >}
+marks. If you don't include @samp{< >} markers in the format, Calc
+guesses at which parts, if any, should be omitted when formatting
+pure dates.
+
+The default format is: @samp{<H:mm:SSpp >Www Mmm D, YYYY}.
+An example string in this format is @samp{3:32pm Wed Jan 9, 1991}.
+If you enter a blank format string, this default format is
+reestablished.
+
+Calc uses @samp{< >} notation for nameless functions as well as for
+dates. @xref{Specifying Operators}. To avoid confusion with nameless
+functions, your date formats should avoid using the @samp{#} character.
+
+@menu
+* Date Formatting Codes::
+* Free-Form Dates::
+* Standard Date Formats::
+@end menu
+
+@node Date Formatting Codes, Free-Form Dates, Date Formats, Date Formats
+@subsubsection Date Formatting Codes
+
+@noindent
+When displaying a date, the current date format is used. All
+characters except for letters and @samp{<} and @samp{>} are
+copied literally when dates are formatted. The portion between
+@samp{< >} markers is omitted for pure dates, or included for
+date/time forms. Letters are interpreted according to the table
+below.
+
+When dates are read in during algebraic entry, Calc first tries to
+match the input string to the current format either with or without
+the time part. The punctuation characters (including spaces) must
+match exactly; letter fields must correspond to suitable text in
+the input. If this doesn't work, Calc checks if the input is a
+simple number; if so, the number is interpreted as a number of days
+since Jan 1, 1 AD. Otherwise, Calc tries a much more relaxed and
+flexible algorithm which is described in the next section.
+
+Weekday names are ignored during reading.
+
+Two-digit year numbers are interpreted as lying in the range
+from 1941 to 2039. Years outside that range are always
+entered and displayed in full. Year numbers with a leading
+@samp{+} sign are always interpreted exactly, allowing the
+entry and display of the years 1 through 99 AD.
+
+Here is a complete list of the formatting codes for dates:
+
+@table @asis
+@item Y
+Year: ``91'' for 1991, ``7'' for 2007, ``+23'' for 23 AD.
+@item YY
+Year: ``91'' for 1991, ``07'' for 2007, ``+23'' for 23 AD.
+@item BY
+Year: ``91'' for 1991, `` 7'' for 2007, ``+23'' for 23 AD.
+@item YYY
+Year: ``1991'' for 1991, ``23'' for 23 AD.
+@item YYYY
+Year: ``1991'' for 1991, ``+23'' for 23 AD.
+@item aa
+Year: ``ad'' or blank.
+@item AA
+Year: ``AD'' or blank.
+@item aaa
+Year: ``ad '' or blank. (Note trailing space.)
+@item AAA
+Year: ``AD '' or blank.
+@item aaaa
+Year: ``a.d.'' or blank.
+@item AAAA
+Year: ``A.D.'' or blank.
+@item bb
+Year: ``bc'' or blank.
+@item BB
+Year: ``BC'' or blank.
+@item bbb
+Year: `` bc'' or blank. (Note leading space.)
+@item BBB
+Year: `` BC'' or blank.
+@item bbbb
+Year: ``b.c.'' or blank.
+@item BBBB
+Year: ``B.C.'' or blank.
+@item M
+Month: ``8'' for August.
+@item MM
+Month: ``08'' for August.
+@item BM
+Month: `` 8'' for August.
+@item MMM
+Month: ``AUG'' for August.
+@item Mmm
+Month: ``Aug'' for August.
+@item mmm
+Month: ``aug'' for August.
+@item MMMM
+Month: ``AUGUST'' for August.
+@item Mmmm
+Month: ``August'' for August.
+@item D
+Day: ``7'' for 7th day of month.
+@item DD
+Day: ``07'' for 7th day of month.
+@item BD
+Day: `` 7'' for 7th day of month.
+@item W
+Weekday: ``0'' for Sunday, ``6'' for Saturday.
+@item WWW
+Weekday: ``SUN'' for Sunday.
+@item Www
+Weekday: ``Sun'' for Sunday.
+@item www
+Weekday: ``sun'' for Sunday.
+@item WWWW
+Weekday: ``SUNDAY'' for Sunday.
+@item Wwww
+Weekday: ``Sunday'' for Sunday.
+@item d
+Day of year: ``34'' for Feb. 3.
+@item ddd
+Day of year: ``034'' for Feb. 3.
+@item bdd
+Day of year: `` 34'' for Feb. 3.
+@item h
+Hour: ``5'' for 5 AM; ``17'' for 5 PM.
+@item hh
+Hour: ``05'' for 5 AM; ``17'' for 5 PM.
+@item bh
+Hour: `` 5'' for 5 AM; ``17'' for 5 PM.
+@item H
+Hour: ``5'' for 5 AM and 5 PM.
+@item HH
+Hour: ``05'' for 5 AM and 5 PM.
+@item BH
+Hour: `` 5'' for 5 AM and 5 PM.
+@item p
+AM/PM: ``a'' or ``p''.
+@item P
+AM/PM: ``A'' or ``P''.
+@item pp
+AM/PM: ``am'' or ``pm''.
+@item PP
+AM/PM: ``AM'' or ``PM''.
+@item pppp
+AM/PM: ``a.m.'' or ``p.m.''.
+@item PPPP
+AM/PM: ``A.M.'' or ``P.M.''.
+@item m
+Minutes: ``7'' for 7.
+@item mm
+Minutes: ``07'' for 7.
+@item bm
+Minutes: `` 7'' for 7.
+@item s
+Seconds: ``7'' for 7; ``7.23'' for 7.23.
+@item ss
+Seconds: ``07'' for 7; ``07.23'' for 7.23.
+@item bs
+Seconds: `` 7'' for 7; `` 7.23'' for 7.23.
+@item SS
+Optional seconds: ``07'' for 7; blank for 0.
+@item BS
+Optional seconds: `` 7'' for 7; blank for 0.
+@item N
+Numeric date/time: ``726842.25'' for 6:00am Wed Jan 9, 1991.
+@item n
+Numeric date: ``726842'' for any time on Wed Jan 9, 1991.
+@item J
+Julian date/time: ``2448265.75'' for 6:00am Wed Jan 9, 1991.
+@item j
+Julian date: ``2448266'' for any time on Wed Jan 9, 1991.
+@item U
+Unix time: ``663400800'' for 6:00am Wed Jan 9, 1991.
+@item X
+Brackets suppression. An ``X'' at the front of the format
+causes the surrounding @w{@samp{< >}} delimiters to be omitted
+when formatting dates. Note that the brackets are still
+required for algebraic entry.
+@end table
+
+If ``SS'' or ``BS'' (optional seconds) is preceded by a colon, the
+colon is also omitted if the seconds part is zero.
+
+If ``bb,'' ``bbb'' or ``bbbb'' or their upper-case equivalents
+appear in the format, then negative year numbers are displayed
+without a minus sign. Note that ``aa'' and ``bb'' are mutually
+exclusive. Some typical usages would be @samp{YYYY AABB};
+@samp{AAAYYYYBBB}; @samp{YYYYBBB}.
+
+The formats ``YY,'' ``YYYY,'' ``MM,'' ``DD,'' ``ddd,'' ``hh,'' ``HH,''
+``mm,'' ``ss,'' and ``SS'' actually match any number of digits during
+reading unless several of these codes are strung together with no
+punctuation in between, in which case the input must have exactly as
+many digits as there are letters in the format.
+
+The ``j,'' ``J,'' and ``U'' formats do not make any time zone
+adjustment. They effectively use @samp{julian(x,0)} and
+@samp{unixtime(x,0)} to make the conversion; @pxref{Date Arithmetic}.
+
+@node Free-Form Dates, Standard Date Formats, Date Formatting Codes, Date Formats
+@subsubsection Free-Form Dates
+
+@noindent
+When reading a date form during algebraic entry, Calc falls back
+on the algorithm described here if the input does not exactly
+match the current date format. This algorithm generally
+``does the right thing'' and you don't have to worry about it,
+but it is described here in full detail for the curious.
+
+Calc does not distinguish between upper- and lower-case letters
+while interpreting dates.
+
+First, the time portion, if present, is located somewhere in the
+text and then removed. The remaining text is then interpreted as
+the date.
+
+A time is of the form @samp{hh:mm:ss}, possibly with the seconds
+part omitted and possibly with an AM/PM indicator added to indicate
+12-hour time. If the AM/PM is present, the minutes may also be
+omitted. The AM/PM part may be any of the words @samp{am},
+@samp{pm}, @samp{noon}, or @samp{midnight}; each of these may be
+abbreviated to one letter, and the alternate forms @samp{a.m.},
+@samp{p.m.}, and @samp{mid} are also understood. Obviously
+@samp{noon} and @samp{midnight} are allowed only on 12:00:00.
+The words @samp{noon}, @samp{mid}, and @samp{midnight} are also
+recognized with no number attached.
+
+If there is no AM/PM indicator, the time is interpreted in 24-hour
+format.
+
+To read the date portion, all words and numbers are isolated
+from the string; other characters are ignored. All words must
+be either month names or day-of-week names (the latter of which
+are ignored). Names can be written in full or as three-letter
+abbreviations.
+
+Large numbers, or numbers with @samp{+} or @samp{-} signs,
+are interpreted as years. If one of the other numbers is
+greater than 12, then that must be the day and the remaining
+number in the input is therefore the month. Otherwise, Calc
+assumes the month, day and year are in the same order that they
+appear in the current date format. If the year is omitted, the
+current year is taken from the system clock.
+
+If there are too many or too few numbers, or any unrecognizable
+words, then the input is rejected.
+
+If there are any large numbers (of five digits or more) other than
+the year, they are ignored on the assumption that they are something
+like Julian dates that were included along with the traditional
+date components when the date was formatted.
+
+One of the words @samp{ad}, @samp{a.d.}, @samp{bc}, or @samp{b.c.}
+may optionally be used; the latter two are equivalent to a
+minus sign on the year value.
+
+If you always enter a four-digit year, and use a name instead
+of a number for the month, there is no danger of ambiguity.
+
+@node Standard Date Formats, , Free-Form Dates, Date Formats
+@subsubsection Standard Date Formats
+
+@noindent
+There are actually ten standard date formats, numbered 0 through 9.
+Entering a blank line at the @kbd{d d} command's prompt gives
+you format number 1, Calc's usual format. You can enter any digit
+to select the other formats.
+
+To create your own standard date formats, give a numeric prefix
+argument from 0 to 9 to the @w{@kbd{d d}} command. The format you
+enter will be recorded as the new standard format of that
+number, as well as becoming the new current date format.
+You can save your formats permanently with the @w{@kbd{m m}}
+command (@pxref{Mode Settings}).
+
+@table @asis
+@item 0
+@samp{N} (Numerical format)
+@item 1
+@samp{<H:mm:SSpp >Www Mmm D, YYYY} (American format)
+@item 2
+@samp{D Mmm YYYY<, h:mm:SS>} (European format)
+@item 3
+@samp{Www Mmm BD< hh:mm:ss> YYYY} (Unix written date format)
+@item 4
+@samp{M/D/Y< H:mm:SSpp>} (American slashed format)
+@item 5
+@samp{D.M.Y< h:mm:SS>} (European dotted format)
+@item 6
+@samp{M-D-Y< H:mm:SSpp>} (American dashed format)
+@item 7
+@samp{D-M-Y< h:mm:SS>} (European dashed format)
+@item 8
+@samp{j<, h:mm:ss>} (Julian day plus time)
+@item 9
+@samp{YYddd< hh:mm:ss>} (Year-day format)
+@end table
+
+@node Truncating the Stack, Justification, Date Formats, Display Modes
+@subsection Truncating the Stack
+
+@noindent
+@kindex d t
+@pindex calc-truncate-stack
+@cindex Truncating the stack
+@cindex Narrowing the stack
+The @kbd{d t} (@code{calc-truncate-stack}) command moves the @samp{.}@:
+line that marks the top-of-stack up or down in the Calculator buffer.
+The number right above that line is considered to the be at the top of
+the stack. Any numbers below that line are ``hidden'' from all stack
+operations (although still visible to the user). This is similar to the
+Emacs ``narrowing'' feature, except that the values below the @samp{.}
+are @emph{visible}, just temporarily frozen. This feature allows you to
+keep several independent calculations running at once in different parts
+of the stack, or to apply a certain command to an element buried deep in
+the stack.
+
+Pressing @kbd{d t} by itself moves the @samp{.} to the line the cursor
+is on. Thus, this line and all those below it become hidden. To un-hide
+these lines, move down to the end of the buffer and press @w{@kbd{d t}}.
+With a positive numeric prefix argument @expr{n}, @kbd{d t} hides the
+bottom @expr{n} values in the buffer. With a negative argument, it hides
+all but the top @expr{n} values. With an argument of zero, it hides zero
+values, i.e., moves the @samp{.} all the way down to the bottom.
+
+@kindex d [
+@pindex calc-truncate-up
+@kindex d ]
+@pindex calc-truncate-down
+The @kbd{d [} (@code{calc-truncate-up}) and @kbd{d ]}
+(@code{calc-truncate-down}) commands move the @samp{.} up or down one
+line at a time (or several lines with a prefix argument).
+
+@node Justification, Labels, Truncating the Stack, Display Modes
+@subsection Justification
+
+@noindent
+@kindex d <
+@pindex calc-left-justify
+@kindex d =
+@pindex calc-center-justify
+@kindex d >
+@pindex calc-right-justify
+Values on the stack are normally left-justified in the window. You can
+control this arrangement by typing @kbd{d <} (@code{calc-left-justify}),
+@kbd{d >} (@code{calc-right-justify}), or @kbd{d =}
+(@code{calc-center-justify}). For example, in Right-Justification mode,
+stack entries are displayed flush-right against the right edge of the
+window.
+
+If you change the width of the Calculator window you may have to type
+@kbd{d @key{SPC}} (@code{calc-refresh}) to re-align right-justified or centered
+text.
+
+Right-justification is especially useful together with fixed-point
+notation (see @code{d f}; @code{calc-fix-notation}). With these modes
+together, the decimal points on numbers will always line up.
+
+With a numeric prefix argument, the justification commands give you
+a little extra control over the display. The argument specifies the
+horizontal ``origin'' of a display line. It is also possible to
+specify a maximum line width using the @kbd{d b} command (@pxref{Normal
+Language Modes}). For reference, the precise rules for formatting and
+breaking lines are given below. Notice that the interaction between
+origin and line width is slightly different in each justification
+mode.
+
+In Left-Justified mode, the line is indented by a number of spaces
+given by the origin (default zero). If the result is longer than the
+maximum line width, if given, or too wide to fit in the Calc window
+otherwise, then it is broken into lines which will fit; each broken
+line is indented to the origin.
+
+In Right-Justified mode, lines are shifted right so that the rightmost
+character is just before the origin, or just before the current
+window width if no origin was specified. If the line is too long
+for this, then it is broken; the current line width is used, if
+specified, or else the origin is used as a width if that is
+specified, or else the line is broken to fit in the window.
+
+In Centering mode, the origin is the column number of the center of
+each stack entry. If a line width is specified, lines will not be
+allowed to go past that width; Calc will either indent less or
+break the lines if necessary. If no origin is specified, half the
+line width or Calc window width is used.
+
+Note that, in each case, if line numbering is enabled the display
+is indented an additional four spaces to make room for the line
+number. The width of the line number is taken into account when
+positioning according to the current Calc window width, but not
+when positioning by explicit origins and widths. In the latter
+case, the display is formatted as specified, and then uniformly
+shifted over four spaces to fit the line numbers.
+
+@node Labels, , Justification, Display Modes
+@subsection Labels
+
+@noindent
+@kindex d @{
+@pindex calc-left-label
+The @kbd{d @{} (@code{calc-left-label}) command prompts for a string,
+then displays that string to the left of every stack entry. If the
+entries are left-justified (@pxref{Justification}), then they will
+appear immediately after the label (unless you specified an origin
+greater than the length of the label). If the entries are centered
+or right-justified, the label appears on the far left and does not
+affect the horizontal position of the stack entry.
+
+Give a blank string (with @kbd{d @{ @key{RET}}) to turn the label off.
+
+@kindex d @}
+@pindex calc-right-label
+The @kbd{d @}} (@code{calc-right-label}) command similarly adds a
+label on the righthand side. It does not affect positioning of
+the stack entries unless they are right-justified. Also, if both
+a line width and an origin are given in Right-Justified mode, the
+stack entry is justified to the origin and the righthand label is
+justified to the line width.
+
+One application of labels would be to add equation numbers to
+formulas you are manipulating in Calc and then copying into a
+document (possibly using Embedded mode). The equations would
+typically be centered, and the equation numbers would be on the
+left or right as you prefer.
+
+@node Language Modes, Modes Variable, Display Modes, Mode Settings
+@section Language Modes
+
+@noindent
+The commands in this section change Calc to use a different notation for
+entry and display of formulas, corresponding to the conventions of some
+other common language such as Pascal or La@TeX{}. Objects displayed on the
+stack or yanked from the Calculator to an editing buffer will be formatted
+in the current language; objects entered in algebraic entry or yanked from
+another buffer will be interpreted according to the current language.
+
+The current language has no effect on things written to or read from the
+trail buffer, nor does it affect numeric entry. Only algebraic entry is
+affected. You can make even algebraic entry ignore the current language
+and use the standard notation by giving a numeric prefix, e.g., @kbd{C-u '}.
+
+For example, suppose the formula @samp{2*a[1] + atan(a[2])} occurs in a C
+program; elsewhere in the program you need the derivatives of this formula
+with respect to @samp{a[1]} and @samp{a[2]}. First, type @kbd{d C}
+to switch to C notation. Now use @code{C-u C-x * g} to grab the formula
+into the Calculator, @kbd{a d a[1] @key{RET}} to differentiate with respect
+to the first variable, and @kbd{C-x * y} to yank the formula for the derivative
+back into your C program. Press @kbd{U} to undo the differentiation and
+repeat with @kbd{a d a[2] @key{RET}} for the other derivative.
+
+Without being switched into C mode first, Calc would have misinterpreted
+the brackets in @samp{a[1]} and @samp{a[2]}, would not have known that
+@code{atan} was equivalent to Calc's built-in @code{arctan} function,
+and would have written the formula back with notations (like implicit
+multiplication) which would not have been valid for a C program.
+
+As another example, suppose you are maintaining a C program and a La@TeX{}
+document, each of which needs a copy of the same formula. You can grab the
+formula from the program in C mode, switch to La@TeX{} mode, and yank the
+formula into the document in La@TeX{} math-mode format.
+
+Language modes are selected by typing the letter @kbd{d} followed by a
+shifted letter key.
+
+@menu
+* Normal Language Modes::
+* C FORTRAN Pascal::
+* TeX and LaTeX Language Modes::
+* Eqn Language Mode::
+* Mathematica Language Mode::
+* Maple Language Mode::
+* Compositions::
+* Syntax Tables::
+@end menu
+
+@node Normal Language Modes, C FORTRAN Pascal, Language Modes, Language Modes
+@subsection Normal Language Modes
+
+@noindent
+@kindex d N
+@pindex calc-normal-language
+The @kbd{d N} (@code{calc-normal-language}) command selects the usual
+notation for Calc formulas, as described in the rest of this manual.
+Matrices are displayed in a multi-line tabular format, but all other
+objects are written in linear form, as they would be typed from the
+keyboard.
+
+@kindex d O
+@pindex calc-flat-language
+@cindex Matrix display
+The @kbd{d O} (@code{calc-flat-language}) command selects a language
+identical with the normal one, except that matrices are written in
+one-line form along with everything else. In some applications this
+form may be more suitable for yanking data into other buffers.
+
+@kindex d b
+@pindex calc-line-breaking
+@cindex Line breaking
+@cindex Breaking up long lines
+Even in one-line mode, long formulas or vectors will still be split
+across multiple lines if they exceed the width of the Calculator window.
+The @kbd{d b} (@code{calc-line-breaking}) command turns this line-breaking
+feature on and off. (It works independently of the current language.)
+If you give a numeric prefix argument of five or greater to the @kbd{d b}
+command, that argument will specify the line width used when breaking
+long lines.
+
+@kindex d B
+@pindex calc-big-language
+The @kbd{d B} (@code{calc-big-language}) command selects a language
+which uses textual approximations to various mathematical notations,
+such as powers, quotients, and square roots:
+
+@example
+ ____________
+ | a + 1 2
+ | ----- + c
+\| b
+@end example
+
+@noindent
+in place of @samp{sqrt((a+1)/b + c^2)}.
+
+Subscripts like @samp{a_i} are displayed as actual subscripts in Big
+mode. Double subscripts, @samp{a_i_j} (@samp{subscr(subscr(a, i), j)})
+are displayed as @samp{a} with subscripts separated by commas:
+@samp{i, j}. They must still be entered in the usual underscore
+notation.
+
+One slight ambiguity of Big notation is that
+
+@example
+ 3
+- -
+ 4
+@end example
+
+@noindent
+can represent either the negative rational number @expr{-3:4}, or the
+actual expression @samp{-(3/4)}; but the latter formula would normally
+never be displayed because it would immediately be evaluated to
+@expr{-3:4} or @expr{-0.75}, so this ambiguity is not a problem in
+typical use.
+
+Non-decimal numbers are displayed with subscripts. Thus there is no
+way to tell the difference between @samp{16#C2} and @samp{C2_16},
+though generally you will know which interpretation is correct.
+Logarithms @samp{log(x,b)} and @samp{log10(x)} also use subscripts
+in Big mode.
+
+In Big mode, stack entries often take up several lines. To aid
+readability, stack entries are separated by a blank line in this mode.
+You may find it useful to expand the Calc window's height using
+@kbd{C-x ^} (@code{enlarge-window}) or to make the Calc window the only
+one on the screen with @kbd{C-x 1} (@code{delete-other-windows}).
+
+Long lines are currently not rearranged to fit the window width in
+Big mode, so you may need to use the @kbd{<} and @kbd{>} keys
+to scroll across a wide formula. For really big formulas, you may
+even need to use @kbd{@{} and @kbd{@}} to scroll up and down.
+
+@kindex d U
+@pindex calc-unformatted-language
+The @kbd{d U} (@code{calc-unformatted-language}) command altogether disables
+the use of operator notation in formulas. In this mode, the formula
+shown above would be displayed:
+
+@example
+sqrt(add(div(add(a, 1), b), pow(c, 2)))
+@end example
+
+These four modes differ only in display format, not in the format
+expected for algebraic entry. The standard Calc operators work in
+all four modes, and unformatted notation works in any language mode
+(except that Mathematica mode expects square brackets instead of
+parentheses).
+
+@node C FORTRAN Pascal, TeX and LaTeX Language Modes, Normal Language Modes, Language Modes
+@subsection C, FORTRAN, and Pascal Modes
+
+@noindent
+@kindex d C
+@pindex calc-c-language
+@cindex C language
+The @kbd{d C} (@code{calc-c-language}) command selects the conventions
+of the C language for display and entry of formulas. This differs from
+the normal language mode in a variety of (mostly minor) ways. In
+particular, C language operators and operator precedences are used in
+place of Calc's usual ones. For example, @samp{a^b} means @samp{xor(a,b)}
+in C mode; a value raised to a power is written as a function call,
+@samp{pow(a,b)}.
+
+In C mode, vectors and matrices use curly braces instead of brackets.
+Octal and hexadecimal values are written with leading @samp{0} or @samp{0x}
+rather than using the @samp{#} symbol. Array subscripting is
+translated into @code{subscr} calls, so that @samp{a[i]} in C
+mode is the same as @samp{a_i} in Normal mode. Assignments
+turn into the @code{assign} function, which Calc normally displays
+using the @samp{:=} symbol.
+
+The variables @code{pi} and @code{e} would be displayed @samp{pi}
+and @samp{e} in Normal mode, but in C mode they are displayed as
+@samp{M_PI} and @samp{M_E}, corresponding to the names of constants
+typically provided in the @file{<math.h>} header. Functions whose
+names are different in C are translated automatically for entry and
+display purposes. For example, entering @samp{asin(x)} will push the
+formula @samp{arcsin(x)} onto the stack; this formula will be displayed
+as @samp{asin(x)} as long as C mode is in effect.
+
+@kindex d P
+@pindex calc-pascal-language
+@cindex Pascal language
+The @kbd{d P} (@code{calc-pascal-language}) command selects Pascal
+conventions. Like C mode, Pascal mode interprets array brackets and uses
+a different table of operators. Hexadecimal numbers are entered and
+displayed with a preceding dollar sign. (Thus the regular meaning of
+@kbd{$2} during algebraic entry does not work in Pascal mode, though
+@kbd{$} (and @kbd{$$}, etc.) not followed by digits works the same as
+always.) No special provisions are made for other non-decimal numbers,
+vectors, and so on, since there is no universally accepted standard way
+of handling these in Pascal.
+
+@kindex d F
+@pindex calc-fortran-language
+@cindex FORTRAN language
+The @kbd{d F} (@code{calc-fortran-language}) command selects FORTRAN
+conventions. Various function names are transformed into FORTRAN
+equivalents. Vectors are written as @samp{/1, 2, 3/}, and may be
+entered this way or using square brackets. Since FORTRAN uses round
+parentheses for both function calls and array subscripts, Calc displays
+both in the same way; @samp{a(i)} is interpreted as a function call
+upon reading, and subscripts must be entered as @samp{subscr(a, i)}.
+Also, if the variable @code{a} has been declared to have type
+@code{vector} or @code{matrix} then @samp{a(i)} will be parsed as a
+subscript. (@xref{Declarations}.) Usually it doesn't matter, though;
+if you enter the subscript expression @samp{a(i)} and Calc interprets
+it as a function call, you'll never know the difference unless you
+switch to another language mode or replace @code{a} with an actual
+vector (or unless @code{a} happens to be the name of a built-in
+function!).
+
+Underscores are allowed in variable and function names in all of these
+language modes. The underscore here is equivalent to the @samp{#} in
+Normal mode, or to hyphens in the underlying Emacs Lisp variable names.
+
+FORTRAN and Pascal modes normally do not adjust the case of letters in
+formulas. Most built-in Calc names use lower-case letters. If you use a
+positive numeric prefix argument with @kbd{d P} or @kbd{d F}, these
+modes will use upper-case letters exclusively for display, and will
+convert to lower-case on input. With a negative prefix, these modes
+convert to lower-case for display and input.
+
+@node TeX and LaTeX Language Modes, Eqn Language Mode, C FORTRAN Pascal, Language Modes
+@subsection @TeX{} and La@TeX{} Language Modes
+
+@noindent
+@kindex d T
+@pindex calc-tex-language
+@cindex TeX language
+@kindex d L
+@pindex calc-latex-language
+@cindex LaTeX language
+The @kbd{d T} (@code{calc-tex-language}) command selects the conventions
+of ``math mode'' in Donald Knuth's @TeX{} typesetting language,
+and the @kbd{d L} (@code{calc-latex-language}) command selects the
+conventions of ``math mode'' in La@TeX{}, a typesetting language that
+uses @TeX{} as its formatting engine. Calc's La@TeX{} language mode can
+read any formula that the @TeX{} language mode can, although La@TeX{}
+mode may display it differently.
+
+Formulas are entered and displayed in the appropriate notation;
+@texline @math{\sin(a/b)}
+@infoline @expr{sin(a/b)}
+will appear as @samp{\sin\left( a \over b \right)} in @TeX{} mode and
+@samp{\sin\left(\frac@{a@}@{b@}\right)} in La@TeX{} mode.
+Math formulas are often enclosed by @samp{$ $} signs in @TeX{} and
+La@TeX{}; these should be omitted when interfacing with Calc. To Calc,
+the @samp{$} sign has the same meaning it always does in algebraic
+formulas (a reference to an existing entry on the stack).
+
+Complex numbers are displayed as in @samp{3 + 4i}. Fractions and
+quotients are written using @code{\over} in @TeX{} mode (as in
+@code{@{a \over b@}}) and @code{\frac} in La@TeX{} mode (as in
+@code{\frac@{a@}@{b@}}); binomial coefficients are written with
+@code{\choose} in @TeX{} mode (as in @code{@{a \choose b@}}) and
+@code{\binom} in La@TeX{} mode (as in @code{\binom@{a@}@{b@}}).
+Interval forms are written with @code{\ldots}, and error forms are
+written with @code{\pm}. Absolute values are written as in
+@samp{|x + 1|}, and the floor and ceiling functions are written with
+@code{\lfloor}, @code{\rfloor}, etc. The words @code{\left} and
+@code{\right} are ignored when reading formulas in @TeX{} and La@TeX{}
+modes. Both @code{inf} and @code{uinf} are written as @code{\infty};
+when read, @code{\infty} always translates to @code{inf}.
+
+Function calls are written the usual way, with the function name followed
+by the arguments in parentheses. However, functions for which @TeX{}
+and La@TeX{} have special names (like @code{\sin}) will use curly braces
+instead of parentheses for very simple arguments. During input, curly
+braces and parentheses work equally well for grouping, but when the
+document is formatted the curly braces will be invisible. Thus the
+printed result is
+@texline @math{\sin{2 x}}
+@infoline @expr{sin 2x}
+but
+@texline @math{\sin(2 + x)}.
+@infoline @expr{sin(2 + x)}.
+
+Function and variable names not treated specially by @TeX{} and La@TeX{}
+are simply written out as-is, which will cause them to come out in
+italic letters in the printed document. If you invoke @kbd{d T} or
+@kbd{d L} with a positive numeric prefix argument, names of more than
+one character will instead be enclosed in a protective commands that
+will prevent them from being typeset in the math italics; they will be
+written @samp{\hbox@{@var{name}@}} in @TeX{} mode and
+@samp{\text@{@var{name}@}} in La@TeX{} mode. The
+@samp{\hbox@{ @}} and @samp{\text@{ @}} notations are ignored during
+reading. If you use a negative prefix argument, such function names are
+written @samp{\@var{name}}, and function names that begin with @code{\} during
+reading have the @code{\} removed. (Note that in this mode, long
+variable names are still written with @code{\hbox} or @code{\text}.
+However, you can always make an actual variable name like @code{\bar} in
+any @TeX{} mode.)
+
+During reading, text of the form @samp{\matrix@{ ...@: @}} is replaced
+by @samp{[ ...@: ]}. The same also applies to @code{\pmatrix} and
+@code{\bmatrix}. In La@TeX{} mode this also applies to
+@samp{\begin@{matrix@} ... \end@{matrix@}},
+@samp{\begin@{bmatrix@} ... \end@{bmatrix@}},
+@samp{\begin@{pmatrix@} ... \end@{pmatrix@}}, as well as
+@samp{\begin@{smallmatrix@} ... \end@{smallmatrix@}}.
+The symbol @samp{&} is interpreted as a comma,
+and the symbols @samp{\cr} and @samp{\\} are interpreted as semicolons.
+During output, matrices are displayed in @samp{\matrix@{ a & b \\ c & d@}}
+format in @TeX{} mode and in
+@samp{\begin@{pmatrix@} a & b \\ c & d \end@{pmatrix@}} format in
+La@TeX{} mode; you may need to edit this afterwards to change to your
+preferred matrix form. If you invoke @kbd{d T} or @kbd{d L} with an
+argument of 2 or -2, then matrices will be displayed in two-dimensional
+form, such as
+
+@example
+\begin@{pmatrix@}
+a & b \\
+c & d
+\end@{pmatrix@}
+@end example
+
+@noindent
+This may be convenient for isolated matrices, but could lead to
+expressions being displayed like
+
+@example
+\begin@{pmatrix@} \times x
+a & b \\
+c & d
+\end@{pmatrix@}
+@end example
+
+@noindent
+While this wouldn't bother Calc, it is incorrect La@TeX{}.
+(Similarly for @TeX{}.)
+
+Accents like @code{\tilde} and @code{\bar} translate into function
+calls internally (@samp{tilde(x)}, @samp{bar(x)}). The @code{\underline}
+sequence is treated as an accent. The @code{\vec} accent corresponds
+to the function name @code{Vec}, because @code{vec} is the name of
+a built-in Calc function. The following table shows the accents
+in Calc, @TeX{}, La@TeX{} and @dfn{eqn} (described in the next section):
+
+@iftex
+@begingroup
+@let@calcindexershow=@calcindexernoshow @c Suppress marginal notes
+@let@calcindexersh=@calcindexernoshow
+@end iftex
+@ignore
+@starindex
+@end ignore
+@tindex acute
+@ignore
+@starindex
+@end ignore
+@tindex Acute
+@ignore
+@starindex
+@end ignore
+@tindex bar
+@ignore
+@starindex
+@end ignore
+@tindex Bar
+@ignore
+@starindex
+@end ignore
+@tindex breve
+@ignore
+@starindex
+@end ignore
+@tindex Breve
+@ignore
+@starindex
+@end ignore
+@tindex check
+@ignore
+@starindex
+@end ignore
+@tindex Check
+@ignore
+@starindex
+@end ignore
+@tindex dddot
+@ignore
+@starindex
+@end ignore
+@tindex ddddot
+@ignore
+@starindex
+@end ignore
+@tindex dot
+@ignore
+@starindex
+@end ignore
+@tindex Dot
+@ignore
+@starindex
+@end ignore
+@tindex dotdot
+@ignore
+@starindex
+@end ignore
+@tindex DotDot
+@ignore
+@starindex
+@end ignore
+@tindex dyad
+@ignore
+@starindex
+@end ignore
+@tindex grave
+@ignore
+@starindex
+@end ignore
+@tindex Grave
+@ignore
+@starindex
+@end ignore
+@tindex hat
+@ignore
+@starindex
+@end ignore
+@tindex Hat
+@ignore
+@starindex
+@end ignore
+@tindex Prime
+@ignore
+@starindex
+@end ignore
+@tindex tilde
+@ignore
+@starindex
+@end ignore
+@tindex Tilde
+@ignore
+@starindex
+@end ignore
+@tindex under
+@ignore
+@starindex
+@end ignore
+@tindex Vec
+@ignore
+@starindex
+@end ignore
+@tindex VEC
+@iftex
+@endgroup
+@end iftex
+@example
+Calc TeX LaTeX eqn
+---- --- ----- ---
+acute \acute \acute
+Acute \Acute
+bar \bar \bar bar
+Bar \Bar
+breve \breve \breve
+Breve \Breve
+check \check \check
+Check \Check
+dddot \dddot
+ddddot \ddddot
+dot \dot \dot dot
+Dot \Dot
+dotdot \ddot \ddot dotdot
+DotDot \Ddot
+dyad dyad
+grave \grave \grave
+Grave \Grave
+hat \hat \hat hat
+Hat \Hat
+Prime prime
+tilde \tilde \tilde tilde
+Tilde \Tilde
+under \underline \underline under
+Vec \vec \vec vec
+VEC \Vec
+@end example
+
+The @samp{=>} (evaluates-to) operator appears as a @code{\to} symbol:
+@samp{@{@var{a} \to @var{b}@}}. @TeX{} defines @code{\to} as an
+alias for @code{\rightarrow}. However, if the @samp{=>} is the
+top-level expression being formatted, a slightly different notation
+is used: @samp{\evalto @var{a} \to @var{b}}. The @code{\evalto}
+word is ignored by Calc's input routines, and is undefined in @TeX{}.
+You will typically want to include one of the following definitions
+at the top of a @TeX{} file that uses @code{\evalto}:
+
+@example
+\def\evalto@{@}
+\def\evalto#1\to@{@}
+@end example
+
+The first definition formats evaluates-to operators in the usual
+way. The second causes only the @var{b} part to appear in the
+printed document; the @var{a} part and the arrow are hidden.
+Another definition you may wish to use is @samp{\let\to=\Rightarrow}
+which causes @code{\to} to appear more like Calc's @samp{=>} symbol.
+@xref{Evaluates-To Operator}, for a discussion of @code{evalto}.
+
+The complete set of @TeX{} control sequences that are ignored during
+reading is:
+
+@example
+\hbox \mbox \text \left \right
+\, \> \: \; \! \quad \qquad \hfil \hfill
+\displaystyle \textstyle \dsize \tsize
+\scriptstyle \scriptscriptstyle \ssize \ssize
+\rm \bf \it \sl \roman \bold \italic \slanted
+\cal \mit \Cal \Bbb \frak \goth
+\evalto
+@end example
+
+Note that, because these symbols are ignored, reading a @TeX{} or
+La@TeX{} formula into Calc and writing it back out may lose spacing and
+font information.
+
+Also, the ``discretionary multiplication sign'' @samp{\*} is read
+the same as @samp{*}.
+
+@ifnottex
+The @TeX{} version of this manual includes some printed examples at the
+end of this section.
+@end ifnottex
+@iftex
+Here are some examples of how various Calc formulas are formatted in @TeX{}:
+
+@example
+@group
+sin(a^2 / b_i)
+\sin\left( {a^2 \over b_i} \right)
+@end group
+@end example
+@tex
+$$ \sin\left( a^2 \over b_i \right) $$
+@end tex
+@sp 1
+
+@example
+@group
+[(3, 4), 3:4, 3 +/- 4, [3 .. inf)]
+[3 + 4i, @{3 \over 4@}, 3 \pm 4, [3 \ldots \infty)]
+@end group
+@end example
+@tex
+\turnoffactive
+$$ [3 + 4i, {3 \over 4}, 3 \pm 4, [ 3 \ldots \infty)] $$
+@end tex
+@sp 1
+
+@example
+@group
+[abs(a), abs(a / b), floor(a), ceil(a / b)]
+[|a|, \left| a \over b \right|,
+ \lfloor a \rfloor, \left\lceil a \over b \right\rceil]
+@end group
+@end example
+@tex
+$$ [|a|, \left| a \over b \right|,
+ \lfloor a \rfloor, \left\lceil a \over b \right\rceil] $$
+@end tex
+@sp 1
+
+@example
+@group
+[sin(a), sin(2 a), sin(2 + a), sin(a / b)]
+[\sin@{a@}, \sin@{2 a@}, \sin(2 + a),
+ \sin\left( @{a \over b@} \right)]
+@end group
+@end example
+@tex
+\turnoffactive
+$$ [\sin{a}, \sin{2 a}, \sin(2 + a), \sin\left( {a \over b} \right)] $$
+@end tex
+@sp 2
+
+First with plain @kbd{d T}, then with @kbd{C-u d T}, then finally with
+@kbd{C-u - d T} (using the example definition
+@samp{\def\foo#1@{\tilde F(#1)@}}:
+
+@example
+@group
+[f(a), foo(bar), sin(pi)]
+[f(a), foo(bar), \sin{\pi}]
+[f(a), \hbox@{foo@}(\hbox@{bar@}), \sin@{\pi@}]
+[f(a), \foo@{\hbox@{bar@}@}, \sin@{\pi@}]
+@end group
+@end example
+@tex
+$$ [f(a), foo(bar), \sin{\pi}] $$
+$$ [f(a), \hbox{foo}(\hbox{bar}), \sin{\pi}] $$
+$$ [f(a), \tilde F(\hbox{bar}), \sin{\pi}] $$
+@end tex
+@sp 2
+
+First with @samp{\def\evalto@{@}}, then with @samp{\def\evalto#1\to@{@}}:
+
+@example
+@group
+2 + 3 => 5
+\evalto 2 + 3 \to 5
+@end group
+@end example
+@tex
+\turnoffactive
+$$ 2 + 3 \to 5 $$
+$$ 5 $$
+@end tex
+@sp 2
+
+First with standard @code{\to}, then with @samp{\let\to\Rightarrow}:
+
+@example
+@group
+[2 + 3 => 5, a / 2 => (b + c) / 2]
+[@{2 + 3 \to 5@}, @{@{a \over 2@} \to @{b + c \over 2@}@}]
+@end group
+@end example
+@tex
+\turnoffactive
+$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$
+{\let\to\Rightarrow
+$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$}
+@end tex
+@sp 2
+
+Matrices normally, then changing @code{\matrix} to @code{\pmatrix}:
+
+@example
+@group
+[ [ a / b, 0 ], [ 0, 2^(x + 1) ] ]
+\matrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @}
+\pmatrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @}
+@end group
+@end example
+@tex
+\turnoffactive
+$$ \matrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$
+$$ \pmatrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$
+@end tex
+@sp 2
+@end iftex
+
+@node Eqn Language Mode, Mathematica Language Mode, TeX and LaTeX Language Modes, Language Modes
+@subsection Eqn Language Mode
+
+@noindent
+@kindex d E
+@pindex calc-eqn-language
+@dfn{Eqn} is another popular formatter for math formulas. It is
+designed for use with the TROFF text formatter, and comes standard
+with many versions of Unix. The @kbd{d E} (@code{calc-eqn-language})
+command selects @dfn{eqn} notation.
+
+The @dfn{eqn} language's main idiosyncrasy is that whitespace plays
+a significant part in the parsing of the language. For example,
+@samp{sqrt x+1 + y} treats @samp{x+1} as the argument of the
+@code{sqrt} operator. @dfn{Eqn} also understands more conventional
+grouping using curly braces: @samp{sqrt@{x+1@} + y}. Braces are
+required only when the argument contains spaces.
+
+In Calc's @dfn{eqn} mode, however, curly braces are required to
+delimit arguments of operators like @code{sqrt}. The first of the
+above examples would treat only the @samp{x} as the argument of
+@code{sqrt}, and in fact @samp{sin x+1} would be interpreted as
+@samp{sin * x + 1}, because @code{sin} is not a special operator
+in the @dfn{eqn} language. If you always surround the argument
+with curly braces, Calc will never misunderstand.
+
+Calc also understands parentheses as grouping characters. Another
+peculiarity of @dfn{eqn}'s syntax makes it advisable to separate
+words with spaces from any surrounding characters that aren't curly
+braces, so Calc writes @samp{sin ( x + y )} in @dfn{eqn} mode.
+(The spaces around @code{sin} are important to make @dfn{eqn}
+recognize that @code{sin} should be typeset in a roman font, and
+the spaces around @code{x} and @code{y} are a good idea just in
+case the @dfn{eqn} document has defined special meanings for these
+names, too.)
+
+Powers and subscripts are written with the @code{sub} and @code{sup}
+operators, respectively. Note that the caret symbol @samp{^} is
+treated the same as a space in @dfn{eqn} mode, as is the @samp{~}
+symbol (these are used to introduce spaces of various widths into
+the typeset output of @dfn{eqn}).
+
+As in La@TeX{} mode, Calc's formatter omits parentheses around the
+arguments of functions like @code{ln} and @code{sin} if they are
+``simple-looking''; in this case Calc surrounds the argument with
+braces, separated by a @samp{~} from the function name: @samp{sin~@{x@}}.
+
+Font change codes (like @samp{roman @var{x}}) and positioning codes
+(like @samp{~} and @samp{down @var{n} @var{x}}) are ignored by the
+@dfn{eqn} reader. Also ignored are the words @code{left}, @code{right},
+@code{mark}, and @code{lineup}. Quotation marks in @dfn{eqn} mode input
+are treated the same as curly braces: @samp{sqrt "1+x"} is equivalent to
+@samp{sqrt @{1+x@}}; this is only an approximation to the true meaning
+of quotes in @dfn{eqn}, but it is good enough for most uses.
+
+Accent codes (@samp{@var{x} dot}) are handled by treating them as
+function calls (@samp{dot(@var{x})}) internally.
+@xref{TeX and LaTeX Language Modes}, for a table of these accent
+functions. The @code{prime} accent is treated specially if it occurs on
+a variable or function name: @samp{f prime prime @w{( x prime )}} is
+stored internally as @samp{f'@w{'}(x')}. For example, taking the
+derivative of @samp{f(2 x)} with @kbd{a d x} will produce @samp{2 f'(2
+x)}, which @dfn{eqn} mode will display as @samp{2 f prime ( 2 x )}.
+
+Assignments are written with the @samp{<-} (left-arrow) symbol,
+and @code{evalto} operators are written with @samp{->} or
+@samp{evalto ... ->} (@pxref{TeX and LaTeX Language Modes}, for a discussion
+of this). The regular Calc symbols @samp{:=} and @samp{=>} are also
+recognized for these operators during reading.
+
+Vectors in @dfn{eqn} mode use regular Calc square brackets, but
+matrices are formatted as @samp{matrix @{ ccol @{ a above b @} ... @}}.
+The words @code{lcol} and @code{rcol} are recognized as synonyms
+for @code{ccol} during input, and are generated instead of @code{ccol}
+if the matrix justification mode so specifies.
+
+@node Mathematica Language Mode, Maple Language Mode, Eqn Language Mode, Language Modes
+@subsection Mathematica Language Mode
+
+@noindent
+@kindex d M
+@pindex calc-mathematica-language
+@cindex Mathematica language
+The @kbd{d M} (@code{calc-mathematica-language}) command selects the
+conventions of Mathematica. Notable differences in Mathematica mode
+are that the names of built-in functions are capitalized, and function
+calls use square brackets instead of parentheses. Thus the Calc
+formula @samp{sin(2 x)} is entered and displayed @w{@samp{Sin[2 x]}} in
+Mathematica mode.
+
+Vectors and matrices use curly braces in Mathematica. Complex numbers
+are written @samp{3 + 4 I}. The standard special constants in Calc are
+written @code{Pi}, @code{E}, @code{I}, @code{GoldenRatio}, @code{EulerGamma},
+@code{Infinity}, @code{ComplexInfinity}, and @code{Indeterminate} in
+Mathematica mode.
+Non-decimal numbers are written, e.g., @samp{16^^7fff}. Floating-point
+numbers in scientific notation are written @samp{1.23*10.^3}.
+Subscripts use double square brackets: @samp{a[[i]]}.
+
+@node Maple Language Mode, Compositions, Mathematica Language Mode, Language Modes
+@subsection Maple Language Mode
+
+@noindent
+@kindex d W
+@pindex calc-maple-language
+@cindex Maple language
+The @kbd{d W} (@code{calc-maple-language}) command selects the
+conventions of Maple.
+
+Maple's language is much like C. Underscores are allowed in symbol
+names; square brackets are used for subscripts; explicit @samp{*}s for
+multiplications are required. Use either @samp{^} or @samp{**} to
+denote powers.
+
+Maple uses square brackets for lists and curly braces for sets. Calc
+interprets both notations as vectors, and displays vectors with square
+brackets. This means Maple sets will be converted to lists when they
+pass through Calc. As a special case, matrices are written as calls
+to the function @code{matrix}, given a list of lists as the argument,
+and can be read in this form or with all-capitals @code{MATRIX}.
+
+The Maple interval notation @samp{2 .. 3} has no surrounding brackets;
+Calc reads @samp{2 .. 3} as the closed interval @samp{[2 .. 3]}, and
+writes any kind of interval as @samp{2 .. 3}. This means you cannot
+see the difference between an open and a closed interval while in
+Maple display mode.
+
+Maple writes complex numbers as @samp{3 + 4*I}. Its special constants
+are @code{Pi}, @code{E}, @code{I}, and @code{infinity} (all three of
+@code{inf}, @code{uinf}, and @code{nan} display as @code{infinity}).
+Floating-point numbers are written @samp{1.23*10.^3}.
+
+Among things not currently handled by Calc's Maple mode are the
+various quote symbols, procedures and functional operators, and
+inert (@samp{&}) operators.
+
+@node Compositions, Syntax Tables, Maple Language Mode, Language Modes
+@subsection Compositions
+
+@noindent
+@cindex Compositions
+There are several @dfn{composition functions} which allow you to get
+displays in a variety of formats similar to those in Big language
+mode. Most of these functions do not evaluate to anything; they are
+placeholders which are left in symbolic form by Calc's evaluator but
+are recognized by Calc's display formatting routines.
+
+Two of these, @code{string} and @code{bstring}, are described elsewhere.
+@xref{Strings}. For example, @samp{string("ABC")} is displayed as
+@samp{ABC}. When viewed on the stack it will be indistinguishable from
+the variable @code{ABC}, but internally it will be stored as
+@samp{string([65, 66, 67])} and can still be manipulated this way; for
+example, the selection and vector commands @kbd{j 1 v v j u} would
+select the vector portion of this object and reverse the elements, then
+deselect to reveal a string whose characters had been reversed.
+
+The composition functions do the same thing in all language modes
+(although their components will of course be formatted in the current
+language mode). The one exception is Unformatted mode (@kbd{d U}),
+which does not give the composition functions any special treatment.
+The functions are discussed here because of their relationship to
+the language modes.
+
+@menu
+* Composition Basics::
+* Horizontal Compositions::
+* Vertical Compositions::
+* Other Compositions::
+* Information about Compositions::
+* User-Defined Compositions::
+@end menu
+
+@node Composition Basics, Horizontal Compositions, Compositions, Compositions
+@subsubsection Composition Basics
+
+@noindent
+Compositions are generally formed by stacking formulas together
+horizontally or vertically in various ways. Those formulas are
+themselves compositions. @TeX{} users will find this analogous
+to @TeX{}'s ``boxes.'' Each multi-line composition has a
+@dfn{baseline}; horizontal compositions use the baselines to
+decide how formulas should be positioned relative to one another.
+For example, in the Big mode formula
+
+@example
+@group
+ 2
+ a + b
+17 + ------
+ c
+@end group
+@end example
+
+@noindent
+the second term of the sum is four lines tall and has line three as
+its baseline. Thus when the term is combined with 17, line three
+is placed on the same level as the baseline of 17.
+
+@tex
+\bigskip
+@end tex
+
+Another important composition concept is @dfn{precedence}. This is
+an integer that represents the binding strength of various operators.
+For example, @samp{*} has higher precedence (195) than @samp{+} (180),
+which means that @samp{(a * b) + c} will be formatted without the
+parentheses, but @samp{a * (b + c)} will keep the parentheses.
+
+The operator table used by normal and Big language modes has the
+following precedences:
+
+@example
+_ 1200 @r{(subscripts)}
+% 1100 @r{(as in n}%@r{)}
+- 1000 @r{(as in }-@r{n)}
+! 1000 @r{(as in }!@r{n)}
+mod 400
++/- 300
+!! 210 @r{(as in n}!!@r{)}
+! 210 @r{(as in n}!@r{)}
+^ 200
+* 195 @r{(or implicit multiplication)}
+/ % \ 190
++ - 180 @r{(as in a}+@r{b)}
+| 170
+< = 160 @r{(and other relations)}
+&& 110
+|| 100
+? : 90
+!!! 85
+&&& 80
+||| 75
+:= 50
+:: 45
+=> 40
+@end example
+
+The general rule is that if an operator with precedence @expr{n}
+occurs as an argument to an operator with precedence @expr{m}, then
+the argument is enclosed in parentheses if @expr{n < m}. Top-level
+expressions and expressions which are function arguments, vector
+components, etc., are formatted with precedence zero (so that they
+normally never get additional parentheses).
+
+For binary left-associative operators like @samp{+}, the righthand
+argument is actually formatted with one-higher precedence than shown
+in the table. This makes sure @samp{(a + b) + c} omits the parentheses,
+but the unnatural form @samp{a + (b + c)} keeps its parentheses.
+Right-associative operators like @samp{^} format the lefthand argument
+with one-higher precedence.
+
+@ignore
+@starindex
+@end ignore
+@tindex cprec
+The @code{cprec} function formats an expression with an arbitrary
+precedence. For example, @samp{cprec(abc, 185)} will combine into
+sums and products as follows: @samp{7 + abc}, @samp{7 (abc)} (because
+this @code{cprec} form has higher precedence than addition, but lower
+precedence than multiplication).
+
+@tex
+\bigskip
+@end tex
+
+A final composition issue is @dfn{line breaking}. Calc uses two
+different strategies for ``flat'' and ``non-flat'' compositions.
+A non-flat composition is anything that appears on multiple lines
+(not counting line breaking). Examples would be matrices and Big
+mode powers and quotients. Non-flat compositions are displayed
+exactly as specified. If they come out wider than the current
+window, you must use horizontal scrolling (@kbd{<} and @kbd{>}) to
+view them.
+
+Flat compositions, on the other hand, will be broken across several
+lines if they are too wide to fit the window. Certain points in a
+composition are noted internally as @dfn{break points}. Calc's
+general strategy is to fill each line as much as possible, then to
+move down to the next line starting at the first break point that
+didn't fit. However, the line breaker understands the hierarchical
+structure of formulas. It will not break an ``inner'' formula if
+it can use an earlier break point from an ``outer'' formula instead.
+For example, a vector of sums might be formatted as:
+
+@example
+@group
+[ a + b + c, d + e + f,
+ g + h + i, j + k + l, m ]
+@end group
+@end example
+
+@noindent
+If the @samp{m} can fit, then so, it seems, could the @samp{g}.
+But Calc prefers to break at the comma since the comma is part
+of a ``more outer'' formula. Calc would break at a plus sign
+only if it had to, say, if the very first sum in the vector had
+itself been too large to fit.
+
+Of the composition functions described below, only @code{choriz}
+generates break points. The @code{bstring} function (@pxref{Strings})
+also generates breakable items: A break point is added after every
+space (or group of spaces) except for spaces at the very beginning or
+end of the string.
+
+Composition functions themselves count as levels in the formula
+hierarchy, so a @code{choriz} that is a component of a larger
+@code{choriz} will be less likely to be broken. As a special case,
+if a @code{bstring} occurs as a component of a @code{choriz} or
+@code{choriz}-like object (such as a vector or a list of arguments
+in a function call), then the break points in that @code{bstring}
+will be on the same level as the break points of the surrounding
+object.
+
+@node Horizontal Compositions, Vertical Compositions, Composition Basics, Compositions
+@subsubsection Horizontal Compositions
+
+@noindent
+@ignore
+@starindex
+@end ignore
+@tindex choriz
+The @code{choriz} function takes a vector of objects and composes
+them horizontally. For example, @samp{choriz([17, a b/c, d])} formats
+as @w{@samp{17a b / cd}} in Normal language mode, or as
+
+@example
+@group
+ a b
+17---d
+ c
+@end group
+@end example
+
+@noindent
+in Big language mode. This is actually one case of the general
+function @samp{choriz(@var{vec}, @var{sep}, @var{prec})}, where
+either or both of @var{sep} and @var{prec} may be omitted.
+@var{Prec} gives the @dfn{precedence} to use when formatting
+each of the components of @var{vec}. The default precedence is
+the precedence from the surrounding environment.
+
+@var{Sep} is a string (i.e., a vector of character codes as might
+be entered with @code{" "} notation) which should separate components
+of the composition. Also, if @var{sep} is given, the line breaker
+will allow lines to be broken after each occurrence of @var{sep}.
+If @var{sep} is omitted, the composition will not be breakable
+(unless any of its component compositions are breakable).
+
+For example, @samp{2 choriz([a, b c, d = e], " + ", 180)} is
+formatted as @samp{2 a + b c + (d = e)}. To get the @code{choriz}
+to have precedence 180 ``outwards'' as well as ``inwards,''
+enclose it in a @code{cprec} form: @samp{2 cprec(choriz(...), 180)}
+formats as @samp{2 (a + b c + (d = e))}.
+
+The baseline of a horizontal composition is the same as the
+baselines of the component compositions, which are all aligned.
+
+@node Vertical Compositions, Other Compositions, Horizontal Compositions, Compositions
+@subsubsection Vertical Compositions
+
+@noindent
+@ignore
+@starindex
+@end ignore
+@tindex cvert
+The @code{cvert} function makes a vertical composition. Each
+component of the vector is centered in a column. The baseline of
+the result is by default the top line of the resulting composition.
+For example, @samp{f(cvert([a, bb, ccc]), cvert([a^2 + 1, b^2]))}
+formats in Big mode as
+
+@example
+@group
+f( a , 2 )
+ bb a + 1
+ ccc 2
+ b
+@end group
+@end example
+
+@ignore
+@starindex
+@end ignore
+@tindex cbase
+There are several special composition functions that work only as
+components of a vertical composition. The @code{cbase} function
+controls the baseline of the vertical composition; the baseline
+will be the same as the baseline of whatever component is enclosed
+in @code{cbase}. Thus @samp{f(cvert([a, cbase(bb), ccc]),
+cvert([a^2 + 1, cbase(b^2)]))} displays as
+
+@example
+@group
+ 2
+ a + 1
+ a 2
+f(bb , b )
+ ccc
+@end group
+@end example
+
+@ignore
+@starindex
+@end ignore
+@tindex ctbase
+@ignore
+@starindex
+@end ignore
+@tindex cbbase
+There are also @code{ctbase} and @code{cbbase} functions which
+make the baseline of the vertical composition equal to the top
+or bottom line (rather than the baseline) of that component.
+Thus @samp{cvert([cbase(a / b)]) + cvert([ctbase(a / b)]) +
+cvert([cbbase(a / b)])} gives
+
+@example
+@group
+ a
+a -
+- + a + b
+b -
+ b
+@end group
+@end example
+
+There should be only one @code{cbase}, @code{ctbase}, or @code{cbbase}
+function in a given vertical composition. These functions can also
+be written with no arguments: @samp{ctbase()} is a zero-height object
+which means the baseline is the top line of the following item, and
+@samp{cbbase()} means the baseline is the bottom line of the preceding
+item.
+
+@ignore
+@starindex
+@end ignore
+@tindex crule
+The @code{crule} function builds a ``rule,'' or horizontal line,
+across a vertical composition. By itself @samp{crule()} uses @samp{-}
+characters to build the rule. You can specify any other character,
+e.g., @samp{crule("=")}. The argument must be a character code or
+vector of exactly one character code. It is repeated to match the
+width of the widest item in the stack. For example, a quotient
+with a thick line is @samp{cvert([a + 1, cbase(crule("=")), b^2])}:
+
+@example
+@group
+a + 1
+=====
+ 2
+ b
+@end group
+@end example
+
+@ignore
+@starindex
+@end ignore
+@tindex clvert
+@ignore
+@starindex
+@end ignore
+@tindex crvert
+Finally, the functions @code{clvert} and @code{crvert} act exactly
+like @code{cvert} except that the items are left- or right-justified
+in the stack. Thus @samp{clvert([a, bb, ccc]) + crvert([a, bb, ccc])}
+gives:
+
+@example
+@group
+a + a
+bb bb
+ccc ccc
+@end group
+@end example
+
+Like @code{choriz}, the vertical compositions accept a second argument
+which gives the precedence to use when formatting the components.
+Vertical compositions do not support separator strings.
+
+@node Other Compositions, Information about Compositions, Vertical Compositions, Compositions
+@subsubsection Other Compositions
+
+@noindent
+@ignore
+@starindex
+@end ignore
+@tindex csup
+The @code{csup} function builds a superscripted expression. For
+example, @samp{csup(a, b)} looks the same as @samp{a^b} does in Big
+language mode. This is essentially a horizontal composition of
+@samp{a} and @samp{b}, where @samp{b} is shifted up so that its
+bottom line is one above the baseline.
+
+@ignore
+@starindex
+@end ignore
+@tindex csub
+Likewise, the @code{csub} function builds a subscripted expression.
+This shifts @samp{b} down so that its top line is one below the
+bottom line of @samp{a} (note that this is not quite analogous to
+@code{csup}). Other arrangements can be obtained by using
+@code{choriz} and @code{cvert} directly.
+
+@ignore
+@starindex
+@end ignore
+@tindex cflat
+The @code{cflat} function formats its argument in ``flat'' mode,
+as obtained by @samp{d O}, if the current language mode is normal
+or Big. It has no effect in other language modes. For example,
+@samp{a^(b/c)} is formatted by Big mode like @samp{csup(a, cflat(b/c))}
+to improve its readability.
+
+@ignore
+@starindex
+@end ignore
+@tindex cspace
+The @code{cspace} function creates horizontal space. For example,
+@samp{cspace(4)} is effectively the same as @samp{string(" ")}.
+A second string (i.e., vector of characters) argument is repeated
+instead of the space character. For example, @samp{cspace(4, "ab")}
+looks like @samp{abababab}. If the second argument is not a string,
+it is formatted in the normal way and then several copies of that
+are composed together: @samp{cspace(4, a^2)} yields
+
+@example
+@group
+ 2 2 2 2
+a a a a
+@end group
+@end example
+
+@noindent
+If the number argument is zero, this is a zero-width object.
+
+@ignore
+@starindex
+@end ignore
+@tindex cvspace
+The @code{cvspace} function creates vertical space, or a vertical
+stack of copies of a certain string or formatted object. The
+baseline is the center line of the resulting stack. A numerical
+argument of zero will produce an object which contributes zero
+height if used in a vertical composition.
+
+@ignore
+@starindex
+@end ignore
+@tindex ctspace
+@ignore
+@starindex
+@end ignore
+@tindex cbspace
+There are also @code{ctspace} and @code{cbspace} functions which
+create vertical space with the baseline the same as the baseline
+of the top or bottom copy, respectively, of the second argument.
+Thus @samp{cvspace(2, a/b) + ctspace(2, a/b) + cbspace(2, a/b)}
+displays as:
+
+@example
+@group
+ a
+ -
+a b
+- a a
+b + - + -
+a b b
+- a
+b -
+ b
+@end group
+@end example
+
+@node Information about Compositions, User-Defined Compositions, Other Compositions, Compositions
+@subsubsection Information about Compositions
+
+@noindent
+The functions in this section are actual functions; they compose their
+arguments according to the current language and other display modes,
+then return a certain measurement of the composition as an integer.
+
+@ignore
+@starindex
+@end ignore
+@tindex cwidth
+The @code{cwidth} function measures the width, in characters, of a
+composition. For example, @samp{cwidth(a + b)} is 5, and
+@samp{cwidth(a / b)} is 5 in Normal mode, 1 in Big mode, and 11 in
+@TeX{} mode (for @samp{@{a \over b@}}). The argument may involve
+the composition functions described in this section.
+
+@ignore
+@starindex
+@end ignore
+@tindex cheight
+The @code{cheight} function measures the height of a composition.
+This is the total number of lines in the argument's printed form.
+
+@ignore
+@starindex
+@end ignore
+@tindex cascent
+@ignore
+@starindex
+@end ignore
+@tindex cdescent
+The functions @code{cascent} and @code{cdescent} measure the amount
+of the height that is above (and including) the baseline, or below
+the baseline, respectively. Thus @samp{cascent(@var{x}) + cdescent(@var{x})}
+always equals @samp{cheight(@var{x})}. For a one-line formula like
+@samp{a + b}, @code{cascent} returns 1 and @code{cdescent} returns 0.
+For @samp{a / b} in Big mode, @code{cascent} returns 2 and @code{cdescent}
+returns 1. The only formula for which @code{cascent} will return zero
+is @samp{cvspace(0)} or equivalents.
+
+@node User-Defined Compositions, , Information about Compositions, Compositions
+@subsubsection User-Defined Compositions
+
+@noindent
+@kindex Z C
+@pindex calc-user-define-composition
+The @kbd{Z C} (@code{calc-user-define-composition}) command lets you
+define the display format for any algebraic function. You provide a
+formula containing a certain number of argument variables on the stack.
+Any time Calc formats a call to the specified function in the current
+language mode and with that number of arguments, Calc effectively
+replaces the function call with that formula with the arguments
+replaced.
+
+Calc builds the default argument list by sorting all the variable names
+that appear in the formula into alphabetical order. You can edit this
+argument list before pressing @key{RET} if you wish. Any variables in
+the formula that do not appear in the argument list will be displayed
+literally; any arguments that do not appear in the formula will not
+affect the display at all.
+
+You can define formats for built-in functions, for functions you have
+defined with @kbd{Z F} (@pxref{Algebraic Definitions}), or for functions
+which have no definitions but are being used as purely syntactic objects.
+You can define different formats for each language mode, and for each
+number of arguments, using a succession of @kbd{Z C} commands. When
+Calc formats a function call, it first searches for a format defined
+for the current language mode (and number of arguments); if there is
+none, it uses the format defined for the Normal language mode. If
+neither format exists, Calc uses its built-in standard format for that
+function (usually just @samp{@var{func}(@var{args})}).
+
+If you execute @kbd{Z C} with the number 0 on the stack instead of a
+formula, any defined formats for the function in the current language
+mode will be removed. The function will revert to its standard format.
+
+For example, the default format for the binomial coefficient function
+@samp{choose(n, m)} in the Big language mode is
+
+@example
+@group
+ n
+( )
+ m
+@end group
+@end example
+
+@noindent
+You might prefer the notation,
+
+@example
+@group
+ C
+n m
+@end group
+@end example
+
+@noindent
+To define this notation, first make sure you are in Big mode,
+then put the formula
+
+@smallexample
+choriz([cvert([cvspace(1), n]), C, cvert([cvspace(1), m])])
+@end smallexample
+
+@noindent
+on the stack and type @kbd{Z C}. Answer the first prompt with
+@code{choose}. The second prompt will be the default argument list
+of @samp{(C m n)}. Edit this list to be @samp{(n m)} and press
+@key{RET}. Now, try it out: For example, turn simplification
+off with @kbd{m O} and enter @samp{choose(a,b) + choose(7,3)}
+as an algebraic entry.
+
+@example
+@group
+ C + C
+a b 7 3
+@end group
+@end example
+
+As another example, let's define the usual notation for Stirling
+numbers of the first kind, @samp{stir1(n, m)}. This is just like
+the regular format for binomial coefficients but with square brackets
+instead of parentheses.
+
+@smallexample
+choriz([string("["), cvert([n, cbase(cvspace(1)), m]), string("]")])
+@end smallexample
+
+Now type @kbd{Z C stir1 @key{RET}}, edit the argument list to
+@samp{(n m)}, and type @key{RET}.
+
+The formula provided to @kbd{Z C} usually will involve composition
+functions, but it doesn't have to. Putting the formula @samp{a + b + c}
+onto the stack and typing @kbd{Z C foo @key{RET} @key{RET}} would define
+the function @samp{foo(x,y,z)} to display like @samp{x + y + z}.
+This ``sum'' will act exactly like a real sum for all formatting
+purposes (it will be parenthesized the same, and so on). However
+it will be computationally unrelated to a sum. For example, the
+formula @samp{2 * foo(1, 2, 3)} will display as @samp{2 (1 + 2 + 3)}.
+Operator precedences have caused the ``sum'' to be written in
+parentheses, but the arguments have not actually been summed.
+(Generally a display format like this would be undesirable, since
+it can easily be confused with a real sum.)
+
+The special function @code{eval} can be used inside a @kbd{Z C}
+composition formula to cause all or part of the formula to be
+evaluated at display time. For example, if the formula is
+@samp{a + eval(b + c)}, then @samp{foo(1, 2, 3)} will be displayed
+as @samp{1 + 5}. Evaluation will use the default simplifications,
+regardless of the current simplification mode. There are also
+@code{evalsimp} and @code{evalextsimp} which simplify as if by
+@kbd{a s} and @kbd{a e} (respectively). Note that these ``functions''
+operate only in the context of composition formulas (and also in
+rewrite rules, where they serve a similar purpose; @pxref{Rewrite
+Rules}). On the stack, a call to @code{eval} will be left in
+symbolic form.
+
+It is not a good idea to use @code{eval} except as a last resort.
+It can cause the display of formulas to be extremely slow. For
+example, while @samp{eval(a + b)} might seem quite fast and simple,
+there are several situations where it could be slow. For example,
+@samp{a} and/or @samp{b} could be polar complex numbers, in which
+case doing the sum requires trigonometry. Or, @samp{a} could be
+the factorial @samp{fact(100)} which is unevaluated because you
+have typed @kbd{m O}; @code{eval} will evaluate it anyway to
+produce a large, unwieldy integer.
+
+You can save your display formats permanently using the @kbd{Z P}
+command (@pxref{Creating User Keys}).
+
+@node Syntax Tables, , Compositions, Language Modes
+@subsection Syntax Tables
+
+@noindent
+@cindex Syntax tables
+@cindex Parsing formulas, customized
+Syntax tables do for input what compositions do for output: They
+allow you to teach custom notations to Calc's formula parser.
+Calc keeps a separate syntax table for each language mode.
+
+(Note that the Calc ``syntax tables'' discussed here are completely
+unrelated to the syntax tables described in the Emacs manual.)
+
+@kindex Z S
+@pindex calc-edit-user-syntax
+The @kbd{Z S} (@code{calc-edit-user-syntax}) command edits the
+syntax table for the current language mode. If you want your
+syntax to work in any language, define it in the Normal language
+mode. Type @kbd{C-c C-c} to finish editing the syntax table, or
+@kbd{C-x k} to cancel the edit. The @kbd{m m} command saves all
+the syntax tables along with the other mode settings;
+@pxref{General Mode Commands}.
+
+@menu
+* Syntax Table Basics::
+* Precedence in Syntax Tables::
+* Advanced Syntax Patterns::
+* Conditional Syntax Rules::
+@end menu
+
+@node Syntax Table Basics, Precedence in Syntax Tables, Syntax Tables, Syntax Tables
+@subsubsection Syntax Table Basics
+
+@noindent
+@dfn{Parsing} is the process of converting a raw string of characters,
+such as you would type in during algebraic entry, into a Calc formula.
+Calc's parser works in two stages. First, the input is broken down
+into @dfn{tokens}, such as words, numbers, and punctuation symbols
+like @samp{+}, @samp{:=}, and @samp{+/-}. Space between tokens is
+ignored (except when it serves to separate adjacent words). Next,
+the parser matches this string of tokens against various built-in
+syntactic patterns, such as ``an expression followed by @samp{+}
+followed by another expression'' or ``a name followed by @samp{(},
+zero or more expressions separated by commas, and @samp{)}.''
+
+A @dfn{syntax table} is a list of user-defined @dfn{syntax rules},
+which allow you to specify new patterns to define your own
+favorite input notations. Calc's parser always checks the syntax
+table for the current language mode, then the table for the Normal
+language mode, before it uses its built-in rules to parse an
+algebraic formula you have entered. Each syntax rule should go on
+its own line; it consists of a @dfn{pattern}, a @samp{:=} symbol,
+and a Calc formula with an optional @dfn{condition}. (Syntax rules
+resemble algebraic rewrite rules, but the notation for patterns is
+completely different.)
+
+A syntax pattern is a list of tokens, separated by spaces.
+Except for a few special symbols, tokens in syntax patterns are
+matched literally, from left to right. For example, the rule,
+
+@example
+foo ( ) := 2+3
+@end example
+
+@noindent
+would cause Calc to parse the formula @samp{4+foo()*5} as if it
+were @samp{4+(2+3)*5}. Notice that the parentheses were written
+as two separate tokens in the rule. As a result, the rule works
+for both @samp{foo()} and @w{@samp{foo ( )}}. If we had written
+the rule as @samp{foo () := 2+3}, then Calc would treat @samp{()}
+as a single, indivisible token, so that @w{@samp{foo( )}} would
+not be recognized by the rule. (It would be parsed as a regular
+zero-argument function call instead.) In fact, this rule would
+also make trouble for the rest of Calc's parser: An unrelated
+formula like @samp{bar()} would now be tokenized into @samp{bar ()}
+instead of @samp{bar ( )}, so that the standard parser for function
+calls would no longer recognize it!
+
+While it is possible to make a token with a mixture of letters
+and punctuation symbols, this is not recommended. It is better to
+break it into several tokens, as we did with @samp{foo()} above.
+
+The symbol @samp{#} in a syntax pattern matches any Calc expression.
+On the righthand side, the things that matched the @samp{#}s can
+be referred to as @samp{#1}, @samp{#2}, and so on (where @samp{#1}
+matches the leftmost @samp{#} in the pattern). For example, these
+rules match a user-defined function, prefix operator, infix operator,
+and postfix operator, respectively:
+
+@example
+foo ( # ) := myfunc(#1)
+foo # := myprefix(#1)
+# foo # := myinfix(#1,#2)
+# foo := mypostfix(#1)
+@end example
+
+Thus @samp{foo(3)} will parse as @samp{myfunc(3)}, and @samp{2+3 foo}
+will parse as @samp{mypostfix(2+3)}.
+
+It is important to write the first two rules in the order shown,
+because Calc tries rules in order from first to last. If the
+pattern @samp{foo #} came first, it would match anything that could
+match the @samp{foo ( # )} rule, since an expression in parentheses
+is itself a valid expression. Thus the @w{@samp{foo ( # )}} rule would
+never get to match anything. Likewise, the last two rules must be
+written in the order shown or else @samp{3 foo 4} will be parsed as
+@samp{mypostfix(3) * 4}. (Of course, the best way to avoid these
+ambiguities is not to use the same symbol in more than one way at
+the same time! In case you're not convinced, try the following
+exercise: How will the above rules parse the input @samp{foo(3,4)},
+if at all? Work it out for yourself, then try it in Calc and see.)
+
+Calc is quite flexible about what sorts of patterns are allowed.
+The only rule is that every pattern must begin with a literal
+token (like @samp{foo} in the first two patterns above), or with
+a @samp{#} followed by a literal token (as in the last two
+patterns). After that, any mixture is allowed, although putting
+two @samp{#}s in a row will not be very useful since two
+expressions with nothing between them will be parsed as one
+expression that uses implicit multiplication.
+
+As a more practical example, Maple uses the notation
+@samp{sum(a(i), i=1..10)} for sums, which Calc's Maple mode doesn't
+recognize at present. To handle this syntax, we simply add the
+rule,
+
+@example
+sum ( # , # = # .. # ) := sum(#1,#2,#3,#4)
+@end example
+
+@noindent
+to the Maple mode syntax table. As another example, C mode can't
+read assignment operators like @samp{++} and @samp{*=}. We can
+define these operators quite easily:
+
+@example
+# *= # := muleq(#1,#2)
+# ++ := postinc(#1)
+++ # := preinc(#1)
+@end example
+
+@noindent
+To complete the job, we would use corresponding composition functions
+and @kbd{Z C} to cause these functions to display in their respective
+Maple and C notations. (Note that the C example ignores issues of
+operator precedence, which are discussed in the next section.)
+
+You can enclose any token in quotes to prevent its usual
+interpretation in syntax patterns:
+
+@example
+# ":=" # := becomes(#1,#2)
+@end example
+
+Quotes also allow you to include spaces in a token, although once
+again it is generally better to use two tokens than one token with
+an embedded space. To include an actual quotation mark in a quoted
+token, precede it with a backslash. (This also works to include
+backslashes in tokens.)
+
+@example
+# "bad token" # "/\"\\" # := silly(#1,#2,#3)
+@end example
+
+@noindent
+This will parse @samp{3 bad token 4 /"\ 5} to @samp{silly(3,4,5)}.
+
+The token @kbd{#} has a predefined meaning in Calc's formula parser;
+it is not valid to use @samp{"#"} in a syntax rule. However, longer
+tokens that include the @samp{#} character are allowed. Also, while
+@samp{"$"} and @samp{"\""} are allowed as tokens, their presence in
+the syntax table will prevent those characters from working in their
+usual ways (referring to stack entries and quoting strings,
+respectively).
+
+Finally, the notation @samp{%%} anywhere in a syntax table causes
+the rest of the line to be ignored as a comment.
+
+@node Precedence in Syntax Tables, Advanced Syntax Patterns, Syntax Table Basics, Syntax Tables
+@subsubsection Precedence
+
+@noindent
+Different operators are generally assigned different @dfn{precedences}.
+By default, an operator defined by a rule like
+
+@example
+# foo # := foo(#1,#2)
+@end example
+
+@noindent
+will have an extremely low precedence, so that @samp{2*3+4 foo 5 == 6}
+will be parsed as @samp{(2*3+4) foo (5 == 6)}. To change the
+precedence of an operator, use the notation @samp{#/@var{p}} in
+place of @samp{#}, where @var{p} is an integer precedence level.
+For example, 185 lies between the precedences for @samp{+} and
+@samp{*}, so if we change this rule to
+
+@example
+#/185 foo #/186 := foo(#1,#2)
+@end example
+
+@noindent
+then @samp{2+3 foo 4*5} will be parsed as @samp{2+(3 foo (4*5))}.
+Also, because we've given the righthand expression slightly higher
+precedence, our new operator will be left-associative:
+@samp{1 foo 2 foo 3} will be parsed as @samp{(1 foo 2) foo 3}.
+By raising the precedence of the lefthand expression instead, we
+can create a right-associative operator.
+
+@xref{Composition Basics}, for a table of precedences of the
+standard Calc operators. For the precedences of operators in other
+language modes, look in the Calc source file @file{calc-lang.el}.
+
+@node Advanced Syntax Patterns, Conditional Syntax Rules, Precedence in Syntax Tables, Syntax Tables
+@subsubsection Advanced Syntax Patterns
+
+@noindent
+To match a function with a variable number of arguments, you could
+write
+
+@example
+foo ( # ) := myfunc(#1)
+foo ( # , # ) := myfunc(#1,#2)
+foo ( # , # , # ) := myfunc(#1,#2,#3)
+@end example
+
+@noindent
+but this isn't very elegant. To match variable numbers of items,
+Calc uses some notations inspired regular expressions and the
+``extended BNF'' style used by some language designers.
+
+@example
+foo ( @{ # @}*, ) := apply(myfunc,#1)
+@end example
+
+The token @samp{@{} introduces a repeated or optional portion.
+One of the three tokens @samp{@}*}, @samp{@}+}, or @samp{@}?}
+ends the portion. These will match zero or more, one or more,
+or zero or one copies of the enclosed pattern, respectively.
+In addition, @samp{@}*} and @samp{@}+} can be followed by a
+separator token (with no space in between, as shown above).
+Thus @samp{@{ # @}*,} matches nothing, or one expression, or
+several expressions separated by commas.
+
+A complete @samp{@{ ... @}} item matches as a vector of the
+items that matched inside it. For example, the above rule will
+match @samp{foo(1,2,3)} to get @samp{apply(myfunc,[1,2,3])}.
+The Calc @code{apply} function takes a function name and a vector
+of arguments and builds a call to the function with those
+arguments, so the net result is the formula @samp{myfunc(1,2,3)}.
+
+If the body of a @samp{@{ ... @}} contains several @samp{#}s
+(or nested @samp{@{ ... @}} constructs), then the items will be
+strung together into the resulting vector. If the body
+does not contain anything but literal tokens, the result will
+always be an empty vector.
+
+@example
+foo ( @{ # , # @}+, ) := bar(#1)
+foo ( @{ @{ # @}*, @}*; ) := matrix(#1)
+@end example
+
+@noindent
+will parse @samp{foo(1, 2, 3, 4)} as @samp{bar([1, 2, 3, 4])}, and
+@samp{foo(1, 2; 3, 4)} as @samp{matrix([[1, 2], [3, 4]])}. Also, after
+some thought it's easy to see how this pair of rules will parse
+@samp{foo(1, 2, 3)} as @samp{matrix([[1, 2, 3]])}, since the first
+rule will only match an even number of arguments. The rule
+
+@example
+foo ( # @{ , # , # @}? ) := bar(#1,#2)
+@end example
+
+@noindent
+will parse @samp{foo(2,3,4)} as @samp{bar(2,[3,4])}, and
+@samp{foo(2)} as @samp{bar(2,[])}.
+
+The notation @samp{@{ ... @}?.} (note the trailing period) works
+just the same as regular @samp{@{ ... @}?}, except that it does not
+count as an argument; the following two rules are equivalent:
+
+@example
+foo ( # , @{ also @}? # ) := bar(#1,#3)
+foo ( # , @{ also @}?. # ) := bar(#1,#2)
+@end example
+
+@noindent
+Note that in the first case the optional text counts as @samp{#2},
+which will always be an empty vector, but in the second case no
+empty vector is produced.
+
+Another variant is @samp{@{ ... @}?$}, which means the body is
+optional only at the end of the input formula. All built-in syntax
+rules in Calc use this for closing delimiters, so that during
+algebraic entry you can type @kbd{[sqrt(2), sqrt(3 @key{RET}}, omitting
+the closing parenthesis and bracket. Calc does this automatically
+for trailing @samp{)}, @samp{]}, and @samp{>} tokens in syntax
+rules, but you can use @samp{@{ ... @}?$} explicitly to get
+this effect with any token (such as @samp{"@}"} or @samp{end}).
+Like @samp{@{ ... @}?.}, this notation does not count as an
+argument. Conversely, you can use quotes, as in @samp{")"}, to
+prevent a closing-delimiter token from being automatically treated
+as optional.
+
+Calc's parser does not have full backtracking, which means some
+patterns will not work as you might expect:
+
+@example
+foo ( @{ # , @}? # , # ) := bar(#1,#2,#3)
+@end example
+
+@noindent
+Here we are trying to make the first argument optional, so that
+@samp{foo(2,3)} parses as @samp{bar([],2,3)}. Unfortunately, Calc
+first tries to match @samp{2,} against the optional part of the
+pattern, finds a match, and so goes ahead to match the rest of the
+pattern. Later on it will fail to match the second comma, but it
+doesn't know how to go back and try the other alternative at that
+point. One way to get around this would be to use two rules:
+
+@example
+foo ( # , # , # ) := bar([#1],#2,#3)
+foo ( # , # ) := bar([],#1,#2)
+@end example
+
+More precisely, when Calc wants to match an optional or repeated
+part of a pattern, it scans forward attempting to match that part.
+If it reaches the end of the optional part without failing, it
+``finalizes'' its choice and proceeds. If it fails, though, it
+backs up and tries the other alternative. Thus Calc has ``partial''
+backtracking. A fully backtracking parser would go on to make sure
+the rest of the pattern matched before finalizing the choice.
+
+@node Conditional Syntax Rules, , Advanced Syntax Patterns, Syntax Tables
+@subsubsection Conditional Syntax Rules
+
+@noindent
+It is possible to attach a @dfn{condition} to a syntax rule. For
+example, the rules
+
+@example
+foo ( # ) := ifoo(#1) :: integer(#1)
+foo ( # ) := gfoo(#1)
+@end example
+
+@noindent
+will parse @samp{foo(3)} as @samp{ifoo(3)}, but will parse
+@samp{foo(3.5)} and @samp{foo(x)} as calls to @code{gfoo}. Any
+number of conditions may be attached; all must be true for the
+rule to succeed. A condition is ``true'' if it evaluates to a
+nonzero number. @xref{Logical Operations}, for a list of Calc
+functions like @code{integer} that perform logical tests.
+
+The exact sequence of events is as follows: When Calc tries a
+rule, it first matches the pattern as usual. It then substitutes
+@samp{#1}, @samp{#2}, etc., in the conditions, if any. Next, the
+conditions are simplified and evaluated in order from left to right,
+as if by the @w{@kbd{a s}} algebra command (@pxref{Simplifying Formulas}).
+Each result is true if it is a nonzero number, or an expression
+that can be proven to be nonzero (@pxref{Declarations}). If the
+results of all conditions are true, the expression (such as
+@samp{ifoo(#1)}) has its @samp{#}s substituted, and that is the
+result of the parse. If the result of any condition is false, Calc
+goes on to try the next rule in the syntax table.
+
+Syntax rules also support @code{let} conditions, which operate in
+exactly the same way as they do in algebraic rewrite rules.
+@xref{Other Features of Rewrite Rules}, for details. A @code{let}
+condition is always true, but as a side effect it defines a
+variable which can be used in later conditions, and also in the
+expression after the @samp{:=} sign:
+
+@example
+foo ( # ) := hifoo(x) :: let(x := #1 + 0.5) :: dnumint(x)
+@end example
+
+@noindent
+The @code{dnumint} function tests if a value is numerically an
+integer, i.e., either a true integer or an integer-valued float.
+This rule will parse @code{foo} with a half-integer argument,
+like @samp{foo(3.5)}, to a call like @samp{hifoo(4.)}.
+
+The lefthand side of a syntax rule @code{let} must be a simple
+variable, not the arbitrary pattern that is allowed in rewrite
+rules.
+
+The @code{matches} function is also treated specially in syntax
+rule conditions (again, in the same way as in rewrite rules).
+@xref{Matching Commands}. If the matching pattern contains
+meta-variables, then those meta-variables may be used in later
+conditions and in the result expression. The arguments to
+@code{matches} are not evaluated in this situation.
+
+@example
+sum ( # , # ) := sum(#1,a,b,c) :: matches(#2, a=[b..c])
+@end example
+
+@noindent
+This is another way to implement the Maple mode @code{sum} notation.
+In this approach, we allow @samp{#2} to equal the whole expression
+@samp{i=1..10}. Then, we use @code{matches} to break it apart into
+its components. If the expression turns out not to match the pattern,
+the syntax rule will fail. Note that @kbd{Z S} always uses Calc's
+Normal language mode for editing expressions in syntax rules, so we
+must use regular Calc notation for the interval @samp{[b..c]} that
+will correspond to the Maple mode interval @samp{1..10}.
+
+@node Modes Variable, Calc Mode Line, Language Modes, Mode Settings
+@section The @code{Modes} Variable
+
+@noindent
+@kindex m g
+@pindex calc-get-modes
+The @kbd{m g} (@code{calc-get-modes}) command pushes onto the stack
+a vector of numbers that describes the various mode settings that
+are in effect. With a numeric prefix argument, it pushes only the
+@var{n}th mode, i.e., the @var{n}th element of this vector. Keyboard
+macros can use the @kbd{m g} command to modify their behavior based
+on the current mode settings.
+
+@cindex @code{Modes} variable
+@vindex Modes
+The modes vector is also available in the special variable
+@code{Modes}. In other words, @kbd{m g} is like @kbd{s r Modes @key{RET}}.
+It will not work to store into this variable; in fact, if you do,
+@code{Modes} will cease to track the current modes. (The @kbd{m g}
+command will continue to work, however.)
+
+In general, each number in this vector is suitable as a numeric
+prefix argument to the associated mode-setting command. (Recall
+that the @kbd{~} key takes a number from the stack and gives it as
+a numeric prefix to the next command.)
+
+The elements of the modes vector are as follows:
+
+@enumerate
+@item
+Current precision. Default is 12; associated command is @kbd{p}.
+
+@item
+Binary word size. Default is 32; associated command is @kbd{b w}.
+
+@item
+Stack size (not counting the value about to be pushed by @kbd{m g}).
+This is zero if @kbd{m g} is executed with an empty stack.
+
+@item
+Number radix. Default is 10; command is @kbd{d r}.
+
+@item
+Floating-point format. This is the number of digits, plus the
+constant 0 for normal notation, 10000 for scientific notation,
+20000 for engineering notation, or 30000 for fixed-point notation.
+These codes are acceptable as prefix arguments to the @kbd{d n}
+command, but note that this may lose information: For example,
+@kbd{d s} and @kbd{C-u 12 d s} have similar (but not quite
+identical) effects if the current precision is 12, but they both
+produce a code of 10012, which will be treated by @kbd{d n} as
+@kbd{C-u 12 d s}. If the precision then changes, the float format
+will still be frozen at 12 significant figures.
+
+@item
+Angular mode. Default is 1 (degrees). Other values are 2 (radians)
+and 3 (HMS). The @kbd{m d} command accepts these prefixes.
+
+@item
+Symbolic mode. Value is 0 or 1; default is 0. Command is @kbd{m s}.
+
+@item
+Fraction mode. Value is 0 or 1; default is 0. Command is @kbd{m f}.
+
+@item
+Polar mode. Value is 0 (rectangular) or 1 (polar); default is 0.
+Command is @kbd{m p}.
+
+@item
+Matrix/Scalar mode. Default value is @mathit{-1}. Value is 0 for Scalar
+mode, @mathit{-2} for Matrix mode, @mathit{-3} for square Matrix mode,
+or @var{N} for
+@texline @math{N\times N}
+@infoline @var{N}x@var{N}
+Matrix mode. Command is @kbd{m v}.
+
+@item
+Simplification mode. Default is 1. Value is @mathit{-1} for off (@kbd{m O}),
+0 for @kbd{m N}, 2 for @kbd{m B}, 3 for @kbd{m A}, 4 for @kbd{m E},
+or 5 for @w{@kbd{m U}}. The @kbd{m D} command accepts these prefixes.
+
+@item
+Infinite mode. Default is @mathit{-1} (off). Value is 1 if the mode is on,
+or 0 if the mode is on with positive zeros. Command is @kbd{m i}.
+@end enumerate
+
+For example, the sequence @kbd{M-1 m g @key{RET} 2 + ~ p} increases the
+precision by two, leaving a copy of the old precision on the stack.
+Later, @kbd{~ p} will restore the original precision using that
+stack value. (This sequence might be especially useful inside a
+keyboard macro.)
+
+As another example, @kbd{M-3 m g 1 - ~ @key{DEL}} deletes all but the
+oldest (bottommost) stack entry.
+
+Yet another example: The HP-48 ``round'' command rounds a number
+to the current displayed precision. You could roughly emulate this
+in Calc with the sequence @kbd{M-5 m g 10000 % ~ c c}. (This
+would not work for fixed-point mode, but it wouldn't be hard to
+do a full emulation with the help of the @kbd{Z [} and @kbd{Z ]}
+programming commands. @xref{Conditionals in Macros}.)
+
+@node Calc Mode Line, , Modes Variable, Mode Settings
+@section The Calc Mode Line
+
+@noindent
+@cindex Mode line indicators
+This section is a summary of all symbols that can appear on the
+Calc mode line, the highlighted bar that appears under the Calc
+stack window (or under an editing window in Embedded mode).
+
+The basic mode line format is:
+
+@example
+--%%-Calc: 12 Deg @var{other modes} (Calculator)
+@end example
+
+The @samp{%%} is the Emacs symbol for ``read-only''; it shows that
+regular Emacs commands are not allowed to edit the stack buffer
+as if it were text.
+
+The word @samp{Calc:} changes to @samp{CalcEmbed:} if Embedded mode
+is enabled. The words after this describe the various Calc modes
+that are in effect.
+
+The first mode is always the current precision, an integer.
+The second mode is always the angular mode, either @code{Deg},
+@code{Rad}, or @code{Hms}.
+
+Here is a complete list of the remaining symbols that can appear
+on the mode line:
+
+@table @code
+@item Alg
+Algebraic mode (@kbd{m a}; @pxref{Algebraic Entry}).
+
+@item Alg[(
+Incomplete algebraic mode (@kbd{C-u m a}).
+
+@item Alg*
+Total algebraic mode (@kbd{m t}).
+
+@item Symb
+Symbolic mode (@kbd{m s}; @pxref{Symbolic Mode}).
+
+@item Matrix
+Matrix mode (@kbd{m v}; @pxref{Matrix Mode}).
+
+@item Matrix@var{n}
+Dimensioned Matrix mode (@kbd{C-u @var{n} m v}; @pxref{Matrix Mode}).
+
+@item SqMatrix
+Square Matrix mode (@kbd{C-u m v}; @pxref{Matrix Mode}).
+
+@item Scalar
+Scalar mode (@kbd{m v}; @pxref{Matrix Mode}).
+
+@item Polar
+Polar complex mode (@kbd{m p}; @pxref{Polar Mode}).
+
+@item Frac
+Fraction mode (@kbd{m f}; @pxref{Fraction Mode}).
+
+@item Inf
+Infinite mode (@kbd{m i}; @pxref{Infinite Mode}).
+
+@item +Inf
+Positive Infinite mode (@kbd{C-u 0 m i}).
+
+@item NoSimp
+Default simplifications off (@kbd{m O}; @pxref{Simplification Modes}).
+
+@item NumSimp
+Default simplifications for numeric arguments only (@kbd{m N}).
+
+@item BinSimp@var{w}
+Binary-integer simplification mode; word size @var{w} (@kbd{m B}, @kbd{b w}).
+
+@item AlgSimp
+Algebraic simplification mode (@kbd{m A}).
+
+@item ExtSimp
+Extended algebraic simplification mode (@kbd{m E}).
+
+@item UnitSimp
+Units simplification mode (@kbd{m U}).
+
+@item Bin
+Current radix is 2 (@kbd{d 2}; @pxref{Radix Modes}).
+
+@item Oct
+Current radix is 8 (@kbd{d 8}).
+
+@item Hex
+Current radix is 16 (@kbd{d 6}).
+
+@item Radix@var{n}
+Current radix is @var{n} (@kbd{d r}).
+
+@item Zero
+Leading zeros (@kbd{d z}; @pxref{Radix Modes}).
+
+@item Big
+Big language mode (@kbd{d B}; @pxref{Normal Language Modes}).
+
+@item Flat
+One-line normal language mode (@kbd{d O}).
+
+@item Unform
+Unformatted language mode (@kbd{d U}).
+
+@item C
+C language mode (@kbd{d C}; @pxref{C FORTRAN Pascal}).
+
+@item Pascal
+Pascal language mode (@kbd{d P}).
+
+@item Fortran
+FORTRAN language mode (@kbd{d F}).
+
+@item TeX
+@TeX{} language mode (@kbd{d T}; @pxref{TeX and LaTeX Language Modes}).
+
+@item LaTeX
+La@TeX{} language mode (@kbd{d L}; @pxref{TeX and LaTeX Language Modes}).
+
+@item Eqn
+@dfn{Eqn} language mode (@kbd{d E}; @pxref{Eqn Language Mode}).
+
+@item Math
+Mathematica language mode (@kbd{d M}; @pxref{Mathematica Language Mode}).
+
+@item Maple
+Maple language mode (@kbd{d W}; @pxref{Maple Language Mode}).
+
+@item Norm@var{n}
+Normal float mode with @var{n} digits (@kbd{d n}; @pxref{Float Formats}).
+
+@item Fix@var{n}
+Fixed point mode with @var{n} digits after the point (@kbd{d f}).
+
+@item Sci
+Scientific notation mode (@kbd{d s}).
+
+@item Sci@var{n}
+Scientific notation with @var{n} digits (@kbd{d s}).
+
+@item Eng
+Engineering notation mode (@kbd{d e}).
+
+@item Eng@var{n}
+Engineering notation with @var{n} digits (@kbd{d e}).
+
+@item Left@var{n}
+Left-justified display indented by @var{n} (@kbd{d <}; @pxref{Justification}).
+
+@item Right
+Right-justified display (@kbd{d >}).
+
+@item Right@var{n}
+Right-justified display with width @var{n} (@kbd{d >}).
+
+@item Center
+Centered display (@kbd{d =}).
+
+@item Center@var{n}
+Centered display with center column @var{n} (@kbd{d =}).
+
+@item Wid@var{n}
+Line breaking with width @var{n} (@kbd{d b}; @pxref{Normal Language Modes}).
+
+@item Wide
+No line breaking (@kbd{d b}).
+
+@item Break
+Selections show deep structure (@kbd{j b}; @pxref{Making Selections}).
+
+@item Save
+Record modes in @file{~/.calc.el} (@kbd{m R}; @pxref{General Mode Commands}).
+
+@item Local
+Record modes in Embedded buffer (@kbd{m R}).
+
+@item LocEdit
+Record modes as editing-only in Embedded buffer (@kbd{m R}).
+
+@item LocPerm
+Record modes as permanent-only in Embedded buffer (@kbd{m R}).
+
+@item Global
+Record modes as global in Embedded buffer (@kbd{m R}).
+
+@item Manual
+Automatic recomputation turned off (@kbd{m C}; @pxref{Automatic
+Recomputation}).
+
+@item Graph
+GNUPLOT process is alive in background (@pxref{Graphics}).
+
+@item Sel
+Top-of-stack has a selection (Embedded only; @pxref{Making Selections}).
+
+@item Dirty
+The stack display may not be up-to-date (@pxref{Display Modes}).
+
+@item Inv
+``Inverse'' prefix was pressed (@kbd{I}; @pxref{Inverse and Hyperbolic}).
+
+@item Hyp
+``Hyperbolic'' prefix was pressed (@kbd{H}).
+
+@item Keep
+``Keep-arguments'' prefix was pressed (@kbd{K}).
+
+@item Narrow
+Stack is truncated (@kbd{d t}; @pxref{Truncating the Stack}).
+@end table
+
+In addition, the symbols @code{Active} and @code{~Active} can appear
+as minor modes on an Embedded buffer's mode line. @xref{Embedded Mode}.
+
+@node Arithmetic, Scientific Functions, Mode Settings, Top
+@chapter Arithmetic Functions
+
+@noindent
+This chapter describes the Calc commands for doing simple calculations
+on numbers, such as addition, absolute value, and square roots. These
+commands work by removing the top one or two values from the stack,
+performing the desired operation, and pushing the result back onto the
+stack. If the operation cannot be performed, the result pushed is a
+formula instead of a number, such as @samp{2/0} (because division by zero
+is invalid) or @samp{sqrt(x)} (because the argument @samp{x} is a formula).
+
+Most of the commands described here can be invoked by a single keystroke.
+Some of the more obscure ones are two-letter sequences beginning with
+the @kbd{f} (``functions'') prefix key.
+
+@xref{Prefix Arguments}, for a discussion of the effect of numeric
+prefix arguments on commands in this chapter which do not otherwise
+interpret a prefix argument.
+
+@menu
+* Basic Arithmetic::
+* Integer Truncation::
+* Complex Number Functions::
+* Conversions::
+* Date Arithmetic::
+* Financial Functions::
+* Binary Functions::
+@end menu
+
+@node Basic Arithmetic, Integer Truncation, Arithmetic, Arithmetic
+@section Basic Arithmetic
+
+@noindent
+@kindex +
+@pindex calc-plus
+@ignore
+@mindex @null
+@end ignore
+@tindex +
+The @kbd{+} (@code{calc-plus}) command adds two numbers. The numbers may
+be any of the standard Calc data types. The resulting sum is pushed back
+onto the stack.
+
+If both arguments of @kbd{+} are vectors or matrices (of matching dimensions),
+the result is a vector or matrix sum. If one argument is a vector and the
+other a scalar (i.e., a non-vector), the scalar is added to each of the
+elements of the vector to form a new vector. If the scalar is not a
+number, the operation is left in symbolic form: Suppose you added @samp{x}
+to the vector @samp{[1,2]}. You may want the result @samp{[1+x,2+x]}, or
+you may plan to substitute a 2-vector for @samp{x} in the future. Since
+the Calculator can't tell which interpretation you want, it makes the
+safest assumption. @xref{Reducing and Mapping}, for a way to add @samp{x}
+to every element of a vector.
+
+If either argument of @kbd{+} is a complex number, the result will in general
+be complex. If one argument is in rectangular form and the other polar,
+the current Polar mode determines the form of the result. If Symbolic
+mode is enabled, the sum may be left as a formula if the necessary
+conversions for polar addition are non-trivial.
+
+If both arguments of @kbd{+} are HMS forms, the forms are added according to
+the usual conventions of hours-minutes-seconds notation. If one argument
+is an HMS form and the other is a number, that number is converted from
+degrees or radians (depending on the current Angular mode) to HMS format
+and then the two HMS forms are added.
+
+If one argument of @kbd{+} is a date form, the other can be either a
+real number, which advances the date by a certain number of days, or
+an HMS form, which advances the date by a certain amount of time.
+Subtracting two date forms yields the number of days between them.
+Adding two date forms is meaningless, but Calc interprets it as the
+subtraction of one date form and the negative of the other. (The
+negative of a date form can be understood by remembering that dates
+are stored as the number of days before or after Jan 1, 1 AD.)
+
+If both arguments of @kbd{+} are error forms, the result is an error form
+with an appropriately computed standard deviation. If one argument is an
+error form and the other is a number, the number is taken to have zero error.
+Error forms may have symbolic formulas as their mean and/or error parts;
+adding these will produce a symbolic error form result. However, adding an
+error form to a plain symbolic formula (as in @samp{(a +/- b) + c}) will not
+work, for the same reasons just mentioned for vectors. Instead you must
+write @samp{(a +/- b) + (c +/- 0)}.
+
+If both arguments of @kbd{+} are modulo forms with equal values of @expr{M},
+or if one argument is a modulo form and the other a plain number, the
+result is a modulo form which represents the sum, modulo @expr{M}, of
+the two values.
+
+If both arguments of @kbd{+} are intervals, the result is an interval
+which describes all possible sums of the possible input values. If
+one argument is a plain number, it is treated as the interval
+@w{@samp{[x ..@: x]}}.
+
+If one argument of @kbd{+} is an infinity and the other is not, the
+result is that same infinity. If both arguments are infinite and in
+the same direction, the result is the same infinity, but if they are
+infinite in different directions the result is @code{nan}.
+
+@kindex -
+@pindex calc-minus
+@ignore
+@mindex @null
+@end ignore
+@tindex -
+The @kbd{-} (@code{calc-minus}) command subtracts two values. The top
+number on the stack is subtracted from the one behind it, so that the
+computation @kbd{5 @key{RET} 2 -} produces 3, not @mathit{-3}. All options
+available for @kbd{+} are available for @kbd{-} as well.
+
+@kindex *
+@pindex calc-times
+@ignore
+@mindex @null
+@end ignore
+@tindex *
+The @kbd{*} (@code{calc-times}) command multiplies two numbers. If one
+argument is a vector and the other a scalar, the scalar is multiplied by
+the elements of the vector to produce a new vector. If both arguments
+are vectors, the interpretation depends on the dimensions of the
+vectors: If both arguments are matrices, a matrix multiplication is
+done. If one argument is a matrix and the other a plain vector, the
+vector is interpreted as a row vector or column vector, whichever is
+dimensionally correct. If both arguments are plain vectors, the result
+is a single scalar number which is the dot product of the two vectors.
+
+If one argument of @kbd{*} is an HMS form and the other a number, the
+HMS form is multiplied by that amount. It is an error to multiply two
+HMS forms together, or to attempt any multiplication involving date
+forms. Error forms, modulo forms, and intervals can be multiplied;
+see the comments for addition of those forms. When two error forms
+or intervals are multiplied they are considered to be statistically
+independent; thus, @samp{[-2 ..@: 3] * [-2 ..@: 3]} is @samp{[-6 ..@: 9]},
+whereas @w{@samp{[-2 ..@: 3] ^ 2}} is @samp{[0 ..@: 9]}.
+
+@kindex /
+@pindex calc-divide
+@ignore
+@mindex @null
+@end ignore
+@tindex /
+The @kbd{/} (@code{calc-divide}) command divides two numbers.
+
+When combining multiplication and division in an algebraic formula, it
+is good style to use parentheses to distinguish between possible
+interpretations; the expression @samp{a/b*c} should be written
+@samp{(a/b)*c} or @samp{a/(b*c)}, as appropriate. Without the
+parentheses, Calc will interpret @samp{a/b*c} as @samp{a/(b*c)}, since
+in algebraic entry Calc gives division a lower precedence than
+multiplication. (This is not standard across all computer languages, and
+Calc may change the precedence depending on the language mode being used.
+@xref{Language Modes}.) This default ordering can be changed by setting
+the customizable variable @code{calc-multiplication-has-precedence} to
+@code{nil} (@pxref{Customizing Calc}); this will give multiplication and
+division equal precedences. Note that Calc's default choice of
+precedence allows @samp{a b / c d} to be used as a shortcut for
+@smallexample
+@group
+a b
+---.
+c d
+@end group
+@end smallexample
+
+When dividing a scalar @expr{B} by a square matrix @expr{A}, the
+computation performed is @expr{B} times the inverse of @expr{A}. This
+also occurs if @expr{B} is itself a vector or matrix, in which case the
+effect is to solve the set of linear equations represented by @expr{B}.
+If @expr{B} is a matrix with the same number of rows as @expr{A}, or a
+plain vector (which is interpreted here as a column vector), then the
+equation @expr{A X = B} is solved for the vector or matrix @expr{X}.
+Otherwise, if @expr{B} is a non-square matrix with the same number of
+@emph{columns} as @expr{A}, the equation @expr{X A = B} is solved. If
+you wish a vector @expr{B} to be interpreted as a row vector to be
+solved as @expr{X A = B}, make it into a one-row matrix with @kbd{C-u 1
+v p} first. To force a left-handed solution with a square matrix
+@expr{B}, transpose @expr{A} and @expr{B} before dividing, then
+transpose the result.
+
+HMS forms can be divided by real numbers or by other HMS forms. Error
+forms can be divided in any combination of ways. Modulo forms where both
+values and the modulo are integers can be divided to get an integer modulo
+form result. Intervals can be divided; dividing by an interval that
+encompasses zero or has zero as a limit will result in an infinite
+interval.
+
+@kindex ^
+@pindex calc-power
+@ignore
+@mindex @null
+@end ignore
+@tindex ^
+The @kbd{^} (@code{calc-power}) command raises a number to a power. If
+the power is an integer, an exact result is computed using repeated
+multiplications. For non-integer powers, Calc uses Newton's method or
+logarithms and exponentials. Square matrices can be raised to integer
+powers. If either argument is an error (or interval or modulo) form,
+the result is also an error (or interval or modulo) form.
+
+@kindex I ^
+@tindex nroot
+If you press the @kbd{I} (inverse) key first, the @kbd{I ^} command
+computes an Nth root: @kbd{125 @key{RET} 3 I ^} computes the number 5.
+(This is entirely equivalent to @kbd{125 @key{RET} 1:3 ^}.)
+
+@kindex \
+@pindex calc-idiv
+@tindex idiv
+@ignore
+@mindex @null
+@end ignore
+@tindex \
+The @kbd{\} (@code{calc-idiv}) command divides two numbers on the stack
+to produce an integer result. It is equivalent to dividing with
+@key{/}, then rounding down with @kbd{F} (@code{calc-floor}), only a bit
+more convenient and efficient. Also, since it is an all-integer
+operation when the arguments are integers, it avoids problems that
+@kbd{/ F} would have with floating-point roundoff.
+
+@kindex %
+@pindex calc-mod
+@ignore
+@mindex @null
+@end ignore
+@tindex %
+The @kbd{%} (@code{calc-mod}) command performs a ``modulo'' (or ``remainder'')
+operation. Mathematically, @samp{a%b = a - (a\b)*b}, and is defined
+for all real numbers @expr{a} and @expr{b} (except @expr{b=0}). For
+positive @expr{b}, the result will always be between 0 (inclusive) and
+@expr{b} (exclusive). Modulo does not work for HMS forms and error forms.
+If @expr{a} is a modulo form, its modulo is changed to @expr{b}, which
+must be positive real number.
+
+@kindex :
+@pindex calc-fdiv
+@tindex fdiv
+The @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command
+divides the two integers on the top of the stack to produce a fractional
+result. This is a convenient shorthand for enabling Fraction mode (with
+@kbd{m f}) temporarily and using @samp{/}. Note that during numeric entry
+the @kbd{:} key is interpreted as a fraction separator, so to divide 8 by 6
+you would have to type @kbd{8 @key{RET} 6 @key{RET} :}. (Of course, in
+this case, it would be much easier simply to enter the fraction directly
+as @kbd{8:6 @key{RET}}!)
+
+@kindex n
+@pindex calc-change-sign
+The @kbd{n} (@code{calc-change-sign}) command negates the number on the top
+of the stack. It works on numbers, vectors and matrices, HMS forms, date
+forms, error forms, intervals, and modulo forms.
+
+@kindex A
+@pindex calc-abs
+@tindex abs
+The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the absolute
+value of a number. The result of @code{abs} is always a nonnegative
+real number: With a complex argument, it computes the complex magnitude.
+With a vector or matrix argument, it computes the Frobenius norm, i.e.,
+the square root of the sum of the squares of the absolute values of the
+elements. The absolute value of an error form is defined by replacing
+the mean part with its absolute value and leaving the error part the same.
+The absolute value of a modulo form is undefined. The absolute value of
+an interval is defined in the obvious way.
+
+@kindex f A
+@pindex calc-abssqr
+@tindex abssqr
+The @kbd{f A} (@code{calc-abssqr}) [@code{abssqr}] command computes the
+absolute value squared of a number, vector or matrix, or error form.
+
+@kindex f s
+@pindex calc-sign
+@tindex sign
+The @kbd{f s} (@code{calc-sign}) [@code{sign}] command returns 1 if its
+argument is positive, @mathit{-1} if its argument is negative, or 0 if its
+argument is zero. In algebraic form, you can also write @samp{sign(a,x)}
+which evaluates to @samp{x * sign(a)}, i.e., either @samp{x}, @samp{-x}, or
+zero depending on the sign of @samp{a}.
+
+@kindex &
+@pindex calc-inv
+@tindex inv
+@cindex Reciprocal
+The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the
+reciprocal of a number, i.e., @expr{1 / x}. Operating on a square
+matrix, it computes the inverse of that matrix.
+
+@kindex Q
+@pindex calc-sqrt
+@tindex sqrt
+The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] command computes the square
+root of a number. For a negative real argument, the result will be a
+complex number whose form is determined by the current Polar mode.
+
+@kindex f h
+@pindex calc-hypot
+@tindex hypot
+The @kbd{f h} (@code{calc-hypot}) [@code{hypot}] command computes the square
+root of the sum of the squares of two numbers. That is, @samp{hypot(a,b)}
+is the length of the hypotenuse of a right triangle with sides @expr{a}
+and @expr{b}. If the arguments are complex numbers, their squared
+magnitudes are used.
+
+@kindex f Q
+@pindex calc-isqrt
+@tindex isqrt
+The @kbd{f Q} (@code{calc-isqrt}) [@code{isqrt}] command computes the
+integer square root of an integer. This is the true square root of the
+number, rounded down to an integer. For example, @samp{isqrt(10)}
+produces 3. Note that, like @kbd{\} [@code{idiv}], this uses exact
+integer arithmetic throughout to avoid roundoff problems. If the input
+is a floating-point number or other non-integer value, this is exactly
+the same as @samp{floor(sqrt(x))}.
+
+@kindex f n
+@kindex f x
+@pindex calc-min
+@tindex min
+@pindex calc-max
+@tindex max
+The @kbd{f n} (@code{calc-min}) [@code{min}] and @kbd{f x} (@code{calc-max})
+[@code{max}] commands take the minimum or maximum of two real numbers,
+respectively. These commands also work on HMS forms, date forms,
+intervals, and infinities. (In algebraic expressions, these functions
+take any number of arguments and return the maximum or minimum among
+all the arguments.)
+
+@kindex f M
+@kindex f X
+@pindex calc-mant-part
+@tindex mant
+@pindex calc-xpon-part
+@tindex xpon
+The @kbd{f M} (@code{calc-mant-part}) [@code{mant}] function extracts
+the ``mantissa'' part @expr{m} of its floating-point argument; @kbd{f X}
+(@code{calc-xpon-part}) [@code{xpon}] extracts the ``exponent'' part
+@expr{e}. The original number is equal to
+@texline @math{m \times 10^e},
+@infoline @expr{m * 10^e},
+where @expr{m} is in the interval @samp{[1.0 ..@: 10.0)} except that
+@expr{m=e=0} if the original number is zero. For integers
+and fractions, @code{mant} returns the number unchanged and @code{xpon}
+returns zero. The @kbd{v u} (@code{calc-unpack}) command can also be
+used to ``unpack'' a floating-point number; this produces an integer
+mantissa and exponent, with the constraint that the mantissa is not
+a multiple of ten (again except for the @expr{m=e=0} case).
+
+@kindex f S
+@pindex calc-scale-float
+@tindex scf
+The @kbd{f S} (@code{calc-scale-float}) [@code{scf}] function scales a number
+by a given power of ten. Thus, @samp{scf(mant(x), xpon(x)) = x} for any
+real @samp{x}. The second argument must be an integer, but the first
+may actually be any numeric value. For example, @samp{scf(5,-2) = 0.05}
+or @samp{1:20} depending on the current Fraction mode.
+
+@kindex f [
+@kindex f ]
+@pindex calc-decrement
+@pindex calc-increment
+@tindex decr
+@tindex incr
+The @kbd{f [} (@code{calc-decrement}) [@code{decr}] and @kbd{f ]}
+(@code{calc-increment}) [@code{incr}] functions decrease or increase
+a number by one unit. For integers, the effect is obvious. For
+floating-point numbers, the change is by one unit in the last place.
+For example, incrementing @samp{12.3456} when the current precision
+is 6 digits yields @samp{12.3457}. If the current precision had been
+8 digits, the result would have been @samp{12.345601}. Incrementing
+@samp{0.0} produces
+@texline @math{10^{-p}},
+@infoline @expr{10^-p},
+where @expr{p} is the current
+precision. These operations are defined only on integers and floats.
+With numeric prefix arguments, they change the number by @expr{n} units.
+
+Note that incrementing followed by decrementing, or vice-versa, will
+almost but not quite always cancel out. Suppose the precision is
+6 digits and the number @samp{9.99999} is on the stack. Incrementing
+will produce @samp{10.0000}; decrementing will produce @samp{9.9999}.
+One digit has been dropped. This is an unavoidable consequence of the
+way floating-point numbers work.
+
+Incrementing a date/time form adjusts it by a certain number of seconds.
+Incrementing a pure date form adjusts it by a certain number of days.
+
+@node Integer Truncation, Complex Number Functions, Basic Arithmetic, Arithmetic
+@section Integer Truncation
+
+@noindent
+There are four commands for truncating a real number to an integer,
+differing mainly in their treatment of negative numbers. All of these
+commands have the property that if the argument is an integer, the result
+is the same integer. An integer-valued floating-point argument is converted
+to integer form.
+
+If you press @kbd{H} (@code{calc-hyperbolic}) first, the result will be
+expressed as an integer-valued floating-point number.
+
+@cindex Integer part of a number
+@kindex F
+@pindex calc-floor
+@tindex floor
+@tindex ffloor
+@ignore
+@mindex @null
+@end ignore
+@kindex H F
+The @kbd{F} (@code{calc-floor}) [@code{floor} or @code{ffloor}] command
+truncates a real number to the next lower integer, i.e., toward minus
+infinity. Thus @kbd{3.6 F} produces 3, but @kbd{_3.6 F} produces
+@mathit{-4}.
+
+@kindex I F
+@pindex calc-ceiling
+@tindex ceil
+@tindex fceil
+@ignore
+@mindex @null
+@end ignore
+@kindex H I F
+The @kbd{I F} (@code{calc-ceiling}) [@code{ceil} or @code{fceil}]
+command truncates toward positive infinity. Thus @kbd{3.6 I F} produces
+4, and @kbd{_3.6 I F} produces @mathit{-3}.
+
+@kindex R
+@pindex calc-round
+@tindex round
+@tindex fround
+@ignore
+@mindex @null
+@end ignore
+@kindex H R
+The @kbd{R} (@code{calc-round}) [@code{round} or @code{fround}] command
+rounds to the nearest integer. When the fractional part is .5 exactly,
+this command rounds away from zero. (All other rounding in the
+Calculator uses this convention as well.) Thus @kbd{3.5 R} produces 4
+but @kbd{3.4 R} produces 3; @kbd{_3.5 R} produces @mathit{-4}.
+
+@kindex I R
+@pindex calc-trunc
+@tindex trunc
+@tindex ftrunc
+@ignore
+@mindex @null
+@end ignore
+@kindex H I R
+The @kbd{I R} (@code{calc-trunc}) [@code{trunc} or @code{ftrunc}]
+command truncates toward zero. In other words, it ``chops off''
+everything after the decimal point. Thus @kbd{3.6 I R} produces 3 and
+@kbd{_3.6 I R} produces @mathit{-3}.
+
+These functions may not be applied meaningfully to error forms, but they
+do work for intervals. As a convenience, applying @code{floor} to a
+modulo form floors the value part of the form. Applied to a vector,
+these functions operate on all elements of the vector one by one.
+Applied to a date form, they operate on the internal numerical
+representation of dates, converting a date/time form into a pure date.
+
+@ignore
+@starindex
+@end ignore
+@tindex rounde
+@ignore
+@starindex
+@end ignore
+@tindex roundu
+@ignore
+@starindex
+@end ignore
+@tindex frounde
+@ignore
+@starindex
+@end ignore
+@tindex froundu
+There are two more rounding functions which can only be entered in
+algebraic notation. The @code{roundu} function is like @code{round}
+except that it rounds up, toward plus infinity, when the fractional
+part is .5. This distinction matters only for negative arguments.
+Also, @code{rounde} rounds to an even number in the case of a tie,
+rounding up or down as necessary. For example, @samp{rounde(3.5)} and
+@samp{rounde(4.5)} both return 4, but @samp{rounde(5.5)} returns 6.
+The advantage of round-to-even is that the net error due to rounding
+after a long calculation tends to cancel out to zero. An important
+subtle point here is that the number being fed to @code{rounde} will
+already have been rounded to the current precision before @code{rounde}
+begins. For example, @samp{rounde(2.500001)} with a current precision
+of 6 will incorrectly, or at least surprisingly, yield 2 because the
+argument will first have been rounded down to @expr{2.5} (which
+@code{rounde} sees as an exact tie between 2 and 3).
+
+Each of these functions, when written in algebraic formulas, allows
+a second argument which specifies the number of digits after the
+decimal point to keep. For example, @samp{round(123.4567, 2)} will
+produce the answer 123.46, and @samp{round(123.4567, -1)} will
+produce 120 (i.e., the cutoff is one digit to the @emph{left} of
+the decimal point). A second argument of zero is equivalent to
+no second argument at all.
+
+@cindex Fractional part of a number
+To compute the fractional part of a number (i.e., the amount which, when
+added to `@tfn{floor(}@var{n}@tfn{)}', will produce @var{n}) just take @var{n}
+modulo 1 using the @code{%} command.
+
+Note also the @kbd{\} (integer quotient), @kbd{f I} (integer logarithm),
+and @kbd{f Q} (integer square root) commands, which are analogous to
+@kbd{/}, @kbd{B}, and @kbd{Q}, respectively, except that they take integer
+arguments and return the result rounded down to an integer.
+
+@node Complex Number Functions, Conversions, Integer Truncation, Arithmetic
+@section Complex Number Functions
+
+@noindent
+@kindex J
+@pindex calc-conj
+@tindex conj
+The @kbd{J} (@code{calc-conj}) [@code{conj}] command computes the
+complex conjugate of a number. For complex number @expr{a+bi}, the
+complex conjugate is @expr{a-bi}. If the argument is a real number,
+this command leaves it the same. If the argument is a vector or matrix,
+this command replaces each element by its complex conjugate.
+
+@kindex G
+@pindex calc-argument
+@tindex arg
+The @kbd{G} (@code{calc-argument}) [@code{arg}] command computes the
+``argument'' or polar angle of a complex number. For a number in polar
+notation, this is simply the second component of the pair
+@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}'.
+@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}'.
+The result is expressed according to the current angular mode and will
+be in the range @mathit{-180} degrees (exclusive) to @mathit{+180} degrees
+(inclusive), or the equivalent range in radians.
+
+@pindex calc-imaginary
+The @code{calc-imaginary} command multiplies the number on the
+top of the stack by the imaginary number @expr{i = (0,1)}. This
+command is not normally bound to a key in Calc, but it is available
+on the @key{IMAG} button in Keypad mode.
+
+@kindex f r
+@pindex calc-re
+@tindex re
+The @kbd{f r} (@code{calc-re}) [@code{re}] command replaces a complex number
+by its real part. This command has no effect on real numbers. (As an
+added convenience, @code{re} applied to a modulo form extracts
+the value part.)
+
+@kindex f i
+@pindex calc-im
+@tindex im
+The @kbd{f i} (@code{calc-im}) [@code{im}] command replaces a complex number
+by its imaginary part; real numbers are converted to zero. With a vector
+or matrix argument, these functions operate element-wise.
+
+@ignore
+@mindex v p
+@end ignore
+@kindex v p (complex)
+@pindex calc-pack
+The @kbd{v p} (@code{calc-pack}) command can pack the top two numbers on
+the stack into a composite object such as a complex number. With
+a prefix argument of @mathit{-1}, it produces a rectangular complex number;
+with an argument of @mathit{-2}, it produces a polar complex number.
+(Also, @pxref{Building Vectors}.)
+
+@ignore
+@mindex v u
+@end ignore
+@kindex v u (complex)
+@pindex calc-unpack
+The @kbd{v u} (@code{calc-unpack}) command takes the complex number
+(or other composite object) on the top of the stack and unpacks it
+into its separate components.
+
+@node Conversions, Date Arithmetic, Complex Number Functions, Arithmetic
+@section Conversions
+
+@noindent
+The commands described in this section convert numbers from one form
+to another; they are two-key sequences beginning with the letter @kbd{c}.
+
+@kindex c f
+@pindex calc-float
+@tindex pfloat
+The @kbd{c f} (@code{calc-float}) [@code{pfloat}] command converts the
+number on the top of the stack to floating-point form. For example,
+@expr{23} is converted to @expr{23.0}, @expr{3:2} is converted to
+@expr{1.5}, and @expr{2.3} is left the same. If the value is a composite
+object such as a complex number or vector, each of the components is
+converted to floating-point. If the value is a formula, all numbers
+in the formula are converted to floating-point. Note that depending
+on the current floating-point precision, conversion to floating-point
+format may lose information.
+
+As a special exception, integers which appear as powers or subscripts
+are not floated by @kbd{c f}. If you really want to float a power,
+you can use a @kbd{j s} command to select the power followed by @kbd{c f}.
+Because @kbd{c f} cannot examine the formula outside of the selection,
+it does not notice that the thing being floated is a power.
+@xref{Selecting Subformulas}.
+
+The normal @kbd{c f} command is ``pervasive'' in the sense that it
+applies to all numbers throughout the formula. The @code{pfloat}
+algebraic function never stays around in a formula; @samp{pfloat(a + 1)}
+changes to @samp{a + 1.0} as soon as it is evaluated.
+
+@kindex H c f
+@tindex float
+With the Hyperbolic flag, @kbd{H c f} [@code{float}] operates
+only on the number or vector of numbers at the top level of its
+argument. Thus, @samp{float(1)} is 1.0, but @samp{float(a + 1)}
+is left unevaluated because its argument is not a number.
+
+You should use @kbd{H c f} if you wish to guarantee that the final
+value, once all the variables have been assigned, is a float; you
+would use @kbd{c f} if you wish to do the conversion on the numbers
+that appear right now.
+
+@kindex c F
+@pindex calc-fraction
+@tindex pfrac
+The @kbd{c F} (@code{calc-fraction}) [@code{pfrac}] command converts a
+floating-point number into a fractional approximation. By default, it
+produces a fraction whose decimal representation is the same as the
+input number, to within the current precision. You can also give a
+numeric prefix argument to specify a tolerance, either directly, or,
+if the prefix argument is zero, by using the number on top of the stack
+as the tolerance. If the tolerance is a positive integer, the fraction
+is correct to within that many significant figures. If the tolerance is
+a non-positive integer, it specifies how many digits fewer than the current
+precision to use. If the tolerance is a floating-point number, the
+fraction is correct to within that absolute amount.
+
+@kindex H c F
+@tindex frac
+The @code{pfrac} function is pervasive, like @code{pfloat}.
+There is also a non-pervasive version, @kbd{H c F} [@code{frac}],
+which is analogous to @kbd{H c f} discussed above.
+
+@kindex c d
+@pindex calc-to-degrees
+@tindex deg
+The @kbd{c d} (@code{calc-to-degrees}) [@code{deg}] command converts a
+number into degrees form. The value on the top of the stack may be an
+HMS form (interpreted as degrees-minutes-seconds), or a real number which
+will be interpreted in radians regardless of the current angular mode.
+
+@kindex c r
+@pindex calc-to-radians
+@tindex rad
+The @kbd{c r} (@code{calc-to-radians}) [@code{rad}] command converts an
+HMS form or angle in degrees into an angle in radians.
+
+@kindex c h
+@pindex calc-to-hms
+@tindex hms
+The @kbd{c h} (@code{calc-to-hms}) [@code{hms}] command converts a real
+number, interpreted according to the current angular mode, to an HMS
+form describing the same angle. In algebraic notation, the @code{hms}
+function also accepts three arguments: @samp{hms(@var{h}, @var{m}, @var{s})}.
+(The three-argument version is independent of the current angular mode.)
+
+@pindex calc-from-hms
+The @code{calc-from-hms} command converts the HMS form on the top of the
+stack into a real number according to the current angular mode.
+
+@kindex c p
+@kindex I c p
+@pindex calc-polar
+@tindex polar
+@tindex rect
+The @kbd{c p} (@code{calc-polar}) command converts the complex number on
+the top of the stack from polar to rectangular form, or from rectangular
+to polar form, whichever is appropriate. Real numbers are left the same.
+This command is equivalent to the @code{rect} or @code{polar}
+functions in algebraic formulas, depending on the direction of
+conversion. (It uses @code{polar}, except that if the argument is
+already a polar complex number, it uses @code{rect} instead. The
+@kbd{I c p} command always uses @code{rect}.)
+
+@kindex c c
+@pindex calc-clean
+@tindex pclean
+The @kbd{c c} (@code{calc-clean}) [@code{pclean}] command ``cleans'' the
+number on the top of the stack. Floating point numbers are re-rounded
+according to the current precision. Polar numbers whose angular
+components have strayed from the @mathit{-180} to @mathit{+180} degree range
+are normalized. (Note that results will be undesirable if the current
+angular mode is different from the one under which the number was
+produced!) Integers and fractions are generally unaffected by this
+operation. Vectors and formulas are cleaned by cleaning each component
+number (i.e., pervasively).
+
+If the simplification mode is set below the default level, it is raised
+to the default level for the purposes of this command. Thus, @kbd{c c}
+applies the default simplifications even if their automatic application
+is disabled. @xref{Simplification Modes}.
+
+@cindex Roundoff errors, correcting
+A numeric prefix argument to @kbd{c c} sets the floating-point precision
+to that value for the duration of the command. A positive prefix (of at
+least 3) sets the precision to the specified value; a negative or zero
+prefix decreases the precision by the specified amount.
+
+@kindex c 0-9
+@pindex calc-clean-num
+The keystroke sequences @kbd{c 0} through @kbd{c 9} are equivalent
+to @kbd{c c} with the corresponding negative prefix argument. If roundoff
+errors have changed 2.0 into 1.999999, typing @kbd{c 1} to clip off one
+decimal place often conveniently does the trick.
+
+The @kbd{c c} command with a numeric prefix argument, and the @kbd{c 0}
+through @kbd{c 9} commands, also ``clip'' very small floating-point
+numbers to zero. If the exponent is less than or equal to the negative
+of the specified precision, the number is changed to 0.0. For example,
+if the current precision is 12, then @kbd{c 2} changes the vector
+@samp{[1e-8, 1e-9, 1e-10, 1e-11]} to @samp{[1e-8, 1e-9, 0, 0]}.
+Numbers this small generally arise from roundoff noise.
+
+If the numbers you are using really are legitimately this small,
+you should avoid using the @kbd{c 0} through @kbd{c 9} commands.
+(The plain @kbd{c c} command rounds to the current precision but
+does not clip small numbers.)
+
+One more property of @kbd{c 0} through @kbd{c 9}, and of @kbd{c c} with
+a prefix argument, is that integer-valued floats are converted to
+plain integers, so that @kbd{c 1} on @samp{[1., 1.5, 2., 2.5, 3.]}
+produces @samp{[1, 1.5, 2, 2.5, 3]}. This is not done for huge
+numbers (@samp{1e100} is technically an integer-valued float, but
+you wouldn't want it automatically converted to a 100-digit integer).
+
+@kindex H c 0-9
+@kindex H c c
+@tindex clean
+With the Hyperbolic flag, @kbd{H c c} and @kbd{H c 0} through @kbd{H c 9}
+operate non-pervasively [@code{clean}].
+
+@node Date Arithmetic, Financial Functions, Conversions, Arithmetic
+@section Date Arithmetic
+
+@noindent
+@cindex Date arithmetic, additional functions
+The commands described in this section perform various conversions
+and calculations involving date forms (@pxref{Date Forms}). They
+use the @kbd{t} (for time/date) prefix key followed by shifted
+letters.
+
+The simplest date arithmetic is done using the regular @kbd{+} and @kbd{-}
+commands. In particular, adding a number to a date form advances the
+date form by a certain number of days; adding an HMS form to a date
+form advances the date by a certain amount of time; and subtracting two
+date forms produces a difference measured in days. The commands
+described here provide additional, more specialized operations on dates.
+
+Many of these commands accept a numeric prefix argument; if you give
+plain @kbd{C-u} as the prefix, these commands will instead take the
+additional argument from the top of the stack.
+
+@menu
+* Date Conversions::
+* Date Functions::
+* Time Zones::
+* Business Days::
+@end menu
+
+@node Date Conversions, Date Functions, Date Arithmetic, Date Arithmetic
+@subsection Date Conversions
+
+@noindent
+@kindex t D
+@pindex calc-date
+@tindex date
+The @kbd{t D} (@code{calc-date}) [@code{date}] command converts a
+date form into a number, measured in days since Jan 1, 1 AD. The
+result will be an integer if @var{date} is a pure date form, or a
+fraction or float if @var{date} is a date/time form. Or, if its
+argument is a number, it converts this number into a date form.
+
+With a numeric prefix argument, @kbd{t D} takes that many objects
+(up to six) from the top of the stack and interprets them in one
+of the following ways:
+
+The @samp{date(@var{year}, @var{month}, @var{day})} function
+builds a pure date form out of the specified year, month, and
+day, which must all be integers. @var{Year} is a year number,
+such as 1991 (@emph{not} the same as 91!). @var{Month} must be
+an integer in the range 1 to 12; @var{day} must be in the range
+1 to 31. If the specified month has fewer than 31 days and
+@var{day} is too large, the equivalent day in the following
+month will be used.
+
+The @samp{date(@var{month}, @var{day})} function builds a
+pure date form using the current year, as determined by the
+real-time clock.
+
+The @samp{date(@var{year}, @var{month}, @var{day}, @var{hms})}
+function builds a date/time form using an @var{hms} form.
+
+The @samp{date(@var{year}, @var{month}, @var{day}, @var{hour},
+@var{minute}, @var{second})} function builds a date/time form.
+@var{hour} should be an integer in the range 0 to 23;
+@var{minute} should be an integer in the range 0 to 59;
+@var{second} should be any real number in the range @samp{[0 .. 60)}.
+The last two arguments default to zero if omitted.
+
+@kindex t J
+@pindex calc-julian
+@tindex julian
+@cindex Julian day counts, conversions
+The @kbd{t J} (@code{calc-julian}) [@code{julian}] command converts
+a date form into a Julian day count, which is the number of days
+since noon (GMT) on Jan 1, 4713 BC. A pure date is converted to an
+integer Julian count representing noon of that day. A date/time form
+is converted to an exact floating-point Julian count, adjusted to
+interpret the date form in the current time zone but the Julian
+day count in Greenwich Mean Time. A numeric prefix argument allows
+you to specify the time zone; @pxref{Time Zones}. Use a prefix of
+zero to suppress the time zone adjustment. Note that pure date forms
+are never time-zone adjusted.
+
+This command can also do the opposite conversion, from a Julian day
+count (either an integer day, or a floating-point day and time in
+the GMT zone), into a pure date form or a date/time form in the
+current or specified time zone.
+
+@kindex t U
+@pindex calc-unix-time
+@tindex unixtime
+@cindex Unix time format, conversions
+The @kbd{t U} (@code{calc-unix-time}) [@code{unixtime}] command
+converts a date form into a Unix time value, which is the number of
+seconds since midnight on Jan 1, 1970, or vice-versa. The numeric result
+will be an integer if the current precision is 12 or less; for higher
+precisions, the result may be a float with (@var{precision}@minus{}12)
+digits after the decimal. Just as for @kbd{t J}, the numeric time
+is interpreted in the GMT time zone and the date form is interpreted
+in the current or specified zone. Some systems use Unix-like
+numbering but with the local time zone; give a prefix of zero to
+suppress the adjustment if so.
+
+@kindex t C
+@pindex calc-convert-time-zones
+@tindex tzconv
+@cindex Time Zones, converting between
+The @kbd{t C} (@code{calc-convert-time-zones}) [@code{tzconv}]
+command converts a date form from one time zone to another. You
+are prompted for each time zone name in turn; you can answer with
+any suitable Calc time zone expression (@pxref{Time Zones}).
+If you answer either prompt with a blank line, the local time
+zone is used for that prompt. You can also answer the first
+prompt with @kbd{$} to take the two time zone names from the
+stack (and the date to be converted from the third stack level).
+
+@node Date Functions, Business Days, Date Conversions, Date Arithmetic
+@subsection Date Functions
+
+@noindent
+@kindex t N
+@pindex calc-now
+@tindex now
+The @kbd{t N} (@code{calc-now}) [@code{now}] command pushes the
+current date and time on the stack as a date form. The time is
+reported in terms of the specified time zone; with no numeric prefix
+argument, @kbd{t N} reports for the current time zone.
+
+@kindex t P
+@pindex calc-date-part
+The @kbd{t P} (@code{calc-date-part}) command extracts one part
+of a date form. The prefix argument specifies the part; with no
+argument, this command prompts for a part code from 1 to 9.
+The various part codes are described in the following paragraphs.
+
+@tindex year
+The @kbd{M-1 t P} [@code{year}] function extracts the year number
+from a date form as an integer, e.g., 1991. This and the
+following functions will also accept a real number for an
+argument, which is interpreted as a standard Calc day number.
+Note that this function will never return zero, since the year
+1 BC immediately precedes the year 1 AD.
+
+@tindex month
+The @kbd{M-2 t P} [@code{month}] function extracts the month number
+from a date form as an integer in the range 1 to 12.
+
+@tindex day
+The @kbd{M-3 t P} [@code{day}] function extracts the day number
+from a date form as an integer in the range 1 to 31.
+
+@tindex hour
+The @kbd{M-4 t P} [@code{hour}] function extracts the hour from
+a date form as an integer in the range 0 (midnight) to 23. Note
+that 24-hour time is always used. This returns zero for a pure
+date form. This function (and the following two) also accept
+HMS forms as input.
+
+@tindex minute
+The @kbd{M-5 t P} [@code{minute}] function extracts the minute
+from a date form as an integer in the range 0 to 59.
+
+@tindex second
+The @kbd{M-6 t P} [@code{second}] function extracts the second
+from a date form. If the current precision is 12 or less,
+the result is an integer in the range 0 to 59. For higher
+precisions, the result may instead be a floating-point number.
+
+@tindex weekday
+The @kbd{M-7 t P} [@code{weekday}] function extracts the weekday
+number from a date form as an integer in the range 0 (Sunday)
+to 6 (Saturday).
+
+@tindex yearday
+The @kbd{M-8 t P} [@code{yearday}] function extracts the day-of-year
+number from a date form as an integer in the range 1 (January 1)
+to 366 (December 31 of a leap year).
+
+@tindex time
+The @kbd{M-9 t P} [@code{time}] function extracts the time portion
+of a date form as an HMS form. This returns @samp{0@@ 0' 0"}
+for a pure date form.
+
+@kindex t M
+@pindex calc-new-month
+@tindex newmonth
+The @kbd{t M} (@code{calc-new-month}) [@code{newmonth}] command
+computes a new date form that represents the first day of the month
+specified by the input date. The result is always a pure date
+form; only the year and month numbers of the input are retained.
+With a numeric prefix argument @var{n} in the range from 1 to 31,
+@kbd{t M} computes the @var{n}th day of the month. (If @var{n}
+is greater than the actual number of days in the month, or if
+@var{n} is zero, the last day of the month is used.)
+
+@kindex t Y
+@pindex calc-new-year
+@tindex newyear
+The @kbd{t Y} (@code{calc-new-year}) [@code{newyear}] command
+computes a new pure date form that represents the first day of
+the year specified by the input. The month, day, and time
+of the input date form are lost. With a numeric prefix argument
+@var{n} in the range from 1 to 366, @kbd{t Y} computes the
+@var{n}th day of the year (366 is treated as 365 in non-leap
+years). A prefix argument of 0 computes the last day of the
+year (December 31). A negative prefix argument from @mathit{-1} to
+@mathit{-12} computes the first day of the @var{n}th month of the year.
+
+@kindex t W
+@pindex calc-new-week
+@tindex newweek
+The @kbd{t W} (@code{calc-new-week}) [@code{newweek}] command
+computes a new pure date form that represents the Sunday on or before
+the input date. With a numeric prefix argument, it can be made to
+use any day of the week as the starting day; the argument must be in
+the range from 0 (Sunday) to 6 (Saturday). This function always
+subtracts between 0 and 6 days from the input date.
+
+Here's an example use of @code{newweek}: Find the date of the next
+Wednesday after a given date. Using @kbd{M-3 t W} or @samp{newweek(d, 3)}
+will give you the @emph{preceding} Wednesday, so @samp{newweek(d+7, 3)}
+will give you the following Wednesday. A further look at the definition
+of @code{newweek} shows that if the input date is itself a Wednesday,
+this formula will return the Wednesday one week in the future. An
+exercise for the reader is to modify this formula to yield the same day
+if the input is already a Wednesday. Another interesting exercise is
+to preserve the time-of-day portion of the input (@code{newweek} resets
+the time to midnight; hint:@: how can @code{newweek} be defined in terms
+of the @code{weekday} function?).
+
+@ignore
+@starindex
+@end ignore
+@tindex pwday
+The @samp{pwday(@var{date})} function (not on any key) computes the
+day-of-month number of the Sunday on or before @var{date}. With
+two arguments, @samp{pwday(@var{date}, @var{day})} computes the day
+number of the Sunday on or before day number @var{day} of the month
+specified by @var{date}. The @var{day} must be in the range from
+7 to 31; if the day number is greater than the actual number of days
+in the month, the true number of days is used instead. Thus
+@samp{pwday(@var{date}, 7)} finds the first Sunday of the month, and
+@samp{pwday(@var{date}, 31)} finds the last Sunday of the month.
+With a third @var{weekday} argument, @code{pwday} can be made to look
+for any day of the week instead of Sunday.
+
+@kindex t I
+@pindex calc-inc-month
+@tindex incmonth
+The @kbd{t I} (@code{calc-inc-month}) [@code{incmonth}] command
+increases a date form by one month, or by an arbitrary number of
+months specified by a numeric prefix argument. The time portion,
+if any, of the date form stays the same. The day also stays the
+same, except that if the new month has fewer days the day
+number may be reduced to lie in the valid range. For example,
+@samp{incmonth(<Jan 31, 1991>)} produces @samp{<Feb 28, 1991>}.
+Because of this, @kbd{t I t I} and @kbd{M-2 t I} do not always give
+the same results (@samp{<Mar 28, 1991>} versus @samp{<Mar 31, 1991>}
+in this case).
+
+@ignore
+@starindex
+@end ignore
+@tindex incyear
+The @samp{incyear(@var{date}, @var{step})} function increases
+a date form by the specified number of years, which may be
+any positive or negative integer. Note that @samp{incyear(d, n)}
+is equivalent to @w{@samp{incmonth(d, 12*n)}}, but these do not have
+simple equivalents in terms of day arithmetic because
+months and years have varying lengths. If the @var{step}
+argument is omitted, 1 year is assumed. There is no keyboard
+command for this function; use @kbd{C-u 12 t I} instead.
+
+There is no @code{newday} function at all because @kbd{F} [@code{floor}]
+serves this purpose. Similarly, instead of @code{incday} and
+@code{incweek} simply use @expr{d + n} or @expr{d + 7 n}.
+
+@xref{Basic Arithmetic}, for the @kbd{f ]} [@code{incr}] command
+which can adjust a date/time form by a certain number of seconds.
+
+@node Business Days, Time Zones, Date Functions, Date Arithmetic
+@subsection Business Days
+
+@noindent
+Often time is measured in ``business days'' or ``working days,''
+where weekends and holidays are skipped. Calc's normal date
+arithmetic functions use calendar days, so that subtracting two
+consecutive Mondays will yield a difference of 7 days. By contrast,
+subtracting two consecutive Mondays would yield 5 business days
+(assuming two-day weekends and the absence of holidays).
+
+@kindex t +
+@kindex t -
+@tindex badd
+@tindex bsub
+@pindex calc-business-days-plus
+@pindex calc-business-days-minus
+The @kbd{t +} (@code{calc-business-days-plus}) [@code{badd}]
+and @kbd{t -} (@code{calc-business-days-minus}) [@code{bsub}]
+commands perform arithmetic using business days. For @kbd{t +},
+one argument must be a date form and the other must be a real
+number (positive or negative). If the number is not an integer,
+then a certain amount of time is added as well as a number of
+days; for example, adding 0.5 business days to a time in Friday
+evening will produce a time in Monday morning. It is also
+possible to add an HMS form; adding @samp{12@@ 0' 0"} also adds
+half a business day. For @kbd{t -}, the arguments are either a
+date form and a number or HMS form, or two date forms, in which
+case the result is the number of business days between the two
+dates.
+
+@cindex @code{Holidays} variable
+@vindex Holidays
+By default, Calc considers any day that is not a Saturday or
+Sunday to be a business day. You can define any number of
+additional holidays by editing the variable @code{Holidays}.
+(There is an @w{@kbd{s H}} convenience command for editing this
+variable.) Initially, @code{Holidays} contains the vector
+@samp{[sat, sun]}. Entries in the @code{Holidays} vector may
+be any of the following kinds of objects:
+
+@itemize @bullet
+@item
+Date forms (pure dates, not date/time forms). These specify
+particular days which are to be treated as holidays.
+
+@item
+Intervals of date forms. These specify a range of days, all of
+which are holidays (e.g., Christmas week). @xref{Interval Forms}.
+
+@item
+Nested vectors of date forms. Each date form in the vector is
+considered to be a holiday.
+
+@item
+Any Calc formula which evaluates to one of the above three things.
+If the formula involves the variable @expr{y}, it stands for a
+yearly repeating holiday; @expr{y} will take on various year
+numbers like 1992. For example, @samp{date(y, 12, 25)} specifies
+Christmas day, and @samp{newweek(date(y, 11, 7), 4) + 21} specifies
+Thanksgiving (which is held on the fourth Thursday of November).
+If the formula involves the variable @expr{m}, that variable
+takes on month numbers from 1 to 12: @samp{date(y, m, 15)} is
+a holiday that takes place on the 15th of every month.
+
+@item
+A weekday name, such as @code{sat} or @code{sun}. This is really
+a variable whose name is a three-letter, lower-case day name.
+
+@item
+An interval of year numbers (integers). This specifies the span of
+years over which this holiday list is to be considered valid. Any
+business-day arithmetic that goes outside this range will result
+in an error message. Use this if you are including an explicit
+list of holidays, rather than a formula to generate them, and you
+want to make sure you don't accidentally go beyond the last point
+where the holidays you entered are complete. If there is no
+limiting interval in the @code{Holidays} vector, the default
+@samp{[1 .. 2737]} is used. (This is the absolute range of years
+for which Calc's business-day algorithms will operate.)
+
+@item
+An interval of HMS forms. This specifies the span of hours that
+are to be considered one business day. For example, if this
+range is @samp{[9@@ 0' 0" .. 17@@ 0' 0"]} (i.e., 9am to 5pm), then
+the business day is only eight hours long, so that @kbd{1.5 t +}
+on @samp{<4:00pm Fri Dec 13, 1991>} will add one business day and
+four business hours to produce @samp{<12:00pm Tue Dec 17, 1991>}.
+Likewise, @kbd{t -} will now express differences in time as
+fractions of an eight-hour day. Times before 9am will be treated
+as 9am by business date arithmetic, and times at or after 5pm will
+be treated as 4:59:59pm. If there is no HMS interval in @code{Holidays},
+the full 24-hour day @samp{[0@ 0' 0" .. 24@ 0' 0"]} is assumed.
+(Regardless of the type of bounds you specify, the interval is
+treated as inclusive on the low end and exclusive on the high end,
+so that the work day goes from 9am up to, but not including, 5pm.)
+@end itemize
+
+If the @code{Holidays} vector is empty, then @kbd{t +} and
+@kbd{t -} will act just like @kbd{+} and @kbd{-} because there will
+then be no difference between business days and calendar days.
+
+Calc expands the intervals and formulas you give into a complete
+list of holidays for internal use. This is done mainly to make
+sure it can detect multiple holidays. (For example,
+@samp{<Jan 1, 1989>} is both New Year's Day and a Sunday, but
+Calc's algorithms take care to count it only once when figuring
+the number of holidays between two dates.)
+
+Since the complete list of holidays for all the years from 1 to
+2737 would be huge, Calc actually computes only the part of the
+list between the smallest and largest years that have been involved
+in business-day calculations so far. Normally, you won't have to
+worry about this. Keep in mind, however, that if you do one
+calculation for 1992, and another for 1792, even if both involve
+only a small range of years, Calc will still work out all the
+holidays that fall in that 200-year span.
+
+If you add a (positive) number of days to a date form that falls on a
+weekend or holiday, the date form is treated as if it were the most
+recent business day. (Thus adding one business day to a Friday,
+Saturday, or Sunday will all yield the following Monday.) If you
+subtract a number of days from a weekend or holiday, the date is
+effectively on the following business day. (So subtracting one business
+day from Saturday, Sunday, or Monday yields the preceding Friday.) The
+difference between two dates one or both of which fall on holidays
+equals the number of actual business days between them. These
+conventions are consistent in the sense that, if you add @var{n}
+business days to any date, the difference between the result and the
+original date will come out to @var{n} business days. (It can't be
+completely consistent though; a subtraction followed by an addition
+might come out a bit differently, since @kbd{t +} is incapable of
+producing a date that falls on a weekend or holiday.)
+
+@ignore
+@starindex
+@end ignore
+@tindex holiday
+There is a @code{holiday} function, not on any keys, that takes
+any date form and returns 1 if that date falls on a weekend or
+holiday, as defined in @code{Holidays}, or 0 if the date is a
+business day.
+
+@node Time Zones, , Business Days, Date Arithmetic
+@subsection Time Zones
+
+@noindent
+@cindex Time zones
+@cindex Daylight saving time
+Time zones and daylight saving time are a complicated business.
+The conversions to and from Julian and Unix-style dates automatically
+compute the correct time zone and daylight saving adjustment to use,
+provided they can figure out this information. This section describes
+Calc's time zone adjustment algorithm in detail, in case you want to
+do conversions in different time zones or in case Calc's algorithms
+can't determine the right correction to use.
+
+Adjustments for time zones and daylight saving time are done by
+@kbd{t U}, @kbd{t J}, @kbd{t N}, and @kbd{t C}, but not by any other
+commands. In particular, @samp{<may 1 1991> - <apr 1 1991>} evaluates
+to exactly 30 days even though there is a daylight-saving
+transition in between. This is also true for Julian pure dates:
+@samp{julian(<may 1 1991>) - julian(<apr 1 1991>)}. But Julian
+and Unix date/times will adjust for daylight saving time: using Calc's
+default daylight saving time rule (see the explanation below),
+@samp{julian(<12am may 1 1991>) - julian(<12am apr 1 1991>)}
+evaluates to @samp{29.95833} (that's 29 days and 23 hours)
+because one hour was lost when daylight saving commenced on
+April 7, 1991.
+
+In brief, the idiom @samp{julian(@var{date1}) - julian(@var{date2})}
+computes the actual number of 24-hour periods between two dates, whereas
+@samp{@var{date1} - @var{date2}} computes the number of calendar
+days between two dates without taking daylight saving into account.
+
+@pindex calc-time-zone
+@ignore
+@starindex
+@end ignore
+@tindex tzone
+The @code{calc-time-zone} [@code{tzone}] command converts the time
+zone specified by its numeric prefix argument into a number of
+seconds difference from Greenwich mean time (GMT). If the argument
+is a number, the result is simply that value multiplied by 3600.
+Typical arguments for North America are 5 (Eastern) or 8 (Pacific). If
+Daylight Saving time is in effect, one hour should be subtracted from
+the normal difference.
+
+If you give a prefix of plain @kbd{C-u}, @code{calc-time-zone} (like other
+date arithmetic commands that include a time zone argument) takes the
+zone argument from the top of the stack. (In the case of @kbd{t J}
+and @kbd{t U}, the normal argument is then taken from the second-to-top
+stack position.) This allows you to give a non-integer time zone
+adjustment. The time-zone argument can also be an HMS form, or
+it can be a variable which is a time zone name in upper- or lower-case.
+For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)}
+(for Pacific standard and daylight saving times, respectively).
+
+North American and European time zone names are defined as follows;
+note that for each time zone there is one name for standard time,
+another for daylight saving time, and a third for ``generalized'' time
+in which the daylight saving adjustment is computed from context.
+
+@smallexample
+@group
+YST PST MST CST EST AST NST GMT WET MET MEZ
+ 9 8 7 6 5 4 3.5 0 -1 -2 -2
+
+YDT PDT MDT CDT EDT ADT NDT BST WETDST METDST MESZ
+ 8 7 6 5 4 3 2.5 -1 -2 -3 -3
+
+YGT PGT MGT CGT EGT AGT NGT BGT WEGT MEGT MEGZ
+9/8 8/7 7/6 6/5 5/4 4/3 3.5/2.5 0/-1 -1/-2 -2/-3 -2/-3
+@end group
+@end smallexample
+
+@vindex math-tzone-names
+To define time zone names that do not appear in the above table,
+you must modify the Lisp variable @code{math-tzone-names}. This
+is a list of lists describing the different time zone names; its
+structure is best explained by an example. The three entries for
+Pacific Time look like this:
+
+@smallexample
+@group
+( ( "PST" 8 0 ) ; Name as an upper-case string, then standard
+ ( "PDT" 8 -1 ) ; adjustment, then daylight saving adjustment.
+ ( "PGT" 8 "PST" "PDT" ) ) ; Generalized time zone.
+@end group
+@end smallexample
+
+@cindex @code{TimeZone} variable
+@vindex TimeZone
+With no arguments, @code{calc-time-zone} or @samp{tzone()} will by
+default get the time zone and daylight saving information from the
+calendar (@pxref{Daylight Saving,Calendar/Diary,The Calendar and the Diary,
+emacs,The GNU Emacs Manual}). To use a different time zone, or if the
+calendar does not give the desired result, you can set the Calc variable
+@code{TimeZone} (which is by default @code{nil}) to an appropriate
+time zone name. (The easiest way to do this is to edit the
+@code{TimeZone} variable using Calc's @kbd{s T} command, then use the
+@kbd{s p} (@code{calc-permanent-variable}) command to save the value of
+@code{TimeZone} permanently.)
+If the time zone given by @code{TimeZone} is a generalized time zone,
+e.g., @code{EGT}, Calc examines the date being converted to tell whether
+to use standard or daylight saving time. But if the current time zone
+is explicit, e.g., @code{EST} or @code{EDT}, then that adjustment is
+used exactly and Calc's daylight saving algorithm is not consulted.
+The special time zone name @code{local}
+is equivalent to no argument; i.e., it uses the information obtained
+from the calendar.
+
+The @kbd{t J} and @code{t U} commands with no numeric prefix
+arguments do the same thing as @samp{tzone()}; namely, use the
+information from the calendar if @code{TimeZone} is @code{nil},
+otherwise use the time zone given by @code{TimeZone}.
+
+@vindex math-daylight-savings-hook
+@findex math-std-daylight-savings
+When Calc computes the daylight saving information itself (i.e., when
+the @code{TimeZone} variable is set), it will by default consider
+daylight saving time to begin at 2 a.m.@: on the second Sunday of March
+(for years from 2007 on) or on the last Sunday in April (for years
+before 2007), and to end at 2 a.m.@: on the first Sunday of
+November. (for years from 2007 on) or the last Sunday in October (for
+years before 2007). These are the rules that have been in effect in
+much of North America since 1966 and take into account the rule change
+that began in 2007. If you are in a country that uses different rules
+for computing daylight saving time, you have two choices: Write your own
+daylight saving hook, or control time zones explicitly by setting the
+@code{TimeZone} variable and/or always giving a time-zone argument for
+the conversion functions.
+
+The Lisp variable @code{math-daylight-savings-hook} holds the
+name of a function that is used to compute the daylight saving
+adjustment for a given date. The default is
+@code{math-std-daylight-savings}, which computes an adjustment
+(either 0 or @mathit{-1}) using the North American rules given above.
+
+The daylight saving hook function is called with four arguments:
+The date, as a floating-point number in standard Calc format;
+a six-element list of the date decomposed into year, month, day,
+hour, minute, and second, respectively; a string which contains
+the generalized time zone name in upper-case, e.g., @code{"WEGT"};
+and a special adjustment to be applied to the hour value when
+converting into a generalized time zone (see below).
+
+@findex math-prev-weekday-in-month
+The Lisp function @code{math-prev-weekday-in-month} is useful for
+daylight saving computations. This is an internal version of
+the user-level @code{pwday} function described in the previous
+section. It takes four arguments: The floating-point date value,
+the corresponding six-element date list, the day-of-month number,
+and the weekday number (0-6).
+
+The default daylight saving hook ignores the time zone name, but a
+more sophisticated hook could use different algorithms for different
+time zones. It would also be possible to use different algorithms
+depending on the year number, but the default hook always uses the
+algorithm for 1987 and later. Here is a listing of the default
+daylight saving hook:
+
+@smallexample
+(defun math-std-daylight-savings (date dt zone bump)
+ (cond ((< (nth 1 dt) 4) 0)
+ ((= (nth 1 dt) 4)
+ (let ((sunday (math-prev-weekday-in-month date dt 7 0)))
+ (cond ((< (nth 2 dt) sunday) 0)
+ ((= (nth 2 dt) sunday)
+ (if (>= (nth 3 dt) (+ 3 bump)) -1 0))
+ (t -1))))
+ ((< (nth 1 dt) 10) -1)
+ ((= (nth 1 dt) 10)
+ (let ((sunday (math-prev-weekday-in-month date dt 31 0)))
+ (cond ((< (nth 2 dt) sunday) -1)
+ ((= (nth 2 dt) sunday)
+ (if (>= (nth 3 dt) (+ 2 bump)) 0 -1))
+ (t 0))))
+ (t 0))
+)
+@end smallexample
+
+@noindent
+The @code{bump} parameter is equal to zero when Calc is converting
+from a date form in a generalized time zone into a GMT date value.
+It is @mathit{-1} when Calc is converting in the other direction. The
+adjustments shown above ensure that the conversion behaves correctly
+and reasonably around the 2 a.m.@: transition in each direction.
+
+There is a ``missing'' hour between 2 a.m.@: and 3 a.m.@: at the
+beginning of daylight saving time; converting a date/time form that
+falls in this hour results in a time value for the following hour,
+from 3 a.m.@: to 4 a.m. At the end of daylight saving time, the
+hour from 1 a.m.@: to 2 a.m.@: repeats itself; converting a date/time
+form that falls in this hour results in a time value for the first
+manifestation of that time (@emph{not} the one that occurs one hour
+later).
+
+If @code{math-daylight-savings-hook} is @code{nil}, then the
+daylight saving adjustment is always taken to be zero.
+
+In algebraic formulas, @samp{tzone(@var{zone}, @var{date})}
+computes the time zone adjustment for a given zone name at a
+given date. The @var{date} is ignored unless @var{zone} is a
+generalized time zone. If @var{date} is a date form, the
+daylight saving computation is applied to it as it appears.
+If @var{date} is a numeric date value, it is adjusted for the
+daylight-saving version of @var{zone} before being given to
+the daylight saving hook. This odd-sounding rule ensures
+that the daylight-saving computation is always done in
+local time, not in the GMT time that a numeric @var{date}
+is typically represented in.
+
+@ignore
+@starindex
+@end ignore
+@tindex dsadj
+The @samp{dsadj(@var{date}, @var{zone})} function computes the
+daylight saving adjustment that is appropriate for @var{date} in
+time zone @var{zone}. If @var{zone} is explicitly in or not in
+daylight saving time (e.g., @code{PDT} or @code{PST}) the
+@var{date} is ignored. If @var{zone} is a generalized time zone,
+the algorithms described above are used. If @var{zone} is omitted,
+the computation is done for the current time zone.
+
+@xref{Reporting Bugs}, for the address of Calc's author, if you
+should wish to contribute your improved versions of
+@code{math-tzone-names} and @code{math-daylight-savings-hook}
+to the Calc distribution.
+
+@node Financial Functions, Binary Functions, Date Arithmetic, Arithmetic
+@section Financial Functions
+
+@noindent
+Calc's financial or business functions use the @kbd{b} prefix
+key followed by a shifted letter. (The @kbd{b} prefix followed by
+a lower-case letter is used for operations on binary numbers.)
+
+Note that the rate and the number of intervals given to these
+functions must be on the same time scale, e.g., both months or
+both years. Mixing an annual interest rate with a time expressed
+in months will give you very wrong answers!
+
+It is wise to compute these functions to a higher precision than
+you really need, just to make sure your answer is correct to the
+last penny; also, you may wish to check the definitions at the end
+of this section to make sure the functions have the meaning you expect.
+
+@menu
+* Percentages::
+* Future Value::
+* Present Value::
+* Related Financial Functions::
+* Depreciation Functions::
+* Definitions of Financial Functions::
+@end menu
+
+@node Percentages, Future Value, Financial Functions, Financial Functions
+@subsection Percentages
+
+@kindex M-%
+@pindex calc-percent
+@tindex %
+@tindex percent
+The @kbd{M-%} (@code{calc-percent}) command takes a percentage value,
+say 5.4, and converts it to an equivalent actual number. For example,
+@kbd{5.4 M-%} enters 0.054 on the stack. (That's the @key{META} or
+@key{ESC} key combined with @kbd{%}.)
+
+Actually, @kbd{M-%} creates a formula of the form @samp{5.4%}.
+You can enter @samp{5.4%} yourself during algebraic entry. The
+@samp{%} operator simply means, ``the preceding value divided by
+100.'' The @samp{%} operator has very high precedence, so that
+@samp{1+8%} is interpreted as @samp{1+(8%)}, not as @samp{(1+8)%}.
+(The @samp{%} operator is just a postfix notation for the
+@code{percent} function, just like @samp{20!} is the notation for
+@samp{fact(20)}, or twenty-factorial.)
+
+The formula @samp{5.4%} would normally evaluate immediately to
+0.054, but the @kbd{M-%} command suppresses evaluation as it puts
+the formula onto the stack. However, the next Calc command that
+uses the formula @samp{5.4%} will evaluate it as its first step.
+The net effect is that you get to look at @samp{5.4%} on the stack,
+but Calc commands see it as @samp{0.054}, which is what they expect.
+
+In particular, @samp{5.4%} and @samp{0.054} are suitable values
+for the @var{rate} arguments of the various financial functions,
+but the number @samp{5.4} is probably @emph{not} suitable---it
+represents a rate of 540 percent!
+
+The key sequence @kbd{M-% *} effectively means ``percent-of.''
+For example, @kbd{68 @key{RET} 25 M-% *} computes 17, which is 25% of
+68 (and also 68% of 25, which comes out to the same thing).
+
+@kindex c %
+@pindex calc-convert-percent
+The @kbd{c %} (@code{calc-convert-percent}) command converts the
+value on the top of the stack from numeric to percentage form.
+For example, if 0.08 is on the stack, @kbd{c %} converts it to
+@samp{8%}. The quantity is the same, it's just represented
+differently. (Contrast this with @kbd{M-%}, which would convert
+this number to @samp{0.08%}.) The @kbd{=} key is a convenient way
+to convert a formula like @samp{8%} back to numeric form, 0.08.
+
+To compute what percentage one quantity is of another quantity,
+use @kbd{/ c %}. For example, @w{@kbd{17 @key{RET} 68 / c %}} displays
+@samp{25%}.
+
+@kindex b %
+@pindex calc-percent-change
+@tindex relch
+The @kbd{b %} (@code{calc-percent-change}) [@code{relch}] command
+calculates the percentage change from one number to another.
+For example, @kbd{40 @key{RET} 50 b %} produces the answer @samp{25%},
+since 50 is 25% larger than 40. A negative result represents a
+decrease: @kbd{50 @key{RET} 40 b %} produces @samp{-20%}, since 40 is
+20% smaller than 50. (The answers are different in magnitude
+because, in the first case, we're increasing by 25% of 40, but
+in the second case, we're decreasing by 20% of 50.) The effect
+of @kbd{40 @key{RET} 50 b %} is to compute @expr{(50-40)/40}, converting
+the answer to percentage form as if by @kbd{c %}.
+
+@node Future Value, Present Value, Percentages, Financial Functions
+@subsection Future Value
+
+@noindent
+@kindex b F
+@pindex calc-fin-fv
+@tindex fv
+The @kbd{b F} (@code{calc-fin-fv}) [@code{fv}] command computes
+the future value of an investment. It takes three arguments
+from the stack: @samp{fv(@var{rate}, @var{n}, @var{payment})}.
+If you give payments of @var{payment} every year for @var{n}
+years, and the money you have paid earns interest at @var{rate} per
+year, then this function tells you what your investment would be
+worth at the end of the period. (The actual interval doesn't
+have to be years, as long as @var{n} and @var{rate} are expressed
+in terms of the same intervals.) This function assumes payments
+occur at the @emph{end} of each interval.
+
+@kindex I b F
+@tindex fvb
+The @kbd{I b F} [@code{fvb}] command does the same computation,
+but assuming your payments are at the beginning of each interval.
+Suppose you plan to deposit $1000 per year in a savings account
+earning 5.4% interest, starting right now. How much will be
+in the account after five years? @code{fvb(5.4%, 5, 1000) = 5870.73}.
+Thus you will have earned $870 worth of interest over the years.
+Using the stack, this calculation would have been
+@kbd{5.4 M-% 5 @key{RET} 1000 I b F}. Note that the rate is expressed
+as a number between 0 and 1, @emph{not} as a percentage.
+
+@kindex H b F
+@tindex fvl
+The @kbd{H b F} [@code{fvl}] command computes the future value
+of an initial lump sum investment. Suppose you could deposit
+those five thousand dollars in the bank right now; how much would
+they be worth in five years? @code{fvl(5.4%, 5, 5000) = 6503.89}.
+
+The algebraic functions @code{fv} and @code{fvb} accept an optional
+fourth argument, which is used as an initial lump sum in the sense
+of @code{fvl}. In other words, @code{fv(@var{rate}, @var{n},
+@var{payment}, @var{initial}) = fv(@var{rate}, @var{n}, @var{payment})
++ fvl(@var{rate}, @var{n}, @var{initial})}.
+
+To illustrate the relationships between these functions, we could
+do the @code{fvb} calculation ``by hand'' using @code{fvl}. The
+final balance will be the sum of the contributions of our five
+deposits at various times. The first deposit earns interest for
+five years: @code{fvl(5.4%, 5, 1000) = 1300.78}. The second
+deposit only earns interest for four years: @code{fvl(5.4%, 4, 1000) =
+1234.13}. And so on down to the last deposit, which earns one
+year's interest: @code{fvl(5.4%, 1, 1000) = 1054.00}. The sum of
+these five values is, sure enough, $5870.73, just as was computed
+by @code{fvb} directly.
+
+What does @code{fv(5.4%, 5, 1000) = 5569.96} mean? The payments
+are now at the ends of the periods. The end of one year is the same
+as the beginning of the next, so what this really means is that we've
+lost the payment at year zero (which contributed $1300.78), but we're
+now counting the payment at year five (which, since it didn't have
+a chance to earn interest, counts as $1000). Indeed, @expr{5569.96 =
+5870.73 - 1300.78 + 1000} (give or take a bit of roundoff error).
+
+@node Present Value, Related Financial Functions, Future Value, Financial Functions
+@subsection Present Value
+
+@noindent
+@kindex b P
+@pindex calc-fin-pv
+@tindex pv
+The @kbd{b P} (@code{calc-fin-pv}) [@code{pv}] command computes
+the present value of an investment. Like @code{fv}, it takes
+three arguments: @code{pv(@var{rate}, @var{n}, @var{payment})}.
+It computes the present value of a series of regular payments.
+Suppose you have the chance to make an investment that will
+pay $2000 per year over the next four years; as you receive
+these payments you can put them in the bank at 9% interest.
+You want to know whether it is better to make the investment, or
+to keep the money in the bank where it earns 9% interest right
+from the start. The calculation @code{pv(9%, 4, 2000)} gives the
+result 6479.44. If your initial investment must be less than this,
+say, $6000, then the investment is worthwhile. But if you had to
+put up $7000, then it would be better just to leave it in the bank.
+
+Here is the interpretation of the result of @code{pv}: You are
+trying to compare the return from the investment you are
+considering, which is @code{fv(9%, 4, 2000) = 9146.26}, with
+the return from leaving the money in the bank, which is
+@code{fvl(9%, 4, @var{x})} where @var{x} is the amount of money
+you would have to put up in advance. The @code{pv} function
+finds the break-even point, @expr{x = 6479.44}, at which
+@code{fvl(9%, 4, 6479.44)} is also equal to 9146.26. This is
+the largest amount you should be willing to invest.
+
+@kindex I b P
+@tindex pvb
+The @kbd{I b P} [@code{pvb}] command solves the same problem,
+but with payments occurring at the beginning of each interval.
+It has the same relationship to @code{fvb} as @code{pv} has
+to @code{fv}. For example @code{pvb(9%, 4, 2000) = 7062.59},
+a larger number than @code{pv} produced because we get to start
+earning interest on the return from our investment sooner.
+
+@kindex H b P
+@tindex pvl
+The @kbd{H b P} [@code{pvl}] command computes the present value of
+an investment that will pay off in one lump sum at the end of the
+period. For example, if we get our $8000 all at the end of the
+four years, @code{pvl(9%, 4, 8000) = 5667.40}. This is much
+less than @code{pv} reported, because we don't earn any interest
+on the return from this investment. Note that @code{pvl} and
+@code{fvl} are simple inverses: @code{fvl(9%, 4, 5667.40) = 8000}.
+
+You can give an optional fourth lump-sum argument to @code{pv}
+and @code{pvb}; this is handled in exactly the same way as the
+fourth argument for @code{fv} and @code{fvb}.
+
+@kindex b N
+@pindex calc-fin-npv
+@tindex npv
+The @kbd{b N} (@code{calc-fin-npv}) [@code{npv}] command computes
+the net present value of a series of irregular investments.
+The first argument is the interest rate. The second argument is
+a vector which represents the expected return from the investment
+at the end of each interval. For example, if the rate represents
+a yearly interest rate, then the vector elements are the return
+from the first year, second year, and so on.
+
+Thus, @code{npv(9%, [2000,2000,2000,2000]) = pv(9%, 4, 2000) = 6479.44}.
+Obviously this function is more interesting when the payments are
+not all the same!
+
+The @code{npv} function can actually have two or more arguments.
+Multiple arguments are interpreted in the same way as for the
+vector statistical functions like @code{vsum}.
+@xref{Single-Variable Statistics}. Basically, if there are several
+payment arguments, each either a vector or a plain number, all these
+values are collected left-to-right into the complete list of payments.
+A numeric prefix argument on the @kbd{b N} command says how many
+payment values or vectors to take from the stack.
+
+@kindex I b N
+@tindex npvb
+The @kbd{I b N} [@code{npvb}] command computes the net present
+value where payments occur at the beginning of each interval
+rather than at the end.
+
+@node Related Financial Functions, Depreciation Functions, Present Value, Financial Functions
+@subsection Related Financial Functions
+
+@noindent
+The functions in this section are basically inverses of the
+present value functions with respect to the various arguments.
+
+@kindex b M
+@pindex calc-fin-pmt
+@tindex pmt
+The @kbd{b M} (@code{calc-fin-pmt}) [@code{pmt}] command computes
+the amount of periodic payment necessary to amortize a loan.
+Thus @code{pmt(@var{rate}, @var{n}, @var{amount})} equals the
+value of @var{payment} such that @code{pv(@var{rate}, @var{n},
+@var{payment}) = @var{amount}}.
+
+@kindex I b M
+@tindex pmtb
+The @kbd{I b M} [@code{pmtb}] command does the same computation
+but using @code{pvb} instead of @code{pv}. Like @code{pv} and
+@code{pvb}, these functions can also take a fourth argument which
+represents an initial lump-sum investment.
+
+@kindex H b M
+The @kbd{H b M} key just invokes the @code{fvl} function, which is
+the inverse of @code{pvl}. There is no explicit @code{pmtl} function.
+
+@kindex b #
+@pindex calc-fin-nper
+@tindex nper
+The @kbd{b #} (@code{calc-fin-nper}) [@code{nper}] command computes
+the number of regular payments necessary to amortize a loan.
+Thus @code{nper(@var{rate}, @var{payment}, @var{amount})} equals
+the value of @var{n} such that @code{pv(@var{rate}, @var{n},
+@var{payment}) = @var{amount}}. If @var{payment} is too small
+ever to amortize a loan for @var{amount} at interest rate @var{rate},
+the @code{nper} function is left in symbolic form.
+
+@kindex I b #
+@tindex nperb
+The @kbd{I b #} [@code{nperb}] command does the same computation
+but using @code{pvb} instead of @code{pv}. You can give a fourth
+lump-sum argument to these functions, but the computation will be
+rather slow in the four-argument case.
+
+@kindex H b #
+@tindex nperl
+The @kbd{H b #} [@code{nperl}] command does the same computation
+using @code{pvl}. By exchanging @var{payment} and @var{amount} you
+can also get the solution for @code{fvl}. For example,
+@code{nperl(8%, 2000, 1000) = 9.006}, so if you place $1000 in a
+bank account earning 8%, it will take nine years to grow to $2000.
+
+@kindex b T
+@pindex calc-fin-rate
+@tindex rate
+The @kbd{b T} (@code{calc-fin-rate}) [@code{rate}] command computes
+the rate of return on an investment. This is also an inverse of @code{pv}:
+@code{rate(@var{n}, @var{payment}, @var{amount})} computes the value of
+@var{rate} such that @code{pv(@var{rate}, @var{n}, @var{payment}) =
+@var{amount}}. The result is expressed as a formula like @samp{6.3%}.
+
+@kindex I b T
+@kindex H b T
+@tindex rateb
+@tindex ratel
+The @kbd{I b T} [@code{rateb}] and @kbd{H b T} [@code{ratel}]
+commands solve the analogous equations with @code{pvb} or @code{pvl}
+in place of @code{pv}. Also, @code{rate} and @code{rateb} can
+accept an optional fourth argument just like @code{pv} and @code{pvb}.
+To redo the above example from a different perspective,
+@code{ratel(9, 2000, 1000) = 8.00597%}, which says you will need an
+interest rate of 8% in order to double your account in nine years.
+
+@kindex b I
+@pindex calc-fin-irr
+@tindex irr
+The @kbd{b I} (@code{calc-fin-irr}) [@code{irr}] command is the
+analogous function to @code{rate} but for net present value.
+Its argument is a vector of payments. Thus @code{irr(@var{payments})}
+computes the @var{rate} such that @code{npv(@var{rate}, @var{payments}) = 0};
+this rate is known as the @dfn{internal rate of return}.
+
+@kindex I b I
+@tindex irrb
+The @kbd{I b I} [@code{irrb}] command computes the internal rate of
+return assuming payments occur at the beginning of each period.
+
+@node Depreciation Functions, Definitions of Financial Functions, Related Financial Functions, Financial Functions
+@subsection Depreciation Functions
+
+@noindent
+The functions in this section calculate @dfn{depreciation}, which is
+the amount of value that a possession loses over time. These functions
+are characterized by three parameters: @var{cost}, the original cost
+of the asset; @var{salvage}, the value the asset will have at the end
+of its expected ``useful life''; and @var{life}, the number of years
+(or other periods) of the expected useful life.
+
+There are several methods for calculating depreciation that differ in
+the way they spread the depreciation over the lifetime of the asset.
+
+@kindex b S
+@pindex calc-fin-sln
+@tindex sln
+The @kbd{b S} (@code{calc-fin-sln}) [@code{sln}] command computes the
+``straight-line'' depreciation. In this method, the asset depreciates
+by the same amount every year (or period). For example,
+@samp{sln(12000, 2000, 5)} returns 2000. The asset costs $12000
+initially and will be worth $2000 after five years; it loses $2000
+per year.
+
+@kindex b Y
+@pindex calc-fin-syd
+@tindex syd
+The @kbd{b Y} (@code{calc-fin-syd}) [@code{syd}] command computes the
+accelerated ``sum-of-years'-digits'' depreciation. Here the depreciation
+is higher during the early years of the asset's life. Since the
+depreciation is different each year, @kbd{b Y} takes a fourth @var{period}
+parameter which specifies which year is requested, from 1 to @var{life}.
+If @var{period} is outside this range, the @code{syd} function will
+return zero.
+
+@kindex b D
+@pindex calc-fin-ddb
+@tindex ddb
+The @kbd{b D} (@code{calc-fin-ddb}) [@code{ddb}] command computes an
+accelerated depreciation using the double-declining balance method.
+It also takes a fourth @var{period} parameter.
+
+For symmetry, the @code{sln} function will accept a @var{period}
+parameter as well, although it will ignore its value except that the
+return value will as usual be zero if @var{period} is out of range.
+
+For example, pushing the vector @expr{[1,2,3,4,5]} (perhaps with @kbd{v x 5})
+and then mapping @kbd{V M ' [sln(12000,2000,5,$), syd(12000,2000,5,$),
+ddb(12000,2000,5,$)] @key{RET}} produces a matrix that allows us to compare
+the three depreciation methods:
+
+@example
+@group
+[ [ 2000, 3333, 4800 ]
+ [ 2000, 2667, 2880 ]
+ [ 2000, 2000, 1728 ]
+ [ 2000, 1333, 592 ]
+ [ 2000, 667, 0 ] ]
+@end group
+@end example
+
+@noindent
+(Values have been rounded to nearest integers in this figure.)
+We see that @code{sln} depreciates by the same amount each year,
+@kbd{syd} depreciates more at the beginning and less at the end,
+and @kbd{ddb} weights the depreciation even more toward the beginning.
+
+Summing columns with @kbd{V R : +} yields @expr{[10000, 10000, 10000]};
+the total depreciation in any method is (by definition) the
+difference between the cost and the salvage value.
+
+@node Definitions of Financial Functions, , Depreciation Functions, Financial Functions
+@subsection Definitions
+
+@noindent
+For your reference, here are the actual formulas used to compute
+Calc's financial functions.
+
+Calc will not evaluate a financial function unless the @var{rate} or
+@var{n} argument is known. However, @var{payment} or @var{amount} can
+be a variable. Calc expands these functions according to the
+formulas below for symbolic arguments only when you use the @kbd{a "}
+(@code{calc-expand-formula}) command, or when taking derivatives or
+integrals or solving equations involving the functions.
+
+@ifnottex
+These formulas are shown using the conventions of Big display
+mode (@kbd{d B}); for example, the formula for @code{fv} written
+linearly is @samp{pmt * ((1 + rate)^n) - 1) / rate}.
+
+@example
+ n
+ (1 + rate) - 1
+fv(rate, n, pmt) = pmt * ---------------
+ rate
+
+ n
+ ((1 + rate) - 1) (1 + rate)
+fvb(rate, n, pmt) = pmt * ----------------------------
+ rate
+
+ n
+fvl(rate, n, pmt) = pmt * (1 + rate)
+
+ -n
+ 1 - (1 + rate)
+pv(rate, n, pmt) = pmt * ----------------
+ rate
+
+ -n
+ (1 - (1 + rate) ) (1 + rate)
+pvb(rate, n, pmt) = pmt * -----------------------------
+ rate
+
+ -n
+pvl(rate, n, pmt) = pmt * (1 + rate)
+
+ -1 -2 -3
+npv(rate, [a, b, c]) = a*(1 + rate) + b*(1 + rate) + c*(1 + rate)
+
+ -1 -2
+npvb(rate, [a, b, c]) = a + b*(1 + rate) + c*(1 + rate)
+
+ -n
+ (amt - x * (1 + rate) ) * rate
+pmt(rate, n, amt, x) = -------------------------------
+ -n
+ 1 - (1 + rate)
+
+ -n
+ (amt - x * (1 + rate) ) * rate
+pmtb(rate, n, amt, x) = -------------------------------
+ -n
+ (1 - (1 + rate) ) (1 + rate)
+
+ amt * rate
+nper(rate, pmt, amt) = - log(1 - ------------, 1 + rate)
+ pmt
+
+ amt * rate
+nperb(rate, pmt, amt) = - log(1 - ---------------, 1 + rate)
+ pmt * (1 + rate)
+
+ amt
+nperl(rate, pmt, amt) = - log(---, 1 + rate)
+ pmt
+
+ 1/n
+ pmt
+ratel(n, pmt, amt) = ------ - 1
+ 1/n
+ amt
+
+ cost - salv
+sln(cost, salv, life) = -----------
+ life
+
+ (cost - salv) * (life - per + 1)
+syd(cost, salv, life, per) = --------------------------------
+ life * (life + 1) / 2
+
+ book * 2
+ddb(cost, salv, life, per) = --------, book = cost - depreciation so far
+ life
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+$$ \code{fv}(r, n, p) = p { (1 + r)^n - 1 \over r } $$
+$$ \code{fvb}(r, n, p) = p { ((1 + r)^n - 1) (1 + r) \over r } $$
+$$ \code{fvl}(r, n, p) = p (1 + r)^n $$
+$$ \code{pv}(r, n, p) = p { 1 - (1 + r)^{-n} \over r } $$
+$$ \code{pvb}(r, n, p) = p { (1 - (1 + r)^{-n}) (1 + r) \over r } $$
+$$ \code{pvl}(r, n, p) = p (1 + r)^{-n} $$
+$$ \code{npv}(r, [a,b,c]) = a (1 + r)^{-1} + b (1 + r)^{-2} + c (1 + r)^{-3} $$
+$$ \code{npvb}(r, [a,b,c]) = a + b (1 + r)^{-1} + c (1 + r)^{-2} $$
+$$ \code{pmt}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over 1 - (1 + r)^{-n} }$$
+$$ \code{pmtb}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over
+ (1 - (1 + r)^{-n}) (1 + r) } $$
+$$ \code{nper}(r, p, a) = -\code{log}(1 - { a r \over p }, 1 + r) $$
+$$ \code{nperb}(r, p, a) = -\code{log}(1 - { a r \over p (1 + r) }, 1 + r) $$
+$$ \code{nperl}(r, p, a) = -\code{log}({a \over p}, 1 + r) $$
+$$ \code{ratel}(n, p, a) = { p^{1/n} \over a^{1/n} } - 1 $$
+$$ \code{sln}(c, s, l) = { c - s \over l } $$
+$$ \code{syd}(c, s, l, p) = { (c - s) (l - p + 1) \over l (l+1) / 2 } $$
+$$ \code{ddb}(c, s, l, p) = { 2 (c - \hbox{depreciation so far}) \over l } $$
+@end tex
+
+@noindent
+In @code{pmt} and @code{pmtb}, @expr{x=0} if omitted.
+
+These functions accept any numeric objects, including error forms,
+intervals, and even (though not very usefully) complex numbers. The
+above formulas specify exactly the behavior of these functions with
+all sorts of inputs.
+
+Note that if the first argument to the @code{log} in @code{nper} is
+negative, @code{nper} leaves itself in symbolic form rather than
+returning a (financially meaningless) complex number.
+
+@samp{rate(num, pmt, amt)} solves the equation
+@samp{pv(rate, num, pmt) = amt} for @samp{rate} using @kbd{H a R}
+(@code{calc-find-root}), with the interval @samp{[.01% .. 100%]}
+for an initial guess. The @code{rateb} function is the same except
+that it uses @code{pvb}. Note that @code{ratel} can be solved
+directly; its formula is shown in the above list.
+
+Similarly, @samp{irr(pmts)} solves the equation @samp{npv(rate, pmts) = 0}
+for @samp{rate}.
+
+If you give a fourth argument to @code{nper} or @code{nperb}, Calc
+will also use @kbd{H a R} to solve the equation using an initial
+guess interval of @samp{[0 .. 100]}.
+
+A fourth argument to @code{fv} simply sums the two components
+calculated from the above formulas for @code{fv} and @code{fvl}.
+The same is true of @code{fvb}, @code{pv}, and @code{pvb}.
+
+The @kbd{ddb} function is computed iteratively; the ``book'' value
+starts out equal to @var{cost}, and decreases according to the above
+formula for the specified number of periods. If the book value
+would decrease below @var{salvage}, it only decreases to @var{salvage}
+and the depreciation is zero for all subsequent periods. The @code{ddb}
+function returns the amount the book value decreased in the specified
+period.
+
+@node Binary Functions, , Financial Functions, Arithmetic
+@section Binary Number Functions
+
+@noindent
+The commands in this chapter all use two-letter sequences beginning with
+the @kbd{b} prefix.
+
+@cindex Binary numbers
+The ``binary'' operations actually work regardless of the currently
+displayed radix, although their results make the most sense in a radix
+like 2, 8, or 16 (as obtained by the @kbd{d 2}, @kbd{d 8}, or @w{@kbd{d 6}}
+commands, respectively). You may also wish to enable display of leading
+zeros with @kbd{d z}. @xref{Radix Modes}.
+
+@cindex Word size for binary operations
+The Calculator maintains a current @dfn{word size} @expr{w}, an
+arbitrary positive or negative integer. For a positive word size, all
+of the binary operations described here operate modulo @expr{2^w}. In
+particular, negative arguments are converted to positive integers modulo
+@expr{2^w} by all binary functions.
+
+If the word size is negative, binary operations produce 2's complement
+integers from
+@texline @math{-2^{-w-1}}
+@infoline @expr{-(2^(-w-1))}
+to
+@texline @math{2^{-w-1}-1}
+@infoline @expr{2^(-w-1)-1}
+inclusive. Either mode accepts inputs in any range; the sign of
+@expr{w} affects only the results produced.
+
+@kindex b c
+@pindex calc-clip
+@tindex clip
+The @kbd{b c} (@code{calc-clip})
+[@code{clip}] command can be used to clip a number by reducing it modulo
+@expr{2^w}. The commands described in this chapter automatically clip
+their results to the current word size. Note that other operations like
+addition do not use the current word size, since integer addition
+generally is not ``binary.'' (However, @pxref{Simplification Modes},
+@code{calc-bin-simplify-mode}.) For example, with a word size of 8
+bits @kbd{b c} converts a number to the range 0 to 255; with a word
+size of @mathit{-8} @kbd{b c} converts to the range @mathit{-128} to 127.
+
+@kindex b w
+@pindex calc-word-size
+The default word size is 32 bits. All operations except the shifts and
+rotates allow you to specify a different word size for that one
+operation by giving a numeric prefix argument: @kbd{C-u 8 b c} clips the
+top of stack to the range 0 to 255 regardless of the current word size.
+To set the word size permanently, use @kbd{b w} (@code{calc-word-size}).
+This command displays a prompt with the current word size; press @key{RET}
+immediately to keep this word size, or type a new word size at the prompt.
+
+When the binary operations are written in symbolic form, they take an
+optional second (or third) word-size parameter. When a formula like
+@samp{and(a,b)} is finally evaluated, the word size current at that time
+will be used, but when @samp{and(a,b,-8)} is evaluated, a word size of
+@mathit{-8} will always be used. A symbolic binary function will be left
+in symbolic form unless the all of its argument(s) are integers or
+integer-valued floats.
+
+If either or both arguments are modulo forms for which @expr{M} is a
+power of two, that power of two is taken as the word size unless a
+numeric prefix argument overrides it. The current word size is never
+consulted when modulo-power-of-two forms are involved.
+
+@kindex b a
+@pindex calc-and
+@tindex and
+The @kbd{b a} (@code{calc-and}) [@code{and}] command computes the bitwise
+AND of the two numbers on the top of the stack. In other words, for each
+of the @expr{w} binary digits of the two numbers (pairwise), the corresponding
+bit of the result is 1 if and only if both input bits are 1:
+@samp{and(2#1100, 2#1010) = 2#1000}.
+
+@kindex b o
+@pindex calc-or
+@tindex or
+The @kbd{b o} (@code{calc-or}) [@code{or}] command computes the bitwise
+inclusive OR of two numbers. A bit is 1 if either of the input bits, or
+both, are 1: @samp{or(2#1100, 2#1010) = 2#1110}.
+
+@kindex b x
+@pindex calc-xor
+@tindex xor
+The @kbd{b x} (@code{calc-xor}) [@code{xor}] command computes the bitwise
+exclusive OR of two numbers. A bit is 1 if exactly one of the input bits
+is 1: @samp{xor(2#1100, 2#1010) = 2#0110}.
+
+@kindex b d
+@pindex calc-diff
+@tindex diff
+The @kbd{b d} (@code{calc-diff}) [@code{diff}] command computes the bitwise
+difference of two numbers; this is defined by @samp{diff(a,b) = and(a,not(b))},
+so that @samp{diff(2#1100, 2#1010) = 2#0100}.
+
+@kindex b n
+@pindex calc-not
+@tindex not
+The @kbd{b n} (@code{calc-not}) [@code{not}] command computes the bitwise
+NOT of a number. A bit is 1 if the input bit is 0 and vice-versa.
+
+@kindex b l
+@pindex calc-lshift-binary
+@tindex lsh
+The @kbd{b l} (@code{calc-lshift-binary}) [@code{lsh}] command shifts a
+number left by one bit, or by the number of bits specified in the numeric
+prefix argument. A negative prefix argument performs a logical right shift,
+in which zeros are shifted in on the left. In symbolic form, @samp{lsh(a)}
+is short for @samp{lsh(a,1)}, which in turn is short for @samp{lsh(a,n,w)}.
+Bits shifted ``off the end,'' according to the current word size, are lost.
+
+@kindex H b l
+@kindex H b r
+@ignore
+@mindex @idots
+@end ignore
+@kindex H b L
+@ignore
+@mindex @null
+@end ignore
+@kindex H b R
+@ignore
+@mindex @null
+@end ignore
+@kindex H b t
+The @kbd{H b l} command also does a left shift, but it takes two arguments
+from the stack (the value to shift, and, at top-of-stack, the number of
+bits to shift). This version interprets the prefix argument just like
+the regular binary operations, i.e., as a word size. The Hyperbolic flag
+has a similar effect on the rest of the binary shift and rotate commands.
+
+@kindex b r
+@pindex calc-rshift-binary
+@tindex rsh
+The @kbd{b r} (@code{calc-rshift-binary}) [@code{rsh}] command shifts a
+number right by one bit, or by the number of bits specified in the numeric
+prefix argument: @samp{rsh(a,n) = lsh(a,-n)}.
+
+@kindex b L
+@pindex calc-lshift-arith
+@tindex ash
+The @kbd{b L} (@code{calc-lshift-arith}) [@code{ash}] command shifts a
+number left. It is analogous to @code{lsh}, except that if the shift
+is rightward (the prefix argument is negative), an arithmetic shift
+is performed as described below.
+
+@kindex b R
+@pindex calc-rshift-arith
+@tindex rash
+The @kbd{b R} (@code{calc-rshift-arith}) [@code{rash}] command performs
+an ``arithmetic'' shift to the right, in which the leftmost bit (according
+to the current word size) is duplicated rather than shifting in zeros.
+This corresponds to dividing by a power of two where the input is interpreted
+as a signed, twos-complement number. (The distinction between the @samp{rsh}
+and @samp{rash} operations is totally independent from whether the word
+size is positive or negative.) With a negative prefix argument, this
+performs a standard left shift.
+
+@kindex b t
+@pindex calc-rotate-binary
+@tindex rot
+The @kbd{b t} (@code{calc-rotate-binary}) [@code{rot}] command rotates a
+number one bit to the left. The leftmost bit (according to the current
+word size) is dropped off the left and shifted in on the right. With a
+numeric prefix argument, the number is rotated that many bits to the left
+or right.
+
+@xref{Set Operations}, for the @kbd{b p} and @kbd{b u} commands that
+pack and unpack binary integers into sets. (For example, @kbd{b u}
+unpacks the number @samp{2#11001} to the set of bit-numbers
+@samp{[0, 3, 4]}.) Type @kbd{b u V #} to count the number of ``1''
+bits in a binary integer.
+
+Another interesting use of the set representation of binary integers
+is to reverse the bits in, say, a 32-bit integer. Type @kbd{b u} to
+unpack; type @kbd{31 @key{TAB} -} to replace each bit-number in the set
+with 31 minus that bit-number; type @kbd{b p} to pack the set back
+into a binary integer.
+
+@node Scientific Functions, Matrix Functions, Arithmetic, Top
+@chapter Scientific Functions
+
+@noindent
+The functions described here perform trigonometric and other transcendental
+calculations. They generally produce floating-point answers correct to the
+full current precision. The @kbd{H} (Hyperbolic) and @kbd{I} (Inverse)
+flag keys must be used to get some of these functions from the keyboard.
+
+@kindex P
+@pindex calc-pi
+@cindex @code{pi} variable
+@vindex pi
+@kindex H P
+@cindex @code{e} variable
+@vindex e
+@kindex I P
+@cindex @code{gamma} variable
+@vindex gamma
+@cindex Gamma constant, Euler's
+@cindex Euler's gamma constant
+@kindex H I P
+@cindex @code{phi} variable
+@cindex Phi, golden ratio
+@cindex Golden ratio
+One miscellaneous command is shift-@kbd{P} (@code{calc-pi}), which pushes
+the value of @cpi{} (at the current precision) onto the stack. With the
+Hyperbolic flag, it pushes the value @expr{e}, the base of natural logarithms.
+With the Inverse flag, it pushes Euler's constant
+@texline @math{\gamma}
+@infoline @expr{gamma}
+(about 0.5772). With both Inverse and Hyperbolic, it
+pushes the ``golden ratio''
+@texline @math{\phi}
+@infoline @expr{phi}
+(about 1.618). (At present, Euler's constant is not available
+to unlimited precision; Calc knows only the first 100 digits.)
+In Symbolic mode, these commands push the
+actual variables @samp{pi}, @samp{e}, @samp{gamma}, and @samp{phi},
+respectively, instead of their values; @pxref{Symbolic Mode}.
+
+@ignore
+@mindex Q
+@end ignore
+@ignore
+@mindex I Q
+@end ignore
+@kindex I Q
+@tindex sqr
+The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] function is described elsewhere;
+@pxref{Basic Arithmetic}. With the Inverse flag [@code{sqr}], this command
+computes the square of the argument.
+
+@xref{Prefix Arguments}, for a discussion of the effect of numeric
+prefix arguments on commands in this chapter which do not otherwise
+interpret a prefix argument.
+
+@menu
+* Logarithmic Functions::
+* Trigonometric and Hyperbolic Functions::
+* Advanced Math Functions::
+* Branch Cuts::
+* Random Numbers::
+* Combinatorial Functions::
+* Probability Distribution Functions::
+@end menu
+
+@node Logarithmic Functions, Trigonometric and Hyperbolic Functions, Scientific Functions, Scientific Functions
+@section Logarithmic Functions
+
+@noindent
+@kindex L
+@pindex calc-ln
+@tindex ln
+@ignore
+@mindex @null
+@end ignore
+@kindex I E
+The shift-@kbd{L} (@code{calc-ln}) [@code{ln}] command computes the natural
+logarithm of the real or complex number on the top of the stack. With
+the Inverse flag it computes the exponential function instead, although
+this is redundant with the @kbd{E} command.
+
+@kindex E
+@pindex calc-exp
+@tindex exp
+@ignore
+@mindex @null
+@end ignore
+@kindex I L
+The shift-@kbd{E} (@code{calc-exp}) [@code{exp}] command computes the
+exponential, i.e., @expr{e} raised to the power of the number on the stack.
+The meanings of the Inverse and Hyperbolic flags follow from those for
+the @code{calc-ln} command.
+
+@kindex H L
+@kindex H E
+@pindex calc-log10
+@tindex log10
+@tindex exp10
+@ignore
+@mindex @null
+@end ignore
+@kindex H I L
+@ignore
+@mindex @null
+@end ignore
+@kindex H I E
+The @kbd{H L} (@code{calc-log10}) [@code{log10}] command computes the common
+(base-10) logarithm of a number. (With the Inverse flag [@code{exp10}],
+it raises ten to a given power.) Note that the common logarithm of a
+complex number is computed by taking the natural logarithm and dividing
+by
+@texline @math{\ln10}.
+@infoline @expr{ln(10)}.
+
+@kindex B
+@kindex I B
+@pindex calc-log
+@tindex log
+@tindex alog
+The @kbd{B} (@code{calc-log}) [@code{log}] command computes a logarithm
+to any base. For example, @kbd{1024 @key{RET} 2 B} produces 10, since
+@texline @math{2^{10} = 1024}.
+@infoline @expr{2^10 = 1024}.
+In certain cases like @samp{log(3,9)}, the result
+will be either @expr{1:2} or @expr{0.5} depending on the current Fraction
+mode setting. With the Inverse flag [@code{alog}], this command is
+similar to @kbd{^} except that the order of the arguments is reversed.
+
+@kindex f I
+@pindex calc-ilog
+@tindex ilog
+The @kbd{f I} (@code{calc-ilog}) [@code{ilog}] command computes the
+integer logarithm of a number to any base. The number and the base must
+themselves be positive integers. This is the true logarithm, rounded
+down to an integer. Thus @kbd{ilog(x,10)} is 3 for all @expr{x} in the
+range from 1000 to 9999. If both arguments are positive integers, exact
+integer arithmetic is used; otherwise, this is equivalent to
+@samp{floor(log(x,b))}.
+
+@kindex f E
+@pindex calc-expm1
+@tindex expm1
+The @kbd{f E} (@code{calc-expm1}) [@code{expm1}] command computes
+@texline @math{e^x - 1},
+@infoline @expr{exp(x)-1},
+but using an algorithm that produces a more accurate
+answer when the result is close to zero, i.e., when
+@texline @math{e^x}
+@infoline @expr{exp(x)}
+is close to one.
+
+@kindex f L
+@pindex calc-lnp1
+@tindex lnp1
+The @kbd{f L} (@code{calc-lnp1}) [@code{lnp1}] command computes
+@texline @math{\ln(x+1)},
+@infoline @expr{ln(x+1)},
+producing a more accurate answer when @expr{x} is close to zero.
+
+@node Trigonometric and Hyperbolic Functions, Advanced Math Functions, Logarithmic Functions, Scientific Functions
+@section Trigonometric/Hyperbolic Functions
+
+@noindent
+@kindex S
+@pindex calc-sin
+@tindex sin
+The shift-@kbd{S} (@code{calc-sin}) [@code{sin}] command computes the sine
+of an angle or complex number. If the input is an HMS form, it is interpreted
+as degrees-minutes-seconds; otherwise, the input is interpreted according
+to the current angular mode. It is best to use Radians mode when operating
+on complex numbers.
+
+Calc's ``units'' mechanism includes angular units like @code{deg},
+@code{rad}, and @code{grad}. While @samp{sin(45 deg)} is not evaluated
+all the time, the @kbd{u s} (@code{calc-simplify-units}) command will
+simplify @samp{sin(45 deg)} by taking the sine of 45 degrees, regardless
+of the current angular mode. @xref{Basic Operations on Units}.
+
+Also, the symbolic variable @code{pi} is not ordinarily recognized in
+arguments to trigonometric functions, as in @samp{sin(3 pi / 4)}, but
+the @kbd{a s} (@code{calc-simplify}) command recognizes many such
+formulas when the current angular mode is Radians @emph{and} Symbolic
+mode is enabled; this example would be replaced by @samp{sqrt(2) / 2}.
+@xref{Symbolic Mode}. Beware, this simplification occurs even if you
+have stored a different value in the variable @samp{pi}; this is one
+reason why changing built-in variables is a bad idea. Arguments of
+the form @expr{x} plus a multiple of @cpiover{2} are also simplified.
+Calc includes similar formulas for @code{cos} and @code{tan}.
+
+The @kbd{a s} command knows all angles which are integer multiples of
+@cpiover{12}, @cpiover{10}, or @cpiover{8} radians. In Degrees mode,
+analogous simplifications occur for integer multiples of 15 or 18
+degrees, and for arguments plus multiples of 90 degrees.
+
+@kindex I S
+@pindex calc-arcsin
+@tindex arcsin
+With the Inverse flag, @code{calc-sin} computes an arcsine. This is also
+available as the @code{calc-arcsin} command or @code{arcsin} algebraic
+function. The returned argument is converted to degrees, radians, or HMS
+notation depending on the current angular mode.
+
+@kindex H S
+@pindex calc-sinh
+@tindex sinh
+@kindex H I S
+@pindex calc-arcsinh
+@tindex arcsinh
+With the Hyperbolic flag, @code{calc-sin} computes the hyperbolic
+sine, also available as @code{calc-sinh} [@code{sinh}]. With the
+Hyperbolic and Inverse flags, it computes the hyperbolic arcsine
+(@code{calc-arcsinh}) [@code{arcsinh}].
+
+@kindex C
+@pindex calc-cos
+@tindex cos
+@ignore
+@mindex @idots
+@end ignore
+@kindex I C
+@pindex calc-arccos
+@ignore
+@mindex @null
+@end ignore
+@tindex arccos
+@ignore
+@mindex @null
+@end ignore
+@kindex H C
+@pindex calc-cosh
+@ignore
+@mindex @null
+@end ignore
+@tindex cosh
+@ignore
+@mindex @null
+@end ignore
+@kindex H I C
+@pindex calc-arccosh
+@ignore
+@mindex @null
+@end ignore
+@tindex arccosh
+@ignore
+@mindex @null
+@end ignore
+@kindex T
+@pindex calc-tan
+@ignore
+@mindex @null
+@end ignore
+@tindex tan
+@ignore
+@mindex @null
+@end ignore
+@kindex I T
+@pindex calc-arctan
+@ignore
+@mindex @null
+@end ignore
+@tindex arctan
+@ignore
+@mindex @null
+@end ignore
+@kindex H T
+@pindex calc-tanh
+@ignore
+@mindex @null
+@end ignore
+@tindex tanh
+@ignore
+@mindex @null
+@end ignore
+@kindex H I T
+@pindex calc-arctanh
+@ignore
+@mindex @null
+@end ignore
+@tindex arctanh
+The shift-@kbd{C} (@code{calc-cos}) [@code{cos}] command computes the cosine
+of an angle or complex number, and shift-@kbd{T} (@code{calc-tan}) [@code{tan}]
+computes the tangent, along with all the various inverse and hyperbolic
+variants of these functions.
+
+@kindex f T
+@pindex calc-arctan2
+@tindex arctan2
+The @kbd{f T} (@code{calc-arctan2}) [@code{arctan2}] command takes two
+numbers from the stack and computes the arc tangent of their ratio. The
+result is in the full range from @mathit{-180} (exclusive) to @mathit{+180}
+(inclusive) degrees, or the analogous range in radians. A similar
+result would be obtained with @kbd{/} followed by @kbd{I T}, but the
+value would only be in the range from @mathit{-90} to @mathit{+90} degrees
+since the division loses information about the signs of the two
+components, and an error might result from an explicit division by zero
+which @code{arctan2} would avoid. By (arbitrary) definition,
+@samp{arctan2(0,0)=0}.
+
+@pindex calc-sincos
+@ignore
+@starindex
+@end ignore
+@tindex sincos
+@ignore
+@starindex
+@end ignore
+@ignore
+@mindex arc@idots
+@end ignore
+@tindex arcsincos
+The @code{calc-sincos} [@code{sincos}] command computes the sine and
+cosine of a number, returning them as a vector of the form
+@samp{[@var{cos}, @var{sin}]}.
+With the Inverse flag [@code{arcsincos}], this command takes a two-element
+vector as an argument and computes @code{arctan2} of the elements.
+(This command does not accept the Hyperbolic flag.)
+
+@pindex calc-sec
+@tindex sec
+@pindex calc-csc
+@tindex csc
+@pindex calc-cot
+@tindex cot
+@pindex calc-sech
+@tindex sech
+@pindex calc-csch
+@tindex csch
+@pindex calc-coth
+@tindex coth
+The remaining trigonometric functions, @code{calc-sec} [@code{sec}],
+@code{calc-csc} [@code{csc}] and @code{calc-sec} [@code{sec}], are also
+available. With the Hyperbolic flag, these compute their hyperbolic
+counterparts, which are also available separately as @code{calc-sech}
+[@code{sech}], @code{calc-csch} [@code{csch}] and @code{calc-sech}
+[@code{sech}]. (These commmands do not accept the Inverse flag.)
+
+@node Advanced Math Functions, Branch Cuts, Trigonometric and Hyperbolic Functions, Scientific Functions
+@section Advanced Mathematical Functions
+
+@noindent
+Calc can compute a variety of less common functions that arise in
+various branches of mathematics. All of the functions described in
+this section allow arbitrary complex arguments and, except as noted,
+will work to arbitrarily large precisions. They can not at present
+handle error forms or intervals as arguments.
+
+NOTE: These functions are still experimental. In particular, their
+accuracy is not guaranteed in all domains. It is advisable to set the
+current precision comfortably higher than you actually need when
+using these functions. Also, these functions may be impractically
+slow for some values of the arguments.
+
+@kindex f g
+@pindex calc-gamma
+@tindex gamma
+The @kbd{f g} (@code{calc-gamma}) [@code{gamma}] command computes the Euler
+gamma function. For positive integer arguments, this is related to the
+factorial function: @samp{gamma(n+1) = fact(n)}. For general complex
+arguments the gamma function can be defined by the following definite
+integral:
+@texline @math{\Gamma(a) = \int_0^\infty t^{a-1} e^t dt}.
+@infoline @expr{gamma(a) = integ(t^(a-1) exp(t), t, 0, inf)}.
+(The actual implementation uses far more efficient computational methods.)
+
+@kindex f G
+@tindex gammaP
+@ignore
+@mindex @idots
+@end ignore
+@kindex I f G
+@ignore
+@mindex @null
+@end ignore
+@kindex H f G
+@ignore
+@mindex @null
+@end ignore
+@kindex H I f G
+@pindex calc-inc-gamma
+@ignore
+@mindex @null
+@end ignore
+@tindex gammaQ
+@ignore
+@mindex @null
+@end ignore
+@tindex gammag
+@ignore
+@mindex @null
+@end ignore
+@tindex gammaG
+The @kbd{f G} (@code{calc-inc-gamma}) [@code{gammaP}] command computes
+the incomplete gamma function, denoted @samp{P(a,x)}. This is defined by
+the integral,
+@texline @math{P(a,x) = \left( \int_0^x t^{a-1} e^t dt \right) / \Gamma(a)}.
+@infoline @expr{gammaP(a,x) = integ(t^(a-1) exp(t), t, 0, x) / gamma(a)}.
+This implies that @samp{gammaP(a,inf) = 1} for any @expr{a} (see the
+definition of the normal gamma function).
+
+Several other varieties of incomplete gamma function are defined.
+The complement of @expr{P(a,x)}, called @expr{Q(a,x) = 1-P(a,x)} by
+some authors, is computed by the @kbd{I f G} [@code{gammaQ}] command.
+You can think of this as taking the other half of the integral, from
+@expr{x} to infinity.
+
+@ifnottex
+The functions corresponding to the integrals that define @expr{P(a,x)}
+and @expr{Q(a,x)} but without the normalizing @expr{1/gamma(a)}
+factor are called @expr{g(a,x)} and @expr{G(a,x)}, respectively
+(where @expr{g} and @expr{G} represent the lower- and upper-case Greek
+letter gamma). You can obtain these using the @kbd{H f G} [@code{gammag}]
+and @kbd{H I f G} [@code{gammaG}] commands.
+@end ifnottex
+@tex
+\turnoffactive
+The functions corresponding to the integrals that define $P(a,x)$
+and $Q(a,x)$ but without the normalizing $1/\Gamma(a)$
+factor are called $\gamma(a,x)$ and $\Gamma(a,x)$, respectively.
+You can obtain these using the \kbd{H f G} [\code{gammag}] and
+\kbd{I H f G} [\code{gammaG}] commands.
+@end tex
+
+@kindex f b
+@pindex calc-beta
+@tindex beta
+The @kbd{f b} (@code{calc-beta}) [@code{beta}] command computes the
+Euler beta function, which is defined in terms of the gamma function as
+@texline @math{B(a,b) = \Gamma(a) \Gamma(b) / \Gamma(a+b)},
+@infoline @expr{beta(a,b) = gamma(a) gamma(b) / gamma(a+b)},
+or by
+@texline @math{B(a,b) = \int_0^1 t^{a-1} (1-t)^{b-1} dt}.
+@infoline @expr{beta(a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, 1)}.
+
+@kindex f B
+@kindex H f B
+@pindex calc-inc-beta
+@tindex betaI
+@tindex betaB
+The @kbd{f B} (@code{calc-inc-beta}) [@code{betaI}] command computes
+the incomplete beta function @expr{I(x,a,b)}. It is defined by
+@texline @math{I(x,a,b) = \left( \int_0^x t^{a-1} (1-t)^{b-1} dt \right) / B(a,b)}.
+@infoline @expr{betaI(x,a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, x) / beta(a,b)}.
+Once again, the @kbd{H} (hyperbolic) prefix gives the corresponding
+un-normalized version [@code{betaB}].
+
+@kindex f e
+@kindex I f e
+@pindex calc-erf
+@tindex erf
+@tindex erfc
+The @kbd{f e} (@code{calc-erf}) [@code{erf}] command computes the
+error function
+@texline @math{\hbox{erf}(x) = {2 \over \sqrt{\pi}} \int_0^x e^{-t^2} dt}.
+@infoline @expr{erf(x) = 2 integ(exp(-(t^2)), t, 0, x) / sqrt(pi)}.
+The complementary error function @kbd{I f e} (@code{calc-erfc}) [@code{erfc}]
+is the corresponding integral from @samp{x} to infinity; the sum
+@texline @math{\hbox{erf}(x) + \hbox{erfc}(x) = 1}.
+@infoline @expr{erf(x) + erfc(x) = 1}.
+
+@kindex f j
+@kindex f y
+@pindex calc-bessel-J
+@pindex calc-bessel-Y
+@tindex besJ
+@tindex besY
+The @kbd{f j} (@code{calc-bessel-J}) [@code{besJ}] and @kbd{f y}
+(@code{calc-bessel-Y}) [@code{besY}] commands compute the Bessel
+functions of the first and second kinds, respectively.
+In @samp{besJ(n,x)} and @samp{besY(n,x)} the ``order'' parameter
+@expr{n} is often an integer, but is not required to be one.
+Calc's implementation of the Bessel functions currently limits the
+precision to 8 digits, and may not be exact even to that precision.
+Use with care!
+
+@node Branch Cuts, Random Numbers, Advanced Math Functions, Scientific Functions
+@section Branch Cuts and Principal Values
+
+@noindent
+@cindex Branch cuts
+@cindex Principal values
+All of the logarithmic, trigonometric, and other scientific functions are
+defined for complex numbers as well as for reals.
+This section describes the values
+returned in cases where the general result is a family of possible values.
+Calc follows section 12.5.3 of Steele's @dfn{Common Lisp, the Language},
+second edition, in these matters. This section will describe each
+function briefly; for a more detailed discussion (including some nifty
+diagrams), consult Steele's book.
+
+Note that the branch cuts for @code{arctan} and @code{arctanh} were
+changed between the first and second editions of Steele. Versions of
+Calc starting with 2.00 follow the second edition.
+
+The new branch cuts exactly match those of the HP-28/48 calculators.
+They also match those of Mathematica 1.2, except that Mathematica's
+@code{arctan} cut is always in the right half of the complex plane,
+and its @code{arctanh} cut is always in the top half of the plane.
+Calc's cuts are continuous with quadrants I and III for @code{arctan},
+or II and IV for @code{arctanh}.
+
+Note: The current implementations of these functions with complex arguments
+are designed with proper behavior around the branch cuts in mind, @emph{not}
+efficiency or accuracy. You may need to increase the floating precision
+and wait a while to get suitable answers from them.
+
+For @samp{sqrt(a+bi)}: When @expr{a<0} and @expr{b} is small but positive
+or zero, the result is close to the @expr{+i} axis. For @expr{b} small and
+negative, the result is close to the @expr{-i} axis. The result always lies
+in the right half of the complex plane.
+
+For @samp{ln(a+bi)}: The real part is defined as @samp{ln(abs(a+bi))}.
+The imaginary part is defined as @samp{arg(a+bi) = arctan2(b,a)}.
+Thus the branch cuts for @code{sqrt} and @code{ln} both lie on the
+negative real axis.
+
+The following table describes these branch cuts in another way.
+If the real and imaginary parts of @expr{z} are as shown, then
+the real and imaginary parts of @expr{f(z)} will be as shown.
+Here @code{eps} stands for a small positive value; each
+occurrence of @code{eps} may stand for a different small value.
+
+@smallexample
+ z sqrt(z) ln(z)
+----------------------------------------
+ +, 0 +, 0 any, 0
+ -, 0 0, + any, pi
+ -, +eps +eps, + +eps, +
+ -, -eps +eps, - +eps, -
+@end smallexample
+
+For @samp{z1^z2}: This is defined by @samp{exp(ln(z1)*z2)}.
+One interesting consequence of this is that @samp{(-8)^1:3} does
+not evaluate to @mathit{-2} as you might expect, but to the complex
+number @expr{(1., 1.732)}. Both of these are valid cube roots
+of @mathit{-8} (as is @expr{(1., -1.732)}); Calc chooses a perhaps
+less-obvious root for the sake of mathematical consistency.
+
+For @samp{arcsin(z)}: This is defined by @samp{-i*ln(i*z + sqrt(1-z^2))}.
+The branch cuts are on the real axis, less than @mathit{-1} and greater than 1.
+
+For @samp{arccos(z)}: This is defined by @samp{-i*ln(z + i*sqrt(1-z^2))},
+or equivalently by @samp{pi/2 - arcsin(z)}. The branch cuts are on
+the real axis, less than @mathit{-1} and greater than 1.
+
+For @samp{arctan(z)}: This is defined by
+@samp{(ln(1+i*z) - ln(1-i*z)) / (2*i)}. The branch cuts are on the
+imaginary axis, below @expr{-i} and above @expr{i}.
+
+For @samp{arcsinh(z)}: This is defined by @samp{ln(z + sqrt(1+z^2))}.
+The branch cuts are on the imaginary axis, below @expr{-i} and
+above @expr{i}.
+
+For @samp{arccosh(z)}: This is defined by
+@samp{ln(z + (z+1)*sqrt((z-1)/(z+1)))}. The branch cut is on the
+real axis less than 1.
+
+For @samp{arctanh(z)}: This is defined by @samp{(ln(1+z) - ln(1-z)) / 2}.
+The branch cuts are on the real axis, less than @mathit{-1} and greater than 1.
+
+The following tables for @code{arcsin}, @code{arccos}, and
+@code{arctan} assume the current angular mode is Radians. The
+hyperbolic functions operate independently of the angular mode.
+
+@smallexample
+ z arcsin(z) arccos(z)
+-------------------------------------------------------
+ (-1..1), 0 (-pi/2..pi/2), 0 (0..pi), 0
+ (-1..1), +eps (-pi/2..pi/2), +eps (0..pi), -eps
+ (-1..1), -eps (-pi/2..pi/2), -eps (0..pi), +eps
+ <-1, 0 -pi/2, + pi, -
+ <-1, +eps -pi/2 + eps, + pi - eps, -
+ <-1, -eps -pi/2 + eps, - pi - eps, +
+ >1, 0 pi/2, - 0, +
+ >1, +eps pi/2 - eps, + +eps, -
+ >1, -eps pi/2 - eps, - +eps, +
+@end smallexample
+
+@smallexample
+ z arccosh(z) arctanh(z)
+-----------------------------------------------------
+ (-1..1), 0 0, (0..pi) any, 0
+ (-1..1), +eps +eps, (0..pi) any, +eps
+ (-1..1), -eps +eps, (-pi..0) any, -eps
+ <-1, 0 +, pi -, pi/2
+ <-1, +eps +, pi - eps -, pi/2 - eps
+ <-1, -eps +, -pi + eps -, -pi/2 + eps
+ >1, 0 +, 0 +, -pi/2
+ >1, +eps +, +eps +, pi/2 - eps
+ >1, -eps +, -eps +, -pi/2 + eps
+@end smallexample
+
+@smallexample
+ z arcsinh(z) arctan(z)
+-----------------------------------------------------
+ 0, (-1..1) 0, (-pi/2..pi/2) 0, any
+ 0, <-1 -, -pi/2 -pi/2, -
+ +eps, <-1 +, -pi/2 + eps pi/2 - eps, -
+ -eps, <-1 -, -pi/2 + eps -pi/2 + eps, -
+ 0, >1 +, pi/2 pi/2, +
+ +eps, >1 +, pi/2 - eps pi/2 - eps, +
+ -eps, >1 -, pi/2 - eps -pi/2 + eps, +
+@end smallexample
+
+Finally, the following identities help to illustrate the relationship
+between the complex trigonometric and hyperbolic functions. They
+are valid everywhere, including on the branch cuts.
+
+@smallexample
+sin(i*z) = i*sinh(z) arcsin(i*z) = i*arcsinh(z)
+cos(i*z) = cosh(z) arcsinh(i*z) = i*arcsin(z)
+tan(i*z) = i*tanh(z) arctan(i*z) = i*arctanh(z)
+sinh(i*z) = i*sin(z) cosh(i*z) = cos(z)
+@end smallexample
+
+The ``advanced math'' functions (gamma, Bessel, etc.@:) are also defined
+for general complex arguments, but their branch cuts and principal values
+are not rigorously specified at present.
+
+@node Random Numbers, Combinatorial Functions, Branch Cuts, Scientific Functions
+@section Random Numbers
+
+@noindent
+@kindex k r
+@pindex calc-random
+@tindex random
+The @kbd{k r} (@code{calc-random}) [@code{random}] command produces
+random numbers of various sorts.
+
+Given a positive numeric prefix argument @expr{M}, it produces a random
+integer @expr{N} in the range
+@texline @math{0 \le N < M}.
+@infoline @expr{0 <= N < M}.
+Each of the @expr{M} values appears with equal probability.
+
+With no numeric prefix argument, the @kbd{k r} command takes its argument
+from the stack instead. Once again, if this is a positive integer @expr{M}
+the result is a random integer less than @expr{M}. However, note that
+while numeric prefix arguments are limited to six digits or so, an @expr{M}
+taken from the stack can be arbitrarily large. If @expr{M} is negative,
+the result is a random integer in the range
+@texline @math{M < N \le 0}.
+@infoline @expr{M < N <= 0}.
+
+If the value on the stack is a floating-point number @expr{M}, the result
+is a random floating-point number @expr{N} in the range
+@texline @math{0 \le N < M}
+@infoline @expr{0 <= N < M}
+or
+@texline @math{M < N \le 0},
+@infoline @expr{M < N <= 0},
+according to the sign of @expr{M}.
+
+If @expr{M} is zero, the result is a Gaussian-distributed random real
+number; the distribution has a mean of zero and a standard deviation
+of one. The algorithm used generates random numbers in pairs; thus,
+every other call to this function will be especially fast.
+
+If @expr{M} is an error form
+@texline @math{m} @code{+/-} @math{\sigma}
+@infoline @samp{m +/- s}
+where @var{m} and
+@texline @math{\sigma}
+@infoline @var{s}
+are both real numbers, the result uses a Gaussian distribution with mean
+@var{m} and standard deviation
+@texline @math{\sigma}.
+@infoline @var{s}.
+
+If @expr{M} is an interval form, the lower and upper bounds specify the
+acceptable limits of the random numbers. If both bounds are integers,
+the result is a random integer in the specified range. If either bound
+is floating-point, the result is a random real number in the specified
+range. If the interval is open at either end, the result will be sure
+not to equal that end value. (This makes a big difference for integer
+intervals, but for floating-point intervals it's relatively minor:
+with a precision of 6, @samp{random([1.0..2.0))} will return any of one
+million numbers from 1.00000 to 1.99999; @samp{random([1.0..2.0])} may
+additionally return 2.00000, but the probability of this happening is
+extremely small.)
+
+If @expr{M} is a vector, the result is one element taken at random from
+the vector. All elements of the vector are given equal probabilities.
+
+@vindex RandSeed
+The sequence of numbers produced by @kbd{k r} is completely random by
+default, i.e., the sequence is seeded each time you start Calc using
+the current time and other information. You can get a reproducible
+sequence by storing a particular ``seed value'' in the Calc variable
+@code{RandSeed}. Any integer will do for a seed; integers of from 1
+to 12 digits are good. If you later store a different integer into
+@code{RandSeed}, Calc will switch to a different pseudo-random
+sequence. If you ``unstore'' @code{RandSeed}, Calc will re-seed itself
+from the current time. If you store the same integer that you used
+before back into @code{RandSeed}, you will get the exact same sequence
+of random numbers as before.
+
+@pindex calc-rrandom
+The @code{calc-rrandom} command (not on any key) produces a random real
+number between zero and one. It is equivalent to @samp{random(1.0)}.
+
+@kindex k a
+@pindex calc-random-again
+The @kbd{k a} (@code{calc-random-again}) command produces another random
+number, re-using the most recent value of @expr{M}. With a numeric
+prefix argument @var{n}, it produces @var{n} more random numbers using
+that value of @expr{M}.
+
+@kindex k h
+@pindex calc-shuffle
+@tindex shuffle
+The @kbd{k h} (@code{calc-shuffle}) command produces a vector of several
+random values with no duplicates. The value on the top of the stack
+specifies the set from which the random values are drawn, and may be any
+of the @expr{M} formats described above. The numeric prefix argument
+gives the length of the desired list. (If you do not provide a numeric
+prefix argument, the length of the list is taken from the top of the
+stack, and @expr{M} from second-to-top.)
+
+If @expr{M} is a floating-point number, zero, or an error form (so
+that the random values are being drawn from the set of real numbers)
+there is little practical difference between using @kbd{k h} and using
+@kbd{k r} several times. But if the set of possible values consists
+of just a few integers, or the elements of a vector, then there is
+a very real chance that multiple @kbd{k r}'s will produce the same
+number more than once. The @kbd{k h} command produces a vector whose
+elements are always distinct. (Actually, there is a slight exception:
+If @expr{M} is a vector, no given vector element will be drawn more
+than once, but if several elements of @expr{M} are equal, they may
+each make it into the result vector.)
+
+One use of @kbd{k h} is to rearrange a list at random. This happens
+if the prefix argument is equal to the number of values in the list:
+@kbd{[1, 1.5, 2, 2.5, 3] 5 k h} might produce the permuted list
+@samp{[2.5, 1, 1.5, 3, 2]}. As a convenient feature, if the argument
+@var{n} is negative it is replaced by the size of the set represented
+by @expr{M}. Naturally, this is allowed only when @expr{M} specifies
+a small discrete set of possibilities.
+
+To do the equivalent of @kbd{k h} but with duplications allowed,
+given @expr{M} on the stack and with @var{n} just entered as a numeric
+prefix, use @kbd{v b} to build a vector of copies of @expr{M}, then use
+@kbd{V M k r} to ``map'' the normal @kbd{k r} function over the
+elements of this vector. @xref{Matrix Functions}.
+
+@menu
+* Random Number Generator:: (Complete description of Calc's algorithm)
+@end menu
+
+@node Random Number Generator, , Random Numbers, Random Numbers
+@subsection Random Number Generator
+
+Calc's random number generator uses several methods to ensure that
+the numbers it produces are highly random. Knuth's @emph{Art of
+Computer Programming}, Volume II, contains a thorough description
+of the theory of random number generators and their measurement and
+characterization.
+
+If @code{RandSeed} has no stored value, Calc calls Emacs' built-in
+@code{random} function to get a stream of random numbers, which it
+then treats in various ways to avoid problems inherent in the simple
+random number generators that many systems use to implement @code{random}.
+
+When Calc's random number generator is first invoked, it ``seeds''
+the low-level random sequence using the time of day, so that the
+random number sequence will be different every time you use Calc.
+
+Since Emacs Lisp doesn't specify the range of values that will be
+returned by its @code{random} function, Calc exercises the function
+several times to estimate the range. When Calc subsequently uses
+the @code{random} function, it takes only 10 bits of the result
+near the most-significant end. (It avoids at least the bottom
+four bits, preferably more, and also tries to avoid the top two
+bits.) This strategy works well with the linear congruential
+generators that are typically used to implement @code{random}.
+
+If @code{RandSeed} contains an integer, Calc uses this integer to
+seed an ``additive congruential'' method (Knuth's algorithm 3.2.2A,
+computing
+@texline @math{X_{n-55} - X_{n-24}}.
+@infoline @expr{X_n-55 - X_n-24}).
+This method expands the seed
+value into a large table which is maintained internally; the variable
+@code{RandSeed} is changed from, e.g., 42 to the vector @expr{[42]}
+to indicate that the seed has been absorbed into this table. When
+@code{RandSeed} contains a vector, @kbd{k r} and related commands
+continue to use the same internal table as last time. There is no
+way to extract the complete state of the random number generator
+so that you can restart it from any point; you can only restart it
+from the same initial seed value. A simple way to restart from the
+same seed is to type @kbd{s r RandSeed} to get the seed vector,
+@kbd{v u} to unpack it back into a number, then @kbd{s t RandSeed}
+to reseed the generator with that number.
+
+Calc uses a ``shuffling'' method as described in algorithm 3.2.2B
+of Knuth. It fills a table with 13 random 10-bit numbers. Then,
+to generate a new random number, it uses the previous number to
+index into the table, picks the value it finds there as the new
+random number, then replaces that table entry with a new value
+obtained from a call to the base random number generator (either
+the additive congruential generator or the @code{random} function
+supplied by the system). If there are any flaws in the base
+generator, shuffling will tend to even them out. But if the system
+provides an excellent @code{random} function, shuffling will not
+damage its randomness.
+
+To create a random integer of a certain number of digits, Calc
+builds the integer three decimal digits at a time. For each group
+of three digits, Calc calls its 10-bit shuffling random number generator
+(which returns a value from 0 to 1023); if the random value is 1000
+or more, Calc throws it out and tries again until it gets a suitable
+value.
+
+To create a random floating-point number with precision @var{p}, Calc
+simply creates a random @var{p}-digit integer and multiplies by
+@texline @math{10^{-p}}.
+@infoline @expr{10^-p}.
+The resulting random numbers should be very clean, but note
+that relatively small numbers will have few significant random digits.
+In other words, with a precision of 12, you will occasionally get
+numbers on the order of
+@texline @math{10^{-9}}
+@infoline @expr{10^-9}
+or
+@texline @math{10^{-10}},
+@infoline @expr{10^-10},
+but those numbers will only have two or three random digits since they
+correspond to small integers times
+@texline @math{10^{-12}}.
+@infoline @expr{10^-12}.
+
+To create a random integer in the interval @samp{[0 .. @var{m})}, Calc
+counts the digits in @var{m}, creates a random integer with three
+additional digits, then reduces modulo @var{m}. Unless @var{m} is a
+power of ten the resulting values will be very slightly biased toward
+the lower numbers, but this bias will be less than 0.1%. (For example,
+if @var{m} is 42, Calc will reduce a random integer less than 100000
+modulo 42 to get a result less than 42. It is easy to show that the
+numbers 40 and 41 will be only 2380/2381 as likely to result from this
+modulo operation as numbers 39 and below.) If @var{m} is a power of
+ten, however, the numbers should be completely unbiased.
+
+The Gaussian random numbers generated by @samp{random(0.0)} use the
+``polar'' method described in Knuth section 3.4.1C. This method
+generates a pair of Gaussian random numbers at a time, so only every
+other call to @samp{random(0.0)} will require significant calculations.
+
+@node Combinatorial Functions, Probability Distribution Functions, Random Numbers, Scientific Functions
+@section Combinatorial Functions
+
+@noindent
+Commands relating to combinatorics and number theory begin with the
+@kbd{k} key prefix.
+
+@kindex k g
+@pindex calc-gcd
+@tindex gcd
+The @kbd{k g} (@code{calc-gcd}) [@code{gcd}] command computes the
+Greatest Common Divisor of two integers. It also accepts fractions;
+the GCD of two fractions is defined by taking the GCD of the
+numerators, and the LCM of the denominators. This definition is
+consistent with the idea that @samp{a / gcd(a,x)} should yield an
+integer for any @samp{a} and @samp{x}. For other types of arguments,
+the operation is left in symbolic form.
+
+@kindex k l
+@pindex calc-lcm
+@tindex lcm
+The @kbd{k l} (@code{calc-lcm}) [@code{lcm}] command computes the
+Least Common Multiple of two integers or fractions. The product of
+the LCM and GCD of two numbers is equal to the product of the
+numbers.
+
+@kindex k E
+@pindex calc-extended-gcd
+@tindex egcd
+The @kbd{k E} (@code{calc-extended-gcd}) [@code{egcd}] command computes
+the GCD of two integers @expr{x} and @expr{y} and returns a vector
+@expr{[g, a, b]} where
+@texline @math{g = \gcd(x,y) = a x + b y}.
+@infoline @expr{g = gcd(x,y) = a x + b y}.
+
+@kindex !
+@pindex calc-factorial
+@tindex fact
+@ignore
+@mindex @null
+@end ignore
+@tindex !
+The @kbd{!} (@code{calc-factorial}) [@code{fact}] command computes the
+factorial of the number at the top of the stack. If the number is an
+integer, the result is an exact integer. If the number is an
+integer-valued float, the result is a floating-point approximation. If
+the number is a non-integral real number, the generalized factorial is used,
+as defined by the Euler Gamma function. Please note that computation of
+large factorials can be slow; using floating-point format will help
+since fewer digits must be maintained. The same is true of many of
+the commands in this section.
+
+@kindex k d
+@pindex calc-double-factorial
+@tindex dfact
+@ignore
+@mindex @null
+@end ignore
+@tindex !!
+The @kbd{k d} (@code{calc-double-factorial}) [@code{dfact}] command
+computes the ``double factorial'' of an integer. For an even integer,
+this is the product of even integers from 2 to @expr{N}. For an odd
+integer, this is the product of odd integers from 3 to @expr{N}. If
+the argument is an integer-valued float, the result is a floating-point
+approximation. This function is undefined for negative even integers.
+The notation @expr{N!!} is also recognized for double factorials.
+
+@kindex k c
+@pindex calc-choose
+@tindex choose
+The @kbd{k c} (@code{calc-choose}) [@code{choose}] command computes the
+binomial coefficient @expr{N}-choose-@expr{M}, where @expr{M} is the number
+on the top of the stack and @expr{N} is second-to-top. If both arguments
+are integers, the result is an exact integer. Otherwise, the result is a
+floating-point approximation. The binomial coefficient is defined for all
+real numbers by
+@texline @math{N! \over M! (N-M)!\,}.
+@infoline @expr{N! / M! (N-M)!}.
+
+@kindex H k c
+@pindex calc-perm
+@tindex perm
+@ifnottex
+The @kbd{H k c} (@code{calc-perm}) [@code{perm}] command computes the
+number-of-permutations function @expr{N! / (N-M)!}.
+@end ifnottex
+@tex
+The \kbd{H k c} (\code{calc-perm}) [\code{perm}] command computes the
+number-of-perm\-utations function $N! \over (N-M)!\,$.
+@end tex
+
+@kindex k b
+@kindex H k b
+@pindex calc-bernoulli-number
+@tindex bern
+The @kbd{k b} (@code{calc-bernoulli-number}) [@code{bern}] command
+computes a given Bernoulli number. The value at the top of the stack
+is a nonnegative integer @expr{n} that specifies which Bernoulli number
+is desired. The @kbd{H k b} command computes a Bernoulli polynomial,
+taking @expr{n} from the second-to-top position and @expr{x} from the
+top of the stack. If @expr{x} is a variable or formula the result is
+a polynomial in @expr{x}; if @expr{x} is a number the result is a number.
+
+@kindex k e
+@kindex H k e
+@pindex calc-euler-number
+@tindex euler
+The @kbd{k e} (@code{calc-euler-number}) [@code{euler}] command similarly
+computes an Euler number, and @w{@kbd{H k e}} computes an Euler polynomial.
+Bernoulli and Euler numbers occur in the Taylor expansions of several
+functions.
+
+@kindex k s
+@kindex H k s
+@pindex calc-stirling-number
+@tindex stir1
+@tindex stir2
+The @kbd{k s} (@code{calc-stirling-number}) [@code{stir1}] command
+computes a Stirling number of the first
+@texline kind@tie{}@math{n \brack m},
+@infoline kind,
+given two integers @expr{n} and @expr{m} on the stack. The @kbd{H k s}
+[@code{stir2}] command computes a Stirling number of the second
+@texline kind@tie{}@math{n \brace m}.
+@infoline kind.
+These are the number of @expr{m}-cycle permutations of @expr{n} objects,
+and the number of ways to partition @expr{n} objects into @expr{m}
+non-empty sets, respectively.
+
+@kindex k p
+@pindex calc-prime-test
+@cindex Primes
+The @kbd{k p} (@code{calc-prime-test}) command checks if the integer on
+the top of the stack is prime. For integers less than eight million, the
+answer is always exact and reasonably fast. For larger integers, a
+probabilistic method is used (see Knuth vol. II, section 4.5.4, algorithm P).
+The number is first checked against small prime factors (up to 13). Then,
+any number of iterations of the algorithm are performed. Each step either
+discovers that the number is non-prime, or substantially increases the
+certainty that the number is prime. After a few steps, the chance that
+a number was mistakenly described as prime will be less than one percent.
+(Indeed, this is a worst-case estimate of the probability; in practice
+even a single iteration is quite reliable.) After the @kbd{k p} command,
+the number will be reported as definitely prime or non-prime if possible,
+or otherwise ``probably'' prime with a certain probability of error.
+
+@ignore
+@starindex
+@end ignore
+@tindex prime
+The normal @kbd{k p} command performs one iteration of the primality
+test. Pressing @kbd{k p} repeatedly for the same integer will perform
+additional iterations. Also, @kbd{k p} with a numeric prefix performs
+the specified number of iterations. There is also an algebraic function
+@samp{prime(n)} or @samp{prime(n,iters)} which returns 1 if @expr{n}
+is (probably) prime and 0 if not.
+
+@kindex k f
+@pindex calc-prime-factors
+@tindex prfac
+The @kbd{k f} (@code{calc-prime-factors}) [@code{prfac}] command
+attempts to decompose an integer into its prime factors. For numbers up
+to 25 million, the answer is exact although it may take some time. The
+result is a vector of the prime factors in increasing order. For larger
+inputs, prime factors above 5000 may not be found, in which case the
+last number in the vector will be an unfactored integer greater than 25
+million (with a warning message). For negative integers, the first
+element of the list will be @mathit{-1}. For inputs @mathit{-1}, @mathit{0}, and
+@mathit{1}, the result is a list of the same number.
+
+@kindex k n
+@pindex calc-next-prime
+@ignore
+@mindex nextpr@idots
+@end ignore
+@tindex nextprime
+The @kbd{k n} (@code{calc-next-prime}) [@code{nextprime}] command finds
+the next prime above a given number. Essentially, it searches by calling
+@code{calc-prime-test} on successive integers until it finds one that
+passes the test. This is quite fast for integers less than eight million,
+but once the probabilistic test comes into play the search may be rather
+slow. Ordinarily this command stops for any prime that passes one iteration
+of the primality test. With a numeric prefix argument, a number must pass
+the specified number of iterations before the search stops. (This only
+matters when searching above eight million.) You can always use additional
+@kbd{k p} commands to increase your certainty that the number is indeed
+prime.
+
+@kindex I k n
+@pindex calc-prev-prime
+@ignore
+@mindex prevpr@idots
+@end ignore
+@tindex prevprime
+The @kbd{I k n} (@code{calc-prev-prime}) [@code{prevprime}] command
+analogously finds the next prime less than a given number.
+
+@kindex k t
+@pindex calc-totient
+@tindex totient
+The @kbd{k t} (@code{calc-totient}) [@code{totient}] command computes the
+Euler ``totient''
+@texline function@tie{}@math{\phi(n)},
+@infoline function,
+the number of integers less than @expr{n} which
+are relatively prime to @expr{n}.
+
+@kindex k m
+@pindex calc-moebius
+@tindex moebius
+The @kbd{k m} (@code{calc-moebius}) [@code{moebius}] command computes the
+@texline M@"obius @math{\mu}
+@infoline Moebius ``mu''
+function. If the input number is a product of @expr{k}
+distinct factors, this is @expr{(-1)^k}. If the input number has any
+duplicate factors (i.e., can be divided by the same prime more than once),
+the result is zero.
+
+@node Probability Distribution Functions, , Combinatorial Functions, Scientific Functions
+@section Probability Distribution Functions
+
+@noindent
+The functions in this section compute various probability distributions.
+For continuous distributions, this is the integral of the probability
+density function from @expr{x} to infinity. (These are the ``upper
+tail'' distribution functions; there are also corresponding ``lower
+tail'' functions which integrate from minus infinity to @expr{x}.)
+For discrete distributions, the upper tail function gives the sum
+from @expr{x} to infinity; the lower tail function gives the sum
+from minus infinity up to, but not including,@w{ }@expr{x}.
+
+To integrate from @expr{x} to @expr{y}, just use the distribution
+function twice and subtract. For example, the probability that a
+Gaussian random variable with mean 2 and standard deviation 1 will
+lie in the range from 2.5 to 2.8 is @samp{utpn(2.5,2,1) - utpn(2.8,2,1)}
+(``the probability that it is greater than 2.5, but not greater than 2.8''),
+or equivalently @samp{ltpn(2.8,2,1) - ltpn(2.5,2,1)}.
+
+@kindex k B
+@kindex I k B
+@pindex calc-utpb
+@tindex utpb
+@tindex ltpb
+The @kbd{k B} (@code{calc-utpb}) [@code{utpb}] function uses the
+binomial distribution. Push the parameters @var{n}, @var{p}, and
+then @var{x} onto the stack; the result (@samp{utpb(x,n,p)}) is the
+probability that an event will occur @var{x} or more times out
+of @var{n} trials, if its probability of occurring in any given
+trial is @var{p}. The @kbd{I k B} [@code{ltpb}] function is
+the probability that the event will occur fewer than @var{x} times.
+
+The other probability distribution functions similarly take the
+form @kbd{k @var{X}} (@code{calc-utp@var{x}}) [@code{utp@var{x}}]
+and @kbd{I k @var{X}} [@code{ltp@var{x}}], for various letters
+@var{x}. The arguments to the algebraic functions are the value of
+the random variable first, then whatever other parameters define the
+distribution. Note these are among the few Calc functions where the
+order of the arguments in algebraic form differs from the order of
+arguments as found on the stack. (The random variable comes last on
+the stack, so that you can type, e.g., @kbd{2 @key{RET} 1 @key{RET} 2.5
+k N M-@key{RET} @key{DEL} 2.8 k N -}, using @kbd{M-@key{RET} @key{DEL}} to
+recover the original arguments but substitute a new value for @expr{x}.)
+
+@kindex k C
+@pindex calc-utpc
+@tindex utpc
+@ignore
+@mindex @idots
+@end ignore
+@kindex I k C
+@ignore
+@mindex @null
+@end ignore
+@tindex ltpc
+The @samp{utpc(x,v)} function uses the chi-square distribution with
+@texline @math{\nu}
+@infoline @expr{v}
+degrees of freedom. It is the probability that a model is
+correct if its chi-square statistic is @expr{x}.
+
+@kindex k F
+@pindex calc-utpf
+@tindex utpf
+@ignore
+@mindex @idots
+@end ignore
+@kindex I k F
+@ignore
+@mindex @null
+@end ignore
+@tindex ltpf
+The @samp{utpf(F,v1,v2)} function uses the F distribution, used in
+various statistical tests. The parameters
+@texline @math{\nu_1}
+@infoline @expr{v1}
+and
+@texline @math{\nu_2}
+@infoline @expr{v2}
+are the degrees of freedom in the numerator and denominator,
+respectively, used in computing the statistic @expr{F}.
+
+@kindex k N
+@pindex calc-utpn
+@tindex utpn
+@ignore
+@mindex @idots
+@end ignore
+@kindex I k N
+@ignore
+@mindex @null
+@end ignore
+@tindex ltpn
+The @samp{utpn(x,m,s)} function uses a normal (Gaussian) distribution
+with mean @expr{m} and standard deviation
+@texline @math{\sigma}.
+@infoline @expr{s}.
+It is the probability that such a normal-distributed random variable
+would exceed @expr{x}.
+
+@kindex k P
+@pindex calc-utpp
+@tindex utpp
+@ignore
+@mindex @idots
+@end ignore
+@kindex I k P
+@ignore
+@mindex @null
+@end ignore
+@tindex ltpp
+The @samp{utpp(n,x)} function uses a Poisson distribution with
+mean @expr{x}. It is the probability that @expr{n} or more such
+Poisson random events will occur.
+
+@kindex k T
+@pindex calc-ltpt
+@tindex utpt
+@ignore
+@mindex @idots
+@end ignore
+@kindex I k T
+@ignore
+@mindex @null
+@end ignore
+@tindex ltpt
+The @samp{utpt(t,v)} function uses the Student's ``t'' distribution
+with
+@texline @math{\nu}
+@infoline @expr{v}
+degrees of freedom. It is the probability that a
+t-distributed random variable will be greater than @expr{t}.
+(Note: This computes the distribution function
+@texline @math{A(t|\nu)}
+@infoline @expr{A(t|v)}
+where
+@texline @math{A(0|\nu) = 1}
+@infoline @expr{A(0|v) = 1}
+and
+@texline @math{A(\infty|\nu) \to 0}.
+@infoline @expr{A(inf|v) -> 0}.
+The @code{UTPT} operation on the HP-48 uses a different definition which
+returns half of Calc's value: @samp{UTPT(t,v) = .5*utpt(t,v)}.)
+
+While Calc does not provide inverses of the probability distribution
+functions, the @kbd{a R} command can be used to solve for the inverse.
+Since the distribution functions are monotonic, @kbd{a R} is guaranteed
+to be able to find a solution given any initial guess.
+@xref{Numerical Solutions}.
+
+@node Matrix Functions, Algebra, Scientific Functions, Top
+@chapter Vector/Matrix Functions
+
+@noindent
+Many of the commands described here begin with the @kbd{v} prefix.
+(For convenience, the shift-@kbd{V} prefix is equivalent to @kbd{v}.)
+The commands usually apply to both plain vectors and matrices; some
+apply only to matrices or only to square matrices. If the argument
+has the wrong dimensions the operation is left in symbolic form.
+
+Vectors are entered and displayed using @samp{[a,b,c]} notation.
+Matrices are vectors of which all elements are vectors of equal length.
+(Though none of the standard Calc commands use this concept, a
+three-dimensional matrix or rank-3 tensor could be defined as a
+vector of matrices, and so on.)
+
+@menu
+* Packing and Unpacking::
+* Building Vectors::
+* Extracting Elements::
+* Manipulating Vectors::
+* Vector and Matrix Arithmetic::
+* Set Operations::
+* Statistical Operations::
+* Reducing and Mapping::
+* Vector and Matrix Formats::
+@end menu
+
+@node Packing and Unpacking, Building Vectors, Matrix Functions, Matrix Functions
+@section Packing and Unpacking
+
+@noindent
+Calc's ``pack'' and ``unpack'' commands collect stack entries to build
+composite objects such as vectors and complex numbers. They are
+described in this chapter because they are most often used to build
+vectors.
+
+@kindex v p
+@pindex calc-pack
+The @kbd{v p} (@code{calc-pack}) [@code{pack}] command collects several
+elements from the stack into a matrix, complex number, HMS form, error
+form, etc. It uses a numeric prefix argument to specify the kind of
+object to be built; this argument is referred to as the ``packing mode.''
+If the packing mode is a nonnegative integer, a vector of that
+length is created. For example, @kbd{C-u 5 v p} will pop the top
+five stack elements and push back a single vector of those five
+elements. (@kbd{C-u 0 v p} simply creates an empty vector.)
+
+The same effect can be had by pressing @kbd{[} to push an incomplete
+vector on the stack, using @key{TAB} (@code{calc-roll-down}) to sneak
+the incomplete object up past a certain number of elements, and
+then pressing @kbd{]} to complete the vector.
+
+Negative packing modes create other kinds of composite objects:
+
+@table @cite
+@item -1
+Two values are collected to build a complex number. For example,
+@kbd{5 @key{RET} 7 C-u -1 v p} creates the complex number
+@expr{(5, 7)}. The result is always a rectangular complex
+number. The two input values must both be real numbers,
+i.e., integers, fractions, or floats. If they are not, Calc
+will instead build a formula like @samp{a + (0, 1) b}. (The
+other packing modes also create a symbolic answer if the
+components are not suitable.)
+
+@item -2
+Two values are collected to build a polar complex number.
+The first is the magnitude; the second is the phase expressed
+in either degrees or radians according to the current angular
+mode.
+
+@item -3
+Three values are collected into an HMS form. The first
+two values (hours and minutes) must be integers or
+integer-valued floats. The third value may be any real
+number.
+
+@item -4
+Two values are collected into an error form. The inputs
+may be real numbers or formulas.
+
+@item -5
+Two values are collected into a modulo form. The inputs
+must be real numbers.
+
+@item -6
+Two values are collected into the interval @samp{[a .. b]}.
+The inputs may be real numbers, HMS or date forms, or formulas.
+
+@item -7
+Two values are collected into the interval @samp{[a .. b)}.
+
+@item -8
+Two values are collected into the interval @samp{(a .. b]}.
+
+@item -9
+Two values are collected into the interval @samp{(a .. b)}.
+
+@item -10
+Two integer values are collected into a fraction.
+
+@item -11
+Two values are collected into a floating-point number.
+The first is the mantissa; the second, which must be an
+integer, is the exponent. The result is the mantissa
+times ten to the power of the exponent.
+
+@item -12
+This is treated the same as @mathit{-11} by the @kbd{v p} command.
+When unpacking, @mathit{-12} specifies that a floating-point mantissa
+is desired.
+
+@item -13
+A real number is converted into a date form.
+
+@item -14
+Three numbers (year, month, day) are packed into a pure date form.
+
+@item -15
+Six numbers are packed into a date/time form.
+@end table
+
+With any of the two-input negative packing modes, either or both
+of the inputs may be vectors. If both are vectors of the same
+length, the result is another vector made by packing corresponding
+elements of the input vectors. If one input is a vector and the
+other is a plain number, the number is packed along with each vector
+element to produce a new vector. For example, @kbd{C-u -4 v p}
+could be used to convert a vector of numbers and a vector of errors
+into a single vector of error forms; @kbd{C-u -5 v p} could convert
+a vector of numbers and a single number @var{M} into a vector of
+numbers modulo @var{M}.
+
+If you don't give a prefix argument to @kbd{v p}, it takes
+the packing mode from the top of the stack. The elements to
+be packed then begin at stack level 2. Thus
+@kbd{1 @key{RET} 2 @key{RET} 4 n v p} is another way to
+enter the error form @samp{1 +/- 2}.
+
+If the packing mode taken from the stack is a vector, the result is a
+matrix with the dimensions specified by the elements of the vector,
+which must each be integers. For example, if the packing mode is
+@samp{[2, 3]}, then six numbers will be taken from the stack and
+returned in the form @samp{[@w{[a, b, c]}, [d, e, f]]}.
+
+If any elements of the vector are negative, other kinds of
+packing are done at that level as described above. For
+example, @samp{[2, 3, -4]} takes 12 objects and creates a
+@texline @math{2\times3}
+@infoline 2x3
+matrix of error forms: @samp{[[a +/- b, c +/- d ... ]]}.
+Also, @samp{[-4, -10]} will convert four integers into an
+error form consisting of two fractions: @samp{a:b +/- c:d}.
+
+@ignore
+@starindex
+@end ignore
+@tindex pack
+There is an equivalent algebraic function,
+@samp{pack(@var{mode}, @var{items})} where @var{mode} is a
+packing mode (an integer or a vector of integers) and @var{items}
+is a vector of objects to be packed (re-packed, really) according
+to that mode. For example, @samp{pack([3, -4], [a,b,c,d,e,f])}
+yields @samp{[a +/- b, @w{c +/- d}, e +/- f]}. The function is
+left in symbolic form if the packing mode is invalid, or if the
+number of data items does not match the number of items required
+by the mode.
+
+@kindex v u
+@pindex calc-unpack
+The @kbd{v u} (@code{calc-unpack}) command takes the vector, complex
+number, HMS form, or other composite object on the top of the stack and
+``unpacks'' it, pushing each of its elements onto the stack as separate
+objects. Thus, it is the ``inverse'' of @kbd{v p}. If the value
+at the top of the stack is a formula, @kbd{v u} unpacks it by pushing
+each of the arguments of the top-level operator onto the stack.
+
+You can optionally give a numeric prefix argument to @kbd{v u}
+to specify an explicit (un)packing mode. If the packing mode is
+negative and the input is actually a vector or matrix, the result
+will be two or more similar vectors or matrices of the elements.
+For example, given the vector @samp{[@w{a +/- b}, c^2, d +/- 7]},
+the result of @kbd{C-u -4 v u} will be the two vectors
+@samp{[a, c^2, d]} and @w{@samp{[b, 0, 7]}}.
+
+Note that the prefix argument can have an effect even when the input is
+not a vector. For example, if the input is the number @mathit{-5}, then
+@kbd{c-u -1 v u} yields @mathit{-5} and 0 (the components of @mathit{-5}
+when viewed as a rectangular complex number); @kbd{C-u -2 v u} yields 5
+and 180 (assuming Degrees mode); and @kbd{C-u -10 v u} yields @mathit{-5}
+and 1 (the numerator and denominator of @mathit{-5}, viewed as a rational
+number). Plain @kbd{v u} with this input would complain that the input
+is not a composite object.
+
+Unpacking mode @mathit{-11} converts a float into an integer mantissa and
+an integer exponent, where the mantissa is not divisible by 10
+(except that 0.0 is represented by a mantissa and exponent of 0).
+Unpacking mode @mathit{-12} converts a float into a floating-point mantissa
+and integer exponent, where the mantissa (for non-zero numbers)
+is guaranteed to lie in the range [1 .. 10). In both cases,
+the mantissa is shifted left or right (and the exponent adjusted
+to compensate) in order to satisfy these constraints.
+
+Positive unpacking modes are treated differently than for @kbd{v p}.
+A mode of 1 is much like plain @kbd{v u} with no prefix argument,
+except that in addition to the components of the input object,
+a suitable packing mode to re-pack the object is also pushed.
+Thus, @kbd{C-u 1 v u} followed by @kbd{v p} will re-build the
+original object.
+
+A mode of 2 unpacks two levels of the object; the resulting
+re-packing mode will be a vector of length 2. This might be used
+to unpack a matrix, say, or a vector of error forms. Higher
+unpacking modes unpack the input even more deeply.
+
+@ignore
+@starindex
+@end ignore
+@tindex unpack
+There are two algebraic functions analogous to @kbd{v u}.
+The @samp{unpack(@var{mode}, @var{item})} function unpacks the
+@var{item} using the given @var{mode}, returning the result as
+a vector of components. Here the @var{mode} must be an
+integer, not a vector. For example, @samp{unpack(-4, a +/- b)}
+returns @samp{[a, b]}, as does @samp{unpack(1, a +/- b)}.
+
+@ignore
+@starindex
+@end ignore
+@tindex unpackt
+The @code{unpackt} function is like @code{unpack} but instead
+of returning a simple vector of items, it returns a vector of
+two things: The mode, and the vector of items. For example,
+@samp{unpackt(1, 2:3 +/- 1:4)} returns @samp{[-4, [2:3, 1:4]]},
+and @samp{unpackt(2, 2:3 +/- 1:4)} returns @samp{[[-4, -10], [2, 3, 1, 4]]}.
+The identity for re-building the original object is
+@samp{apply(pack, unpackt(@var{n}, @var{x})) = @var{x}}. (The
+@code{apply} function builds a function call given the function
+name and a vector of arguments.)
+
+@cindex Numerator of a fraction, extracting
+Subscript notation is a useful way to extract a particular part
+of an object. For example, to get the numerator of a rational
+number, you can use @samp{unpack(-10, @var{x})_1}.
+
+@node Building Vectors, Extracting Elements, Packing and Unpacking, Matrix Functions
+@section Building Vectors
+
+@noindent
+Vectors and matrices can be added,
+subtracted, multiplied, and divided; @pxref{Basic Arithmetic}.
+
+@kindex |
+@pindex calc-concat
+@ignore
+@mindex @null
+@end ignore
+@tindex |
+The @kbd{|} (@code{calc-concat}) [@code{vconcat}] command ``concatenates'' two vectors
+into one. For example, after @kbd{@w{[ 1 , 2 ]} [ 3 , 4 ] |}, the stack
+will contain the single vector @samp{[1, 2, 3, 4]}. If the arguments
+are matrices, the rows of the first matrix are concatenated with the
+rows of the second. (In other words, two matrices are just two vectors
+of row-vectors as far as @kbd{|} is concerned.)
+
+If either argument to @kbd{|} is a scalar (a non-vector), it is treated
+like a one-element vector for purposes of concatenation: @kbd{1 [ 2 , 3 ] |}
+produces the vector @samp{[1, 2, 3]}. Likewise, if one argument is a
+matrix and the other is a plain vector, the vector is treated as a
+one-row matrix.
+
+@kindex H |
+@tindex append
+The @kbd{H |} (@code{calc-append}) [@code{append}] command concatenates
+two vectors without any special cases. Both inputs must be vectors.
+Whether or not they are matrices is not taken into account. If either
+argument is a scalar, the @code{append} function is left in symbolic form.
+See also @code{cons} and @code{rcons} below.
+
+@kindex I |
+@kindex H I |
+The @kbd{I |} and @kbd{H I |} commands are similar, but they use their
+two stack arguments in the opposite order. Thus @kbd{I |} is equivalent
+to @kbd{@key{TAB} |}, but possibly more convenient and also a bit faster.
+
+@kindex v d
+@pindex calc-diag
+@tindex diag
+The @kbd{v d} (@code{calc-diag}) [@code{diag}] function builds a diagonal
+square matrix. The optional numeric prefix gives the number of rows
+and columns in the matrix. If the value at the top of the stack is a
+vector, the elements of the vector are used as the diagonal elements; the
+prefix, if specified, must match the size of the vector. If the value on
+the stack is a scalar, it is used for each element on the diagonal, and
+the prefix argument is required.
+
+To build a constant square matrix, e.g., a
+@texline @math{3\times3}
+@infoline 3x3
+matrix filled with ones, use @kbd{0 M-3 v d 1 +}, i.e., build a zero
+matrix first and then add a constant value to that matrix. (Another
+alternative would be to use @kbd{v b} and @kbd{v a}; see below.)
+
+@kindex v i
+@pindex calc-ident
+@tindex idn
+The @kbd{v i} (@code{calc-ident}) [@code{idn}] function builds an identity
+matrix of the specified size. It is a convenient form of @kbd{v d}
+where the diagonal element is always one. If no prefix argument is given,
+this command prompts for one.
+
+In algebraic notation, @samp{idn(a,n)} acts much like @samp{diag(a,n)},
+except that @expr{a} is required to be a scalar (non-vector) quantity.
+If @expr{n} is omitted, @samp{idn(a)} represents @expr{a} times an
+identity matrix of unknown size. Calc can operate algebraically on
+such generic identity matrices, and if one is combined with a matrix
+whose size is known, it is converted automatically to an identity
+matrix of a suitable matching size. The @kbd{v i} command with an
+argument of zero creates a generic identity matrix, @samp{idn(1)}.
+Note that in dimensioned Matrix mode (@pxref{Matrix Mode}), generic
+identity matrices are immediately expanded to the current default
+dimensions.
+
+@kindex v x
+@pindex calc-index
+@tindex index
+The @kbd{v x} (@code{calc-index}) [@code{index}] function builds a vector
+of consecutive integers from 1 to @var{n}, where @var{n} is the numeric
+prefix argument. If you do not provide a prefix argument, you will be
+prompted to enter a suitable number. If @var{n} is negative, the result
+is a vector of negative integers from @var{n} to @mathit{-1}.
+
+With a prefix argument of just @kbd{C-u}, the @kbd{v x} command takes
+three values from the stack: @var{n}, @var{start}, and @var{incr} (with
+@var{incr} at top-of-stack). Counting starts at @var{start} and increases
+by @var{incr} for successive vector elements. If @var{start} or @var{n}
+is in floating-point format, the resulting vector elements will also be
+floats. Note that @var{start} and @var{incr} may in fact be any kind
+of numbers or formulas.
+
+When @var{start} and @var{incr} are specified, a negative @var{n} has a
+different interpretation: It causes a geometric instead of arithmetic
+sequence to be generated. For example, @samp{index(-3, a, b)} produces
+@samp{[a, a b, a b^2]}. If you omit @var{incr} in the algebraic form,
+@samp{index(@var{n}, @var{start})}, the default value for @var{incr}
+is one for positive @var{n} or two for negative @var{n}.
+
+@kindex v b
+@pindex calc-build-vector
+@tindex cvec
+The @kbd{v b} (@code{calc-build-vector}) [@code{cvec}] function builds a
+vector of @var{n} copies of the value on the top of the stack, where @var{n}
+is the numeric prefix argument. In algebraic formulas, @samp{cvec(x,n,m)}
+can also be used to build an @var{n}-by-@var{m} matrix of copies of @var{x}.
+(Interactively, just use @kbd{v b} twice: once to build a row, then again
+to build a matrix of copies of that row.)
+
+@kindex v h
+@kindex I v h
+@pindex calc-head
+@pindex calc-tail
+@tindex head
+@tindex tail
+The @kbd{v h} (@code{calc-head}) [@code{head}] function returns the first
+element of a vector. The @kbd{I v h} (@code{calc-tail}) [@code{tail}]
+function returns the vector with its first element removed. In both
+cases, the argument must be a non-empty vector.
+
+@kindex v k
+@pindex calc-cons
+@tindex cons
+The @kbd{v k} (@code{calc-cons}) [@code{cons}] function takes a value @var{h}
+and a vector @var{t} from the stack, and produces the vector whose head is
+@var{h} and whose tail is @var{t}. This is similar to @kbd{|}, except
+if @var{h} is itself a vector, @kbd{|} will concatenate the two vectors
+whereas @code{cons} will insert @var{h} at the front of the vector @var{t}.
+
+@kindex H v h
+@tindex rhead
+@ignore
+@mindex @idots
+@end ignore
+@kindex H I v h
+@ignore
+@mindex @null
+@end ignore
+@kindex H v k
+@ignore
+@mindex @null
+@end ignore
+@tindex rtail
+@ignore
+@mindex @null
+@end ignore
+@tindex rcons
+Each of these three functions also accepts the Hyperbolic flag [@code{rhead},
+@code{rtail}, @code{rcons}] in which case @var{t} instead represents
+the @emph{last} single element of the vector, with @var{h}
+representing the remainder of the vector. Thus the vector
+@samp{[a, b, c, d] = cons(a, [b, c, d]) = rcons([a, b, c], d)}.
+Also, @samp{head([a, b, c, d]) = a}, @samp{tail([a, b, c, d]) = [b, c, d]},
+@samp{rhead([a, b, c, d]) = [a, b, c]}, and @samp{rtail([a, b, c, d]) = d}.
+
+@node Extracting Elements, Manipulating Vectors, Building Vectors, Matrix Functions
+@section Extracting Vector Elements
+
+@noindent
+@kindex v r
+@pindex calc-mrow
+@tindex mrow
+The @kbd{v r} (@code{calc-mrow}) [@code{mrow}] command extracts one row of
+the matrix on the top of the stack, or one element of the plain vector on
+the top of the stack. The row or element is specified by the numeric
+prefix argument; the default is to prompt for the row or element number.
+The matrix or vector is replaced by the specified row or element in the
+form of a vector or scalar, respectively.
+
+@cindex Permutations, applying
+With a prefix argument of @kbd{C-u} only, @kbd{v r} takes the index of
+the element or row from the top of the stack, and the vector or matrix
+from the second-to-top position. If the index is itself a vector of
+integers, the result is a vector of the corresponding elements of the
+input vector, or a matrix of the corresponding rows of the input matrix.
+This command can be used to obtain any permutation of a vector.
+
+With @kbd{C-u}, if the index is an interval form with integer components,
+it is interpreted as a range of indices and the corresponding subvector or
+submatrix is returned.
+
+@cindex Subscript notation
+@kindex a _
+@pindex calc-subscript
+@tindex subscr
+@tindex _
+Subscript notation in algebraic formulas (@samp{a_b}) stands for the
+Calc function @code{subscr}, which is synonymous with @code{mrow}.
+Thus, @samp{[x, y, z]_k} produces @expr{x}, @expr{y}, or @expr{z} if
+@expr{k} is one, two, or three, respectively. A double subscript
+(@samp{M_i_j}, equivalent to @samp{subscr(subscr(M, i), j)}) will
+access the element at row @expr{i}, column @expr{j} of a matrix.
+The @kbd{a _} (@code{calc-subscript}) command creates a subscript
+formula @samp{a_b} out of two stack entries. (It is on the @kbd{a}
+``algebra'' prefix because subscripted variables are often used
+purely as an algebraic notation.)
+
+@tindex mrrow
+Given a negative prefix argument, @kbd{v r} instead deletes one row or
+element from the matrix or vector on the top of the stack. Thus
+@kbd{C-u 2 v r} replaces a matrix with its second row, but @kbd{C-u -2 v r}
+replaces the matrix with the same matrix with its second row removed.
+In algebraic form this function is called @code{mrrow}.
+
+@tindex getdiag
+Given a prefix argument of zero, @kbd{v r} extracts the diagonal elements
+of a square matrix in the form of a vector. In algebraic form this
+function is called @code{getdiag}.
+
+@kindex v c
+@pindex calc-mcol
+@tindex mcol
+@tindex mrcol
+The @kbd{v c} (@code{calc-mcol}) [@code{mcol} or @code{mrcol}] command is
+the analogous operation on columns of a matrix. Given a plain vector
+it extracts (or removes) one element, just like @kbd{v r}. If the
+index in @kbd{C-u v c} is an interval or vector and the argument is a
+matrix, the result is a submatrix with only the specified columns
+retained (and possibly permuted in the case of a vector index).
+
+To extract a matrix element at a given row and column, use @kbd{v r} to
+extract the row as a vector, then @kbd{v c} to extract the column element
+from that vector. In algebraic formulas, it is often more convenient to
+use subscript notation: @samp{m_i_j} gives row @expr{i}, column @expr{j}
+of matrix @expr{m}.
+
+@kindex v s
+@pindex calc-subvector
+@tindex subvec
+The @kbd{v s} (@code{calc-subvector}) [@code{subvec}] command extracts
+a subvector of a vector. The arguments are the vector, the starting
+index, and the ending index, with the ending index in the top-of-stack
+position. The starting index indicates the first element of the vector
+to take. The ending index indicates the first element @emph{past} the
+range to be taken. Thus, @samp{subvec([a, b, c, d, e], 2, 4)} produces
+the subvector @samp{[b, c]}. You could get the same result using
+@samp{mrow([a, b, c, d, e], @w{[2 .. 4)})}.
+
+If either the start or the end index is zero or negative, it is
+interpreted as relative to the end of the vector. Thus
+@samp{subvec([a, b, c, d, e], 2, -2)} also produces @samp{[b, c]}. In
+the algebraic form, the end index can be omitted in which case it
+is taken as zero, i.e., elements from the starting element to the
+end of the vector are used. The infinity symbol, @code{inf}, also
+has this effect when used as the ending index.
+
+@kindex I v s
+@tindex rsubvec
+With the Inverse flag, @kbd{I v s} [@code{rsubvec}] removes a subvector
+from a vector. The arguments are interpreted the same as for the
+normal @kbd{v s} command. Thus, @samp{rsubvec([a, b, c, d, e], 2, 4)}
+produces @samp{[a, d, e]}. It is always true that @code{subvec} and
+@code{rsubvec} return complementary parts of the input vector.
+
+@xref{Selecting Subformulas}, for an alternative way to operate on
+vectors one element at a time.
+
+@node Manipulating Vectors, Vector and Matrix Arithmetic, Extracting Elements, Matrix Functions
+@section Manipulating Vectors
+
+@noindent
+@kindex v l
+@pindex calc-vlength
+@tindex vlen
+The @kbd{v l} (@code{calc-vlength}) [@code{vlen}] command computes the
+length of a vector. The length of a non-vector is considered to be zero.
+Note that matrices are just vectors of vectors for the purposes of this
+command.
+
+@kindex H v l
+@tindex mdims
+With the Hyperbolic flag, @kbd{H v l} [@code{mdims}] computes a vector
+of the dimensions of a vector, matrix, or higher-order object. For
+example, @samp{mdims([[a,b,c],[d,e,f]])} returns @samp{[2, 3]} since
+its argument is a
+@texline @math{2\times3}
+@infoline 2x3
+matrix.
+
+@kindex v f
+@pindex calc-vector-find
+@tindex find
+The @kbd{v f} (@code{calc-vector-find}) [@code{find}] command searches
+along a vector for the first element equal to a given target. The target
+is on the top of the stack; the vector is in the second-to-top position.
+If a match is found, the result is the index of the matching element.
+Otherwise, the result is zero. The numeric prefix argument, if given,
+allows you to select any starting index for the search.
+
+@kindex v a
+@pindex calc-arrange-vector
+@tindex arrange
+@cindex Arranging a matrix
+@cindex Reshaping a matrix
+@cindex Flattening a matrix
+The @kbd{v a} (@code{calc-arrange-vector}) [@code{arrange}] command
+rearranges a vector to have a certain number of columns and rows. The
+numeric prefix argument specifies the number of columns; if you do not
+provide an argument, you will be prompted for the number of columns.
+The vector or matrix on the top of the stack is @dfn{flattened} into a
+plain vector. If the number of columns is nonzero, this vector is
+then formed into a matrix by taking successive groups of @var{n} elements.
+If the number of columns does not evenly divide the number of elements
+in the vector, the last row will be short and the result will not be
+suitable for use as a matrix. For example, with the matrix
+@samp{[[1, 2], @w{[3, 4]}]} on the stack, @kbd{v a 4} produces
+@samp{[[1, 2, 3, 4]]} (a
+@texline @math{1\times4}
+@infoline 1x4
+matrix), @kbd{v a 1} produces @samp{[[1], [2], [3], [4]]} (a
+@texline @math{4\times1}
+@infoline 4x1
+matrix), @kbd{v a 2} produces @samp{[[1, 2], [3, 4]]} (the original
+@texline @math{2\times2}
+@infoline 2x2
+matrix), @w{@kbd{v a 3}} produces @samp{[[1, 2, 3], [4]]} (not a
+matrix), and @kbd{v a 0} produces the flattened list
+@samp{[1, 2, @w{3, 4}]}.
+
+@cindex Sorting data
+@kindex V S
+@kindex I V S
+@pindex calc-sort
+@tindex sort
+@tindex rsort
+The @kbd{V S} (@code{calc-sort}) [@code{sort}] command sorts the elements of
+a vector into increasing order. Real numbers, real infinities, and
+constant interval forms come first in this ordering; next come other
+kinds of numbers, then variables (in alphabetical order), then finally
+come formulas and other kinds of objects; these are sorted according
+to a kind of lexicographic ordering with the useful property that
+one vector is less or greater than another if the first corresponding
+unequal elements are less or greater, respectively. Since quoted strings
+are stored by Calc internally as vectors of ASCII character codes
+(@pxref{Strings}), this means vectors of strings are also sorted into
+alphabetical order by this command.
+
+The @kbd{I V S} [@code{rsort}] command sorts a vector into decreasing order.
+
+@cindex Permutation, inverse of
+@cindex Inverse of permutation
+@cindex Index tables
+@cindex Rank tables
+@kindex V G
+@kindex I V G
+@pindex calc-grade
+@tindex grade
+@tindex rgrade
+The @kbd{V G} (@code{calc-grade}) [@code{grade}, @code{rgrade}] command
+produces an index table or permutation vector which, if applied to the
+input vector (as the index of @kbd{C-u v r}, say), would sort the vector.
+A permutation vector is just a vector of integers from 1 to @var{n}, where
+each integer occurs exactly once. One application of this is to sort a
+matrix of data rows using one column as the sort key; extract that column,
+grade it with @kbd{V G}, then use the result to reorder the original matrix
+with @kbd{C-u v r}. Another interesting property of the @code{V G} command
+is that, if the input is itself a permutation vector, the result will
+be the inverse of the permutation. The inverse of an index table is
+a rank table, whose @var{k}th element says where the @var{k}th original
+vector element will rest when the vector is sorted. To get a rank
+table, just use @kbd{V G V G}.
+
+With the Inverse flag, @kbd{I V G} produces an index table that would
+sort the input into decreasing order. Note that @kbd{V S} and @kbd{V G}
+use a ``stable'' sorting algorithm, i.e., any two elements which are equal
+will not be moved out of their original order. Generally there is no way
+to tell with @kbd{V S}, since two elements which are equal look the same,
+but with @kbd{V G} this can be an important issue. In the matrix-of-rows
+example, suppose you have names and telephone numbers as two columns and
+you wish to sort by phone number primarily, and by name when the numbers
+are equal. You can sort the data matrix by names first, and then again
+by phone numbers. Because the sort is stable, any two rows with equal
+phone numbers will remain sorted by name even after the second sort.
+
+@cindex Histograms
+@kindex V H
+@pindex calc-histogram
+@ignore
+@mindex histo@idots
+@end ignore
+@tindex histogram
+The @kbd{V H} (@code{calc-histogram}) [@code{histogram}] command builds a
+histogram of a vector of numbers. Vector elements are assumed to be
+integers or real numbers in the range [0..@var{n}) for some ``number of
+bins'' @var{n}, which is the numeric prefix argument given to the
+command. The result is a vector of @var{n} counts of how many times
+each value appeared in the original vector. Non-integers in the input
+are rounded down to integers. Any vector elements outside the specified
+range are ignored. (You can tell if elements have been ignored by noting
+that the counts in the result vector don't add up to the length of the
+input vector.)
+
+@kindex H V H
+With the Hyperbolic flag, @kbd{H V H} pulls two vectors from the stack.
+The second-to-top vector is the list of numbers as before. The top
+vector is an equal-sized list of ``weights'' to attach to the elements
+of the data vector. For example, if the first data element is 4.2 and
+the first weight is 10, then 10 will be added to bin 4 of the result
+vector. Without the hyperbolic flag, every element has a weight of one.
+
+@kindex v t
+@pindex calc-transpose
+@tindex trn
+The @kbd{v t} (@code{calc-transpose}) [@code{trn}] command computes
+the transpose of the matrix at the top of the stack. If the argument
+is a plain vector, it is treated as a row vector and transposed into
+a one-column matrix.
+
+@kindex v v
+@pindex calc-reverse-vector
+@tindex rev
+The @kbd{v v} (@code{calc-reverse-vector}) [@code{rev}] command reverses
+a vector end-for-end. Given a matrix, it reverses the order of the rows.
+(To reverse the columns instead, just use @kbd{v t v v v t}. The same
+principle can be used to apply other vector commands to the columns of
+a matrix.)
+
+@kindex v m
+@pindex calc-mask-vector
+@tindex vmask
+The @kbd{v m} (@code{calc-mask-vector}) [@code{vmask}] command uses
+one vector as a mask to extract elements of another vector. The mask
+is in the second-to-top position; the target vector is on the top of
+the stack. These vectors must have the same length. The result is
+the same as the target vector, but with all elements which correspond
+to zeros in the mask vector deleted. Thus, for example,
+@samp{vmask([1, 0, 1, 0, 1], [a, b, c, d, e])} produces @samp{[a, c, e]}.
+@xref{Logical Operations}.
+
+@kindex v e
+@pindex calc-expand-vector
+@tindex vexp
+The @kbd{v e} (@code{calc-expand-vector}) [@code{vexp}] command
+expands a vector according to another mask vector. The result is a
+vector the same length as the mask, but with nonzero elements replaced
+by successive elements from the target vector. The length of the target
+vector is normally the number of nonzero elements in the mask. If the
+target vector is longer, its last few elements are lost. If the target
+vector is shorter, the last few nonzero mask elements are left
+unreplaced in the result. Thus @samp{vexp([2, 0, 3, 0, 7], [a, b])}
+produces @samp{[a, 0, b, 0, 7]}.
+
+@kindex H v e
+With the Hyperbolic flag, @kbd{H v e} takes a filler value from the
+top of the stack; the mask and target vectors come from the third and
+second elements of the stack. This filler is used where the mask is
+zero: @samp{vexp([2, 0, 3, 0, 7], [a, b], z)} produces
+@samp{[a, z, c, z, 7]}. If the filler value is itself a vector,
+then successive values are taken from it, so that the effect is to
+interleave two vectors according to the mask:
+@samp{vexp([2, 0, 3, 7, 0, 0], [a, b], [x, y])} produces
+@samp{[a, x, b, 7, y, 0]}.
+
+Another variation on the masking idea is to combine @samp{[a, b, c, d, e]}
+with the mask @samp{[1, 0, 1, 0, 1]} to produce @samp{[a, 0, c, 0, e]}.
+You can accomplish this with @kbd{V M a &}, mapping the logical ``and''
+operation across the two vectors. @xref{Logical Operations}. Note that
+the @code{? :} operation also discussed there allows other types of
+masking using vectors.
+
+@node Vector and Matrix Arithmetic, Set Operations, Manipulating Vectors, Matrix Functions
+@section Vector and Matrix Arithmetic
+
+@noindent
+Basic arithmetic operations like addition and multiplication are defined
+for vectors and matrices as well as for numbers. Division of matrices, in
+the sense of multiplying by the inverse, is supported. (Division by a
+matrix actually uses LU-decomposition for greater accuracy and speed.)
+@xref{Basic Arithmetic}.
+
+The following functions are applied element-wise if their arguments are
+vectors or matrices: @code{change-sign}, @code{conj}, @code{arg},
+@code{re}, @code{im}, @code{polar}, @code{rect}, @code{clean},
+@code{float}, @code{frac}. @xref{Function Index}.
+
+@kindex V J
+@pindex calc-conj-transpose
+@tindex ctrn
+The @kbd{V J} (@code{calc-conj-transpose}) [@code{ctrn}] command computes
+the conjugate transpose of its argument, i.e., @samp{conj(trn(x))}.
+
+@ignore
+@mindex A
+@end ignore
+@kindex A (vectors)
+@pindex calc-abs (vectors)
+@ignore
+@mindex abs
+@end ignore
+@tindex abs (vectors)
+The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the
+Frobenius norm of a vector or matrix argument. This is the square
+root of the sum of the squares of the absolute values of the
+elements of the vector or matrix. If the vector is interpreted as
+a point in two- or three-dimensional space, this is the distance
+from that point to the origin.
+
+@kindex v n
+@pindex calc-rnorm
+@tindex rnorm
+The @kbd{v n} (@code{calc-rnorm}) [@code{rnorm}] command computes
+the row norm, or infinity-norm, of a vector or matrix. For a plain
+vector, this is the maximum of the absolute values of the elements.
+For a matrix, this is the maximum of the row-absolute-value-sums,
+i.e., of the sums of the absolute values of the elements along the
+various rows.
+
+@kindex V N
+@pindex calc-cnorm
+@tindex cnorm
+The @kbd{V N} (@code{calc-cnorm}) [@code{cnorm}] command computes
+the column norm, or one-norm, of a vector or matrix. For a plain
+vector, this is the sum of the absolute values of the elements.
+For a matrix, this is the maximum of the column-absolute-value-sums.
+General @expr{k}-norms for @expr{k} other than one or infinity are
+not provided.
+
+@kindex V C
+@pindex calc-cross
+@tindex cross
+The @kbd{V C} (@code{calc-cross}) [@code{cross}] command computes the
+right-handed cross product of two vectors, each of which must have
+exactly three elements.
+
+@ignore
+@mindex &
+@end ignore
+@kindex & (matrices)
+@pindex calc-inv (matrices)
+@ignore
+@mindex inv
+@end ignore
+@tindex inv (matrices)
+The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the
+inverse of a square matrix. If the matrix is singular, the inverse
+operation is left in symbolic form. Matrix inverses are recorded so
+that once an inverse (or determinant) of a particular matrix has been
+computed, the inverse and determinant of the matrix can be recomputed
+quickly in the future.
+
+If the argument to @kbd{&} is a plain number @expr{x}, this
+command simply computes @expr{1/x}. This is okay, because the
+@samp{/} operator also does a matrix inversion when dividing one
+by a matrix.
+
+@kindex V D
+@pindex calc-mdet
+@tindex det
+The @kbd{V D} (@code{calc-mdet}) [@code{det}] command computes the
+determinant of a square matrix.
+
+@kindex V L
+@pindex calc-mlud
+@tindex lud
+The @kbd{V L} (@code{calc-mlud}) [@code{lud}] command computes the
+LU decomposition of a matrix. The result is a list of three matrices
+which, when multiplied together left-to-right, form the original matrix.
+The first is a permutation matrix that arises from pivoting in the
+algorithm, the second is lower-triangular with ones on the diagonal,
+and the third is upper-triangular.
+
+@kindex V T
+@pindex calc-mtrace
+@tindex tr
+The @kbd{V T} (@code{calc-mtrace}) [@code{tr}] command computes the
+trace of a square matrix. This is defined as the sum of the diagonal
+elements of the matrix.
+
+@node Set Operations, Statistical Operations, Vector and Matrix Arithmetic, Matrix Functions
+@section Set Operations using Vectors
+
+@noindent
+@cindex Sets, as vectors
+Calc includes several commands which interpret vectors as @dfn{sets} of
+objects. A set is a collection of objects; any given object can appear
+only once in the set. Calc stores sets as vectors of objects in
+sorted order. Objects in a Calc set can be any of the usual things,
+such as numbers, variables, or formulas. Two set elements are considered
+equal if they are identical, except that numerically equal numbers like
+the integer 4 and the float 4.0 are considered equal even though they
+are not ``identical.'' Variables are treated like plain symbols without
+attached values by the set operations; subtracting the set @samp{[b]}
+from @samp{[a, b]} always yields the set @samp{[a]} even though if
+the variables @samp{a} and @samp{b} both equaled 17, you might
+expect the answer @samp{[]}.
+
+If a set contains interval forms, then it is assumed to be a set of
+real numbers. In this case, all set operations require the elements
+of the set to be only things that are allowed in intervals: Real
+numbers, plus and minus infinity, HMS forms, and date forms. If
+there are variables or other non-real objects present in a real set,
+all set operations on it will be left in unevaluated form.
+
+If the input to a set operation is a plain number or interval form
+@var{a}, it is treated like the one-element vector @samp{[@var{a}]}.
+The result is always a vector, except that if the set consists of a
+single interval, the interval itself is returned instead.
+
+@xref{Logical Operations}, for the @code{in} function which tests if
+a certain value is a member of a given set. To test if the set @expr{A}
+is a subset of the set @expr{B}, use @samp{vdiff(A, B) = []}.
+
+@kindex V +
+@pindex calc-remove-duplicates
+@tindex rdup
+The @kbd{V +} (@code{calc-remove-duplicates}) [@code{rdup}] command
+converts an arbitrary vector into set notation. It works by sorting
+the vector as if by @kbd{V S}, then removing duplicates. (For example,
+@kbd{[a, 5, 4, a, 4.0]} is sorted to @samp{[4, 4.0, 5, a, a]} and then
+reduced to @samp{[4, 5, a]}). Overlapping intervals are merged as
+necessary. You rarely need to use @kbd{V +} explicitly, since all the
+other set-based commands apply @kbd{V +} to their inputs before using
+them.
+
+@kindex V V
+@pindex calc-set-union
+@tindex vunion
+The @kbd{V V} (@code{calc-set-union}) [@code{vunion}] command computes
+the union of two sets. An object is in the union of two sets if and
+only if it is in either (or both) of the input sets. (You could
+accomplish the same thing by concatenating the sets with @kbd{|},
+then using @kbd{V +}.)
+
+@kindex V ^
+@pindex calc-set-intersect
+@tindex vint
+The @kbd{V ^} (@code{calc-set-intersect}) [@code{vint}] command computes
+the intersection of two sets. An object is in the intersection if
+and only if it is in both of the input sets. Thus if the input
+sets are disjoint, i.e., if they share no common elements, the result
+will be the empty vector @samp{[]}. Note that the characters @kbd{V}
+and @kbd{^} were chosen to be close to the conventional mathematical
+notation for set
+@texline union@tie{}(@math{A \cup B})
+@infoline union
+and
+@texline intersection@tie{}(@math{A \cap B}).
+@infoline intersection.
+
+@kindex V -
+@pindex calc-set-difference
+@tindex vdiff
+The @kbd{V -} (@code{calc-set-difference}) [@code{vdiff}] command computes
+the difference between two sets. An object is in the difference
+@expr{A - B} if and only if it is in @expr{A} but not in @expr{B}.
+Thus subtracting @samp{[y,z]} from a set will remove the elements
+@samp{y} and @samp{z} if they are present. You can also think of this
+as a general @dfn{set complement} operator; if @expr{A} is the set of
+all possible values, then @expr{A - B} is the ``complement'' of @expr{B}.
+Obviously this is only practical if the set of all possible values in
+your problem is small enough to list in a Calc vector (or simple
+enough to express in a few intervals).
+
+@kindex V X
+@pindex calc-set-xor
+@tindex vxor
+The @kbd{V X} (@code{calc-set-xor}) [@code{vxor}] command computes
+the ``exclusive-or,'' or ``symmetric difference'' of two sets.
+An object is in the symmetric difference of two sets if and only
+if it is in one, but @emph{not} both, of the sets. Objects that
+occur in both sets ``cancel out.''
+
+@kindex V ~
+@pindex calc-set-complement
+@tindex vcompl
+The @kbd{V ~} (@code{calc-set-complement}) [@code{vcompl}] command
+computes the complement of a set with respect to the real numbers.
+Thus @samp{vcompl(x)} is equivalent to @samp{vdiff([-inf .. inf], x)}.
+For example, @samp{vcompl([2, (3 .. 4]])} evaluates to
+@samp{[[-inf .. 2), (2 .. 3], (4 .. inf]]}.
+
+@kindex V F
+@pindex calc-set-floor
+@tindex vfloor
+The @kbd{V F} (@code{calc-set-floor}) [@code{vfloor}] command
+reinterprets a set as a set of integers. Any non-integer values,
+and intervals that do not enclose any integers, are removed. Open
+intervals are converted to equivalent closed intervals. Successive
+integers are converted into intervals of integers. For example, the
+complement of the set @samp{[2, 6, 7, 8]} is messy, but if you wanted
+the complement with respect to the set of integers you could type
+@kbd{V ~ V F} to get @samp{[[-inf .. 1], [3 .. 5], [9 .. inf]]}.
+
+@kindex V E
+@pindex calc-set-enumerate
+@tindex venum
+The @kbd{V E} (@code{calc-set-enumerate}) [@code{venum}] command
+converts a set of integers into an explicit vector. Intervals in
+the set are expanded out to lists of all integers encompassed by
+the intervals. This only works for finite sets (i.e., sets which
+do not involve @samp{-inf} or @samp{inf}).
+
+@kindex V :
+@pindex calc-set-span
+@tindex vspan
+The @kbd{V :} (@code{calc-set-span}) [@code{vspan}] command converts any
+set of reals into an interval form that encompasses all its elements.
+The lower limit will be the smallest element in the set; the upper
+limit will be the largest element. For an empty set, @samp{vspan([])}
+returns the empty interval @w{@samp{[0 .. 0)}}.
+
+@kindex V #
+@pindex calc-set-cardinality
+@tindex vcard
+The @kbd{V #} (@code{calc-set-cardinality}) [@code{vcard}] command counts
+the number of integers in a set. The result is the length of the vector
+that would be produced by @kbd{V E}, although the computation is much
+more efficient than actually producing that vector.
+
+@cindex Sets, as binary numbers
+Another representation for sets that may be more appropriate in some
+cases is binary numbers. If you are dealing with sets of integers
+in the range 0 to 49, you can use a 50-bit binary number where a
+particular bit is 1 if the corresponding element is in the set.
+@xref{Binary Functions}, for a list of commands that operate on
+binary numbers. Note that many of the above set operations have
+direct equivalents in binary arithmetic: @kbd{b o} (@code{calc-or}),
+@kbd{b a} (@code{calc-and}), @kbd{b d} (@code{calc-diff}),
+@kbd{b x} (@code{calc-xor}), and @kbd{b n} (@code{calc-not}),
+respectively. You can use whatever representation for sets is most
+convenient to you.
+
+@kindex b p
+@kindex b u
+@pindex calc-pack-bits
+@pindex calc-unpack-bits
+@tindex vpack
+@tindex vunpack
+The @kbd{b u} (@code{calc-unpack-bits}) [@code{vunpack}] command
+converts an integer that represents a set in binary into a set
+in vector/interval notation. For example, @samp{vunpack(67)}
+returns @samp{[[0 .. 1], 6]}. If the input is negative, the set
+it represents is semi-infinite: @samp{vunpack(-4) = [2 .. inf)}.
+Use @kbd{V E} afterwards to expand intervals to individual
+values if you wish. Note that this command uses the @kbd{b}
+(binary) prefix key.
+
+The @kbd{b p} (@code{calc-pack-bits}) [@code{vpack}] command
+converts the other way, from a vector or interval representing
+a set of nonnegative integers into a binary integer describing
+the same set. The set may include positive infinity, but must
+not include any negative numbers. The input is interpreted as a
+set of integers in the sense of @kbd{V F} (@code{vfloor}). Beware
+that a simple input like @samp{[100]} can result in a huge integer
+representation
+@texline (@math{2^{100}}, a 31-digit integer, in this case).
+@infoline (@expr{2^100}, a 31-digit integer, in this case).
+
+@node Statistical Operations, Reducing and Mapping, Set Operations, Matrix Functions
+@section Statistical Operations on Vectors
+
+@noindent
+@cindex Statistical functions
+The commands in this section take vectors as arguments and compute
+various statistical measures on the data stored in the vectors. The
+references used in the definitions of these functions are Bevington's
+@emph{Data Reduction and Error Analysis for the Physical Sciences},
+and @emph{Numerical Recipes} by Press, Flannery, Teukolsky and
+Vetterling.
+
+The statistical commands use the @kbd{u} prefix key followed by
+a shifted letter or other character.
+
+@xref{Manipulating Vectors}, for a description of @kbd{V H}
+(@code{calc-histogram}).
+
+@xref{Curve Fitting}, for the @kbd{a F} command for doing
+least-squares fits to statistical data.
+
+@xref{Probability Distribution Functions}, for several common
+probability distribution functions.
+
+@menu
+* Single-Variable Statistics::
+* Paired-Sample Statistics::
+@end menu
+
+@node Single-Variable Statistics, Paired-Sample Statistics, Statistical Operations, Statistical Operations
+@subsection Single-Variable Statistics
+
+@noindent
+These functions do various statistical computations on single
+vectors. Given a numeric prefix argument, they actually pop
+@var{n} objects from the stack and combine them into a data
+vector. Each object may be either a number or a vector; if a
+vector, any sub-vectors inside it are ``flattened'' as if by
+@kbd{v a 0}; @pxref{Manipulating Vectors}. By default one object
+is popped, which (in order to be useful) is usually a vector.
+
+If an argument is a variable name, and the value stored in that
+variable is a vector, then the stored vector is used. This method
+has the advantage that if your data vector is large, you can avoid
+the slow process of manipulating it directly on the stack.
+
+These functions are left in symbolic form if any of their arguments
+are not numbers or vectors, e.g., if an argument is a formula, or
+a non-vector variable. However, formulas embedded within vector
+arguments are accepted; the result is a symbolic representation
+of the computation, based on the assumption that the formula does
+not itself represent a vector. All varieties of numbers such as
+error forms and interval forms are acceptable.
+
+Some of the functions in this section also accept a single error form
+or interval as an argument. They then describe a property of the
+normal or uniform (respectively) statistical distribution described
+by the argument. The arguments are interpreted in the same way as
+the @var{M} argument of the random number function @kbd{k r}. In
+particular, an interval with integer limits is considered an integer
+distribution, so that @samp{[2 .. 6)} is the same as @samp{[2 .. 5]}.
+An interval with at least one floating-point limit is a continuous
+distribution: @samp{[2.0 .. 6.0)} is @emph{not} the same as
+@samp{[2.0 .. 5.0]}!
+
+@kindex u #
+@pindex calc-vector-count
+@tindex vcount
+The @kbd{u #} (@code{calc-vector-count}) [@code{vcount}] command
+computes the number of data values represented by the inputs.
+For example, @samp{vcount(1, [2, 3], [[4, 5], [], x, y])} returns 7.
+If the argument is a single vector with no sub-vectors, this
+simply computes the length of the vector.
+
+@kindex u +
+@kindex u *
+@pindex calc-vector-sum
+@pindex calc-vector-prod
+@tindex vsum
+@tindex vprod
+@cindex Summations (statistical)
+The @kbd{u +} (@code{calc-vector-sum}) [@code{vsum}] command
+computes the sum of the data values. The @kbd{u *}
+(@code{calc-vector-prod}) [@code{vprod}] command computes the
+product of the data values. If the input is a single flat vector,
+these are the same as @kbd{V R +} and @kbd{V R *}
+(@pxref{Reducing and Mapping}).
+
+@kindex u X
+@kindex u N
+@pindex calc-vector-max
+@pindex calc-vector-min
+@tindex vmax
+@tindex vmin
+The @kbd{u X} (@code{calc-vector-max}) [@code{vmax}] command
+computes the maximum of the data values, and the @kbd{u N}
+(@code{calc-vector-min}) [@code{vmin}] command computes the minimum.
+If the argument is an interval, this finds the minimum or maximum
+value in the interval. (Note that @samp{vmax([2..6)) = 5} as
+described above.) If the argument is an error form, this returns
+plus or minus infinity.
+
+@kindex u M
+@pindex calc-vector-mean
+@tindex vmean
+@cindex Mean of data values
+The @kbd{u M} (@code{calc-vector-mean}) [@code{vmean}] command
+computes the average (arithmetic mean) of the data values.
+If the inputs are error forms
+@texline @math{x \pm \sigma},
+@infoline @samp{x +/- s},
+this is the weighted mean of the @expr{x} values with weights
+@texline @math{1 /\sigma^2}.
+@infoline @expr{1 / s^2}.
+@tex
+\turnoffactive
+$$ \mu = { \displaystyle \sum { x_i \over \sigma_i^2 } \over
+ \displaystyle \sum { 1 \over \sigma_i^2 } } $$
+@end tex
+If the inputs are not error forms, this is simply the sum of the
+values divided by the count of the values.
+
+Note that a plain number can be considered an error form with
+error
+@texline @math{\sigma = 0}.
+@infoline @expr{s = 0}.
+If the input to @kbd{u M} is a mixture of
+plain numbers and error forms, the result is the mean of the
+plain numbers, ignoring all values with non-zero errors. (By the
+above definitions it's clear that a plain number effectively
+has an infinite weight, next to which an error form with a finite
+weight is completely negligible.)
+
+This function also works for distributions (error forms or
+intervals). The mean of an error form `@var{a} @tfn{+/-} @var{b}' is simply
+@expr{a}. The mean of an interval is the mean of the minimum
+and maximum values of the interval.
+
+@kindex I u M
+@pindex calc-vector-mean-error
+@tindex vmeane
+The @kbd{I u M} (@code{calc-vector-mean-error}) [@code{vmeane}]
+command computes the mean of the data points expressed as an
+error form. This includes the estimated error associated with
+the mean. If the inputs are error forms, the error is the square
+root of the reciprocal of the sum of the reciprocals of the squares
+of the input errors. (I.e., the variance is the reciprocal of the
+sum of the reciprocals of the variances.)
+@tex
+\turnoffactive
+$$ \sigma_\mu^2 = {1 \over \displaystyle \sum {1 \over \sigma_i^2}} $$
+@end tex
+If the inputs are plain
+numbers, the error is equal to the standard deviation of the values
+divided by the square root of the number of values. (This works
+out to be equivalent to calculating the standard deviation and
+then assuming each value's error is equal to this standard
+deviation.)
+@tex
+\turnoffactive
+$$ \sigma_\mu^2 = {\sigma^2 \over N} $$
+@end tex
+
+@kindex H u M
+@pindex calc-vector-median
+@tindex vmedian
+@cindex Median of data values
+The @kbd{H u M} (@code{calc-vector-median}) [@code{vmedian}]
+command computes the median of the data values. The values are
+first sorted into numerical order; the median is the middle
+value after sorting. (If the number of data values is even,
+the median is taken to be the average of the two middle values.)
+The median function is different from the other functions in
+this section in that the arguments must all be real numbers;
+variables are not accepted even when nested inside vectors.
+(Otherwise it is not possible to sort the data values.) If
+any of the input values are error forms, their error parts are
+ignored.
+
+The median function also accepts distributions. For both normal
+(error form) and uniform (interval) distributions, the median is
+the same as the mean.
+
+@kindex H I u M
+@pindex calc-vector-harmonic-mean
+@tindex vhmean
+@cindex Harmonic mean
+The @kbd{H I u M} (@code{calc-vector-harmonic-mean}) [@code{vhmean}]
+command computes the harmonic mean of the data values. This is
+defined as the reciprocal of the arithmetic mean of the reciprocals
+of the values.
+@tex
+\turnoffactive
+$$ { N \over \displaystyle \sum {1 \over x_i} } $$
+@end tex
+
+@kindex u G
+@pindex calc-vector-geometric-mean
+@tindex vgmean
+@cindex Geometric mean
+The @kbd{u G} (@code{calc-vector-geometric-mean}) [@code{vgmean}]
+command computes the geometric mean of the data values. This
+is the @var{n}th root of the product of the values. This is also
+equal to the @code{exp} of the arithmetic mean of the logarithms
+of the data values.
+@tex
+\turnoffactive
+$$ \exp \left ( \sum { \ln x_i } \right ) =
+ \left ( \prod { x_i } \right)^{1 / N} $$
+@end tex
+
+@kindex H u G
+@tindex agmean
+The @kbd{H u G} [@code{agmean}] command computes the ``arithmetic-geometric
+mean'' of two numbers taken from the stack. This is computed by
+replacing the two numbers with their arithmetic mean and geometric
+mean, then repeating until the two values converge.
+@tex
+\turnoffactive
+$$ a_{i+1} = { a_i + b_i \over 2 } , \qquad b_{i+1} = \sqrt{a_i b_i} $$
+@end tex
+
+@cindex Root-mean-square
+Another commonly used mean, the RMS (root-mean-square), can be computed
+for a vector of numbers simply by using the @kbd{A} command.
+
+@kindex u S
+@pindex calc-vector-sdev
+@tindex vsdev
+@cindex Standard deviation
+@cindex Sample statistics
+The @kbd{u S} (@code{calc-vector-sdev}) [@code{vsdev}] command
+computes the standard
+@texline deviation@tie{}@math{\sigma}
+@infoline deviation
+of the data values. If the values are error forms, the errors are used
+as weights just as for @kbd{u M}. This is the @emph{sample} standard
+deviation, whose value is the square root of the sum of the squares of
+the differences between the values and the mean of the @expr{N} values,
+divided by @expr{N-1}.
+@tex
+\turnoffactive
+$$ \sigma^2 = {1 \over N - 1} \sum (x_i - \mu)^2 $$
+@end tex
+
+This function also applies to distributions. The standard deviation
+of a single error form is simply the error part. The standard deviation
+of a continuous interval happens to equal the difference between the
+limits, divided by
+@texline @math{\sqrt{12}}.
+@infoline @expr{sqrt(12)}.
+The standard deviation of an integer interval is the same as the
+standard deviation of a vector of those integers.
+
+@kindex I u S
+@pindex calc-vector-pop-sdev
+@tindex vpsdev
+@cindex Population statistics
+The @kbd{I u S} (@code{calc-vector-pop-sdev}) [@code{vpsdev}]
+command computes the @emph{population} standard deviation.
+It is defined by the same formula as above but dividing
+by @expr{N} instead of by @expr{N-1}. The population standard
+deviation is used when the input represents the entire set of
+data values in the distribution; the sample standard deviation
+is used when the input represents a sample of the set of all
+data values, so that the mean computed from the input is itself
+only an estimate of the true mean.
+@tex
+\turnoffactive
+$$ \sigma^2 = {1 \over N} \sum (x_i - \mu)^2 $$
+@end tex
+
+For error forms and continuous intervals, @code{vpsdev} works
+exactly like @code{vsdev}. For integer intervals, it computes the
+population standard deviation of the equivalent vector of integers.
+
+@kindex H u S
+@kindex H I u S
+@pindex calc-vector-variance
+@pindex calc-vector-pop-variance
+@tindex vvar
+@tindex vpvar
+@cindex Variance of data values
+The @kbd{H u S} (@code{calc-vector-variance}) [@code{vvar}] and
+@kbd{H I u S} (@code{calc-vector-pop-variance}) [@code{vpvar}]
+commands compute the variance of the data values. The variance
+is the
+@texline square@tie{}@math{\sigma^2}
+@infoline square
+of the standard deviation, i.e., the sum of the
+squares of the deviations of the data values from the mean.
+(This definition also applies when the argument is a distribution.)
+
+@ignore
+@starindex
+@end ignore
+@tindex vflat
+The @code{vflat} algebraic function returns a vector of its
+arguments, interpreted in the same way as the other functions
+in this section. For example, @samp{vflat(1, [2, [3, 4]], 5)}
+returns @samp{[1, 2, 3, 4, 5]}.
+
+@node Paired-Sample Statistics, , Single-Variable Statistics, Statistical Operations
+@subsection Paired-Sample Statistics
+
+@noindent
+The functions in this section take two arguments, which must be
+vectors of equal size. The vectors are each flattened in the same
+way as by the single-variable statistical functions. Given a numeric
+prefix argument of 1, these functions instead take one object from
+the stack, which must be an
+@texline @math{N\times2}
+@infoline Nx2
+matrix of data values. Once again, variable names can be used in place
+of actual vectors and matrices.
+
+@kindex u C
+@pindex calc-vector-covariance
+@tindex vcov
+@cindex Covariance
+The @kbd{u C} (@code{calc-vector-covariance}) [@code{vcov}] command
+computes the sample covariance of two vectors. The covariance
+of vectors @var{x} and @var{y} is the sum of the products of the
+differences between the elements of @var{x} and the mean of @var{x}
+times the differences between the corresponding elements of @var{y}
+and the mean of @var{y}, all divided by @expr{N-1}. Note that
+the variance of a vector is just the covariance of the vector
+with itself. Once again, if the inputs are error forms the
+errors are used as weight factors. If both @var{x} and @var{y}
+are composed of error forms, the error for a given data point
+is taken as the square root of the sum of the squares of the two
+input errors.
+@tex
+\turnoffactive
+$$ \sigma_{x\!y}^2 = {1 \over N-1} \sum (x_i - \mu_x) (y_i - \mu_y) $$
+$$ \sigma_{x\!y}^2 =
+ {\displaystyle {1 \over N-1}
+ \sum {(x_i - \mu_x) (y_i - \mu_y) \over \sigma_i^2}
+ \over \displaystyle {1 \over N} \sum {1 \over \sigma_i^2}}
+$$
+@end tex
+
+@kindex I u C
+@pindex calc-vector-pop-covariance
+@tindex vpcov
+The @kbd{I u C} (@code{calc-vector-pop-covariance}) [@code{vpcov}]
+command computes the population covariance, which is the same as the
+sample covariance computed by @kbd{u C} except dividing by @expr{N}
+instead of @expr{N-1}.
+
+@kindex H u C
+@pindex calc-vector-correlation
+@tindex vcorr
+@cindex Correlation coefficient
+@cindex Linear correlation
+The @kbd{H u C} (@code{calc-vector-correlation}) [@code{vcorr}]
+command computes the linear correlation coefficient of two vectors.
+This is defined by the covariance of the vectors divided by the
+product of their standard deviations. (There is no difference
+between sample or population statistics here.)
+@tex
+\turnoffactive
+$$ r_{x\!y} = { \sigma_{x\!y}^2 \over \sigma_x^2 \sigma_y^2 } $$
+@end tex
+
+@node Reducing and Mapping, Vector and Matrix Formats, Statistical Operations, Matrix Functions
+@section Reducing and Mapping Vectors
+
+@noindent
+The commands in this section allow for more general operations on the
+elements of vectors.
+
+@kindex V A
+@pindex calc-apply
+@tindex apply
+The simplest of these operations is @kbd{V A} (@code{calc-apply})
+[@code{apply}], which applies a given operator to the elements of a vector.
+For example, applying the hypothetical function @code{f} to the vector
+@w{@samp{[1, 2, 3]}} would produce the function call @samp{f(1, 2, 3)}.
+Applying the @code{+} function to the vector @samp{[a, b]} gives
+@samp{a + b}. Applying @code{+} to the vector @samp{[a, b, c]} is an
+error, since the @code{+} function expects exactly two arguments.
+
+While @kbd{V A} is useful in some cases, you will usually find that either
+@kbd{V R} or @kbd{V M}, described below, is closer to what you want.
+
+@menu
+* Specifying Operators::
+* Mapping::
+* Reducing::
+* Nesting and Fixed Points::
+* Generalized Products::
+@end menu
+
+@node Specifying Operators, Mapping, Reducing and Mapping, Reducing and Mapping
+@subsection Specifying Operators
+
+@noindent
+Commands in this section (like @kbd{V A}) prompt you to press the key
+corresponding to the desired operator. Press @kbd{?} for a partial
+list of the available operators. Generally, an operator is any key or
+sequence of keys that would normally take one or more arguments from
+the stack and replace them with a result. For example, @kbd{V A H C}
+uses the hyperbolic cosine operator, @code{cosh}. (Since @code{cosh}
+expects one argument, @kbd{V A H C} requires a vector with a single
+element as its argument.)
+
+You can press @kbd{x} at the operator prompt to select any algebraic
+function by name to use as the operator. This includes functions you
+have defined yourself using the @kbd{Z F} command. (@xref{Algebraic
+Definitions}.) If you give a name for which no function has been
+defined, the result is left in symbolic form, as in @samp{f(1, 2, 3)}.
+Calc will prompt for the number of arguments the function takes if it
+can't figure it out on its own (say, because you named a function that
+is currently undefined). It is also possible to type a digit key before
+the function name to specify the number of arguments, e.g.,
+@kbd{V M 3 x f @key{RET}} calls @code{f} with three arguments even if it
+looks like it ought to have only two. This technique may be necessary
+if the function allows a variable number of arguments. For example,
+the @kbd{v e} [@code{vexp}] function accepts two or three arguments;
+if you want to map with the three-argument version, you will have to
+type @kbd{V M 3 v e}.
+
+It is also possible to apply any formula to a vector by treating that
+formula as a function. When prompted for the operator to use, press
+@kbd{'} (the apostrophe) and type your formula as an algebraic entry.
+You will then be prompted for the argument list, which defaults to a
+list of all variables that appear in the formula, sorted into alphabetic
+order. For example, suppose you enter the formula @w{@samp{x + 2y^x}}.
+The default argument list would be @samp{(x y)}, which means that if
+this function is applied to the arguments @samp{[3, 10]} the result will
+be @samp{3 + 2*10^3}. (If you plan to use a certain formula in this
+way often, you might consider defining it as a function with @kbd{Z F}.)
+
+Another way to specify the arguments to the formula you enter is with
+@kbd{$}, @kbd{$$}, and so on. For example, @kbd{V A ' $$ + 2$^$$}
+has the same effect as the previous example. The argument list is
+automatically taken to be @samp{($$ $)}. (The order of the arguments
+may seem backwards, but it is analogous to the way normal algebraic
+entry interacts with the stack.)
+
+If you press @kbd{$} at the operator prompt, the effect is similar to
+the apostrophe except that the relevant formula is taken from top-of-stack
+instead. The actual vector arguments of the @kbd{V A $} or related command
+then start at the second-to-top stack position. You will still be
+prompted for an argument list.
+
+@cindex Nameless functions
+@cindex Generic functions
+A function can be written without a name using the notation @samp{<#1 - #2>},
+which means ``a function of two arguments that computes the first
+argument minus the second argument.'' The symbols @samp{#1} and @samp{#2}
+are placeholders for the arguments. You can use any names for these
+placeholders if you wish, by including an argument list followed by a
+colon: @samp{<x, y : x - y>}. When you type @kbd{V A ' $$ + 2$^$$ @key{RET}},
+Calc builds the nameless function @samp{<#1 + 2 #2^#1>} as the function
+to map across the vectors. When you type @kbd{V A ' x + 2y^x @key{RET} @key{RET}},
+Calc builds the nameless function @w{@samp{<x, y : x + 2 y^x>}}. In both
+cases, Calc also writes the nameless function to the Trail so that you
+can get it back later if you wish.
+
+If there is only one argument, you can write @samp{#} in place of @samp{#1}.
+(Note that @samp{< >} notation is also used for date forms. Calc tells
+that @samp{<@var{stuff}>} is a nameless function by the presence of
+@samp{#} signs inside @var{stuff}, or by the fact that @var{stuff}
+begins with a list of variables followed by a colon.)
+
+You can type a nameless function directly to @kbd{V A '}, or put one on
+the stack and use it with @w{@kbd{V A $}}. Calc will not prompt for an
+argument list in this case, since the nameless function specifies the
+argument list as well as the function itself. In @kbd{V A '}, you can
+omit the @samp{< >} marks if you use @samp{#} notation for the arguments,
+so that @kbd{V A ' #1+#2 @key{RET}} is the same as @kbd{V A ' <#1+#2> @key{RET}},
+which in turn is the same as @kbd{V A ' $$+$ @key{RET}}.
+
+@cindex Lambda expressions
+@ignore
+@starindex
+@end ignore
+@tindex lambda
+The internal format for @samp{<x, y : x + y>} is @samp{lambda(x, y, x + y)}.
+(The word @code{lambda} derives from Lisp notation and the theory of
+functions.) The internal format for @samp{<#1 + #2>} is @samp{lambda(ArgA,
+ArgB, ArgA + ArgB)}. Note that there is no actual Calc function called
+@code{lambda}; the whole point is that the @code{lambda} expression is
+used in its symbolic form, not evaluated for an answer until it is applied
+to specific arguments by a command like @kbd{V A} or @kbd{V M}.
+
+(Actually, @code{lambda} does have one special property: Its arguments
+are never evaluated; for example, putting @samp{<(2/3) #>} on the stack
+will not simplify the @samp{2/3} until the nameless function is actually
+called.)
+
+@tindex add
+@tindex sub
+@ignore
+@mindex @idots
+@end ignore
+@tindex mul
+@ignore
+@mindex @null
+@end ignore
+@tindex div
+@ignore
+@mindex @null
+@end ignore
+@tindex pow
+@ignore
+@mindex @null
+@end ignore
+@tindex neg
+@ignore
+@mindex @null
+@end ignore
+@tindex mod
+@ignore
+@mindex @null
+@end ignore
+@tindex vconcat
+As usual, commands like @kbd{V A} have algebraic function name equivalents.
+For example, @kbd{V A k g} with an argument of @samp{v} is equivalent to
+@samp{apply(gcd, v)}. The first argument specifies the operator name,
+and is either a variable whose name is the same as the function name,
+or a nameless function like @samp{<#^3+1>}. Operators that are normally
+written as algebraic symbols have the names @code{add}, @code{sub},
+@code{mul}, @code{div}, @code{pow}, @code{neg}, @code{mod}, and
+@code{vconcat}.
+
+@ignore
+@starindex
+@end ignore
+@tindex call
+The @code{call} function builds a function call out of several arguments:
+@samp{call(gcd, x, y)} is the same as @samp{apply(gcd, [x, y])}, which
+in turn is the same as @samp{gcd(x, y)}. The first argument of @code{call},
+like the other functions described here, may be either a variable naming a
+function, or a nameless function (@samp{call(<#1+2#2>, x, y)} is the same
+as @samp{x + 2y}).
+
+(Experts will notice that it's not quite proper to use a variable to name
+a function, since the name @code{gcd} corresponds to the Lisp variable
+@code{var-gcd} but to the Lisp function @code{calcFunc-gcd}. Calc
+automatically makes this translation, so you don't have to worry
+about it.)
+
+@node Mapping, Reducing, Specifying Operators, Reducing and Mapping
+@subsection Mapping
+
+@noindent
+@kindex V M
+@pindex calc-map
+@tindex map
+The @kbd{V M} (@code{calc-map}) [@code{map}] command applies a given
+operator elementwise to one or more vectors. For example, mapping
+@code{A} [@code{abs}] produces a vector of the absolute values of the
+elements in the input vector. Mapping @code{+} pops two vectors from
+the stack, which must be of equal length, and produces a vector of the
+pairwise sums of the elements. If either argument is a non-vector, it
+is duplicated for each element of the other vector. For example,
+@kbd{[1,2,3] 2 V M ^} squares the elements of the specified vector.
+With the 2 listed first, it would have computed a vector of powers of
+two. Mapping a user-defined function pops as many arguments from the
+stack as the function requires. If you give an undefined name, you will
+be prompted for the number of arguments to use.
+
+If any argument to @kbd{V M} is a matrix, the operator is normally mapped
+across all elements of the matrix. For example, given the matrix
+@expr{[[1, -2, 3], [-4, 5, -6]]}, @kbd{V M A} takes six absolute values to
+produce another
+@texline @math{3\times2}
+@infoline 3x2
+matrix, @expr{[[1, 2, 3], [4, 5, 6]]}.
+
+@tindex mapr
+The command @kbd{V M _} [@code{mapr}] (i.e., type an underscore at the
+operator prompt) maps by rows instead. For example, @kbd{V M _ A} views
+the above matrix as a vector of two 3-element row vectors. It produces
+a new vector which contains the absolute values of those row vectors,
+namely @expr{[3.74, 8.77]}. (Recall, the absolute value of a vector is
+defined as the square root of the sum of the squares of the elements.)
+Some operators accept vectors and return new vectors; for example,
+@kbd{v v} reverses a vector, so @kbd{V M _ v v} would reverse each row
+of the matrix to get a new matrix, @expr{[[3, -2, 1], [-6, 5, -4]]}.
+
+Sometimes a vector of vectors (representing, say, strings, sets, or lists)
+happens to look like a matrix. If so, remember to use @kbd{V M _} if you
+want to map a function across the whole strings or sets rather than across
+their individual elements.
+
+@tindex mapc
+The command @kbd{V M :} [@code{mapc}] maps by columns. Basically, it
+transposes the input matrix, maps by rows, and then, if the result is a
+matrix, transposes again. For example, @kbd{V M : A} takes the absolute
+values of the three columns of the matrix, treating each as a 2-vector,
+and @kbd{V M : v v} reverses the columns to get the matrix
+@expr{[[-4, 5, -6], [1, -2, 3]]}.
+
+(The symbols @kbd{_} and @kbd{:} were chosen because they had row-like
+and column-like appearances, and were not already taken by useful
+operators. Also, they appear shifted on most keyboards so they are easy
+to type after @kbd{V M}.)
+
+The @kbd{_} and @kbd{:} modifiers have no effect on arguments that are
+not matrices (so if none of the arguments are matrices, they have no
+effect at all). If some of the arguments are matrices and others are
+plain numbers, the plain numbers are held constant for all rows of the
+matrix (so that @kbd{2 V M _ ^} squares every row of a matrix; squaring
+a vector takes a dot product of the vector with itself).
+
+If some of the arguments are vectors with the same lengths as the
+rows (for @kbd{V M _}) or columns (for @kbd{V M :}) of the matrix
+arguments, those vectors are also held constant for every row or
+column.
+
+Sometimes it is useful to specify another mapping command as the operator
+to use with @kbd{V M}. For example, @kbd{V M _ V A +} applies @kbd{V A +}
+to each row of the input matrix, which in turn adds the two values on that
+row. If you give another vector-operator command as the operator for
+@kbd{V M}, it automatically uses map-by-rows mode if you don't specify
+otherwise; thus @kbd{V M V A +} is equivalent to @kbd{V M _ V A +}. (If
+you really want to map-by-elements another mapping command, you can use
+a triple-nested mapping command: @kbd{V M V M V A +} means to map
+@kbd{V M V A +} over the rows of the matrix; in turn, @kbd{V A +} is
+mapped over the elements of each row.)
+
+@tindex mapa
+@tindex mapd
+Previous versions of Calc had ``map across'' and ``map down'' modes
+that are now considered obsolete; the old ``map across'' is now simply
+@kbd{V M V A}, and ``map down'' is now @kbd{V M : V A}. The algebraic
+functions @code{mapa} and @code{mapd} are still supported, though.
+Note also that, while the old mapping modes were persistent (once you
+set the mode, it would apply to later mapping commands until you reset
+it), the new @kbd{:} and @kbd{_} modifiers apply only to the current
+mapping command. The default @kbd{V M} always means map-by-elements.
+
+@xref{Algebraic Manipulation}, for the @kbd{a M} command, which is like
+@kbd{V M} but for equations and inequalities instead of vectors.
+@xref{Storing Variables}, for the @kbd{s m} command which modifies a
+variable's stored value using a @kbd{V M}-like operator.
+
+@node Reducing, Nesting and Fixed Points, Mapping, Reducing and Mapping
+@subsection Reducing
+
+@noindent
+@kindex V R
+@pindex calc-reduce
+@tindex reduce
+The @kbd{V R} (@code{calc-reduce}) [@code{reduce}] command applies a given
+binary operator across all the elements of a vector. A binary operator is
+a function such as @code{+} or @code{max} which takes two arguments. For
+example, reducing @code{+} over a vector computes the sum of the elements
+of the vector. Reducing @code{-} computes the first element minus each of
+the remaining elements. Reducing @code{max} computes the maximum element
+and so on. In general, reducing @code{f} over the vector @samp{[a, b, c, d]}
+produces @samp{f(f(f(a, b), c), d)}.
+
+@kindex I V R
+@tindex rreduce
+The @kbd{I V R} [@code{rreduce}] command is similar to @kbd{V R} except
+that works from right to left through the vector. For example, plain
+@kbd{V R -} on the vector @samp{[a, b, c, d]} produces @samp{a - b - c - d}
+but @kbd{I V R -} on the same vector produces @samp{a - (b - (c - d))},
+or @samp{a - b + c - d}. This ``alternating sum'' occurs frequently
+in power series expansions.
+
+@kindex V U
+@tindex accum
+The @kbd{V U} (@code{calc-accumulate}) [@code{accum}] command does an
+accumulation operation. Here Calc does the corresponding reduction
+operation, but instead of producing only the final result, it produces
+a vector of all the intermediate results. Accumulating @code{+} over
+the vector @samp{[a, b, c, d]} produces the vector
+@samp{[a, a + b, a + b + c, a + b + c + d]}.
+
+@kindex I V U
+@tindex raccum
+The @kbd{I V U} [@code{raccum}] command does a right-to-left accumulation.
+For example, @kbd{I V U -} on the vector @samp{[a, b, c, d]} produces the
+vector @samp{[a - b + c - d, b - c + d, c - d, d]}.
+
+@tindex reducea
+@tindex rreducea
+@tindex reduced
+@tindex rreduced
+As for @kbd{V M}, @kbd{V R} normally reduces a matrix elementwise. For
+example, given the matrix @expr{[[a, b, c], [d, e, f]]}, @kbd{V R +} will
+compute @expr{a + b + c + d + e + f}. You can type @kbd{V R _} or
+@kbd{V R :} to modify this behavior. The @kbd{V R _} [@code{reducea}]
+command reduces ``across'' the matrix; it reduces each row of the matrix
+as a vector, then collects the results. Thus @kbd{V R _ +} of this
+matrix would produce @expr{[a + b + c, d + e + f]}. Similarly, @kbd{V R :}
+[@code{reduced}] reduces down; @kbd{V R : +} would produce @expr{[a + d,
+b + e, c + f]}.
+
+@tindex reducer
+@tindex rreducer
+There is a third ``by rows'' mode for reduction that is occasionally
+useful; @kbd{V R =} [@code{reducer}] simply reduces the operator over
+the rows of the matrix themselves. Thus @kbd{V R = +} on the above
+matrix would get the same result as @kbd{V R : +}, since adding two
+row vectors is equivalent to adding their elements. But @kbd{V R = *}
+would multiply the two rows (to get a single number, their dot product),
+while @kbd{V R : *} would produce a vector of the products of the columns.
+
+These three matrix reduction modes work with @kbd{V R} and @kbd{I V R},
+but they are not currently supported with @kbd{V U} or @kbd{I V U}.
+
+@tindex reducec
+@tindex rreducec
+The obsolete reduce-by-columns function, @code{reducec}, is still
+supported but there is no way to get it through the @kbd{V R} command.
+
+The commands @kbd{C-x * :} and @kbd{C-x * _} are equivalent to typing
+@kbd{C-x * r} to grab a rectangle of data into Calc, and then typing
+@kbd{V R : +} or @kbd{V R _ +}, respectively, to sum the columns or
+rows of the matrix. @xref{Grabbing From Buffers}.
+
+@node Nesting and Fixed Points, Generalized Products, Reducing, Reducing and Mapping
+@subsection Nesting and Fixed Points
+
+@noindent
+@kindex H V R
+@tindex nest
+The @kbd{H V R} [@code{nest}] command applies a function to a given
+argument repeatedly. It takes two values, @samp{a} and @samp{n}, from
+the stack, where @samp{n} must be an integer. It then applies the
+function nested @samp{n} times; if the function is @samp{f} and @samp{n}
+is 3, the result is @samp{f(f(f(a)))}. The number @samp{n} may be
+negative if Calc knows an inverse for the function @samp{f}; for
+example, @samp{nest(sin, a, -2)} returns @samp{arcsin(arcsin(a))}.
+
+@kindex H V U
+@tindex anest
+The @kbd{H V U} [@code{anest}] command is an accumulating version of
+@code{nest}: It returns a vector of @samp{n+1} values, e.g.,
+@samp{[a, f(a), f(f(a)), f(f(f(a)))]}. If @samp{n} is negative and
+@samp{F} is the inverse of @samp{f}, then the result is of the
+form @samp{[a, F(a), F(F(a)), F(F(F(a)))]}.
+
+@kindex H I V R
+@tindex fixp
+@cindex Fixed points
+The @kbd{H I V R} [@code{fixp}] command is like @kbd{H V R}, except
+that it takes only an @samp{a} value from the stack; the function is
+applied until it reaches a ``fixed point,'' i.e., until the result
+no longer changes.
+
+@kindex H I V U
+@tindex afixp
+The @kbd{H I V U} [@code{afixp}] command is an accumulating @code{fixp}.
+The first element of the return vector will be the initial value @samp{a};
+the last element will be the final result that would have been returned
+by @code{fixp}.
+
+For example, 0.739085 is a fixed point of the cosine function (in radians):
+@samp{cos(0.739085) = 0.739085}. You can find this value by putting, say,
+1.0 on the stack and typing @kbd{H I V U C}. (We use the accumulating
+version so we can see the intermediate results: @samp{[1, 0.540302, 0.857553,
+0.65329, ...]}. With a precision of six, this command will take 36 steps
+to converge to 0.739085.)
+
+Newton's method for finding roots is a classic example of iteration
+to a fixed point. To find the square root of five starting with an
+initial guess, Newton's method would look for a fixed point of the
+function @samp{(x + 5/x) / 2}. Putting a guess of 1 on the stack
+and typing @kbd{H I V R ' ($ + 5/$)/2 @key{RET}} quickly yields the result
+2.23607. This is equivalent to using the @kbd{a R} (@code{calc-find-root})
+command to find a root of the equation @samp{x^2 = 5}.
+
+These examples used numbers for @samp{a} values. Calc keeps applying
+the function until two successive results are equal to within the
+current precision. For complex numbers, both the real parts and the
+imaginary parts must be equal to within the current precision. If
+@samp{a} is a formula (say, a variable name), then the function is
+applied until two successive results are exactly the same formula.
+It is up to you to ensure that the function will eventually converge;
+if it doesn't, you may have to press @kbd{C-g} to stop the Calculator.
+
+The algebraic @code{fixp} function takes two optional arguments, @samp{n}
+and @samp{tol}. The first is the maximum number of steps to be allowed,
+and must be either an integer or the symbol @samp{inf} (infinity, the
+default). The second is a convergence tolerance. If a tolerance is
+specified, all results during the calculation must be numbers, not
+formulas, and the iteration stops when the magnitude of the difference
+between two successive results is less than or equal to the tolerance.
+(This implies that a tolerance of zero iterates until the results are
+exactly equal.)
+
+Putting it all together, @samp{fixp(<(# + A/#)/2>, B, 20, 1e-10)}
+computes the square root of @samp{A} given the initial guess @samp{B},
+stopping when the result is correct within the specified tolerance, or
+when 20 steps have been taken, whichever is sooner.
+
+@node Generalized Products, , Nesting and Fixed Points, Reducing and Mapping
+@subsection Generalized Products
+
+@kindex V O
+@pindex calc-outer-product
+@tindex outer
+The @kbd{V O} (@code{calc-outer-product}) [@code{outer}] command applies
+a given binary operator to all possible pairs of elements from two
+vectors, to produce a matrix. For example, @kbd{V O *} with @samp{[a, b]}
+and @samp{[x, y, z]} on the stack produces a multiplication table:
+@samp{[[a x, a y, a z], [b x, b y, b z]]}. Element @var{r},@var{c} of
+the result matrix is obtained by applying the operator to element @var{r}
+of the lefthand vector and element @var{c} of the righthand vector.
+
+@kindex V I
+@pindex calc-inner-product
+@tindex inner
+The @kbd{V I} (@code{calc-inner-product}) [@code{inner}] command computes
+the generalized inner product of two vectors or matrices, given a
+``multiplicative'' operator and an ``additive'' operator. These can each
+actually be any binary operators; if they are @samp{*} and @samp{+},
+respectively, the result is a standard matrix multiplication. Element
+@var{r},@var{c} of the result matrix is obtained by mapping the
+multiplicative operator across row @var{r} of the lefthand matrix and
+column @var{c} of the righthand matrix, and then reducing with the additive
+operator. Just as for the standard @kbd{*} command, this can also do a
+vector-matrix or matrix-vector inner product, or a vector-vector
+generalized dot product.
+
+Since @kbd{V I} requires two operators, it prompts twice. In each case,
+you can use any of the usual methods for entering the operator. If you
+use @kbd{$} twice to take both operator formulas from the stack, the
+first (multiplicative) operator is taken from the top of the stack
+and the second (additive) operator is taken from second-to-top.
+
+@node Vector and Matrix Formats, , Reducing and Mapping, Matrix Functions
+@section Vector and Matrix Display Formats
+
+@noindent
+Commands for controlling vector and matrix display use the @kbd{v} prefix
+instead of the usual @kbd{d} prefix. But they are display modes; in
+particular, they are influenced by the @kbd{I} and @kbd{H} prefix keys
+in the same way (@pxref{Display Modes}). Matrix display is also
+influenced by the @kbd{d O} (@code{calc-flat-language}) mode;
+@pxref{Normal Language Modes}.
+
+@kindex V <
+@pindex calc-matrix-left-justify
+@kindex V =
+@pindex calc-matrix-center-justify
+@kindex V >
+@pindex calc-matrix-right-justify
+The commands @kbd{v <} (@code{calc-matrix-left-justify}), @kbd{v >}
+(@code{calc-matrix-right-justify}), and @w{@kbd{v =}}
+(@code{calc-matrix-center-justify}) control whether matrix elements
+are justified to the left, right, or center of their columns.
+
+@kindex V [
+@pindex calc-vector-brackets
+@kindex V @{
+@pindex calc-vector-braces
+@kindex V (
+@pindex calc-vector-parens
+The @kbd{v [} (@code{calc-vector-brackets}) command turns the square
+brackets that surround vectors and matrices displayed in the stack on
+and off. The @kbd{v @{} (@code{calc-vector-braces}) and @kbd{v (}
+(@code{calc-vector-parens}) commands use curly braces or parentheses,
+respectively, instead of square brackets. For example, @kbd{v @{} might
+be used in preparation for yanking a matrix into a buffer running
+Mathematica. (In fact, the Mathematica language mode uses this mode;
+@pxref{Mathematica Language Mode}.) Note that, regardless of the
+display mode, either brackets or braces may be used to enter vectors,
+and parentheses may never be used for this purpose.
+
+@kindex V ]
+@pindex calc-matrix-brackets
+The @kbd{v ]} (@code{calc-matrix-brackets}) command controls the
+``big'' style display of matrices. It prompts for a string of code
+letters; currently implemented letters are @code{R}, which enables
+brackets on each row of the matrix; @code{O}, which enables outer
+brackets in opposite corners of the matrix; and @code{C}, which
+enables commas or semicolons at the ends of all rows but the last.
+The default format is @samp{RO}. (Before Calc 2.00, the format
+was fixed at @samp{ROC}.) Here are some example matrices:
+
+@example
+@group
+[ [ 123, 0, 0 ] [ [ 123, 0, 0 ],
+ [ 0, 123, 0 ] [ 0, 123, 0 ],
+ [ 0, 0, 123 ] ] [ 0, 0, 123 ] ]
+
+ RO ROC
+
+@end group
+@end example
+@noindent
+@example
+@group
+ [ 123, 0, 0 [ 123, 0, 0 ;
+ 0, 123, 0 0, 123, 0 ;
+ 0, 0, 123 ] 0, 0, 123 ]
+
+ O OC
+
+@end group
+@end example
+@noindent
+@example
+@group
+ [ 123, 0, 0 ] 123, 0, 0
+ [ 0, 123, 0 ] 0, 123, 0
+ [ 0, 0, 123 ] 0, 0, 123
+
+ R @r{blank}
+@end group
+@end example
+
+@noindent
+Note that of the formats shown here, @samp{RO}, @samp{ROC}, and
+@samp{OC} are all recognized as matrices during reading, while
+the others are useful for display only.
+
+@kindex V ,
+@pindex calc-vector-commas
+The @kbd{v ,} (@code{calc-vector-commas}) command turns commas on and
+off in vector and matrix display.
+
+In vectors of length one, and in all vectors when commas have been
+turned off, Calc adds extra parentheses around formulas that might
+otherwise be ambiguous. For example, @samp{[a b]} could be a vector
+of the one formula @samp{a b}, or it could be a vector of two
+variables with commas turned off. Calc will display the former
+case as @samp{[(a b)]}. You can disable these extra parentheses
+(to make the output less cluttered at the expense of allowing some
+ambiguity) by adding the letter @code{P} to the control string you
+give to @kbd{v ]} (as described above).
+
+@kindex V .
+@pindex calc-full-vectors
+The @kbd{v .} (@code{calc-full-vectors}) command turns abbreviated
+display of long vectors on and off. In this mode, vectors of six
+or more elements, or matrices of six or more rows or columns, will
+be displayed in an abbreviated form that displays only the first
+three elements and the last element: @samp{[a, b, c, ..., z]}.
+When very large vectors are involved this will substantially
+improve Calc's display speed.
+
+@kindex t .
+@pindex calc-full-trail-vectors
+The @kbd{t .} (@code{calc-full-trail-vectors}) command controls a
+similar mode for recording vectors in the Trail. If you turn on
+this mode, vectors of six or more elements and matrices of six or
+more rows or columns will be abbreviated when they are put in the
+Trail. The @kbd{t y} (@code{calc-trail-yank}) command will be
+unable to recover those vectors. If you are working with very
+large vectors, this mode will improve the speed of all operations
+that involve the trail.
+
+@kindex V /
+@pindex calc-break-vectors
+The @kbd{v /} (@code{calc-break-vectors}) command turns multi-line
+vector display on and off. Normally, matrices are displayed with one
+row per line but all other types of vectors are displayed in a single
+line. This mode causes all vectors, whether matrices or not, to be
+displayed with a single element per line. Sub-vectors within the
+vectors will still use the normal linear form.
+
+@node Algebra, Units, Matrix Functions, Top
+@chapter Algebra
+
+@noindent
+This section covers the Calc features that help you work with
+algebraic formulas. First, the general sub-formula selection
+mechanism is described; this works in conjunction with any Calc
+commands. Then, commands for specific algebraic operations are
+described. Finally, the flexible @dfn{rewrite rule} mechanism
+is discussed.
+
+The algebraic commands use the @kbd{a} key prefix; selection
+commands use the @kbd{j} (for ``just a letter that wasn't used
+for anything else'') prefix.
+
+@xref{Editing Stack Entries}, to see how to manipulate formulas
+using regular Emacs editing commands.
+
+When doing algebraic work, you may find several of the Calculator's
+modes to be helpful, including Algebraic Simplification mode (@kbd{m A})
+or No-Simplification mode (@kbd{m O}),
+Algebraic entry mode (@kbd{m a}), Fraction mode (@kbd{m f}), and
+Symbolic mode (@kbd{m s}). @xref{Mode Settings}, for discussions
+of these modes. You may also wish to select Big display mode (@kbd{d B}).
+@xref{Normal Language Modes}.
+
+@menu
+* Selecting Subformulas::
+* Algebraic Manipulation::
+* Simplifying Formulas::
+* Polynomials::
+* Calculus::
+* Solving Equations::
+* Numerical Solutions::
+* Curve Fitting::
+* Summations::
+* Logical Operations::
+* Rewrite Rules::
+@end menu
+
+@node Selecting Subformulas, Algebraic Manipulation, Algebra, Algebra
+@section Selecting Sub-Formulas
+
+@noindent
+@cindex Selections
+@cindex Sub-formulas
+@cindex Parts of formulas
+When working with an algebraic formula it is often necessary to
+manipulate a portion of the formula rather than the formula as a
+whole. Calc allows you to ``select'' a portion of any formula on
+the stack. Commands which would normally operate on that stack
+entry will now operate only on the sub-formula, leaving the
+surrounding part of the stack entry alone.
+
+One common non-algebraic use for selection involves vectors. To work
+on one element of a vector in-place, simply select that element as a
+``sub-formula'' of the vector.
+
+@menu
+* Making Selections::
+* Changing Selections::
+* Displaying Selections::
+* Operating on Selections::
+* Rearranging with Selections::
+@end menu
+
+@node Making Selections, Changing Selections, Selecting Subformulas, Selecting Subformulas
+@subsection Making Selections
+
+@noindent
+@kindex j s
+@pindex calc-select-here
+To select a sub-formula, move the Emacs cursor to any character in that
+sub-formula, and press @w{@kbd{j s}} (@code{calc-select-here}). Calc will
+highlight the smallest portion of the formula that contains that
+character. By default the sub-formula is highlighted by blanking out
+all of the rest of the formula with dots. Selection works in any
+display mode but is perhaps easiest in Big mode (@kbd{d B}).
+Suppose you enter the following formula:
+
+@smallexample
+@group
+ 3 ___
+ (a + b) + V c
+1: ---------------
+ 2 x + 1
+@end group
+@end smallexample
+
+@noindent
+(by typing @kbd{' ((a+b)^3 + sqrt(c)) / (2x+1)}). If you move the
+cursor to the letter @samp{b} and press @w{@kbd{j s}}, the display changes
+to
+
+@smallexample
+@group
+ . ...
+ .. . b. . . .
+1* ...............
+ . . . .
+@end group
+@end smallexample
+
+@noindent
+Every character not part of the sub-formula @samp{b} has been changed
+to a dot. The @samp{*} next to the line number is to remind you that
+the formula has a portion of it selected. (In this case, it's very
+obvious, but it might not always be. If Embedded mode is enabled,
+the word @samp{Sel} also appears in the mode line because the stack
+may not be visible. @pxref{Embedded Mode}.)
+
+If you had instead placed the cursor on the parenthesis immediately to
+the right of the @samp{b}, the selection would have been:
+
+@smallexample
+@group
+ . ...
+ (a + b) . . .
+1* ...............
+ . . . .
+@end group
+@end smallexample
+
+@noindent
+The portion selected is always large enough to be considered a complete
+formula all by itself, so selecting the parenthesis selects the whole
+formula that it encloses. Putting the cursor on the @samp{+} sign
+would have had the same effect.
+
+(Strictly speaking, the Emacs cursor is really the manifestation of
+the Emacs ``point,'' which is a position @emph{between} two characters
+in the buffer. So purists would say that Calc selects the smallest
+sub-formula which contains the character to the right of ``point.'')
+
+If you supply a numeric prefix argument @var{n}, the selection is
+expanded to the @var{n}th enclosing sub-formula. Thus, positioning
+the cursor on the @samp{b} and typing @kbd{C-u 1 j s} will select
+@samp{a + b}; typing @kbd{C-u 2 j s} will select @samp{(a + b)^3},
+and so on.
+
+If the cursor is not on any part of the formula, or if you give a
+numeric prefix that is too large, the entire formula is selected.
+
+If the cursor is on the @samp{.} line that marks the top of the stack
+(i.e., its normal ``rest position''), this command selects the entire
+formula at stack level 1. Most selection commands similarly operate
+on the formula at the top of the stack if you haven't positioned the
+cursor on any stack entry.
+
+@kindex j a
+@pindex calc-select-additional
+The @kbd{j a} (@code{calc-select-additional}) command enlarges the
+current selection to encompass the cursor. To select the smallest
+sub-formula defined by two different points, move to the first and
+press @kbd{j s}, then move to the other and press @kbd{j a}. This
+is roughly analogous to using @kbd{C-@@} (@code{set-mark-command}) to
+select the two ends of a region of text during normal Emacs editing.
+
+@kindex j o
+@pindex calc-select-once
+The @kbd{j o} (@code{calc-select-once}) command selects a formula in
+exactly the same way as @kbd{j s}, except that the selection will
+last only as long as the next command that uses it. For example,
+@kbd{j o 1 +} is a handy way to add one to the sub-formula indicated
+by the cursor.
+
+(A somewhat more precise definition: The @kbd{j o} command sets a flag
+such that the next command involving selected stack entries will clear
+the selections on those stack entries afterwards. All other selection
+commands except @kbd{j a} and @kbd{j O} clear this flag.)
+
+@kindex j S
+@kindex j O
+@pindex calc-select-here-maybe
+@pindex calc-select-once-maybe
+The @kbd{j S} (@code{calc-select-here-maybe}) and @kbd{j O}
+(@code{calc-select-once-maybe}) commands are equivalent to @kbd{j s}
+and @kbd{j o}, respectively, except that if the formula already
+has a selection they have no effect. This is analogous to the
+behavior of some commands such as @kbd{j r} (@code{calc-rewrite-selection};
+@pxref{Selections with Rewrite Rules}) and is mainly intended to be
+used in keyboard macros that implement your own selection-oriented
+commands.
+
+Selection of sub-formulas normally treats associative terms like
+@samp{a + b - c + d} and @samp{x * y * z} as single levels of the formula.
+If you place the cursor anywhere inside @samp{a + b - c + d} except
+on one of the variable names and use @kbd{j s}, you will select the
+entire four-term sum.
+
+@kindex j b
+@pindex calc-break-selections
+The @kbd{j b} (@code{calc-break-selections}) command controls a mode
+in which the ``deep structure'' of these associative formulas shows
+through. Calc actually stores the above formulas as @samp{((a + b) - c) + d}
+and @samp{x * (y * z)}. (Note that for certain obscure reasons, Calc
+treats multiplication as right-associative.) Once you have enabled
+@kbd{j b} mode, selecting with the cursor on the @samp{-} sign would
+only select the @samp{a + b - c} portion, which makes sense when the
+deep structure of the sum is considered. There is no way to select
+the @samp{b - c + d} portion; although this might initially look
+like just as legitimate a sub-formula as @samp{a + b - c}, the deep
+structure shows that it isn't. The @kbd{d U} command can be used
+to view the deep structure of any formula (@pxref{Normal Language Modes}).
+
+When @kbd{j b} mode has not been enabled, the deep structure is
+generally hidden by the selection commands---what you see is what
+you get.
+
+@kindex j u
+@pindex calc-unselect
+The @kbd{j u} (@code{calc-unselect}) command unselects the formula
+that the cursor is on. If there was no selection in the formula,
+this command has no effect. With a numeric prefix argument, it
+unselects the @var{n}th stack element rather than using the cursor
+position.
+
+@kindex j c
+@pindex calc-clear-selections
+The @kbd{j c} (@code{calc-clear-selections}) command unselects all
+stack elements.
+
+@node Changing Selections, Displaying Selections, Making Selections, Selecting Subformulas
+@subsection Changing Selections
+
+@noindent
+@kindex j m
+@pindex calc-select-more
+Once you have selected a sub-formula, you can expand it using the
+@w{@kbd{j m}} (@code{calc-select-more}) command. If @samp{a + b} is
+selected, pressing @w{@kbd{j m}} repeatedly works as follows:
+
+@smallexample
+@group
+ 3 ... 3 ___ 3 ___
+ (a + b) . . . (a + b) + V c (a + b) + V c
+1* ............... 1* ............... 1* ---------------
+ . . . . . . . . 2 x + 1
+@end group
+@end smallexample
+
+@noindent
+In the last example, the entire formula is selected. This is roughly
+the same as having no selection at all, but because there are subtle
+differences the @samp{*} character is still there on the line number.
+
+With a numeric prefix argument @var{n}, @kbd{j m} expands @var{n}
+times (or until the entire formula is selected). Note that @kbd{j s}
+with argument @var{n} is equivalent to plain @kbd{j s} followed by
+@kbd{j m} with argument @var{n}. If @w{@kbd{j m}} is used when there
+is no current selection, it is equivalent to @w{@kbd{j s}}.
+
+Even though @kbd{j m} does not explicitly use the location of the
+cursor within the formula, it nevertheless uses the cursor to determine
+which stack element to operate on. As usual, @kbd{j m} when the cursor
+is not on any stack element operates on the top stack element.
+
+@kindex j l
+@pindex calc-select-less
+The @kbd{j l} (@code{calc-select-less}) command reduces the current
+selection around the cursor position. That is, it selects the
+immediate sub-formula of the current selection which contains the
+cursor, the opposite of @kbd{j m}. If the cursor is not inside the
+current selection, the command de-selects the formula.
+
+@kindex j 1-9
+@pindex calc-select-part
+The @kbd{j 1} through @kbd{j 9} (@code{calc-select-part}) commands
+select the @var{n}th sub-formula of the current selection. They are
+like @kbd{j l} (@code{calc-select-less}) except they use counting
+rather than the cursor position to decide which sub-formula to select.
+For example, if the current selection is @kbd{a + b + c} or
+@kbd{f(a, b, c)} or @kbd{[a, b, c]}, then @kbd{j 1} selects @samp{a},
+@kbd{j 2} selects @samp{b}, and @kbd{j 3} selects @samp{c}; in each of
+these cases, @kbd{j 4} through @kbd{j 9} would be errors.
+
+If there is no current selection, @kbd{j 1} through @kbd{j 9} select
+the @var{n}th top-level sub-formula. (In other words, they act as if
+the entire stack entry were selected first.) To select the @var{n}th
+sub-formula where @var{n} is greater than nine, you must instead invoke
+@w{@kbd{j 1}} with @var{n} as a numeric prefix argument.
+
+@kindex j n
+@kindex j p
+@pindex calc-select-next
+@pindex calc-select-previous
+The @kbd{j n} (@code{calc-select-next}) and @kbd{j p}
+(@code{calc-select-previous}) commands change the current selection
+to the next or previous sub-formula at the same level. For example,
+if @samp{b} is selected in @w{@samp{2 + a*b*c + x}}, then @kbd{j n}
+selects @samp{c}. Further @kbd{j n} commands would be in error because,
+even though there is something to the right of @samp{c} (namely, @samp{x}),
+it is not at the same level; in this case, it is not a term of the
+same product as @samp{b} and @samp{c}. However, @kbd{j m} (to select
+the whole product @samp{a*b*c} as a term of the sum) followed by
+@w{@kbd{j n}} would successfully select the @samp{x}.
+
+Similarly, @kbd{j p} moves the selection from the @samp{b} in this
+sample formula to the @samp{a}. Both commands accept numeric prefix
+arguments to move several steps at a time.
+
+It is interesting to compare Calc's selection commands with the
+Emacs Info system's commands for navigating through hierarchically
+organized documentation. Calc's @kbd{j n} command is completely
+analogous to Info's @kbd{n} command. Likewise, @kbd{j p} maps to
+@kbd{p}, @kbd{j 2} maps to @kbd{2}, and Info's @kbd{u} is like @kbd{j m}.
+(Note that @kbd{j u} stands for @code{calc-unselect}, not ``up''.)
+The Info @kbd{m} command is somewhat similar to Calc's @kbd{j s} and
+@kbd{j l}; in each case, you can jump directly to a sub-component
+of the hierarchy simply by pointing to it with the cursor.
+
+@node Displaying Selections, Operating on Selections, Changing Selections, Selecting Subformulas
+@subsection Displaying Selections
+
+@noindent
+@kindex j d
+@pindex calc-show-selections
+The @kbd{j d} (@code{calc-show-selections}) command controls how
+selected sub-formulas are displayed. One of the alternatives is
+illustrated in the above examples; if we press @kbd{j d} we switch
+to the other style in which the selected portion itself is obscured
+by @samp{#} signs:
+
+@smallexample
+@group
+ 3 ... # ___
+ (a + b) . . . ## # ## + V c
+1* ............... 1* ---------------
+ . . . . 2 x + 1
+@end group
+@end smallexample
+
+@node Operating on Selections, Rearranging with Selections, Displaying Selections, Selecting Subformulas
+@subsection Operating on Selections
+
+@noindent
+Once a selection is made, all Calc commands that manipulate items
+on the stack will operate on the selected portions of the items
+instead. (Note that several stack elements may have selections
+at once, though there can be only one selection at a time in any
+given stack element.)
+
+@kindex j e
+@pindex calc-enable-selections
+The @kbd{j e} (@code{calc-enable-selections}) command disables the
+effect that selections have on Calc commands. The current selections
+still exist, but Calc commands operate on whole stack elements anyway.
+This mode can be identified by the fact that the @samp{*} markers on
+the line numbers are gone, even though selections are visible. To
+reactivate the selections, press @kbd{j e} again.
+
+To extract a sub-formula as a new formula, simply select the
+sub-formula and press @key{RET}. This normally duplicates the top
+stack element; here it duplicates only the selected portion of that
+element.
+
+To replace a sub-formula with something different, you can enter the
+new value onto the stack and press @key{TAB}. This normally exchanges
+the top two stack elements; here it swaps the value you entered into
+the selected portion of the formula, returning the old selected
+portion to the top of the stack.
+
+@smallexample
+@group
+ 3 ... ... ___
+ (a + b) . . . 17 x y . . . 17 x y + V c
+2* ............... 2* ............. 2: -------------
+ . . . . . . . . 2 x + 1
+
+ 3 3
+1: 17 x y 1: (a + b) 1: (a + b)
+@end group
+@end smallexample
+
+In this example we select a sub-formula of our original example,
+enter a new formula, @key{TAB} it into place, then deselect to see
+the complete, edited formula.
+
+If you want to swap whole formulas around even though they contain
+selections, just use @kbd{j e} before and after.
+
+@kindex j '
+@pindex calc-enter-selection
+The @kbd{j '} (@code{calc-enter-selection}) command is another way
+to replace a selected sub-formula. This command does an algebraic
+entry just like the regular @kbd{'} key. When you press @key{RET},
+the formula you type replaces the original selection. You can use
+the @samp{$} symbol in the formula to refer to the original
+selection. If there is no selection in the formula under the cursor,
+the cursor is used to make a temporary selection for the purposes of
+the command. Thus, to change a term of a formula, all you have to
+do is move the Emacs cursor to that term and press @kbd{j '}.
+
+@kindex j `
+@pindex calc-edit-selection
+The @kbd{j `} (@code{calc-edit-selection}) command is a similar
+analogue of the @kbd{`} (@code{calc-edit}) command. It edits the
+selected sub-formula in a separate buffer. If there is no
+selection, it edits the sub-formula indicated by the cursor.
+
+To delete a sub-formula, press @key{DEL}. This generally replaces
+the sub-formula with the constant zero, but in a few suitable contexts
+it uses the constant one instead. The @key{DEL} key automatically
+deselects and re-simplifies the entire formula afterwards. Thus:
+
+@smallexample
+@group
+ ###
+ 17 x y + # # 17 x y 17 # y 17 y
+1* ------------- 1: ------- 1* ------- 1: -------
+ 2 x + 1 2 x + 1 2 x + 1 2 x + 1
+@end group
+@end smallexample
+
+In this example, we first delete the @samp{sqrt(c)} term; Calc
+accomplishes this by replacing @samp{sqrt(c)} with zero and
+resimplifying. We then delete the @kbd{x} in the numerator;
+since this is part of a product, Calc replaces it with @samp{1}
+and resimplifies.
+
+If you select an element of a vector and press @key{DEL}, that
+element is deleted from the vector. If you delete one side of
+an equation or inequality, only the opposite side remains.
+
+@kindex j @key{DEL}
+@pindex calc-del-selection
+The @kbd{j @key{DEL}} (@code{calc-del-selection}) command is like
+@key{DEL} but with the auto-selecting behavior of @kbd{j '} and
+@kbd{j `}. It deletes the selected portion of the formula
+indicated by the cursor, or, in the absence of a selection, it
+deletes the sub-formula indicated by the cursor position.
+
+@kindex j @key{RET}
+@pindex calc-grab-selection
+(There is also an auto-selecting @kbd{j @key{RET}} (@code{calc-copy-selection})
+command.)
+
+Normal arithmetic operations also apply to sub-formulas. Here we
+select the denominator, press @kbd{5 -} to subtract five from the
+denominator, press @kbd{n} to negate the denominator, then
+press @kbd{Q} to take the square root.
+
+@smallexample
+@group
+ .. . .. . .. . .. .
+1* ....... 1* ....... 1* ....... 1* ..........
+ 2 x + 1 2 x - 4 4 - 2 x _________
+ V 4 - 2 x
+@end group
+@end smallexample
+
+Certain types of operations on selections are not allowed. For
+example, for an arithmetic function like @kbd{-} no more than one of
+the arguments may be a selected sub-formula. (As the above example
+shows, the result of the subtraction is spliced back into the argument
+which had the selection; if there were more than one selection involved,
+this would not be well-defined.) If you try to subtract two selections,
+the command will abort with an error message.
+
+Operations on sub-formulas sometimes leave the formula as a whole
+in an ``un-natural'' state. Consider negating the @samp{2 x} term
+of our sample formula by selecting it and pressing @kbd{n}
+(@code{calc-change-sign}).
+
+@smallexample
+@group
+ .. . .. .
+1* .......... 1* ...........
+ ......... ..........
+ . . . 2 x . . . -2 x
+@end group
+@end smallexample
+
+Unselecting the sub-formula reveals that the minus sign, which would
+normally have cancelled out with the subtraction automatically, has
+not been able to do so because the subtraction was not part of the
+selected portion. Pressing @kbd{=} (@code{calc-evaluate}) or doing
+any other mathematical operation on the whole formula will cause it
+to be simplified.
+
+@smallexample
+@group
+ 17 y 17 y
+1: ----------- 1: ----------
+ __________ _________
+ V 4 - -2 x V 4 + 2 x
+@end group
+@end smallexample
+
+@node Rearranging with Selections, , Operating on Selections, Selecting Subformulas
+@subsection Rearranging Formulas using Selections
+
+@noindent
+@kindex j R
+@pindex calc-commute-right
+The @kbd{j R} (@code{calc-commute-right}) command moves the selected
+sub-formula to the right in its surrounding formula. Generally the
+selection is one term of a sum or product; the sum or product is
+rearranged according to the commutative laws of algebra.
+
+As with @kbd{j '} and @kbd{j @key{DEL}}, the term under the cursor is used
+if there is no selection in the current formula. All commands described
+in this section share this property. In this example, we place the
+cursor on the @samp{a} and type @kbd{j R}, then repeat.
+
+@smallexample
+1: a + b - c 1: b + a - c 1: b - c + a
+@end smallexample
+
+@noindent
+Note that in the final step above, the @samp{a} is switched with
+the @samp{c} but the signs are adjusted accordingly. When moving
+terms of sums and products, @kbd{j R} will never change the
+mathematical meaning of the formula.
+
+The selected term may also be an element of a vector or an argument
+of a function. The term is exchanged with the one to its right.
+In this case, the ``meaning'' of the vector or function may of
+course be drastically changed.
+
+@smallexample
+1: [a, b, c] 1: [b, a, c] 1: [b, c, a]
+
+1: f(a, b, c) 1: f(b, a, c) 1: f(b, c, a)
+@end smallexample
+
+@kindex j L
+@pindex calc-commute-left
+The @kbd{j L} (@code{calc-commute-left}) command is like @kbd{j R}
+except that it swaps the selected term with the one to its left.
+
+With numeric prefix arguments, these commands move the selected
+term several steps at a time. It is an error to try to move a
+term left or right past the end of its enclosing formula.
+With numeric prefix arguments of zero, these commands move the
+selected term as far as possible in the given direction.
+
+@kindex j D
+@pindex calc-sel-distribute
+The @kbd{j D} (@code{calc-sel-distribute}) command mixes the selected
+sum or product into the surrounding formula using the distributive
+law. For example, in @samp{a * (b - c)} with the @samp{b - c}
+selected, the result is @samp{a b - a c}. This also distributes
+products or quotients into surrounding powers, and can also do
+transformations like @samp{exp(a + b)} to @samp{exp(a) exp(b)},
+where @samp{a + b} is the selected term, and @samp{ln(a ^ b)}
+to @samp{ln(a) b}, where @samp{a ^ b} is the selected term.
+
+For multiple-term sums or products, @kbd{j D} takes off one term
+at a time: @samp{a * (b + c - d)} goes to @samp{a * (c - d) + a b}
+with the @samp{c - d} selected so that you can type @kbd{j D}
+repeatedly to expand completely. The @kbd{j D} command allows a
+numeric prefix argument which specifies the maximum number of
+times to expand at once; the default is one time only.
+
+@vindex DistribRules
+The @kbd{j D} command is implemented using rewrite rules.
+@xref{Selections with Rewrite Rules}. The rules are stored in
+the Calc variable @code{DistribRules}. A convenient way to view
+these rules is to use @kbd{s e} (@code{calc-edit-variable}) which
+displays and edits the stored value of a variable. Press @kbd{C-c C-c}
+to return from editing mode; be careful not to make any actual changes
+or else you will affect the behavior of future @kbd{j D} commands!
+
+To extend @kbd{j D} to handle new cases, just edit @code{DistribRules}
+as described above. You can then use the @kbd{s p} command to save
+this variable's value permanently for future Calc sessions.
+@xref{Operations on Variables}.
+
+@kindex j M
+@pindex calc-sel-merge
+@vindex MergeRules
+The @kbd{j M} (@code{calc-sel-merge}) command is the complement
+of @kbd{j D}; given @samp{a b - a c} with either @samp{a b} or
+@samp{a c} selected, the result is @samp{a * (b - c)}. Once
+again, @kbd{j M} can also merge calls to functions like @code{exp}
+and @code{ln}; examine the variable @code{MergeRules} to see all
+the relevant rules.
+
+@kindex j C
+@pindex calc-sel-commute
+@vindex CommuteRules
+The @kbd{j C} (@code{calc-sel-commute}) command swaps the arguments
+of the selected sum, product, or equation. It always behaves as
+if @kbd{j b} mode were in effect, i.e., the sum @samp{a + b + c} is
+treated as the nested sums @samp{(a + b) + c} by this command.
+If you put the cursor on the first @samp{+}, the result is
+@samp{(b + a) + c}; if you put the cursor on the second @samp{+}, the
+result is @samp{c + (a + b)} (which the default simplifications
+will rearrange to @samp{(c + a) + b}). The relevant rules are stored
+in the variable @code{CommuteRules}.
+
+You may need to turn default simplifications off (with the @kbd{m O}
+command) in order to get the full benefit of @kbd{j C}. For example,
+commuting @samp{a - b} produces @samp{-b + a}, but the default
+simplifications will ``simplify'' this right back to @samp{a - b} if
+you don't turn them off. The same is true of some of the other
+manipulations described in this section.
+
+@kindex j N
+@pindex calc-sel-negate
+@vindex NegateRules
+The @kbd{j N} (@code{calc-sel-negate}) command replaces the selected
+term with the negative of that term, then adjusts the surrounding
+formula in order to preserve the meaning. For example, given
+@samp{exp(a - b)} where @samp{a - b} is selected, the result is
+@samp{1 / exp(b - a)}. By contrast, selecting a term and using the
+regular @kbd{n} (@code{calc-change-sign}) command negates the
+term without adjusting the surroundings, thus changing the meaning
+of the formula as a whole. The rules variable is @code{NegateRules}.
+
+@kindex j &
+@pindex calc-sel-invert
+@vindex InvertRules
+The @kbd{j &} (@code{calc-sel-invert}) command is similar to @kbd{j N}
+except it takes the reciprocal of the selected term. For example,
+given @samp{a - ln(b)} with @samp{b} selected, the result is
+@samp{a + ln(1/b)}. The rules variable is @code{InvertRules}.
+
+@kindex j E
+@pindex calc-sel-jump-equals
+@vindex JumpRules
+The @kbd{j E} (@code{calc-sel-jump-equals}) command moves the
+selected term from one side of an equation to the other. Given
+@samp{a + b = c + d} with @samp{c} selected, the result is
+@samp{a + b - c = d}. This command also works if the selected
+term is part of a @samp{*}, @samp{/}, or @samp{^} formula. The
+relevant rules variable is @code{JumpRules}.
+
+@kindex j I
+@kindex H j I
+@pindex calc-sel-isolate
+The @kbd{j I} (@code{calc-sel-isolate}) command isolates the
+selected term on its side of an equation. It uses the @kbd{a S}
+(@code{calc-solve-for}) command to solve the equation, and the
+Hyperbolic flag affects it in the same way. @xref{Solving Equations}.
+When it applies, @kbd{j I} is often easier to use than @kbd{j E}.
+It understands more rules of algebra, and works for inequalities
+as well as equations.
+
+@kindex j *
+@kindex j /
+@pindex calc-sel-mult-both-sides
+@pindex calc-sel-div-both-sides
+The @kbd{j *} (@code{calc-sel-mult-both-sides}) command prompts for a
+formula using algebraic entry, then multiplies both sides of the
+selected quotient or equation by that formula. It simplifies each
+side with @kbd{a s} (@code{calc-simplify}) before re-forming the
+quotient or equation. You can suppress this simplification by
+providing any numeric prefix argument. There is also a @kbd{j /}
+(@code{calc-sel-div-both-sides}) which is similar to @kbd{j *} but
+dividing instead of multiplying by the factor you enter.
+
+As a special feature, if the numerator of the quotient is 1, then
+the denominator is expanded at the top level using the distributive
+law (i.e., using the @kbd{C-u -1 a x} command). Suppose the
+formula on the stack is @samp{1 / (sqrt(a) + 1)}, and you wish
+to eliminate the square root in the denominator by multiplying both
+sides by @samp{sqrt(a) - 1}. Calc's default simplifications would
+change the result @samp{(sqrt(a) - 1) / (sqrt(a) - 1) (sqrt(a) + 1)}
+right back to the original form by cancellation; Calc expands the
+denominator to @samp{sqrt(a) (sqrt(a) - 1) + sqrt(a) - 1} to prevent
+this. (You would now want to use an @kbd{a x} command to expand
+the rest of the way, whereupon the denominator would cancel out to
+the desired form, @samp{a - 1}.) When the numerator is not 1, this
+initial expansion is not necessary because Calc's default
+simplifications will not notice the potential cancellation.
+
+If the selection is an inequality, @kbd{j *} and @kbd{j /} will
+accept any factor, but will warn unless they can prove the factor
+is either positive or negative. (In the latter case the direction
+of the inequality will be switched appropriately.) @xref{Declarations},
+for ways to inform Calc that a given variable is positive or
+negative. If Calc can't tell for sure what the sign of the factor
+will be, it will assume it is positive and display a warning
+message.
+
+For selections that are not quotients, equations, or inequalities,
+these commands pull out a multiplicative factor: They divide (or
+multiply) by the entered formula, simplify, then multiply (or divide)
+back by the formula.
+
+@kindex j +
+@kindex j -
+@pindex calc-sel-add-both-sides
+@pindex calc-sel-sub-both-sides
+The @kbd{j +} (@code{calc-sel-add-both-sides}) and @kbd{j -}
+(@code{calc-sel-sub-both-sides}) commands analogously add to or
+subtract from both sides of an equation or inequality. For other
+types of selections, they extract an additive factor. A numeric
+prefix argument suppresses simplification of the intermediate
+results.
+
+@kindex j U
+@pindex calc-sel-unpack
+The @kbd{j U} (@code{calc-sel-unpack}) command replaces the
+selected function call with its argument. For example, given
+@samp{a + sin(x^2)} with @samp{sin(x^2)} selected, the result
+is @samp{a + x^2}. (The @samp{x^2} will remain selected; if you
+wanted to change the @code{sin} to @code{cos}, just press @kbd{C}
+now to take the cosine of the selected part.)
+
+@kindex j v
+@pindex calc-sel-evaluate
+The @kbd{j v} (@code{calc-sel-evaluate}) command performs the
+normal default simplifications on the selected sub-formula.
+These are the simplifications that are normally done automatically
+on all results, but which may have been partially inhibited by
+previous selection-related operations, or turned off altogether
+by the @kbd{m O} command. This command is just an auto-selecting
+version of the @w{@kbd{a v}} command (@pxref{Algebraic Manipulation}).
+
+With a numeric prefix argument of 2, @kbd{C-u 2 j v} applies
+the @kbd{a s} (@code{calc-simplify}) command to the selected
+sub-formula. With a prefix argument of 3 or more, e.g., @kbd{C-u j v}
+applies the @kbd{a e} (@code{calc-simplify-extended}) command.
+@xref{Simplifying Formulas}. With a negative prefix argument
+it simplifies at the top level only, just as with @kbd{a v}.
+Here the ``top'' level refers to the top level of the selected
+sub-formula.
+
+@kindex j "
+@pindex calc-sel-expand-formula
+The @kbd{j "} (@code{calc-sel-expand-formula}) command is to @kbd{a "}
+(@pxref{Algebraic Manipulation}) what @kbd{j v} is to @kbd{a v}.
+
+You can use the @kbd{j r} (@code{calc-rewrite-selection}) command
+to define other algebraic operations on sub-formulas. @xref{Rewrite Rules}.
+
+@node Algebraic Manipulation, Simplifying Formulas, Selecting Subformulas, Algebra
+@section Algebraic Manipulation
+
+@noindent
+The commands in this section perform general-purpose algebraic
+manipulations. They work on the whole formula at the top of the
+stack (unless, of course, you have made a selection in that
+formula).
+
+Many algebra commands prompt for a variable name or formula. If you
+answer the prompt with a blank line, the variable or formula is taken
+from top-of-stack, and the normal argument for the command is taken
+from the second-to-top stack level.
+
+@kindex a v
+@pindex calc-alg-evaluate
+The @kbd{a v} (@code{calc-alg-evaluate}) command performs the normal
+default simplifications on a formula; for example, @samp{a - -b} is
+changed to @samp{a + b}. These simplifications are normally done
+automatically on all Calc results, so this command is useful only if
+you have turned default simplifications off with an @kbd{m O}
+command. @xref{Simplification Modes}.
+
+It is often more convenient to type @kbd{=}, which is like @kbd{a v}
+but which also substitutes stored values for variables in the formula.
+Use @kbd{a v} if you want the variables to ignore their stored values.
+
+If you give a numeric prefix argument of 2 to @kbd{a v}, it simplifies
+as if in Algebraic Simplification mode. This is equivalent to typing
+@kbd{a s}; @pxref{Simplifying Formulas}. If you give a numeric prefix
+of 3 or more, it uses Extended Simplification mode (@kbd{a e}).
+
+If you give a negative prefix argument @mathit{-1}, @mathit{-2}, or @mathit{-3},
+it simplifies in the corresponding mode but only works on the top-level
+function call of the formula. For example, @samp{(2 + 3) * (2 + 3)} will
+simplify to @samp{(2 + 3)^2}, without simplifying the sub-formulas
+@samp{2 + 3}. As another example, typing @kbd{V R +} to sum the vector
+@samp{[1, 2, 3, 4]} produces the formula @samp{reduce(add, [1, 2, 3, 4])}
+in No-Simplify mode. Using @kbd{a v} will evaluate this all the way to
+10; using @kbd{C-u - a v} will evaluate it only to @samp{1 + 2 + 3 + 4}.
+(@xref{Reducing and Mapping}.)
+
+@tindex evalv
+@tindex evalvn
+The @kbd{=} command corresponds to the @code{evalv} function, and
+the related @kbd{N} command, which is like @kbd{=} but temporarily
+disables Symbolic mode (@kbd{m s}) during the evaluation, corresponds
+to the @code{evalvn} function. (These commands interpret their prefix
+arguments differently than @kbd{a v}; @kbd{=} treats the prefix as
+the number of stack elements to evaluate at once, and @kbd{N} treats
+it as a temporary different working precision.)
+
+The @code{evalvn} function can take an alternate working precision
+as an optional second argument. This argument can be either an
+integer, to set the precision absolutely, or a vector containing
+a single integer, to adjust the precision relative to the current
+precision. Note that @code{evalvn} with a larger than current
+precision will do the calculation at this higher precision, but the
+result will as usual be rounded back down to the current precision
+afterward. For example, @samp{evalvn(pi - 3.1415)} at a precision
+of 12 will return @samp{9.265359e-5}; @samp{evalvn(pi - 3.1415, 30)}
+will return @samp{9.26535897932e-5} (computing a 25-digit result which
+is then rounded down to 12); and @samp{evalvn(pi - 3.1415, [-2])}
+will return @samp{9.2654e-5}.
+
+@kindex a "
+@pindex calc-expand-formula
+The @kbd{a "} (@code{calc-expand-formula}) command expands functions
+into their defining formulas wherever possible. For example,
+@samp{deg(x^2)} is changed to @samp{180 x^2 / pi}. Most functions,
+like @code{sin} and @code{gcd}, are not defined by simple formulas
+and so are unaffected by this command. One important class of
+functions which @emph{can} be expanded is the user-defined functions
+created by the @kbd{Z F} command. @xref{Algebraic Definitions}.
+Other functions which @kbd{a "} can expand include the probability
+distribution functions, most of the financial functions, and the
+hyperbolic and inverse hyperbolic functions. A numeric prefix argument
+affects @kbd{a "} in the same way as it does @kbd{a v}: A positive
+argument expands all functions in the formula and then simplifies in
+various ways; a negative argument expands and simplifies only the
+top-level function call.
+
+@kindex a M
+@pindex calc-map-equation
+@tindex mapeq
+The @kbd{a M} (@code{calc-map-equation}) [@code{mapeq}] command applies
+a given function or operator to one or more equations. It is analogous
+to @kbd{V M}, which operates on vectors instead of equations.
+@pxref{Reducing and Mapping}. For example, @kbd{a M S} changes
+@samp{x = y+1} to @samp{sin(x) = sin(y+1)}, and @kbd{a M +} with
+@samp{x = y+1} and @expr{6} on the stack produces @samp{x+6 = y+7}.
+With two equations on the stack, @kbd{a M +} would add the lefthand
+sides together and the righthand sides together to get the two
+respective sides of a new equation.
+
+Mapping also works on inequalities. Mapping two similar inequalities
+produces another inequality of the same type. Mapping an inequality
+with an equation produces an inequality of the same type. Mapping a
+@samp{<=} with a @samp{<} or @samp{!=} (not-equal) produces a @samp{<}.
+If inequalities with opposite direction (e.g., @samp{<} and @samp{>})
+are mapped, the direction of the second inequality is reversed to
+match the first: Using @kbd{a M +} on @samp{a < b} and @samp{a > 2}
+reverses the latter to get @samp{2 < a}, which then allows the
+combination @samp{a + 2 < b + a}, which the @kbd{a s} command can
+then simplify to get @samp{2 < b}.
+
+Using @kbd{a M *}, @kbd{a M /}, @kbd{a M n}, or @kbd{a M &} to negate
+or invert an inequality will reverse the direction of the inequality.
+Other adjustments to inequalities are @emph{not} done automatically;
+@kbd{a M S} will change @w{@samp{x < y}} to @samp{sin(x) < sin(y)} even
+though this is not true for all values of the variables.
+
+@kindex H a M
+@tindex mapeqp
+With the Hyperbolic flag, @kbd{H a M} [@code{mapeqp}] does a plain
+mapping operation without reversing the direction of any inequalities.
+Thus, @kbd{H a M &} would change @kbd{x > 2} to @kbd{1/x > 0.5}.
+(This change is mathematically incorrect, but perhaps you were
+fixing an inequality which was already incorrect.)
+
+@kindex I a M
+@tindex mapeqr
+With the Inverse flag, @kbd{I a M} [@code{mapeqr}] always reverses
+the direction of the inequality. You might use @kbd{I a M C} to
+change @samp{x < y} to @samp{cos(x) > cos(y)} if you know you are
+working with small positive angles.
+
+@kindex a b
+@pindex calc-substitute
+@tindex subst
+The @kbd{a b} (@code{calc-substitute}) [@code{subst}] command substitutes
+all occurrences
+of some variable or sub-expression of an expression with a new
+sub-expression. For example, substituting @samp{sin(x)} with @samp{cos(y)}
+in @samp{2 sin(x)^2 + x sin(x) + sin(2 x)} produces
+@samp{2 cos(y)^2 + x cos(y) + @w{sin(2 x)}}.
+Note that this is a purely structural substitution; the lone @samp{x} and
+the @samp{sin(2 x)} stayed the same because they did not look like
+@samp{sin(x)}. @xref{Rewrite Rules}, for a more general method for
+doing substitutions.
+
+The @kbd{a b} command normally prompts for two formulas, the old
+one and the new one. If you enter a blank line for the first
+prompt, all three arguments are taken from the stack (new, then old,
+then target expression). If you type an old formula but then enter a
+blank line for the new one, the new formula is taken from top-of-stack
+and the target from second-to-top. If you answer both prompts, the
+target is taken from top-of-stack as usual.
+
+Note that @kbd{a b} has no understanding of commutativity or
+associativity. The pattern @samp{x+y} will not match the formula
+@samp{y+x}. Also, @samp{y+z} will not match inside the formula @samp{x+y+z}
+because the @samp{+} operator is left-associative, so the ``deep
+structure'' of that formula is @samp{(x+y) + z}. Use @kbd{d U}
+(@code{calc-unformatted-language}) mode to see the true structure of
+a formula. The rewrite rule mechanism, discussed later, does not have
+these limitations.
+
+As an algebraic function, @code{subst} takes three arguments:
+Target expression, old, new. Note that @code{subst} is always
+evaluated immediately, even if its arguments are variables, so if
+you wish to put a call to @code{subst} onto the stack you must
+turn the default simplifications off first (with @kbd{m O}).
+
+@node Simplifying Formulas, Polynomials, Algebraic Manipulation, Algebra
+@section Simplifying Formulas
+
+@noindent
+@kindex a s
+@pindex calc-simplify
+@tindex simplify
+The @kbd{a s} (@code{calc-simplify}) [@code{simplify}] command applies
+various algebraic rules to simplify a formula. This includes rules which
+are not part of the default simplifications because they may be too slow
+to apply all the time, or may not be desirable all of the time. For
+example, non-adjacent terms of sums are combined, as in @samp{a + b + 2 a}
+to @samp{b + 3 a}, and some formulas like @samp{sin(arcsin(x))} are
+simplified to @samp{x}.
+
+The sections below describe all the various kinds of algebraic
+simplifications Calc provides in full detail. None of Calc's
+simplification commands are designed to pull rabbits out of hats;
+they simply apply certain specific rules to put formulas into
+less redundant or more pleasing forms. Serious algebra in Calc
+must be done manually, usually with a combination of selections
+and rewrite rules. @xref{Rearranging with Selections}.
+@xref{Rewrite Rules}.
+
+@xref{Simplification Modes}, for commands to control what level of
+simplification occurs automatically. Normally only the ``default
+simplifications'' occur.
+
+@menu
+* Default Simplifications::
+* Algebraic Simplifications::
+* Unsafe Simplifications::
+* Simplification of Units::
+@end menu
+
+@node Default Simplifications, Algebraic Simplifications, Simplifying Formulas, Simplifying Formulas
+@subsection Default Simplifications
+
+@noindent
+@cindex Default simplifications
+This section describes the ``default simplifications,'' those which are
+normally applied to all results. For example, if you enter the variable
+@expr{x} on the stack twice and push @kbd{+}, Calc's default
+simplifications automatically change @expr{x + x} to @expr{2 x}.
+
+The @kbd{m O} command turns off the default simplifications, so that
+@expr{x + x} will remain in this form unless you give an explicit
+``simplify'' command like @kbd{=} or @kbd{a v}. @xref{Algebraic
+Manipulation}. The @kbd{m D} command turns the default simplifications
+back on.
+
+The most basic default simplification is the evaluation of functions.
+For example, @expr{2 + 3} is evaluated to @expr{5}, and @expr{@tfn{sqrt}(9)}
+is evaluated to @expr{3}. Evaluation does not occur if the arguments
+to a function are somehow of the wrong type @expr{@tfn{tan}([2,3,4])}),
+range (@expr{@tfn{tan}(90)}), or number (@expr{@tfn{tan}(3,5)}),
+or if the function name is not recognized (@expr{@tfn{f}(5)}), or if
+Symbolic mode (@pxref{Symbolic Mode}) prevents evaluation
+(@expr{@tfn{sqrt}(2)}).
+
+Calc simplifies (evaluates) the arguments to a function before it
+simplifies the function itself. Thus @expr{@tfn{sqrt}(5+4)} is
+simplified to @expr{@tfn{sqrt}(9)} before the @code{sqrt} function
+itself is applied. There are very few exceptions to this rule:
+@code{quote}, @code{lambda}, and @code{condition} (the @code{::}
+operator) do not evaluate their arguments, @code{if} (the @code{? :}
+operator) does not evaluate all of its arguments, and @code{evalto}
+does not evaluate its lefthand argument.
+
+Most commands apply the default simplifications to all arguments they
+take from the stack, perform a particular operation, then simplify
+the result before pushing it back on the stack. In the common special
+case of regular arithmetic commands like @kbd{+} and @kbd{Q} [@code{sqrt}],
+the arguments are simply popped from the stack and collected into a
+suitable function call, which is then simplified (the arguments being
+simplified first as part of the process, as described above).
+
+The default simplifications are too numerous to describe completely
+here, but this section will describe the ones that apply to the
+major arithmetic operators. This list will be rather technical in
+nature, and will probably be interesting to you only if you are
+a serious user of Calc's algebra facilities.
+
+@tex
+\bigskip
+@end tex
+
+As well as the simplifications described here, if you have stored
+any rewrite rules in the variable @code{EvalRules} then these rules
+will also be applied before any built-in default simplifications.
+@xref{Automatic Rewrites}, for details.
+
+@tex
+\bigskip
+@end tex
+
+And now, on with the default simplifications:
+
+Arithmetic operators like @kbd{+} and @kbd{*} always take two
+arguments in Calc's internal form. Sums and products of three or
+more terms are arranged by the associative law of algebra into
+a left-associative form for sums, @expr{((a + b) + c) + d}, and
+a right-associative form for products, @expr{a * (b * (c * d))}.
+Formulas like @expr{(a + b) + (c + d)} are rearranged to
+left-associative form, though this rarely matters since Calc's
+algebra commands are designed to hide the inner structure of
+sums and products as much as possible. Sums and products in
+their proper associative form will be written without parentheses
+in the examples below.
+
+Sums and products are @emph{not} rearranged according to the
+commutative law (@expr{a + b} to @expr{b + a}) except in a few
+special cases described below. Some algebra programs always
+rearrange terms into a canonical order, which enables them to
+see that @expr{a b + b a} can be simplified to @expr{2 a b}.
+Calc assumes you have put the terms into the order you want
+and generally leaves that order alone, with the consequence
+that formulas like the above will only be simplified if you
+explicitly give the @kbd{a s} command. @xref{Algebraic
+Simplifications}.
+
+Differences @expr{a - b} are treated like sums @expr{a + (-b)}
+for purposes of simplification; one of the default simplifications
+is to rewrite @expr{a + (-b)} or @expr{(-b) + a}, where @expr{-b}
+represents a ``negative-looking'' term, into @expr{a - b} form.
+``Negative-looking'' means negative numbers, negated formulas like
+@expr{-x}, and products or quotients in which either term is
+negative-looking.
+
+Other simplifications involving negation are @expr{-(-x)} to @expr{x};
+@expr{-(a b)} or @expr{-(a/b)} where either @expr{a} or @expr{b} is
+negative-looking, simplified by negating that term, or else where
+@expr{a} or @expr{b} is any number, by negating that number;
+@expr{-(a + b)} to @expr{-a - b}, and @expr{-(b - a)} to @expr{a - b}.
+(This, and rewriting @expr{(-b) + a} to @expr{a - b}, are the only
+cases where the order of terms in a sum is changed by the default
+simplifications.)
+
+The distributive law is used to simplify sums in some cases:
+@expr{a x + b x} to @expr{(a + b) x}, where @expr{a} represents
+a number or an implicit 1 or @mathit{-1} (as in @expr{x} or @expr{-x})
+and similarly for @expr{b}. Use the @kbd{a c}, @w{@kbd{a f}}, or
+@kbd{j M} commands to merge sums with non-numeric coefficients
+using the distributive law.
+
+The distributive law is only used for sums of two terms, or
+for adjacent terms in a larger sum. Thus @expr{a + b + b + c}
+is simplified to @expr{a + 2 b + c}, but @expr{a + b + c + b}
+is not simplified. The reason is that comparing all terms of a
+sum with one another would require time proportional to the
+square of the number of terms; Calc relegates potentially slow
+operations like this to commands that have to be invoked
+explicitly, like @kbd{a s}.
+
+Finally, @expr{a + 0} and @expr{0 + a} are simplified to @expr{a}.
+A consequence of the above rules is that @expr{0 - a} is simplified
+to @expr{-a}.
+
+@tex
+\bigskip
+@end tex
+
+The products @expr{1 a} and @expr{a 1} are simplified to @expr{a};
+@expr{(-1) a} and @expr{a (-1)} are simplified to @expr{-a};
+@expr{0 a} and @expr{a 0} are simplified to @expr{0}, except that
+in Matrix mode where @expr{a} is not provably scalar the result
+is the generic zero matrix @samp{idn(0)}, and that if @expr{a} is
+infinite the result is @samp{nan}.
+
+Also, @expr{(-a) b} and @expr{a (-b)} are simplified to @expr{-(a b)},
+where this occurs for negated formulas but not for regular negative
+numbers.
+
+Products are commuted only to move numbers to the front:
+@expr{a b 2} is commuted to @expr{2 a b}.
+
+The product @expr{a (b + c)} is distributed over the sum only if
+@expr{a} and at least one of @expr{b} and @expr{c} are numbers:
+@expr{2 (x + 3)} goes to @expr{2 x + 6}. The formula
+@expr{(-a) (b - c)}, where @expr{-a} is a negative number, is
+rewritten to @expr{a (c - b)}.
+
+The distributive law of products and powers is used for adjacent
+terms of the product: @expr{x^a x^b} goes to
+@texline @math{x^{a+b}}
+@infoline @expr{x^(a+b)}
+where @expr{a} is a number, or an implicit 1 (as in @expr{x}),
+or the implicit one-half of @expr{@tfn{sqrt}(x)}, and similarly for
+@expr{b}. The result is written using @samp{sqrt} or @samp{1/sqrt}
+if the sum of the powers is @expr{1/2} or @expr{-1/2}, respectively.
+If the sum of the powers is zero, the product is simplified to
+@expr{1} or to @samp{idn(1)} if Matrix mode is enabled.
+
+The product of a negative power times anything but another negative
+power is changed to use division:
+@texline @math{x^{-2} y}
+@infoline @expr{x^(-2) y}
+goes to @expr{y / x^2} unless Matrix mode is
+in effect and neither @expr{x} nor @expr{y} are scalar (in which
+case it is considered unsafe to rearrange the order of the terms).
+
+Finally, @expr{a (b/c)} is rewritten to @expr{(a b)/c}, and also
+@expr{(a/b) c} is changed to @expr{(a c)/b} unless in Matrix mode.
+
+@tex
+\bigskip
+@end tex
+
+Simplifications for quotients are analogous to those for products.
+The quotient @expr{0 / x} is simplified to @expr{0}, with the same
+exceptions that were noted for @expr{0 x}. Likewise, @expr{x / 1}
+and @expr{x / (-1)} are simplified to @expr{x} and @expr{-x},
+respectively.
+
+The quotient @expr{x / 0} is left unsimplified or changed to an
+infinite quantity, as directed by the current infinite mode.
+@xref{Infinite Mode}.
+
+The expression
+@texline @math{a / b^{-c}}
+@infoline @expr{a / b^(-c)}
+is changed to @expr{a b^c}, where @expr{-c} is any negative-looking
+power. Also, @expr{1 / b^c} is changed to
+@texline @math{b^{-c}}
+@infoline @expr{b^(-c)}
+for any power @expr{c}.
+
+Also, @expr{(-a) / b} and @expr{a / (-b)} go to @expr{-(a/b)};
+@expr{(a/b) / c} goes to @expr{a / (b c)}; and @expr{a / (b/c)}
+goes to @expr{(a c) / b} unless Matrix mode prevents this
+rearrangement. Similarly, @expr{a / (b:c)} is simplified to
+@expr{(c:b) a} for any fraction @expr{b:c}.
+
+The distributive law is applied to @expr{(a + b) / c} only if
+@expr{c} and at least one of @expr{a} and @expr{b} are numbers.
+Quotients of powers and square roots are distributed just as
+described for multiplication.
+
+Quotients of products cancel only in the leading terms of the
+numerator and denominator. In other words, @expr{a x b / a y b}
+is cancelled to @expr{x b / y b} but not to @expr{x / y}. Once
+again this is because full cancellation can be slow; use @kbd{a s}
+to cancel all terms of the quotient.
+
+Quotients of negative-looking values are simplified according
+to @expr{(-a) / (-b)} to @expr{a / b}, @expr{(-a) / (b - c)}
+to @expr{a / (c - b)}, and @expr{(a - b) / (-c)} to @expr{(b - a) / c}.
+
+@tex
+\bigskip
+@end tex
+
+The formula @expr{x^0} is simplified to @expr{1}, or to @samp{idn(1)}
+in Matrix mode. The formula @expr{0^x} is simplified to @expr{0}
+unless @expr{x} is a negative number, complex number or zero.
+If @expr{x} is negative, complex or @expr{0.0}, @expr{0^x} is an
+infinity or an unsimplified formula according to the current infinite
+mode. The expression @expr{0^0} is simplified to @expr{1}.
+
+Powers of products or quotients @expr{(a b)^c}, @expr{(a/b)^c}
+are distributed to @expr{a^c b^c}, @expr{a^c / b^c} only if @expr{c}
+is an integer, or if either @expr{a} or @expr{b} are nonnegative
+real numbers. Powers of powers @expr{(a^b)^c} are simplified to
+@texline @math{a^{b c}}
+@infoline @expr{a^(b c)}
+only when @expr{c} is an integer and @expr{b c} also
+evaluates to an integer. Without these restrictions these simplifications
+would not be safe because of problems with principal values.
+(In other words,
+@texline @math{((-3)^{1/2})^2}
+@infoline @expr{((-3)^1:2)^2}
+is safe to simplify, but
+@texline @math{((-3)^2)^{1/2}}
+@infoline @expr{((-3)^2)^1:2}
+is not.) @xref{Declarations}, for ways to inform Calc that your
+variables satisfy these requirements.
+
+As a special case of this rule, @expr{@tfn{sqrt}(x)^n} is simplified to
+@texline @math{x^{n/2}}
+@infoline @expr{x^(n/2)}
+only for even integers @expr{n}.
+
+If @expr{a} is known to be real, @expr{b} is an even integer, and
+@expr{c} is a half- or quarter-integer, then @expr{(a^b)^c} is
+simplified to @expr{@tfn{abs}(a^(b c))}.
+
+Also, @expr{(-a)^b} is simplified to @expr{a^b} if @expr{b} is an
+even integer, or to @expr{-(a^b)} if @expr{b} is an odd integer,
+for any negative-looking expression @expr{-a}.
+
+Square roots @expr{@tfn{sqrt}(x)} generally act like one-half powers
+@texline @math{x^{1:2}}
+@infoline @expr{x^1:2}
+for the purposes of the above-listed simplifications.
+
+Also, note that
+@texline @math{1 / x^{1:2}}
+@infoline @expr{1 / x^1:2}
+is changed to
+@texline @math{x^{-1:2}},
+@infoline @expr{x^(-1:2)},
+but @expr{1 / @tfn{sqrt}(x)} is left alone.
+
+@tex
+\bigskip
+@end tex
+
+Generic identity matrices (@pxref{Matrix Mode}) are simplified by the
+following rules: @expr{@tfn{idn}(a) + b} to @expr{a + b} if @expr{b}
+is provably scalar, or expanded out if @expr{b} is a matrix;
+@expr{@tfn{idn}(a) + @tfn{idn}(b)} to @expr{@tfn{idn}(a + b)};
+@expr{-@tfn{idn}(a)} to @expr{@tfn{idn}(-a)}; @expr{a @tfn{idn}(b)} to
+@expr{@tfn{idn}(a b)} if @expr{a} is provably scalar, or to @expr{a b}
+if @expr{a} is provably non-scalar; @expr{@tfn{idn}(a) @tfn{idn}(b)} to
+@expr{@tfn{idn}(a b)}; analogous simplifications for quotients involving
+@code{idn}; and @expr{@tfn{idn}(a)^n} to @expr{@tfn{idn}(a^n)} where
+@expr{n} is an integer.
+
+@tex
+\bigskip
+@end tex
+
+The @code{floor} function and other integer truncation functions
+vanish if the argument is provably integer-valued, so that
+@expr{@tfn{floor}(@tfn{round}(x))} simplifies to @expr{@tfn{round}(x)}.
+Also, combinations of @code{float}, @code{floor} and its friends,
+and @code{ffloor} and its friends, are simplified in appropriate
+ways. @xref{Integer Truncation}.
+
+The expression @expr{@tfn{abs}(-x)} changes to @expr{@tfn{abs}(x)}.
+The expression @expr{@tfn{abs}(@tfn{abs}(x))} changes to
+@expr{@tfn{abs}(x)}; in fact, @expr{@tfn{abs}(x)} changes to @expr{x} or
+@expr{-x} if @expr{x} is provably nonnegative or nonpositive
+(@pxref{Declarations}).
+
+While most functions do not recognize the variable @code{i} as an
+imaginary number, the @code{arg} function does handle the two cases
+@expr{@tfn{arg}(@tfn{i})} and @expr{@tfn{arg}(-@tfn{i})} just for convenience.
+
+The expression @expr{@tfn{conj}(@tfn{conj}(x))} simplifies to @expr{x}.
+Various other expressions involving @code{conj}, @code{re}, and
+@code{im} are simplified, especially if some of the arguments are
+provably real or involve the constant @code{i}. For example,
+@expr{@tfn{conj}(a + b i)} is changed to
+@expr{@tfn{conj}(a) - @tfn{conj}(b) i}, or to @expr{a - b i} if @expr{a}
+and @expr{b} are known to be real.
+
+Functions like @code{sin} and @code{arctan} generally don't have
+any default simplifications beyond simply evaluating the functions
+for suitable numeric arguments and infinity. The @kbd{a s} command
+described in the next section does provide some simplifications for
+these functions, though.
+
+One important simplification that does occur is that
+@expr{@tfn{ln}(@tfn{e})} is simplified to 1, and @expr{@tfn{ln}(@tfn{e}^x)} is
+simplified to @expr{x} for any @expr{x}. This occurs even if you have
+stored a different value in the Calc variable @samp{e}; but this would
+be a bad idea in any case if you were also using natural logarithms!
+
+Among the logical functions, @tfn{!(@var{a} <= @var{b})} changes to
+@tfn{@var{a} > @var{b}} and so on. Equations and inequalities where both sides
+are either negative-looking or zero are simplified by negating both sides
+and reversing the inequality. While it might seem reasonable to simplify
+@expr{!!x} to @expr{x}, this would not be valid in general because
+@expr{!!2} is 1, not 2.
+
+Most other Calc functions have few if any default simplifications
+defined, aside of course from evaluation when the arguments are
+suitable numbers.
+
+@node Algebraic Simplifications, Unsafe Simplifications, Default Simplifications, Simplifying Formulas
+@subsection Algebraic Simplifications
+
+@noindent
+@cindex Algebraic simplifications
+The @kbd{a s} command makes simplifications that may be too slow to
+do all the time, or that may not be desirable all of the time.
+If you find these simplifications are worthwhile, you can type
+@kbd{m A} to have Calc apply them automatically.
+
+This section describes all simplifications that are performed by
+the @kbd{a s} command. Note that these occur in addition to the
+default simplifications; even if the default simplifications have
+been turned off by an @kbd{m O} command, @kbd{a s} will turn them
+back on temporarily while it simplifies the formula.
+
+There is a variable, @code{AlgSimpRules}, in which you can put rewrites
+to be applied by @kbd{a s}. Its use is analogous to @code{EvalRules},
+but without the special restrictions. Basically, the simplifier does
+@samp{@w{a r} AlgSimpRules} with an infinite repeat count on the whole
+expression being simplified, then it traverses the expression applying
+the built-in rules described below. If the result is different from
+the original expression, the process repeats with the default
+simplifications (including @code{EvalRules}), then @code{AlgSimpRules},
+then the built-in simplifications, and so on.
+
+@tex
+\bigskip
+@end tex
+
+Sums are simplified in two ways. Constant terms are commuted to the
+end of the sum, so that @expr{a + 2 + b} changes to @expr{a + b + 2}.
+The only exception is that a constant will not be commuted away
+from the first position of a difference, i.e., @expr{2 - x} is not
+commuted to @expr{-x + 2}.
+
+Also, terms of sums are combined by the distributive law, as in
+@expr{x + y + 2 x} to @expr{y + 3 x}. This always occurs for
+adjacent terms, but @kbd{a s} compares all pairs of terms including
+non-adjacent ones.
+
+@tex
+\bigskip
+@end tex
+
+Products are sorted into a canonical order using the commutative
+law. For example, @expr{b c a} is commuted to @expr{a b c}.
+This allows easier comparison of products; for example, the default
+simplifications will not change @expr{x y + y x} to @expr{2 x y},
+but @kbd{a s} will; it first rewrites the sum to @expr{x y + x y},
+and then the default simplifications are able to recognize a sum
+of identical terms.
+
+The canonical ordering used to sort terms of products has the
+property that real-valued numbers, interval forms and infinities
+come first, and are sorted into increasing order. The @kbd{V S}
+command uses the same ordering when sorting a vector.
+
+Sorting of terms of products is inhibited when Matrix mode is
+turned on; in this case, Calc will never exchange the order of
+two terms unless it knows at least one of the terms is a scalar.
+
+Products of powers are distributed by comparing all pairs of
+terms, using the same method that the default simplifications
+use for adjacent terms of products.
+
+Even though sums are not sorted, the commutative law is still
+taken into account when terms of a product are being compared.
+Thus @expr{(x + y) (y + x)} will be simplified to @expr{(x + y)^2}.
+A subtle point is that @expr{(x - y) (y - x)} will @emph{not}
+be simplified to @expr{-(x - y)^2}; Calc does not notice that
+one term can be written as a constant times the other, even if
+that constant is @mathit{-1}.
+
+A fraction times any expression, @expr{(a:b) x}, is changed to
+a quotient involving integers: @expr{a x / b}. This is not
+done for floating-point numbers like @expr{0.5}, however. This
+is one reason why you may find it convenient to turn Fraction mode
+on while doing algebra; @pxref{Fraction Mode}.
+
+@tex
+\bigskip
+@end tex
+
+Quotients are simplified by comparing all terms in the numerator
+with all terms in the denominator for possible cancellation using
+the distributive law. For example, @expr{a x^2 b / c x^3 d} will
+cancel @expr{x^2} from the top and bottom to get @expr{a b / c x d}.
+(The terms in the denominator will then be rearranged to @expr{c d x}
+as described above.) If there is any common integer or fractional
+factor in the numerator and denominator, it is cancelled out;
+for example, @expr{(4 x + 6) / 8 x} simplifies to @expr{(2 x + 3) / 4 x}.
+
+Non-constant common factors are not found even by @kbd{a s}. To
+cancel the factor @expr{a} in @expr{(a x + a) / a^2} you could first
+use @kbd{j M} on the product @expr{a x} to Merge the numerator to
+@expr{a (1+x)}, which can then be simplified successfully.
+
+@tex
+\bigskip
+@end tex
+
+Integer powers of the variable @code{i} are simplified according
+to the identity @expr{i^2 = -1}. If you store a new value other
+than the complex number @expr{(0,1)} in @code{i}, this simplification
+will no longer occur. This is done by @kbd{a s} instead of by default
+in case someone (unwisely) uses the name @code{i} for a variable
+unrelated to complex numbers; it would be unfortunate if Calc
+quietly and automatically changed this formula for reasons the
+user might not have been thinking of.
+
+Square roots of integer or rational arguments are simplified in
+several ways. (Note that these will be left unevaluated only in
+Symbolic mode.) First, square integer or rational factors are
+pulled out so that @expr{@tfn{sqrt}(8)} is rewritten as
+@texline @math{2\,@tfn{sqrt}(2)}.
+@infoline @expr{2 sqrt(2)}.
+Conceptually speaking this implies factoring the argument into primes
+and moving pairs of primes out of the square root, but for reasons of
+efficiency Calc only looks for primes up to 29.
+
+Square roots in the denominator of a quotient are moved to the
+numerator: @expr{1 / @tfn{sqrt}(3)} changes to @expr{@tfn{sqrt}(3) / 3}.
+The same effect occurs for the square root of a fraction:
+@expr{@tfn{sqrt}(2:3)} changes to @expr{@tfn{sqrt}(6) / 3}.
+
+@tex
+\bigskip
+@end tex
+
+The @code{%} (modulo) operator is simplified in several ways
+when the modulus @expr{M} is a positive real number. First, if
+the argument is of the form @expr{x + n} for some real number
+@expr{n}, then @expr{n} is itself reduced modulo @expr{M}. For
+example, @samp{(x - 23) % 10} is simplified to @samp{(x + 7) % 10}.
+
+If the argument is multiplied by a constant, and this constant
+has a common integer divisor with the modulus, then this factor is
+cancelled out. For example, @samp{12 x % 15} is changed to
+@samp{3 (4 x % 5)} by factoring out 3. Also, @samp{(12 x + 1) % 15}
+is changed to @samp{3 ((4 x + 1:3) % 5)}. While these forms may
+not seem ``simpler,'' they allow Calc to discover useful information
+about modulo forms in the presence of declarations.
+
+If the modulus is 1, then Calc can use @code{int} declarations to
+evaluate the expression. For example, the idiom @samp{x % 2} is
+often used to check whether a number is odd or even. As described
+above, @w{@samp{2 n % 2}} and @samp{(2 n + 1) % 2} are simplified to
+@samp{2 (n % 1)} and @samp{2 ((n + 1:2) % 1)}, respectively; Calc
+can simplify these to 0 and 1 (respectively) if @code{n} has been
+declared to be an integer.
+
+@tex
+\bigskip
+@end tex
+
+Trigonometric functions are simplified in several ways. Whenever a
+products of two trigonometric functions can be replaced by a single
+function, the replacement is made; for example,
+@expr{@tfn{tan}(x) @tfn{cos}(x)} is simplified to @expr{@tfn{sin}(x)}.
+Reciprocals of trigonometric functions are replaced by their reciprocal
+function; for example, @expr{1/@tfn{sec}(x)} is simplified to
+@expr{@tfn{cos}(x)}. The corresponding simplifications for the
+hyperbolic functions are also handled.
+
+Trigonometric functions of their inverse functions are
+simplified. The expression @expr{@tfn{sin}(@tfn{arcsin}(x))} is
+simplified to @expr{x}, and similarly for @code{cos} and @code{tan}.
+Trigonometric functions of inverses of different trigonometric
+functions can also be simplified, as in @expr{@tfn{sin}(@tfn{arccos}(x))}
+to @expr{@tfn{sqrt}(1 - x^2)}.
+
+If the argument to @code{sin} is negative-looking, it is simplified to
+@expr{-@tfn{sin}(x)}, and similarly for @code{cos} and @code{tan}.
+Finally, certain special values of the argument are recognized;
+@pxref{Trigonometric and Hyperbolic Functions}.
+
+Hyperbolic functions of their inverses and of negative-looking
+arguments are also handled, as are exponentials of inverse
+hyperbolic functions.
+
+No simplifications for inverse trigonometric and hyperbolic
+functions are known, except for negative arguments of @code{arcsin},
+@code{arctan}, @code{arcsinh}, and @code{arctanh}. Note that
+@expr{@tfn{arcsin}(@tfn{sin}(x))} can @emph{not} safely change to
+@expr{x}, since this only correct within an integer multiple of
+@texline @math{2 \pi}
+@infoline @expr{2 pi}
+radians or 360 degrees. However, @expr{@tfn{arcsinh}(@tfn{sinh}(x))} is
+simplified to @expr{x} if @expr{x} is known to be real.
+
+Several simplifications that apply to logarithms and exponentials
+are that @expr{@tfn{exp}(@tfn{ln}(x))},
+@texline @tfn{e}@math{^{\ln(x)}},
+@infoline @expr{e^@tfn{ln}(x)},
+and
+@texline @math{10^{{\rm log10}(x)}}
+@infoline @expr{10^@tfn{log10}(x)}
+all reduce to @expr{x}. Also, @expr{@tfn{ln}(@tfn{exp}(x))}, etc., can
+reduce to @expr{x} if @expr{x} is provably real. The form
+@expr{@tfn{exp}(x)^y} is simplified to @expr{@tfn{exp}(x y)}. If @expr{x}
+is a suitable multiple of
+@texline @math{\pi i}
+@infoline @expr{pi i}
+(as described above for the trigonometric functions), then
+@expr{@tfn{exp}(x)} or @expr{e^x} will be expanded. Finally,
+@expr{@tfn{ln}(x)} is simplified to a form involving @code{pi} and
+@code{i} where @expr{x} is provably negative, positive imaginary, or
+negative imaginary.
+
+The error functions @code{erf} and @code{erfc} are simplified when
+their arguments are negative-looking or are calls to the @code{conj}
+function.
+
+@tex
+\bigskip
+@end tex
+
+Equations and inequalities are simplified by cancelling factors
+of products, quotients, or sums on both sides. Inequalities
+change sign if a negative multiplicative factor is cancelled.
+Non-constant multiplicative factors as in @expr{a b = a c} are
+cancelled from equations only if they are provably nonzero (generally
+because they were declared so; @pxref{Declarations}). Factors
+are cancelled from inequalities only if they are nonzero and their
+sign is known.
+
+Simplification also replaces an equation or inequality with
+1 or 0 (``true'' or ``false'') if it can through the use of
+declarations. If @expr{x} is declared to be an integer greater
+than 5, then @expr{x < 3}, @expr{x = 3}, and @expr{x = 7.5} are
+all simplified to 0, but @expr{x > 3} is simplified to 1.
+By a similar analysis, @expr{abs(x) >= 0} is simplified to 1,
+as is @expr{x^2 >= 0} if @expr{x} is known to be real.
+
+@node Unsafe Simplifications, Simplification of Units, Algebraic Simplifications, Simplifying Formulas
+@subsection ``Unsafe'' Simplifications
+
+@noindent
+@cindex Unsafe simplifications
+@cindex Extended simplification
+@kindex a e
+@pindex calc-simplify-extended
+@ignore
+@mindex esimpl@idots
+@end ignore
+@tindex esimplify
+The @kbd{a e} (@code{calc-simplify-extended}) [@code{esimplify}] command
+is like @kbd{a s}
+except that it applies some additional simplifications which are not
+``safe'' in all cases. Use this only if you know the values in your
+formula lie in the restricted ranges for which these simplifications
+are valid. The symbolic integrator uses @kbd{a e};
+one effect of this is that the integrator's results must be used with
+caution. Where an integral table will often attach conditions like
+``for positive @expr{a} only,'' Calc (like most other symbolic
+integration programs) will simply produce an unqualified result.
+
+Because @kbd{a e}'s simplifications are unsafe, it is sometimes better
+to type @kbd{C-u -3 a v}, which does extended simplification only
+on the top level of the formula without affecting the sub-formulas.
+In fact, @kbd{C-u -3 j v} allows you to target extended simplification
+to any specific part of a formula.
+
+The variable @code{ExtSimpRules} contains rewrites to be applied by
+the @kbd{a e} command. These are applied in addition to
+@code{EvalRules} and @code{AlgSimpRules}. (The @kbd{a r AlgSimpRules}
+step described above is simply followed by an @kbd{a r ExtSimpRules} step.)
+
+Following is a complete list of ``unsafe'' simplifications performed
+by @kbd{a e}.
+
+@tex
+\bigskip
+@end tex
+
+Inverse trigonometric or hyperbolic functions, called with their
+corresponding non-inverse functions as arguments, are simplified
+by @kbd{a e}. For example, @expr{@tfn{arcsin}(@tfn{sin}(x))} changes
+to @expr{x}. Also, @expr{@tfn{arcsin}(@tfn{cos}(x))} and
+@expr{@tfn{arccos}(@tfn{sin}(x))} both change to @expr{@tfn{pi}/2 - x}.
+These simplifications are unsafe because they are valid only for
+values of @expr{x} in a certain range; outside that range, values
+are folded down to the 360-degree range that the inverse trigonometric
+functions always produce.
+
+Powers of powers @expr{(x^a)^b} are simplified to
+@texline @math{x^{a b}}
+@infoline @expr{x^(a b)}
+for all @expr{a} and @expr{b}. These results will be valid only
+in a restricted range of @expr{x}; for example, in
+@texline @math{(x^2)^{1:2}}
+@infoline @expr{(x^2)^1:2}
+the powers cancel to get @expr{x}, which is valid for positive values
+of @expr{x} but not for negative or complex values.
+
+Similarly, @expr{@tfn{sqrt}(x^a)} and @expr{@tfn{sqrt}(x)^a} are both
+simplified (possibly unsafely) to
+@texline @math{x^{a/2}}.
+@infoline @expr{x^(a/2)}.
+
+Forms like @expr{@tfn{sqrt}(1 - sin(x)^2)} are simplified to, e.g.,
+@expr{@tfn{cos}(x)}. Calc has identities of this sort for @code{sin},
+@code{cos}, @code{tan}, @code{sinh}, and @code{cosh}.
+
+Arguments of square roots are partially factored to look for
+squared terms that can be extracted. For example,
+@expr{@tfn{sqrt}(a^2 b^3 + a^3 b^2)} simplifies to
+@expr{a b @tfn{sqrt}(a+b)}.
+
+The simplifications of @expr{@tfn{ln}(@tfn{exp}(x))},
+@expr{@tfn{ln}(@tfn{e}^x)}, and @expr{@tfn{log10}(10^x)} to @expr{x} are also
+unsafe because of problems with principal values (although these
+simplifications are safe if @expr{x} is known to be real).
+
+Common factors are cancelled from products on both sides of an
+equation, even if those factors may be zero: @expr{a x / b x}
+to @expr{a / b}. Such factors are never cancelled from
+inequalities: Even @kbd{a e} is not bold enough to reduce
+@expr{a x < b x} to @expr{a < b} (or @expr{a > b}, depending
+on whether you believe @expr{x} is positive or negative).
+The @kbd{a M /} command can be used to divide a factor out of
+both sides of an inequality.
+
+@node Simplification of Units, , Unsafe Simplifications, Simplifying Formulas
+@subsection Simplification of Units
+
+@noindent
+The simplifications described in this section are applied by the
+@kbd{u s} (@code{calc-simplify-units}) command. These are in addition
+to the regular @kbd{a s} (but not @kbd{a e}) simplifications described
+earlier. @xref{Basic Operations on Units}.
+
+The variable @code{UnitSimpRules} contains rewrites to be applied by
+the @kbd{u s} command. These are applied in addition to @code{EvalRules}
+and @code{AlgSimpRules}.
+
+Scalar mode is automatically put into effect when simplifying units.
+@xref{Matrix Mode}.
+
+Sums @expr{a + b} involving units are simplified by extracting the
+units of @expr{a} as if by the @kbd{u x} command (call the result
+@expr{u_a}), then simplifying the expression @expr{b / u_a}
+using @kbd{u b} and @kbd{u s}. If the result has units then the sum
+is inconsistent and is left alone. Otherwise, it is rewritten
+in terms of the units @expr{u_a}.
+
+If units auto-ranging mode is enabled, products or quotients in
+which the first argument is a number which is out of range for the
+leading unit are modified accordingly.
+
+When cancelling and combining units in products and quotients,
+Calc accounts for unit names that differ only in the prefix letter.
+For example, @samp{2 km m} is simplified to @samp{2000 m^2}.
+However, compatible but different units like @code{ft} and @code{in}
+are not combined in this way.
+
+Quotients @expr{a / b} are simplified in three additional ways. First,
+if @expr{b} is a number or a product beginning with a number, Calc
+computes the reciprocal of this number and moves it to the numerator.
+
+Second, for each pair of unit names from the numerator and denominator
+of a quotient, if the units are compatible (e.g., they are both
+units of area) then they are replaced by the ratio between those
+units. For example, in @samp{3 s in N / kg cm} the units
+@samp{in / cm} will be replaced by @expr{2.54}.
+
+Third, if the units in the quotient exactly cancel out, so that
+a @kbd{u b} command on the quotient would produce a dimensionless
+number for an answer, then the quotient simplifies to that number.
+
+For powers and square roots, the ``unsafe'' simplifications
+@expr{(a b)^c} to @expr{a^c b^c}, @expr{(a/b)^c} to @expr{a^c / b^c},
+and @expr{(a^b)^c} to
+@texline @math{a^{b c}}
+@infoline @expr{a^(b c)}
+are done if the powers are real numbers. (These are safe in the context
+of units because all numbers involved can reasonably be assumed to be
+real.)
+
+Also, if a unit name is raised to a fractional power, and the
+base units in that unit name all occur to powers which are a
+multiple of the denominator of the power, then the unit name
+is expanded out into its base units, which can then be simplified
+according to the previous paragraph. For example, @samp{acre^1.5}
+is simplified by noting that @expr{1.5 = 3:2}, that @samp{acre}
+is defined in terms of @samp{m^2}, and that the 2 in the power of
+@code{m} is a multiple of 2 in @expr{3:2}. Thus, @code{acre^1.5} is
+replaced by approximately
+@texline @math{(4046 m^2)^{1.5}}
+@infoline @expr{(4046 m^2)^1.5},
+which is then changed to
+@texline @math{4046^{1.5} \, (m^2)^{1.5}},
+@infoline @expr{4046^1.5 (m^2)^1.5},
+then to @expr{257440 m^3}.
+
+The functions @code{float}, @code{frac}, @code{clean}, @code{abs},
+as well as @code{floor} and the other integer truncation functions,
+applied to unit names or products or quotients involving units, are
+simplified. For example, @samp{round(1.6 in)} is changed to
+@samp{round(1.6) round(in)}; the lefthand term evaluates to 2,
+and the righthand term simplifies to @code{in}.
+
+The functions @code{sin}, @code{cos}, and @code{tan} with arguments
+that have angular units like @code{rad} or @code{arcmin} are
+simplified by converting to base units (radians), then evaluating
+with the angular mode temporarily set to radians.
+
+@node Polynomials, Calculus, Simplifying Formulas, Algebra
+@section Polynomials
+
+A @dfn{polynomial} is a sum of terms which are coefficients times
+various powers of a ``base'' variable. For example, @expr{2 x^2 + 3 x - 4}
+is a polynomial in @expr{x}. Some formulas can be considered
+polynomials in several different variables: @expr{1 + 2 x + 3 y + 4 x y^2}
+is a polynomial in both @expr{x} and @expr{y}. Polynomial coefficients
+are often numbers, but they may in general be any formulas not
+involving the base variable.
+
+@kindex a f
+@pindex calc-factor
+@tindex factor
+The @kbd{a f} (@code{calc-factor}) [@code{factor}] command factors a
+polynomial into a product of terms. For example, the polynomial
+@expr{x^3 + 2 x^2 + x} is factored into @samp{x*(x+1)^2}. As another
+example, @expr{a c + b d + b c + a d} is factored into the product
+@expr{(a + b) (c + d)}.
+
+Calc currently has three algorithms for factoring. Formulas which are
+linear in several variables, such as the second example above, are
+merged according to the distributive law. Formulas which are
+polynomials in a single variable, with constant integer or fractional
+coefficients, are factored into irreducible linear and/or quadratic
+terms. The first example above factors into three linear terms
+(@expr{x}, @expr{x+1}, and @expr{x+1} again). Finally, formulas
+which do not fit the above criteria are handled by the algebraic
+rewrite mechanism.
+
+Calc's polynomial factorization algorithm works by using the general
+root-finding command (@w{@kbd{a P}}) to solve for the roots of the
+polynomial. It then looks for roots which are rational numbers
+or complex-conjugate pairs, and converts these into linear and
+quadratic terms, respectively. Because it uses floating-point
+arithmetic, it may be unable to find terms that involve large
+integers (whose number of digits approaches the current precision).
+Also, irreducible factors of degree higher than quadratic are not
+found, and polynomials in more than one variable are not treated.
+(A more robust factorization algorithm may be included in a future
+version of Calc.)
+
+@vindex FactorRules
+@ignore
+@starindex
+@end ignore
+@tindex thecoefs
+@ignore
+@starindex
+@end ignore
+@ignore
+@mindex @idots
+@end ignore
+@tindex thefactors
+The rewrite-based factorization method uses rules stored in the variable
+@code{FactorRules}. @xref{Rewrite Rules}, for a discussion of the
+operation of rewrite rules. The default @code{FactorRules} are able
+to factor quadratic forms symbolically into two linear terms,
+@expr{(a x + b) (c x + d)}. You can edit these rules to include other
+cases if you wish. To use the rules, Calc builds the formula
+@samp{thecoefs(x, [a, b, c, ...])} where @code{x} is the polynomial
+base variable and @code{a}, @code{b}, etc., are polynomial coefficients
+(which may be numbers or formulas). The constant term is written first,
+i.e., in the @code{a} position. When the rules complete, they should have
+changed the formula into the form @samp{thefactors(x, [f1, f2, f3, ...])}
+where each @code{fi} should be a factored term, e.g., @samp{x - ai}.
+Calc then multiplies these terms together to get the complete
+factored form of the polynomial. If the rules do not change the
+@code{thecoefs} call to a @code{thefactors} call, @kbd{a f} leaves the
+polynomial alone on the assumption that it is unfactorable. (Note that
+the function names @code{thecoefs} and @code{thefactors} are used only
+as placeholders; there are no actual Calc functions by those names.)
+
+@kindex H a f
+@tindex factors
+The @kbd{H a f} [@code{factors}] command also factors a polynomial,
+but it returns a list of factors instead of an expression which is the
+product of the factors. Each factor is represented by a sub-vector
+of the factor, and the power with which it appears. For example,
+@expr{x^5 + x^4 - 33 x^3 + 63 x^2} factors to @expr{(x + 7) x^2 (x - 3)^2}
+in @kbd{a f}, or to @expr{[ [x, 2], [x+7, 1], [x-3, 2] ]} in @kbd{H a f}.
+If there is an overall numeric factor, it always comes first in the list.
+The functions @code{factor} and @code{factors} allow a second argument
+when written in algebraic form; @samp{factor(x,v)} factors @expr{x} with
+respect to the specific variable @expr{v}. The default is to factor with
+respect to all the variables that appear in @expr{x}.
+
+@kindex a c
+@pindex calc-collect
+@tindex collect
+The @kbd{a c} (@code{calc-collect}) [@code{collect}] command rearranges a
+formula as a
+polynomial in a given variable, ordered in decreasing powers of that
+variable. For example, given @expr{1 + 2 x + 3 y + 4 x y^2} on
+the stack, @kbd{a c x} would produce @expr{(2 + 4 y^2) x + (1 + 3 y)},
+and @kbd{a c y} would produce @expr{(4 x) y^2 + 3 y + (1 + 2 x)}.
+The polynomial will be expanded out using the distributive law as
+necessary: Collecting @expr{x} in @expr{(x - 1)^3} produces
+@expr{x^3 - 3 x^2 + 3 x - 1}. Terms not involving @expr{x} will
+not be expanded.
+
+The ``variable'' you specify at the prompt can actually be any
+expression: @kbd{a c ln(x+1)} will collect together all terms multiplied
+by @samp{ln(x+1)} or integer powers thereof. If @samp{x} also appears
+in the formula in a context other than @samp{ln(x+1)}, @kbd{a c} will
+treat those occurrences as unrelated to @samp{ln(x+1)}, i.e., as constants.
+
+@kindex a x
+@pindex calc-expand
+@tindex expand
+The @kbd{a x} (@code{calc-expand}) [@code{expand}] command expands an
+expression by applying the distributive law everywhere. It applies to
+products, quotients, and powers involving sums. By default, it fully
+distributes all parts of the expression. With a numeric prefix argument,
+the distributive law is applied only the specified number of times, then
+the partially expanded expression is left on the stack.
+
+The @kbd{a x} and @kbd{j D} commands are somewhat redundant. Use
+@kbd{a x} if you want to expand all products of sums in your formula.
+Use @kbd{j D} if you want to expand a particular specified term of
+the formula. There is an exactly analogous correspondence between
+@kbd{a f} and @kbd{j M}. (The @kbd{j D} and @kbd{j M} commands
+also know many other kinds of expansions, such as
+@samp{exp(a + b) = exp(a) exp(b)}, which @kbd{a x} and @kbd{a f}
+do not do.)
+
+Calc's automatic simplifications will sometimes reverse a partial
+expansion. For example, the first step in expanding @expr{(x+1)^3} is
+to write @expr{(x+1) (x+1)^2}. If @kbd{a x} stops there and tries
+to put this formula onto the stack, though, Calc will automatically
+simplify it back to @expr{(x+1)^3} form. The solution is to turn
+simplification off first (@pxref{Simplification Modes}), or to run
+@kbd{a x} without a numeric prefix argument so that it expands all
+the way in one step.
+
+@kindex a a
+@pindex calc-apart
+@tindex apart
+The @kbd{a a} (@code{calc-apart}) [@code{apart}] command expands a
+rational function by partial fractions. A rational function is the
+quotient of two polynomials; @code{apart} pulls this apart into a
+sum of rational functions with simple denominators. In algebraic
+notation, the @code{apart} function allows a second argument that
+specifies which variable to use as the ``base''; by default, Calc
+chooses the base variable automatically.
+
+@kindex a n
+@pindex calc-normalize-rat
+@tindex nrat
+The @kbd{a n} (@code{calc-normalize-rat}) [@code{nrat}] command
+attempts to arrange a formula into a quotient of two polynomials.
+For example, given @expr{1 + (a + b/c) / d}, the result would be
+@expr{(b + a c + c d) / c d}. The quotient is reduced, so that
+@kbd{a n} will simplify @expr{(x^2 + 2x + 1) / (x^2 - 1)} by dividing
+out the common factor @expr{x + 1}, yielding @expr{(x + 1) / (x - 1)}.
+
+@kindex a \
+@pindex calc-poly-div
+@tindex pdiv
+The @kbd{a \} (@code{calc-poly-div}) [@code{pdiv}] command divides
+two polynomials @expr{u} and @expr{v}, yielding a new polynomial
+@expr{q}. If several variables occur in the inputs, the inputs are
+considered multivariate polynomials. (Calc divides by the variable
+with the largest power in @expr{u} first, or, in the case of equal
+powers, chooses the variables in alphabetical order.) For example,
+dividing @expr{x^2 + 3 x + 2} by @expr{x + 2} yields @expr{x + 1}.
+The remainder from the division, if any, is reported at the bottom
+of the screen and is also placed in the Trail along with the quotient.
+
+Using @code{pdiv} in algebraic notation, you can specify the particular
+variable to be used as the base: @code{pdiv(@var{a},@var{b},@var{x})}.
+If @code{pdiv} is given only two arguments (as is always the case with
+the @kbd{a \} command), then it does a multivariate division as outlined
+above.
+
+@kindex a %
+@pindex calc-poly-rem
+@tindex prem
+The @kbd{a %} (@code{calc-poly-rem}) [@code{prem}] command divides
+two polynomials and keeps the remainder @expr{r}. The quotient
+@expr{q} is discarded. For any formulas @expr{a} and @expr{b}, the
+results of @kbd{a \} and @kbd{a %} satisfy @expr{a = q b + r}.
+(This is analogous to plain @kbd{\} and @kbd{%}, which compute the
+integer quotient and remainder from dividing two numbers.)
+
+@kindex a /
+@kindex H a /
+@pindex calc-poly-div-rem
+@tindex pdivrem
+@tindex pdivide
+The @kbd{a /} (@code{calc-poly-div-rem}) [@code{pdivrem}] command
+divides two polynomials and reports both the quotient and the
+remainder as a vector @expr{[q, r]}. The @kbd{H a /} [@code{pdivide}]
+command divides two polynomials and constructs the formula
+@expr{q + r/b} on the stack. (Naturally if the remainder is zero,
+this will immediately simplify to @expr{q}.)
+
+@kindex a g
+@pindex calc-poly-gcd
+@tindex pgcd
+The @kbd{a g} (@code{calc-poly-gcd}) [@code{pgcd}] command computes
+the greatest common divisor of two polynomials. (The GCD actually
+is unique only to within a constant multiplier; Calc attempts to
+choose a GCD which will be unsurprising.) For example, the @kbd{a n}
+command uses @kbd{a g} to take the GCD of the numerator and denominator
+of a quotient, then divides each by the result using @kbd{a \}. (The
+definition of GCD ensures that this division can take place without
+leaving a remainder.)
+
+While the polynomials used in operations like @kbd{a /} and @kbd{a g}
+often have integer coefficients, this is not required. Calc can also
+deal with polynomials over the rationals or floating-point reals.
+Polynomials with modulo-form coefficients are also useful in many
+applications; if you enter @samp{(x^2 + 3 x - 1) mod 5}, Calc
+automatically transforms this into a polynomial over the field of
+integers mod 5: @samp{(1 mod 5) x^2 + (3 mod 5) x + (4 mod 5)}.
+
+Congratulations and thanks go to Ove Ewerlid
+(@code{ewerlid@@mizar.DoCS.UU.SE}), who contributed many of the
+polynomial routines used in the above commands.
+
+@xref{Decomposing Polynomials}, for several useful functions for
+extracting the individual coefficients of a polynomial.
+
+@node Calculus, Solving Equations, Polynomials, Algebra
+@section Calculus
+
+@noindent
+The following calculus commands do not automatically simplify their
+inputs or outputs using @code{calc-simplify}. You may find it helps
+to do this by hand by typing @kbd{a s} or @kbd{a e}. It may also help
+to use @kbd{a x} and/or @kbd{a c} to arrange a result in the most
+readable way.
+
+@menu
+* Differentiation::
+* Integration::
+* Customizing the Integrator::
+* Numerical Integration::
+* Taylor Series::
+@end menu
+
+@node Differentiation, Integration, Calculus, Calculus
+@subsection Differentiation
+
+@noindent
+@kindex a d
+@kindex H a d
+@pindex calc-derivative
+@tindex deriv
+@tindex tderiv
+The @kbd{a d} (@code{calc-derivative}) [@code{deriv}] command computes
+the derivative of the expression on the top of the stack with respect to
+some variable, which it will prompt you to enter. Normally, variables
+in the formula other than the specified differentiation variable are
+considered constant, i.e., @samp{deriv(y,x)} is reduced to zero. With
+the Hyperbolic flag, the @code{tderiv} (total derivative) operation is used
+instead, in which derivatives of variables are not reduced to zero
+unless those variables are known to be ``constant,'' i.e., independent
+of any other variables. (The built-in special variables like @code{pi}
+are considered constant, as are variables that have been declared
+@code{const}; @pxref{Declarations}.)
+
+With a numeric prefix argument @var{n}, this command computes the
+@var{n}th derivative.
+
+When working with trigonometric functions, it is best to switch to
+Radians mode first (with @w{@kbd{m r}}). The derivative of @samp{sin(x)}
+in degrees is @samp{(pi/180) cos(x)}, probably not the expected
+answer!
+
+If you use the @code{deriv} function directly in an algebraic formula,
+you can write @samp{deriv(f,x,x0)} which represents the derivative
+of @expr{f} with respect to @expr{x}, evaluated at the point
+@texline @math{x=x_0}.
+@infoline @expr{x=x0}.
+
+If the formula being differentiated contains functions which Calc does
+not know, the derivatives of those functions are produced by adding
+primes (apostrophe characters). For example, @samp{deriv(f(2x), x)}
+produces @samp{2 f'(2 x)}, where the function @code{f'} represents the
+derivative of @code{f}.
+
+For functions you have defined with the @kbd{Z F} command, Calc expands
+the functions according to their defining formulas unless you have
+also defined @code{f'} suitably. For example, suppose we define
+@samp{sinc(x) = sin(x)/x} using @kbd{Z F}. If we then differentiate
+the formula @samp{sinc(2 x)}, the formula will be expanded to
+@samp{sin(2 x) / (2 x)} and differentiated. However, if we also
+define @samp{sinc'(x) = dsinc(x)}, say, then Calc will write the
+result as @samp{2 dsinc(2 x)}. @xref{Algebraic Definitions}.
+
+For multi-argument functions @samp{f(x,y,z)}, the derivative with respect
+to the first argument is written @samp{f'(x,y,z)}; derivatives with
+respect to the other arguments are @samp{f'2(x,y,z)} and @samp{f'3(x,y,z)}.
+Various higher-order derivatives can be formed in the obvious way, e.g.,
+@samp{f'@var{}'(x)} (the second derivative of @code{f}) or
+@samp{f'@var{}'2'3(x,y,z)} (@code{f} differentiated with respect to each
+argument once).
+
+@node Integration, Customizing the Integrator, Differentiation, Calculus
+@subsection Integration
+
+@noindent
+@kindex a i
+@pindex calc-integral
+@tindex integ
+The @kbd{a i} (@code{calc-integral}) [@code{integ}] command computes the
+indefinite integral of the expression on the top of the stack with
+respect to a prompted-for variable. The integrator is not guaranteed to
+work for all integrable functions, but it is able to integrate several
+large classes of formulas. In particular, any polynomial or rational
+function (a polynomial divided by a polynomial) is acceptable.
+(Rational functions don't have to be in explicit quotient form, however;
+@texline @math{x/(1+x^{-2})}
+@infoline @expr{x/(1+x^-2)}
+is not strictly a quotient of polynomials, but it is equivalent to
+@expr{x^3/(x^2+1)}, which is.) Also, square roots of terms involving
+@expr{x} and @expr{x^2} may appear in rational functions being
+integrated. Finally, rational functions involving trigonometric or
+hyperbolic functions can be integrated.
+
+With an argument (@kbd{C-u a i}), this command will compute the definite
+integral of the expression on top of the stack. In this case, the
+command will again prompt for an integration variable, then prompt for a
+lower limit and an upper limit.
+
+@ifnottex
+If you use the @code{integ} function directly in an algebraic formula,
+you can also write @samp{integ(f,x,v)} which expresses the resulting
+indefinite integral in terms of variable @code{v} instead of @code{x}.
+With four arguments, @samp{integ(f(x),x,a,b)} represents a definite
+integral from @code{a} to @code{b}.
+@end ifnottex
+@tex
+If you use the @code{integ} function directly in an algebraic formula,
+you can also write @samp{integ(f,x,v)} which expresses the resulting
+indefinite integral in terms of variable @code{v} instead of @code{x}.
+With four arguments, @samp{integ(f(x),x,a,b)} represents a definite
+integral $\int_a^b f(x) \, dx$.
+@end tex
+
+Please note that the current implementation of Calc's integrator sometimes
+produces results that are significantly more complex than they need to
+be. For example, the integral Calc finds for
+@texline @math{1/(x+\sqrt{x^2+1})}
+@infoline @expr{1/(x+sqrt(x^2+1))}
+is several times more complicated than the answer Mathematica
+returns for the same input, although the two forms are numerically
+equivalent. Also, any indefinite integral should be considered to have
+an arbitrary constant of integration added to it, although Calc does not
+write an explicit constant of integration in its result. For example,
+Calc's solution for
+@texline @math{1/(1+\tan x)}
+@infoline @expr{1/(1+tan(x))}
+differs from the solution given in the @emph{CRC Math Tables} by a
+constant factor of
+@texline @math{\pi i / 2}
+@infoline @expr{pi i / 2},
+due to a different choice of constant of integration.
+
+The Calculator remembers all the integrals it has done. If conditions
+change in a way that would invalidate the old integrals, say, a switch
+from Degrees to Radians mode, then they will be thrown out. If you
+suspect this is not happening when it should, use the
+@code{calc-flush-caches} command; @pxref{Caches}.
+
+@vindex IntegLimit
+Calc normally will pursue integration by substitution or integration by
+parts up to 3 nested times before abandoning an approach as fruitless.
+If the integrator is taking too long, you can lower this limit by storing
+a number (like 2) in the variable @code{IntegLimit}. (The @kbd{s I}
+command is a convenient way to edit @code{IntegLimit}.) If this variable
+has no stored value or does not contain a nonnegative integer, a limit
+of 3 is used. The lower this limit is, the greater the chance that Calc
+will be unable to integrate a function it could otherwise handle. Raising
+this limit allows the Calculator to solve more integrals, though the time
+it takes may grow exponentially. You can monitor the integrator's actions
+by creating an Emacs buffer called @code{*Trace*}. If such a buffer
+exists, the @kbd{a i} command will write a log of its actions there.
+
+If you want to manipulate integrals in a purely symbolic way, you can
+set the integration nesting limit to 0 to prevent all but fast
+table-lookup solutions of integrals. You might then wish to define
+rewrite rules for integration by parts, various kinds of substitutions,
+and so on. @xref{Rewrite Rules}.
+
+@node Customizing the Integrator, Numerical Integration, Integration, Calculus
+@subsection Customizing the Integrator
+
+@noindent
+@vindex IntegRules
+Calc has two built-in rewrite rules called @code{IntegRules} and
+@code{IntegAfterRules} which you can edit to define new integration
+methods. @xref{Rewrite Rules}. At each step of the integration process,
+Calc wraps the current integrand in a call to the fictitious function
+@samp{integtry(@var{expr},@var{var})}, where @var{expr} is the
+integrand and @var{var} is the integration variable. If your rules
+rewrite this to be a plain formula (not a call to @code{integtry}), then
+Calc will use this formula as the integral of @var{expr}. For example,
+the rule @samp{integtry(mysin(x),x) := -mycos(x)} would define a rule to
+integrate a function @code{mysin} that acts like the sine function.
+Then, putting @samp{4 mysin(2y+1)} on the stack and typing @kbd{a i y}
+will produce the integral @samp{-2 mycos(2y+1)}. Note that Calc has
+automatically made various transformations on the integral to allow it
+to use your rule; integral tables generally give rules for
+@samp{mysin(a x + b)}, but you don't need to use this much generality
+in your @code{IntegRules}.
+
+@cindex Exponential integral Ei(x)
+@ignore
+@starindex
+@end ignore
+@tindex Ei
+As a more serious example, the expression @samp{exp(x)/x} cannot be
+integrated in terms of the standard functions, so the ``exponential
+integral'' function
+@texline @math{{\rm Ei}(x)}
+@infoline @expr{Ei(x)}
+was invented to describe it.
+We can get Calc to do this integral in terms of a made-up @code{Ei}
+function by adding the rule @samp{[integtry(exp(x)/x, x) := Ei(x)]}
+to @code{IntegRules}. Now entering @samp{exp(2x)/x} on the stack
+and typing @kbd{a i x} yields @samp{Ei(2 x)}. This new rule will
+work with Calc's various built-in integration methods (such as
+integration by substitution) to solve a variety of other problems
+involving @code{Ei}: For example, now Calc will also be able to
+integrate @samp{exp(exp(x))} and @samp{ln(ln(x))} (to get @samp{Ei(exp(x))}
+and @samp{x ln(ln(x)) - Ei(ln(x))}, respectively).
+
+Your rule may do further integration by calling @code{integ}. For
+example, @samp{integtry(twice(u),x) := twice(integ(u))} allows Calc
+to integrate @samp{twice(sin(x))} to get @samp{twice(-cos(x))}.
+Note that @code{integ} was called with only one argument. This notation
+is allowed only within @code{IntegRules}; it means ``integrate this
+with respect to the same integration variable.'' If Calc is unable
+to integrate @code{u}, the integration that invoked @code{IntegRules}
+also fails. Thus integrating @samp{twice(f(x))} fails, returning the
+unevaluated integral @samp{integ(twice(f(x)), x)}. It is still valid
+to call @code{integ} with two or more arguments, however; in this case,
+if @code{u} is not integrable, @code{twice} itself will still be
+integrated: If the above rule is changed to @samp{... := twice(integ(u,x))},
+then integrating @samp{twice(f(x))} will yield @samp{twice(integ(f(x),x))}.
+
+If a rule instead produces the formula @samp{integsubst(@var{sexpr},
+@var{svar})}, either replacing the top-level @code{integtry} call or
+nested anywhere inside the expression, then Calc will apply the
+substitution @samp{@var{u} = @var{sexpr}(@var{svar})} to try to
+integrate the original @var{expr}. For example, the rule
+@samp{sqrt(a) := integsubst(sqrt(x),x)} says that if Calc ever finds
+a square root in the integrand, it should attempt the substitution
+@samp{u = sqrt(x)}. (This particular rule is unnecessary because
+Calc always tries ``obvious'' substitutions where @var{sexpr} actually
+appears in the integrand.) The variable @var{svar} may be the same
+as the @var{var} that appeared in the call to @code{integtry}, but
+it need not be.
+
+When integrating according to an @code{integsubst}, Calc uses the
+equation solver to find the inverse of @var{sexpr} (if the integrand
+refers to @var{var} anywhere except in subexpressions that exactly
+match @var{sexpr}). It uses the differentiator to find the derivative
+of @var{sexpr} and/or its inverse (it has two methods that use one
+derivative or the other). You can also specify these items by adding
+extra arguments to the @code{integsubst} your rules construct; the
+general form is @samp{integsubst(@var{sexpr}, @var{svar}, @var{sinv},
+@var{sprime})}, where @var{sinv} is the inverse of @var{sexpr} (still
+written as a function of @var{svar}), and @var{sprime} is the
+derivative of @var{sexpr} with respect to @var{svar}. If you don't
+specify these things, and Calc is not able to work them out on its
+own with the information it knows, then your substitution rule will
+work only in very specific, simple cases.
+
+Calc applies @code{IntegRules} as if by @kbd{C-u 1 a r IntegRules};
+in other words, Calc stops rewriting as soon as any rule in your rule
+set succeeds. (If it weren't for this, the @samp{integsubst(sqrt(x),x)}
+example above would keep on adding layers of @code{integsubst} calls
+forever!)
+
+@vindex IntegSimpRules
+Another set of rules, stored in @code{IntegSimpRules}, are applied
+every time the integrator uses @kbd{a s} to simplify an intermediate
+result. For example, putting the rule @samp{twice(x) := 2 x} into
+@code{IntegSimpRules} would tell Calc to convert the @code{twice}
+function into a form it knows whenever integration is attempted.
+
+One more way to influence the integrator is to define a function with
+the @kbd{Z F} command (@pxref{Algebraic Definitions}). Calc's
+integrator automatically expands such functions according to their
+defining formulas, even if you originally asked for the function to
+be left unevaluated for symbolic arguments. (Certain other Calc
+systems, such as the differentiator and the equation solver, also
+do this.)
+
+@vindex IntegAfterRules
+Sometimes Calc is able to find a solution to your integral, but it
+expresses the result in a way that is unnecessarily complicated. If
+this happens, you can either use @code{integsubst} as described
+above to try to hint at a more direct path to the desired result, or
+you can use @code{IntegAfterRules}. This is an extra rule set that
+runs after the main integrator returns its result; basically, Calc does
+an @kbd{a r IntegAfterRules} on the result before showing it to you.
+(It also does an @kbd{a s}, without @code{IntegSimpRules}, after that
+to further simplify the result.) For example, Calc's integrator
+sometimes produces expressions of the form @samp{ln(1+x) - ln(1-x)};
+the default @code{IntegAfterRules} rewrite this into the more readable
+form @samp{2 arctanh(x)}. Note that, unlike @code{IntegRules},
+@code{IntegSimpRules} and @code{IntegAfterRules} are applied any number
+of times until no further changes are possible. Rewriting by
+@code{IntegAfterRules} occurs only after the main integrator has
+finished, not at every step as for @code{IntegRules} and
+@code{IntegSimpRules}.
+
+@node Numerical Integration, Taylor Series, Customizing the Integrator, Calculus
+@subsection Numerical Integration
+
+@noindent
+@kindex a I
+@pindex calc-num-integral
+@tindex ninteg
+If you want a purely numerical answer to an integration problem, you can
+use the @kbd{a I} (@code{calc-num-integral}) [@code{ninteg}] command. This
+command prompts for an integration variable, a lower limit, and an
+upper limit. Except for the integration variable, all other variables
+that appear in the integrand formula must have stored values. (A stored
+value, if any, for the integration variable itself is ignored.)
+
+Numerical integration works by evaluating your formula at many points in
+the specified interval. Calc uses an ``open Romberg'' method; this means
+that it does not evaluate the formula actually at the endpoints (so that
+it is safe to integrate @samp{sin(x)/x} from zero, for example). Also,
+the Romberg method works especially well when the function being
+integrated is fairly smooth. If the function is not smooth, Calc will
+have to evaluate it at quite a few points before it can accurately
+determine the value of the integral.
+
+Integration is much faster when the current precision is small. It is
+best to set the precision to the smallest acceptable number of digits
+before you use @kbd{a I}. If Calc appears to be taking too long, press
+@kbd{C-g} to halt it and try a lower precision. If Calc still appears
+to need hundreds of evaluations, check to make sure your function is
+well-behaved in the specified interval.
+
+It is possible for the lower integration limit to be @samp{-inf} (minus
+infinity). Likewise, the upper limit may be plus infinity. Calc
+internally transforms the integral into an equivalent one with finite
+limits. However, integration to or across singularities is not supported:
+The integral of @samp{1/sqrt(x)} from 0 to 1 exists (it can be found
+by Calc's symbolic integrator, for example), but @kbd{a I} will fail
+because the integrand goes to infinity at one of the endpoints.
+
+@node Taylor Series, , Numerical Integration, Calculus
+@subsection Taylor Series
+
+@noindent
+@kindex a t
+@pindex calc-taylor
+@tindex taylor
+The @kbd{a t} (@code{calc-taylor}) [@code{taylor}] command computes a
+power series expansion or Taylor series of a function. You specify the
+variable and the desired number of terms. You may give an expression of
+the form @samp{@var{var} = @var{a}} or @samp{@var{var} - @var{a}} instead
+of just a variable to produce a Taylor expansion about the point @var{a}.
+You may specify the number of terms with a numeric prefix argument;
+otherwise the command will prompt you for the number of terms. Note that
+many series expansions have coefficients of zero for some terms, so you
+may appear to get fewer terms than you asked for.
+
+If the @kbd{a i} command is unable to find a symbolic integral for a
+function, you can get an approximation by integrating the function's
+Taylor series.
+
+@node Solving Equations, Numerical Solutions, Calculus, Algebra
+@section Solving Equations
+
+@noindent
+@kindex a S
+@pindex calc-solve-for
+@tindex solve
+@cindex Equations, solving
+@cindex Solving equations
+The @kbd{a S} (@code{calc-solve-for}) [@code{solve}] command rearranges
+an equation to solve for a specific variable. An equation is an
+expression of the form @expr{L = R}. For example, the command @kbd{a S x}
+will rearrange @expr{y = 3x + 6} to the form, @expr{x = y/3 - 2}. If the
+input is not an equation, it is treated like an equation of the
+form @expr{X = 0}.
+
+This command also works for inequalities, as in @expr{y < 3x + 6}.
+Some inequalities cannot be solved where the analogous equation could
+be; for example, solving
+@texline @math{a < b \, c}
+@infoline @expr{a < b c}
+for @expr{b} is impossible
+without knowing the sign of @expr{c}. In this case, @kbd{a S} will
+produce the result
+@texline @math{b \mathbin{\hbox{\code{!=}}} a/c}
+@infoline @expr{b != a/c}
+(using the not-equal-to operator) to signify that the direction of the
+inequality is now unknown. The inequality
+@texline @math{a \le b \, c}
+@infoline @expr{a <= b c}
+is not even partially solved. @xref{Declarations}, for a way to tell
+Calc that the signs of the variables in a formula are in fact known.
+
+Two useful commands for working with the result of @kbd{a S} are
+@kbd{a .} (@pxref{Logical Operations}), which converts @expr{x = y/3 - 2}
+to @expr{y/3 - 2}, and @kbd{s l} (@pxref{Let Command}) which evaluates
+another formula with @expr{x} set equal to @expr{y/3 - 2}.
+
+@menu
+* Multiple Solutions::
+* Solving Systems of Equations::
+* Decomposing Polynomials::
+@end menu
+
+@node Multiple Solutions, Solving Systems of Equations, Solving Equations, Solving Equations
+@subsection Multiple Solutions
+
+@noindent
+@kindex H a S
+@tindex fsolve
+Some equations have more than one solution. The Hyperbolic flag
+(@code{H a S}) [@code{fsolve}] tells the solver to report the fully
+general family of solutions. It will invent variables @code{n1},
+@code{n2}, @dots{}, which represent independent arbitrary integers, and
+@code{s1}, @code{s2}, @dots{}, which represent independent arbitrary
+signs (either @mathit{+1} or @mathit{-1}). If you don't use the Hyperbolic
+flag, Calc will use zero in place of all arbitrary integers, and plus
+one in place of all arbitrary signs. Note that variables like @code{n1}
+and @code{s1} are not given any special interpretation in Calc except by
+the equation solver itself. As usual, you can use the @w{@kbd{s l}}
+(@code{calc-let}) command to obtain solutions for various actual values
+of these variables.
+
+For example, @kbd{' x^2 = y @key{RET} H a S x @key{RET}} solves to
+get @samp{x = s1 sqrt(y)}, indicating that the two solutions to the
+equation are @samp{sqrt(y)} and @samp{-sqrt(y)}. Another way to
+think about it is that the square-root operation is really a
+two-valued function; since every Calc function must return a
+single result, @code{sqrt} chooses to return the positive result.
+Then @kbd{H a S} doctors this result using @code{s1} to indicate
+the full set of possible values of the mathematical square-root.
+
+There is a similar phenomenon going the other direction: Suppose
+we solve @samp{sqrt(y) = x} for @code{y}. Calc squares both sides
+to get @samp{y = x^2}. This is correct, except that it introduces
+some dubious solutions. Consider solving @samp{sqrt(y) = -3}:
+Calc will report @expr{y = 9} as a valid solution, which is true
+in the mathematical sense of square-root, but false (there is no
+solution) for the actual Calc positive-valued @code{sqrt}. This
+happens for both @kbd{a S} and @kbd{H a S}.
+
+@cindex @code{GenCount} variable
+@vindex GenCount
+@ignore
+@starindex
+@end ignore
+@tindex an
+@ignore
+@starindex
+@end ignore
+@tindex as
+If you store a positive integer in the Calc variable @code{GenCount},
+then Calc will generate formulas of the form @samp{as(@var{n})} for
+arbitrary signs, and @samp{an(@var{n})} for arbitrary integers,
+where @var{n} represents successive values taken by incrementing
+@code{GenCount} by one. While the normal arbitrary sign and
+integer symbols start over at @code{s1} and @code{n1} with each
+new Calc command, the @code{GenCount} approach will give each
+arbitrary value a name that is unique throughout the entire Calc
+session. Also, the arbitrary values are function calls instead
+of variables, which is advantageous in some cases. For example,
+you can make a rewrite rule that recognizes all arbitrary signs
+using a pattern like @samp{as(n)}. The @kbd{s l} command only works
+on variables, but you can use the @kbd{a b} (@code{calc-substitute})
+command to substitute actual values for function calls like @samp{as(3)}.
+
+The @kbd{s G} (@code{calc-edit-GenCount}) command is a convenient
+way to create or edit this variable. Press @kbd{C-c C-c} to finish.
+
+If you have not stored a value in @code{GenCount}, or if the value
+in that variable is not a positive integer, the regular
+@code{s1}/@code{n1} notation is used.
+
+@kindex I a S
+@kindex H I a S
+@tindex finv
+@tindex ffinv
+With the Inverse flag, @kbd{I a S} [@code{finv}] treats the expression
+on top of the stack as a function of the specified variable and solves
+to find the inverse function, written in terms of the same variable.
+For example, @kbd{I a S x} inverts @expr{2x + 6} to @expr{x/2 - 3}.
+You can use both Inverse and Hyperbolic [@code{ffinv}] to obtain a
+fully general inverse, as described above.
+
+@kindex a P
+@pindex calc-poly-roots
+@tindex roots
+Some equations, specifically polynomials, have a known, finite number
+of solutions. The @kbd{a P} (@code{calc-poly-roots}) [@code{roots}]
+command uses @kbd{H a S} to solve an equation in general form, then, for
+all arbitrary-sign variables like @code{s1}, and all arbitrary-integer
+variables like @code{n1} for which @code{n1} only usefully varies over
+a finite range, it expands these variables out to all their possible
+values. The results are collected into a vector, which is returned.
+For example, @samp{roots(x^4 = 1, x)} returns the four solutions
+@samp{[1, -1, (0, 1), (0, -1)]}. Generally an @var{n}th degree
+polynomial will always have @var{n} roots on the complex plane.
+(If you have given a @code{real} declaration for the solution
+variable, then only the real-valued solutions, if any, will be
+reported; @pxref{Declarations}.)
+
+Note that because @kbd{a P} uses @kbd{H a S}, it is able to deliver
+symbolic solutions if the polynomial has symbolic coefficients. Also
+note that Calc's solver is not able to get exact symbolic solutions
+to all polynomials. Polynomials containing powers up to @expr{x^4}
+can always be solved exactly; polynomials of higher degree sometimes
+can be: @expr{x^6 + x^3 + 1} is converted to @expr{(x^3)^2 + (x^3) + 1},
+which can be solved for @expr{x^3} using the quadratic equation, and then
+for @expr{x} by taking cube roots. But in many cases, like
+@expr{x^6 + x + 1}, Calc does not know how to rewrite the polynomial
+into a form it can solve. The @kbd{a P} command can still deliver a
+list of numerical roots, however, provided that Symbolic mode (@kbd{m s})
+is not turned on. (If you work with Symbolic mode on, recall that the
+@kbd{N} (@code{calc-eval-num}) key is a handy way to reevaluate the
+formula on the stack with Symbolic mode temporarily off.) Naturally,
+@kbd{a P} can only provide numerical roots if the polynomial coefficients
+are all numbers (real or complex).
+
+@node Solving Systems of Equations, Decomposing Polynomials, Multiple Solutions, Solving Equations
+@subsection Solving Systems of Equations
+
+@noindent
+@cindex Systems of equations, symbolic
+You can also use the commands described above to solve systems of
+simultaneous equations. Just create a vector of equations, then
+specify a vector of variables for which to solve. (You can omit
+the surrounding brackets when entering the vector of variables
+at the prompt.)
+
+For example, putting @samp{[x + y = a, x - y = b]} on the stack
+and typing @kbd{a S x,y @key{RET}} produces the vector of solutions
+@samp{[x = a - (a-b)/2, y = (a-b)/2]}. The result vector will
+have the same length as the variables vector, and the variables
+will be listed in the same order there. Note that the solutions
+are not always simplified as far as possible; the solution for
+@expr{x} here could be improved by an application of the @kbd{a n}
+command.
+
+Calc's algorithm works by trying to eliminate one variable at a
+time by solving one of the equations for that variable and then
+substituting into the other equations. Calc will try all the
+possibilities, but you can speed things up by noting that Calc
+first tries to eliminate the first variable with the first
+equation, then the second variable with the second equation,
+and so on. It also helps to put the simpler (e.g., more linear)
+equations toward the front of the list. Calc's algorithm will
+solve any system of linear equations, and also many kinds of
+nonlinear systems.
+
+@ignore
+@starindex
+@end ignore
+@tindex elim
+Normally there will be as many variables as equations. If you
+give fewer variables than equations (an ``over-determined'' system
+of equations), Calc will find a partial solution. For example,
+typing @kbd{a S y @key{RET}} with the above system of equations
+would produce @samp{[y = a - x]}. There are now several ways to
+express this solution in terms of the original variables; Calc uses
+the first one that it finds. You can control the choice by adding
+variable specifiers of the form @samp{elim(@var{v})} to the
+variables list. This says that @var{v} should be eliminated from
+the equations; the variable will not appear at all in the solution.
+For example, typing @kbd{a S y,elim(x)} would yield
+@samp{[y = a - (b+a)/2]}.
+
+If the variables list contains only @code{elim} specifiers,
+Calc simply eliminates those variables from the equations
+and then returns the resulting set of equations. For example,
+@kbd{a S elim(x)} produces @samp{[a - 2 y = b]}. Every variable
+eliminated will reduce the number of equations in the system
+by one.
+
+Again, @kbd{a S} gives you one solution to the system of
+equations. If there are several solutions, you can use @kbd{H a S}
+to get a general family of solutions, or, if there is a finite
+number of solutions, you can use @kbd{a P} to get a list. (In
+the latter case, the result will take the form of a matrix where
+the rows are different solutions and the columns correspond to the
+variables you requested.)
+
+Another way to deal with certain kinds of overdetermined systems of
+equations is the @kbd{a F} command, which does least-squares fitting
+to satisfy the equations. @xref{Curve Fitting}.
+
+@node Decomposing Polynomials, , Solving Systems of Equations, Solving Equations
+@subsection Decomposing Polynomials
+
+@noindent
+@ignore
+@starindex
+@end ignore
+@tindex poly
+The @code{poly} function takes a polynomial and a variable as
+arguments, and returns a vector of polynomial coefficients (constant
+coefficient first). For example, @samp{poly(x^3 + 2 x, x)} returns
+@expr{[0, 2, 0, 1]}. If the input is not a polynomial in @expr{x},
+the call to @code{poly} is left in symbolic form. If the input does
+not involve the variable @expr{x}, the input is returned in a list
+of length one, representing a polynomial with only a constant
+coefficient. The call @samp{poly(x, x)} returns the vector @expr{[0, 1]}.
+The last element of the returned vector is guaranteed to be nonzero;
+note that @samp{poly(0, x)} returns the empty vector @expr{[]}.
+Note also that @expr{x} may actually be any formula; for example,
+@samp{poly(sin(x)^2 - sin(x) + 3, sin(x))} returns @expr{[3, -1, 1]}.
+
+@cindex Coefficients of polynomial
+@cindex Degree of polynomial
+To get the @expr{x^k} coefficient of polynomial @expr{p}, use
+@samp{poly(p, x)_(k+1)}. To get the degree of polynomial @expr{p},
+use @samp{vlen(poly(p, x)) - 1}. For example, @samp{poly((x+1)^4, x)}
+returns @samp{[1, 4, 6, 4, 1]}, so @samp{poly((x+1)^4, x)_(2+1)}
+gives the @expr{x^2} coefficient of this polynomial, 6.
+
+@ignore
+@starindex
+@end ignore
+@tindex gpoly
+One important feature of the solver is its ability to recognize
+formulas which are ``essentially'' polynomials. This ability is
+made available to the user through the @code{gpoly} function, which
+is used just like @code{poly}: @samp{gpoly(@var{expr}, @var{var})}.
+If @var{expr} is a polynomial in some term which includes @var{var}, then
+this function will return a vector @samp{[@var{x}, @var{c}, @var{a}]}
+where @var{x} is the term that depends on @var{var}, @var{c} is a
+vector of polynomial coefficients (like the one returned by @code{poly}),
+and @var{a} is a multiplier which is usually 1. Basically,
+@samp{@var{expr} = @var{a}*(@var{c}_1 + @var{c}_2 @var{x} +
+@var{c}_3 @var{x}^2 + ...)}. The last element of @var{c} is
+guaranteed to be non-zero, and @var{c} will not equal @samp{[1]}
+(i.e., the trivial decomposition @var{expr} = @var{x} is not
+considered a polynomial). One side effect is that @samp{gpoly(x, x)}
+and @samp{gpoly(6, x)}, both of which might be expected to recognize
+their arguments as polynomials, will not because the decomposition
+is considered trivial.
+
+For example, @samp{gpoly((x-2)^2, x)} returns @samp{[x, [4, -4, 1], 1]},
+since the expanded form of this polynomial is @expr{4 - 4 x + x^2}.
+
+The term @var{x} may itself be a polynomial in @var{var}. This is
+done to reduce the size of the @var{c} vector. For example,
+@samp{gpoly(x^4 + x^2 - 1, x)} returns @samp{[x^2, [-1, 1, 1], 1]},
+since a quadratic polynomial in @expr{x^2} is easier to solve than
+a quartic polynomial in @expr{x}.
+
+A few more examples of the kinds of polynomials @code{gpoly} can
+discover:
+
+@smallexample
+sin(x) - 1 [sin(x), [-1, 1], 1]
+x + 1/x - 1 [x, [1, -1, 1], 1/x]
+x + 1/x [x^2, [1, 1], 1/x]
+x^3 + 2 x [x^2, [2, 1], x]
+x + x^2:3 + sqrt(x) [x^1:6, [1, 1, 0, 1], x^1:2]
+x^(2a) + 2 x^a + 5 [x^a, [5, 2, 1], 1]
+(exp(-x) + exp(x)) / 2 [e^(2 x), [0.5, 0.5], e^-x]
+@end smallexample
+
+The @code{poly} and @code{gpoly} functions accept a third integer argument
+which specifies the largest degree of polynomial that is acceptable.
+If this is @expr{n}, then only @var{c} vectors of length @expr{n+1}
+or less will be returned. Otherwise, the @code{poly} or @code{gpoly}
+call will remain in symbolic form. For example, the equation solver
+can handle quartics and smaller polynomials, so it calls
+@samp{gpoly(@var{expr}, @var{var}, 4)} to discover whether @var{expr}
+can be treated by its linear, quadratic, cubic, or quartic formulas.
+
+@ignore
+@starindex
+@end ignore
+@tindex pdeg
+The @code{pdeg} function computes the degree of a polynomial;
+@samp{pdeg(p,x)} is the highest power of @code{x} that appears in
+@code{p}. This is the same as @samp{vlen(poly(p,x))-1}, but is
+much more efficient. If @code{p} is constant with respect to @code{x},
+then @samp{pdeg(p,x) = 0}. If @code{p} is not a polynomial in @code{x}
+(e.g., @samp{pdeg(2 cos(x), x)}, the function remains unevaluated.
+It is possible to omit the second argument @code{x}, in which case
+@samp{pdeg(p)} returns the highest total degree of any term of the
+polynomial, counting all variables that appear in @code{p}. Note
+that @code{pdeg(c) = pdeg(c,x) = 0} for any nonzero constant @code{c};
+the degree of the constant zero is considered to be @code{-inf}
+(minus infinity).
+
+@ignore
+@starindex
+@end ignore
+@tindex plead
+The @code{plead} function finds the leading term of a polynomial.
+Thus @samp{plead(p,x)} is equivalent to @samp{poly(p,x)_vlen(poly(p,x))},
+though again more efficient. In particular, @samp{plead((2x+1)^10, x)}
+returns 1024 without expanding out the list of coefficients. The
+value of @code{plead(p,x)} will be zero only if @expr{p = 0}.
+
+@ignore
+@starindex
+@end ignore
+@tindex pcont
+The @code{pcont} function finds the @dfn{content} of a polynomial. This
+is the greatest common divisor of all the coefficients of the polynomial.
+With two arguments, @code{pcont(p,x)} effectively uses @samp{poly(p,x)}
+to get a list of coefficients, then uses @code{pgcd} (the polynomial
+GCD function) to combine these into an answer. For example,
+@samp{pcont(4 x y^2 + 6 x^2 y, x)} is @samp{2 y}. The content is
+basically the ``biggest'' polynomial that can be divided into @code{p}
+exactly. The sign of the content is the same as the sign of the leading
+coefficient.
+
+With only one argument, @samp{pcont(p)} computes the numerical
+content of the polynomial, i.e., the @code{gcd} of the numerical
+coefficients of all the terms in the formula. Note that @code{gcd}
+is defined on rational numbers as well as integers; it computes
+the @code{gcd} of the numerators and the @code{lcm} of the
+denominators. Thus @samp{pcont(4:3 x y^2 + 6 x^2 y)} returns 2:3.
+Dividing the polynomial by this number will clear all the
+denominators, as well as dividing by any common content in the
+numerators. The numerical content of a polynomial is negative only
+if all the coefficients in the polynomial are negative.
+
+@ignore
+@starindex
+@end ignore
+@tindex pprim
+The @code{pprim} function finds the @dfn{primitive part} of a
+polynomial, which is simply the polynomial divided (using @code{pdiv}
+if necessary) by its content. If the input polynomial has rational
+coefficients, the result will have integer coefficients in simplest
+terms.
+
+@node Numerical Solutions, Curve Fitting, Solving Equations, Algebra
+@section Numerical Solutions
+
+@noindent
+Not all equations can be solved symbolically. The commands in this
+section use numerical algorithms that can find a solution to a specific
+instance of an equation to any desired accuracy. Note that the
+numerical commands are slower than their algebraic cousins; it is a
+good idea to try @kbd{a S} before resorting to these commands.
+
+(@xref{Curve Fitting}, for some other, more specialized, operations
+on numerical data.)
+
+@menu
+* Root Finding::
+* Minimization::
+* Numerical Systems of Equations::
+@end menu
+
+@node Root Finding, Minimization, Numerical Solutions, Numerical Solutions
+@subsection Root Finding
+
+@noindent
+@kindex a R
+@pindex calc-find-root
+@tindex root
+@cindex Newton's method
+@cindex Roots of equations
+@cindex Numerical root-finding
+The @kbd{a R} (@code{calc-find-root}) [@code{root}] command finds a
+numerical solution (or @dfn{root}) of an equation. (This command treats
+inequalities the same as equations. If the input is any other kind
+of formula, it is interpreted as an equation of the form @expr{X = 0}.)
+
+The @kbd{a R} command requires an initial guess on the top of the
+stack, and a formula in the second-to-top position. It prompts for a
+solution variable, which must appear in the formula. All other variables
+that appear in the formula must have assigned values, i.e., when
+a value is assigned to the solution variable and the formula is
+evaluated with @kbd{=}, it should evaluate to a number. Any assigned
+value for the solution variable itself is ignored and unaffected by
+this command.
+
+When the command completes, the initial guess is replaced on the stack
+by a vector of two numbers: The value of the solution variable that
+solves the equation, and the difference between the lefthand and
+righthand sides of the equation at that value. Ordinarily, the second
+number will be zero or very nearly zero. (Note that Calc uses a
+slightly higher precision while finding the root, and thus the second
+number may be slightly different from the value you would compute from
+the equation yourself.)
+
+The @kbd{v h} (@code{calc-head}) command is a handy way to extract
+the first element of the result vector, discarding the error term.
+
+The initial guess can be a real number, in which case Calc searches
+for a real solution near that number, or a complex number, in which
+case Calc searches the whole complex plane near that number for a
+solution, or it can be an interval form which restricts the search
+to real numbers inside that interval.
+
+Calc tries to use @kbd{a d} to take the derivative of the equation.
+If this succeeds, it uses Newton's method. If the equation is not
+differentiable Calc uses a bisection method. (If Newton's method
+appears to be going astray, Calc switches over to bisection if it
+can, or otherwise gives up. In this case it may help to try again
+with a slightly different initial guess.) If the initial guess is a
+complex number, the function must be differentiable.
+
+If the formula (or the difference between the sides of an equation)
+is negative at one end of the interval you specify and positive at
+the other end, the root finder is guaranteed to find a root.
+Otherwise, Calc subdivides the interval into small parts looking for
+positive and negative values to bracket the root. When your guess is
+an interval, Calc will not look outside that interval for a root.
+
+@kindex H a R
+@tindex wroot
+The @kbd{H a R} [@code{wroot}] command is similar to @kbd{a R}, except
+that if the initial guess is an interval for which the function has
+the same sign at both ends, then rather than subdividing the interval
+Calc attempts to widen it to enclose a root. Use this mode if
+you are not sure if the function has a root in your interval.
+
+If the function is not differentiable, and you give a simple number
+instead of an interval as your initial guess, Calc uses this widening
+process even if you did not type the Hyperbolic flag. (If the function
+@emph{is} differentiable, Calc uses Newton's method which does not
+require a bounding interval in order to work.)
+
+If Calc leaves the @code{root} or @code{wroot} function in symbolic
+form on the stack, it will normally display an explanation for why
+no root was found. If you miss this explanation, press @kbd{w}
+(@code{calc-why}) to get it back.
+
+@node Minimization, Numerical Systems of Equations, Root Finding, Numerical Solutions
+@subsection Minimization
+
+@noindent
+@kindex a N
+@kindex H a N
+@kindex a X
+@kindex H a X
+@pindex calc-find-minimum
+@pindex calc-find-maximum
+@tindex minimize
+@tindex maximize
+@cindex Minimization, numerical
+The @kbd{a N} (@code{calc-find-minimum}) [@code{minimize}] command
+finds a minimum value for a formula. It is very similar in operation
+to @kbd{a R} (@code{calc-find-root}): You give the formula and an initial
+guess on the stack, and are prompted for the name of a variable. The guess
+may be either a number near the desired minimum, or an interval enclosing
+the desired minimum. The function returns a vector containing the
+value of the variable which minimizes the formula's value, along
+with the minimum value itself.
+
+Note that this command looks for a @emph{local} minimum. Many functions
+have more than one minimum; some, like
+@texline @math{x \sin x},
+@infoline @expr{x sin(x)},
+have infinitely many. In fact, there is no easy way to define the
+``global'' minimum of
+@texline @math{x \sin x}
+@infoline @expr{x sin(x)}
+but Calc can still locate any particular local minimum
+for you. Calc basically goes downhill from the initial guess until it
+finds a point at which the function's value is greater both to the left
+and to the right. Calc does not use derivatives when minimizing a function.
+
+If your initial guess is an interval and it looks like the minimum
+occurs at one or the other endpoint of the interval, Calc will return
+that endpoint only if that endpoint is closed; thus, minimizing @expr{17 x}
+over @expr{[2..3]} will return @expr{[2, 38]}, but minimizing over
+@expr{(2..3]} would report no minimum found. In general, you should
+use closed intervals to find literally the minimum value in that
+range of @expr{x}, or open intervals to find the local minimum, if
+any, that happens to lie in that range.
+
+Most functions are smooth and flat near their minimum values. Because
+of this flatness, if the current precision is, say, 12 digits, the
+variable can only be determined meaningfully to about six digits. Thus
+you should set the precision to twice as many digits as you need in your
+answer.
+
+@ignore
+@mindex wmin@idots
+@end ignore
+@tindex wminimize
+@ignore
+@mindex wmax@idots
+@end ignore
+@tindex wmaximize
+The @kbd{H a N} [@code{wminimize}] command, analogously to @kbd{H a R},
+expands the guess interval to enclose a minimum rather than requiring
+that the minimum lie inside the interval you supply.
+
+The @kbd{a X} (@code{calc-find-maximum}) [@code{maximize}] and
+@kbd{H a X} [@code{wmaximize}] commands effectively minimize the
+negative of the formula you supply.
+
+The formula must evaluate to a real number at all points inside the
+interval (or near the initial guess if the guess is a number). If
+the initial guess is a complex number the variable will be minimized
+over the complex numbers; if it is real or an interval it will
+be minimized over the reals.
+
+@node Numerical Systems of Equations, , Minimization, Numerical Solutions
+@subsection Systems of Equations
+
+@noindent
+@cindex Systems of equations, numerical
+The @kbd{a R} command can also solve systems of equations. In this
+case, the equation should instead be a vector of equations, the
+guess should instead be a vector of numbers (intervals are not
+supported), and the variable should be a vector of variables. You
+can omit the brackets while entering the list of variables. Each
+equation must be differentiable by each variable for this mode to
+work. The result will be a vector of two vectors: The variable
+values that solved the system of equations, and the differences
+between the sides of the equations with those variable values.
+There must be the same number of equations as variables. Since
+only plain numbers are allowed as guesses, the Hyperbolic flag has
+no effect when solving a system of equations.
+
+It is also possible to minimize over many variables with @kbd{a N}
+(or maximize with @kbd{a X}). Once again the variable name should
+be replaced by a vector of variables, and the initial guess should
+be an equal-sized vector of initial guesses. But, unlike the case of
+multidimensional @kbd{a R}, the formula being minimized should
+still be a single formula, @emph{not} a vector. Beware that
+multidimensional minimization is currently @emph{very} slow.
+
+@node Curve Fitting, Summations, Numerical Solutions, Algebra
+@section Curve Fitting
+
+@noindent
+The @kbd{a F} command fits a set of data to a @dfn{model formula},
+such as @expr{y = m x + b} where @expr{m} and @expr{b} are parameters
+to be determined. For a typical set of measured data there will be
+no single @expr{m} and @expr{b} that exactly fit the data; in this
+case, Calc chooses values of the parameters that provide the closest
+possible fit. The model formula can be entered in various ways after
+the key sequence @kbd{a F} is pressed.
+
+If the letter @kbd{P} is pressed after @kbd{a F} but before the model
+description is entered, the data as well as the model formula will be
+plotted after the formula is determined. This will be indicated by a
+``P'' in the minibuffer after the help message.
+
+@menu
+* Linear Fits::
+* Polynomial and Multilinear Fits::
+* Error Estimates for Fits::
+* Standard Nonlinear Models::
+* Curve Fitting Details::
+* Interpolation::
+@end menu
+
+@node Linear Fits, Polynomial and Multilinear Fits, Curve Fitting, Curve Fitting
+@subsection Linear Fits
+
+@noindent
+@kindex a F
+@pindex calc-curve-fit
+@tindex fit
+@cindex Linear regression
+@cindex Least-squares fits
+The @kbd{a F} (@code{calc-curve-fit}) [@code{fit}] command attempts
+to fit a set of data (@expr{x} and @expr{y} vectors of numbers) to a
+straight line, polynomial, or other function of @expr{x}. For the
+moment we will consider only the case of fitting to a line, and we
+will ignore the issue of whether or not the model was in fact a good
+fit for the data.
+
+In a standard linear least-squares fit, we have a set of @expr{(x,y)}
+data points that we wish to fit to the model @expr{y = m x + b}
+by adjusting the parameters @expr{m} and @expr{b} to make the @expr{y}
+values calculated from the formula be as close as possible to the actual
+@expr{y} values in the data set. (In a polynomial fit, the model is
+instead, say, @expr{y = a x^3 + b x^2 + c x + d}. In a multilinear fit,
+we have data points of the form @expr{(x_1,x_2,x_3,y)} and our model is
+@expr{y = a x_1 + b x_2 + c x_3 + d}. These will be discussed later.)
+
+In the model formula, variables like @expr{x} and @expr{x_2} are called
+the @dfn{independent variables}, and @expr{y} is the @dfn{dependent
+variable}. Variables like @expr{m}, @expr{a}, and @expr{b} are called
+the @dfn{parameters} of the model.
+
+The @kbd{a F} command takes the data set to be fitted from the stack.
+By default, it expects the data in the form of a matrix. For example,
+for a linear or polynomial fit, this would be a
+@texline @math{2\times N}
+@infoline 2xN
+matrix where the first row is a list of @expr{x} values and the second
+row has the corresponding @expr{y} values. For the multilinear fit
+shown above, the matrix would have four rows (@expr{x_1}, @expr{x_2},
+@expr{x_3}, and @expr{y}, respectively).
+
+If you happen to have an
+@texline @math{N\times2}
+@infoline Nx2
+matrix instead of a
+@texline @math{2\times N}
+@infoline 2xN
+matrix, just press @kbd{v t} first to transpose the matrix.
+
+After you type @kbd{a F}, Calc prompts you to select a model. For a
+linear fit, press the digit @kbd{1}.
+
+Calc then prompts for you to name the variables. By default it chooses
+high letters like @expr{x} and @expr{y} for independent variables and
+low letters like @expr{a} and @expr{b} for parameters. (The dependent
+variable doesn't need a name.) The two kinds of variables are separated
+by a semicolon. Since you generally care more about the names of the
+independent variables than of the parameters, Calc also allows you to
+name only those and let the parameters use default names.
+
+For example, suppose the data matrix
+
+@ifnottex
+@example
+@group
+[ [ 1, 2, 3, 4, 5 ]
+ [ 5, 7, 9, 11, 13 ] ]
+@end group
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\turnoffactive
+\beforedisplay
+$$ \pmatrix{ 1 & 2 & 3 & 4 & 5 \cr
+ 5 & 7 & 9 & 11 & 13 }
+$$
+\afterdisplay
+@end tex
+
+@noindent
+is on the stack and we wish to do a simple linear fit. Type
+@kbd{a F}, then @kbd{1} for the model, then @key{RET} to use
+the default names. The result will be the formula @expr{3. + 2. x}
+on the stack. Calc has created the model expression @kbd{a + b x},
+then found the optimal values of @expr{a} and @expr{b} to fit the
+data. (In this case, it was able to find an exact fit.) Calc then
+substituted those values for @expr{a} and @expr{b} in the model
+formula.
+
+The @kbd{a F} command puts two entries in the trail. One is, as
+always, a copy of the result that went to the stack; the other is
+a vector of the actual parameter values, written as equations:
+@expr{[a = 3, b = 2]}, in case you'd rather read them in a list
+than pick them out of the formula. (You can type @kbd{t y}
+to move this vector to the stack; see @ref{Trail Commands}.
+
+Specifying a different independent variable name will affect the
+resulting formula: @kbd{a F 1 k @key{RET}} produces @kbd{3 + 2 k}.
+Changing the parameter names (say, @kbd{a F 1 k;b,m @key{RET}}) will affect
+the equations that go into the trail.
+
+@tex
+\bigskip
+@end tex
+
+To see what happens when the fit is not exact, we could change
+the number 13 in the data matrix to 14 and try the fit again.
+The result is:
+
+@example
+2.6 + 2.2 x
+@end example
+
+Evaluating this formula, say with @kbd{v x 5 @key{RET} @key{TAB} V M $ @key{RET}}, shows
+a reasonably close match to the y-values in the data.
+
+@example
+[4.8, 7., 9.2, 11.4, 13.6]
+@end example
+
+Since there is no line which passes through all the @var{n} data points,
+Calc has chosen a line that best approximates the data points using
+the method of least squares. The idea is to define the @dfn{chi-square}
+error measure
+
+@ifnottex
+@example
+chi^2 = sum((y_i - (a + b x_i))^2, i, 1, N)
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ \chi^2 = \sum_{i=1}^N (y_i - (a + b x_i))^2 $$
+\afterdisplay
+@end tex
+
+@noindent
+which is clearly zero if @expr{a + b x} exactly fits all data points,
+and increases as various @expr{a + b x_i} values fail to match the
+corresponding @expr{y_i} values. There are several reasons why the
+summand is squared, one of them being to ensure that
+@texline @math{\chi^2 \ge 0}.
+@infoline @expr{chi^2 >= 0}.
+Least-squares fitting simply chooses the values of @expr{a} and @expr{b}
+for which the error
+@texline @math{\chi^2}
+@infoline @expr{chi^2}
+is as small as possible.
+
+Other kinds of models do the same thing but with a different model
+formula in place of @expr{a + b x_i}.
+
+@tex
+\bigskip
+@end tex
+
+A numeric prefix argument causes the @kbd{a F} command to take the
+data in some other form than one big matrix. A positive argument @var{n}
+will take @var{N} items from the stack, corresponding to the @var{n} rows
+of a data matrix. In the linear case, @var{n} must be 2 since there
+is always one independent variable and one dependent variable.
+
+A prefix of zero or plain @kbd{C-u} is a compromise; Calc takes two
+items from the stack, an @var{n}-row matrix of @expr{x} values, and a
+vector of @expr{y} values. If there is only one independent variable,
+the @expr{x} values can be either a one-row matrix or a plain vector,
+in which case the @kbd{C-u} prefix is the same as a @w{@kbd{C-u 2}} prefix.
+
+@node Polynomial and Multilinear Fits, Error Estimates for Fits, Linear Fits, Curve Fitting
+@subsection Polynomial and Multilinear Fits
+
+@noindent
+To fit the data to higher-order polynomials, just type one of the
+digits @kbd{2} through @kbd{9} when prompted for a model. For example,
+we could fit the original data matrix from the previous section
+(with 13, not 14) to a parabola instead of a line by typing
+@kbd{a F 2 @key{RET}}.
+
+@example
+2.00000000001 x - 1.5e-12 x^2 + 2.99999999999
+@end example
+
+Note that since the constant and linear terms are enough to fit the
+data exactly, it's no surprise that Calc chose a tiny contribution
+for @expr{x^2}. (The fact that it's not exactly zero is due only
+to roundoff error. Since our data are exact integers, we could get
+an exact answer by typing @kbd{m f} first to get Fraction mode.
+Then the @expr{x^2} term would vanish altogether. Usually, though,
+the data being fitted will be approximate floats so Fraction mode
+won't help.)
+
+Doing the @kbd{a F 2} fit on the data set with 14 instead of 13
+gives a much larger @expr{x^2} contribution, as Calc bends the
+line slightly to improve the fit.
+
+@example
+0.142857142855 x^2 + 1.34285714287 x + 3.59999999998
+@end example
+
+An important result from the theory of polynomial fitting is that it
+is always possible to fit @var{n} data points exactly using a polynomial
+of degree @mathit{@var{n}-1}, sometimes called an @dfn{interpolating polynomial}.
+Using the modified (14) data matrix, a model number of 4 gives
+a polynomial that exactly matches all five data points:
+
+@example
+0.04167 x^4 - 0.4167 x^3 + 1.458 x^2 - 0.08333 x + 4.
+@end example
+
+The actual coefficients we get with a precision of 12, like
+@expr{0.0416666663588}, clearly suffer from loss of precision.
+It is a good idea to increase the working precision to several
+digits beyond what you need when you do a fitting operation.
+Or, if your data are exact, use Fraction mode to get exact
+results.
+
+You can type @kbd{i} instead of a digit at the model prompt to fit
+the data exactly to a polynomial. This just counts the number of
+columns of the data matrix to choose the degree of the polynomial
+automatically.
+
+Fitting data ``exactly'' to high-degree polynomials is not always
+a good idea, though. High-degree polynomials have a tendency to
+wiggle uncontrollably in between the fitting data points. Also,
+if the exact-fit polynomial is going to be used to interpolate or
+extrapolate the data, it is numerically better to use the @kbd{a p}
+command described below. @xref{Interpolation}.
+
+@tex
+\bigskip
+@end tex
+
+Another generalization of the linear model is to assume the
+@expr{y} values are a sum of linear contributions from several
+@expr{x} values. This is a @dfn{multilinear} fit, and it is also
+selected by the @kbd{1} digit key. (Calc decides whether the fit
+is linear or multilinear by counting the rows in the data matrix.)
+
+Given the data matrix,
+
+@example
+@group
+[ [ 1, 2, 3, 4, 5 ]
+ [ 7, 2, 3, 5, 2 ]
+ [ 14.5, 15, 18.5, 22.5, 24 ] ]
+@end group
+@end example
+
+@noindent
+the command @kbd{a F 1 @key{RET}} will call the first row @expr{x} and the
+second row @expr{y}, and will fit the values in the third row to the
+model @expr{a + b x + c y}.
+
+@example
+8. + 3. x + 0.5 y
+@end example
+
+Calc can do multilinear fits with any number of independent variables
+(i.e., with any number of data rows).
+
+@tex
+\bigskip
+@end tex
+
+Yet another variation is @dfn{homogeneous} linear models, in which
+the constant term is known to be zero. In the linear case, this
+means the model formula is simply @expr{a x}; in the multilinear
+case, the model might be @expr{a x + b y + c z}; and in the polynomial
+case, the model could be @expr{a x + b x^2 + c x^3}. You can get
+a homogeneous linear or multilinear model by pressing the letter
+@kbd{h} followed by a regular model key, like @kbd{1} or @kbd{2}.
+This will be indicated by an ``h'' in the minibuffer after the help
+message.
+
+It is certainly possible to have other constrained linear models,
+like @expr{2.3 + a x} or @expr{a - 4 x}. While there is no single
+key to select models like these, a later section shows how to enter
+any desired model by hand. In the first case, for example, you
+would enter @kbd{a F ' 2.3 + a x}.
+
+Another class of models that will work but must be entered by hand
+are multinomial fits, e.g., @expr{a + b x + c y + d x^2 + e y^2 + f x y}.
+
+@node Error Estimates for Fits, Standard Nonlinear Models, Polynomial and Multilinear Fits, Curve Fitting
+@subsection Error Estimates for Fits
+
+@noindent
+@kindex H a F
+@tindex efit
+With the Hyperbolic flag, @kbd{H a F} [@code{efit}] performs the same
+fitting operation as @kbd{a F}, but reports the coefficients as error
+forms instead of plain numbers. Fitting our two data matrices (first
+with 13, then with 14) to a line with @kbd{H a F} gives the results,
+
+@example
+3. + 2. x
+2.6 +/- 0.382970843103 + 2.2 +/- 0.115470053838 x
+@end example
+
+In the first case the estimated errors are zero because the linear
+fit is perfect. In the second case, the errors are nonzero but
+moderately small, because the data are still very close to linear.
+
+It is also possible for the @emph{input} to a fitting operation to
+contain error forms. The data values must either all include errors
+or all be plain numbers. Error forms can go anywhere but generally
+go on the numbers in the last row of the data matrix. If the last
+row contains error forms
+@texline `@var{y_i}@w{ @tfn{+/-} }@math{\sigma_i}',
+@infoline `@var{y_i}@w{ @tfn{+/-} }@var{sigma_i}',
+then the
+@texline @math{\chi^2}
+@infoline @expr{chi^2}
+statistic is now,
+
+@ifnottex
+@example
+chi^2 = sum(((y_i - (a + b x_i)) / sigma_i)^2, i, 1, N)
+@end example
+@end ifnottex
+@tex
+\turnoffactive
+\beforedisplay
+$$ \chi^2 = \sum_{i=1}^N \left(y_i - (a + b x_i) \over \sigma_i\right)^2 $$
+\afterdisplay
+@end tex
+
+@noindent
+so that data points with larger error estimates contribute less to
+the fitting operation.
+
+If there are error forms on other rows of the data matrix, all the
+errors for a given data point are combined; the square root of the
+sum of the squares of the errors forms the
+@texline @math{\sigma_i}
+@infoline @expr{sigma_i}
+used for the data point.
+
+Both @kbd{a F} and @kbd{H a F} can accept error forms in the input
+matrix, although if you are concerned about error analysis you will
+probably use @kbd{H a F} so that the output also contains error
+estimates.
+
+If the input contains error forms but all the
+@texline @math{\sigma_i}
+@infoline @expr{sigma_i}
+values are the same, it is easy to see that the resulting fitted model
+will be the same as if the input did not have error forms at all
+@texline (@math{\chi^2}
+@infoline (@expr{chi^2}
+is simply scaled uniformly by
+@texline @math{1 / \sigma^2},
+@infoline @expr{1 / sigma^2},
+which doesn't affect where it has a minimum). But there @emph{will} be
+a difference in the estimated errors of the coefficients reported by
+@kbd{H a F}.
+
+Consult any text on statistical modeling of data for a discussion
+of where these error estimates come from and how they should be
+interpreted.
+
+@tex
+\bigskip
+@end tex
+
+@kindex I a F
+@tindex xfit
+With the Inverse flag, @kbd{I a F} [@code{xfit}] produces even more
+information. The result is a vector of six items:
+
+@enumerate
+@item
+The model formula with error forms for its coefficients or
+parameters. This is the result that @kbd{H a F} would have
+produced.
+
+@item
+A vector of ``raw'' parameter values for the model. These are the
+polynomial coefficients or other parameters as plain numbers, in the
+same order as the parameters appeared in the final prompt of the
+@kbd{I a F} command. For polynomials of degree @expr{d}, this vector
+will have length @expr{M = d+1} with the constant term first.
+
+@item
+The covariance matrix @expr{C} computed from the fit. This is
+an @var{m}x@var{m} symmetric matrix; the diagonal elements
+@texline @math{C_{jj}}
+@infoline @expr{C_j_j}
+are the variances
+@texline @math{\sigma_j^2}
+@infoline @expr{sigma_j^2}
+of the parameters. The other elements are covariances
+@texline @math{\sigma_{ij}^2}
+@infoline @expr{sigma_i_j^2}
+that describe the correlation between pairs of parameters. (A related
+set of numbers, the @dfn{linear correlation coefficients}
+@texline @math{r_{ij}},
+@infoline @expr{r_i_j},
+are defined as
+@texline @math{\sigma_{ij}^2 / \sigma_i \, \sigma_j}.)
+@infoline @expr{sigma_i_j^2 / sigma_i sigma_j}.)
+
+@item
+A vector of @expr{M} ``parameter filter'' functions whose
+meanings are described below. If no filters are necessary this
+will instead be an empty vector; this is always the case for the
+polynomial and multilinear fits described so far.
+
+@item
+The value of
+@texline @math{\chi^2}
+@infoline @expr{chi^2}
+for the fit, calculated by the formulas shown above. This gives a
+measure of the quality of the fit; statisticians consider
+@texline @math{\chi^2 \approx N - M}
+@infoline @expr{chi^2 = N - M}
+to indicate a moderately good fit (where again @expr{N} is the number of
+data points and @expr{M} is the number of parameters).
+
+@item
+A measure of goodness of fit expressed as a probability @expr{Q}.
+This is computed from the @code{utpc} probability distribution
+function using
+@texline @math{\chi^2}
+@infoline @expr{chi^2}
+with @expr{N - M} degrees of freedom. A
+value of 0.5 implies a good fit; some texts recommend that often
+@expr{Q = 0.1} or even 0.001 can signify an acceptable fit. In
+particular,
+@texline @math{\chi^2}
+@infoline @expr{chi^2}
+statistics assume the errors in your inputs
+follow a normal (Gaussian) distribution; if they don't, you may
+have to accept smaller values of @expr{Q}.
+
+The @expr{Q} value is computed only if the input included error
+estimates. Otherwise, Calc will report the symbol @code{nan}
+for @expr{Q}. The reason is that in this case the
+@texline @math{\chi^2}
+@infoline @expr{chi^2}
+value has effectively been used to estimate the original errors
+in the input, and thus there is no redundant information left
+over to use for a confidence test.
+@end enumerate
+
+@node Standard Nonlinear Models, Curve Fitting Details, Error Estimates for Fits, Curve Fitting
+@subsection Standard Nonlinear Models
+
+@noindent
+The @kbd{a F} command also accepts other kinds of models besides
+lines and polynomials. Some common models have quick single-key
+abbreviations; others must be entered by hand as algebraic formulas.
+
+Here is a complete list of the standard models recognized by @kbd{a F}:
+
+@table @kbd
+@item 1
+Linear or multilinear. @mathit{a + b x + c y + d z}.
+@item 2-9
+Polynomials. @mathit{a + b x + c x^2 + d x^3}.
+@item e
+Exponential. @mathit{a} @tfn{exp}@mathit{(b x)} @tfn{exp}@mathit{(c y)}.
+@item E
+Base-10 exponential. @mathit{a} @tfn{10^}@mathit{(b x)} @tfn{10^}@mathit{(c y)}.
+@item x
+Exponential (alternate notation). @tfn{exp}@mathit{(a + b x + c y)}.
+@item X
+Base-10 exponential (alternate). @tfn{10^}@mathit{(a + b x + c y)}.
+@item l
+Logarithmic. @mathit{a + b} @tfn{ln}@mathit{(x) + c} @tfn{ln}@mathit{(y)}.
+@item L
+Base-10 logarithmic. @mathit{a + b} @tfn{log10}@mathit{(x) + c} @tfn{log10}@mathit{(y)}.
+@item ^
+General exponential. @mathit{a b^x c^y}.
+@item p
+Power law. @mathit{a x^b y^c}.
+@item q
+Quadratic. @mathit{a + b (x-c)^2 + d (x-e)^2}.
+@item g
+Gaussian.
+@texline @math{{a \over b \sqrt{2 \pi}} \exp\left( -{1 \over 2} \left( x - c \over b \right)^2 \right)}.
+@infoline @mathit{(a / b sqrt(2 pi)) exp(-0.5*((x-c)/b)^2)}.
+@item s
+Logistic @emph{s} curve.
+@texline @math{a/(1+e^{b(x-c)})}.
+@infoline @mathit{a/(1 + exp(b (x - c)))}.
+@item b
+Logistic bell curve.
+@texline @math{ae^{b(x-c)}/(1+e^{b(x-c)})^2}.
+@infoline @mathit{a exp(b (x - c))/(1 + exp(b (x - c)))^2}.
+@item o
+Hubbert linearization.
+@texline @math{{y \over x} = a(1-x/b)}.
+@infoline @mathit{(y/x) = a (1 - x/b)}.
+@end table
+
+All of these models are used in the usual way; just press the appropriate
+letter at the model prompt, and choose variable names if you wish. The
+result will be a formula as shown in the above table, with the best-fit
+values of the parameters substituted. (You may find it easier to read
+the parameter values from the vector that is placed in the trail.)
+
+All models except Gaussian, logistics, Hubbert and polynomials can
+generalize as shown to any number of independent variables. Also, all
+the built-in models except for the logistic and Hubbert curves have an
+additive or multiplicative parameter shown as @expr{a} in the above table
+which can be replaced by zero or one, as appropriate, by typing @kbd{h}
+before the model key.
+
+Note that many of these models are essentially equivalent, but express
+the parameters slightly differently. For example, @expr{a b^x} and
+the other two exponential models are all algebraic rearrangements of
+each other. Also, the ``quadratic'' model is just a degree-2 polynomial
+with the parameters expressed differently. Use whichever form best
+matches the problem.
+
+The HP-28/48 calculators support four different models for curve
+fitting, called @code{LIN}, @code{LOG}, @code{EXP}, and @code{PWR}.
+These correspond to Calc models @samp{a + b x}, @samp{a + b ln(x)},
+@samp{a exp(b x)}, and @samp{a x^b}, respectively. In each case,
+@expr{a} is what the HP-48 identifies as the ``intercept,'' and
+@expr{b} is what it calls the ``slope.''
+
+@tex
+\bigskip
+@end tex
+
+If the model you want doesn't appear on this list, press @kbd{'}
+(the apostrophe key) at the model prompt to enter any algebraic
+formula, such as @kbd{m x - b}, as the model. (Not all models
+will work, though---see the next section for details.)
+
+The model can also be an equation like @expr{y = m x + b}.
+In this case, Calc thinks of all the rows of the data matrix on
+equal terms; this model effectively has two parameters
+(@expr{m} and @expr{b}) and two independent variables (@expr{x}
+and @expr{y}), with no ``dependent'' variables. Model equations
+do not need to take this @expr{y =} form. For example, the
+implicit line equation @expr{a x + b y = 1} works fine as a
+model.
+
+When you enter a model, Calc makes an alphabetical list of all
+the variables that appear in the model. These are used for the
+default parameters, independent variables, and dependent variable
+(in that order). If you enter a plain formula (not an equation),
+Calc assumes the dependent variable does not appear in the formula
+and thus does not need a name.
+
+For example, if the model formula has the variables @expr{a,mu,sigma,t,x},
+and the data matrix has three rows (meaning two independent variables),
+Calc will use @expr{a,mu,sigma} as the default parameters, and the
+data rows will be named @expr{t} and @expr{x}, respectively. If you
+enter an equation instead of a plain formula, Calc will use @expr{a,mu}
+as the parameters, and @expr{sigma,t,x} as the three independent
+variables.
+
+You can, of course, override these choices by entering something
+different at the prompt. If you leave some variables out of the list,
+those variables must have stored values and those stored values will
+be used as constants in the model. (Stored values for the parameters
+and independent variables are ignored by the @kbd{a F} command.)
+If you list only independent variables, all the remaining variables
+in the model formula will become parameters.
+
+If there are @kbd{$} signs in the model you type, they will stand
+for parameters and all other variables (in alphabetical order)
+will be independent. Use @kbd{$} for one parameter, @kbd{$$} for
+another, and so on. Thus @kbd{$ x + $$} is another way to describe
+a linear model.
+
+If you type a @kbd{$} instead of @kbd{'} at the model prompt itself,
+Calc will take the model formula from the stack. (The data must then
+appear at the second stack level.) The same conventions are used to
+choose which variables in the formula are independent by default and
+which are parameters.
+
+Models taken from the stack can also be expressed as vectors of
+two or three elements, @expr{[@var{model}, @var{vars}]} or
+@expr{[@var{model}, @var{vars}, @var{params}]}. Each of @var{vars}
+and @var{params} may be either a variable or a vector of variables.
+(If @var{params} is omitted, all variables in @var{model} except
+those listed as @var{vars} are parameters.)
+
+When you enter a model manually with @kbd{'}, Calc puts a 3-vector
+describing the model in the trail so you can get it back if you wish.
+
+@tex
+\bigskip
+@end tex
+
+@vindex Model1
+@vindex Model2
+Finally, you can store a model in one of the Calc variables
+@code{Model1} or @code{Model2}, then use this model by typing
+@kbd{a F u} or @kbd{a F U} (respectively). The value stored in
+the variable can be any of the formats that @kbd{a F $} would
+accept for a model on the stack.
+
+@tex
+\bigskip
+@end tex
+
+Calc uses the principal values of inverse functions like @code{ln}
+and @code{arcsin} when doing fits. For example, when you enter
+the model @samp{y = sin(a t + b)} Calc actually uses the easier
+form @samp{arcsin(y) = a t + b}. The @code{arcsin} function always
+returns results in the range from @mathit{-90} to 90 degrees (or the
+equivalent range in radians). Suppose you had data that you
+believed to represent roughly three oscillations of a sine wave,
+so that the argument of the sine might go from zero to
+@texline @math{3\times360}
+@infoline @mathit{3*360}
+degrees.
+The above model would appear to be a good way to determine the
+true frequency and phase of the sine wave, but in practice it
+would fail utterly. The righthand side of the actual model
+@samp{arcsin(y) = a t + b} will grow smoothly with @expr{t}, but
+the lefthand side will bounce back and forth between @mathit{-90} and 90.
+No values of @expr{a} and @expr{b} can make the two sides match,
+even approximately.
+
+There is no good solution to this problem at present. You could
+restrict your data to small enough ranges so that the above problem
+doesn't occur (i.e., not straddling any peaks in the sine wave).
+Or, in this case, you could use a totally different method such as
+Fourier analysis, which is beyond the scope of the @kbd{a F} command.
+(Unfortunately, Calc does not currently have any facilities for
+taking Fourier and related transforms.)
+
+@node Curve Fitting Details, Interpolation, Standard Nonlinear Models, Curve Fitting
+@subsection Curve Fitting Details
+
+@noindent
+Calc's internal least-squares fitter can only handle multilinear
+models. More precisely, it can handle any model of the form
+@expr{a f(x,y,z) + b g(x,y,z) + c h(x,y,z)}, where @expr{a,b,c}
+are the parameters and @expr{x,y,z} are the independent variables
+(of course there can be any number of each, not just three).
+
+In a simple multilinear or polynomial fit, it is easy to see how
+to convert the model into this form. For example, if the model
+is @expr{a + b x + c x^2}, then @expr{f(x) = 1}, @expr{g(x) = x},
+and @expr{h(x) = x^2} are suitable functions.
+
+For most other models, Calc uses a variety of algebraic manipulations
+to try to put the problem into the form
+
+@smallexample
+Y(x,y,z) = A(a,b,c) F(x,y,z) + B(a,b,c) G(x,y,z) + C(a,b,c) H(x,y,z)
+@end smallexample
+
+@noindent
+where @expr{Y,A,B,C,F,G,H} are arbitrary functions. It computes
+@expr{Y}, @expr{F}, @expr{G}, and @expr{H} for all the data points,
+does a standard linear fit to find the values of @expr{A}, @expr{B},
+and @expr{C}, then uses the equation solver to solve for @expr{a,b,c}
+in terms of @expr{A,B,C}.
+
+A remarkable number of models can be cast into this general form.
+We'll look at two examples here to see how it works. The power-law
+model @expr{y = a x^b} with two independent variables and two parameters
+can be rewritten as follows:
+
+@example
+y = a x^b
+y = a exp(b ln(x))
+y = exp(ln(a) + b ln(x))
+ln(y) = ln(a) + b ln(x)
+@end example
+
+@noindent
+which matches the desired form with
+@texline @math{Y = \ln(y)},
+@infoline @expr{Y = ln(y)},
+@texline @math{A = \ln(a)},
+@infoline @expr{A = ln(a)},
+@expr{F = 1}, @expr{B = b}, and
+@texline @math{G = \ln(x)}.
+@infoline @expr{G = ln(x)}.
+Calc thus computes the logarithms of your @expr{y} and @expr{x} values,
+does a linear fit for @expr{A} and @expr{B}, then solves to get
+@texline @math{a = \exp(A)}
+@infoline @expr{a = exp(A)}
+and @expr{b = B}.
+
+Another interesting example is the ``quadratic'' model, which can
+be handled by expanding according to the distributive law.
+
+@example
+y = a + b*(x - c)^2
+y = a + b c^2 - 2 b c x + b x^2
+@end example
+
+@noindent
+which matches with @expr{Y = y}, @expr{A = a + b c^2}, @expr{F = 1},
+@expr{B = -2 b c}, @expr{G = x} (the @mathit{-2} factor could just as easily
+have been put into @expr{G} instead of @expr{B}), @expr{C = b}, and
+@expr{H = x^2}.
+
+The Gaussian model looks quite complicated, but a closer examination
+shows that it's actually similar to the quadratic model but with an
+exponential that can be brought to the top and moved into @expr{Y}.
+
+The logistic models cannot be put into general linear form. For these
+models, and the Hubbert linearization, Calc computes a rough
+approximation for the parameters, then uses the Levenberg-Marquardt
+iterative method to refine the approximations.
+
+Another model that cannot be put into general linear
+form is a Gaussian with a constant background added on, i.e.,
+@expr{d} + the regular Gaussian formula. If you have a model like
+this, your best bet is to replace enough of your parameters with
+constants to make the model linearizable, then adjust the constants
+manually by doing a series of fits. You can compare the fits by
+graphing them, by examining the goodness-of-fit measures returned by
+@kbd{I a F}, or by some other method suitable to your application.
+Note that some models can be linearized in several ways. The
+Gaussian-plus-@var{d} model can be linearized by setting @expr{d}
+(the background) to a constant, or by setting @expr{b} (the standard
+deviation) and @expr{c} (the mean) to constants.
+
+To fit a model with constants substituted for some parameters, just
+store suitable values in those parameter variables, then omit them
+from the list of parameters when you answer the variables prompt.
+
+@tex
+\bigskip
+@end tex
+
+A last desperate step would be to use the general-purpose
+@code{minimize} function rather than @code{fit}. After all, both
+functions solve the problem of minimizing an expression (the
+@texline @math{\chi^2}
+@infoline @expr{chi^2}
+sum) by adjusting certain parameters in the expression. The @kbd{a F}
+command is able to use a vastly more efficient algorithm due to its
+special knowledge about linear chi-square sums, but the @kbd{a N}
+command can do the same thing by brute force.
+
+A compromise would be to pick out a few parameters without which the
+fit is linearizable, and use @code{minimize} on a call to @code{fit}
+which efficiently takes care of the rest of the parameters. The thing
+to be minimized would be the value of
+@texline @math{\chi^2}
+@infoline @expr{chi^2}
+returned as the fifth result of the @code{xfit} function:
+
+@smallexample
+minimize(xfit(gaus(a,b,c,d,x), x, [a,b,c], data)_5, d, guess)
+@end smallexample
+
+@noindent
+where @code{gaus} represents the Gaussian model with background,
+@code{data} represents the data matrix, and @code{guess} represents
+the initial guess for @expr{d} that @code{minimize} requires.
+This operation will only be, shall we say, extraordinarily slow
+rather than astronomically slow (as would be the case if @code{minimize}
+were used by itself to solve the problem).
+
+@tex
+\bigskip
+@end tex
+
+The @kbd{I a F} [@code{xfit}] command is somewhat trickier when
+nonlinear models are used. The second item in the result is the
+vector of ``raw'' parameters @expr{A}, @expr{B}, @expr{C}. The
+covariance matrix is written in terms of those raw parameters.
+The fifth item is a vector of @dfn{filter} expressions. This
+is the empty vector @samp{[]} if the raw parameters were the same
+as the requested parameters, i.e., if @expr{A = a}, @expr{B = b},
+and so on (which is always true if the model is already linear
+in the parameters as written, e.g., for polynomial fits). If the
+parameters had to be rearranged, the fifth item is instead a vector
+of one formula per parameter in the original model. The raw
+parameters are expressed in these ``filter'' formulas as
+@samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)} for @expr{B},
+and so on.
+
+When Calc needs to modify the model to return the result, it replaces
+@samp{fitdummy(1)} in all the filters with the first item in the raw
+parameters list, and so on for the other raw parameters, then
+evaluates the resulting filter formulas to get the actual parameter
+values to be substituted into the original model. In the case of
+@kbd{H a F} and @kbd{I a F} where the parameters must be error forms,
+Calc uses the square roots of the diagonal entries of the covariance
+matrix as error values for the raw parameters, then lets Calc's
+standard error-form arithmetic take it from there.
+
+If you use @kbd{I a F} with a nonlinear model, be sure to remember
+that the covariance matrix is in terms of the raw parameters,
+@emph{not} the actual requested parameters. It's up to you to
+figure out how to interpret the covariances in the presence of
+nontrivial filter functions.
+
+Things are also complicated when the input contains error forms.
+Suppose there are three independent and dependent variables, @expr{x},
+@expr{y}, and @expr{z}, one or more of which are error forms in the
+data. Calc combines all the error values by taking the square root
+of the sum of the squares of the errors. It then changes @expr{x}
+and @expr{y} to be plain numbers, and makes @expr{z} into an error
+form with this combined error. The @expr{Y(x,y,z)} part of the
+linearized model is evaluated, and the result should be an error
+form. The error part of that result is used for
+@texline @math{\sigma_i}
+@infoline @expr{sigma_i}
+for the data point. If for some reason @expr{Y(x,y,z)} does not return
+an error form, the combined error from @expr{z} is used directly for
+@texline @math{\sigma_i}.
+@infoline @expr{sigma_i}.
+Finally, @expr{z} is also stripped of its error
+for use in computing @expr{F(x,y,z)}, @expr{G(x,y,z)} and so on;
+the righthand side of the linearized model is computed in regular
+arithmetic with no error forms.
+
+(While these rules may seem complicated, they are designed to do
+the most reasonable thing in the typical case that @expr{Y(x,y,z)}
+depends only on the dependent variable @expr{z}, and in fact is
+often simply equal to @expr{z}. For common cases like polynomials
+and multilinear models, the combined error is simply used as the
+@texline @math{\sigma}
+@infoline @expr{sigma}
+for the data point with no further ado.)
+
+@tex
+\bigskip
+@end tex
+
+@vindex FitRules
+It may be the case that the model you wish to use is linearizable,
+but Calc's built-in rules are unable to figure it out. Calc uses
+its algebraic rewrite mechanism to linearize a model. The rewrite
+rules are kept in the variable @code{FitRules}. You can edit this
+variable using the @kbd{s e FitRules} command; in fact, there is
+a special @kbd{s F} command just for editing @code{FitRules}.
+@xref{Operations on Variables}.
+
+@xref{Rewrite Rules}, for a discussion of rewrite rules.
+
+@ignore
+@starindex
+@end ignore
+@tindex fitvar
+@ignore
+@starindex
+@end ignore
+@ignore
+@mindex @idots
+@end ignore
+@tindex fitparam
+@ignore
+@starindex
+@end ignore
+@ignore
+@mindex @null
+@end ignore
+@tindex fitmodel
+@ignore
+@starindex
+@end ignore
+@ignore
+@mindex @null
+@end ignore
+@tindex fitsystem
+@ignore
+@starindex
+@end ignore
+@ignore
+@mindex @null
+@end ignore
+@tindex fitdummy
+Calc uses @code{FitRules} as follows. First, it converts the model
+to an equation if necessary and encloses the model equation in a
+call to the function @code{fitmodel} (which is not actually a defined
+function in Calc; it is only used as a placeholder by the rewrite rules).
+Parameter variables are renamed to function calls @samp{fitparam(1)},
+@samp{fitparam(2)}, and so on, and independent variables are renamed
+to @samp{fitvar(1)}, @samp{fitvar(2)}, etc. The dependent variable
+is the highest-numbered @code{fitvar}. For example, the power law
+model @expr{a x^b} is converted to @expr{y = a x^b}, then to
+
+@smallexample
+@group
+fitmodel(fitvar(2) = fitparam(1) fitvar(1)^fitparam(2))
+@end group
+@end smallexample
+
+Calc then applies the rewrites as if by @samp{C-u 0 a r FitRules}.
+(The zero prefix means that rewriting should continue until no further
+changes are possible.)
+
+When rewriting is complete, the @code{fitmodel} call should have
+been replaced by a @code{fitsystem} call that looks like this:
+
+@example
+fitsystem(@var{Y}, @var{FGH}, @var{abc})
+@end example
+
+@noindent
+where @var{Y} is a formula that describes the function @expr{Y(x,y,z)},
+@var{FGH} is the vector of formulas @expr{[F(x,y,z), G(x,y,z), H(x,y,z)]},
+and @var{abc} is the vector of parameter filters which refer to the
+raw parameters as @samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)}
+for @expr{B}, etc. While the number of raw parameters (the length of
+the @var{FGH} vector) is usually the same as the number of original
+parameters (the length of the @var{abc} vector), this is not required.
+
+The power law model eventually boils down to
+
+@smallexample
+@group
+fitsystem(ln(fitvar(2)),
+ [1, ln(fitvar(1))],
+ [exp(fitdummy(1)), fitdummy(2)])
+@end group
+@end smallexample
+
+The actual implementation of @code{FitRules} is complicated; it
+proceeds in four phases. First, common rearrangements are done
+to try to bring linear terms together and to isolate functions like
+@code{exp} and @code{ln} either all the way ``out'' (so that they
+can be put into @var{Y}) or all the way ``in'' (so that they can
+be put into @var{abc} or @var{FGH}). In particular, all
+non-constant powers are converted to logs-and-exponentials form,
+and the distributive law is used to expand products of sums.
+Quotients are rewritten to use the @samp{fitinv} function, where
+@samp{fitinv(x)} represents @expr{1/x} while the @code{FitRules}
+are operating. (The use of @code{fitinv} makes recognition of
+linear-looking forms easier.) If you modify @code{FitRules}, you
+will probably only need to modify the rules for this phase.
+
+Phase two, whose rules can actually also apply during phases one
+and three, first rewrites @code{fitmodel} to a two-argument
+form @samp{fitmodel(@var{Y}, @var{model})}, where @var{Y} is
+initially zero and @var{model} has been changed from @expr{a=b}
+to @expr{a-b} form. It then tries to peel off invertible functions
+from the outside of @var{model} and put them into @var{Y} instead,
+calling the equation solver to invert the functions. Finally, when
+this is no longer possible, the @code{fitmodel} is changed to a
+four-argument @code{fitsystem}, where the fourth argument is
+@var{model} and the @var{FGH} and @var{abc} vectors are initially
+empty. (The last vector is really @var{ABC}, corresponding to
+raw parameters, for now.)
+
+Phase three converts a sum of items in the @var{model} to a sum
+of @samp{fitpart(@var{a}, @var{b}, @var{c})} terms which represent
+terms @samp{@var{a}*@var{b}*@var{c}} of the sum, where @var{a}
+is all factors that do not involve any variables, @var{b} is all
+factors that involve only parameters, and @var{c} is the factors
+that involve only independent variables. (If this decomposition
+is not possible, the rule set will not complete and Calc will
+complain that the model is too complex.) Then @code{fitpart}s
+with equal @var{b} or @var{c} components are merged back together
+using the distributive law in order to minimize the number of
+raw parameters needed.
+
+Phase four moves the @code{fitpart} terms into the @var{FGH} and
+@var{ABC} vectors. Also, some of the algebraic expansions that
+were done in phase 1 are undone now to make the formulas more
+computationally efficient. Finally, it calls the solver one more
+time to convert the @var{ABC} vector to an @var{abc} vector, and
+removes the fourth @var{model} argument (which by now will be zero)
+to obtain the three-argument @code{fitsystem} that the linear
+least-squares solver wants to see.
+
+@ignore
+@starindex
+@end ignore
+@ignore
+@mindex hasfit@idots
+@end ignore
+@tindex hasfitparams
+@ignore
+@starindex
+@end ignore
+@ignore
+@mindex @null
+@end ignore
+@tindex hasfitvars
+Two functions which are useful in connection with @code{FitRules}
+are @samp{hasfitparams(x)} and @samp{hasfitvars(x)}, which check
+whether @expr{x} refers to any parameters or independent variables,
+respectively. Specifically, these functions return ``true'' if the
+argument contains any @code{fitparam} (or @code{fitvar}) function
+calls, and ``false'' otherwise. (Recall that ``true'' means a
+nonzero number, and ``false'' means zero. The actual nonzero number
+returned is the largest @var{n} from all the @samp{fitparam(@var{n})}s
+or @samp{fitvar(@var{n})}s, respectively, that appear in the formula.)
+
+@tex
+\bigskip
+@end tex
+
+The @code{fit} function in algebraic notation normally takes four
+arguments, @samp{fit(@var{model}, @var{vars}, @var{params}, @var{data})},
+where @var{model} is the model formula as it would be typed after
+@kbd{a F '}, @var{vars} is the independent variable or a vector of
+independent variables, @var{params} likewise gives the parameter(s),
+and @var{data} is the data matrix. Note that the length of @var{vars}
+must be equal to the number of rows in @var{data} if @var{model} is
+an equation, or one less than the number of rows if @var{model} is
+a plain formula. (Actually, a name for the dependent variable is
+allowed but will be ignored in the plain-formula case.)
+
+If @var{params} is omitted, the parameters are all variables in
+@var{model} except those that appear in @var{vars}. If @var{vars}
+is also omitted, Calc sorts all the variables that appear in
+@var{model} alphabetically and uses the higher ones for @var{vars}
+and the lower ones for @var{params}.
+
+Alternatively, @samp{fit(@var{modelvec}, @var{data})} is allowed
+where @var{modelvec} is a 2- or 3-vector describing the model
+and variables, as discussed previously.
+
+If Calc is unable to do the fit, the @code{fit} function is left
+in symbolic form, ordinarily with an explanatory message. The
+message will be ``Model expression is too complex'' if the
+linearizer was unable to put the model into the required form.
+
+The @code{efit} (corresponding to @kbd{H a F}) and @code{xfit}
+(for @kbd{I a F}) functions are completely analogous.
+
+@node Interpolation, , Curve Fitting Details, Curve Fitting
+@subsection Polynomial Interpolation
+
+@kindex a p
+@pindex calc-poly-interp
+@tindex polint
+The @kbd{a p} (@code{calc-poly-interp}) [@code{polint}] command does
+a polynomial interpolation at a particular @expr{x} value. It takes
+two arguments from the stack: A data matrix of the sort used by
+@kbd{a F}, and a single number which represents the desired @expr{x}
+value. Calc effectively does an exact polynomial fit as if by @kbd{a F i},
+then substitutes the @expr{x} value into the result in order to get an
+approximate @expr{y} value based on the fit. (Calc does not actually
+use @kbd{a F i}, however; it uses a direct method which is both more
+efficient and more numerically stable.)
+
+The result of @kbd{a p} is actually a vector of two values: The @expr{y}
+value approximation, and an error measure @expr{dy} that reflects Calc's
+estimation of the probable error of the approximation at that value of
+@expr{x}. If the input @expr{x} is equal to any of the @expr{x} values
+in the data matrix, the output @expr{y} will be the corresponding @expr{y}
+value from the matrix, and the output @expr{dy} will be exactly zero.
+
+A prefix argument of 2 causes @kbd{a p} to take separate x- and
+y-vectors from the stack instead of one data matrix.
+
+If @expr{x} is a vector of numbers, @kbd{a p} will return a matrix of
+interpolated results for each of those @expr{x} values. (The matrix will
+have two columns, the @expr{y} values and the @expr{dy} values.)
+If @expr{x} is a formula instead of a number, the @code{polint} function
+remains in symbolic form; use the @kbd{a "} command to expand it out to
+a formula that describes the fit in symbolic terms.
+
+In all cases, the @kbd{a p} command leaves the data vectors or matrix
+on the stack. Only the @expr{x} value is replaced by the result.
+
+@kindex H a p
+@tindex ratint
+The @kbd{H a p} [@code{ratint}] command does a rational function
+interpolation. It is used exactly like @kbd{a p}, except that it
+uses as its model the quotient of two polynomials. If there are
+@expr{N} data points, the numerator and denominator polynomials will
+each have degree @expr{N/2} (if @expr{N} is odd, the denominator will
+have degree one higher than the numerator).
+
+Rational approximations have the advantage that they can accurately
+describe functions that have poles (points at which the function's value
+goes to infinity, so that the denominator polynomial of the approximation
+goes to zero). If @expr{x} corresponds to a pole of the fitted rational
+function, then the result will be a division by zero. If Infinite mode
+is enabled, the result will be @samp{[uinf, uinf]}.
+
+There is no way to get the actual coefficients of the rational function
+used by @kbd{H a p}. (The algorithm never generates these coefficients
+explicitly, and quotients of polynomials are beyond @w{@kbd{a F}}'s
+capabilities to fit.)
+
+@node Summations, Logical Operations, Curve Fitting, Algebra
+@section Summations
+
+@noindent
+@cindex Summation of a series
+@kindex a +
+@pindex calc-summation
+@tindex sum
+The @kbd{a +} (@code{calc-summation}) [@code{sum}] command computes
+the sum of a formula over a certain range of index values. The formula
+is taken from the top of the stack; the command prompts for the
+name of the summation index variable, the lower limit of the
+sum (any formula), and the upper limit of the sum. If you
+enter a blank line at any of these prompts, that prompt and
+any later ones are answered by reading additional elements from
+the stack. Thus, @kbd{' k^2 @key{RET} ' k @key{RET} 1 @key{RET} 5 @key{RET} a + @key{RET}}
+produces the result 55.
+@tex
+\turnoffactive
+$$ \sum_{k=1}^5 k^2 = 55 $$
+@end tex
+
+The choice of index variable is arbitrary, but it's best not to
+use a variable with a stored value. In particular, while
+@code{i} is often a favorite index variable, it should be avoided
+in Calc because @code{i} has the imaginary constant @expr{(0, 1)}
+as a value. If you pressed @kbd{=} on a sum over @code{i}, it would
+be changed to a nonsensical sum over the ``variable'' @expr{(0, 1)}!
+If you really want to use @code{i} as an index variable, use
+@w{@kbd{s u i @key{RET}}} first to ``unstore'' this variable.
+(@xref{Storing Variables}.)
+
+A numeric prefix argument steps the index by that amount rather
+than by one. Thus @kbd{' a_k @key{RET} C-u -2 a + k @key{RET} 10 @key{RET} 0 @key{RET}}
+yields @samp{a_10 + a_8 + a_6 + a_4 + a_2 + a_0}. A prefix
+argument of plain @kbd{C-u} causes @kbd{a +} to prompt for the
+step value, in which case you can enter any formula or enter
+a blank line to take the step value from the stack. With the
+@kbd{C-u} prefix, @kbd{a +} can take up to five arguments from
+the stack: The formula, the variable, the lower limit, the
+upper limit, and (at the top of the stack), the step value.
+
+Calc knows how to do certain sums in closed form. For example,
+@samp{sum(6 k^2, k, 1, n) = @w{2 n^3} + 3 n^2 + n}. In particular,
+this is possible if the formula being summed is polynomial or
+exponential in the index variable. Sums of logarithms are
+transformed into logarithms of products. Sums of trigonometric
+and hyperbolic functions are transformed to sums of exponentials
+and then done in closed form. Also, of course, sums in which the
+lower and upper limits are both numbers can always be evaluated
+just by grinding them out, although Calc will use closed forms
+whenever it can for the sake of efficiency.
+
+The notation for sums in algebraic formulas is
+@samp{sum(@var{expr}, @var{var}, @var{low}, @var{high}, @var{step})}.
+If @var{step} is omitted, it defaults to one. If @var{high} is
+omitted, @var{low} is actually the upper limit and the lower limit
+is one. If @var{low} is also omitted, the limits are @samp{-inf}
+and @samp{inf}, respectively.
+
+Infinite sums can sometimes be evaluated: @samp{sum(.5^k, k, 1, inf)}
+returns @expr{1}. This is done by evaluating the sum in closed
+form (to @samp{1. - 0.5^n} in this case), then evaluating this
+formula with @code{n} set to @code{inf}. Calc's usual rules
+for ``infinite'' arithmetic can find the answer from there. If
+infinite arithmetic yields a @samp{nan}, or if the sum cannot be
+solved in closed form, Calc leaves the @code{sum} function in
+symbolic form. @xref{Infinities}.
+
+As a special feature, if the limits are infinite (or omitted, as
+described above) but the formula includes vectors subscripted by
+expressions that involve the iteration variable, Calc narrows
+the limits to include only the range of integers which result in
+valid subscripts for the vector. For example, the sum
+@samp{sum(k [a,b,c,d,e,f,g]_(2k),k)} evaluates to @samp{b + 2 d + 3 f}.
+
+The limits of a sum do not need to be integers. For example,
+@samp{sum(a_k, k, 0, 2 n, n)} produces @samp{a_0 + a_n + a_(2 n)}.
+Calc computes the number of iterations using the formula
+@samp{1 + (@var{high} - @var{low}) / @var{step}}, which must,
+after simplification as if by @kbd{a s}, evaluate to an integer.
+
+If the number of iterations according to the above formula does
+not come out to an integer, the sum is invalid and will be left
+in symbolic form. However, closed forms are still supplied, and
+you are on your honor not to misuse the resulting formulas by
+substituting mismatched bounds into them. For example,
+@samp{sum(k, k, 1, 10, 2)} is invalid, but Calc will go ahead and
+evaluate the closed form solution for the limits 1 and 10 to get
+the rather dubious answer, 29.25.
+
+If the lower limit is greater than the upper limit (assuming a
+positive step size), the result is generally zero. However,
+Calc only guarantees a zero result when the upper limit is
+exactly one step less than the lower limit, i.e., if the number
+of iterations is @mathit{-1}. Thus @samp{sum(f(k), k, n, n-1)} is zero
+but the sum from @samp{n} to @samp{n-2} may report a nonzero value
+if Calc used a closed form solution.
+
+Calc's logical predicates like @expr{a < b} return 1 for ``true''
+and 0 for ``false.'' @xref{Logical Operations}. This can be
+used to advantage for building conditional sums. For example,
+@samp{sum(prime(k)*k^2, k, 1, 20)} is the sum of the squares of all
+prime numbers from 1 to 20; the @code{prime} predicate returns 1 if
+its argument is prime and 0 otherwise. You can read this expression
+as ``the sum of @expr{k^2}, where @expr{k} is prime.'' Indeed,
+@samp{sum(prime(k)*k^2, k)} would represent the sum of @emph{all} primes
+squared, since the limits default to plus and minus infinity, but
+there are no such sums that Calc's built-in rules can do in
+closed form.
+
+As another example, @samp{sum((k != k_0) * f(k), k, 1, n)} is the
+sum of @expr{f(k)} for all @expr{k} from 1 to @expr{n}, excluding
+one value @expr{k_0}. Slightly more tricky is the summand
+@samp{(k != k_0) / (k - k_0)}, which is an attempt to describe
+the sum of all @expr{1/(k-k_0)} except at @expr{k = k_0}, where
+this would be a division by zero. But at @expr{k = k_0}, this
+formula works out to the indeterminate form @expr{0 / 0}, which
+Calc will not assume is zero. Better would be to use
+@samp{(k != k_0) ? 1/(k-k_0) : 0}; the @samp{? :} operator does
+an ``if-then-else'' test: This expression says, ``if
+@texline @math{k \ne k_0},
+@infoline @expr{k != k_0},
+then @expr{1/(k-k_0)}, else zero.'' Now the formula @expr{1/(k-k_0)}
+will not even be evaluated by Calc when @expr{k = k_0}.
+
+@cindex Alternating sums
+@kindex a -
+@pindex calc-alt-summation
+@tindex asum
+The @kbd{a -} (@code{calc-alt-summation}) [@code{asum}] command
+computes an alternating sum. Successive terms of the sequence
+are given alternating signs, with the first term (corresponding
+to the lower index value) being positive. Alternating sums
+are converted to normal sums with an extra term of the form
+@samp{(-1)^(k-@var{low})}. This formula is adjusted appropriately
+if the step value is other than one. For example, the Taylor
+series for the sine function is @samp{asum(x^k / k!, k, 1, inf, 2)}.
+(Calc cannot evaluate this infinite series, but it can approximate
+it if you replace @code{inf} with any particular odd number.)
+Calc converts this series to a regular sum with a step of one,
+namely @samp{sum((-1)^k x^(2k+1) / (2k+1)!, k, 0, inf)}.
+
+@cindex Product of a sequence
+@kindex a *
+@pindex calc-product
+@tindex prod
+The @kbd{a *} (@code{calc-product}) [@code{prod}] command is
+the analogous way to take a product of many terms. Calc also knows
+some closed forms for products, such as @samp{prod(k, k, 1, n) = n!}.
+Conditional products can be written @samp{prod(k^prime(k), k, 1, n)}
+or @samp{prod(prime(k) ? k : 1, k, 1, n)}.
+
+@kindex a T
+@pindex calc-tabulate
+@tindex table
+The @kbd{a T} (@code{calc-tabulate}) [@code{table}] command
+evaluates a formula at a series of iterated index values, just
+like @code{sum} and @code{prod}, but its result is simply a
+vector of the results. For example, @samp{table(a_i, i, 1, 7, 2)}
+produces @samp{[a_1, a_3, a_5, a_7]}.
+
+@node Logical Operations, Rewrite Rules, Summations, Algebra
+@section Logical Operations
+
+@noindent
+The following commands and algebraic functions return true/false values,
+where 1 represents ``true'' and 0 represents ``false.'' In cases where
+a truth value is required (such as for the condition part of a rewrite
+rule, or as the condition for a @w{@kbd{Z [ Z ]}} control structure), any
+nonzero value is accepted to mean ``true.'' (Specifically, anything
+for which @code{dnonzero} returns 1 is ``true,'' and anything for
+which @code{dnonzero} returns 0 or cannot decide is assumed ``false.''
+Note that this means that @w{@kbd{Z [ Z ]}} will execute the ``then''
+portion if its condition is provably true, but it will execute the
+``else'' portion for any condition like @expr{a = b} that is not
+provably true, even if it might be true. Algebraic functions that
+have conditions as arguments, like @code{? :} and @code{&&}, remain
+unevaluated if the condition is neither provably true nor provably
+false. @xref{Declarations}.)
+
+@kindex a =
+@pindex calc-equal-to
+@tindex eq
+@tindex =
+@tindex ==
+The @kbd{a =} (@code{calc-equal-to}) command, or @samp{eq(a,b)} function
+(which can also be written @samp{a = b} or @samp{a == b} in an algebraic
+formula) is true if @expr{a} and @expr{b} are equal, either because they
+are identical expressions, or because they are numbers which are
+numerically equal. (Thus the integer 1 is considered equal to the float
+1.0.) If the equality of @expr{a} and @expr{b} cannot be determined,
+the comparison is left in symbolic form. Note that as a command, this
+operation pops two values from the stack and pushes back either a 1 or
+a 0, or a formula @samp{a = b} if the values' equality cannot be determined.
+
+Many Calc commands use @samp{=} formulas to represent @dfn{equations}.
+For example, the @kbd{a S} (@code{calc-solve-for}) command rearranges
+an equation to solve for a given variable. The @kbd{a M}
+(@code{calc-map-equation}) command can be used to apply any
+function to both sides of an equation; for example, @kbd{2 a M *}
+multiplies both sides of the equation by two. Note that just
+@kbd{2 *} would not do the same thing; it would produce the formula
+@samp{2 (a = b)} which represents 2 if the equality is true or
+zero if not.
+
+The @code{eq} function with more than two arguments (e.g., @kbd{C-u 3 a =}
+or @samp{a = b = c}) tests if all of its arguments are equal. In
+algebraic notation, the @samp{=} operator is unusual in that it is
+neither left- nor right-associative: @samp{a = b = c} is not the
+same as @samp{(a = b) = c} or @samp{a = (b = c)} (which each compare
+one variable with the 1 or 0 that results from comparing two other
+variables).
+
+@kindex a #
+@pindex calc-not-equal-to
+@tindex neq
+@tindex !=
+The @kbd{a #} (@code{calc-not-equal-to}) command, or @samp{neq(a,b)} or
+@samp{a != b} function, is true if @expr{a} and @expr{b} are not equal.
+This also works with more than two arguments; @samp{a != b != c != d}
+tests that all four of @expr{a}, @expr{b}, @expr{c}, and @expr{d} are
+distinct numbers.
+
+@kindex a <
+@tindex lt
+@ignore
+@mindex @idots
+@end ignore
+@kindex a >
+@ignore
+@mindex @null
+@end ignore
+@kindex a [
+@ignore
+@mindex @null
+@end ignore
+@kindex a ]
+@pindex calc-less-than
+@pindex calc-greater-than
+@pindex calc-less-equal
+@pindex calc-greater-equal
+@ignore
+@mindex @null
+@end ignore
+@tindex gt
+@ignore
+@mindex @null
+@end ignore
+@tindex leq
+@ignore
+@mindex @null
+@end ignore
+@tindex geq
+@ignore
+@mindex @null
+@end ignore
+@tindex <
+@ignore
+@mindex @null
+@end ignore
+@tindex >
+@ignore
+@mindex @null
+@end ignore
+@tindex <=
+@ignore
+@mindex @null
+@end ignore
+@tindex >=
+The @kbd{a <} (@code{calc-less-than}) [@samp{lt(a,b)} or @samp{a < b}]
+operation is true if @expr{a} is less than @expr{b}. Similar functions
+are @kbd{a >} (@code{calc-greater-than}) [@samp{gt(a,b)} or @samp{a > b}],
+@kbd{a [} (@code{calc-less-equal}) [@samp{leq(a,b)} or @samp{a <= b}], and
+@kbd{a ]} (@code{calc-greater-equal}) [@samp{geq(a,b)} or @samp{a >= b}].
+
+While the inequality functions like @code{lt} do not accept more
+than two arguments, the syntax @w{@samp{a <= b < c}} is translated to an
+equivalent expression involving intervals: @samp{b in [a .. c)}.
+(See the description of @code{in} below.) All four combinations
+of @samp{<} and @samp{<=} are allowed, or any of the four combinations
+of @samp{>} and @samp{>=}. Four-argument constructions like
+@samp{a < b < c < d}, and mixtures like @w{@samp{a < b = c}} that
+involve both equalities and inequalities, are not allowed.
+
+@kindex a .
+@pindex calc-remove-equal
+@tindex rmeq
+The @kbd{a .} (@code{calc-remove-equal}) [@code{rmeq}] command extracts
+the righthand side of the equation or inequality on the top of the
+stack. It also works elementwise on vectors. For example, if
+@samp{[x = 2.34, y = z / 2]} is on the stack, then @kbd{a .} produces
+@samp{[2.34, z / 2]}. As a special case, if the righthand side is a
+variable and the lefthand side is a number (as in @samp{2.34 = x}), then
+Calc keeps the lefthand side instead. Finally, this command works with
+assignments @samp{x := 2.34} as well as equations, always taking the
+righthand side, and for @samp{=>} (evaluates-to) operators, always
+taking the lefthand side.
+
+@kindex a &
+@pindex calc-logical-and
+@tindex land
+@tindex &&
+The @kbd{a &} (@code{calc-logical-and}) [@samp{land(a,b)} or @samp{a && b}]
+function is true if both of its arguments are true, i.e., are
+non-zero numbers. In this case, the result will be either @expr{a} or
+@expr{b}, chosen arbitrarily. If either argument is zero, the result is
+zero. Otherwise, the formula is left in symbolic form.
+
+@kindex a |
+@pindex calc-logical-or
+@tindex lor
+@tindex ||
+The @kbd{a |} (@code{calc-logical-or}) [@samp{lor(a,b)} or @samp{a || b}]
+function is true if either or both of its arguments are true (nonzero).
+The result is whichever argument was nonzero, choosing arbitrarily if both
+are nonzero. If both @expr{a} and @expr{b} are zero, the result is
+zero.
+
+@kindex a !
+@pindex calc-logical-not
+@tindex lnot
+@tindex !
+The @kbd{a !} (@code{calc-logical-not}) [@samp{lnot(a)} or @samp{!@: a}]
+function is true if @expr{a} is false (zero), or false if @expr{a} is
+true (nonzero). It is left in symbolic form if @expr{a} is not a
+number.
+
+@kindex a :
+@pindex calc-logical-if
+@tindex if
+@ignore
+@mindex ? :
+@end ignore
+@tindex ?
+@ignore
+@mindex @null
+@end ignore
+@tindex :
+@cindex Arguments, not evaluated
+The @kbd{a :} (@code{calc-logical-if}) [@samp{if(a,b,c)} or @samp{a ? b :@: c}]
+function is equal to either @expr{b} or @expr{c} if @expr{a} is a nonzero
+number or zero, respectively. If @expr{a} is not a number, the test is
+left in symbolic form and neither @expr{b} nor @expr{c} is evaluated in
+any way. In algebraic formulas, this is one of the few Calc functions
+whose arguments are not automatically evaluated when the function itself
+is evaluated. The others are @code{lambda}, @code{quote}, and
+@code{condition}.
+
+One minor surprise to watch out for is that the formula @samp{a?3:4}
+will not work because the @samp{3:4} is parsed as a fraction instead of
+as three separate symbols. Type something like @samp{a ? 3 : 4} or
+@samp{a?(3):4} instead.
+
+As a special case, if @expr{a} evaluates to a vector, then both @expr{b}
+and @expr{c} are evaluated; the result is a vector of the same length
+as @expr{a} whose elements are chosen from corresponding elements of
+@expr{b} and @expr{c} according to whether each element of @expr{a}
+is zero or nonzero. Each of @expr{b} and @expr{c} must be either a
+vector of the same length as @expr{a}, or a non-vector which is matched
+with all elements of @expr{a}.
+
+@kindex a @{
+@pindex calc-in-set
+@tindex in
+The @kbd{a @{} (@code{calc-in-set}) [@samp{in(a,b)}] function is true if
+the number @expr{a} is in the set of numbers represented by @expr{b}.
+If @expr{b} is an interval form, @expr{a} must be one of the values
+encompassed by the interval. If @expr{b} is a vector, @expr{a} must be
+equal to one of the elements of the vector. (If any vector elements are
+intervals, @expr{a} must be in any of the intervals.) If @expr{b} is a
+plain number, @expr{a} must be numerically equal to @expr{b}.
+@xref{Set Operations}, for a group of commands that manipulate sets
+of this sort.
+
+@ignore
+@starindex
+@end ignore
+@tindex typeof
+The @samp{typeof(a)} function produces an integer or variable which
+characterizes @expr{a}. If @expr{a} is a number, vector, or variable,
+the result will be one of the following numbers:
+
+@example
+ 1 Integer
+ 2 Fraction
+ 3 Floating-point number
+ 4 HMS form
+ 5 Rectangular complex number
+ 6 Polar complex number
+ 7 Error form
+ 8 Interval form
+ 9 Modulo form
+10 Date-only form
+11 Date/time form
+12 Infinity (inf, uinf, or nan)
+100 Variable
+101 Vector (but not a matrix)
+102 Matrix
+@end example
+
+Otherwise, @expr{a} is a formula, and the result is a variable which
+represents the name of the top-level function call.
+
+@ignore
+@starindex
+@end ignore
+@tindex integer
+@ignore
+@starindex
+@end ignore
+@tindex real
+@ignore
+@starindex
+@end ignore
+@tindex constant
+The @samp{integer(a)} function returns true if @expr{a} is an integer.
+The @samp{real(a)} function
+is true if @expr{a} is a real number, either integer, fraction, or
+float. The @samp{constant(a)} function returns true if @expr{a} is
+any of the objects for which @code{typeof} would produce an integer
+code result except for variables, and provided that the components of
+an object like a vector or error form are themselves constant.
+Note that infinities do not satisfy any of these tests, nor do
+special constants like @code{pi} and @code{e}.
+
+@xref{Declarations}, for a set of similar functions that recognize
+formulas as well as actual numbers. For example, @samp{dint(floor(x))}
+is true because @samp{floor(x)} is provably integer-valued, but
+@samp{integer(floor(x))} does not because @samp{floor(x)} is not
+literally an integer constant.
+
+@ignore
+@starindex
+@end ignore
+@tindex refers
+The @samp{refers(a,b)} function is true if the variable (or sub-expression)
+@expr{b} appears in @expr{a}, or false otherwise. Unlike the other
+tests described here, this function returns a definite ``no'' answer
+even if its arguments are still in symbolic form. The only case where
+@code{refers} will be left unevaluated is if @expr{a} is a plain
+variable (different from @expr{b}).
+
+@ignore
+@starindex
+@end ignore
+@tindex negative
+The @samp{negative(a)} function returns true if @expr{a} ``looks'' negative,
+because it is a negative number, because it is of the form @expr{-x},
+or because it is a product or quotient with a term that looks negative.
+This is most useful in rewrite rules. Beware that @samp{negative(a)}
+evaluates to 1 or 0 for @emph{any} argument @expr{a}, so it can only
+be stored in a formula if the default simplifications are turned off
+first with @kbd{m O} (or if it appears in an unevaluated context such
+as a rewrite rule condition).
+
+@ignore
+@starindex
+@end ignore
+@tindex variable
+The @samp{variable(a)} function is true if @expr{a} is a variable,
+or false if not. If @expr{a} is a function call, this test is left
+in symbolic form. Built-in variables like @code{pi} and @code{inf}
+are considered variables like any others by this test.
+
+@ignore
+@starindex
+@end ignore
+@tindex nonvar
+The @samp{nonvar(a)} function is true if @expr{a} is a non-variable.
+If its argument is a variable it is left unsimplified; it never
+actually returns zero. However, since Calc's condition-testing
+commands consider ``false'' anything not provably true, this is
+often good enough.
+
+@ignore
+@starindex
+@end ignore
+@tindex lin
+@ignore
+@starindex
+@end ignore
+@tindex linnt
+@ignore
+@starindex
+@end ignore
+@tindex islin
+@ignore
+@starindex
+@end ignore
+@tindex islinnt
+@cindex Linearity testing
+The functions @code{lin}, @code{linnt}, @code{islin}, and @code{islinnt}
+check if an expression is ``linear,'' i.e., can be written in the form
+@expr{a + b x} for some constants @expr{a} and @expr{b}, and some
+variable or subformula @expr{x}. The function @samp{islin(f,x)} checks
+if formula @expr{f} is linear in @expr{x}, returning 1 if so. For
+example, @samp{islin(x,x)}, @samp{islin(-x,x)}, @samp{islin(3,x)}, and
+@samp{islin(x y / 3 - 2, x)} all return 1. The @samp{lin(f,x)} function
+is similar, except that instead of returning 1 it returns the vector
+@expr{[a, b, x]}. For the above examples, this vector would be
+@expr{[0, 1, x]}, @expr{[0, -1, x]}, @expr{[3, 0, x]}, and
+@expr{[-2, y/3, x]}, respectively. Both @code{lin} and @code{islin}
+generally remain unevaluated for expressions which are not linear,
+e.g., @samp{lin(2 x^2, x)} and @samp{lin(sin(x), x)}. The second
+argument can also be a formula; @samp{islin(2 + 3 sin(x), sin(x))}
+returns true.
+
+The @code{linnt} and @code{islinnt} functions perform a similar check,
+but require a ``non-trivial'' linear form, which means that the
+@expr{b} coefficient must be non-zero. For example, @samp{lin(2,x)}
+returns @expr{[2, 0, x]} and @samp{lin(y,x)} returns @expr{[y, 0, x]},
+but @samp{linnt(2,x)} and @samp{linnt(y,x)} are left unevaluated
+(in other words, these formulas are considered to be only ``trivially''
+linear in @expr{x}).
+
+All four linearity-testing functions allow you to omit the second
+argument, in which case the input may be linear in any non-constant
+formula. Here, the @expr{a=0}, @expr{b=1} case is also considered
+trivial, and only constant values for @expr{a} and @expr{b} are
+recognized. Thus, @samp{lin(2 x y)} returns @expr{[0, 2, x y]},
+@samp{lin(2 - x y)} returns @expr{[2, -1, x y]}, and @samp{lin(x y)}
+returns @expr{[0, 1, x y]}. The @code{linnt} function would allow the
+first two cases but not the third. Also, neither @code{lin} nor
+@code{linnt} accept plain constants as linear in the one-argument
+case: @samp{islin(2,x)} is true, but @samp{islin(2)} is false.
+
+@ignore
+@starindex
+@end ignore
+@tindex istrue
+The @samp{istrue(a)} function returns 1 if @expr{a} is a nonzero
+number or provably nonzero formula, or 0 if @expr{a} is anything else.
+Calls to @code{istrue} can only be manipulated if @kbd{m O} mode is
+used to make sure they are not evaluated prematurely. (Note that
+declarations are used when deciding whether a formula is true;
+@code{istrue} returns 1 when @code{dnonzero} would return 1, and
+it returns 0 when @code{dnonzero} would return 0 or leave itself
+in symbolic form.)
+
+@node Rewrite Rules, , Logical Operations, Algebra
+@section Rewrite Rules
+
+@noindent
+@cindex Rewrite rules
+@cindex Transformations
+@cindex Pattern matching
+@kindex a r
+@pindex calc-rewrite
+@tindex rewrite
+The @kbd{a r} (@code{calc-rewrite}) [@code{rewrite}] command makes
+substitutions in a formula according to a specified pattern or patterns
+known as @dfn{rewrite rules}. Whereas @kbd{a b} (@code{calc-substitute})
+matches literally, so that substituting @samp{sin(x)} with @samp{cos(x)}
+matches only the @code{sin} function applied to the variable @code{x},
+rewrite rules match general kinds of formulas; rewriting using the rule
+@samp{sin(x) := cos(x)} matches @code{sin} of any argument and replaces
+it with @code{cos} of that same argument. The only significance of the
+name @code{x} is that the same name is used on both sides of the rule.
+
+Rewrite rules rearrange formulas already in Calc's memory.
+@xref{Syntax Tables}, to read about @dfn{syntax rules}, which are
+similar to algebraic rewrite rules but operate when new algebraic
+entries are being parsed, converting strings of characters into
+Calc formulas.
+
+@menu
+* Entering Rewrite Rules::
+* Basic Rewrite Rules::
+* Conditional Rewrite Rules::
+* Algebraic Properties of Rewrite Rules::
+* Other Features of Rewrite Rules::
+* Composing Patterns in Rewrite Rules::
+* Nested Formulas with Rewrite Rules::
+* Multi-Phase Rewrite Rules::
+* Selections with Rewrite Rules::
+* Matching Commands::
+* Automatic Rewrites::
+* Debugging Rewrites::
+* Examples of Rewrite Rules::
+@end menu
+
+@node Entering Rewrite Rules, Basic Rewrite Rules, Rewrite Rules, Rewrite Rules
+@subsection Entering Rewrite Rules
+
+@noindent
+Rewrite rules normally use the ``assignment'' operator
+@samp{@var{old} := @var{new}}.
+This operator is equivalent to the function call @samp{assign(old, new)}.
+The @code{assign} function is undefined by itself in Calc, so an
+assignment formula such as a rewrite rule will be left alone by ordinary
+Calc commands. But certain commands, like the rewrite system, interpret
+assignments in special ways.
+
+For example, the rule @samp{sin(x)^2 := 1-cos(x)^2} says to replace
+every occurrence of the sine of something, squared, with one minus the
+square of the cosine of that same thing. All by itself as a formula
+on the stack it does nothing, but when given to the @kbd{a r} command
+it turns that command into a sine-squared-to-cosine-squared converter.
+
+To specify a set of rules to be applied all at once, make a vector of
+rules.
+
+When @kbd{a r} prompts you to enter the rewrite rules, you can answer
+in several ways:
+
+@enumerate
+@item
+With a rule: @kbd{f(x) := g(x) @key{RET}}.
+@item
+With a vector of rules: @kbd{[f1(x) := g1(x), f2(x) := g2(x)] @key{RET}}.
+(You can omit the enclosing square brackets if you wish.)
+@item
+With the name of a variable that contains the rule or rules vector:
+@kbd{myrules @key{RET}}.
+@item
+With any formula except a rule, a vector, or a variable name; this
+will be interpreted as the @var{old} half of a rewrite rule,
+and you will be prompted a second time for the @var{new} half:
+@kbd{f(x) @key{RET} g(x) @key{RET}}.
+@item
+With a blank line, in which case the rule, rules vector, or variable
+will be taken from the top of the stack (and the formula to be
+rewritten will come from the second-to-top position).
+@end enumerate
+
+If you enter the rules directly (as opposed to using rules stored
+in a variable), those rules will be put into the Trail so that you
+can retrieve them later. @xref{Trail Commands}.
+
+It is most convenient to store rules you use often in a variable and
+invoke them by giving the variable name. The @kbd{s e}
+(@code{calc-edit-variable}) command is an easy way to create or edit a
+rule set stored in a variable. You may also wish to use @kbd{s p}
+(@code{calc-permanent-variable}) to save your rules permanently;
+@pxref{Operations on Variables}.
+
+Rewrite rules are compiled into a special internal form for faster
+matching. If you enter a rule set directly it must be recompiled
+every time. If you store the rules in a variable and refer to them
+through that variable, they will be compiled once and saved away
+along with the variable for later reference. This is another good
+reason to store your rules in a variable.
+
+Calc also accepts an obsolete notation for rules, as vectors
+@samp{[@var{old}, @var{new}]}. But because it is easily confused with a
+vector of two rules, the use of this notation is no longer recommended.
+
+@node Basic Rewrite Rules, Conditional Rewrite Rules, Entering Rewrite Rules, Rewrite Rules
+@subsection Basic Rewrite Rules
+
+@noindent
+To match a particular formula @expr{x} with a particular rewrite rule
+@samp{@var{old} := @var{new}}, Calc compares the structure of @expr{x} with
+the structure of @var{old}. Variables that appear in @var{old} are
+treated as @dfn{meta-variables}; the corresponding positions in @expr{x}
+may contain any sub-formulas. For example, the pattern @samp{f(x,y)}
+would match the expression @samp{f(12, a+1)} with the meta-variable
+@samp{x} corresponding to 12 and with @samp{y} corresponding to
+@samp{a+1}. However, this pattern would not match @samp{f(12)} or
+@samp{g(12, a+1)}, since there is no assignment of the meta-variables
+that will make the pattern match these expressions. Notice that if
+the pattern is a single meta-variable, it will match any expression.
+
+If a given meta-variable appears more than once in @var{old}, the
+corresponding sub-formulas of @expr{x} must be identical. Thus
+the pattern @samp{f(x,x)} would match @samp{f(12, 12)} and
+@samp{f(a+1, a+1)} but not @samp{f(12, a+1)} or @samp{f(a+b, b+a)}.
+(@xref{Conditional Rewrite Rules}, for a way to match the latter.)
+
+Things other than variables must match exactly between the pattern
+and the target formula. To match a particular variable exactly, use
+the pseudo-function @samp{quote(v)} in the pattern. For example, the
+pattern @samp{x+quote(y)} matches @samp{x+y}, @samp{2+y}, or
+@samp{sin(a)+y}.
+
+The special variable names @samp{e}, @samp{pi}, @samp{i}, @samp{phi},
+@samp{gamma}, @samp{inf}, @samp{uinf}, and @samp{nan} always match
+literally. Thus the pattern @samp{sin(d + e + f)} acts exactly like
+@samp{sin(d + quote(e) + f)}.
+
+If the @var{old} pattern is found to match a given formula, that
+formula is replaced by @var{new}, where any occurrences in @var{new}
+of meta-variables from the pattern are replaced with the sub-formulas
+that they matched. Thus, applying the rule @samp{f(x,y) := g(y+x,x)}
+to @samp{f(12, a+1)} would produce @samp{g(a+13, 12)}.
+
+The normal @kbd{a r} command applies rewrite rules over and over
+throughout the target formula until no further changes are possible
+(up to a limit of 100 times). Use @kbd{C-u 1 a r} to make only one
+change at a time.
+
+@node Conditional Rewrite Rules, Algebraic Properties of Rewrite Rules, Basic Rewrite Rules, Rewrite Rules
+@subsection Conditional Rewrite Rules
+
+@noindent
+A rewrite rule can also be @dfn{conditional}, written in the form
+@samp{@var{old} := @var{new} :: @var{cond}}. (There is also the obsolete
+form @samp{[@var{old}, @var{new}, @var{cond}]}.) If a @var{cond} part
+is present in the
+rule, this is an additional condition that must be satisfied before
+the rule is accepted. Once @var{old} has been successfully matched
+to the target expression, @var{cond} is evaluated (with all the
+meta-variables substituted for the values they matched) and simplified
+with @kbd{a s} (@code{calc-simplify}). If the result is a nonzero
+number or any other object known to be nonzero (@pxref{Declarations}),
+the rule is accepted. If the result is zero or if it is a symbolic
+formula that is not known to be nonzero, the rule is rejected.
+@xref{Logical Operations}, for a number of functions that return
+1 or 0 according to the results of various tests.
+
+For example, the formula @samp{n > 0} simplifies to 1 or 0 if @expr{n}
+is replaced by a positive or nonpositive number, respectively (or if
+@expr{n} has been declared to be positive or nonpositive). Thus,
+the rule @samp{f(x,y) := g(y+x,x) :: x+y > 0} would apply to
+@samp{f(0, 4)} but not to @samp{f(-3, 2)} or @samp{f(12, a+1)}
+(assuming no outstanding declarations for @expr{a}). In the case of
+@samp{f(-3, 2)}, the condition can be shown not to be satisfied; in
+the case of @samp{f(12, a+1)}, the condition merely cannot be shown
+to be satisfied, but that is enough to reject the rule.
+
+While Calc will use declarations to reason about variables in the
+formula being rewritten, declarations do not apply to meta-variables.
+For example, the rule @samp{f(a) := g(a+1)} will match for any values
+of @samp{a}, such as complex numbers, vectors, or formulas, even if
+@samp{a} has been declared to be real or scalar. If you want the
+meta-variable @samp{a} to match only literal real numbers, use
+@samp{f(a) := g(a+1) :: real(a)}. If you want @samp{a} to match only
+reals and formulas which are provably real, use @samp{dreal(a)} as
+the condition.
+
+The @samp{::} operator is a shorthand for the @code{condition}
+function; @samp{@var{old} := @var{new} :: @var{cond}} is equivalent to
+the formula @samp{condition(assign(@var{old}, @var{new}), @var{cond})}.
+
+If you have several conditions, you can use @samp{... :: c1 :: c2 :: c3}
+or @samp{... :: c1 && c2 && c3}. The two are entirely equivalent.
+
+It is also possible to embed conditions inside the pattern:
+@samp{f(x :: x>0, y) := g(y+x, x)}. This is purely a notational
+convenience, though; where a condition appears in a rule has no
+effect on when it is tested. The rewrite-rule compiler automatically
+decides when it is best to test each condition while a rule is being
+matched.
+
+Certain conditions are handled as special cases by the rewrite rule
+system and are tested very efficiently: Where @expr{x} is any
+meta-variable, these conditions are @samp{integer(x)}, @samp{real(x)},
+@samp{constant(x)}, @samp{negative(x)}, @samp{x >= y} where @expr{y}
+is either a constant or another meta-variable and @samp{>=} may be
+replaced by any of the six relational operators, and @samp{x % a = b}
+where @expr{a} and @expr{b} are constants. Other conditions, like
+@samp{x >= y+1} or @samp{dreal(x)}, will be less efficient to check
+since Calc must bring the whole evaluator and simplifier into play.
+
+An interesting property of @samp{::} is that neither of its arguments
+will be touched by Calc's default simplifications. This is important
+because conditions often are expressions that cannot safely be
+evaluated early. For example, the @code{typeof} function never
+remains in symbolic form; entering @samp{typeof(a)} will put the
+number 100 (the type code for variables like @samp{a}) on the stack.
+But putting the condition @samp{... :: typeof(a) = 6} on the stack
+is safe since @samp{::} prevents the @code{typeof} from being
+evaluated until the condition is actually used by the rewrite system.
+
+Since @samp{::} protects its lefthand side, too, you can use a dummy
+condition to protect a rule that must itself not evaluate early.
+For example, it's not safe to put @samp{a(f,x) := apply(f, [x])} on
+the stack because it will immediately evaluate to @samp{a(f,x) := f(x)},
+where the meta-variable-ness of @code{f} on the righthand side has been
+lost. But @samp{a(f,x) := apply(f, [x]) :: 1} is safe, and of course
+the condition @samp{1} is always true (nonzero) so it has no effect on
+the functioning of the rule. (The rewrite compiler will ensure that
+it doesn't even impact the speed of matching the rule.)
+
+@node Algebraic Properties of Rewrite Rules, Other Features of Rewrite Rules, Conditional Rewrite Rules, Rewrite Rules
+@subsection Algebraic Properties of Rewrite Rules
+
+@noindent
+The rewrite mechanism understands the algebraic properties of functions
+like @samp{+} and @samp{*}. In particular, pattern matching takes
+the associativity and commutativity of the following functions into
+account:
+
+@smallexample
++ - * = != && || and or xor vint vunion vxor gcd lcm max min beta
+@end smallexample
+
+For example, the rewrite rule:
+
+@example
+a x + b x := (a + b) x
+@end example
+
+@noindent
+will match formulas of the form,
+
+@example
+a x + b x, x a + x b, a x + x b, x a + b x
+@end example
+
+Rewrites also understand the relationship between the @samp{+} and @samp{-}
+operators. The above rewrite rule will also match the formulas,
+
+@example
+a x - b x, x a - x b, a x - x b, x a - b x
+@end example
+
+@noindent
+by matching @samp{b} in the pattern to @samp{-b} from the formula.
+
+Applied to a sum of many terms like @samp{r + a x + s + b x + t}, this
+pattern will check all pairs of terms for possible matches. The rewrite
+will take whichever suitable pair it discovers first.
+
+In general, a pattern using an associative operator like @samp{a + b}
+will try @var{2 n} different ways to match a sum of @var{n} terms
+like @samp{x + y + z - w}. First, @samp{a} is matched against each
+of @samp{x}, @samp{y}, @samp{z}, and @samp{-w} in turn, with @samp{b}
+being matched to the remainders @samp{y + z - w}, @samp{x + z - w}, etc.
+If none of these succeed, then @samp{b} is matched against each of the
+four terms with @samp{a} matching the remainder. Half-and-half matches,
+like @samp{(x + y) + (z - w)}, are not tried.
+
+Note that @samp{*} is not commutative when applied to matrices, but
+rewrite rules pretend that it is. If you type @kbd{m v} to enable
+Matrix mode (@pxref{Matrix Mode}), rewrite rules will match @samp{*}
+literally, ignoring its usual commutativity property. (In the
+current implementation, the associativity also vanishes---it is as
+if the pattern had been enclosed in a @code{plain} marker; see below.)
+If you are applying rewrites to formulas with matrices, it's best to
+enable Matrix mode first to prevent algebraically incorrect rewrites
+from occurring.
+
+The pattern @samp{-x} will actually match any expression. For example,
+the rule
+
+@example
+f(-x) := -f(x)
+@end example
+
+@noindent
+will rewrite @samp{f(a)} to @samp{-f(-a)}. To avoid this, either use
+a @code{plain} marker as described below, or add a @samp{negative(x)}
+condition. The @code{negative} function is true if its argument
+``looks'' negative, for example, because it is a negative number or
+because it is a formula like @samp{-x}. The new rule using this
+condition is:
+
+@example
+f(x) := -f(-x) :: negative(x) @r{or, equivalently,}
+f(-x) := -f(x) :: negative(-x)
+@end example
+
+In the same way, the pattern @samp{x - y} will match the sum @samp{a + b}
+by matching @samp{y} to @samp{-b}.
+
+The pattern @samp{a b} will also match the formula @samp{x/y} if
+@samp{y} is a number. Thus the rule @samp{a x + @w{b x} := (a+b) x}
+will also convert @samp{a x + x / 2} to @samp{(a + 0.5) x} (or
+@samp{(a + 1:2) x}, depending on the current fraction mode).
+
+Calc will @emph{not} take other liberties with @samp{*}, @samp{/}, and
+@samp{^}. For example, the pattern @samp{f(a b)} will not match
+@samp{f(x^2)}, and @samp{f(a + b)} will not match @samp{f(2 x)}, even
+though conceivably these patterns could match with @samp{a = b = x}.
+Nor will @samp{f(a b)} match @samp{f(x / y)} if @samp{y} is not a
+constant, even though it could be considered to match with @samp{a = x}
+and @samp{b = 1/y}. The reasons are partly for efficiency, and partly
+because while few mathematical operations are substantively different
+for addition and subtraction, often it is preferable to treat the cases
+of multiplication, division, and integer powers separately.
+
+Even more subtle is the rule set
+
+@example
+[ f(a) + f(b) := f(a + b), -f(a) := f(-a) ]
+@end example
+
+@noindent
+attempting to match @samp{f(x) - f(y)}. You might think that Calc
+will view this subtraction as @samp{f(x) + (-f(y))} and then apply
+the above two rules in turn, but actually this will not work because
+Calc only does this when considering rules for @samp{+} (like the
+first rule in this set). So it will see first that @samp{f(x) + (-f(y))}
+does not match @samp{f(a) + f(b)} for any assignments of the
+meta-variables, and then it will see that @samp{f(x) - f(y)} does
+not match @samp{-f(a)} for any assignment of @samp{a}. Because Calc
+tries only one rule at a time, it will not be able to rewrite
+@samp{f(x) - f(y)} with this rule set. An explicit @samp{f(a) - f(b)}
+rule will have to be added.
+
+Another thing patterns will @emph{not} do is break up complex numbers.
+The pattern @samp{myconj(a + @w{b i)} := a - b i} will work for formulas
+involving the special constant @samp{i} (such as @samp{3 - 4 i}), but
+it will not match actual complex numbers like @samp{(3, -4)}. A version
+of the above rule for complex numbers would be
+
+@example
+myconj(a) := re(a) - im(a) (0,1) :: im(a) != 0
+@end example
+
+@noindent
+(Because the @code{re} and @code{im} functions understand the properties
+of the special constant @samp{i}, this rule will also work for
+@samp{3 - 4 i}. In fact, this particular rule would probably be better
+without the @samp{im(a) != 0} condition, since if @samp{im(a) = 0} the
+righthand side of the rule will still give the correct answer for the
+conjugate of a real number.)
+
+It is also possible to specify optional arguments in patterns. The rule
+
+@example
+opt(a) x + opt(b) (x^opt(c) + opt(d)) := f(a, b, c, d)
+@end example
+
+@noindent
+will match the formula
+
+@example
+5 (x^2 - 4) + 3 x
+@end example
+
+@noindent
+in a fairly straightforward manner, but it will also match reduced
+formulas like
+
+@example
+x + x^2, 2(x + 1) - x, x + x
+@end example
+
+@noindent
+producing, respectively,
+
+@example
+f(1, 1, 2, 0), f(-1, 2, 1, 1), f(1, 1, 1, 0)
+@end example
+
+(The latter two formulas can be entered only if default simplifications
+have been turned off with @kbd{m O}.)
+
+The default value for a term of a sum is zero. The default value
+for a part of a product, for a power, or for the denominator of a
+quotient, is one. Also, @samp{-x} matches the pattern @samp{opt(a) b}
+with @samp{a = -1}.
+
+In particular, the distributive-law rule can be refined to
+
+@example
+opt(a) x + opt(b) x := (a + b) x
+@end example
+
+@noindent
+so that it will convert, e.g., @samp{a x - x}, to @samp{(a - 1) x}.
+
+The pattern @samp{opt(a) + opt(b) x} matches almost any formulas which
+are linear in @samp{x}. You can also use the @code{lin} and @code{islin}
+functions with rewrite conditions to test for this; @pxref{Logical
+Operations}. These functions are not as convenient to use in rewrite
+rules, but they recognize more kinds of formulas as linear:
+@samp{x/z} is considered linear with @expr{b = 1/z} by @code{lin},
+but it will not match the above pattern because that pattern calls
+for a multiplication, not a division.
+
+As another example, the obvious rule to replace @samp{sin(x)^2 + cos(x)^2}
+by 1,
+
+@example
+sin(x)^2 + cos(x)^2 := 1
+@end example
+
+@noindent
+misses many cases because the sine and cosine may both be multiplied by
+an equal factor. Here's a more successful rule:
+
+@example
+opt(a) sin(x)^2 + opt(a) cos(x)^2 := a
+@end example
+
+Note that this rule will @emph{not} match @samp{sin(x)^2 + 6 cos(x)^2}
+because one @expr{a} would have ``matched'' 1 while the other matched 6.
+
+Calc automatically converts a rule like
+
+@example
+f(x-1, x) := g(x)
+@end example
+
+@noindent
+into the form
+
+@example
+f(temp, x) := g(x) :: temp = x-1
+@end example
+
+@noindent
+(where @code{temp} stands for a new, invented meta-variable that
+doesn't actually have a name). This modified rule will successfully
+match @samp{f(6, 7)}, binding @samp{temp} and @samp{x} to 6 and 7,
+respectively, then verifying that they differ by one even though
+@samp{6} does not superficially look like @samp{x-1}.
+
+However, Calc does not solve equations to interpret a rule. The
+following rule,
+
+@example
+f(x-1, x+1) := g(x)
+@end example
+
+@noindent
+will not work. That is, it will match @samp{f(a - 1 + b, a + 1 + b)}
+but not @samp{f(6, 8)}. Calc always interprets at least one occurrence
+of a variable by literal matching. If the variable appears ``isolated''
+then Calc is smart enough to use it for literal matching. But in this
+last example, Calc is forced to rewrite the rule to @samp{f(x-1, temp)
+:= g(x) :: temp = x+1} where the @samp{x-1} term must correspond to an
+actual ``something-minus-one'' in the target formula.
+
+A successful way to write this would be @samp{f(x, x+2) := g(x+1)}.
+You could make this resemble the original form more closely by using
+@code{let} notation, which is described in the next section:
+
+@example
+f(xm1, x+1) := g(x) :: let(x := xm1+1)
+@end example
+
+Calc does this rewriting or ``conditionalizing'' for any sub-pattern
+which involves only the functions in the following list, operating
+only on constants and meta-variables which have already been matched
+elsewhere in the pattern. When matching a function call, Calc is
+careful to match arguments which are plain variables before arguments
+which are calls to any of the functions below, so that a pattern like
+@samp{f(x-1, x)} can be conditionalized even though the isolated
+@samp{x} comes after the @samp{x-1}.
+
+@smallexample
++ - * / \ % ^ abs sign round rounde roundu trunc floor ceil
+max min re im conj arg
+@end smallexample
+
+You can suppress all of the special treatments described in this
+section by surrounding a function call with a @code{plain} marker.
+This marker causes the function call which is its argument to be
+matched literally, without regard to commutativity, associativity,
+negation, or conditionalization. When you use @code{plain}, the
+``deep structure'' of the formula being matched can show through.
+For example,
+
+@example
+plain(a - a b) := f(a, b)
+@end example
+
+@noindent
+will match only literal subtractions. However, the @code{plain}
+marker does not affect its arguments' arguments. In this case,
+commutativity and associativity is still considered while matching
+the @w{@samp{a b}} sub-pattern, so the whole pattern will match
+@samp{x - y x} as well as @samp{x - x y}. We could go still
+further and use
+
+@example
+plain(a - plain(a b)) := f(a, b)
+@end example
+
+@noindent
+which would do a completely strict match for the pattern.
+
+By contrast, the @code{quote} marker means that not only the
+function name but also the arguments must be literally the same.
+The above pattern will match @samp{x - x y} but
+
+@example
+quote(a - a b) := f(a, b)
+@end example
+
+@noindent
+will match only the single formula @samp{a - a b}. Also,
+
+@example
+quote(a - quote(a b)) := f(a, b)
+@end example
+
+@noindent
+will match only @samp{a - quote(a b)}---probably not the desired
+effect!
+
+A certain amount of algebra is also done when substituting the
+meta-variables on the righthand side of a rule. For example,
+in the rule
+
+@example
+a + f(b) := f(a + b)
+@end example
+
+@noindent
+matching @samp{f(x) - y} would produce @samp{f((-y) + x)} if
+taken literally, but the rewrite mechanism will simplify the
+righthand side to @samp{f(x - y)} automatically. (Of course,
+the default simplifications would do this anyway, so this
+special simplification is only noticeable if you have turned the
+default simplifications off.) This rewriting is done only when
+a meta-variable expands to a ``negative-looking'' expression.
+If this simplification is not desirable, you can use a @code{plain}
+marker on the righthand side:
+
+@example
+a + f(b) := f(plain(a + b))
+@end example
+
+@noindent
+In this example, we are still allowing the pattern-matcher to
+use all the algebra it can muster, but the righthand side will
+always simplify to a literal addition like @samp{f((-y) + x)}.
+
+@node Other Features of Rewrite Rules, Composing Patterns in Rewrite Rules, Algebraic Properties of Rewrite Rules, Rewrite Rules
+@subsection Other Features of Rewrite Rules
+
+@noindent
+Certain ``function names'' serve as markers in rewrite rules.
+Here is a complete list of these markers. First are listed the
+markers that work inside a pattern; then come the markers that
+work in the righthand side of a rule.
+
+@ignore
+@starindex
+@end ignore
+@tindex import
+One kind of marker, @samp{import(x)}, takes the place of a whole
+rule. Here @expr{x} is the name of a variable containing another
+rule set; those rules are ``spliced into'' the rule set that
+imports them. For example, if @samp{[f(a+b) := f(a) + f(b),
+f(a b) := a f(b) :: real(a)]} is stored in variable @samp{linearF},
+then the rule set @samp{[f(0) := 0, import(linearF)]} will apply
+all three rules. It is possible to modify the imported rules
+slightly: @samp{import(x, v1, x1, v2, x2, @dots{})} imports
+the rule set @expr{x} with all occurrences of
+@texline @math{v_1},
+@infoline @expr{v1},
+as either a variable name or a function name, replaced with
+@texline @math{x_1}
+@infoline @expr{x1}
+and so on. (If
+@texline @math{v_1}
+@infoline @expr{v1}
+is used as a function name, then
+@texline @math{x_1}
+@infoline @expr{x1}
+must be either a function name itself or a @w{@samp{< >}} nameless
+function; @pxref{Specifying Operators}.) For example, @samp{[g(0) := 0,
+import(linearF, f, g)]} applies the linearity rules to the function
+@samp{g} instead of @samp{f}. Imports can be nested, but the
+import-with-renaming feature may fail to rename sub-imports properly.
+
+The special functions allowed in patterns are:
+
+@table @samp
+@item quote(x)
+@ignore
+@starindex
+@end ignore
+@tindex quote
+This pattern matches exactly @expr{x}; variable names in @expr{x} are
+not interpreted as meta-variables. The only flexibility is that
+numbers are compared for numeric equality, so that the pattern
+@samp{f(quote(12))} will match both @samp{f(12)} and @samp{f(12.0)}.
+(Numbers are always treated this way by the rewrite mechanism:
+The rule @samp{f(x,x) := g(x)} will match @samp{f(12, 12.0)}.
+The rewrite may produce either @samp{g(12)} or @samp{g(12.0)}
+as a result in this case.)
+
+@item plain(x)
+@ignore
+@starindex
+@end ignore
+@tindex plain
+Here @expr{x} must be a function call @samp{f(x1,x2,@dots{})}. This
+pattern matches a call to function @expr{f} with the specified
+argument patterns. No special knowledge of the properties of the
+function @expr{f} is used in this case; @samp{+} is not commutative or
+associative. Unlike @code{quote}, the arguments @samp{x1,x2,@dots{}}
+are treated as patterns. If you wish them to be treated ``plainly''
+as well, you must enclose them with more @code{plain} markers:
+@samp{plain(plain(@w{-a}) + plain(b c))}.
+
+@item opt(x,def)
+@ignore
+@starindex
+@end ignore
+@tindex opt
+Here @expr{x} must be a variable name. This must appear as an
+argument to a function or an element of a vector; it specifies that
+the argument or element is optional.
+As an argument to @samp{+}, @samp{-}, @samp{*}, @samp{&&}, or @samp{||},
+or as the second argument to @samp{/} or @samp{^}, the value @var{def}
+may be omitted. The pattern @samp{x + opt(y)} matches a sum by
+binding one summand to @expr{x} and the other to @expr{y}, and it
+matches anything else by binding the whole expression to @expr{x} and
+zero to @expr{y}. The other operators above work similarly.
+
+For general miscellaneous functions, the default value @code{def}
+must be specified. Optional arguments are dropped starting with
+the rightmost one during matching. For example, the pattern
+@samp{f(opt(a,0), b, opt(c,b))} will match @samp{f(b)}, @samp{f(a,b)},
+or @samp{f(a,b,c)}. Default values of zero and @expr{b} are
+supplied in this example for the omitted arguments. Note that
+the literal variable @expr{b} will be the default in the latter
+case, @emph{not} the value that matched the meta-variable @expr{b}.
+In other words, the default @var{def} is effectively quoted.
+
+@item condition(x,c)
+@ignore
+@starindex
+@end ignore
+@tindex condition
+@tindex ::
+This matches the pattern @expr{x}, with the attached condition
+@expr{c}. It is the same as @samp{x :: c}.
+
+@item pand(x,y)
+@ignore
+@starindex
+@end ignore
+@tindex pand
+@tindex &&&
+This matches anything that matches both pattern @expr{x} and
+pattern @expr{y}. It is the same as @samp{x &&& y}.
+@pxref{Composing Patterns in Rewrite Rules}.
+
+@item por(x,y)
+@ignore
+@starindex
+@end ignore
+@tindex por
+@tindex |||
+This matches anything that matches either pattern @expr{x} or
+pattern @expr{y}. It is the same as @w{@samp{x ||| y}}.
+
+@item pnot(x)
+@ignore
+@starindex
+@end ignore
+@tindex pnot
+@tindex !!!
+This matches anything that does not match pattern @expr{x}.
+It is the same as @samp{!!! x}.
+
+@item cons(h,t)
+@ignore
+@mindex cons
+@end ignore
+@tindex cons (rewrites)
+This matches any vector of one or more elements. The first
+element is matched to @expr{h}; a vector of the remaining
+elements is matched to @expr{t}. Note that vectors of fixed
+length can also be matched as actual vectors: The rule
+@samp{cons(a,cons(b,[])) := cons(a+b,[])} is equivalent
+to the rule @samp{[a,b] := [a+b]}.
+
+@item rcons(t,h)
+@ignore
+@mindex rcons
+@end ignore
+@tindex rcons (rewrites)
+This is like @code{cons}, except that the @emph{last} element
+is matched to @expr{h}, with the remaining elements matched
+to @expr{t}.
+
+@item apply(f,args)
+@ignore
+@mindex apply
+@end ignore
+@tindex apply (rewrites)
+This matches any function call. The name of the function, in
+the form of a variable, is matched to @expr{f}. The arguments
+of the function, as a vector of zero or more objects, are
+matched to @samp{args}. Constants, variables, and vectors
+do @emph{not} match an @code{apply} pattern. For example,
+@samp{apply(f,x)} matches any function call, @samp{apply(quote(f),x)}
+matches any call to the function @samp{f}, @samp{apply(f,[a,b])}
+matches any function call with exactly two arguments, and
+@samp{apply(quote(f), cons(a,cons(b,x)))} matches any call
+to the function @samp{f} with two or more arguments. Another
+way to implement the latter, if the rest of the rule does not
+need to refer to the first two arguments of @samp{f} by name,
+would be @samp{apply(quote(f), x :: vlen(x) >= 2)}.
+Here's a more interesting sample use of @code{apply}:
+
+@example
+apply(f,[x+n]) := n + apply(f,[x])
+ :: in(f, [floor,ceil,round,trunc]) :: integer(n)
+@end example
+
+Note, however, that this will be slower to match than a rule
+set with four separate rules. The reason is that Calc sorts
+the rules of a rule set according to top-level function name;
+if the top-level function is @code{apply}, Calc must try the
+rule for every single formula and sub-formula. If the top-level
+function in the pattern is, say, @code{floor}, then Calc invokes
+the rule only for sub-formulas which are calls to @code{floor}.
+
+Formulas normally written with operators like @code{+} are still
+considered function calls: @code{apply(f,x)} matches @samp{a+b}
+with @samp{f = add}, @samp{x = [a,b]}.
+
+You must use @code{apply} for meta-variables with function names
+on both sides of a rewrite rule: @samp{apply(f, [x]) := f(x+1)}
+is @emph{not} correct, because it rewrites @samp{spam(6)} into
+@samp{f(7)}. The righthand side should be @samp{apply(f, [x+1])}.
+Also note that you will have to use No-Simplify mode (@kbd{m O})
+when entering this rule so that the @code{apply} isn't
+evaluated immediately to get the new rule @samp{f(x) := f(x+1)}.
+Or, use @kbd{s e} to enter the rule without going through the stack,
+or enter the rule as @samp{apply(f, [x]) := apply(f, [x+1]) @w{:: 1}}.
+@xref{Conditional Rewrite Rules}.
+
+@item select(x)
+@ignore
+@starindex
+@end ignore
+@tindex select
+This is used for applying rules to formulas with selections;
+@pxref{Selections with Rewrite Rules}.
+@end table
+
+Special functions for the righthand sides of rules are:
+
+@table @samp
+@item quote(x)
+The notation @samp{quote(x)} is changed to @samp{x} when the
+righthand side is used. As far as the rewrite rule is concerned,
+@code{quote} is invisible. However, @code{quote} has the special
+property in Calc that its argument is not evaluated. Thus,
+while it will not work to put the rule @samp{t(a) := typeof(a)}
+on the stack because @samp{typeof(a)} is evaluated immediately
+to produce @samp{t(a) := 100}, you can use @code{quote} to
+protect the righthand side: @samp{t(a) := quote(typeof(a))}.
+(@xref{Conditional Rewrite Rules}, for another trick for
+protecting rules from evaluation.)
+
+@item plain(x)
+Special properties of and simplifications for the function call
+@expr{x} are not used. One interesting case where @code{plain}
+is useful is the rule, @samp{q(x) := quote(x)}, trying to expand a
+shorthand notation for the @code{quote} function. This rule will
+not work as shown; instead of replacing @samp{q(foo)} with
+@samp{quote(foo)}, it will replace it with @samp{foo}! The correct
+rule would be @samp{q(x) := plain(quote(x))}.
+
+@item cons(h,t)
+Where @expr{t} is a vector, this is converted into an expanded
+vector during rewrite processing. Note that @code{cons} is a regular
+Calc function which normally does this anyway; the only way @code{cons}
+is treated specially by rewrites is that @code{cons} on the righthand
+side of a rule will be evaluated even if default simplifications
+have been turned off.
+
+@item rcons(t,h)
+Analogous to @code{cons} except putting @expr{h} at the @emph{end} of
+the vector @expr{t}.
+
+@item apply(f,args)
+Where @expr{f} is a variable and @var{args} is a vector, this
+is converted to a function call. Once again, note that @code{apply}
+is also a regular Calc function.
+
+@item eval(x)
+@ignore
+@starindex
+@end ignore
+@tindex eval
+The formula @expr{x} is handled in the usual way, then the
+default simplifications are applied to it even if they have
+been turned off normally. This allows you to treat any function
+similarly to the way @code{cons} and @code{apply} are always
+treated. However, there is a slight difference: @samp{cons(2+3, [])}
+with default simplifications off will be converted to @samp{[2+3]},
+whereas @samp{eval(cons(2+3, []))} will be converted to @samp{[5]}.
+
+@item evalsimp(x)
+@ignore
+@starindex
+@end ignore
+@tindex evalsimp
+The formula @expr{x} has meta-variables substituted in the usual
+way, then algebraically simplified as if by the @kbd{a s} command.
+
+@item evalextsimp(x)
+@ignore
+@starindex
+@end ignore
+@tindex evalextsimp
+The formula @expr{x} has meta-variables substituted in the normal
+way, then ``extendedly'' simplified as if by the @kbd{a e} command.
+
+@item select(x)
+@xref{Selections with Rewrite Rules}.
+@end table
+
+There are also some special functions you can use in conditions.
+
+@table @samp
+@item let(v := x)
+@ignore
+@starindex
+@end ignore
+@tindex let
+The expression @expr{x} is evaluated with meta-variables substituted.
+The @kbd{a s} command's simplifications are @emph{not} applied by
+default, but @expr{x} can include calls to @code{evalsimp} or
+@code{evalextsimp} as described above to invoke higher levels
+of simplification. The
+result of @expr{x} is then bound to the meta-variable @expr{v}. As
+usual, if this meta-variable has already been matched to something
+else the two values must be equal; if the meta-variable is new then
+it is bound to the result of the expression. This variable can then
+appear in later conditions, and on the righthand side of the rule.
+In fact, @expr{v} may be any pattern in which case the result of
+evaluating @expr{x} is matched to that pattern, binding any
+meta-variables that appear in that pattern. Note that @code{let}
+can only appear by itself as a condition, or as one term of an
+@samp{&&} which is a whole condition: It cannot be inside
+an @samp{||} term or otherwise buried.
+
+The alternate, equivalent form @samp{let(v, x)} is also recognized.
+Note that the use of @samp{:=} by @code{let}, while still being
+assignment-like in character, is unrelated to the use of @samp{:=}
+in the main part of a rewrite rule.
+
+As an example, @samp{f(a) := g(ia) :: let(ia := 1/a) :: constant(ia)}
+replaces @samp{f(a)} with @samp{g} of the inverse of @samp{a}, if
+that inverse exists and is constant. For example, if @samp{a} is a
+singular matrix the operation @samp{1/a} is left unsimplified and
+@samp{constant(ia)} fails, but if @samp{a} is an invertible matrix
+then the rule succeeds. Without @code{let} there would be no way
+to express this rule that didn't have to invert the matrix twice.
+Note that, because the meta-variable @samp{ia} is otherwise unbound
+in this rule, the @code{let} condition itself always ``succeeds''
+because no matter what @samp{1/a} evaluates to, it can successfully
+be bound to @code{ia}.
+
+Here's another example, for integrating cosines of linear
+terms: @samp{myint(cos(y),x) := sin(y)/b :: let([a,b,x] := lin(y,x))}.
+The @code{lin} function returns a 3-vector if its argument is linear,
+or leaves itself unevaluated if not. But an unevaluated @code{lin}
+call will not match the 3-vector on the lefthand side of the @code{let},
+so this @code{let} both verifies that @code{y} is linear, and binds
+the coefficients @code{a} and @code{b} for use elsewhere in the rule.
+(It would have been possible to use @samp{sin(a x + b)/b} for the
+righthand side instead, but using @samp{sin(y)/b} avoids gratuitous
+rearrangement of the argument of the sine.)
+
+@ignore
+@starindex
+@end ignore
+@tindex ierf
+Similarly, here is a rule that implements an inverse-@code{erf}
+function. It uses @code{root} to search for a solution. If
+@code{root} succeeds, it will return a vector of two numbers
+where the first number is the desired solution. If no solution
+is found, @code{root} remains in symbolic form. So we use
+@code{let} to check that the result was indeed a vector.
+
+@example
+ierf(x) := y :: let([y,z] := root(erf(a) = x, a, .5))
+@end example
+
+@item matches(v,p)
+The meta-variable @var{v}, which must already have been matched
+to something elsewhere in the rule, is compared against pattern
+@var{p}. Since @code{matches} is a standard Calc function, it
+can appear anywhere in a condition. But if it appears alone or
+as a term of a top-level @samp{&&}, then you get the special
+extra feature that meta-variables which are bound to things
+inside @var{p} can be used elsewhere in the surrounding rewrite
+rule.
+
+The only real difference between @samp{let(p := v)} and
+@samp{matches(v, p)} is that the former evaluates @samp{v} using
+the default simplifications, while the latter does not.
+
+@item remember
+@vindex remember
+This is actually a variable, not a function. If @code{remember}
+appears as a condition in a rule, then when that rule succeeds
+the original expression and rewritten expression are added to the
+front of the rule set that contained the rule. If the rule set
+was not stored in a variable, @code{remember} is ignored. The
+lefthand side is enclosed in @code{quote} in the added rule if it
+contains any variables.
+
+For example, the rule @samp{f(n) := n f(n-1) :: remember} applied
+to @samp{f(7)} will add the rule @samp{f(7) := 7 f(6)} to the front
+of the rule set. The rule set @code{EvalRules} works slightly
+differently: There, the evaluation of @samp{f(6)} will complete before
+the result is added to the rule set, in this case as @samp{f(7) := 5040}.
+Thus @code{remember} is most useful inside @code{EvalRules}.
+
+It is up to you to ensure that the optimization performed by
+@code{remember} is safe. For example, the rule @samp{foo(n) := n
+:: evalv(eatfoo) > 0 :: remember} is a bad idea (@code{evalv} is
+the function equivalent of the @kbd{=} command); if the variable
+@code{eatfoo} ever contains 1, rules like @samp{foo(7) := 7} will
+be added to the rule set and will continue to operate even if
+@code{eatfoo} is later changed to 0.
+
+@item remember(c)
+@ignore
+@starindex
+@end ignore
+@tindex remember
+Remember the match as described above, but only if condition @expr{c}
+is true. For example, @samp{remember(n % 4 = 0)} in the above factorial
+rule remembers only every fourth result. Note that @samp{remember(1)}
+is equivalent to @samp{remember}, and @samp{remember(0)} has no effect.
+@end table
+
+@node Composing Patterns in Rewrite Rules, Nested Formulas with Rewrite Rules, Other Features of Rewrite Rules, Rewrite Rules
+@subsection Composing Patterns in Rewrite Rules
+
+@noindent
+There are three operators, @samp{&&&}, @samp{|||}, and @samp{!!!},
+that combine rewrite patterns to make larger patterns. The
+combinations are ``and,'' ``or,'' and ``not,'' respectively, and
+these operators are the pattern equivalents of @samp{&&}, @samp{||}
+and @samp{!} (which operate on zero-or-nonzero logical values).
+
+Note that @samp{&&&}, @samp{|||}, and @samp{!!!} are left in symbolic
+form by all regular Calc features; they have special meaning only in
+the context of rewrite rule patterns.
+
+The pattern @samp{@var{p1} &&& @var{p2}} matches anything that
+matches both @var{p1} and @var{p2}. One especially useful case is
+when one of @var{p1} or @var{p2} is a meta-variable. For example,
+here is a rule that operates on error forms:
+
+@example
+f(x &&& a +/- b, x) := g(x)
+@end example
+
+This does the same thing, but is arguably simpler than, the rule
+
+@example
+f(a +/- b, a +/- b) := g(a +/- b)
+@end example
+
+@ignore
+@starindex
+@end ignore
+@tindex ends
+Here's another interesting example:
+
+@example
+ends(cons(a, x) &&& rcons(y, b)) := [a, b]
+@end example
+
+@noindent
+which effectively clips out the middle of a vector leaving just
+the first and last elements. This rule will change a one-element
+vector @samp{[a]} to @samp{[a, a]}. The similar rule
+
+@example
+ends(cons(a, rcons(y, b))) := [a, b]
+@end example
+
+@noindent
+would do the same thing except that it would fail to match a
+one-element vector.
+
+@tex
+\bigskip
+@end tex
+
+The pattern @samp{@var{p1} ||| @var{p2}} matches anything that
+matches either @var{p1} or @var{p2}. Calc first tries matching
+against @var{p1}; if that fails, it goes on to try @var{p2}.
+
+@ignore
+@starindex
+@end ignore
+@tindex curve
+A simple example of @samp{|||} is
+
+@example
+curve(inf ||| -inf) := 0
+@end example
+
+@noindent
+which converts both @samp{curve(inf)} and @samp{curve(-inf)} to zero.
+
+Here is a larger example:
+
+@example
+log(a, b) ||| (ln(a) :: let(b := e)) := mylog(a, b)
+@end example
+
+This matches both generalized and natural logarithms in a single rule.
+Note that the @samp{::} term must be enclosed in parentheses because
+that operator has lower precedence than @samp{|||} or @samp{:=}.
+
+(In practice this rule would probably include a third alternative,
+omitted here for brevity, to take care of @code{log10}.)
+
+While Calc generally treats interior conditions exactly the same as
+conditions on the outside of a rule, it does guarantee that if all the
+variables in the condition are special names like @code{e}, or already
+bound in the pattern to which the condition is attached (say, if
+@samp{a} had appeared in this condition), then Calc will process this
+condition right after matching the pattern to the left of the @samp{::}.
+Thus, we know that @samp{b} will be bound to @samp{e} only if the
+@code{ln} branch of the @samp{|||} was taken.
+
+Note that this rule was careful to bind the same set of meta-variables
+on both sides of the @samp{|||}. Calc does not check this, but if
+you bind a certain meta-variable only in one branch and then use that
+meta-variable elsewhere in the rule, results are unpredictable:
+
+@example
+f(a,b) ||| g(b) := h(a,b)
+@end example
+
+Here if the pattern matches @samp{g(17)}, Calc makes no promises about
+the value that will be substituted for @samp{a} on the righthand side.
+
+@tex
+\bigskip
+@end tex
+
+The pattern @samp{!!! @var{pat}} matches anything that does not
+match @var{pat}. Any meta-variables that are bound while matching
+@var{pat} remain unbound outside of @var{pat}.
+
+For example,
+
+@example
+f(x &&& !!! a +/- b, !!![]) := g(x)
+@end example
+
+@noindent
+converts @code{f} whose first argument is anything @emph{except} an
+error form, and whose second argument is not the empty vector, into
+a similar call to @code{g} (but without the second argument).
+
+If we know that the second argument will be a vector (empty or not),
+then an equivalent rule would be:
+
+@example
+f(x, y) := g(x) :: typeof(x) != 7 :: vlen(y) > 0
+@end example
+
+@noindent
+where of course 7 is the @code{typeof} code for error forms.
+Another final condition, that works for any kind of @samp{y},
+would be @samp{!istrue(y == [])}. (The @code{istrue} function
+returns an explicit 0 if its argument was left in symbolic form;
+plain @samp{!(y == [])} or @samp{y != []} would not work to replace
+@samp{!!![]} since these would be left unsimplified, and thus cause
+the rule to fail, if @samp{y} was something like a variable name.)
+
+It is possible for a @samp{!!!} to refer to meta-variables bound
+elsewhere in the pattern. For example,
+
+@example
+f(a, !!!a) := g(a)
+@end example
+
+@noindent
+matches any call to @code{f} with different arguments, changing
+this to @code{g} with only the first argument.
+
+If a function call is to be matched and one of the argument patterns
+contains a @samp{!!!} somewhere inside it, that argument will be
+matched last. Thus
+
+@example
+f(!!!a, a) := g(a)
+@end example
+
+@noindent
+will be careful to bind @samp{a} to the second argument of @code{f}
+before testing the first argument. If Calc had tried to match the
+first argument of @code{f} first, the results would have been
+disastrous: since @code{a} was unbound so far, the pattern @samp{a}
+would have matched anything at all, and the pattern @samp{!!!a}
+therefore would @emph{not} have matched anything at all!
+
+@node Nested Formulas with Rewrite Rules, Multi-Phase Rewrite Rules, Composing Patterns in Rewrite Rules, Rewrite Rules
+@subsection Nested Formulas with Rewrite Rules
+
+@noindent
+When @kbd{a r} (@code{calc-rewrite}) is used, it takes an expression from
+the top of the stack and attempts to match any of the specified rules
+to any part of the expression, starting with the whole expression
+and then, if that fails, trying deeper and deeper sub-expressions.
+For each part of the expression, the rules are tried in the order
+they appear in the rules vector. The first rule to match the first
+sub-expression wins; it replaces the matched sub-expression according
+to the @var{new} part of the rule.
+
+Often, the rule set will match and change the formula several times.
+The top-level formula is first matched and substituted repeatedly until
+it no longer matches the pattern; then, sub-formulas are tried, and
+so on. Once every part of the formula has gotten its chance, the
+rewrite mechanism starts over again with the top-level formula
+(in case a substitution of one of its arguments has caused it again
+to match). This continues until no further matches can be made
+anywhere in the formula.
+
+It is possible for a rule set to get into an infinite loop. The
+most obvious case, replacing a formula with itself, is not a problem
+because a rule is not considered to ``succeed'' unless the righthand
+side actually comes out to something different than the original
+formula or sub-formula that was matched. But if you accidentally
+had both @samp{ln(a b) := ln(a) + ln(b)} and the reverse
+@samp{ln(a) + ln(b) := ln(a b)} in your rule set, Calc would
+run forever switching a formula back and forth between the two
+forms.
+
+To avoid disaster, Calc normally stops after 100 changes have been
+made to the formula. This will be enough for most multiple rewrites,
+but it will keep an endless loop of rewrites from locking up the
+computer forever. (On most systems, you can also type @kbd{C-g} to
+halt any Emacs command prematurely.)
+
+To change this limit, give a positive numeric prefix argument.
+In particular, @kbd{M-1 a r} applies only one rewrite at a time,
+useful when you are first testing your rule (or just if repeated
+rewriting is not what is called for by your application).
+
+@ignore
+@starindex
+@end ignore
+@ignore
+@mindex iter@idots
+@end ignore
+@tindex iterations
+You can also put a ``function call'' @samp{iterations(@var{n})}
+in place of a rule anywhere in your rules vector (but usually at
+the top). Then, @var{n} will be used instead of 100 as the default
+number of iterations for this rule set. You can use
+@samp{iterations(inf)} if you want no iteration limit by default.
+A prefix argument will override the @code{iterations} limit in the
+rule set.
+
+@example
+[ iterations(1),
+ f(x) := f(x+1) ]
+@end example
+
+More precisely, the limit controls the number of ``iterations,''
+where each iteration is a successful matching of a rule pattern whose
+righthand side, after substituting meta-variables and applying the
+default simplifications, is different from the original sub-formula
+that was matched.
+
+A prefix argument of zero sets the limit to infinity. Use with caution!
+
+Given a negative numeric prefix argument, @kbd{a r} will match and
+substitute the top-level expression up to that many times, but
+will not attempt to match the rules to any sub-expressions.
+
+In a formula, @code{rewrite(@var{expr}, @var{rules}, @var{n})}
+does a rewriting operation. Here @var{expr} is the expression
+being rewritten, @var{rules} is the rule, vector of rules, or
+variable containing the rules, and @var{n} is the optional
+iteration limit, which may be a positive integer, a negative
+integer, or @samp{inf} or @samp{-inf}. If @var{n} is omitted
+the @code{iterations} value from the rule set is used; if both
+are omitted, 100 is used.
+
+@node Multi-Phase Rewrite Rules, Selections with Rewrite Rules, Nested Formulas with Rewrite Rules, Rewrite Rules
+@subsection Multi-Phase Rewrite Rules
+
+@noindent
+It is possible to separate a rewrite rule set into several @dfn{phases}.
+During each phase, certain rules will be enabled while certain others
+will be disabled. A @dfn{phase schedule} controls the order in which
+phases occur during the rewriting process.
+
+@ignore
+@starindex
+@end ignore
+@tindex phase
+@vindex all
+If a call to the marker function @code{phase} appears in the rules
+vector in place of a rule, all rules following that point will be
+members of the phase(s) identified in the arguments to @code{phase}.
+Phases are given integer numbers. The markers @samp{phase()} and
+@samp{phase(all)} both mean the following rules belong to all phases;
+this is the default at the start of the rule set.
+
+If you do not explicitly schedule the phases, Calc sorts all phase
+numbers that appear in the rule set and executes the phases in
+ascending order. For example, the rule set
+
+@example
+@group
+[ f0(x) := g0(x),
+ phase(1),
+ f1(x) := g1(x),
+ phase(2),
+ f2(x) := g2(x),
+ phase(3),
+ f3(x) := g3(x),
+ phase(1,2),
+ f4(x) := g4(x) ]
+@end group
+@end example
+
+@noindent
+has three phases, 1 through 3. Phase 1 consists of the @code{f0},
+@code{f1}, and @code{f4} rules (in that order). Phase 2 consists of
+@code{f0}, @code{f2}, and @code{f4}. Phase 3 consists of @code{f0}
+and @code{f3}.
+
+When Calc rewrites a formula using this rule set, it first rewrites
+the formula using only the phase 1 rules until no further changes are
+possible. Then it switches to the phase 2 rule set and continues
+until no further changes occur, then finally rewrites with phase 3.
+When no more phase 3 rules apply, rewriting finishes. (This is
+assuming @kbd{a r} with a large enough prefix argument to allow the
+rewriting to run to completion; the sequence just described stops
+early if the number of iterations specified in the prefix argument,
+100 by default, is reached.)
+
+During each phase, Calc descends through the nested levels of the
+formula as described previously. (@xref{Nested Formulas with Rewrite
+Rules}.) Rewriting starts at the top of the formula, then works its
+way down to the parts, then goes back to the top and works down again.
+The phase 2 rules do not begin until no phase 1 rules apply anywhere
+in the formula.
+
+@ignore
+@starindex
+@end ignore
+@tindex schedule
+A @code{schedule} marker appearing in the rule set (anywhere, but
+conventionally at the top) changes the default schedule of phases.
+In the simplest case, @code{schedule} has a sequence of phase numbers
+for arguments; each phase number is invoked in turn until the
+arguments to @code{schedule} are exhausted. Thus adding
+@samp{schedule(3,2,1)} at the top of the above rule set would
+reverse the order of the phases; @samp{schedule(1,2,3)} would have
+no effect since this is the default schedule; and @samp{schedule(1,2,1,3)}
+would give phase 1 a second chance after phase 2 has completed, before
+moving on to phase 3.
+
+Any argument to @code{schedule} can instead be a vector of phase
+numbers (or even of sub-vectors). Then the sub-sequence of phases
+described by the vector are tried repeatedly until no change occurs
+in any phase in the sequence. For example, @samp{schedule([1, 2], 3)}
+tries phase 1, then phase 2, then, if either phase made any changes
+to the formula, repeats these two phases until they can make no
+further progress. Finally, it goes on to phase 3 for finishing
+touches.
+
+Also, items in @code{schedule} can be variable names as well as
+numbers. A variable name is interpreted as the name of a function
+to call on the whole formula. For example, @samp{schedule(1, simplify)}
+says to apply the phase-1 rules (presumably, all of them), then to
+call @code{simplify} which is the function name equivalent of @kbd{a s}.
+Likewise, @samp{schedule([1, simplify])} says to alternate between
+phase 1 and @kbd{a s} until no further changes occur.
+
+Phases can be used purely to improve efficiency; if it is known that
+a certain group of rules will apply only at the beginning of rewriting,
+and a certain other group will apply only at the end, then rewriting
+will be faster if these groups are identified as separate phases.
+Once the phase 1 rules are done, Calc can put them aside and no longer
+spend any time on them while it works on phase 2.
+
+There are also some problems that can only be solved with several
+rewrite phases. For a real-world example of a multi-phase rule set,
+examine the set @code{FitRules}, which is used by the curve-fitting
+command to convert a model expression to linear form.
+@xref{Curve Fitting Details}. This set is divided into four phases.
+The first phase rewrites certain kinds of expressions to be more
+easily linearizable, but less computationally efficient. After the
+linear components have been picked out, the final phase includes the
+opposite rewrites to put each component back into an efficient form.
+If both sets of rules were included in one big phase, Calc could get
+into an infinite loop going back and forth between the two forms.
+
+Elsewhere in @code{FitRules}, the components are first isolated,
+then recombined where possible to reduce the complexity of the linear
+fit, then finally packaged one component at a time into vectors.
+If the packaging rules were allowed to begin before the recombining
+rules were finished, some components might be put away into vectors
+before they had a chance to recombine. By putting these rules in
+two separate phases, this problem is neatly avoided.
+
+@node Selections with Rewrite Rules, Matching Commands, Multi-Phase Rewrite Rules, Rewrite Rules
+@subsection Selections with Rewrite Rules
+
+@noindent
+If a sub-formula of the current formula is selected (as by @kbd{j s};
+@pxref{Selecting Subformulas}), the @kbd{a r} (@code{calc-rewrite})
+command applies only to that sub-formula. Together with a negative
+prefix argument, you can use this fact to apply a rewrite to one
+specific part of a formula without affecting any other parts.
+
+@kindex j r
+@pindex calc-rewrite-selection
+The @kbd{j r} (@code{calc-rewrite-selection}) command allows more
+sophisticated operations on selections. This command prompts for
+the rules in the same way as @kbd{a r}, but it then applies those
+rules to the whole formula in question even though a sub-formula
+of it has been selected. However, the selected sub-formula will
+first have been surrounded by a @samp{select( )} function call.
+(Calc's evaluator does not understand the function name @code{select};
+this is only a tag used by the @kbd{j r} command.)
+
+For example, suppose the formula on the stack is @samp{2 (a + b)^2}
+and the sub-formula @samp{a + b} is selected. This formula will
+be rewritten to @samp{2 select(a + b)^2} and then the rewrite
+rules will be applied in the usual way. The rewrite rules can
+include references to @code{select} to tell where in the pattern
+the selected sub-formula should appear.
+
+If there is still exactly one @samp{select( )} function call in
+the formula after rewriting is done, it indicates which part of
+the formula should be selected afterwards. Otherwise, the
+formula will be unselected.
+
+You can make @kbd{j r} act much like @kbd{a r} by enclosing both parts
+of the rewrite rule with @samp{select()}. However, @kbd{j r}
+allows you to use the current selection in more flexible ways.
+Suppose you wished to make a rule which removed the exponent from
+the selected term; the rule @samp{select(a)^x := select(a)} would
+work. In the above example, it would rewrite @samp{2 select(a + b)^2}
+to @samp{2 select(a + b)}. This would then be returned to the
+stack as @samp{2 (a + b)} with the @samp{a + b} selected.
+
+The @kbd{j r} command uses one iteration by default, unlike
+@kbd{a r} which defaults to 100 iterations. A numeric prefix
+argument affects @kbd{j r} in the same way as @kbd{a r}.
+@xref{Nested Formulas with Rewrite Rules}.
+
+As with other selection commands, @kbd{j r} operates on the stack
+entry that contains the cursor. (If the cursor is on the top-of-stack
+@samp{.} marker, it works as if the cursor were on the formula
+at stack level 1.)
+
+If you don't specify a set of rules, the rules are taken from the
+top of the stack, just as with @kbd{a r}. In this case, the
+cursor must indicate stack entry 2 or above as the formula to be
+rewritten (otherwise the same formula would be used as both the
+target and the rewrite rules).
+
+If the indicated formula has no selection, the cursor position within
+the formula temporarily selects a sub-formula for the purposes of this
+command. If the cursor is not on any sub-formula (e.g., it is in
+the line-number area to the left of the formula), the @samp{select( )}
+markers are ignored by the rewrite mechanism and the rules are allowed
+to apply anywhere in the formula.
+
+As a special feature, the normal @kbd{a r} command also ignores
+@samp{select( )} calls in rewrite rules. For example, if you used the
+above rule @samp{select(a)^x := select(a)} with @kbd{a r}, it would apply
+the rule as if it were @samp{a^x := a}. Thus, you can write general
+purpose rules with @samp{select( )} hints inside them so that they
+will ``do the right thing'' in both @kbd{a r} and @kbd{j r},
+both with and without selections.
+
+@node Matching Commands, Automatic Rewrites, Selections with Rewrite Rules, Rewrite Rules
+@subsection Matching Commands
+
+@noindent
+@kindex a m
+@pindex calc-match
+@tindex match
+The @kbd{a m} (@code{calc-match}) [@code{match}] function takes a
+vector of formulas and a rewrite-rule-style pattern, and produces
+a vector of all formulas which match the pattern. The command
+prompts you to enter the pattern; as for @kbd{a r}, you can enter
+a single pattern (i.e., a formula with meta-variables), or a
+vector of patterns, or a variable which contains patterns, or
+you can give a blank response in which case the patterns are taken
+from the top of the stack. The pattern set will be compiled once
+and saved if it is stored in a variable. If there are several
+patterns in the set, vector elements are kept if they match any
+of the patterns.
+
+For example, @samp{match(a+b, [x, x+y, x-y, 7, x+y+z])}
+will return @samp{[x+y, x-y, x+y+z]}.
+
+The @code{import} mechanism is not available for pattern sets.
+
+The @kbd{a m} command can also be used to extract all vector elements
+which satisfy any condition: The pattern @samp{x :: x>0} will select
+all the positive vector elements.
+
+@kindex I a m
+@tindex matchnot
+With the Inverse flag [@code{matchnot}], this command extracts all
+vector elements which do @emph{not} match the given pattern.
+
+@ignore
+@starindex
+@end ignore
+@tindex matches
+There is also a function @samp{matches(@var{x}, @var{p})} which
+evaluates to 1 if expression @var{x} matches pattern @var{p}, or
+to 0 otherwise. This is sometimes useful for including into the
+conditional clauses of other rewrite rules.
+
+@ignore
+@starindex
+@end ignore
+@tindex vmatches
+The function @code{vmatches} is just like @code{matches}, except
+that if the match succeeds it returns a vector of assignments to
+the meta-variables instead of the number 1. For example,
+@samp{vmatches(f(1,2), f(a,b))} returns @samp{[a := 1, b := 2]}.
+If the match fails, the function returns the number 0.
+
+@node Automatic Rewrites, Debugging Rewrites, Matching Commands, Rewrite Rules
+@subsection Automatic Rewrites
+
+@noindent
+@cindex @code{EvalRules} variable
+@vindex EvalRules
+It is possible to get Calc to apply a set of rewrite rules on all
+results, effectively adding to the built-in set of default
+simplifications. To do this, simply store your rule set in the
+variable @code{EvalRules}. There is a convenient @kbd{s E} command
+for editing @code{EvalRules}; @pxref{Operations on Variables}.
+
+For example, suppose you want @samp{sin(a + b)} to be expanded out
+to @samp{sin(b) cos(a) + cos(b) sin(a)} wherever it appears, and
+similarly for @samp{cos(a + b)}. The corresponding rewrite rule
+set would be,
+
+@smallexample
+@group
+[ sin(a + b) := cos(a) sin(b) + sin(a) cos(b),
+ cos(a + b) := cos(a) cos(b) - sin(a) sin(b) ]
+@end group
+@end smallexample
+
+To apply these manually, you could put them in a variable called
+@code{trigexp} and then use @kbd{a r trigexp} every time you wanted
+to expand trig functions. But if instead you store them in the
+variable @code{EvalRules}, they will automatically be applied to all
+sines and cosines of sums. Then, with @samp{2 x} and @samp{45} on
+the stack, typing @kbd{+ S} will (assuming Degrees mode) result in
+@samp{0.7071 sin(2 x) + 0.7071 cos(2 x)} automatically.
+
+As each level of a formula is evaluated, the rules from
+@code{EvalRules} are applied before the default simplifications.
+Rewriting continues until no further @code{EvalRules} apply.
+Note that this is different from the usual order of application of
+rewrite rules: @code{EvalRules} works from the bottom up, simplifying
+the arguments to a function before the function itself, while @kbd{a r}
+applies rules from the top down.
+
+Because the @code{EvalRules} are tried first, you can use them to
+override the normal behavior of any built-in Calc function.
+
+It is important not to write a rule that will get into an infinite
+loop. For example, the rule set @samp{[f(0) := 1, f(n) := n f(n-1)]}
+appears to be a good definition of a factorial function, but it is
+unsafe. Imagine what happens if @samp{f(2.5)} is simplified. Calc
+will continue to subtract 1 from this argument forever without reaching
+zero. A safer second rule would be @samp{f(n) := n f(n-1) :: n>0}.
+Another dangerous rule is @samp{g(x, y) := g(y, x)}. Rewriting
+@samp{g(2, 4)}, this would bounce back and forth between that and
+@samp{g(4, 2)} forever. If an infinite loop in @code{EvalRules}
+occurs, Emacs will eventually stop with a ``Computation got stuck
+or ran too long'' message.
+
+Another subtle difference between @code{EvalRules} and regular rewrites
+concerns rules that rewrite a formula into an identical formula. For
+example, @samp{f(n) := f(floor(n))} ``fails to match'' when @expr{n} is
+already an integer. But in @code{EvalRules} this case is detected only
+if the righthand side literally becomes the original formula before any
+further simplification. This means that @samp{f(n) := f(floor(n))} will
+get into an infinite loop if it occurs in @code{EvalRules}. Calc will
+replace @samp{f(6)} with @samp{f(floor(6))}, which is different from
+@samp{f(6)}, so it will consider the rule to have matched and will
+continue simplifying that formula; first the argument is simplified
+to get @samp{f(6)}, then the rule matches again to get @samp{f(floor(6))}
+again, ad infinitum. A much safer rule would check its argument first,
+say, with @samp{f(n) := f(floor(n)) :: !dint(n)}.
+
+(What really happens is that the rewrite mechanism substitutes the
+meta-variables in the righthand side of a rule, compares to see if the
+result is the same as the original formula and fails if so, then uses
+the default simplifications to simplify the result and compares again
+(and again fails if the formula has simplified back to its original
+form). The only special wrinkle for the @code{EvalRules} is that the
+same rules will come back into play when the default simplifications
+are used. What Calc wants to do is build @samp{f(floor(6))}, see that
+this is different from the original formula, simplify to @samp{f(6)},
+see that this is the same as the original formula, and thus halt the
+rewriting. But while simplifying, @samp{f(6)} will again trigger
+the same @code{EvalRules} rule and Calc will get into a loop inside
+the rewrite mechanism itself.)
+
+The @code{phase}, @code{schedule}, and @code{iterations} markers do
+not work in @code{EvalRules}. If the rule set is divided into phases,
+only the phase 1 rules are applied, and the schedule is ignored.
+The rules are always repeated as many times as possible.
+
+The @code{EvalRules} are applied to all function calls in a formula,
+but not to numbers (and other number-like objects like error forms),
+nor to vectors or individual variable names. (Though they will apply
+to @emph{components} of vectors and error forms when appropriate.) You
+might try to make a variable @code{phihat} which automatically expands
+to its definition without the need to press @kbd{=} by writing the
+rule @samp{quote(phihat) := (1-sqrt(5))/2}, but unfortunately this rule
+will not work as part of @code{EvalRules}.
+
+Finally, another limitation is that Calc sometimes calls its built-in
+functions directly rather than going through the default simplifications.
+When it does this, @code{EvalRules} will not be able to override those
+functions. For example, when you take the absolute value of the complex
+number @expr{(2, 3)}, Calc computes @samp{sqrt(2*2 + 3*3)} by calling
+the multiplication, addition, and square root functions directly rather
+than applying the default simplifications to this formula. So an
+@code{EvalRules} rule that (perversely) rewrites @samp{sqrt(13) := 6}
+would not apply. (However, if you put Calc into Symbolic mode so that
+@samp{sqrt(13)} will be left in symbolic form by the built-in square
+root function, your rule will be able to apply. But if the complex
+number were @expr{(3,4)}, so that @samp{sqrt(25)} must be calculated,
+then Symbolic mode will not help because @samp{sqrt(25)} can be
+evaluated exactly to 5.)
+
+One subtle restriction that normally only manifests itself with
+@code{EvalRules} is that while a given rewrite rule is in the process
+of being checked, that same rule cannot be recursively applied. Calc
+effectively removes the rule from its rule set while checking the rule,
+then puts it back once the match succeeds or fails. (The technical
+reason for this is that compiled pattern programs are not reentrant.)
+For example, consider the rule @samp{foo(x) := x :: foo(x/2) > 0}
+attempting to match @samp{foo(8)}. This rule will be inactive while
+the condition @samp{foo(4) > 0} is checked, even though it might be
+an integral part of evaluating that condition. Note that this is not
+a problem for the more usual recursive type of rule, such as
+@samp{foo(x) := foo(x/2)}, because there the rule has succeeded and
+been reactivated by the time the righthand side is evaluated.
+
+If @code{EvalRules} has no stored value (its default state), or if
+anything but a vector is stored in it, then it is ignored.
+
+Even though Calc's rewrite mechanism is designed to compare rewrite
+rules to formulas as quickly as possible, storing rules in
+@code{EvalRules} may make Calc run substantially slower. This is
+particularly true of rules where the top-level call is a commonly used
+function, or is not fixed. The rule @samp{f(n) := n f(n-1) :: n>0} will
+only activate the rewrite mechanism for calls to the function @code{f},
+but @samp{lg(n) + lg(m) := lg(n m)} will check every @samp{+} operator.
+
+@smallexample
+apply(f, [a*b]) := apply(f, [a]) + apply(f, [b]) :: in(f, [ln, log10])
+@end smallexample
+
+@noindent
+may seem more ``efficient'' than two separate rules for @code{ln} and
+@code{log10}, but actually it is vastly less efficient because rules
+with @code{apply} as the top-level pattern must be tested against
+@emph{every} function call that is simplified.
+
+@cindex @code{AlgSimpRules} variable
+@vindex AlgSimpRules
+Suppose you want @samp{sin(a + b)} to be expanded out not all the time,
+but only when @kbd{a s} is used to simplify the formula. The variable
+@code{AlgSimpRules} holds rules for this purpose. The @kbd{a s} command
+will apply @code{EvalRules} and @code{AlgSimpRules} to the formula, as
+well as all of its built-in simplifications.
+
+Most of the special limitations for @code{EvalRules} don't apply to
+@code{AlgSimpRules}. Calc simply does an @kbd{a r AlgSimpRules}
+command with an infinite repeat count as the first step of @kbd{a s}.
+It then applies its own built-in simplifications throughout the
+formula, and then repeats these two steps (along with applying the
+default simplifications) until no further changes are possible.
+
+@cindex @code{ExtSimpRules} variable
+@cindex @code{UnitSimpRules} variable
+@vindex ExtSimpRules
+@vindex UnitSimpRules
+There are also @code{ExtSimpRules} and @code{UnitSimpRules} variables
+that are used by @kbd{a e} and @kbd{u s}, respectively; these commands
+also apply @code{EvalRules} and @code{AlgSimpRules}. The variable
+@code{IntegSimpRules} contains simplification rules that are used
+only during integration by @kbd{a i}.
+
+@node Debugging Rewrites, Examples of Rewrite Rules, Automatic Rewrites, Rewrite Rules
+@subsection Debugging Rewrites
+
+@noindent
+If a buffer named @samp{*Trace*} exists, the rewrite mechanism will
+record some useful information there as it operates. The original
+formula is written there, as is the result of each successful rewrite,
+and the final result of the rewriting. All phase changes are also
+noted.
+
+Calc always appends to @samp{*Trace*}. You must empty this buffer
+yourself periodically if it is in danger of growing unwieldy.
+
+Note that the rewriting mechanism is substantially slower when the
+@samp{*Trace*} buffer exists, even if the buffer is not visible on
+the screen. Once you are done, you will probably want to kill this
+buffer (with @kbd{C-x k *Trace* @key{RET}}). If you leave it in
+existence and forget about it, all your future rewrite commands will
+be needlessly slow.
+
+@node Examples of Rewrite Rules, , Debugging Rewrites, Rewrite Rules
+@subsection Examples of Rewrite Rules
+
+@noindent
+Returning to the example of substituting the pattern
+@samp{sin(x)^2 + cos(x)^2} with 1, we saw that the rule
+@samp{opt(a) sin(x)^2 + opt(a) cos(x)^2 := a} does a good job of
+finding suitable cases. Another solution would be to use the rule
+@samp{cos(x)^2 := 1 - sin(x)^2}, followed by algebraic simplification
+if necessary. This rule will be the most effective way to do the job,
+but at the expense of making some changes that you might not desire.
+
+Another algebraic rewrite rule is @samp{exp(x+y) := exp(x) exp(y)}.
+To make this work with the @w{@kbd{j r}} command so that it can be
+easily targeted to a particular exponential in a large formula,
+you might wish to write the rule as @samp{select(exp(x+y)) :=
+select(exp(x) exp(y))}. The @samp{select} markers will be
+ignored by the regular @kbd{a r} command
+(@pxref{Selections with Rewrite Rules}).
+
+A surprisingly useful rewrite rule is @samp{a/(b-c) := a*(b+c)/(b^2-c^2)}.
+This will simplify the formula whenever @expr{b} and/or @expr{c} can
+be made simpler by squaring. For example, applying this rule to
+@samp{2 / (sqrt(2) + 3)} yields @samp{6:7 - 2:7 sqrt(2)} (assuming
+Symbolic mode has been enabled to keep the square root from being
+evaluated to a floating-point approximation). This rule is also
+useful when working with symbolic complex numbers, e.g.,
+@samp{(a + b i) / (c + d i)}.
+
+As another example, we could define our own ``triangular numbers'' function
+with the rules @samp{[tri(0) := 0, tri(n) := n + tri(n-1) :: n>0]}. Enter
+this vector and store it in a variable: @kbd{@w{s t} trirules}. Now, given
+a suitable formula like @samp{tri(5)} on the stack, type @samp{a r trirules}
+to apply these rules repeatedly. After six applications, @kbd{a r} will
+stop with 15 on the stack. Once these rules are debugged, it would probably
+be most useful to add them to @code{EvalRules} so that Calc will evaluate
+the new @code{tri} function automatically. We could then use @kbd{Z K} on
+the keyboard macro @kbd{' tri($) @key{RET}} to make a command that applies
+@code{tri} to the value on the top of the stack. @xref{Programming}.
+
+@cindex Quaternions
+The following rule set, contributed by
+@texline Fran\c cois
+@infoline Francois
+Pinard, implements @dfn{quaternions}, a generalization of the concept of
+complex numbers. Quaternions have four components, and are here
+represented by function calls @samp{quat(@var{w}, [@var{x}, @var{y},
+@var{z}])} with ``real part'' @var{w} and the three ``imaginary'' parts
+collected into a vector. Various arithmetical operations on quaternions
+are supported. To use these rules, either add them to @code{EvalRules},
+or create a command based on @kbd{a r} for simplifying quaternion
+formulas. A convenient way to enter quaternions would be a command
+defined by a keyboard macro containing: @kbd{' quat($$$$, [$$$, $$, $])
+@key{RET}}.
+
+@smallexample
+[ quat(w, x, y, z) := quat(w, [x, y, z]),
+ quat(w, [0, 0, 0]) := w,
+ abs(quat(w, v)) := hypot(w, v),
+ -quat(w, v) := quat(-w, -v),
+ r + quat(w, v) := quat(r + w, v) :: real(r),
+ r - quat(w, v) := quat(r - w, -v) :: real(r),
+ quat(w1, v1) + quat(w2, v2) := quat(w1 + w2, v1 + v2),
+ r * quat(w, v) := quat(r * w, r * v) :: real(r),
+ plain(quat(w1, v1) * quat(w2, v2))
+ := quat(w1 * w2 - v1 * v2, w1 * v2 + w2 * v1 + cross(v1, v2)),
+ quat(w1, v1) / r := quat(w1 / r, v1 / r) :: real(r),
+ z / quat(w, v) := z * quatinv(quat(w, v)),
+ quatinv(quat(w, v)) := quat(w, -v) / (w^2 + v^2),
+ quatsqr(quat(w, v)) := quat(w^2 - v^2, 2 * w * v),
+ quat(w, v)^k := quatsqr(quat(w, v)^(k / 2))
+ :: integer(k) :: k > 0 :: k % 2 = 0,
+ quat(w, v)^k := quatsqr(quat(w, v)^((k - 1) / 2)) * quat(w, v)
+ :: integer(k) :: k > 2,
+ quat(w, v)^-k := quatinv(quat(w, v)^k) :: integer(k) :: k > 0 ]
+@end smallexample
+
+Quaternions, like matrices, have non-commutative multiplication.
+In other words, @expr{q1 * q2 = q2 * q1} is not necessarily true if
+@expr{q1} and @expr{q2} are @code{quat} forms. The @samp{quat*quat}
+rule above uses @code{plain} to prevent Calc from rearranging the
+product. It may also be wise to add the line @samp{[quat(), matrix]}
+to the @code{Decls} matrix, to ensure that Calc's other algebraic
+operations will not rearrange a quaternion product. @xref{Declarations}.
+
+These rules also accept a four-argument @code{quat} form, converting
+it to the preferred form in the first rule. If you would rather see
+results in the four-argument form, just append the two items
+@samp{phase(2), quat(w, [x, y, z]) := quat(w, x, y, z)} to the end
+of the rule set. (But remember that multi-phase rule sets don't work
+in @code{EvalRules}.)
+
+@node Units, Store and Recall, Algebra, Top
+@chapter Operating on Units
+
+@noindent
+One special interpretation of algebraic formulas is as numbers with units.
+For example, the formula @samp{5 m / s^2} can be read ``five meters
+per second squared.'' The commands in this chapter help you
+manipulate units expressions in this form. Units-related commands
+begin with the @kbd{u} prefix key.
+
+@menu
+* Basic Operations on Units::
+* The Units Table::
+* Predefined Units::
+* User-Defined Units::
+@end menu
+
+@node Basic Operations on Units, The Units Table, Units, Units
+@section Basic Operations on Units
+
+@noindent
+A @dfn{units expression} is a formula which is basically a number
+multiplied and/or divided by one or more @dfn{unit names}, which may
+optionally be raised to integer powers. Actually, the value part need not
+be a number; any product or quotient involving unit names is a units
+expression. Many of the units commands will also accept any formula,
+where the command applies to all units expressions which appear in the
+formula.
+
+A unit name is a variable whose name appears in the @dfn{unit table},
+or a variable whose name is a prefix character like @samp{k} (for ``kilo'')
+or @samp{u} (for ``micro'') followed by a name in the unit table.
+A substantial table of built-in units is provided with Calc;
+@pxref{Predefined Units}. You can also define your own unit names;
+@pxref{User-Defined Units}.
+
+Note that if the value part of a units expression is exactly @samp{1},
+it will be removed by the Calculator's automatic algebra routines: The
+formula @samp{1 mm} is ``simplified'' to @samp{mm}. This is only a
+display anomaly, however; @samp{mm} will work just fine as a
+representation of one millimeter.
+
+You may find that Algebraic mode (@pxref{Algebraic Entry}) makes working
+with units expressions easier. Otherwise, you will have to remember
+to hit the apostrophe key every time you wish to enter units.
+
+@kindex u s
+@pindex calc-simplify-units
+@ignore
+@mindex usimpl@idots
+@end ignore
+@tindex usimplify
+The @kbd{u s} (@code{calc-simplify-units}) [@code{usimplify}] command
+simplifies a units
+expression. It uses @kbd{a s} (@code{calc-simplify}) to simplify the
+expression first as a regular algebraic formula; it then looks for
+features that can be further simplified by converting one object's units
+to be compatible with another's. For example, @samp{5 m + 23 mm} will
+simplify to @samp{5.023 m}. When different but compatible units are
+added, the righthand term's units are converted to match those of the
+lefthand term. @xref{Simplification Modes}, for a way to have this done
+automatically at all times.
+
+Units simplification also handles quotients of two units with the same
+dimensionality, as in @w{@samp{2 in s/L cm}} to @samp{5.08 s/L}; fractional
+powers of unit expressions, as in @samp{sqrt(9 mm^2)} to @samp{3 mm} and
+@samp{sqrt(9 acre)} to a quantity in meters; and @code{floor},
+@code{ceil}, @code{round}, @code{rounde}, @code{roundu}, @code{trunc},
+@code{float}, @code{frac}, @code{abs}, and @code{clean}
+applied to units expressions, in which case
+the operation in question is applied only to the numeric part of the
+expression. Finally, trigonometric functions of quantities with units
+of angle are evaluated, regardless of the current angular mode.
+
+@kindex u c
+@pindex calc-convert-units
+The @kbd{u c} (@code{calc-convert-units}) command converts a units
+expression to new, compatible units. For example, given the units
+expression @samp{55 mph}, typing @kbd{u c m/s @key{RET}} produces
+@samp{24.5872 m/s}. If you have previously converted a units expression
+with the same type of units (in this case, distance over time), you will
+be offered the previous choice of new units as a default. Continuing
+the above example, entering the units expression @samp{100 km/hr} and
+typing @kbd{u c @key{RET}} (without specifying new units) produces
+@samp{27.7777777778 m/s}.
+
+While many of Calc's conversion factors are exact, some are necessarily
+approximate. If Calc is in fraction mode (@pxref{Fraction Mode}), then
+unit conversions will try to give exact, rational conversions, but it
+isn't always possible. Given @samp{55 mph} in fraction mode, typing
+@kbd{u c m/s @key{RET}} produces @samp{15367:625 m/s}, for example,
+while typing @kbd{u c au/yr @key{RET}} produces
+@samp{5.18665819999e-3 au/yr}.
+
+If the units you request are inconsistent with the original units, the
+number will be converted into your units times whatever ``remainder''
+units are left over. For example, converting @samp{55 mph} into acres
+produces @samp{6.08e-3 acre / m s}. (Recall that multiplication binds
+more strongly than division in Calc formulas, so the units here are
+acres per meter-second.) Remainder units are expressed in terms of
+``fundamental'' units like @samp{m} and @samp{s}, regardless of the
+input units.
+
+One special exception is that if you specify a single unit name, and
+a compatible unit appears somewhere in the units expression, then
+that compatible unit will be converted to the new unit and the
+remaining units in the expression will be left alone. For example,
+given the input @samp{980 cm/s^2}, the command @kbd{u c ms} will
+change the @samp{s} to @samp{ms} to get @samp{9.8e-4 cm/ms^2}.
+The ``remainder unit'' @samp{cm} is left alone rather than being
+changed to the base unit @samp{m}.
+
+You can use explicit unit conversion instead of the @kbd{u s} command
+to gain more control over the units of the result of an expression.
+For example, given @samp{5 m + 23 mm}, you can type @kbd{u c m} or
+@kbd{u c mm} to express the result in either meters or millimeters.
+(For that matter, you could type @kbd{u c fath} to express the result
+in fathoms, if you preferred!)
+
+In place of a specific set of units, you can also enter one of the
+units system names @code{si}, @code{mks} (equivalent), or @code{cgs}.
+For example, @kbd{u c si @key{RET}} converts the expression into
+International System of Units (SI) base units. Also, @kbd{u c base}
+converts to Calc's base units, which are the same as @code{si} units
+except that @code{base} uses @samp{g} as the fundamental unit of mass
+whereas @code{si} uses @samp{kg}.
+
+@cindex Composite units
+The @kbd{u c} command also accepts @dfn{composite units}, which
+are expressed as the sum of several compatible unit names. For
+example, converting @samp{30.5 in} to units @samp{mi+ft+in} (miles,
+feet, and inches) produces @samp{2 ft + 6.5 in}. Calc first
+sorts the unit names into order of decreasing relative size.
+It then accounts for as much of the input quantity as it can
+using an integer number times the largest unit, then moves on
+to the next smaller unit, and so on. Only the smallest unit
+may have a non-integer amount attached in the result. A few
+standard unit names exist for common combinations, such as
+@code{mfi} for @samp{mi+ft+in}, and @code{tpo} for @samp{ton+lb+oz}.
+Composite units are expanded as if by @kbd{a x}, so that
+@samp{(ft+in)/hr} is first converted to @samp{ft/hr+in/hr}.
+
+If the value on the stack does not contain any units, @kbd{u c} will
+prompt first for the old units which this value should be considered
+to have, then for the new units. Assuming the old and new units you
+give are consistent with each other, the result also will not contain
+any units. For example, @kbd{@w{u c} cm @key{RET} in @key{RET}} converts the number
+2 on the stack to 5.08.
+
+@kindex u b
+@pindex calc-base-units
+The @kbd{u b} (@code{calc-base-units}) command is shorthand for
+@kbd{u c base}; it converts the units expression on the top of the
+stack into @code{base} units. If @kbd{u s} does not simplify a
+units expression as far as you would like, try @kbd{u b}.
+
+The @kbd{u c} and @kbd{u b} commands treat temperature units (like
+@samp{degC} and @samp{K}) as relative temperatures. For example,
+@kbd{u c} converts @samp{10 degC} to @samp{18 degF}: A change of 10
+degrees Celsius corresponds to a change of 18 degrees Fahrenheit.
+
+@kindex u t
+@pindex calc-convert-temperature
+@cindex Temperature conversion
+The @kbd{u t} (@code{calc-convert-temperature}) command converts
+absolute temperatures. The value on the stack must be a simple units
+expression with units of temperature only. This command would convert
+@samp{10 degC} to @samp{50 degF}, the equivalent temperature on the
+Fahrenheit scale.
+
+@kindex u r
+@pindex calc-remove-units
+@kindex u x
+@pindex calc-extract-units
+The @kbd{u r} (@code{calc-remove-units}) command removes units from the
+formula at the top of the stack. The @kbd{u x}
+(@code{calc-extract-units}) command extracts only the units portion of a
+formula. These commands essentially replace every term of the formula
+that does or doesn't (respectively) look like a unit name by the
+constant 1, then resimplify the formula.
+
+@kindex u a
+@pindex calc-autorange-units
+The @kbd{u a} (@code{calc-autorange-units}) command turns on and off a
+mode in which unit prefixes like @code{k} (``kilo'') are automatically
+applied to keep the numeric part of a units expression in a reasonable
+range. This mode affects @kbd{u s} and all units conversion commands
+except @kbd{u b}. For example, with autoranging on, @samp{12345 Hz}
+will be simplified to @samp{12.345 kHz}. Autoranging is useful for
+some kinds of units (like @code{Hz} and @code{m}), but is probably
+undesirable for non-metric units like @code{ft} and @code{tbsp}.
+(Composite units are more appropriate for those; see above.)
+
+Autoranging always applies the prefix to the leftmost unit name.
+Calc chooses the largest prefix that causes the number to be greater
+than or equal to 1.0. Thus an increasing sequence of adjusted times
+would be @samp{1 ms, 10 ms, 100 ms, 1 s, 10 s, 100 s, 1 ks}.
+Generally the rule of thumb is that the number will be adjusted
+to be in the interval @samp{[1 .. 1000)}, although there are several
+exceptions to this rule. First, if the unit has a power then this
+is not possible; @samp{0.1 s^2} simplifies to @samp{100000 ms^2}.
+Second, the ``centi-'' prefix is allowed to form @code{cm} (centimeters),
+but will not apply to other units. The ``deci-,'' ``deka-,'' and
+``hecto-'' prefixes are never used. Thus the allowable interval is
+@samp{[1 .. 10)} for millimeters and @samp{[1 .. 100)} for centimeters.
+Finally, a prefix will not be added to a unit if the resulting name
+is also the actual name of another unit; @samp{1e-15 t} would normally
+be considered a ``femto-ton,'' but it is written as @samp{1000 at}
+(1000 atto-tons) instead because @code{ft} would be confused with feet.
+
+@node The Units Table, Predefined Units, Basic Operations on Units, Units
+@section The Units Table
+
+@noindent
+@kindex u v
+@pindex calc-enter-units-table
+The @kbd{u v} (@code{calc-enter-units-table}) command displays the units table
+in another buffer called @code{*Units Table*}. Each entry in this table
+gives the unit name as it would appear in an expression, the definition
+of the unit in terms of simpler units, and a full name or description of
+the unit. Fundamental units are defined as themselves; these are the
+units produced by the @kbd{u b} command. The fundamental units are
+meters, seconds, grams, kelvins, amperes, candelas, moles, radians,
+and steradians.
+
+The Units Table buffer also displays the Unit Prefix Table. Note that
+two prefixes, ``kilo'' and ``hecto,'' accept either upper- or lower-case
+prefix letters. @samp{Meg} is also accepted as a synonym for the @samp{M}
+prefix. Whenever a unit name can be interpreted as either a built-in name
+or a prefix followed by another built-in name, the former interpretation
+wins. For example, @samp{2 pt} means two pints, not two pico-tons.
+
+The Units Table buffer, once created, is not rebuilt unless you define
+new units. To force the buffer to be rebuilt, give any numeric prefix
+argument to @kbd{u v}.
+
+@kindex u V
+@pindex calc-view-units-table
+The @kbd{u V} (@code{calc-view-units-table}) command is like @kbd{u v} except
+that the cursor is not moved into the Units Table buffer. You can
+type @kbd{u V} again to remove the Units Table from the display. To
+return from the Units Table buffer after a @kbd{u v}, type @kbd{C-x * c}
+again or use the regular Emacs @w{@kbd{C-x o}} (@code{other-window})
+command. You can also kill the buffer with @kbd{C-x k} if you wish;
+the actual units table is safely stored inside the Calculator.
+
+@kindex u g
+@pindex calc-get-unit-definition
+The @kbd{u g} (@code{calc-get-unit-definition}) command retrieves a unit's
+defining expression and pushes it onto the Calculator stack. For example,
+@kbd{u g in} will produce the expression @samp{2.54 cm}. This is the
+same definition for the unit that would appear in the Units Table buffer.
+Note that this command works only for actual unit names; @kbd{u g km}
+will report that no such unit exists, for example, because @code{km} is
+really the unit @code{m} with a @code{k} (``kilo'') prefix. To see a
+definition of a unit in terms of base units, it is easier to push the
+unit name on the stack and then reduce it to base units with @kbd{u b}.
+
+@kindex u e
+@pindex calc-explain-units
+The @kbd{u e} (@code{calc-explain-units}) command displays an English
+description of the units of the expression on the stack. For example,
+for the expression @samp{62 km^2 g / s^2 mol K}, the description is
+``Square-Kilometer Gram per (Second-squared Mole Degree-Kelvin).'' This
+command uses the English descriptions that appear in the righthand
+column of the Units Table.
+
+@node Predefined Units, User-Defined Units, The Units Table, Units
+@section Predefined Units
+
+@noindent
+Since the exact definitions of many kinds of units have evolved over the
+years, and since certain countries sometimes have local differences in
+their definitions, it is a good idea to examine Calc's definition of a
+unit before depending on its exact value. For example, there are three
+different units for gallons, corresponding to the US (@code{gal}),
+Canadian (@code{galC}), and British (@code{galUK}) definitions. Also,
+note that @code{oz} is a standard ounce of mass, @code{ozt} is a Troy
+ounce, and @code{ozfl} is a fluid ounce.
+
+The temperature units corresponding to degrees Kelvin and Centigrade
+(Celsius) are the same in this table, since most units commands treat
+temperatures as being relative. The @code{calc-convert-temperature}
+command has special rules for handling the different absolute magnitudes
+of the various temperature scales.
+
+The unit of volume ``liters'' can be referred to by either the lower-case
+@code{l} or the upper-case @code{L}.
+
+The unit @code{A} stands for Amperes; the name @code{Ang} is used
+@tex
+for \AA ngstroms.
+@end tex
+@ifnottex
+for Angstroms.
+@end ifnottex
+
+The unit @code{pt} stands for pints; the name @code{point} stands for
+a typographical point, defined by @samp{72 point = 1 in}. This is
+slightly different than the point defined by the American Typefounder's
+Association in 1886, but the point used by Calc has become standard
+largely due to its use by the PostScript page description language.
+There is also @code{texpt}, which stands for a printer's point as
+defined by the @TeX{} typesetting system: @samp{72.27 texpt = 1 in}.
+Other units used by @TeX{} are available; they are @code{texpc} (a pica),
+@code{texbp} (a ``big point'', equal to a standard point which is larger
+than the point used by @TeX{}), @code{texdd} (a Didot point),
+@code{texcc} (a Cicero) and @code{texsp} (a scaled @TeX{} point,
+all dimensions representable in @TeX{} are multiples of this value).
+
+The unit @code{e} stands for the elementary (electron) unit of charge;
+because algebra command could mistake this for the special constant
+@expr{e}, Calc provides the alternate unit name @code{ech} which is
+preferable to @code{e}.
+
+The name @code{g} stands for one gram of mass; there is also @code{gf},
+one gram of force. (Likewise for @kbd{lb}, pounds, and @kbd{lbf}.)
+Meanwhile, one ``@expr{g}'' of acceleration is denoted @code{ga}.
+
+The unit @code{ton} is a U.S. ton of @samp{2000 lb}, and @code{t} is
+a metric ton of @samp{1000 kg}.
+
+The names @code{s} (or @code{sec}) and @code{min} refer to units of
+time; @code{arcsec} and @code{arcmin} are units of angle.
+
+Some ``units'' are really physical constants; for example, @code{c}
+represents the speed of light, and @code{h} represents Planck's
+constant. You can use these just like other units: converting
+@samp{.5 c} to @samp{m/s} expresses one-half the speed of light in
+meters per second. You can also use this merely as a handy reference;
+the @kbd{u g} command gets the definition of one of these constants
+in its normal terms, and @kbd{u b} expresses the definition in base
+units.
+
+Two units, @code{pi} and @code{alpha} (the fine structure constant,
+approximately @mathit{1/137}) are dimensionless. The units simplification
+commands simply treat these names as equivalent to their corresponding
+values. However you can, for example, use @kbd{u c} to convert a pure
+number into multiples of the fine structure constant, or @kbd{u b} to
+convert this back into a pure number. (When @kbd{u c} prompts for the
+``old units,'' just enter a blank line to signify that the value
+really is unitless.)
+
+@c Describe angular units, luminosity vs. steradians problem.
+
+@node User-Defined Units, , Predefined Units, Units
+@section User-Defined Units
+
+@noindent
+Calc provides ways to get quick access to your selected ``favorite''
+units, as well as ways to define your own new units.
+
+@kindex u 0-9
+@pindex calc-quick-units
+@vindex Units
+@cindex @code{Units} variable
+@cindex Quick units
+To select your favorite units, store a vector of unit names or
+expressions in the Calc variable @code{Units}. The @kbd{u 1}
+through @kbd{u 9} commands (@code{calc-quick-units}) provide access
+to these units. If the value on the top of the stack is a plain
+number (with no units attached), then @kbd{u 1} gives it the
+specified units. (Basically, it multiplies the number by the
+first item in the @code{Units} vector.) If the number on the
+stack @emph{does} have units, then @kbd{u 1} converts that number
+to the new units. For example, suppose the vector @samp{[in, ft]}
+is stored in @code{Units}. Then @kbd{30 u 1} will create the
+expression @samp{30 in}, and @kbd{u 2} will convert that expression
+to @samp{2.5 ft}.
+
+The @kbd{u 0} command accesses the tenth element of @code{Units}.
+Only ten quick units may be defined at a time. If the @code{Units}
+variable has no stored value (the default), or if its value is not
+a vector, then the quick-units commands will not function. The
+@kbd{s U} command is a convenient way to edit the @code{Units}
+variable; @pxref{Operations on Variables}.
+
+@kindex u d
+@pindex calc-define-unit
+@cindex User-defined units
+The @kbd{u d} (@code{calc-define-unit}) command records the units
+expression on the top of the stack as the definition for a new,
+user-defined unit. For example, putting @samp{16.5 ft} on the stack and
+typing @kbd{u d rod} defines the new unit @samp{rod} to be equivalent to
+16.5 feet. The unit conversion and simplification commands will now
+treat @code{rod} just like any other unit of length. You will also be
+prompted for an optional English description of the unit, which will
+appear in the Units Table.
+
+@kindex u u
+@pindex calc-undefine-unit
+The @kbd{u u} (@code{calc-undefine-unit}) command removes a user-defined
+unit. It is not possible to remove one of the predefined units,
+however.
+
+If you define a unit with an existing unit name, your new definition
+will replace the original definition of that unit. If the unit was a
+predefined unit, the old definition will not be replaced, only
+``shadowed.'' The built-in definition will reappear if you later use
+@kbd{u u} to remove the shadowing definition.
+
+To create a new fundamental unit, use either 1 or the unit name itself
+as the defining expression. Otherwise the expression can involve any
+other units that you like (except for composite units like @samp{mfi}).
+You can create a new composite unit with a sum of other units as the
+defining expression. The next unit operation like @kbd{u c} or @kbd{u v}
+will rebuild the internal unit table incorporating your modifications.
+Note that erroneous definitions (such as two units defined in terms of
+each other) will not be detected until the unit table is next rebuilt;
+@kbd{u v} is a convenient way to force this to happen.
+
+Temperature units are treated specially inside the Calculator; it is not
+possible to create user-defined temperature units.
+
+@kindex u p
+@pindex calc-permanent-units
+@cindex Calc init file, user-defined units
+The @kbd{u p} (@code{calc-permanent-units}) command stores the user-defined
+units in your Calc init file (the file given by the variable
+@code{calc-settings-file}, typically @file{~/.calc.el}), so that the
+units will still be available in subsequent Emacs sessions. If there
+was already a set of user-defined units in your Calc init file, it
+is replaced by the new set. (@xref{General Mode Commands}, for a way to
+tell Calc to use a different file for the Calc init file.)
+
+@node Store and Recall, Graphics, Units, Top
+@chapter Storing and Recalling
+
+@noindent
+Calculator variables are really just Lisp variables that contain numbers
+or formulas in a form that Calc can understand. The commands in this
+section allow you to manipulate variables conveniently. Commands related
+to variables use the @kbd{s} prefix key.
+
+@menu
+* Storing Variables::
+* Recalling Variables::
+* Operations on Variables::
+* Let Command::
+* Evaluates-To Operator::
+@end menu
+
+@node Storing Variables, Recalling Variables, Store and Recall, Store and Recall
+@section Storing Variables
+
+@noindent
+@kindex s s
+@pindex calc-store
+@cindex Storing variables
+@cindex Quick variables
+@vindex q0
+@vindex q9
+The @kbd{s s} (@code{calc-store}) command stores the value at the top of
+the stack into a specified variable. It prompts you to enter the
+name of the variable. If you press a single digit, the value is stored
+immediately in one of the ``quick'' variables @code{q0} through
+@code{q9}. Or you can enter any variable name.
+
+@kindex s t
+@pindex calc-store-into
+The @kbd{s s} command leaves the stored value on the stack. There is
+also an @kbd{s t} (@code{calc-store-into}) command, which removes a
+value from the stack and stores it in a variable.
+
+If the top of stack value is an equation @samp{a = 7} or assignment
+@samp{a := 7} with a variable on the lefthand side, then Calc will
+assign that variable with that value by default, i.e., if you type
+@kbd{s s @key{RET}} or @kbd{s t @key{RET}}. In this example, the
+value 7 would be stored in the variable @samp{a}. (If you do type
+a variable name at the prompt, the top-of-stack value is stored in
+its entirety, even if it is an equation: @samp{s s b @key{RET}}
+with @samp{a := 7} on the stack stores @samp{a := 7} in @code{b}.)
+
+In fact, the top of stack value can be a vector of equations or
+assignments with different variables on their lefthand sides; the
+default will be to store all the variables with their corresponding
+righthand sides simultaneously.
+
+It is also possible to type an equation or assignment directly at
+the prompt for the @kbd{s s} or @kbd{s t} command: @kbd{s s foo = 7}.
+In this case the expression to the right of the @kbd{=} or @kbd{:=}
+symbol is evaluated as if by the @kbd{=} command, and that value is
+stored in the variable. No value is taken from the stack; @kbd{s s}
+and @kbd{s t} are equivalent when used in this way.
+
+@kindex s 0-9
+@kindex t 0-9
+The prefix keys @kbd{s} and @kbd{t} may be followed immediately by a
+digit; @kbd{s 9} is equivalent to @kbd{s s 9}, and @kbd{t 9} is
+equivalent to @kbd{s t 9}. (The @kbd{t} prefix is otherwise used
+for trail and time/date commands.)
+
+@kindex s +
+@kindex s -
+@ignore
+@mindex @idots
+@end ignore
+@kindex s *
+@ignore
+@mindex @null
+@end ignore
+@kindex s /
+@ignore
+@mindex @null
+@end ignore
+@kindex s ^
+@ignore
+@mindex @null
+@end ignore
+@kindex s |
+@ignore
+@mindex @null
+@end ignore
+@kindex s n
+@ignore
+@mindex @null
+@end ignore
+@kindex s &
+@ignore
+@mindex @null
+@end ignore
+@kindex s [
+@ignore
+@mindex @null
+@end ignore
+@kindex s ]
+@pindex calc-store-plus
+@pindex calc-store-minus
+@pindex calc-store-times
+@pindex calc-store-div
+@pindex calc-store-power
+@pindex calc-store-concat
+@pindex calc-store-neg
+@pindex calc-store-inv
+@pindex calc-store-decr
+@pindex calc-store-incr
+There are also several ``arithmetic store'' commands. For example,
+@kbd{s +} removes a value from the stack and adds it to the specified
+variable. The other arithmetic stores are @kbd{s -}, @kbd{s *}, @kbd{s /},
+@kbd{s ^}, and @w{@kbd{s |}} (vector concatenation), plus @kbd{s n} and
+@kbd{s &} which negate or invert the value in a variable, and @w{@kbd{s [}}
+and @kbd{s ]} which decrease or increase a variable by one.
+
+All the arithmetic stores accept the Inverse prefix to reverse the
+order of the operands. If @expr{v} represents the contents of the
+variable, and @expr{a} is the value drawn from the stack, then regular
+@w{@kbd{s -}} assigns
+@texline @math{v \coloneq v - a},
+@infoline @expr{v := v - a},
+but @kbd{I s -} assigns
+@texline @math{v \coloneq a - v}.
+@infoline @expr{v := a - v}.
+While @kbd{I s *} might seem pointless, it is
+useful if matrix multiplication is involved. Actually, all the
+arithmetic stores use formulas designed to behave usefully both
+forwards and backwards:
+
+@example
+@group
+s + v := v + a v := a + v
+s - v := v - a v := a - v
+s * v := v * a v := a * v
+s / v := v / a v := a / v
+s ^ v := v ^ a v := a ^ v
+s | v := v | a v := a | v
+s n v := v / (-1) v := (-1) / v
+s & v := v ^ (-1) v := (-1) ^ v
+s [ v := v - 1 v := 1 - v
+s ] v := v - (-1) v := (-1) - v
+@end group
+@end example
+
+In the last four cases, a numeric prefix argument will be used in
+place of the number one. (For example, @kbd{M-2 s ]} increases
+a variable by 2, and @kbd{M-2 I s ]} replaces a variable by
+minus-two minus the variable.
+
+The first six arithmetic stores can also be typed @kbd{s t +}, @kbd{s t -},
+etc. The commands @kbd{s s +}, @kbd{s s -}, and so on are analogous
+arithmetic stores that don't remove the value @expr{a} from the stack.
+
+All arithmetic stores report the new value of the variable in the
+Trail for your information. They signal an error if the variable
+previously had no stored value. If default simplifications have been
+turned off, the arithmetic stores temporarily turn them on for numeric
+arguments only (i.e., they temporarily do an @kbd{m N} command).
+@xref{Simplification Modes}. Large vectors put in the trail by
+these commands always use abbreviated (@kbd{t .}) mode.
+
+@kindex s m
+@pindex calc-store-map
+The @kbd{s m} command is a general way to adjust a variable's value
+using any Calc function. It is a ``mapping'' command analogous to
+@kbd{V M}, @kbd{V R}, etc. @xref{Reducing and Mapping}, to see
+how to specify a function for a mapping command. Basically,
+all you do is type the Calc command key that would invoke that
+function normally. For example, @kbd{s m n} applies the @kbd{n}
+key to negate the contents of the variable, so @kbd{s m n} is
+equivalent to @kbd{s n}. Also, @kbd{s m Q} takes the square root
+of the value stored in a variable, @kbd{s m v v} uses @kbd{v v} to
+reverse the vector stored in the variable, and @kbd{s m H I S}
+takes the hyperbolic arcsine of the variable contents.
+
+If the mapping function takes two or more arguments, the additional
+arguments are taken from the stack; the old value of the variable
+is provided as the first argument. Thus @kbd{s m -} with @expr{a}
+on the stack computes @expr{v - a}, just like @kbd{s -}. With the
+Inverse prefix, the variable's original value becomes the @emph{last}
+argument instead of the first. Thus @kbd{I s m -} is also
+equivalent to @kbd{I s -}.
+
+@kindex s x
+@pindex calc-store-exchange
+The @kbd{s x} (@code{calc-store-exchange}) command exchanges the value
+of a variable with the value on the top of the stack. Naturally, the
+variable must already have a stored value for this to work.
+
+You can type an equation or assignment at the @kbd{s x} prompt. The
+command @kbd{s x a=6} takes no values from the stack; instead, it
+pushes the old value of @samp{a} on the stack and stores @samp{a = 6}.
+
+@kindex s u
+@pindex calc-unstore
+@cindex Void variables
+@cindex Un-storing variables
+Until you store something in them, most variables are ``void,'' that is,
+they contain no value at all. If they appear in an algebraic formula
+they will be left alone even if you press @kbd{=} (@code{calc-evaluate}).
+The @kbd{s u} (@code{calc-unstore}) command returns a variable to the
+void state.
+
+@kindex s c
+@pindex calc-copy-variable
+The @kbd{s c} (@code{calc-copy-variable}) command copies the stored
+value of one variable to another. One way it differs from a simple
+@kbd{s r} followed by an @kbd{s t} (aside from saving keystrokes) is
+that the value never goes on the stack and thus is never rounded,
+evaluated, or simplified in any way; it is not even rounded down to the
+current precision.
+
+The only variables with predefined values are the ``special constants''
+@code{pi}, @code{e}, @code{i}, @code{phi}, and @code{gamma}. You are free
+to unstore these variables or to store new values into them if you like,
+although some of the algebraic-manipulation functions may assume these
+variables represent their standard values. Calc displays a warning if
+you change the value of one of these variables, or of one of the other
+special variables @code{inf}, @code{uinf}, and @code{nan} (which are
+normally void).
+
+Note that @code{pi} doesn't actually have 3.14159265359 stored in it,
+but rather a special magic value that evaluates to @cpi{} at the current
+precision. Likewise @code{e}, @code{i}, and @code{phi} evaluate
+according to the current precision or polar mode. If you recall a value
+from @code{pi} and store it back, this magic property will be lost. The
+magic property is preserved, however, when a variable is copied with
+@kbd{s c}.
+
+@kindex s k
+@pindex calc-copy-special-constant
+If one of the ``special constants'' is redefined (or undefined) so that
+it no longer has its magic property, the property can be restored with
+@kbd{s k} (@code{calc-copy-special-constant}). This command will prompt
+for a special constant and a variable to store it in, and so a special
+constant can be stored in any variable. Here, the special constant that
+you enter doesn't depend on the value of the corresponding variable;
+@code{pi} will represent 3.14159@dots{} regardless of what is currently
+stored in the Calc variable @code{pi}. If one of the other special
+variables, @code{inf}, @code{uinf} or @code{nan}, is given a value, its
+original behavior can be restored by voiding it with @kbd{s u}.
+
+@node Recalling Variables, Operations on Variables, Storing Variables, Store and Recall
+@section Recalling Variables
+
+@noindent
+@kindex s r
+@pindex calc-recall
+@cindex Recalling variables
+The most straightforward way to extract the stored value from a variable
+is to use the @kbd{s r} (@code{calc-recall}) command. This command prompts
+for a variable name (similarly to @code{calc-store}), looks up the value
+of the specified variable, and pushes that value onto the stack. It is
+an error to try to recall a void variable.
+
+It is also possible to recall the value from a variable by evaluating a
+formula containing that variable. For example, @kbd{' a @key{RET} =} is
+the same as @kbd{s r a @key{RET}} except that if the variable is void, the
+former will simply leave the formula @samp{a} on the stack whereas the
+latter will produce an error message.
+
+@kindex r 0-9
+The @kbd{r} prefix may be followed by a digit, so that @kbd{r 9} is
+equivalent to @kbd{s r 9}. (The @kbd{r} prefix is otherwise unused
+in the current version of Calc.)
+
+@node Operations on Variables, Let Command, Recalling Variables, Store and Recall
+@section Other Operations on Variables
+
+@noindent
+@kindex s e
+@pindex calc-edit-variable
+The @kbd{s e} (@code{calc-edit-variable}) command edits the stored
+value of a variable without ever putting that value on the stack
+or simplifying or evaluating the value. It prompts for the name of
+the variable to edit. If the variable has no stored value, the
+editing buffer will start out empty. If the editing buffer is
+empty when you press @kbd{C-c C-c} to finish, the variable will
+be made void. @xref{Editing Stack Entries}, for a general
+description of editing.
+
+The @kbd{s e} command is especially useful for creating and editing
+rewrite rules which are stored in variables. Sometimes these rules
+contain formulas which must not be evaluated until the rules are
+actually used. (For example, they may refer to @samp{deriv(x,y)},
+where @code{x} will someday become some expression involving @code{y};
+if you let Calc evaluate the rule while you are defining it, Calc will
+replace @samp{deriv(x,y)} with 0 because the formula @code{x} does
+not itself refer to @code{y}.) By contrast, recalling the variable,
+editing with @kbd{`}, and storing will evaluate the variable's value
+as a side effect of putting the value on the stack.
+
+@kindex s A
+@kindex s D
+@ignore
+@mindex @idots
+@end ignore
+@kindex s E
+@ignore
+@mindex @null
+@end ignore
+@kindex s F
+@ignore
+@mindex @null
+@end ignore
+@kindex s G
+@ignore
+@mindex @null
+@end ignore
+@kindex s H
+@ignore
+@mindex @null
+@end ignore
+@kindex s I
+@ignore
+@mindex @null
+@end ignore
+@kindex s L
+@ignore
+@mindex @null
+@end ignore
+@kindex s P
+@ignore
+@mindex @null
+@end ignore
+@kindex s R
+@ignore
+@mindex @null
+@end ignore
+@kindex s T
+@ignore
+@mindex @null
+@end ignore
+@kindex s U
+@ignore
+@mindex @null
+@end ignore
+@kindex s X
+@pindex calc-store-AlgSimpRules
+@pindex calc-store-Decls
+@pindex calc-store-EvalRules
+@pindex calc-store-FitRules
+@pindex calc-store-GenCount
+@pindex calc-store-Holidays
+@pindex calc-store-IntegLimit
+@pindex calc-store-LineStyles
+@pindex calc-store-PointStyles
+@pindex calc-store-PlotRejects
+@pindex calc-store-TimeZone
+@pindex calc-store-Units
+@pindex calc-store-ExtSimpRules
+There are several special-purpose variable-editing commands that
+use the @kbd{s} prefix followed by a shifted letter:
+
+@table @kbd
+@item s A
+Edit @code{AlgSimpRules}. @xref{Algebraic Simplifications}.
+@item s D
+Edit @code{Decls}. @xref{Declarations}.
+@item s E
+Edit @code{EvalRules}. @xref{Default Simplifications}.
+@item s F
+Edit @code{FitRules}. @xref{Curve Fitting}.
+@item s G
+Edit @code{GenCount}. @xref{Solving Equations}.
+@item s H
+Edit @code{Holidays}. @xref{Business Days}.
+@item s I
+Edit @code{IntegLimit}. @xref{Calculus}.
+@item s L
+Edit @code{LineStyles}. @xref{Graphics}.
+@item s P
+Edit @code{PointStyles}. @xref{Graphics}.
+@item s R
+Edit @code{PlotRejects}. @xref{Graphics}.
+@item s T
+Edit @code{TimeZone}. @xref{Time Zones}.
+@item s U
+Edit @code{Units}. @xref{User-Defined Units}.
+@item s X
+Edit @code{ExtSimpRules}. @xref{Unsafe Simplifications}.
+@end table
+
+These commands are just versions of @kbd{s e} that use fixed variable
+names rather than prompting for the variable name.
+
+@kindex s p
+@pindex calc-permanent-variable
+@cindex Storing variables
+@cindex Permanent variables
+@cindex Calc init file, variables
+The @kbd{s p} (@code{calc-permanent-variable}) command saves a
+variable's value permanently in your Calc init file (the file given by
+the variable @code{calc-settings-file}, typically @file{~/.calc.el}), so
+that its value will still be available in future Emacs sessions. You
+can re-execute @w{@kbd{s p}} later on to update the saved value, but the
+only way to remove a saved variable is to edit your calc init file
+by hand. (@xref{General Mode Commands}, for a way to tell Calc to
+use a different file for the Calc init file.)
+
+If you do not specify the name of a variable to save (i.e.,
+@kbd{s p @key{RET}}), all Calc variables with defined values
+are saved except for the special constants @code{pi}, @code{e},
+@code{i}, @code{phi}, and @code{gamma}; the variables @code{TimeZone}
+and @code{PlotRejects};
+@code{FitRules}, @code{DistribRules}, and other built-in rewrite
+rules; and @code{PlotData@var{n}} variables generated
+by the graphics commands. (You can still save these variables by
+explicitly naming them in an @kbd{s p} command.)
+
+@kindex s i
+@pindex calc-insert-variables
+The @kbd{s i} (@code{calc-insert-variables}) command writes
+the values of all Calc variables into a specified buffer.
+The variables are written with the prefix @code{var-} in the form of
+Lisp @code{setq} commands
+which store the values in string form. You can place these commands
+in your Calc init file (or @file{.emacs}) if you wish, though in this case it
+would be easier to use @kbd{s p @key{RET}}. (Note that @kbd{s i}
+omits the same set of variables as @w{@kbd{s p @key{RET}}}; the difference
+is that @kbd{s i} will store the variables in any buffer, and it also
+stores in a more human-readable format.)
+
+@node Let Command, Evaluates-To Operator, Operations on Variables, Store and Recall
+@section The Let Command
+
+@noindent
+@kindex s l
+@pindex calc-let
+@cindex Variables, temporary assignment
+@cindex Temporary assignment to variables
+If you have an expression like @samp{a+b^2} on the stack and you wish to
+compute its value where @expr{b=3}, you can simply store 3 in @expr{b} and
+then press @kbd{=} to reevaluate the formula. This has the side-effect
+of leaving the stored value of 3 in @expr{b} for future operations.
+
+The @kbd{s l} (@code{calc-let}) command evaluates a formula under a
+@emph{temporary} assignment of a variable. It stores the value on the
+top of the stack into the specified variable, then evaluates the
+second-to-top stack entry, then restores the original value (or lack of one)
+in the variable. Thus after @kbd{'@w{ }a+b^2 @key{RET} 3 s l b @key{RET}},
+the stack will contain the formula @samp{a + 9}. The subsequent command
+@kbd{@w{5 s l a} @key{RET}} will replace this formula with the number 14.
+The variables @samp{a} and @samp{b} are not permanently affected in any way
+by these commands.
+
+The value on the top of the stack may be an equation or assignment, or
+a vector of equations or assignments, in which case the default will be
+analogous to the case of @kbd{s t @key{RET}}. @xref{Storing Variables}.
+
+Also, you can answer the variable-name prompt with an equation or
+assignment: @kbd{s l b=3 @key{RET}} is the same as storing 3 on the stack
+and typing @kbd{s l b @key{RET}}.
+
+The @kbd{a b} (@code{calc-substitute}) command is another way to substitute
+a variable with a value in a formula. It does an actual substitution
+rather than temporarily assigning the variable and evaluating. For
+example, letting @expr{n=2} in @samp{f(n pi)} with @kbd{a b} will
+produce @samp{f(2 pi)}, whereas @kbd{s l} would give @samp{f(6.28)}
+since the evaluation step will also evaluate @code{pi}.
+
+@node Evaluates-To Operator, , Let Command, Store and Recall
+@section The Evaluates-To Operator
+
+@noindent
+@tindex evalto
+@tindex =>
+@cindex Evaluates-to operator
+@cindex @samp{=>} operator
+The special algebraic symbol @samp{=>} is known as the @dfn{evaluates-to
+operator}. (It will show up as an @code{evalto} function call in
+other language modes like Pascal and La@TeX{}.) This is a binary
+operator, that is, it has a lefthand and a righthand argument,
+although it can be entered with the righthand argument omitted.
+
+A formula like @samp{@var{a} => @var{b}} is evaluated by Calc as
+follows: First, @var{a} is not simplified or modified in any
+way. The previous value of argument @var{b} is thrown away; the
+formula @var{a} is then copied and evaluated as if by the @kbd{=}
+command according to all current modes and stored variable values,
+and the result is installed as the new value of @var{b}.
+
+For example, suppose you enter the algebraic formula @samp{2 + 3 => 17}.
+The number 17 is ignored, and the lefthand argument is left in its
+unevaluated form; the result is the formula @samp{2 + 3 => 5}.
+
+@kindex s =
+@pindex calc-evalto
+You can enter an @samp{=>} formula either directly using algebraic
+entry (in which case the righthand side may be omitted since it is
+going to be replaced right away anyhow), or by using the @kbd{s =}
+(@code{calc-evalto}) command, which takes @var{a} from the stack
+and replaces it with @samp{@var{a} => @var{b}}.
+
+Calc keeps track of all @samp{=>} operators on the stack, and
+recomputes them whenever anything changes that might affect their
+values, i.e., a mode setting or variable value. This occurs only
+if the @samp{=>} operator is at the top level of the formula, or
+if it is part of a top-level vector. In other words, pushing
+@samp{2 + (a => 17)} will change the 17 to the actual value of
+@samp{a} when you enter the formula, but the result will not be
+dynamically updated when @samp{a} is changed later because the
+@samp{=>} operator is buried inside a sum. However, a vector
+of @samp{=>} operators will be recomputed, since it is convenient
+to push a vector like @samp{[a =>, b =>, c =>]} on the stack to
+make a concise display of all the variables in your problem.
+(Another way to do this would be to use @samp{[a, b, c] =>},
+which provides a slightly different format of display. You
+can use whichever you find easiest to read.)
+
+@kindex m C
+@pindex calc-auto-recompute
+The @kbd{m C} (@code{calc-auto-recompute}) command allows you to
+turn this automatic recomputation on or off. If you turn
+recomputation off, you must explicitly recompute an @samp{=>}
+operator on the stack in one of the usual ways, such as by
+pressing @kbd{=}. Turning recomputation off temporarily can save
+a lot of time if you will be changing several modes or variables
+before you look at the @samp{=>} entries again.
+
+Most commands are not especially useful with @samp{=>} operators
+as arguments. For example, given @samp{x + 2 => 17}, it won't
+work to type @kbd{1 +} to get @samp{x + 3 => 18}. If you want
+to operate on the lefthand side of the @samp{=>} operator on
+the top of the stack, type @kbd{j 1} (that's the digit ``one'')
+to select the lefthand side, execute your commands, then type
+@kbd{j u} to unselect.
+
+All current modes apply when an @samp{=>} operator is computed,
+including the current simplification mode. Recall that the
+formula @samp{x + y + x} is not handled by Calc's default
+simplifications, but the @kbd{a s} command will reduce it to
+the simpler form @samp{y + 2 x}. You can also type @kbd{m A}
+to enable an Algebraic Simplification mode in which the
+equivalent of @kbd{a s} is used on all of Calc's results.
+If you enter @samp{x + y + x =>} normally, the result will
+be @samp{x + y + x => x + y + x}. If you change to
+Algebraic Simplification mode, the result will be
+@samp{x + y + x => y + 2 x}. However, just pressing @kbd{a s}
+once will have no effect on @samp{x + y + x => x + y + x},
+because the righthand side depends only on the lefthand side
+and the current mode settings, and the lefthand side is not
+affected by commands like @kbd{a s}.
+
+The ``let'' command (@kbd{s l}) has an interesting interaction
+with the @samp{=>} operator. The @kbd{s l} command evaluates the
+second-to-top stack entry with the top stack entry supplying
+a temporary value for a given variable. As you might expect,
+if that stack entry is an @samp{=>} operator its righthand
+side will temporarily show this value for the variable. In
+fact, all @samp{=>}s on the stack will be updated if they refer
+to that variable. But this change is temporary in the sense
+that the next command that causes Calc to look at those stack
+entries will make them revert to the old variable value.
+
+@smallexample
+@group
+2: a => a 2: a => 17 2: a => a
+1: a + 1 => a + 1 1: a + 1 => 18 1: a + 1 => a + 1
+ . . .
+
+ 17 s l a @key{RET} p 8 @key{RET}
+@end group
+@end smallexample
+
+Here the @kbd{p 8} command changes the current precision,
+thus causing the @samp{=>} forms to be recomputed after the
+influence of the ``let'' is gone. The @kbd{d @key{SPC}} command
+(@code{calc-refresh}) is a handy way to force the @samp{=>}
+operators on the stack to be recomputed without any other
+side effects.
+
+@kindex s :
+@pindex calc-assign
+@tindex assign
+@tindex :=
+Embedded mode also uses @samp{=>} operators. In Embedded mode,
+the lefthand side of an @samp{=>} operator can refer to variables
+assigned elsewhere in the file by @samp{:=} operators. The
+assignment operator @samp{a := 17} does not actually do anything
+by itself. But Embedded mode recognizes it and marks it as a sort
+of file-local definition of the variable. You can enter @samp{:=}
+operators in Algebraic mode, or by using the @kbd{s :}
+(@code{calc-assign}) [@code{assign}] command which takes a variable
+and value from the stack and replaces them with an assignment.
+
+@xref{TeX and LaTeX Language Modes}, for the way @samp{=>} appears in
+@TeX{} language output. The @dfn{eqn} mode gives similar
+treatment to @samp{=>}.
+
+@node Graphics, Kill and Yank, Store and Recall, Top
+@chapter Graphics
+
+@noindent
+The commands for graphing data begin with the @kbd{g} prefix key. Calc
+uses GNUPLOT 2.0 or later to do graphics. These commands will only work
+if GNUPLOT is available on your system. (While GNUPLOT sounds like
+a relative of GNU Emacs, it is actually completely unrelated.
+However, it is free software. It can be obtained from
+@samp{http://www.gnuplot.info}.)
+
+@vindex calc-gnuplot-name
+If you have GNUPLOT installed on your system but Calc is unable to
+find it, you may need to set the @code{calc-gnuplot-name} variable
+in your Calc init file or @file{.emacs}. You may also need to set some Lisp
+variables to show Calc how to run GNUPLOT on your system; these
+are described under @kbd{g D} and @kbd{g O} below. If you are
+using the X window system, Calc will configure GNUPLOT for you
+automatically. If you have GNUPLOT 3.0 or later and you are not using X,
+Calc will configure GNUPLOT to display graphs using simple character
+graphics that will work on any terminal.
+
+@menu
+* Basic Graphics::
+* Three Dimensional Graphics::
+* Managing Curves::
+* Graphics Options::
+* Devices::
+@end menu
+
+@node Basic Graphics, Three Dimensional Graphics, Graphics, Graphics
+@section Basic Graphics
+
+@noindent
+@kindex g f
+@pindex calc-graph-fast
+The easiest graphics command is @kbd{g f} (@code{calc-graph-fast}).
+This command takes two vectors of equal length from the stack.
+The vector at the top of the stack represents the ``y'' values of
+the various data points. The vector in the second-to-top position
+represents the corresponding ``x'' values. This command runs
+GNUPLOT (if it has not already been started by previous graphing
+commands) and displays the set of data points. The points will
+be connected by lines, and there will also be some kind of symbol
+to indicate the points themselves.
+
+The ``x'' entry may instead be an interval form, in which case suitable
+``x'' values are interpolated between the minimum and maximum values of
+the interval (whether the interval is open or closed is ignored).
+
+The ``x'' entry may also be a number, in which case Calc uses the
+sequence of ``x'' values @expr{x}, @expr{x+1}, @expr{x+2}, etc.
+(Generally the number 0 or 1 would be used for @expr{x} in this case.)
+
+The ``y'' entry may be any formula instead of a vector. Calc effectively
+uses @kbd{N} (@code{calc-eval-num}) to evaluate variables in the formula;
+the result of this must be a formula in a single (unassigned) variable.
+The formula is plotted with this variable taking on the various ``x''
+values. Graphs of formulas by default use lines without symbols at the
+computed data points. Note that if neither ``x'' nor ``y'' is a vector,
+Calc guesses at a reasonable number of data points to use. See the
+@kbd{g N} command below. (The ``x'' values must be either a vector
+or an interval if ``y'' is a formula.)
+
+@ignore
+@starindex
+@end ignore
+@tindex xy
+If ``y'' is (or evaluates to) a formula of the form
+@samp{xy(@var{x}, @var{y})} then the result is a
+parametric plot. The two arguments of the fictitious @code{xy} function
+are used as the ``x'' and ``y'' coordinates of the curve, respectively.
+In this case the ``x'' vector or interval you specified is not directly
+visible in the graph. For example, if ``x'' is the interval @samp{[0..360]}
+and ``y'' is the formula @samp{xy(sin(t), cos(t))}, the resulting graph
+will be a circle.
+
+Also, ``x'' and ``y'' may each be variable names, in which case Calc
+looks for suitable vectors, intervals, or formulas stored in those
+variables.
+
+The ``x'' and ``y'' values for the data points (as pulled from the vectors,
+calculated from the formulas, or interpolated from the intervals) should
+be real numbers (integers, fractions, or floats). One exception to this
+is that the ``y'' entry can consist of a vector of numbers combined with
+error forms, in which case the points will be plotted with the
+appropriate error bars. Other than this, if either the ``x''
+value or the ``y'' value of a given data point is not a real number, that
+data point will be omitted from the graph. The points on either side
+of the invalid point will @emph{not} be connected by a line.
+
+See the documentation for @kbd{g a} below for a description of the way
+numeric prefix arguments affect @kbd{g f}.
+
+@cindex @code{PlotRejects} variable
+@vindex PlotRejects
+If you store an empty vector in the variable @code{PlotRejects}
+(i.e., @kbd{[ ] s t PlotRejects}), Calc will append information to
+this vector for every data point which was rejected because its
+``x'' or ``y'' values were not real numbers. The result will be
+a matrix where each row holds the curve number, data point number,
+``x'' value, and ``y'' value for a rejected data point.
+@xref{Evaluates-To Operator}, for a handy way to keep tabs on the
+current value of @code{PlotRejects}. @xref{Operations on Variables},
+for the @kbd{s R} command which is another easy way to examine
+@code{PlotRejects}.
+
+@kindex g c
+@pindex calc-graph-clear
+To clear the graphics display, type @kbd{g c} (@code{calc-graph-clear}).
+If the GNUPLOT output device is an X window, the window will go away.
+Effects on other kinds of output devices will vary. You don't need
+to use @kbd{g c} if you don't want to---if you give another @kbd{g f}
+or @kbd{g p} command later on, it will reuse the existing graphics
+window if there is one.
+
+@node Three Dimensional Graphics, Managing Curves, Basic Graphics, Graphics
+@section Three-Dimensional Graphics
+
+@kindex g F
+@pindex calc-graph-fast-3d
+The @kbd{g F} (@code{calc-graph-fast-3d}) command makes a three-dimensional
+graph. It works only if you have GNUPLOT 3.0 or later; with GNUPLOT 2.0,
+you will see a GNUPLOT error message if you try this command.
+
+The @kbd{g F} command takes three values from the stack, called ``x'',
+``y'', and ``z'', respectively. As was the case for 2D graphs, there
+are several options for these values.
+
+In the first case, ``x'' and ``y'' are each vectors (not necessarily of
+the same length); either or both may instead be interval forms. The
+``z'' value must be a matrix with the same number of rows as elements
+in ``x'', and the same number of columns as elements in ``y''. The
+result is a surface plot where
+@texline @math{z_{ij}}
+@infoline @expr{z_ij}
+is the height of the point
+at coordinate @expr{(x_i, y_j)} on the surface. The 3D graph will
+be displayed from a certain default viewpoint; you can change this
+viewpoint by adding a @samp{set view} to the @samp{*Gnuplot Commands*}
+buffer as described later. See the GNUPLOT documentation for a
+description of the @samp{set view} command.
+
+Each point in the matrix will be displayed as a dot in the graph,
+and these points will be connected by a grid of lines (@dfn{isolines}).
+
+In the second case, ``x'', ``y'', and ``z'' are all vectors of equal
+length. The resulting graph displays a 3D line instead of a surface,
+where the coordinates of points along the line are successive triplets
+of values from the input vectors.
+
+In the third case, ``x'' and ``y'' are vectors or interval forms, and
+``z'' is any formula involving two variables (not counting variables
+with assigned values). These variables are sorted into alphabetical
+order; the first takes on values from ``x'' and the second takes on
+values from ``y'' to form a matrix of results that are graphed as a
+3D surface.
+
+@ignore
+@starindex
+@end ignore
+@tindex xyz
+If the ``z'' formula evaluates to a call to the fictitious function
+@samp{xyz(@var{x}, @var{y}, @var{z})}, then the result is a
+``parametric surface.'' In this case, the axes of the graph are
+taken from the @var{x} and @var{y} values in these calls, and the
+``x'' and ``y'' values from the input vectors or intervals are used only
+to specify the range of inputs to the formula. For example, plotting
+@samp{[0..360], [0..180], xyz(sin(x)*sin(y), cos(x)*sin(y), cos(y))}
+will draw a sphere. (Since the default resolution for 3D plots is
+5 steps in each of ``x'' and ``y'', this will draw a very crude
+sphere. You could use the @kbd{g N} command, described below, to
+increase this resolution, or specify the ``x'' and ``y'' values as
+vectors with more than 5 elements.
+
+It is also possible to have a function in a regular @kbd{g f} plot
+evaluate to an @code{xyz} call. Since @kbd{g f} plots a line, not
+a surface, the result will be a 3D parametric line. For example,
+@samp{[[0..720], xyz(sin(x), cos(x), x)]} will plot two turns of a
+helix (a three-dimensional spiral).
+
+As for @kbd{g f}, each of ``x'', ``y'', and ``z'' may instead be
+variables containing the relevant data.
+
+@node Managing Curves, Graphics Options, Three Dimensional Graphics, Graphics
+@section Managing Curves
+
+@noindent
+The @kbd{g f} command is really shorthand for the following commands:
+@kbd{C-u g d g a g p}. Likewise, @w{@kbd{g F}} is shorthand for
+@kbd{C-u g d g A g p}. You can gain more control over your graph
+by using these commands directly.
+
+@kindex g a
+@pindex calc-graph-add
+The @kbd{g a} (@code{calc-graph-add}) command adds the ``curve''
+represented by the two values on the top of the stack to the current
+graph. You can have any number of curves in the same graph. When
+you give the @kbd{g p} command, all the curves will be drawn superimposed
+on the same axes.
+
+The @kbd{g a} command (and many others that affect the current graph)
+will cause a special buffer, @samp{*Gnuplot Commands*}, to be displayed
+in another window. This buffer is a template of the commands that will
+be sent to GNUPLOT when it is time to draw the graph. The first
+@kbd{g a} command adds a @code{plot} command to this buffer. Succeeding
+@kbd{g a} commands add extra curves onto that @code{plot} command.
+Other graph-related commands put other GNUPLOT commands into this
+buffer. In normal usage you never need to work with this buffer
+directly, but you can if you wish. The only constraint is that there
+must be only one @code{plot} command, and it must be the last command
+in the buffer. If you want to save and later restore a complete graph
+configuration, you can use regular Emacs commands to save and restore
+the contents of the @samp{*Gnuplot Commands*} buffer.
+
+@vindex PlotData1
+@vindex PlotData2
+If the values on the stack are not variable names, @kbd{g a} will invent
+variable names for them (of the form @samp{PlotData@var{n}}) and store
+the values in those variables. The ``x'' and ``y'' variables are what
+go into the @code{plot} command in the template. If you add a curve
+that uses a certain variable and then later change that variable, you
+can replot the graph without having to delete and re-add the curve.
+That's because the variable name, not the vector, interval or formula
+itself, is what was added by @kbd{g a}.
+
+A numeric prefix argument on @kbd{g a} or @kbd{g f} changes the way
+stack entries are interpreted as curves. With a positive prefix
+argument @expr{n}, the top @expr{n} stack entries are ``y'' values
+for @expr{n} different curves which share a common ``x'' value in
+the @expr{n+1}st stack entry. (Thus @kbd{g a} with no prefix
+argument is equivalent to @kbd{C-u 1 g a}.)
+
+A prefix of zero or plain @kbd{C-u} means to take two stack entries,
+``x'' and ``y'' as usual, but to interpret ``y'' as a vector of
+``y'' values for several curves that share a common ``x''.
+
+A negative prefix argument tells Calc to read @expr{n} vectors from
+the stack; each vector @expr{[x, y]} describes an independent curve.
+This is the only form of @kbd{g a} that creates several curves at once
+that don't have common ``x'' values. (Of course, the range of ``x''
+values covered by all the curves ought to be roughly the same if
+they are to look nice on the same graph.)
+
+For example, to plot
+@texline @math{\sin n x}
+@infoline @expr{sin(n x)}
+for integers @expr{n}
+from 1 to 5, you could use @kbd{v x} to create a vector of integers
+(@expr{n}), then @kbd{V M '} or @kbd{V M $} to map @samp{sin(n x)}
+across this vector. The resulting vector of formulas is suitable
+for use as the ``y'' argument to a @kbd{C-u g a} or @kbd{C-u g f}
+command.
+
+@kindex g A
+@pindex calc-graph-add-3d
+The @kbd{g A} (@code{calc-graph-add-3d}) command adds a 3D curve
+to the graph. It is not valid to intermix 2D and 3D curves in a
+single graph. This command takes three arguments, ``x'', ``y'',
+and ``z'', from the stack. With a positive prefix @expr{n}, it
+takes @expr{n+2} arguments (common ``x'' and ``y'', plus @expr{n}
+separate ``z''s). With a zero prefix, it takes three stack entries
+but the ``z'' entry is a vector of curve values. With a negative
+prefix @expr{-n}, it takes @expr{n} vectors of the form @expr{[x, y, z]}.
+The @kbd{g A} command works by adding a @code{splot} (surface-plot)
+command to the @samp{*Gnuplot Commands*} buffer.
+
+(Although @kbd{g a} adds a 2D @code{plot} command to the
+@samp{*Gnuplot Commands*} buffer, Calc changes this to @code{splot}
+before sending it to GNUPLOT if it notices that the data points are
+evaluating to @code{xyz} calls. It will not work to mix 2D and 3D
+@kbd{g a} curves in a single graph, although Calc does not currently
+check for this.)
+
+@kindex g d
+@pindex calc-graph-delete
+The @kbd{g d} (@code{calc-graph-delete}) command deletes the most
+recently added curve from the graph. It has no effect if there are
+no curves in the graph. With a numeric prefix argument of any kind,
+it deletes all of the curves from the graph.
+
+@kindex g H
+@pindex calc-graph-hide
+The @kbd{g H} (@code{calc-graph-hide}) command ``hides'' or ``unhides''
+the most recently added curve. A hidden curve will not appear in
+the actual plot, but information about it such as its name and line and
+point styles will be retained.
+
+@kindex g j
+@pindex calc-graph-juggle
+The @kbd{g j} (@code{calc-graph-juggle}) command moves the curve
+at the end of the list (the ``most recently added curve'') to the
+front of the list. The next-most-recent curve is thus exposed for
+@w{@kbd{g d}} or similar commands to use. With @kbd{g j} you can work
+with any curve in the graph even though curve-related commands only
+affect the last curve in the list.
+
+@kindex g p
+@pindex calc-graph-plot
+The @kbd{g p} (@code{calc-graph-plot}) command uses GNUPLOT to draw
+the graph described in the @samp{*Gnuplot Commands*} buffer. Any
+GNUPLOT parameters which are not defined by commands in this buffer
+are reset to their default values. The variables named in the @code{plot}
+command are written to a temporary data file and the variable names
+are then replaced by the file name in the template. The resulting
+plotting commands are fed to the GNUPLOT program. See the documentation
+for the GNUPLOT program for more specific information. All temporary
+files are removed when Emacs or GNUPLOT exits.
+
+If you give a formula for ``y'', Calc will remember all the values that
+it calculates for the formula so that later plots can reuse these values.
+Calc throws out these saved values when you change any circumstances
+that may affect the data, such as switching from Degrees to Radians
+mode, or changing the value of a parameter in the formula. You can
+force Calc to recompute the data from scratch by giving a negative
+numeric prefix argument to @kbd{g p}.
+
+Calc uses a fairly rough step size when graphing formulas over intervals.
+This is to ensure quick response. You can ``refine'' a plot by giving
+a positive numeric prefix argument to @kbd{g p}. Calc goes through
+the data points it has computed and saved from previous plots of the
+function, and computes and inserts a new data point midway between
+each of the existing points. You can refine a plot any number of times,
+but beware that the amount of calculation involved doubles each time.
+
+Calc does not remember computed values for 3D graphs. This means the
+numerix prefix argument, if any, to @kbd{g p} is effectively ignored if
+the current graph is three-dimensional.
+
+@kindex g P
+@pindex calc-graph-print
+The @kbd{g P} (@code{calc-graph-print}) command is like @kbd{g p},
+except that it sends the output to a printer instead of to the
+screen. More precisely, @kbd{g p} looks for @samp{set terminal}
+or @samp{set output} commands in the @samp{*Gnuplot Commands*} buffer;
+lacking these it uses the default settings. However, @kbd{g P}
+ignores @samp{set terminal} and @samp{set output} commands and
+uses a different set of default values. All of these values are
+controlled by the @kbd{g D} and @kbd{g O} commands discussed below.
+Provided everything is set up properly, @kbd{g p} will plot to
+the screen unless you have specified otherwise and @kbd{g P} will
+always plot to the printer.
+
+@node Graphics Options, Devices, Managing Curves, Graphics
+@section Graphics Options
+
+@noindent
+@kindex g g
+@pindex calc-graph-grid
+The @kbd{g g} (@code{calc-graph-grid}) command turns the ``grid''
+on and off. It is off by default; tick marks appear only at the
+edges of the graph. With the grid turned on, dotted lines appear
+across the graph at each tick mark. Note that this command only
+changes the setting in @samp{*Gnuplot Commands*}; to see the effects
+of the change you must give another @kbd{g p} command.
+
+@kindex g b
+@pindex calc-graph-border
+The @kbd{g b} (@code{calc-graph-border}) command turns the border
+(the box that surrounds the graph) on and off. It is on by default.
+This command will only work with GNUPLOT 3.0 and later versions.
+
+@kindex g k
+@pindex calc-graph-key
+The @kbd{g k} (@code{calc-graph-key}) command turns the ``key''
+on and off. The key is a chart in the corner of the graph that
+shows the correspondence between curves and line styles. It is
+off by default, and is only really useful if you have several
+curves on the same graph.
+
+@kindex g N
+@pindex calc-graph-num-points
+The @kbd{g N} (@code{calc-graph-num-points}) command allows you
+to select the number of data points in the graph. This only affects
+curves where neither ``x'' nor ``y'' is specified as a vector.
+Enter a blank line to revert to the default value (initially 15).
+With no prefix argument, this command affects only the current graph.
+With a positive prefix argument this command changes or, if you enter
+a blank line, displays the default number of points used for all
+graphs created by @kbd{g a} that don't specify the resolution explicitly.
+With a negative prefix argument, this command changes or displays
+the default value (initially 5) used for 3D graphs created by @kbd{g A}.
+Note that a 3D setting of 5 means that a total of @expr{5^2 = 25} points
+will be computed for the surface.
+
+Data values in the graph of a function are normally computed to a
+precision of five digits, regardless of the current precision at the
+time. This is usually more than adequate, but there are cases where
+it will not be. For example, plotting @expr{1 + x} with @expr{x} in the
+interval @samp{[0 ..@: 1e-6]} will round all the data points down
+to 1.0! Putting the command @samp{set precision @var{n}} in the
+@samp{*Gnuplot Commands*} buffer will cause the data to be computed
+at precision @var{n} instead of 5. Since this is such a rare case,
+there is no keystroke-based command to set the precision.
+
+@kindex g h
+@pindex calc-graph-header
+The @kbd{g h} (@code{calc-graph-header}) command sets the title
+for the graph. This will show up centered above the graph.
+The default title is blank (no title).
+
+@kindex g n
+@pindex calc-graph-name
+The @kbd{g n} (@code{calc-graph-name}) command sets the title of an
+individual curve. Like the other curve-manipulating commands, it
+affects the most recently added curve, i.e., the last curve on the
+list in the @samp{*Gnuplot Commands*} buffer. To set the title of
+the other curves you must first juggle them to the end of the list
+with @kbd{g j}, or edit the @samp{*Gnuplot Commands*} buffer by hand.
+Curve titles appear in the key; if the key is turned off they are
+not used.
+
+@kindex g t
+@kindex g T
+@pindex calc-graph-title-x
+@pindex calc-graph-title-y
+The @kbd{g t} (@code{calc-graph-title-x}) and @kbd{g T}
+(@code{calc-graph-title-y}) commands set the titles on the ``x''
+and ``y'' axes, respectively. These titles appear next to the
+tick marks on the left and bottom edges of the graph, respectively.
+Calc does not have commands to control the tick marks themselves,
+but you can edit them into the @samp{*Gnuplot Commands*} buffer if
+you wish. See the GNUPLOT documentation for details.
+
+@kindex g r
+@kindex g R
+@pindex calc-graph-range-x
+@pindex calc-graph-range-y
+The @kbd{g r} (@code{calc-graph-range-x}) and @kbd{g R}
+(@code{calc-graph-range-y}) commands set the range of values on the
+``x'' and ``y'' axes, respectively. You are prompted to enter a
+suitable range. This should be either a pair of numbers of the
+form, @samp{@var{min}:@var{max}}, or a blank line to revert to the
+default behavior of setting the range based on the range of values
+in the data, or @samp{$} to take the range from the top of the stack.
+Ranges on the stack can be represented as either interval forms or
+vectors: @samp{[@var{min} ..@: @var{max}]} or @samp{[@var{min}, @var{max}]}.
+
+@kindex g l
+@kindex g L
+@pindex calc-graph-log-x
+@pindex calc-graph-log-y
+The @kbd{g l} (@code{calc-graph-log-x}) and @kbd{g L} (@code{calc-graph-log-y})
+commands allow you to set either or both of the axes of the graph to
+be logarithmic instead of linear.
+
+@kindex g C-l
+@kindex g C-r
+@kindex g C-t
+@pindex calc-graph-log-z
+@pindex calc-graph-range-z
+@pindex calc-graph-title-z
+For 3D plots, @kbd{g C-t}, @kbd{g C-r}, and @kbd{g C-l} (those are
+letters with the Control key held down) are the corresponding commands
+for the ``z'' axis.
+
+@kindex g z
+@kindex g Z
+@pindex calc-graph-zero-x
+@pindex calc-graph-zero-y
+The @kbd{g z} (@code{calc-graph-zero-x}) and @kbd{g Z}
+(@code{calc-graph-zero-y}) commands control whether a dotted line is
+drawn to indicate the ``x'' and/or ``y'' zero axes. (These are the same
+dotted lines that would be drawn there anyway if you used @kbd{g g} to
+turn the ``grid'' feature on.) Zero-axis lines are on by default, and
+may be turned off only in GNUPLOT 3.0 and later versions. They are
+not available for 3D plots.
+
+@kindex g s
+@pindex calc-graph-line-style
+The @kbd{g s} (@code{calc-graph-line-style}) command turns the connecting
+lines on or off for the most recently added curve, and optionally selects
+the style of lines to be used for that curve. Plain @kbd{g s} simply
+toggles the lines on and off. With a numeric prefix argument, @kbd{g s}
+turns lines on and sets a particular line style. Line style numbers
+start at one and their meanings vary depending on the output device.
+GNUPLOT guarantees that there will be at least six different line styles
+available for any device.
+
+@kindex g S
+@pindex calc-graph-point-style
+The @kbd{g S} (@code{calc-graph-point-style}) command similarly turns
+the symbols at the data points on or off, or sets the point style.
+If you turn both lines and points off, the data points will show as
+tiny dots. If the ``y'' values being plotted contain error forms and
+the connecting lines are turned off, then this command will also turn
+the error bars on or off.
+
+@cindex @code{LineStyles} variable
+@cindex @code{PointStyles} variable
+@vindex LineStyles
+@vindex PointStyles
+Another way to specify curve styles is with the @code{LineStyles} and
+@code{PointStyles} variables. These variables initially have no stored
+values, but if you store a vector of integers in one of these variables,
+the @kbd{g a} and @kbd{g f} commands will use those style numbers
+instead of the defaults for new curves that are added to the graph.
+An entry should be a positive integer for a specific style, or 0 to let
+the style be chosen automatically, or @mathit{-1} to turn off lines or points
+altogether. If there are more curves than elements in the vector, the
+last few curves will continue to have the default styles. Of course,
+you can later use @kbd{g s} and @kbd{g S} to change any of these styles.
+
+For example, @kbd{'[2 -1 3] @key{RET} s t LineStyles} causes the first curve
+to have lines in style number 2, the second curve to have no connecting
+lines, and the third curve to have lines in style 3. Point styles will
+still be assigned automatically, but you could store another vector in
+@code{PointStyles} to define them, too.
+
+@node Devices, , Graphics Options, Graphics
+@section Graphical Devices
+
+@noindent
+@kindex g D
+@pindex calc-graph-device
+The @kbd{g D} (@code{calc-graph-device}) command sets the device name
+(or ``terminal name'' in GNUPLOT lingo) to be used by @kbd{g p} commands
+on this graph. It does not affect the permanent default device name.
+If you enter a blank name, the device name reverts to the default.
+Enter @samp{?} to see a list of supported devices.
+
+With a positive numeric prefix argument, @kbd{g D} instead sets
+the default device name, used by all plots in the future which do
+not override it with a plain @kbd{g D} command. If you enter a
+blank line this command shows you the current default. The special
+name @code{default} signifies that Calc should choose @code{x11} if
+the X window system is in use (as indicated by the presence of a
+@code{DISPLAY} environment variable), or otherwise @code{dumb} under
+GNUPLOT 3.0 and later, or @code{postscript} under GNUPLOT 2.0.
+This is the initial default value.
+
+The @code{dumb} device is an interface to ``dumb terminals,'' i.e.,
+terminals with no special graphics facilities. It writes a crude
+picture of the graph composed of characters like @code{-} and @code{|}
+to a buffer called @samp{*Gnuplot Trail*}, which Calc then displays.
+The graph is made the same size as the Emacs screen, which on most
+dumb terminals will be
+@texline @math{80\times24}
+@infoline 80x24
+characters. The graph is displayed in
+an Emacs ``recursive edit''; type @kbd{q} or @kbd{C-c C-c} to exit
+the recursive edit and return to Calc. Note that the @code{dumb}
+device is present only in GNUPLOT 3.0 and later versions.
+
+The word @code{dumb} may be followed by two numbers separated by
+spaces. These are the desired width and height of the graph in
+characters. Also, the device name @code{big} is like @code{dumb}
+but creates a graph four times the width and height of the Emacs
+screen. You will then have to scroll around to view the entire
+graph. In the @samp{*Gnuplot Trail*} buffer, @key{SPC}, @key{DEL},
+@kbd{<}, and @kbd{>} are defined to scroll by one screenful in each
+of the four directions.
+
+With a negative numeric prefix argument, @kbd{g D} sets or displays
+the device name used by @kbd{g P} (@code{calc-graph-print}). This
+is initially @code{postscript}. If you don't have a PostScript
+printer, you may decide once again to use @code{dumb} to create a
+plot on any text-only printer.
+
+@kindex g O
+@pindex calc-graph-output
+The @kbd{g O} (@code{calc-graph-output}) command sets the name of
+the output file used by GNUPLOT. For some devices, notably @code{x11},
+there is no output file and this information is not used. Many other
+``devices'' are really file formats like @code{postscript}; in these
+cases the output in the desired format goes into the file you name
+with @kbd{g O}. Type @kbd{g O stdout @key{RET}} to set GNUPLOT to write
+to its standard output stream, i.e., to @samp{*Gnuplot Trail*}.
+This is the default setting.
+
+Another special output name is @code{tty}, which means that GNUPLOT
+is going to write graphics commands directly to its standard output,
+which you wish Emacs to pass through to your terminal. Tektronix
+graphics terminals, among other devices, operate this way. Calc does
+this by telling GNUPLOT to write to a temporary file, then running a
+sub-shell executing the command @samp{cat tempfile >/dev/tty}. On
+typical Unix systems, this will copy the temporary file directly to
+the terminal, bypassing Emacs entirely. You will have to type @kbd{C-l}
+to Emacs afterwards to refresh the screen.
+
+Once again, @kbd{g O} with a positive or negative prefix argument
+sets the default or printer output file names, respectively. In each
+case you can specify @code{auto}, which causes Calc to invent a temporary
+file name for each @kbd{g p} (or @kbd{g P}) command. This temporary file
+will be deleted once it has been displayed or printed. If the output file
+name is not @code{auto}, the file is not automatically deleted.
+
+The default and printer devices and output files can be saved
+permanently by the @kbd{m m} (@code{calc-save-modes}) command. The
+default number of data points (see @kbd{g N}) and the X geometry
+(see @kbd{g X}) are also saved. Other graph information is @emph{not}
+saved; you can save a graph's configuration simply by saving the contents
+of the @samp{*Gnuplot Commands*} buffer.
+
+@vindex calc-gnuplot-plot-command
+@vindex calc-gnuplot-default-device
+@vindex calc-gnuplot-default-output
+@vindex calc-gnuplot-print-command
+@vindex calc-gnuplot-print-device
+@vindex calc-gnuplot-print-output
+You may wish to configure the default and
+printer devices and output files for the whole system. The relevant
+Lisp variables are @code{calc-gnuplot-default-device} and @code{-output},
+and @code{calc-gnuplot-print-device} and @code{-output}. The output
+file names must be either strings as described above, or Lisp
+expressions which are evaluated on the fly to get the output file names.
+
+Other important Lisp variables are @code{calc-gnuplot-plot-command} and
+@code{calc-gnuplot-print-command}, which give the system commands to
+display or print the output of GNUPLOT, respectively. These may be
+@code{nil} if no command is necessary, or strings which can include
+@samp{%s} to signify the name of the file to be displayed or printed.
+Or, these variables may contain Lisp expressions which are evaluated
+to display or print the output. These variables are customizable
+(@pxref{Customizing Calc}).
+
+@kindex g x
+@pindex calc-graph-display
+The @kbd{g x} (@code{calc-graph-display}) command lets you specify
+on which X window system display your graphs should be drawn. Enter
+a blank line to see the current display name. This command has no
+effect unless the current device is @code{x11}.
+
+@kindex g X
+@pindex calc-graph-geometry
+The @kbd{g X} (@code{calc-graph-geometry}) command is a similar
+command for specifying the position and size of the X window.
+The normal value is @code{default}, which generally means your
+window manager will let you place the window interactively.
+Entering @samp{800x500+0+0} would create an 800-by-500 pixel
+window in the upper-left corner of the screen.
+
+The buffer called @samp{*Gnuplot Trail*} holds a transcript of the
+session with GNUPLOT. This shows the commands Calc has ``typed'' to
+GNUPLOT and the responses it has received. Calc tries to notice when an
+error message has appeared here and display the buffer for you when
+this happens. You can check this buffer yourself if you suspect
+something has gone wrong.
+
+@kindex g C
+@pindex calc-graph-command
+The @kbd{g C} (@code{calc-graph-command}) command prompts you to
+enter any line of text, then simply sends that line to the current
+GNUPLOT process. The @samp{*Gnuplot Trail*} buffer looks deceptively
+like a Shell buffer but you can't type commands in it yourself.
+Instead, you must use @kbd{g C} for this purpose.
+
+@kindex g v
+@kindex g V
+@pindex calc-graph-view-commands
+@pindex calc-graph-view-trail
+The @kbd{g v} (@code{calc-graph-view-commands}) and @kbd{g V}
+(@code{calc-graph-view-trail}) commands display the @samp{*Gnuplot Commands*}
+and @samp{*Gnuplot Trail*} buffers, respectively, in another window.
+This happens automatically when Calc thinks there is something you
+will want to see in either of these buffers. If you type @kbd{g v}
+or @kbd{g V} when the relevant buffer is already displayed, the
+buffer is hidden again.
+
+One reason to use @kbd{g v} is to add your own commands to the
+@samp{*Gnuplot Commands*} buffer. Press @kbd{g v}, then use
+@kbd{C-x o} to switch into that window. For example, GNUPLOT has
+@samp{set label} and @samp{set arrow} commands that allow you to
+annotate your plots. Since Calc doesn't understand these commands,
+you have to add them to the @samp{*Gnuplot Commands*} buffer
+yourself, then use @w{@kbd{g p}} to replot using these new commands. Note
+that your commands must appear @emph{before} the @code{plot} command.
+To get help on any GNUPLOT feature, type, e.g., @kbd{g C help set label}.
+You may have to type @kbd{g C @key{RET}} a few times to clear the
+``press return for more'' or ``subtopic of @dots{}'' requests.
+Note that Calc always sends commands (like @samp{set nolabel}) to
+reset all plotting parameters to the defaults before each plot, so
+to delete a label all you need to do is delete the @samp{set label}
+line you added (or comment it out with @samp{#}) and then replot
+with @kbd{g p}.
+
+@kindex g q
+@pindex calc-graph-quit
+You can use @kbd{g q} (@code{calc-graph-quit}) to kill the GNUPLOT
+process that is running. The next graphing command you give will
+start a fresh GNUPLOT process. The word @samp{Graph} appears in
+the Calc window's mode line whenever a GNUPLOT process is currently
+running. The GNUPLOT process is automatically killed when you
+exit Emacs if you haven't killed it manually by then.
+
+@kindex g K
+@pindex calc-graph-kill
+The @kbd{g K} (@code{calc-graph-kill}) command is like @kbd{g q}
+except that it also views the @samp{*Gnuplot Trail*} buffer so that
+you can see the process being killed. This is better if you are
+killing GNUPLOT because you think it has gotten stuck.
+
+@node Kill and Yank, Keypad Mode, Graphics, Top
+@chapter Kill and Yank Functions
+
+@noindent
+The commands in this chapter move information between the Calculator and
+other Emacs editing buffers.
+
+In many cases Embedded mode is an easier and more natural way to
+work with Calc from a regular editing buffer. @xref{Embedded Mode}.
+
+@menu
+* Killing From Stack::
+* Yanking Into Stack::
+* Grabbing From Buffers::
+* Yanking Into Buffers::
+* X Cut and Paste::
+@end menu
+
+@node Killing From Stack, Yanking Into Stack, Kill and Yank, Kill and Yank
+@section Killing from the Stack
+
+@noindent
+@kindex C-k
+@pindex calc-kill
+@kindex M-k
+@pindex calc-copy-as-kill
+@kindex C-w
+@pindex calc-kill-region
+@kindex M-w
+@pindex calc-copy-region-as-kill
+@cindex Kill ring
+@dfn{Kill} commands are Emacs commands that insert text into the
+``kill ring,'' from which it can later be ``yanked'' by a @kbd{C-y}
+command. Three common kill commands in normal Emacs are @kbd{C-k}, which
+kills one line, @kbd{C-w}, which kills the region between mark and point,
+and @kbd{M-w}, which puts the region into the kill ring without actually
+deleting it. All of these commands work in the Calculator, too. Also,
+@kbd{M-k} has been provided to complete the set; it puts the current line
+into the kill ring without deleting anything.
+
+The kill commands are unusual in that they pay attention to the location
+of the cursor in the Calculator buffer. If the cursor is on or below the
+bottom line, the kill commands operate on the top of the stack. Otherwise,
+they operate on whatever stack element the cursor is on. Calc's kill
+commands always operate on whole stack entries. (They act the same as their
+standard Emacs cousins except they ``round up'' the specified region to
+encompass full lines.) The text is copied into the kill ring exactly as
+it appears on the screen, including line numbers if they are enabled.
+
+A numeric prefix argument to @kbd{C-k} or @kbd{M-k} affects the number
+of lines killed. A positive argument kills the current line and @expr{n-1}
+lines below it. A negative argument kills the @expr{-n} lines above the
+current line. Again this mirrors the behavior of the standard Emacs
+@kbd{C-k} command. Although a whole line is always deleted, @kbd{C-k}
+with no argument copies only the number itself into the kill ring, whereas
+@kbd{C-k} with a prefix argument of 1 copies the number with its trailing
+newline.
+
+@node Yanking Into Stack, Grabbing From Buffers, Killing From Stack, Kill and Yank
+@section Yanking into the Stack
+
+@noindent
+@kindex C-y
+@pindex calc-yank
+The @kbd{C-y} command yanks the most recently killed text back into the
+Calculator. It pushes this value onto the top of the stack regardless of
+the cursor position. In general it re-parses the killed text as a number
+or formula (or a list of these separated by commas or newlines). However if
+the thing being yanked is something that was just killed from the Calculator
+itself, its full internal structure is yanked. For example, if you have
+set the floating-point display mode to show only four significant digits,
+then killing and re-yanking 3.14159 (which displays as 3.142) will yank the
+full 3.14159, even though yanking it into any other buffer would yank the
+number in its displayed form, 3.142. (Since the default display modes
+show all objects to their full precision, this feature normally makes no
+difference.)
+
+@node Grabbing From Buffers, Yanking Into Buffers, Yanking Into Stack, Kill and Yank
+@section Grabbing from Other Buffers
+
+@noindent
+@kindex C-x * g
+@pindex calc-grab-region
+The @kbd{C-x * g} (@code{calc-grab-region}) command takes the text between
+point and mark in the current buffer and attempts to parse it as a
+vector of values. Basically, it wraps the text in vector brackets
+@samp{[ ]} unless the text already is enclosed in vector brackets,
+then reads the text as if it were an algebraic entry. The contents
+of the vector may be numbers, formulas, or any other Calc objects.
+If the @kbd{C-x * g} command works successfully, it does an automatic
+@kbd{C-x * c} to enter the Calculator buffer.
+
+A numeric prefix argument grabs the specified number of lines around
+point, ignoring the mark. A positive prefix grabs from point to the
+@expr{n}th following newline (so that @kbd{M-1 C-x * g} grabs from point
+to the end of the current line); a negative prefix grabs from point
+back to the @expr{n+1}st preceding newline. In these cases the text
+that is grabbed is exactly the same as the text that @kbd{C-k} would
+delete given that prefix argument.
+
+A prefix of zero grabs the current line; point may be anywhere on the
+line.
+
+A plain @kbd{C-u} prefix interprets the region between point and mark
+as a single number or formula rather than a vector. For example,
+@kbd{C-x * g} on the text @samp{2 a b} produces the vector of three
+values @samp{[2, a, b]}, but @kbd{C-u C-x * g} on the same region
+reads a formula which is a product of three things: @samp{2 a b}.
+(The text @samp{a + b}, on the other hand, will be grabbed as a
+vector of one element by plain @kbd{C-x * g} because the interpretation
+@samp{[a, +, b]} would be a syntax error.)
+
+If a different language has been specified (@pxref{Language Modes}),
+the grabbed text will be interpreted according to that language.
+
+@kindex C-x * r
+@pindex calc-grab-rectangle
+The @kbd{C-x * r} (@code{calc-grab-rectangle}) command takes the text between
+point and mark and attempts to parse it as a matrix. If point and mark
+are both in the leftmost column, the lines in between are parsed in their
+entirety. Otherwise, point and mark define the corners of a rectangle
+whose contents are parsed.
+
+Each line of the grabbed area becomes a row of the matrix. The result
+will actually be a vector of vectors, which Calc will treat as a matrix
+only if every row contains the same number of values.
+
+If a line contains a portion surrounded by square brackets (or curly
+braces), that portion is interpreted as a vector which becomes a row
+of the matrix. Any text surrounding the bracketed portion on the line
+is ignored.
+
+Otherwise, the entire line is interpreted as a row vector as if it
+were surrounded by square brackets. Leading line numbers (in the
+format used in the Calc stack buffer) are ignored. If you wish to
+force this interpretation (even if the line contains bracketed
+portions), give a negative numeric prefix argument to the
+@kbd{C-x * r} command.
+
+If you give a numeric prefix argument of zero or plain @kbd{C-u}, each
+line is instead interpreted as a single formula which is converted into
+a one-element vector. Thus the result of @kbd{C-u C-x * r} will be a
+one-column matrix. For example, suppose one line of the data is the
+expression @samp{2 a}. A plain @w{@kbd{C-x * r}} will interpret this as
+@samp{[2 a]}, which in turn is read as a two-element vector that forms
+one row of the matrix. But a @kbd{C-u C-x * r} will interpret this row
+as @samp{[2*a]}.
+
+If you give a positive numeric prefix argument @var{n}, then each line
+will be split up into columns of width @var{n}; each column is parsed
+separately as a matrix element. If a line contained
+@w{@samp{2 +/- 3 4 +/- 5}}, then grabbing with a prefix argument of 8
+would correctly split the line into two error forms.
+
+@xref{Matrix Functions}, to see how to pull the matrix apart into its
+constituent rows and columns. (If it is a
+@texline @math{1\times1}
+@infoline 1x1
+matrix, just hit @kbd{v u} (@code{calc-unpack}) twice.)
+
+@kindex C-x * :
+@kindex C-x * _
+@pindex calc-grab-sum-across
+@pindex calc-grab-sum-down
+@cindex Summing rows and columns of data
+The @kbd{C-x * :} (@code{calc-grab-sum-down}) command is a handy way to
+grab a rectangle of data and sum its columns. It is equivalent to
+typing @kbd{C-x * r}, followed by @kbd{V R : +} (the vector reduction
+command that sums the columns of a matrix; @pxref{Reducing}). The
+result of the command will be a vector of numbers, one for each column
+in the input data. The @kbd{C-x * _} (@code{calc-grab-sum-across}) command
+similarly grabs a rectangle and sums its rows by executing @w{@kbd{V R _ +}}.
+
+As well as being more convenient, @kbd{C-x * :} and @kbd{C-x * _} are also
+much faster because they don't actually place the grabbed vector on
+the stack. In a @kbd{C-x * r V R : +} sequence, formatting the vector
+for display on the stack takes a large fraction of the total time
+(unless you have planned ahead and used @kbd{v .} and @kbd{t .} modes).
+
+For example, suppose we have a column of numbers in a file which we
+wish to sum. Go to one corner of the column and press @kbd{C-@@} to
+set the mark; go to the other corner and type @kbd{C-x * :}. Since there
+is only one column, the result will be a vector of one number, the sum.
+(You can type @kbd{v u} to unpack this vector into a plain number if
+you want to do further arithmetic with it.)
+
+To compute the product of the column of numbers, we would have to do
+it ``by hand'' since there's no special grab-and-multiply command.
+Use @kbd{C-x * r} to grab the column of numbers into the calculator in
+the form of a column matrix. The statistics command @kbd{u *} is a
+handy way to find the product of a vector or matrix of numbers.
+@xref{Statistical Operations}. Another approach would be to use
+an explicit column reduction command, @kbd{V R : *}.
+
+@node Yanking Into Buffers, X Cut and Paste, Grabbing From Buffers, Kill and Yank
+@section Yanking into Other Buffers
+
+@noindent
+@kindex y
+@pindex calc-copy-to-buffer
+The plain @kbd{y} (@code{calc-copy-to-buffer}) command inserts the number
+at the top of the stack into the most recently used normal editing buffer.
+(More specifically, this is the most recently used buffer which is displayed
+in a window and whose name does not begin with @samp{*}. If there is no
+such buffer, this is the most recently used buffer except for Calculator
+and Calc Trail buffers.) The number is inserted exactly as it appears and
+without a newline. (If line-numbering is enabled, the line number is
+normally not included.) The number is @emph{not} removed from the stack.
+
+With a prefix argument, @kbd{y} inserts several numbers, one per line.
+A positive argument inserts the specified number of values from the top
+of the stack. A negative argument inserts the @expr{n}th value from the
+top of the stack. An argument of zero inserts the entire stack. Note
+that @kbd{y} with an argument of 1 is slightly different from @kbd{y}
+with no argument; the former always copies full lines, whereas the
+latter strips off the trailing newline.
+
+With a lone @kbd{C-u} as a prefix argument, @kbd{y} @emph{replaces} the
+region in the other buffer with the yanked text, then quits the
+Calculator, leaving you in that buffer. A typical use would be to use
+@kbd{C-x * g} to read a region of data into the Calculator, operate on the
+data to produce a new matrix, then type @kbd{C-u y} to replace the
+original data with the new data. One might wish to alter the matrix
+display style (@pxref{Vector and Matrix Formats}) or change the current
+display language (@pxref{Language Modes}) before doing this. Also, note
+that this command replaces a linear region of text (as grabbed by
+@kbd{C-x * g}), not a rectangle (as grabbed by @kbd{C-x * r}).
+
+If the editing buffer is in overwrite (as opposed to insert) mode,
+and the @kbd{C-u} prefix was not used, then the yanked number will
+overwrite the characters following point rather than being inserted
+before those characters. The usual conventions of overwrite mode
+are observed; for example, characters will be inserted at the end of
+a line rather than overflowing onto the next line. Yanking a multi-line
+object such as a matrix in overwrite mode overwrites the next @var{n}
+lines in the buffer, lengthening or shortening each line as necessary.
+Finally, if the thing being yanked is a simple integer or floating-point
+number (like @samp{-1.2345e-3}) and the characters following point also
+make up such a number, then Calc will replace that number with the new
+number, lengthening or shortening as necessary. The concept of
+``overwrite mode'' has thus been generalized from overwriting characters
+to overwriting one complete number with another.
+
+@kindex C-x * y
+The @kbd{C-x * y} key sequence is equivalent to @kbd{y} except that
+it can be typed anywhere, not just in Calc. This provides an easy
+way to guarantee that Calc knows which editing buffer you want to use!
+
+@node X Cut and Paste, , Yanking Into Buffers, Kill and Yank
+@section X Cut and Paste
+
+@noindent
+If you are using Emacs with the X window system, there is an easier
+way to move small amounts of data into and out of the calculator:
+Use the mouse-oriented cut and paste facilities of X.
+
+The default bindings for a three-button mouse cause the left button
+to move the Emacs cursor to the given place, the right button to
+select the text between the cursor and the clicked location, and
+the middle button to yank the selection into the buffer at the
+clicked location. So, if you have a Calc window and an editing
+window on your Emacs screen, you can use left-click/right-click
+to select a number, vector, or formula from one window, then
+middle-click to paste that value into the other window. When you
+paste text into the Calc window, Calc interprets it as an algebraic
+entry. It doesn't matter where you click in the Calc window; the
+new value is always pushed onto the top of the stack.
+
+The @code{xterm} program that is typically used for general-purpose
+shell windows in X interprets the mouse buttons in the same way.
+So you can use the mouse to move data between Calc and any other
+Unix program. One nice feature of @code{xterm} is that a double
+left-click selects one word, and a triple left-click selects a
+whole line. So you can usually transfer a single number into Calc
+just by double-clicking on it in the shell, then middle-clicking
+in the Calc window.
+
+@node Keypad Mode, Embedded Mode, Kill and Yank, Top
+@chapter Keypad Mode
+
+@noindent
+@kindex C-x * k
+@pindex calc-keypad
+The @kbd{C-x * k} (@code{calc-keypad}) command starts the Calculator
+and displays a picture of a calculator-style keypad. If you are using
+the X window system, you can click on any of the ``keys'' in the
+keypad using the left mouse button to operate the calculator.
+The original window remains the selected window; in Keypad mode
+you can type in your file while simultaneously performing
+calculations with the mouse.
+
+@pindex full-calc-keypad
+If you have used @kbd{C-x * b} first, @kbd{C-x * k} instead invokes
+the @code{full-calc-keypad} command, which takes over the whole
+Emacs screen and displays the keypad, the Calc stack, and the Calc
+trail all at once. This mode would normally be used when running
+Calc standalone (@pxref{Standalone Operation}).
+
+If you aren't using the X window system, you must switch into
+the @samp{*Calc Keypad*} window, place the cursor on the desired
+``key,'' and type @key{SPC} or @key{RET}. If you think this
+is easier than using Calc normally, go right ahead.
+
+Calc commands are more or less the same in Keypad mode. Certain
+keypad keys differ slightly from the corresponding normal Calc
+keystrokes; all such deviations are described below.
+
+Keypad mode includes many more commands than will fit on the keypad
+at once. Click the right mouse button [@code{calc-keypad-menu}]
+to switch to the next menu. The bottom five rows of the keypad
+stay the same; the top three rows change to a new set of commands.
+To return to earlier menus, click the middle mouse button
+[@code{calc-keypad-menu-back}] or simply advance through the menus
+until you wrap around. Typing @key{TAB} inside the keypad window
+is equivalent to clicking the right mouse button there.
+
+You can always click the @key{EXEC} button and type any normal
+Calc key sequence. This is equivalent to switching into the
+Calc buffer, typing the keys, then switching back to your
+original buffer.
+
+@menu
+* Keypad Main Menu::
+* Keypad Functions Menu::
+* Keypad Binary Menu::
+* Keypad Vectors Menu::
+* Keypad Modes Menu::
+@end menu
+
+@node Keypad Main Menu, Keypad Functions Menu, Keypad Mode, Keypad Mode
+@section Main Menu
+
+@smallexample
+@group
+|----+-----Calc 2.1------+----1
+|FLR |CEIL|RND |TRNC|CLN2|FLT |
+|----+----+----+----+----+----|
+| LN |EXP | |ABS |IDIV|MOD |
+|----+----+----+----+----+----|
+|SIN |COS |TAN |SQRT|y^x |1/x |
+|----+----+----+----+----+----|
+| ENTER |+/- |EEX |UNDO| <- |
+|-----+---+-+--+--+-+---++----|
+| INV | 7 | 8 | 9 | / |
+|-----+-----+-----+-----+-----|
+| HYP | 4 | 5 | 6 | * |
+|-----+-----+-----+-----+-----|
+|EXEC | 1 | 2 | 3 | - |
+|-----+-----+-----+-----+-----|
+| OFF | 0 | . | PI | + |
+|-----+-----+-----+-----+-----+
+@end group
+@end smallexample
+
+@noindent
+This is the menu that appears the first time you start Keypad mode.
+It will show up in a vertical window on the right side of your screen.
+Above this menu is the traditional Calc stack display. On a 24-line
+screen you will be able to see the top three stack entries.
+
+The ten digit keys, decimal point, and @key{EEX} key are used for
+entering numbers in the obvious way. @key{EEX} begins entry of an
+exponent in scientific notation. Just as with regular Calc, the
+number is pushed onto the stack as soon as you press @key{ENTER}
+or any other function key.
+
+The @key{+/-} key corresponds to normal Calc's @kbd{n} key. During
+numeric entry it changes the sign of the number or of the exponent.
+At other times it changes the sign of the number on the top of the
+stack.
+
+The @key{INV} and @key{HYP} keys modify other keys. As well as
+having the effects described elsewhere in this manual, Keypad mode
+defines several other ``inverse'' operations. These are described
+below and in the following sections.
+
+The @key{ENTER} key finishes the current numeric entry, or otherwise
+duplicates the top entry on the stack.
+
+The @key{UNDO} key undoes the most recent Calc operation.
+@kbd{INV UNDO} is the ``redo'' command, and @kbd{HYP UNDO} is
+``last arguments'' (@kbd{M-@key{RET}}).
+
+The @key{<-} key acts as a ``backspace'' during numeric entry.
+At other times it removes the top stack entry. @kbd{INV <-}
+clears the entire stack. @kbd{HYP <-} takes an integer from
+the stack, then removes that many additional stack elements.
+
+The @key{EXEC} key prompts you to enter any keystroke sequence
+that would normally work in Calc mode. This can include a
+numeric prefix if you wish. It is also possible simply to
+switch into the Calc window and type commands in it; there is
+nothing ``magic'' about this window when Keypad mode is active.
+
+The other keys in this display perform their obvious calculator
+functions. @key{CLN2} rounds the top-of-stack by temporarily
+reducing the precision by 2 digits. @key{FLT} converts an
+integer or fraction on the top of the stack to floating-point.
+
+The @key{INV} and @key{HYP} keys combined with several of these keys
+give you access to some common functions even if the appropriate menu
+is not displayed. Obviously you don't need to learn these keys
+unless you find yourself wasting time switching among the menus.
+
+@table @kbd
+@item INV +/-
+is the same as @key{1/x}.
+@item INV +
+is the same as @key{SQRT}.
+@item INV -
+is the same as @key{CONJ}.
+@item INV *
+is the same as @key{y^x}.
+@item INV /
+is the same as @key{INV y^x} (the @expr{x}th root of @expr{y}).
+@item HYP/INV 1
+are the same as @key{SIN} / @kbd{INV SIN}.
+@item HYP/INV 2
+are the same as @key{COS} / @kbd{INV COS}.
+@item HYP/INV 3
+are the same as @key{TAN} / @kbd{INV TAN}.
+@item INV/HYP 4
+are the same as @key{LN} / @kbd{HYP LN}.
+@item INV/HYP 5
+are the same as @key{EXP} / @kbd{HYP EXP}.
+@item INV 6
+is the same as @key{ABS}.
+@item INV 7
+is the same as @key{RND} (@code{calc-round}).
+@item INV 8
+is the same as @key{CLN2}.
+@item INV 9
+is the same as @key{FLT} (@code{calc-float}).
+@item INV 0
+is the same as @key{IMAG}.
+@item INV .
+is the same as @key{PREC}.
+@item INV ENTER
+is the same as @key{SWAP}.
+@item HYP ENTER
+is the same as @key{RLL3}.
+@item INV HYP ENTER
+is the same as @key{OVER}.
+@item HYP +/-
+packs the top two stack entries as an error form.
+@item HYP EEX
+packs the top two stack entries as a modulo form.
+@item INV EEX
+creates an interval form; this removes an integer which is one
+of 0 @samp{[]}, 1 @samp{[)}, 2 @samp{(]} or 3 @samp{()}, followed
+by the two limits of the interval.
+@end table
+
+The @kbd{OFF} key turns Calc off; typing @kbd{C-x * k} or @kbd{C-x * *}
+again has the same effect. This is analogous to typing @kbd{q} or
+hitting @kbd{C-x * c} again in the normal calculator. If Calc is
+running standalone (the @code{full-calc-keypad} command appeared in the
+command line that started Emacs), then @kbd{OFF} is replaced with
+@kbd{EXIT}; clicking on this actually exits Emacs itself.
+
+@node Keypad Functions Menu, Keypad Binary Menu, Keypad Main Menu, Keypad Mode
+@section Functions Menu
+
+@smallexample
+@group
+|----+----+----+----+----+----2
+|IGAM|BETA|IBET|ERF |BESJ|BESY|
+|----+----+----+----+----+----|
+|IMAG|CONJ| RE |ATN2|RAND|RAGN|
+|----+----+----+----+----+----|
+|GCD |FACT|DFCT|BNOM|PERM|NXTP|
+|----+----+----+----+----+----|
+@end group
+@end smallexample
+
+@noindent
+This menu provides various operations from the @kbd{f} and @kbd{k}
+prefix keys.
+
+@key{IMAG} multiplies the number on the stack by the imaginary
+number @expr{i = (0, 1)}.
+
+@key{RE} extracts the real part a complex number. @kbd{INV RE}
+extracts the imaginary part.
+
+@key{RAND} takes a number from the top of the stack and computes
+a random number greater than or equal to zero but less than that
+number. (@xref{Random Numbers}.) @key{RAGN} is the ``random
+again'' command; it computes another random number using the
+same limit as last time.
+
+@key{INV GCD} computes the LCM (least common multiple) function.
+
+@key{INV FACT} is the gamma function.
+@texline @math{\Gamma(x) = (x-1)!}.
+@infoline @expr{gamma(x) = (x-1)!}.
+
+@key{PERM} is the number-of-permutations function, which is on the
+@kbd{H k c} key in normal Calc.
+
+@key{NXTP} finds the next prime after a number. @kbd{INV NXTP}
+finds the previous prime.
+
+@node Keypad Binary Menu, Keypad Vectors Menu, Keypad Functions Menu, Keypad Mode
+@section Binary Menu
+
+@smallexample
+@group
+|----+----+----+----+----+----3
+|AND | OR |XOR |NOT |LSH |RSH |
+|----+----+----+----+----+----|
+|DEC |HEX |OCT |BIN |WSIZ|ARSH|
+|----+----+----+----+----+----|
+| A | B | C | D | E | F |
+|----+----+----+----+----+----|
+@end group
+@end smallexample
+
+@noindent
+The keys in this menu perform operations on binary integers.
+Note that both logical and arithmetic right-shifts are provided.
+@key{INV LSH} rotates one bit to the left.
+
+The ``difference'' function (normally on @kbd{b d}) is on @key{INV AND}.
+The ``clip'' function (normally on @w{@kbd{b c}}) is on @key{INV NOT}.
+
+The @key{DEC}, @key{HEX}, @key{OCT}, and @key{BIN} keys select the
+current radix for display and entry of numbers: Decimal, hexadecimal,
+octal, or binary. The six letter keys @key{A} through @key{F} are used
+for entering hexadecimal numbers.
+
+The @key{WSIZ} key displays the current word size for binary operations
+and allows you to enter a new word size. You can respond to the prompt
+using either the keyboard or the digits and @key{ENTER} from the keypad.
+The initial word size is 32 bits.
+
+@node Keypad Vectors Menu, Keypad Modes Menu, Keypad Binary Menu, Keypad Mode
+@section Vectors Menu
+
+@smallexample
+@group
+|----+----+----+----+----+----4
+|SUM |PROD|MAX |MAP*|MAP^|MAP$|
+|----+----+----+----+----+----|
+|MINV|MDET|MTRN|IDNT|CRSS|"x" |
+|----+----+----+----+----+----|
+|PACK|UNPK|INDX|BLD |LEN |... |
+|----+----+----+----+----+----|
+@end group
+@end smallexample
+
+@noindent
+The keys in this menu operate on vectors and matrices.
+
+@key{PACK} removes an integer @var{n} from the top of the stack;
+the next @var{n} stack elements are removed and packed into a vector,
+which is replaced onto the stack. Thus the sequence
+@kbd{1 ENTER 3 ENTER 5 ENTER 3 PACK} enters the vector
+@samp{[1, 3, 5]} onto the stack. To enter a matrix, build each row
+on the stack as a vector, then use a final @key{PACK} to collect the
+rows into a matrix.
+
+@key{UNPK} unpacks the vector on the stack, pushing each of its
+components separately.
+
+@key{INDX} removes an integer @var{n}, then builds a vector of
+integers from 1 to @var{n}. @kbd{INV INDX} takes three numbers
+from the stack: The vector size @var{n}, the starting number,
+and the increment. @kbd{BLD} takes an integer @var{n} and any
+value @var{x} and builds a vector of @var{n} copies of @var{x}.
+
+@key{IDNT} removes an integer @var{n}, then builds an @var{n}-by-@var{n}
+identity matrix.
+
+@key{LEN} replaces a vector by its length, an integer.
+
+@key{...} turns on or off ``abbreviated'' display mode for large vectors.
+
+@key{MINV}, @key{MDET}, @key{MTRN}, and @key{CROSS} are the matrix
+inverse, determinant, and transpose, and vector cross product.
+
+@key{SUM} replaces a vector by the sum of its elements. It is
+equivalent to @kbd{u +} in normal Calc (@pxref{Statistical Operations}).
+@key{PROD} computes the product of the elements of a vector, and
+@key{MAX} computes the maximum of all the elements of a vector.
+
+@key{INV SUM} computes the alternating sum of the first element
+minus the second, plus the third, minus the fourth, and so on.
+@key{INV MAX} computes the minimum of the vector elements.
+
+@key{HYP SUM} computes the mean of the vector elements.
+@key{HYP PROD} computes the sample standard deviation.
+@key{HYP MAX} computes the median.
+
+@key{MAP*} multiplies two vectors elementwise. It is equivalent
+to the @kbd{V M *} command. @key{MAP^} computes powers elementwise.
+The arguments must be vectors of equal length, or one must be a vector
+and the other must be a plain number. For example, @kbd{2 MAP^} squares
+all the elements of a vector.
+
+@key{MAP$} maps the formula on the top of the stack across the
+vector in the second-to-top position. If the formula contains
+several variables, Calc takes that many vectors starting at the
+second-to-top position and matches them to the variables in
+alphabetical order. The result is a vector of the same size as
+the input vectors, whose elements are the formula evaluated with
+the variables set to the various sets of numbers in those vectors.
+For example, you could simulate @key{MAP^} using @key{MAP$} with
+the formula @samp{x^y}.
+
+The @kbd{"x"} key pushes the variable name @expr{x} onto the
+stack. To build the formula @expr{x^2 + 6}, you would use the
+key sequence @kbd{"x" 2 y^x 6 +}. This formula would then be
+suitable for use with the @key{MAP$} key described above.
+With @key{INV}, @key{HYP}, or @key{INV} and @key{HYP}, the
+@kbd{"x"} key pushes the variable names @expr{y}, @expr{z}, and
+@expr{t}, respectively.
+
+@node Keypad Modes Menu, , Keypad Vectors Menu, Keypad Mode
+@section Modes Menu
+
+@smallexample
+@group
+|----+----+----+----+----+----5
+|FLT |FIX |SCI |ENG |GRP | |
+|----+----+----+----+----+----|
+|RAD |DEG |FRAC|POLR|SYMB|PREC|
+|----+----+----+----+----+----|
+|SWAP|RLL3|RLL4|OVER|STO |RCL |
+|----+----+----+----+----+----|
+@end group
+@end smallexample
+
+@noindent
+The keys in this menu manipulate modes, variables, and the stack.
+
+The @key{FLT}, @key{FIX}, @key{SCI}, and @key{ENG} keys select
+floating-point, fixed-point, scientific, or engineering notation.
+@key{FIX} displays two digits after the decimal by default; the
+others display full precision. With the @key{INV} prefix, these
+keys pop a number-of-digits argument from the stack.
+
+The @key{GRP} key turns grouping of digits with commas on or off.
+@kbd{INV GRP} enables grouping to the right of the decimal point as
+well as to the left.
+
+The @key{RAD} and @key{DEG} keys switch between radians and degrees
+for trigonometric functions.
+
+The @key{FRAC} key turns Fraction mode on or off. This affects
+whether commands like @kbd{/} with integer arguments produce
+fractional or floating-point results.
+
+The @key{POLR} key turns Polar mode on or off, determining whether
+polar or rectangular complex numbers are used by default.
+
+The @key{SYMB} key turns Symbolic mode on or off, in which
+operations that would produce inexact floating-point results
+are left unevaluated as algebraic formulas.
+
+The @key{PREC} key selects the current precision. Answer with
+the keyboard or with the keypad digit and @key{ENTER} keys.
+
+The @key{SWAP} key exchanges the top two stack elements.
+The @key{RLL3} key rotates the top three stack elements upwards.
+The @key{RLL4} key rotates the top four stack elements upwards.
+The @key{OVER} key duplicates the second-to-top stack element.
+
+The @key{STO} and @key{RCL} keys are analogous to @kbd{s t} and
+@kbd{s r} in regular Calc. @xref{Store and Recall}. Click the
+@key{STO} or @key{RCL} key, then one of the ten digits. (Named
+variables are not available in Keypad mode.) You can also use,
+for example, @kbd{STO + 3} to add to register 3.
+
+@node Embedded Mode, Programming, Keypad Mode, Top
+@chapter Embedded Mode
+
+@noindent
+Embedded mode in Calc provides an alternative to copying numbers
+and formulas back and forth between editing buffers and the Calc
+stack. In Embedded mode, your editing buffer becomes temporarily
+linked to the stack and this copying is taken care of automatically.
+
+@menu
+* Basic Embedded Mode::
+* More About Embedded Mode::
+* Assignments in Embedded Mode::
+* Mode Settings in Embedded Mode::
+* Customizing Embedded Mode::
+@end menu
+
+@node Basic Embedded Mode, More About Embedded Mode, Embedded Mode, Embedded Mode
+@section Basic Embedded Mode
+
+@noindent
+@kindex C-x * e
+@pindex calc-embedded
+To enter Embedded mode, position the Emacs point (cursor) on a
+formula in any buffer and press @kbd{C-x * e} (@code{calc-embedded}).
+Note that @kbd{C-x * e} is not to be used in the Calc stack buffer
+like most Calc commands, but rather in regular editing buffers that
+are visiting your own files.
+
+Calc will try to guess an appropriate language based on the major mode
+of the editing buffer. (@xref{Language Modes}.) If the current buffer is
+in @code{latex-mode}, for example, Calc will set its language to La@TeX{}.
+Similarly, Calc will use @TeX{} language for @code{tex-mode},
+@code{plain-tex-mode} and @code{context-mode}, C language for
+@code{c-mode} and @code{c++-mode}, FORTRAN language for
+@code{fortran-mode} and @code{f90-mode}, Pascal for @code{pascal-mode},
+and eqn for @code{nroff-mode} (@pxref{Customizing Calc}).
+These can be overridden with Calc's mode
+changing commands (@pxref{Mode Settings in Embedded Mode}). If no
+suitable language is available, Calc will continue with its current language.
+
+Calc normally scans backward and forward in the buffer for the
+nearest opening and closing @dfn{formula delimiters}. The simplest
+delimiters are blank lines. Other delimiters that Embedded mode
+understands are:
+
+@enumerate
+@item
+The @TeX{} and La@TeX{} math delimiters @samp{$ $}, @samp{$$ $$},
+@samp{\[ \]}, and @samp{\( \)};
+@item
+Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters);
+@item
+Lines beginning with @samp{@@} (Texinfo delimiters).
+@item
+Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters);
+@item
+Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else.
+@end enumerate
+
+@xref{Customizing Embedded Mode}, to see how to make Calc recognize
+your own favorite delimiters. Delimiters like @samp{$ $} can appear
+on their own separate lines or in-line with the formula.
+
+If you give a positive or negative numeric prefix argument, Calc
+instead uses the current point as one end of the formula, and includes
+that many lines forward or backward (respectively, including the current
+line). Explicit delimiters are not necessary in this case.
+
+With a prefix argument of zero, Calc uses the current region (delimited
+by point and mark) instead of formula delimiters. With a prefix
+argument of @kbd{C-u} only, Calc uses the current line as the formula.
+
+@kindex C-x * w
+@pindex calc-embedded-word
+The @kbd{C-x * w} (@code{calc-embedded-word}) command will start Embedded
+mode on the current ``word''; in this case Calc will scan for the first
+non-numeric character (i.e., the first character that is not a digit,
+sign, decimal point, or upper- or lower-case @samp{e}) forward and
+backward to delimit the formula.
+
+When you enable Embedded mode for a formula, Calc reads the text
+between the delimiters and tries to interpret it as a Calc formula.
+Calc can generally identify @TeX{} formulas and
+Big-style formulas even if the language mode is wrong. If Calc
+can't make sense of the formula, it beeps and refuses to enter
+Embedded mode. But if the current language is wrong, Calc can
+sometimes parse the formula successfully (but incorrectly);
+for example, the C expression @samp{atan(a[1])} can be parsed
+in Normal language mode, but the @code{atan} won't correspond to
+the built-in @code{arctan} function, and the @samp{a[1]} will be
+interpreted as @samp{a} times the vector @samp{[1]}!
+
+If you press @kbd{C-x * e} or @kbd{C-x * w} to activate an embedded
+formula which is blank, say with the cursor on the space between
+the two delimiters @samp{$ $}, Calc will immediately prompt for
+an algebraic entry.
+
+Only one formula in one buffer can be enabled at a time. If you
+move to another area of the current buffer and give Calc commands,
+Calc turns Embedded mode off for the old formula and then tries
+to restart Embedded mode at the new position. Other buffers are
+not affected by Embedded mode.
+
+When Embedded mode begins, Calc pushes the current formula onto
+the stack. No Calc stack window is created; however, Calc copies
+the top-of-stack position into the original buffer at all times.
+You can create a Calc window by hand with @kbd{C-x * o} if you
+find you need to see the entire stack.
+
+For example, typing @kbd{C-x * e} while somewhere in the formula
+@samp{n>2} in the following line enables Embedded mode on that
+inequality:
+
+@example
+We define $F_n = F_(n-1)+F_(n-2)$ for all $n>2$.
+@end example
+
+@noindent
+The formula @expr{n>2} will be pushed onto the Calc stack, and
+the top of stack will be copied back into the editing buffer.
+This means that spaces will appear around the @samp{>} symbol
+to match Calc's usual display style:
+
+@example
+We define $F_n = F_(n-1)+F_(n-2)$ for all $n > 2$.
+@end example
+
+@noindent
+No spaces have appeared around the @samp{+} sign because it's
+in a different formula, one which we have not yet touched with
+Embedded mode.
+
+Now that Embedded mode is enabled, keys you type in this buffer
+are interpreted as Calc commands. At this point we might use
+the ``commute'' command @kbd{j C} to reverse the inequality.
+This is a selection-based command for which we first need to
+move the cursor onto the operator (@samp{>} in this case) that
+needs to be commuted.
+
+@example
+We define $F_n = F_(n-1)+F_(n-2)$ for all $2 < n$.
+@end example
+
+The @kbd{C-x * o} command is a useful way to open a Calc window
+without actually selecting that window. Giving this command
+verifies that @samp{2 < n} is also on the Calc stack. Typing
+@kbd{17 @key{RET}} would produce:
+
+@example
+We define $F_n = F_(n-1)+F_(n-2)$ for all $17$.
+@end example
+
+@noindent
+with @samp{2 < n} and @samp{17} on the stack; typing @key{TAB}
+at this point will exchange the two stack values and restore
+@samp{2 < n} to the embedded formula. Even though you can't
+normally see the stack in Embedded mode, it is still there and
+it still operates in the same way. But, as with old-fashioned
+RPN calculators, you can only see the value at the top of the
+stack at any given time (unless you use @kbd{C-x * o}).
+
+Typing @kbd{C-x * e} again turns Embedded mode off. The Calc
+window reveals that the formula @w{@samp{2 < n}} is automatically
+removed from the stack, but the @samp{17} is not. Entering
+Embedded mode always pushes one thing onto the stack, and
+leaving Embedded mode always removes one thing. Anything else
+that happens on the stack is entirely your business as far as
+Embedded mode is concerned.
+
+If you press @kbd{C-x * e} in the wrong place by accident, it is
+possible that Calc will be able to parse the nearby text as a
+formula and will mangle that text in an attempt to redisplay it
+``properly'' in the current language mode. If this happens,
+press @kbd{C-x * e} again to exit Embedded mode, then give the
+regular Emacs ``undo'' command (@kbd{C-_} or @kbd{C-x u}) to put
+the text back the way it was before Calc edited it. Note that Calc's
+own Undo command (typed before you turn Embedded mode back off)
+will not do you any good, because as far as Calc is concerned
+you haven't done anything with this formula yet.
+
+@node More About Embedded Mode, Assignments in Embedded Mode, Basic Embedded Mode, Embedded Mode
+@section More About Embedded Mode
+
+@noindent
+When Embedded mode ``activates'' a formula, i.e., when it examines
+the formula for the first time since the buffer was created or
+loaded, Calc tries to sense the language in which the formula was
+written. If the formula contains any La@TeX{}-like @samp{\} sequences,
+it is parsed (i.e., read) in La@TeX{} mode. If the formula appears to
+be written in multi-line Big mode, it is parsed in Big mode. Otherwise,
+it is parsed according to the current language mode.
+
+Note that Calc does not change the current language mode according
+the formula it reads in. Even though it can read a La@TeX{} formula when
+not in La@TeX{} mode, it will immediately rewrite this formula using
+whatever language mode is in effect.
+
+@tex
+\bigskip
+@end tex
+
+@kindex d p
+@pindex calc-show-plain
+Calc's parser is unable to read certain kinds of formulas. For
+example, with @kbd{v ]} (@code{calc-matrix-brackets}) you can
+specify matrix display styles which the parser is unable to
+recognize as matrices. The @kbd{d p} (@code{calc-show-plain})
+command turns on a mode in which a ``plain'' version of a
+formula is placed in front of the fully-formatted version.
+When Calc reads a formula that has such a plain version in
+front, it reads the plain version and ignores the formatted
+version.
+
+Plain formulas are preceded and followed by @samp{%%%} signs
+by default. This notation has the advantage that the @samp{%}
+character begins a comment in @TeX{} and La@TeX{}, so if your formula is
+embedded in a @TeX{} or La@TeX{} document its plain version will be
+invisible in the final printed copy. Certain major modes have different
+delimiters to ensure that the ``plain'' version will be
+in a comment for those modes, also.
+See @ref{Customizing Embedded Mode} to see how to change the ``plain''
+formula delimiters.
+
+There are several notations which Calc's parser for ``big''
+formatted formulas can't yet recognize. In particular, it can't
+read the large symbols for @code{sum}, @code{prod}, and @code{integ},
+and it can't handle @samp{=>} with the righthand argument omitted.
+Also, Calc won't recognize special formats you have defined with
+the @kbd{Z C} command (@pxref{User-Defined Compositions}). In
+these cases it is important to use ``plain'' mode to make sure
+Calc will be able to read your formula later.
+
+Another example where ``plain'' mode is important is if you have
+specified a float mode with few digits of precision. Normally
+any digits that are computed but not displayed will simply be
+lost when you save and re-load your embedded buffer, but ``plain''
+mode allows you to make sure that the complete number is present
+in the file as well as the rounded-down number.
+
+@tex
+\bigskip
+@end tex
+
+Embedded buffers remember active formulas for as long as they
+exist in Emacs memory. Suppose you have an embedded formula
+which is @cpi{} to the normal 12 decimal places, and then
+type @w{@kbd{C-u 5 d n}} to display only five decimal places.
+If you then type @kbd{d n}, all 12 places reappear because the
+full number is still there on the Calc stack. More surprisingly,
+even if you exit Embedded mode and later re-enter it for that
+formula, typing @kbd{d n} will restore all 12 places because
+each buffer remembers all its active formulas. However, if you
+save the buffer in a file and reload it in a new Emacs session,
+all non-displayed digits will have been lost unless you used
+``plain'' mode.
+
+@tex
+\bigskip
+@end tex
+
+In some applications of Embedded mode, you will want to have a
+sequence of copies of a formula that show its evolution as you
+work on it. For example, you might want to have a sequence
+like this in your file (elaborating here on the example from
+the ``Getting Started'' chapter):
+
+@smallexample
+The derivative of
+
+ ln(ln(x))
+
+is
+
+ @r{(the derivative of }ln(ln(x))@r{)}
+
+whose value at x = 2 is
+
+ @r{(the value)}
+
+and at x = 3 is
+
+ @r{(the value)}
+@end smallexample
+
+@kindex C-x * d
+@pindex calc-embedded-duplicate
+The @kbd{C-x * d} (@code{calc-embedded-duplicate}) command is a
+handy way to make sequences like this. If you type @kbd{C-x * d},
+the formula under the cursor (which may or may not have Embedded
+mode enabled for it at the time) is copied immediately below and
+Embedded mode is then enabled for that copy.
+
+For this example, you would start with just
+
+@smallexample
+The derivative of
+
+ ln(ln(x))
+@end smallexample
+
+@noindent
+and press @kbd{C-x * d} with the cursor on this formula. The result
+is
+
+@smallexample
+The derivative of
+
+ ln(ln(x))
+
+
+ ln(ln(x))
+@end smallexample
+
+@noindent
+with the second copy of the formula enabled in Embedded mode.
+You can now press @kbd{a d x @key{RET}} to take the derivative, and
+@kbd{C-x * d C-x * d} to make two more copies of the derivative.
+To complete the computations, type @kbd{3 s l x @key{RET}} to evaluate
+the last formula, then move up to the second-to-last formula
+and type @kbd{2 s l x @key{RET}}.
+
+Finally, you would want to press @kbd{C-x * e} to exit Embedded
+mode, then go up and insert the necessary text in between the
+various formulas and numbers.
+
+@tex
+\bigskip
+@end tex
+
+@kindex C-x * f
+@kindex C-x * '
+@pindex calc-embedded-new-formula
+The @kbd{C-x * f} (@code{calc-embedded-new-formula}) command
+creates a new embedded formula at the current point. It inserts
+some default delimiters, which are usually just blank lines,
+and then does an algebraic entry to get the formula (which is
+then enabled for Embedded mode). This is just shorthand for
+typing the delimiters yourself, positioning the cursor between
+the new delimiters, and pressing @kbd{C-x * e}. The key sequence
+@kbd{C-x * '} is equivalent to @kbd{C-x * f}.
+
+@kindex C-x * n
+@kindex C-x * p
+@pindex calc-embedded-next
+@pindex calc-embedded-previous
+The @kbd{C-x * n} (@code{calc-embedded-next}) and @kbd{C-x * p}
+(@code{calc-embedded-previous}) commands move the cursor to the
+next or previous active embedded formula in the buffer. They
+can take positive or negative prefix arguments to move by several
+formulas. Note that these commands do not actually examine the
+text of the buffer looking for formulas; they only see formulas
+which have previously been activated in Embedded mode. In fact,
+@kbd{C-x * n} and @kbd{C-x * p} are a useful way to tell which
+embedded formulas are currently active. Also, note that these
+commands do not enable Embedded mode on the next or previous
+formula, they just move the cursor.
+
+@kindex C-x * `
+@pindex calc-embedded-edit
+The @kbd{C-x * `} (@code{calc-embedded-edit}) command edits the
+embedded formula at the current point as if by @kbd{`} (@code{calc-edit}).
+Embedded mode does not have to be enabled for this to work. Press
+@kbd{C-c C-c} to finish the edit, or @kbd{C-x k} to cancel.
+
+@node Assignments in Embedded Mode, Mode Settings in Embedded Mode, More About Embedded Mode, Embedded Mode
+@section Assignments in Embedded Mode
+
+@noindent
+The @samp{:=} (assignment) and @samp{=>} (``evaluates-to'') operators
+are especially useful in Embedded mode. They allow you to make
+a definition in one formula, then refer to that definition in
+other formulas embedded in the same buffer.
+
+An embedded formula which is an assignment to a variable, as in
+
+@example
+foo := 5
+@end example
+
+@noindent
+records @expr{5} as the stored value of @code{foo} for the
+purposes of Embedded mode operations in the current buffer. It
+does @emph{not} actually store @expr{5} as the ``global'' value
+of @code{foo}, however. Regular Calc operations, and Embedded
+formulas in other buffers, will not see this assignment.
+
+One way to use this assigned value is simply to create an
+Embedded formula elsewhere that refers to @code{foo}, and to press
+@kbd{=} in that formula. However, this permanently replaces the
+@code{foo} in the formula with its current value. More interesting
+is to use @samp{=>} elsewhere:
+
+@example
+foo + 7 => 12
+@end example
+
+@xref{Evaluates-To Operator}, for a general discussion of @samp{=>}.
+
+If you move back and change the assignment to @code{foo}, any
+@samp{=>} formulas which refer to it are automatically updated.
+
+@example
+foo := 17
+
+foo + 7 => 24
+@end example
+
+The obvious question then is, @emph{how} can one easily change the
+assignment to @code{foo}? If you simply select the formula in
+Embedded mode and type 17, the assignment itself will be replaced
+by the 17. The effect on the other formula will be that the
+variable @code{foo} becomes unassigned:
+
+@example
+17
+
+foo + 7 => foo + 7
+@end example
+
+The right thing to do is first to use a selection command (@kbd{j 2}
+will do the trick) to select the righthand side of the assignment.
+Then, @kbd{17 @key{TAB} @key{DEL}} will swap the 17 into place (@pxref{Selecting
+Subformulas}, to see how this works).
+
+@kindex C-x * j
+@pindex calc-embedded-select
+The @kbd{C-x * j} (@code{calc-embedded-select}) command provides an
+easy way to operate on assignments. It is just like @kbd{C-x * e},
+except that if the enabled formula is an assignment, it uses
+@kbd{j 2} to select the righthand side. If the enabled formula
+is an evaluates-to, it uses @kbd{j 1} to select the lefthand side.
+A formula can also be a combination of both:
+
+@example
+bar := foo + 3 => 20
+@end example
+
+@noindent
+in which case @kbd{C-x * j} will select the middle part (@samp{foo + 3}).
+
+The formula is automatically deselected when you leave Embedded
+mode.
+
+@kindex C-x * u
+@pindex calc-embedded-update-formula
+Another way to change the assignment to @code{foo} would simply be
+to edit the number using regular Emacs editing rather than Embedded
+mode. Then, we have to find a way to get Embedded mode to notice
+the change. The @kbd{C-x * u} (@code{calc-embedded-update-formula})
+command is a convenient way to do this.
+
+@example
+foo := 6
+
+foo + 7 => 13
+@end example
+
+Pressing @kbd{C-x * u} is much like pressing @kbd{C-x * e = C-x * e}, that
+is, temporarily enabling Embedded mode for the formula under the
+cursor and then evaluating it with @kbd{=}. But @kbd{C-x * u} does
+not actually use @kbd{C-x * e}, and in fact another formula somewhere
+else can be enabled in Embedded mode while you use @kbd{C-x * u} and
+that formula will not be disturbed.
+
+With a numeric prefix argument, @kbd{C-x * u} updates all active
+@samp{=>} formulas in the buffer. Formulas which have not yet
+been activated in Embedded mode, and formulas which do not have
+@samp{=>} as their top-level operator, are not affected by this.
+(This is useful only if you have used @kbd{m C}; see below.)
+
+With a plain @kbd{C-u} prefix, @kbd{C-u C-x * u} updates only in the
+region between mark and point rather than in the whole buffer.
+
+@kbd{C-x * u} is also a handy way to activate a formula, such as an
+@samp{=>} formula that has freshly been typed in or loaded from a
+file.
+
+@kindex C-x * a
+@pindex calc-embedded-activate
+The @kbd{C-x * a} (@code{calc-embedded-activate}) command scans
+through the current buffer and activates all embedded formulas
+that contain @samp{:=} or @samp{=>} symbols. This does not mean
+that Embedded mode is actually turned on, but only that the
+formulas' positions are registered with Embedded mode so that
+the @samp{=>} values can be properly updated as assignments are
+changed.
+
+It is a good idea to type @kbd{C-x * a} right after loading a file
+that uses embedded @samp{=>} operators. Emacs includes a nifty
+``buffer-local variables'' feature that you can use to do this
+automatically. The idea is to place near the end of your file
+a few lines that look like this:
+
+@example
+--- Local Variables: ---
+--- eval:(calc-embedded-activate) ---
+--- End: ---
+@end example
+
+@noindent
+where the leading and trailing @samp{---} can be replaced by
+any suitable strings (which must be the same on all three lines)
+or omitted altogether; in a @TeX{} or La@TeX{} file, @samp{%} would be a good
+leading string and no trailing string would be necessary. In a
+C program, @samp{/*} and @samp{*/} would be good leading and
+trailing strings.
+
+When Emacs loads a file into memory, it checks for a Local Variables
+section like this one at the end of the file. If it finds this
+section, it does the specified things (in this case, running
+@kbd{C-x * a} automatically) before editing of the file begins.
+The Local Variables section must be within 3000 characters of the
+end of the file for Emacs to find it, and it must be in the last
+page of the file if the file has any page separators.
+@xref{File Variables, , Local Variables in Files, emacs, the
+Emacs manual}.
+
+Note that @kbd{C-x * a} does not update the formulas it finds.
+To do this, type, say, @kbd{M-1 C-x * u} after @w{@kbd{C-x * a}}.
+Generally this should not be a problem, though, because the
+formulas will have been up-to-date already when the file was
+saved.
+
+Normally, @kbd{C-x * a} activates all the formulas it finds, but
+any previous active formulas remain active as well. With a
+positive numeric prefix argument, @kbd{C-x * a} first deactivates
+all current active formulas, then actives the ones it finds in
+its scan of the buffer. With a negative prefix argument,
+@kbd{C-x * a} simply deactivates all formulas.
+
+Embedded mode has two symbols, @samp{Active} and @samp{~Active},
+which it puts next to the major mode name in a buffer's mode line.
+It puts @samp{Active} if it has reason to believe that all
+formulas in the buffer are active, because you have typed @kbd{C-x * a}
+and Calc has not since had to deactivate any formulas (which can
+happen if Calc goes to update an @samp{=>} formula somewhere because
+a variable changed, and finds that the formula is no longer there
+due to some kind of editing outside of Embedded mode). Calc puts
+@samp{~Active} in the mode line if some, but probably not all,
+formulas in the buffer are active. This happens if you activate
+a few formulas one at a time but never use @kbd{C-x * a}, or if you
+used @kbd{C-x * a} but then Calc had to deactivate a formula
+because it lost track of it. If neither of these symbols appears
+in the mode line, no embedded formulas are active in the buffer
+(e.g., before Embedded mode has been used, or after a @kbd{M-- C-x * a}).
+
+Embedded formulas can refer to assignments both before and after them
+in the buffer. If there are several assignments to a variable, the
+nearest preceding assignment is used if there is one, otherwise the
+following assignment is used.
+
+@example
+x => 1
+
+x := 1
+
+x => 1
+
+x := 2
+
+x => 2
+@end example
+
+As well as simple variables, you can also assign to subscript
+expressions of the form @samp{@var{var}_@var{number}} (as in
+@code{x_0}), or @samp{@var{var}_@var{var}} (as in @code{x_max}).
+Assignments to other kinds of objects can be represented by Calc,
+but the automatic linkage between assignments and references works
+only for plain variables and these two kinds of subscript expressions.
+
+If there are no assignments to a given variable, the global
+stored value for the variable is used (@pxref{Storing Variables}),
+or, if no value is stored, the variable is left in symbolic form.
+Note that global stored values will be lost when the file is saved
+and loaded in a later Emacs session, unless you have used the
+@kbd{s p} (@code{calc-permanent-variable}) command to save them;
+@pxref{Operations on Variables}.
+
+The @kbd{m C} (@code{calc-auto-recompute}) command turns automatic
+recomputation of @samp{=>} forms on and off. If you turn automatic
+recomputation off, you will have to use @kbd{C-x * u} to update these
+formulas manually after an assignment has been changed. If you
+plan to change several assignments at once, it may be more efficient
+to type @kbd{m C}, change all the assignments, then use @kbd{M-1 C-x * u}
+to update the entire buffer afterwards. The @kbd{m C} command also
+controls @samp{=>} formulas on the stack; @pxref{Evaluates-To
+Operator}. When you turn automatic recomputation back on, the
+stack will be updated but the Embedded buffer will not; you must
+use @kbd{C-x * u} to update the buffer by hand.
+
+@node Mode Settings in Embedded Mode, Customizing Embedded Mode, Assignments in Embedded Mode, Embedded Mode
+@section Mode Settings in Embedded Mode
+
+@kindex m e
+@pindex calc-embedded-preserve-modes
+@noindent
+The mode settings can be changed while Calc is in embedded mode, but
+by default they will revert to their original values when embedded mode
+is ended. However, the modes saved when the mode-recording mode is
+@code{Save} (see below) and the modes in effect when the @kbd{m e}
+(@code{calc-embedded-preserve-modes}) command is given
+will be preserved when embedded mode is ended.
+
+Embedded mode has a rather complicated mechanism for handling mode
+settings in Embedded formulas. It is possible to put annotations
+in the file that specify mode settings either global to the entire
+file or local to a particular formula or formulas. In the latter
+case, different modes can be specified for use when a formula
+is the enabled Embedded mode formula.
+
+When you give any mode-setting command, like @kbd{m f} (for Fraction
+mode) or @kbd{d s} (for scientific notation), Embedded mode adds
+a line like the following one to the file just before the opening
+delimiter of the formula.
+
+@example
+% [calc-mode: fractions: t]
+% [calc-mode: float-format: (sci 0)]
+@end example
+
+When Calc interprets an embedded formula, it scans the text before
+the formula for mode-setting annotations like these and sets the
+Calc buffer to match these modes. Modes not explicitly described
+in the file are not changed. Calc scans all the way to the top of
+the file, or up to a line of the form
+
+@example
+% [calc-defaults]
+@end example
+
+@noindent
+which you can insert at strategic places in the file if this backward
+scan is getting too slow, or just to provide a barrier between one
+``zone'' of mode settings and another.
+
+If the file contains several annotations for the same mode, the
+closest one before the formula is used. Annotations after the
+formula are never used (except for global annotations, described
+below).
+
+The scan does not look for the leading @samp{% }, only for the
+square brackets and the text they enclose. In fact, the leading
+characters are different for different major modes. You can edit the
+mode annotations to a style that works better in context if you wish.
+@xref{Customizing Embedded Mode}, to see how to change the style
+that Calc uses when it generates the annotations. You can write
+mode annotations into the file yourself if you know the syntax;
+the easiest way to find the syntax for a given mode is to let
+Calc write the annotation for it once and see what it does.
+
+If you give a mode-changing command for a mode that already has
+a suitable annotation just above the current formula, Calc will
+modify that annotation rather than generating a new, conflicting
+one.
+
+Mode annotations have three parts, separated by colons. (Spaces
+after the colons are optional.) The first identifies the kind
+of mode setting, the second is a name for the mode itself, and
+the third is the value in the form of a Lisp symbol, number,
+or list. Annotations with unrecognizable text in the first or
+second parts are ignored. The third part is not checked to make
+sure the value is of a valid type or range; if you write an
+annotation by hand, be sure to give a proper value or results
+will be unpredictable. Mode-setting annotations are case-sensitive.
+
+While Embedded mode is enabled, the word @code{Local} appears in
+the mode line. This is to show that mode setting commands generate
+annotations that are ``local'' to the current formula or set of
+formulas. The @kbd{m R} (@code{calc-mode-record-mode}) command
+causes Calc to generate different kinds of annotations. Pressing
+@kbd{m R} repeatedly cycles through the possible modes.
+
+@code{LocEdit} and @code{LocPerm} modes generate annotations
+that look like this, respectively:
+
+@example
+% [calc-edit-mode: float-format: (sci 0)]
+% [calc-perm-mode: float-format: (sci 5)]
+@end example
+
+The first kind of annotation will be used only while a formula
+is enabled in Embedded mode. The second kind will be used only
+when the formula is @emph{not} enabled. (Whether the formula
+is ``active'' or not, i.e., whether Calc has seen this formula
+yet, is not relevant here.)
+
+@code{Global} mode generates an annotation like this at the end
+of the file:
+
+@example
+% [calc-global-mode: fractions t]
+@end example
+
+Global mode annotations affect all formulas throughout the file,
+and may appear anywhere in the file. This allows you to tuck your
+mode annotations somewhere out of the way, say, on a new page of
+the file, as long as those mode settings are suitable for all
+formulas in the file.
+
+Enabling a formula with @kbd{C-x * e} causes a fresh scan for local
+mode annotations; you will have to use this after adding annotations
+above a formula by hand to get the formula to notice them. Updating
+a formula with @kbd{C-x * u} will also re-scan the local modes, but
+global modes are only re-scanned by @kbd{C-x * a}.
+
+Another way that modes can get out of date is if you add a local
+mode annotation to a formula that has another formula after it.
+In this example, we have used the @kbd{d s} command while the
+first of the two embedded formulas is active. But the second
+formula has not changed its style to match, even though by the
+rules of reading annotations the @samp{(sci 0)} applies to it, too.
+
+@example
+% [calc-mode: float-format: (sci 0)]
+1.23e2
+
+456.
+@end example
+
+We would have to go down to the other formula and press @kbd{C-x * u}
+on it in order to get it to notice the new annotation.
+
+Two more mode-recording modes selectable by @kbd{m R} are available
+which are also available outside of Embedded mode.
+(@pxref{General Mode Commands}.) They are @code{Save}, in which mode
+settings are recorded permanently in your Calc init file (the file given
+by the variable @code{calc-settings-file}, typically @file{~/.calc.el})
+rather than by annotating the current document, and no-recording
+mode (where there is no symbol like @code{Save} or @code{Local} in
+the mode line), in which mode-changing commands do not leave any
+annotations at all.
+
+When Embedded mode is not enabled, mode-recording modes except
+for @code{Save} have no effect.
+
+@node Customizing Embedded Mode, , Mode Settings in Embedded Mode, Embedded Mode
+@section Customizing Embedded Mode
+
+@noindent
+You can modify Embedded mode's behavior by setting various Lisp
+variables described here. These variables are customizable
+(@pxref{Customizing Calc}), or you can use @kbd{M-x set-variable}
+or @kbd{M-x edit-options} to adjust a variable on the fly.
+(Another possibility would be to use a file-local variable annotation at
+the end of the file;
+@pxref{File Variables, , Local Variables in Files, emacs, the Emacs manual}.)
+Many of the variables given mentioned here can be set to depend on the
+major mode of the editing buffer (@pxref{Customizing Calc}).
+
+@vindex calc-embedded-open-formula
+The @code{calc-embedded-open-formula} variable holds a regular
+expression for the opening delimiter of a formula. @xref{Regexp Search,
+, Regular Expression Search, emacs, the Emacs manual}, to see
+how regular expressions work. Basically, a regular expression is a
+pattern that Calc can search for. A regular expression that considers
+blank lines, @samp{$}, and @samp{$$} to be opening delimiters is
+@code{"\\`\\|^\n\\|\\$\\$?"}. Just in case the meaning of this
+regular expression is not completely plain, let's go through it
+in detail.
+
+The surrounding @samp{" "} marks quote the text between them as a
+Lisp string. If you left them off, @code{set-variable} or
+@code{edit-options} would try to read the regular expression as a
+Lisp program.
+
+The most obvious property of this regular expression is that it
+contains indecently many backslashes. There are actually two levels
+of backslash usage going on here. First, when Lisp reads a quoted
+string, all pairs of characters beginning with a backslash are
+interpreted as special characters. Here, @code{\n} changes to a
+new-line character, and @code{\\} changes to a single backslash.
+So the actual regular expression seen by Calc is
+@samp{\`\|^ @r{(newline)} \|\$\$?}.
+
+Regular expressions also consider pairs beginning with backslash
+to have special meanings. Sometimes the backslash is used to quote
+a character that otherwise would have a special meaning in a regular
+expression, like @samp{$}, which normally means ``end-of-line,''
+or @samp{?}, which means that the preceding item is optional. So
+@samp{\$\$?} matches either one or two dollar signs.
+
+The other codes in this regular expression are @samp{^}, which matches
+``beginning-of-line,'' @samp{\|}, which means ``or,'' and @samp{\`},
+which matches ``beginning-of-buffer.'' So the whole pattern means
+that a formula begins at the beginning of the buffer, or on a newline
+that occurs at the beginning of a line (i.e., a blank line), or at
+one or two dollar signs.
+
+The default value of @code{calc-embedded-open-formula} looks just
+like this example, with several more alternatives added on to
+recognize various other common kinds of delimiters.
+
+By the way, the reason to use @samp{^\n} rather than @samp{^$}
+or @samp{\n\n}, which also would appear to match blank lines,
+is that the former expression actually ``consumes'' only one
+newline character as @emph{part of} the delimiter, whereas the
+latter expressions consume zero or two newlines, respectively.
+The former choice gives the most natural behavior when Calc
+must operate on a whole formula including its delimiters.
+
+See the Emacs manual for complete details on regular expressions.
+But just for your convenience, here is a list of all characters
+which must be quoted with backslash (like @samp{\$}) to avoid
+some special interpretation: @samp{. * + ? [ ] ^ $ \}. (Note
+the backslash in this list; for example, to match @samp{\[} you
+must use @code{"\\\\\\["}. An exercise for the reader is to
+account for each of these six backslashes!)
+
+@vindex calc-embedded-close-formula
+The @code{calc-embedded-close-formula} variable holds a regular
+expression for the closing delimiter of a formula. A closing
+regular expression to match the above example would be
+@code{"\\'\\|\n$\\|\\$\\$?"}. This is almost the same as the
+other one, except it now uses @samp{\'} (``end-of-buffer'') and
+@samp{\n$} (newline occurring at end of line, yet another way
+of describing a blank line that is more appropriate for this
+case).
+
+@vindex calc-embedded-open-word
+@vindex calc-embedded-close-word
+The @code{calc-embedded-open-word} and @code{calc-embedded-close-word}
+variables are similar expressions used when you type @kbd{C-x * w}
+instead of @kbd{C-x * e} to enable Embedded mode.
+
+@vindex calc-embedded-open-plain
+The @code{calc-embedded-open-plain} variable is a string which
+begins a ``plain'' formula written in front of the formatted
+formula when @kbd{d p} mode is turned on. Note that this is an
+actual string, not a regular expression, because Calc must be able
+to write this string into a buffer as well as to recognize it.
+The default string is @code{"%%% "} (note the trailing space), but may
+be different for certain major modes.
+
+@vindex calc-embedded-close-plain
+The @code{calc-embedded-close-plain} variable is a string which
+ends a ``plain'' formula. The default is @code{" %%%\n"}, but may be
+different for different major modes. Without
+the trailing newline here, the first line of a Big mode formula
+that followed might be shifted over with respect to the other lines.
+
+@vindex calc-embedded-open-new-formula
+The @code{calc-embedded-open-new-formula} variable is a string
+which is inserted at the front of a new formula when you type
+@kbd{C-x * f}. Its default value is @code{"\n\n"}. If this
+string begins with a newline character and the @kbd{C-x * f} is
+typed at the beginning of a line, @kbd{C-x * f} will skip this
+first newline to avoid introducing unnecessary blank lines in
+the file.
+
+@vindex calc-embedded-close-new-formula
+The @code{calc-embedded-close-new-formula} variable is the corresponding
+string which is inserted at the end of a new formula. Its default
+value is also @code{"\n\n"}. The final newline is omitted by
+@w{@kbd{C-x * f}} if typed at the end of a line. (It follows that if
+@kbd{C-x * f} is typed on a blank line, both a leading opening
+newline and a trailing closing newline are omitted.)
+
+@vindex calc-embedded-announce-formula
+The @code{calc-embedded-announce-formula} variable is a regular
+expression which is sure to be followed by an embedded formula.
+The @kbd{C-x * a} command searches for this pattern as well as for
+@samp{=>} and @samp{:=} operators. Note that @kbd{C-x * a} will
+not activate just anything surrounded by formula delimiters; after
+all, blank lines are considered formula delimiters by default!
+But if your language includes a delimiter which can only occur
+actually in front of a formula, you can take advantage of it here.
+The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, but may be
+different for different major modes.
+This pattern will check for @samp{%Embed} followed by any number of
+lines beginning with @samp{%} and a space. This last is important to
+make Calc consider mode annotations part of the pattern, so that the
+formula's opening delimiter really is sure to follow the pattern.
+
+@vindex calc-embedded-open-mode
+The @code{calc-embedded-open-mode} variable is a string (not a
+regular expression) which should precede a mode annotation.
+Calc never scans for this string; Calc always looks for the
+annotation itself. But this is the string that is inserted before
+the opening bracket when Calc adds an annotation on its own.
+The default is @code{"% "}, but may be different for different major
+modes.
+
+@vindex calc-embedded-close-mode
+The @code{calc-embedded-close-mode} variable is a string which
+follows a mode annotation written by Calc. Its default value
+is simply a newline, @code{"\n"}, but may be different for different
+major modes. If you change this, it is a good idea still to end with a
+newline so that mode annotations will appear on lines by themselves.
+
+@node Programming, Copying, Embedded Mode, Top
+@chapter Programming
+
+@noindent
+There are several ways to ``program'' the Emacs Calculator, depending
+on the nature of the problem you need to solve.
+
+@enumerate
+@item
+@dfn{Keyboard macros} allow you to record a sequence of keystrokes
+and play them back at a later time. This is just the standard Emacs
+keyboard macro mechanism, dressed up with a few more features such
+as loops and conditionals.
+
+@item
+@dfn{Algebraic definitions} allow you to use any formula to define a
+new function. This function can then be used in algebraic formulas or
+as an interactive command.
+
+@item
+@dfn{Rewrite rules} are discussed in the section on algebra commands.
+@xref{Rewrite Rules}. If you put your rewrite rules in the variable
+@code{EvalRules}, they will be applied automatically to all Calc
+results in just the same way as an internal ``rule'' is applied to
+evaluate @samp{sqrt(9)} to 3 and so on. @xref{Automatic Rewrites}.
+
+@item
+@dfn{Lisp} is the programming language that Calc (and most of Emacs)
+is written in. If the above techniques aren't powerful enough, you
+can write Lisp functions to do anything that built-in Calc commands
+can do. Lisp code is also somewhat faster than keyboard macros or
+rewrite rules.
+@end enumerate
+
+@kindex z
+Programming features are available through the @kbd{z} and @kbd{Z}
+prefix keys. New commands that you define are two-key sequences
+beginning with @kbd{z}. Commands for managing these definitions
+use the shift-@kbd{Z} prefix. (The @kbd{Z T} (@code{calc-timing})
+command is described elsewhere; @pxref{Troubleshooting Commands}.
+The @kbd{Z C} (@code{calc-user-define-composition}) command is also
+described elsewhere; @pxref{User-Defined Compositions}.)
+
+@menu
+* Creating User Keys::
+* Keyboard Macros::
+* Invocation Macros::
+* Algebraic Definitions::
+* Lisp Definitions::
+@end menu
+
+@node Creating User Keys, Keyboard Macros, Programming, Programming
+@section Creating User Keys
+
+@noindent
+@kindex Z D
+@pindex calc-user-define
+Any Calculator command may be bound to a key using the @kbd{Z D}
+(@code{calc-user-define}) command. Actually, it is bound to a two-key
+sequence beginning with the lower-case @kbd{z} prefix.
+
+The @kbd{Z D} command first prompts for the key to define. For example,
+press @kbd{Z D a} to define the new key sequence @kbd{z a}. You are then
+prompted for the name of the Calculator command that this key should
+run. For example, the @code{calc-sincos} command is not normally
+available on a key. Typing @kbd{Z D s sincos @key{RET}} programs the
+@kbd{z s} key sequence to run @code{calc-sincos}. This definition will remain
+in effect for the rest of this Emacs session, or until you redefine
+@kbd{z s} to be something else.
+
+You can actually bind any Emacs command to a @kbd{z} key sequence by
+backspacing over the @samp{calc-} when you are prompted for the command name.
+
+As with any other prefix key, you can type @kbd{z ?} to see a list of
+all the two-key sequences you have defined that start with @kbd{z}.
+Initially, no @kbd{z} sequences (except @kbd{z ?} itself) are defined.
+
+User keys are typically letters, but may in fact be any key.
+(@key{META}-keys are not permitted, nor are a terminal's special
+function keys which generate multi-character sequences when pressed.)
+You can define different commands on the shifted and unshifted versions
+of a letter if you wish.
+
+@kindex Z U
+@pindex calc-user-undefine
+The @kbd{Z U} (@code{calc-user-undefine}) command unbinds a user key.
+For example, the key sequence @kbd{Z U s} will undefine the @code{sincos}
+key we defined above.
+
+@kindex Z P
+@pindex calc-user-define-permanent
+@cindex Storing user definitions
+@cindex Permanent user definitions
+@cindex Calc init file, user-defined commands
+The @kbd{Z P} (@code{calc-user-define-permanent}) command makes a key
+binding permanent so that it will remain in effect even in future Emacs
+sessions. (It does this by adding a suitable bit of Lisp code into
+your Calc init file; that is, the file given by the variable
+@code{calc-settings-file}, typically @file{~/.calc.el}.) For example,
+@kbd{Z P s} would register our @code{sincos} command permanently. If
+you later wish to unregister this command you must edit your Calc init
+file by hand. (@xref{General Mode Commands}, for a way to tell Calc to
+use a different file for the Calc init file.)
+
+The @kbd{Z P} command also saves the user definition, if any, for the
+command bound to the key. After @kbd{Z F} and @kbd{Z C}, a given user
+key could invoke a command, which in turn calls an algebraic function,
+which might have one or more special display formats. A single @kbd{Z P}
+command will save all of these definitions.
+To save an algebraic function, type @kbd{'} (the apostrophe)
+when prompted for a key, and type the function name. To save a command
+without its key binding, type @kbd{M-x} and enter a function name. (The
+@samp{calc-} prefix will automatically be inserted for you.)
+(If the command you give implies a function, the function will be saved,
+and if the function has any display formats, those will be saved, but
+not the other way around: Saving a function will not save any commands
+or key bindings associated with the function.)
+
+@kindex Z E
+@pindex calc-user-define-edit
+@cindex Editing user definitions
+The @kbd{Z E} (@code{calc-user-define-edit}) command edits the definition
+of a user key. This works for keys that have been defined by either
+keyboard macros or formulas; further details are contained in the relevant
+following sections.
+
+@node Keyboard Macros, Invocation Macros, Creating User Keys, Programming
+@section Programming with Keyboard Macros
+
+@noindent
+@kindex X
+@cindex Programming with keyboard macros
+@cindex Keyboard macros
+The easiest way to ``program'' the Emacs Calculator is to use standard
+keyboard macros. Press @w{@kbd{C-x (}} to begin recording a macro. From
+this point on, keystrokes you type will be saved away as well as
+performing their usual functions. Press @kbd{C-x )} to end recording.
+Press shift-@kbd{X} (or the standard Emacs key sequence @kbd{C-x e}) to
+execute your keyboard macro by replaying the recorded keystrokes.
+@xref{Keyboard Macros, , , emacs, the Emacs Manual}, for further
+information.
+
+When you use @kbd{X} to invoke a keyboard macro, the entire macro is
+treated as a single command by the undo and trail features. The stack
+display buffer is not updated during macro execution, but is instead
+fixed up once the macro completes. Thus, commands defined with keyboard
+macros are convenient and efficient. The @kbd{C-x e} command, on the
+other hand, invokes the keyboard macro with no special treatment: Each
+command in the macro will record its own undo information and trail entry,
+and update the stack buffer accordingly. If your macro uses features
+outside of Calc's control to operate on the contents of the Calc stack
+buffer, or if it includes Undo, Redo, or last-arguments commands, you
+must use @kbd{C-x e} to make sure the buffer and undo list are up-to-date
+at all times. You could also consider using @kbd{K} (@code{calc-keep-args})
+instead of @kbd{M-@key{RET}} (@code{calc-last-args}).
+
+Calc extends the standard Emacs keyboard macros in several ways.
+Keyboard macros can be used to create user-defined commands. Keyboard
+macros can include conditional and iteration structures, somewhat
+analogous to those provided by a traditional programmable calculator.
+
+@menu
+* Naming Keyboard Macros::
+* Conditionals in Macros::
+* Loops in Macros::
+* Local Values in Macros::
+* Queries in Macros::
+@end menu
+
+@node Naming Keyboard Macros, Conditionals in Macros, Keyboard Macros, Keyboard Macros
+@subsection Naming Keyboard Macros
+
+@noindent
+@kindex Z K
+@pindex calc-user-define-kbd-macro
+Once you have defined a keyboard macro, you can bind it to a @kbd{z}
+key sequence with the @kbd{Z K} (@code{calc-user-define-kbd-macro}) command.
+This command prompts first for a key, then for a command name. For
+example, if you type @kbd{C-x ( n @key{TAB} n @key{TAB} C-x )} you will
+define a keyboard macro which negates the top two numbers on the stack
+(@key{TAB} swaps the top two stack elements). Now you can type
+@kbd{Z K n @key{RET}} to define this keyboard macro onto the @kbd{z n} key
+sequence. The default command name (if you answer the second prompt with
+just the @key{RET} key as in this example) will be something like
+@samp{calc-User-n}. The keyboard macro will now be available as both
+@kbd{z n} and @kbd{M-x calc-User-n}. You can backspace and enter a more
+descriptive command name if you wish.
+
+Macros defined by @kbd{Z K} act like single commands; they are executed
+in the same way as by the @kbd{X} key. If you wish to define the macro
+as a standard no-frills Emacs macro (to be executed as if by @kbd{C-x e}),
+give a negative prefix argument to @kbd{Z K}.
+
+Once you have bound your keyboard macro to a key, you can use
+@kbd{Z P} to register it permanently with Emacs. @xref{Creating User Keys}.
+
+@cindex Keyboard macros, editing
+The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has
+been defined by a keyboard macro tries to use the @code{edmacro} package
+edit the macro. Type @kbd{C-c C-c} to finish editing and update
+the definition stored on the key, or, to cancel the edit, kill the
+buffer with @kbd{C-x k}.
+The special characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC},
+@code{DEL}, and @code{NUL} must be entered as these three character
+sequences, written in all uppercase, as must the prefixes @code{C-} and
+@code{M-}. Spaces and line breaks are ignored. Other characters are
+copied verbatim into the keyboard macro. Basically, the notation is the
+same as is used in all of this manual's examples, except that the manual
+takes some liberties with spaces: When we say @kbd{' [1 2 3] @key{RET}},
+we take it for granted that it is clear we really mean
+@kbd{' [1 @key{SPC} 2 @key{SPC} 3] @key{RET}}.
+
+@kindex C-x * m
+@pindex read-kbd-macro
+The @kbd{C-x * m} (@code{read-kbd-macro}) command reads an Emacs ``region''
+of spelled-out keystrokes and defines it as the current keyboard macro.
+It is a convenient way to define a keyboard macro that has been stored
+in a file, or to define a macro without executing it at the same time.
+
+@node Conditionals in Macros, Loops in Macros, Naming Keyboard Macros, Keyboard Macros
+@subsection Conditionals in Keyboard Macros
+
+@noindent
+@kindex Z [
+@kindex Z ]
+@pindex calc-kbd-if
+@pindex calc-kbd-else
+@pindex calc-kbd-else-if
+@pindex calc-kbd-end-if
+@cindex Conditional structures
+The @kbd{Z [} (@code{calc-kbd-if}) and @kbd{Z ]} (@code{calc-kbd-end-if})
+commands allow you to put simple tests in a keyboard macro. When Calc
+sees the @kbd{Z [}, it pops an object from the stack and, if the object is
+a non-zero value, continues executing keystrokes. But if the object is
+zero, or if it is not provably nonzero, Calc skips ahead to the matching
+@kbd{Z ]} keystroke. @xref{Logical Operations}, for a set of commands for
+performing tests which conveniently produce 1 for true and 0 for false.
+
+For example, @kbd{@key{RET} 0 a < Z [ n Z ]} implements an absolute-value
+function in the form of a keyboard macro. This macro duplicates the
+number on the top of the stack, pushes zero and compares using @kbd{a <}
+(@code{calc-less-than}), then, if the number was less than zero,
+executes @kbd{n} (@code{calc-change-sign}). Otherwise, the change-sign
+command is skipped.
+
+To program this macro, type @kbd{C-x (}, type the above sequence of
+keystrokes, then type @kbd{C-x )}. Note that the keystrokes will be
+executed while you are making the definition as well as when you later
+re-execute the macro by typing @kbd{X}. Thus you should make sure a
+suitable number is on the stack before defining the macro so that you
+don't get a stack-underflow error during the definition process.
+
+Conditionals can be nested arbitrarily. However, there should be exactly
+one @kbd{Z ]} for each @kbd{Z [} in a keyboard macro.
+
+@kindex Z :
+The @kbd{Z :} (@code{calc-kbd-else}) command allows you to choose between
+two keystroke sequences. The general format is @kbd{@var{cond} Z [
+@var{then-part} Z : @var{else-part} Z ]}. If @var{cond} is true
+(i.e., if the top of stack contains a non-zero number after @var{cond}
+has been executed), the @var{then-part} will be executed and the
+@var{else-part} will be skipped. Otherwise, the @var{then-part} will
+be skipped and the @var{else-part} will be executed.
+
+@kindex Z |
+The @kbd{Z |} (@code{calc-kbd-else-if}) command allows you to choose
+between any number of alternatives. For example,
+@kbd{@var{cond1} Z [ @var{part1} Z : @var{cond2} Z | @var{part2} Z :
+@var{part3} Z ]} will execute @var{part1} if @var{cond1} is true,
+otherwise it will execute @var{part2} if @var{cond2} is true, otherwise
+it will execute @var{part3}.
+
+More precisely, @kbd{Z [} pops a number and conditionally skips to the
+next matching @kbd{Z :} or @kbd{Z ]} key. @w{@kbd{Z ]}} has no effect when
+actually executed. @kbd{Z :} skips to the next matching @kbd{Z ]}.
+@kbd{Z |} pops a number and conditionally skips to the next matching
+@kbd{Z :} or @kbd{Z ]}; thus, @kbd{Z [} and @kbd{Z |} are functionally
+equivalent except that @kbd{Z [} participates in nesting but @kbd{Z |}
+does not.
+
+Calc's conditional and looping constructs work by scanning the
+keyboard macro for occurrences of character sequences like @samp{Z:}
+and @samp{Z]}. One side-effect of this is that if you use these
+constructs you must be careful that these character pairs do not
+occur by accident in other parts of the macros. Since Calc rarely
+uses shift-@kbd{Z} for any purpose except as a prefix character, this
+is not likely to be a problem. Another side-effect is that it will
+not work to define your own custom key bindings for these commands.
+Only the standard shift-@kbd{Z} bindings will work correctly.
+
+@kindex Z C-g
+If Calc gets stuck while skipping characters during the definition of a
+macro, type @kbd{Z C-g} to cancel the definition. (Typing plain @kbd{C-g}
+actually adds a @kbd{C-g} keystroke to the macro.)
+
+@node Loops in Macros, Local Values in Macros, Conditionals in Macros, Keyboard Macros
+@subsection Loops in Keyboard Macros
+
+@noindent
+@kindex Z <
+@kindex Z >
+@pindex calc-kbd-repeat
+@pindex calc-kbd-end-repeat
+@cindex Looping structures
+@cindex Iterative structures
+The @kbd{Z <} (@code{calc-kbd-repeat}) and @kbd{Z >}
+(@code{calc-kbd-end-repeat}) commands pop a number from the stack,
+which must be an integer, then repeat the keystrokes between the brackets
+the specified number of times. If the integer is zero or negative, the
+body is skipped altogether. For example, @kbd{1 @key{TAB} Z < 2 * Z >}
+computes two to a nonnegative integer power. First, we push 1 on the
+stack and then swap the integer argument back to the top. The @kbd{Z <}
+pops that argument leaving the 1 back on top of the stack. Then, we
+repeat a multiply-by-two step however many times.
+
+Once again, the keyboard macro is executed as it is being entered.
+In this case it is especially important to set up reasonable initial
+conditions before making the definition: Suppose the integer 1000 just
+happened to be sitting on the stack before we typed the above definition!
+Another approach is to enter a harmless dummy definition for the macro,
+then go back and edit in the real one with a @kbd{Z E} command. Yet
+another approach is to type the macro as written-out keystroke names
+in a buffer, then use @kbd{C-x * m} (@code{read-kbd-macro}) to read the
+macro.
+
+@kindex Z /
+@pindex calc-break
+The @kbd{Z /} (@code{calc-kbd-break}) command allows you to break out
+of a keyboard macro loop prematurely. It pops an object from the stack;
+if that object is true (a non-zero number), control jumps out of the
+innermost enclosing @kbd{Z <} @dots{} @kbd{Z >} loop and continues
+after the @kbd{Z >}. If the object is false, the @kbd{Z /} has no
+effect. Thus @kbd{@var{cond} Z /} is similar to @samp{if (@var{cond}) break;}
+in the C language.
+
+@kindex Z (
+@kindex Z )
+@pindex calc-kbd-for
+@pindex calc-kbd-end-for
+The @kbd{Z (} (@code{calc-kbd-for}) and @kbd{Z )} (@code{calc-kbd-end-for})
+commands are similar to @kbd{Z <} and @kbd{Z >}, except that they make the
+value of the counter available inside the loop. The general layout is
+@kbd{@var{init} @var{final} Z ( @var{body} @var{step} Z )}. The @kbd{Z (}
+command pops initial and final values from the stack. It then creates
+a temporary internal counter and initializes it with the value @var{init}.
+The @kbd{Z (} command then repeatedly pushes the counter value onto the
+stack and executes @var{body} and @var{step}, adding @var{step} to the
+counter each time until the loop finishes.
+
+@cindex Summations (by keyboard macros)
+By default, the loop finishes when the counter becomes greater than (or
+less than) @var{final}, assuming @var{initial} is less than (greater
+than) @var{final}. If @var{initial} is equal to @var{final}, the body
+executes exactly once. The body of the loop always executes at least
+once. For example, @kbd{0 1 10 Z ( 2 ^ + 1 Z )} computes the sum of the
+squares of the integers from 1 to 10, in steps of 1.
+
+If you give a numeric prefix argument of 1 to @kbd{Z (}, the loop is
+forced to use upward-counting conventions. In this case, if @var{initial}
+is greater than @var{final} the body will not be executed at all.
+Note that @var{step} may still be negative in this loop; the prefix
+argument merely constrains the loop-finished test. Likewise, a prefix
+argument of @mathit{-1} forces downward-counting conventions.
+
+@kindex Z @{
+@kindex Z @}
+@pindex calc-kbd-loop
+@pindex calc-kbd-end-loop
+The @kbd{Z @{} (@code{calc-kbd-loop}) and @kbd{Z @}}
+(@code{calc-kbd-end-loop}) commands are similar to @kbd{Z <} and
+@kbd{Z >}, except that they do not pop a count from the stack---they
+effectively create an infinite loop. Every @kbd{Z @{} @dots{} @kbd{Z @}}
+loop ought to include at least one @kbd{Z /} to make sure the loop
+doesn't run forever. (If any error message occurs which causes Emacs
+to beep, the keyboard macro will also be halted; this is a standard
+feature of Emacs. You can also generally press @kbd{C-g} to halt a
+running keyboard macro, although not all versions of Unix support
+this feature.)
+
+The conditional and looping constructs are not actually tied to
+keyboard macros, but they are most often used in that context.
+For example, the keystrokes @kbd{10 Z < 23 @key{RET} Z >} push
+ten copies of 23 onto the stack. This can be typed ``live'' just
+as easily as in a macro definition.
+
+@xref{Conditionals in Macros}, for some additional notes about
+conditional and looping commands.
+
+@node Local Values in Macros, Queries in Macros, Loops in Macros, Keyboard Macros
+@subsection Local Values in Macros
+
+@noindent
+@cindex Local variables
+@cindex Restoring saved modes
+Keyboard macros sometimes want to operate under known conditions
+without affecting surrounding conditions. For example, a keyboard
+macro may wish to turn on Fraction mode, or set a particular
+precision, independent of the user's normal setting for those
+modes.
+
+@kindex Z `
+@kindex Z '
+@pindex calc-kbd-push
+@pindex calc-kbd-pop
+Macros also sometimes need to use local variables. Assignments to
+local variables inside the macro should not affect any variables
+outside the macro. The @kbd{Z `} (@code{calc-kbd-push}) and @kbd{Z '}
+(@code{calc-kbd-pop}) commands give you both of these capabilities.
+
+When you type @kbd{Z `} (with a backquote or accent grave character),
+the values of various mode settings are saved away. The ten ``quick''
+variables @code{q0} through @code{q9} are also saved. When
+you type @w{@kbd{Z '}} (with an apostrophe), these values are restored.
+Pairs of @kbd{Z `} and @kbd{Z '} commands may be nested.
+
+If a keyboard macro halts due to an error in between a @kbd{Z `} and
+a @kbd{Z '}, the saved values will be restored correctly even though
+the macro never reaches the @kbd{Z '} command. Thus you can use
+@kbd{Z `} and @kbd{Z '} without having to worry about what happens
+in exceptional conditions.
+
+If you type @kbd{Z `} ``live'' (not in a keyboard macro), Calc puts
+you into a ``recursive edit.'' You can tell you are in a recursive
+edit because there will be extra square brackets in the mode line,
+as in @samp{[(Calculator)]}. These brackets will go away when you
+type the matching @kbd{Z '} command. The modes and quick variables
+will be saved and restored in just the same way as if actual keyboard
+macros were involved.
+
+The modes saved by @kbd{Z `} and @kbd{Z '} are the current precision
+and binary word size, the angular mode (Deg, Rad, or HMS), the
+simplification mode, Algebraic mode, Symbolic mode, Infinite mode,
+Matrix or Scalar mode, Fraction mode, and the current complex mode
+(Polar or Rectangular). The ten ``quick'' variables' values (or lack
+thereof) are also saved.
+
+Most mode-setting commands act as toggles, but with a numeric prefix
+they force the mode either on (positive prefix) or off (negative
+or zero prefix). Since you don't know what the environment might
+be when you invoke your macro, it's best to use prefix arguments
+for all mode-setting commands inside the macro.
+
+In fact, @kbd{C-u Z `} is like @kbd{Z `} except that it sets the modes
+listed above to their default values. As usual, the matching @kbd{Z '}
+will restore the modes to their settings from before the @kbd{C-u Z `}.
+Also, @w{@kbd{Z `}} with a negative prefix argument resets the algebraic mode
+to its default (off) but leaves the other modes the same as they were
+outside the construct.
+
+The contents of the stack and trail, values of non-quick variables, and
+other settings such as the language mode and the various display modes,
+are @emph{not} affected by @kbd{Z `} and @kbd{Z '}.
+
+@node Queries in Macros, , Local Values in Macros, Keyboard Macros
+@subsection Queries in Keyboard Macros
+
+@c @noindent
+@c @kindex Z =
+@c @pindex calc-kbd-report
+@c The @kbd{Z =} (@code{calc-kbd-report}) command displays an informative
+@c message including the value on the top of the stack. You are prompted
+@c to enter a string. That string, along with the top-of-stack value,
+@c is displayed unless @kbd{m w} (@code{calc-working}) has been used
+@c to turn such messages off.
+
+@noindent
+@kindex Z #
+@pindex calc-kbd-query
+The @kbd{Z #} (@code{calc-kbd-query}) command prompts for an algebraic
+entry which takes its input from the keyboard, even during macro
+execution. All the normal conventions of algebraic input, including the
+use of @kbd{$} characters, are supported. The prompt message itself is
+taken from the top of the stack, and so must be entered (as a string)
+before the @kbd{Z #} command. (Recall, as a string it can be entered by
+pressing the @kbd{"} key and will appear as a vector when it is put on
+the stack. The prompt message is only put on the stack to provide a
+prompt for the @kbd{Z #} command; it will not play any role in any
+subsequent calculations.) This command allows your keyboard macros to
+accept numbers or formulas as interactive input.
+
+As an example,
+@kbd{2 @key{RET} "Power: " @key{RET} Z # 3 @key{RET} ^} will prompt for
+input with ``Power: '' in the minibuffer, then return 2 to the provided
+power. (The response to the prompt that's given, 3 in this example,
+will not be part of the macro.)
+
+@xref{Keyboard Macro Query, , , emacs, the Emacs Manual}, for a description of
+@kbd{C-x q} (@code{kbd-macro-query}), the standard Emacs way to accept
+keyboard input during a keyboard macro. In particular, you can use
+@kbd{C-x q} to enter a recursive edit, which allows the user to perform
+any Calculator operations interactively before pressing @kbd{C-M-c} to
+return control to the keyboard macro.
+
+@node Invocation Macros, Algebraic Definitions, Keyboard Macros, Programming
+@section Invocation Macros
+
+@kindex C-x * z
+@kindex Z I
+@pindex calc-user-invocation
+@pindex calc-user-define-invocation
+Calc provides one special keyboard macro, called up by @kbd{C-x * z}
+(@code{calc-user-invocation}), that is intended to allow you to define
+your own special way of starting Calc. To define this ``invocation
+macro,'' create the macro in the usual way with @kbd{C-x (} and
+@kbd{C-x )}, then type @kbd{Z I} (@code{calc-user-define-invocation}).
+There is only one invocation macro, so you don't need to type any
+additional letters after @kbd{Z I}. From now on, you can type
+@kbd{C-x * z} at any time to execute your invocation macro.
+
+For example, suppose you find yourself often grabbing rectangles of
+numbers into Calc and multiplying their columns. You can do this
+by typing @kbd{C-x * r} to grab, and @kbd{V R : *} to multiply columns.
+To make this into an invocation macro, just type @kbd{C-x ( C-x * r
+V R : * C-x )}, then @kbd{Z I}. Then, to multiply a rectangle of data,
+just mark the data in its buffer in the usual way and type @kbd{C-x * z}.
+
+Invocation macros are treated like regular Emacs keyboard macros;
+all the special features described above for @kbd{Z K}-style macros
+do not apply. @kbd{C-x * z} is just like @kbd{C-x e}, except that it
+uses the macro that was last stored by @kbd{Z I}. (In fact, the
+macro does not even have to have anything to do with Calc!)
+
+The @kbd{m m} command saves the last invocation macro defined by
+@kbd{Z I} along with all the other Calc mode settings.
+@xref{General Mode Commands}.
+
+@node Algebraic Definitions, Lisp Definitions, Invocation Macros, Programming
+@section Programming with Formulas
+
+@noindent
+@kindex Z F
+@pindex calc-user-define-formula
+@cindex Programming with algebraic formulas
+Another way to create a new Calculator command uses algebraic formulas.
+The @kbd{Z F} (@code{calc-user-define-formula}) command stores the
+formula at the top of the stack as the definition for a key. This
+command prompts for five things: The key, the command name, the function
+name, the argument list, and the behavior of the command when given
+non-numeric arguments.
+
+For example, suppose we type @kbd{' a+2b @key{RET}} to push the formula
+@samp{a + 2*b} onto the stack. We now type @kbd{Z F m} to define this
+formula on the @kbd{z m} key sequence. The next prompt is for a command
+name, beginning with @samp{calc-}, which should be the long (@kbd{M-x}) form
+for the new command. If you simply press @key{RET}, a default name like
+@code{calc-User-m} will be constructed. In our example, suppose we enter
+@kbd{spam @key{RET}} to define the new command as @code{calc-spam}.
+
+If you want to give the formula a long-style name only, you can press
+@key{SPC} or @key{RET} when asked which single key to use. For example
+@kbd{Z F @key{RET} spam @key{RET}} defines the new command as
+@kbd{M-x calc-spam}, with no keyboard equivalent.
+
+The third prompt is for an algebraic function name. The default is to
+use the same name as the command name but without the @samp{calc-}
+prefix. (If this is of the form @samp{User-m}, the hyphen is removed so
+it won't be taken for a minus sign in algebraic formulas.)
+This is the name you will use if you want to enter your
+new function in an algebraic formula. Suppose we enter @kbd{yow @key{RET}}.
+Then the new function can be invoked by pushing two numbers on the
+stack and typing @kbd{z m} or @kbd{x spam}, or by entering the algebraic
+formula @samp{yow(x,y)}.
+
+The fourth prompt is for the function's argument list. This is used to
+associate values on the stack with the variables that appear in the formula.
+The default is a list of all variables which appear in the formula, sorted
+into alphabetical order. In our case, the default would be @samp{(a b)}.
+This means that, when the user types @kbd{z m}, the Calculator will remove
+two numbers from the stack, substitute these numbers for @samp{a} and
+@samp{b} (respectively) in the formula, then simplify the formula and
+push the result on the stack. In other words, @kbd{10 @key{RET} 100 z m}
+would replace the 10 and 100 on the stack with the number 210, which is
+@expr{a + 2 b} with @expr{a=10} and @expr{b=100}. Likewise, the formula
+@samp{yow(10, 100)} will be evaluated by substituting @expr{a=10} and
+@expr{b=100} in the definition.
+
+You can rearrange the order of the names before pressing @key{RET} to
+control which stack positions go to which variables in the formula. If
+you remove a variable from the argument list, that variable will be left
+in symbolic form by the command. Thus using an argument list of @samp{(b)}
+for our function would cause @kbd{10 z m} to replace the 10 on the stack
+with the formula @samp{a + 20}. If we had used an argument list of
+@samp{(b a)}, the result with inputs 10 and 100 would have been 120.
+
+You can also put a nameless function on the stack instead of just a
+formula, as in @samp{<a, b : a + 2 b>}. @xref{Specifying Operators}.
+In this example, the command will be defined by the formula @samp{a + 2 b}
+using the argument list @samp{(a b)}.
+
+The final prompt is a y-or-n question concerning what to do if symbolic
+arguments are given to your function. If you answer @kbd{y}, then
+executing @kbd{z m} (using the original argument list @samp{(a b)}) with
+arguments @expr{10} and @expr{x} will leave the function in symbolic
+form, i.e., @samp{yow(10,x)}. On the other hand, if you answer @kbd{n},
+then the formula will always be expanded, even for non-constant
+arguments: @samp{10 + 2 x}. If you never plan to feed algebraic
+formulas to your new function, it doesn't matter how you answer this
+question.
+
+If you answered @kbd{y} to this question you can still cause a function
+call to be expanded by typing @kbd{a "} (@code{calc-expand-formula}).
+Also, Calc will expand the function if necessary when you take a
+derivative or integral or solve an equation involving the function.
+
+@kindex Z G
+@pindex calc-get-user-defn
+Once you have defined a formula on a key, you can retrieve this formula
+with the @kbd{Z G} (@code{calc-user-define-get-defn}) command. Press a
+key, and this command pushes the formula that was used to define that
+key onto the stack. Actually, it pushes a nameless function that
+specifies both the argument list and the defining formula. You will get
+an error message if the key is undefined, or if the key was not defined
+by a @kbd{Z F} command.
+
+The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has
+been defined by a formula uses a variant of the @code{calc-edit} command
+to edit the defining formula. Press @kbd{C-c C-c} to finish editing and
+store the new formula back in the definition, or kill the buffer with
+@kbd{C-x k} to
+cancel the edit. (The argument list and other properties of the
+definition are unchanged; to adjust the argument list, you can use
+@kbd{Z G} to grab the function onto the stack, edit with @kbd{`}, and
+then re-execute the @kbd{Z F} command.)
+
+As usual, the @kbd{Z P} command records your definition permanently.
+In this case it will permanently record all three of the relevant
+definitions: the key, the command, and the function.
+
+You may find it useful to turn off the default simplifications with
+@kbd{m O} (@code{calc-no-simplify-mode}) when entering a formula to be
+used as a function definition. For example, the formula @samp{deriv(a^2,v)}
+which might be used to define a new function @samp{dsqr(a,v)} will be
+``simplified'' to 0 immediately upon entry since @code{deriv} considers
+@expr{a} to be constant with respect to @expr{v}. Turning off
+default simplifications cures this problem: The definition will be stored
+in symbolic form without ever activating the @code{deriv} function. Press
+@kbd{m D} to turn the default simplifications back on afterwards.
+
+@node Lisp Definitions, , Algebraic Definitions, Programming
+@section Programming with Lisp
+
+@noindent
+The Calculator can be programmed quite extensively in Lisp. All you
+do is write a normal Lisp function definition, but with @code{defmath}
+in place of @code{defun}. This has the same form as @code{defun}, but it
+automagically replaces calls to standard Lisp functions like @code{+} and
+@code{zerop} with calls to the corresponding functions in Calc's own library.
+Thus you can write natural-looking Lisp code which operates on all of the
+standard Calculator data types. You can then use @kbd{Z D} if you wish to
+bind your new command to a @kbd{z}-prefix key sequence. The @kbd{Z E} command
+will not edit a Lisp-based definition.
+
+Emacs Lisp is described in the GNU Emacs Lisp Reference Manual. This section
+assumes a familiarity with Lisp programming concepts; if you do not know
+Lisp, you may find keyboard macros or rewrite rules to be an easier way
+to program the Calculator.
+
+This section first discusses ways to write commands, functions, or
+small programs to be executed inside of Calc. Then it discusses how
+your own separate programs are able to call Calc from the outside.
+Finally, there is a list of internal Calc functions and data structures
+for the true Lisp enthusiast.
+
+@menu
+* Defining Functions::
+* Defining Simple Commands::
+* Defining Stack Commands::
+* Argument Qualifiers::
+* Example Definitions::
+
+* Calling Calc from Your Programs::
+* Internals::
+@end menu
+
+@node Defining Functions, Defining Simple Commands, Lisp Definitions, Lisp Definitions
+@subsection Defining New Functions
+
+@noindent
+@findex defmath
+The @code{defmath} function (actually a Lisp macro) is like @code{defun}
+except that code in the body of the definition can make use of the full
+range of Calculator data types. The prefix @samp{calcFunc-} is added
+to the specified name to get the actual Lisp function name. As a simple
+example,
+
+@example
+(defmath myfact (n)
+ (if (> n 0)
+ (* n (myfact (1- n)))
+ 1))
+@end example
+
+@noindent
+This actually expands to the code,
+
+@example
+(defun calcFunc-myfact (n)
+ (if (math-posp n)
+ (math-mul n (calcFunc-myfact (math-add n -1)))
+ 1))
+@end example
+
+@noindent
+This function can be used in algebraic expressions, e.g., @samp{myfact(5)}.
+
+The @samp{myfact} function as it is defined above has the bug that an
+expression @samp{myfact(a+b)} will be simplified to 1 because the
+formula @samp{a+b} is not considered to be @code{posp}. A robust
+factorial function would be written along the following lines:
+
+@smallexample
+(defmath myfact (n)
+ (if (> n 0)
+ (* n (myfact (1- n)))
+ (if (= n 0)
+ 1
+ nil))) ; this could be simplified as: (and (= n 0) 1)
+@end smallexample
+
+If a function returns @code{nil}, it is left unsimplified by the Calculator
+(except that its arguments will be simplified). Thus, @samp{myfact(a+1+2)}
+will be simplified to @samp{myfact(a+3)} but no further. Beware that every
+time the Calculator reexamines this formula it will attempt to resimplify
+it, so your function ought to detect the returning-@code{nil} case as
+efficiently as possible.
+
+The following standard Lisp functions are treated by @code{defmath}:
+@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^} or
+@code{expt}, @code{=}, @code{<}, @code{>}, @code{<=}, @code{>=},
+@code{/=}, @code{1+}, @code{1-}, @code{logand}, @code{logior}, @code{logxor},
+@code{logandc2}, @code{lognot}. Also, @code{~=} is an abbreviation for
+@code{math-nearly-equal}, which is useful in implementing Taylor series.
+
+For other functions @var{func}, if a function by the name
+@samp{calcFunc-@var{func}} exists it is used, otherwise if a function by the
+name @samp{math-@var{func}} exists it is used, otherwise if @var{func} itself
+is defined as a function it is used, otherwise @samp{calcFunc-@var{func}} is
+used on the assumption that this is a to-be-defined math function. Also, if
+the function name is quoted as in @samp{('integerp a)} the function name is
+always used exactly as written (but not quoted).
+
+Variable names have @samp{var-} prepended to them unless they appear in
+the function's argument list or in an enclosing @code{let}, @code{let*},
+@code{for}, or @code{foreach} form,
+or their names already contain a @samp{-} character. Thus a reference to
+@samp{foo} is the same as a reference to @samp{var-foo}.
+
+A few other Lisp extensions are available in @code{defmath} definitions:
+
+@itemize @bullet
+@item
+The @code{elt} function accepts any number of index variables.
+Note that Calc vectors are stored as Lisp lists whose first
+element is the symbol @code{vec}; thus, @samp{(elt v 2)} yields
+the second element of vector @code{v}, and @samp{(elt m i j)}
+yields one element of a Calc matrix.
+
+@item
+The @code{setq} function has been extended to act like the Common
+Lisp @code{setf} function. (The name @code{setf} is recognized as
+a synonym of @code{setq}.) Specifically, the first argument of
+@code{setq} can be an @code{nth}, @code{elt}, @code{car}, or @code{cdr} form,
+in which case the effect is to store into the specified
+element of a list. Thus, @samp{(setq (elt m i j) x)} stores @expr{x}
+into one element of a matrix.
+
+@item
+A @code{for} looping construct is available. For example,
+@samp{(for ((i 0 10)) body)} executes @code{body} once for each
+binding of @expr{i} from zero to 10. This is like a @code{let}
+form in that @expr{i} is temporarily bound to the loop count
+without disturbing its value outside the @code{for} construct.
+Nested loops, as in @samp{(for ((i 0 10) (j 0 (1- i) 2)) body)},
+are also available. For each value of @expr{i} from zero to 10,
+@expr{j} counts from 0 to @expr{i-1} in steps of two. Note that
+@code{for} has the same general outline as @code{let*}, except
+that each element of the header is a list of three or four
+things, not just two.
+
+@item
+The @code{foreach} construct loops over elements of a list.
+For example, @samp{(foreach ((x (cdr v))) body)} executes
+@code{body} with @expr{x} bound to each element of Calc vector
+@expr{v} in turn. The purpose of @code{cdr} here is to skip over
+the initial @code{vec} symbol in the vector.
+
+@item
+The @code{break} function breaks out of the innermost enclosing
+@code{while}, @code{for}, or @code{foreach} loop. If given a
+value, as in @samp{(break x)}, this value is returned by the
+loop. (Lisp loops otherwise always return @code{nil}.)
+
+@item
+The @code{return} function prematurely returns from the enclosing
+function. For example, @samp{(return (+ x y))} returns @expr{x+y}
+as the value of a function. You can use @code{return} anywhere
+inside the body of the function.
+@end itemize
+
+Non-integer numbers (and extremely large integers) cannot be included
+directly into a @code{defmath} definition. This is because the Lisp
+reader will fail to parse them long before @code{defmath} ever gets control.
+Instead, use the notation, @samp{:"3.1415"}. In fact, any algebraic
+formula can go between the quotes. For example,
+
+@smallexample
+(defmath sqexp (x) ; sqexp(x) == sqrt(exp(x)) == exp(x*0.5)
+ (and (numberp x)
+ (exp :"x * 0.5")))
+@end smallexample
+
+expands to
+
+@smallexample
+(defun calcFunc-sqexp (x)
+ (and (math-numberp x)
+ (calcFunc-exp (math-mul x '(float 5 -1)))))
+@end smallexample
+
+Note the use of @code{numberp} as a guard to ensure that the argument is
+a number first, returning @code{nil} if not. The exponential function
+could itself have been included in the expression, if we had preferred:
+@samp{:"exp(x * 0.5)"}. As another example, the multiplication-and-recursion
+step of @code{myfact} could have been written
+
+@example
+:"n * myfact(n-1)"
+@end example
+
+A good place to put your @code{defmath} commands is your Calc init file
+(the file given by @code{calc-settings-file}, typically
+@file{~/.calc.el}), which will not be loaded until Calc starts.
+If a file named @file{.emacs} exists in your home directory, Emacs reads
+and executes the Lisp forms in this file as it starts up. While it may
+seem reasonable to put your favorite @code{defmath} commands there,
+this has the unfortunate side-effect that parts of the Calculator must be
+loaded in to process the @code{defmath} commands whether or not you will
+actually use the Calculator! If you want to put the @code{defmath}
+commands there (for example, if you redefine @code{calc-settings-file}
+to be @file{.emacs}), a better effect can be had by writing
+
+@example
+(put 'calc-define 'thing '(progn
+ (defmath ... )
+ (defmath ... )
+))
+@end example
+
+@noindent
+@vindex calc-define
+The @code{put} function adds a @dfn{property} to a symbol. Each Lisp
+symbol has a list of properties associated with it. Here we add a
+property with a name of @code{thing} and a @samp{(progn ...)} form as
+its value. When Calc starts up, and at the start of every Calc command,
+the property list for the symbol @code{calc-define} is checked and the
+values of any properties found are evaluated as Lisp forms. The
+properties are removed as they are evaluated. The property names
+(like @code{thing}) are not used; you should choose something like the
+name of your project so as not to conflict with other properties.
+
+The net effect is that you can put the above code in your @file{.emacs}
+file and it will not be executed until Calc is loaded. Or, you can put
+that same code in another file which you load by hand either before or
+after Calc itself is loaded.
+
+The properties of @code{calc-define} are evaluated in the same order
+that they were added. They can assume that the Calc modules @file{calc.el},
+@file{calc-ext.el}, and @file{calc-macs.el} have been fully loaded, and
+that the @samp{*Calculator*} buffer will be the current buffer.
+
+If your @code{calc-define} property only defines algebraic functions,
+you can be sure that it will have been evaluated before Calc tries to
+call your function, even if the file defining the property is loaded
+after Calc is loaded. But if the property defines commands or key
+sequences, it may not be evaluated soon enough. (Suppose it defines the
+new command @code{tweak-calc}; the user can load your file, then type
+@kbd{M-x tweak-calc} before Calc has had chance to do anything.) To
+protect against this situation, you can put
+
+@example
+(run-hooks 'calc-check-defines)
+@end example
+
+@findex calc-check-defines
+@noindent
+at the end of your file. The @code{calc-check-defines} function is what
+looks for and evaluates properties on @code{calc-define}; @code{run-hooks}
+has the advantage that it is quietly ignored if @code{calc-check-defines}
+is not yet defined because Calc has not yet been loaded.
+
+Examples of things that ought to be enclosed in a @code{calc-define}
+property are @code{defmath} calls, @code{define-key} calls that modify
+the Calc key map, and any calls that redefine things defined inside Calc.
+Ordinary @code{defun}s need not be enclosed with @code{calc-define}.
+
+@node Defining Simple Commands, Defining Stack Commands, Defining Functions, Lisp Definitions
+@subsection Defining New Simple Commands
+
+@noindent
+@findex interactive
+If a @code{defmath} form contains an @code{interactive} clause, it defines
+a Calculator command. Actually such a @code{defmath} results in @emph{two}
+function definitions: One, a @samp{calcFunc-} function as was just described,
+with the @code{interactive} clause removed. Two, a @samp{calc-} function
+with a suitable @code{interactive} clause and some sort of wrapper to make
+the command work in the Calc environment.
+
+In the simple case, the @code{interactive} clause has the same form as
+for normal Emacs Lisp commands:
+
+@smallexample
+(defmath increase-precision (delta)
+ "Increase precision by DELTA." ; This is the "documentation string"
+ (interactive "p") ; Register this as a M-x-able command
+ (setq calc-internal-prec (+ calc-internal-prec delta)))
+@end smallexample
+
+This expands to the pair of definitions,
+
+@smallexample
+(defun calc-increase-precision (delta)
+ "Increase precision by DELTA."
+ (interactive "p")
+ (calc-wrapper
+ (setq calc-internal-prec (math-add calc-internal-prec delta))))
+
+(defun calcFunc-increase-precision (delta)
+ "Increase precision by DELTA."
+ (setq calc-internal-prec (math-add calc-internal-prec delta)))
+@end smallexample
+
+@noindent
+where in this case the latter function would never really be used! Note
+that since the Calculator stores small integers as plain Lisp integers,
+the @code{math-add} function will work just as well as the native
+@code{+} even when the intent is to operate on native Lisp integers.
+
+@findex calc-wrapper
+The @samp{calc-wrapper} call invokes a macro which surrounds the body of
+the function with code that looks roughly like this:
+
+@smallexample
+(let ((calc-command-flags nil))
+ (unwind-protect
+ (save-excursion
+ (calc-select-buffer)
+ @emph{body of function}
+ @emph{renumber stack}
+ @emph{clear} Working @emph{message})
+ @emph{realign cursor and window}
+ @emph{clear Inverse, Hyperbolic, and Keep Args flags}
+ @emph{update Emacs mode line}))
+@end smallexample
+
+@findex calc-select-buffer
+The @code{calc-select-buffer} function selects the @samp{*Calculator*}
+buffer if necessary, say, because the command was invoked from inside
+the @samp{*Calc Trail*} window.
+
+@findex calc-set-command-flag
+You can call, for example, @code{(calc-set-command-flag 'no-align)} to
+set the above-mentioned command flags. Calc routines recognize the
+following command flags:
+
+@table @code
+@item renum-stack
+Stack line numbers @samp{1:}, @samp{2:}, and so on must be renumbered
+after this command completes. This is set by routines like
+@code{calc-push}.
+
+@item clear-message
+Calc should call @samp{(message "")} if this command completes normally
+(to clear a ``Working@dots{}'' message out of the echo area).
+
+@item no-align
+Do not move the cursor back to the @samp{.} top-of-stack marker.
+
+@item position-point
+Use the variables @code{calc-position-point-line} and
+@code{calc-position-point-column} to position the cursor after
+this command finishes.
+
+@item keep-flags
+Do not clear @code{calc-inverse-flag}, @code{calc-hyperbolic-flag},
+and @code{calc-keep-args-flag} at the end of this command.
+
+@item do-edit
+Switch to buffer @samp{*Calc Edit*} after this command.
+
+@item hold-trail
+Do not move trail pointer to end of trail when something is recorded
+there.
+@end table
+
+@kindex Y
+@kindex Y ?
+@vindex calc-Y-help-msgs
+Calc reserves a special prefix key, shift-@kbd{Y}, for user-written
+extensions to Calc. There are no built-in commands that work with
+this prefix key; you must call @code{define-key} from Lisp (probably
+from inside a @code{calc-define} property) to add to it. Initially only
+@kbd{Y ?} is defined; it takes help messages from a list of strings
+(initially @code{nil}) in the variable @code{calc-Y-help-msgs}. All
+other undefined keys except for @kbd{Y} are reserved for use by
+future versions of Calc.
+
+If you are writing a Calc enhancement which you expect to give to
+others, it is best to minimize the number of @kbd{Y}-key sequences
+you use. In fact, if you have more than one key sequence you should
+consider defining three-key sequences with a @kbd{Y}, then a key that
+stands for your package, then a third key for the particular command
+within your package.
+
+Users may wish to install several Calc enhancements, and it is possible
+that several enhancements will choose to use the same key. In the
+example below, a variable @code{inc-prec-base-key} has been defined
+to contain the key that identifies the @code{inc-prec} package. Its
+value is initially @code{"P"}, but a user can change this variable
+if necessary without having to modify the file.
+
+Here is a complete file, @file{inc-prec.el}, which makes a @kbd{Y P I}
+command that increases the precision, and a @kbd{Y P D} command that
+decreases the precision.
+
+@smallexample
+;;; Increase and decrease Calc precision. Dave Gillespie, 5/31/91.
+;; (Include copyright or copyleft stuff here.)
+
+(defvar inc-prec-base-key "P"
+ "Base key for inc-prec.el commands.")
+
+(put 'calc-define 'inc-prec '(progn
+
+(define-key calc-mode-map (format "Y%sI" inc-prec-base-key)
+ 'increase-precision)
+(define-key calc-mode-map (format "Y%sD" inc-prec-base-key)
+ 'decrease-precision)
+
+(setq calc-Y-help-msgs
+ (cons (format "%s + Inc-prec, Dec-prec" inc-prec-base-key)
+ calc-Y-help-msgs))
+
+(defmath increase-precision (delta)
+ "Increase precision by DELTA."
+ (interactive "p")
+ (setq calc-internal-prec (+ calc-internal-prec delta)))
+
+(defmath decrease-precision (delta)
+ "Decrease precision by DELTA."
+ (interactive "p")
+ (setq calc-internal-prec (- calc-internal-prec delta)))
+
+)) ; end of calc-define property
+
+(run-hooks 'calc-check-defines)
+@end smallexample
+
+@node Defining Stack Commands, Argument Qualifiers, Defining Simple Commands, Lisp Definitions
+@subsection Defining New Stack-Based Commands
+
+@noindent
+To define a new computational command which takes and/or leaves arguments
+on the stack, a special form of @code{interactive} clause is used.
+
+@example
+(interactive @var{num} @var{tag})
+@end example
+
+@noindent
+where @var{num} is an integer, and @var{tag} is a string. The effect is
+to pop @var{num} values off the stack, resimplify them by calling
+@code{calc-normalize}, and hand them to your function according to the
+function's argument list. Your function may include @code{&optional} and
+@code{&rest} parameters, so long as calling the function with @var{num}
+parameters is valid.
+
+Your function must return either a number or a formula in a form
+acceptable to Calc, or a list of such numbers or formulas. These value(s)
+are pushed onto the stack when the function completes. They are also
+recorded in the Calc Trail buffer on a line beginning with @var{tag},
+a string of (normally) four characters or less. If you omit @var{tag}
+or use @code{nil} as a tag, the result is not recorded in the trail.
+
+As an example, the definition
+
+@smallexample
+(defmath myfact (n)
+ "Compute the factorial of the integer at the top of the stack."
+ (interactive 1 "fact")
+ (if (> n 0)
+ (* n (myfact (1- n)))
+ (and (= n 0) 1)))
+@end smallexample
+
+@noindent
+is a version of the factorial function shown previously which can be used
+as a command as well as an algebraic function. It expands to
+
+@smallexample
+(defun calc-myfact ()
+ "Compute the factorial of the integer at the top of the stack."
+ (interactive)
+ (calc-slow-wrapper
+ (calc-enter-result 1 "fact"
+ (cons 'calcFunc-myfact (calc-top-list-n 1)))))
+
+(defun calcFunc-myfact (n)
+ "Compute the factorial of the integer at the top of the stack."
+ (if (math-posp n)
+ (math-mul n (calcFunc-myfact (math-add n -1)))
+ (and (math-zerop n) 1)))
+@end smallexample
+
+@findex calc-slow-wrapper
+The @code{calc-slow-wrapper} function is a version of @code{calc-wrapper}
+that automatically puts up a @samp{Working...} message before the
+computation begins. (This message can be turned off by the user
+with an @kbd{m w} (@code{calc-working}) command.)
+
+@findex calc-top-list-n
+The @code{calc-top-list-n} function returns a list of the specified number
+of values from the top of the stack. It resimplifies each value by
+calling @code{calc-normalize}. If its argument is zero it returns an
+empty list. It does not actually remove these values from the stack.
+
+@findex calc-enter-result
+The @code{calc-enter-result} function takes an integer @var{num} and string
+@var{tag} as described above, plus a third argument which is either a
+Calculator data object or a list of such objects. These objects are
+resimplified and pushed onto the stack after popping the specified number
+of values from the stack. If @var{tag} is non-@code{nil}, the values
+being pushed are also recorded in the trail.
+
+Note that if @code{calcFunc-myfact} returns @code{nil} this represents
+``leave the function in symbolic form.'' To return an actual empty list,
+in the sense that @code{calc-enter-result} will push zero elements back
+onto the stack, you should return the special value @samp{'(nil)}, a list
+containing the single symbol @code{nil}.
+
+The @code{interactive} declaration can actually contain a limited
+Emacs-style code string as well which comes just before @var{num} and
+@var{tag}. Currently the only Emacs code supported is @samp{"p"}, as in
+
+@example
+(defmath foo (a b &optional c)
+ (interactive "p" 2 "foo")
+ @var{body})
+@end example
+
+In this example, the command @code{calc-foo} will evaluate the expression
+@samp{foo(a,b)} if executed with no argument, or @samp{foo(a,b,n)} if
+executed with a numeric prefix argument of @expr{n}.
+
+The other code string allowed is @samp{"m"} (unrelated to the usual @samp{"m"}
+code as used with @code{defun}). It uses the numeric prefix argument as the
+number of objects to remove from the stack and pass to the function.
+In this case, the integer @var{num} serves as a default number of
+arguments to be used when no prefix is supplied.
+
+@node Argument Qualifiers, Example Definitions, Defining Stack Commands, Lisp Definitions
+@subsection Argument Qualifiers
+
+@noindent
+Anywhere a parameter name can appear in the parameter list you can also use
+an @dfn{argument qualifier}. Thus the general form of a definition is:
+
+@example
+(defmath @var{name} (@var{param} @var{param...}
+ &optional @var{param} @var{param...}
+ &rest @var{param})
+ @var{body})
+@end example
+
+@noindent
+where each @var{param} is either a symbol or a list of the form
+
+@example
+(@var{qual} @var{param})
+@end example
+
+The following qualifiers are recognized:
+
+@table @samp
+@item complete
+@findex complete
+The argument must not be an incomplete vector, interval, or complex number.
+(This is rarely needed since the Calculator itself will never call your
+function with an incomplete argument. But there is nothing stopping your
+own Lisp code from calling your function with an incomplete argument.)
+
+@item integer
+@findex integer
+The argument must be an integer. If it is an integer-valued float
+it will be accepted but converted to integer form. Non-integers and
+formulas are rejected.
+
+@item natnum
+@findex natnum
+Like @samp{integer}, but the argument must be non-negative.
+
+@item fixnum
+@findex fixnum
+Like @samp{integer}, but the argument must fit into a native Lisp integer,
+which on most systems means less than 2^23 in absolute value. The
+argument is converted into Lisp-integer form if necessary.
+
+@item float
+@findex float
+The argument is converted to floating-point format if it is a number or
+vector. If it is a formula it is left alone. (The argument is never
+actually rejected by this qualifier.)
+
+@item @var{pred}
+The argument must satisfy predicate @var{pred}, which is one of the
+standard Calculator predicates. @xref{Predicates}.
+
+@item not-@var{pred}
+The argument must @emph{not} satisfy predicate @var{pred}.
+@end table
+
+For example,
+
+@example
+(defmath foo (a (constp (not-matrixp b)) &optional (float c)
+ &rest (integer d))
+ @var{body})
+@end example
+
+@noindent
+expands to
+
+@example
+(defun calcFunc-foo (a b &optional c &rest d)
+ (and (math-matrixp b)
+ (math-reject-arg b 'not-matrixp))
+ (or (math-constp b)
+ (math-reject-arg b 'constp))
+ (and c (setq c (math-check-float c)))
+ (setq d (mapcar 'math-check-integer d))
+ @var{body})
+@end example
+
+@noindent
+which performs the necessary checks and conversions before executing the
+body of the function.
+
+@node Example Definitions, Calling Calc from Your Programs, Argument Qualifiers, Lisp Definitions
+@subsection Example Definitions
+
+@noindent
+This section includes some Lisp programming examples on a larger scale.
+These programs make use of some of the Calculator's internal functions;
+@pxref{Internals}.
+
+@menu
+* Bit Counting Example::
+* Sine Example::
+@end menu
+
+@node Bit Counting Example, Sine Example, Example Definitions, Example Definitions
+@subsubsection Bit-Counting
+
+@noindent
+@ignore
+@starindex
+@end ignore
+@tindex bcount
+Calc does not include a built-in function for counting the number of
+``one'' bits in a binary integer. It's easy to invent one using @kbd{b u}
+to convert the integer to a set, and @kbd{V #} to count the elements of
+that set; let's write a function that counts the bits without having to
+create an intermediate set.
+
+@smallexample
+(defmath bcount ((natnum n))
+ (interactive 1 "bcnt")
+ (let ((count 0))
+ (while (> n 0)
+ (if (oddp n)
+ (setq count (1+ count)))
+ (setq n (lsh n -1)))
+ count))
+@end smallexample
+
+@noindent
+When this is expanded by @code{defmath}, it will become the following
+Emacs Lisp function:
+
+@smallexample
+(defun calcFunc-bcount (n)
+ (setq n (math-check-natnum n))
+ (let ((count 0))
+ (while (math-posp n)
+ (if (math-oddp n)
+ (setq count (math-add count 1)))
+ (setq n (calcFunc-lsh n -1)))
+ count))
+@end smallexample
+
+If the input numbers are large, this function involves a fair amount
+of arithmetic. A binary right shift is essentially a division by two;
+recall that Calc stores integers in decimal form so bit shifts must
+involve actual division.
+
+To gain a bit more efficiency, we could divide the integer into
+@var{n}-bit chunks, each of which can be handled quickly because
+they fit into Lisp integers. It turns out that Calc's arithmetic
+routines are especially fast when dividing by an integer less than
+1000, so we can set @var{n = 9} bits and use repeated division by 512:
+
+@smallexample
+(defmath bcount ((natnum n))
+ (interactive 1 "bcnt")
+ (let ((count 0))
+ (while (not (fixnump n))
+ (let ((qr (idivmod n 512)))
+ (setq count (+ count (bcount-fixnum (cdr qr)))
+ n (car qr))))
+ (+ count (bcount-fixnum n))))
+
+(defun bcount-fixnum (n)
+ (let ((count 0))
+ (while (> n 0)
+ (setq count (+ count (logand n 1))
+ n (lsh n -1)))
+ count))
+@end smallexample
+
+@noindent
+Note that the second function uses @code{defun}, not @code{defmath}.
+Because this function deals only with native Lisp integers (``fixnums''),
+it can use the actual Emacs @code{+} and related functions rather
+than the slower but more general Calc equivalents which @code{defmath}
+uses.
+
+The @code{idivmod} function does an integer division, returning both
+the quotient and the remainder at once. Again, note that while it
+might seem that @samp{(logand n 511)} and @samp{(lsh n -9)} are
+more efficient ways to split off the bottom nine bits of @code{n},
+actually they are less efficient because each operation is really
+a division by 512 in disguise; @code{idivmod} allows us to do the
+same thing with a single division by 512.
+
+@node Sine Example, , Bit Counting Example, Example Definitions
+@subsubsection The Sine Function
+
+@noindent
+@ignore
+@starindex
+@end ignore
+@tindex mysin
+A somewhat limited sine function could be defined as follows, using the
+well-known Taylor series expansion for
+@texline @math{\sin x}:
+@infoline @samp{sin(x)}:
+
+@smallexample
+(defmath mysin ((float (anglep x)))
+ (interactive 1 "mysn")
+ (setq x (to-radians x)) ; Convert from current angular mode.
+ (let ((sum x) ; Initial term of Taylor expansion of sin.
+ newsum
+ (nfact 1) ; "nfact" equals "n" factorial at all times.
+ (xnegsqr :"-(x^2)")) ; "xnegsqr" equals -x^2.
+ (for ((n 3 100 2)) ; Upper limit of 100 is a good precaution.
+ (working "mysin" sum) ; Display "Working" message, if enabled.
+ (setq nfact (* nfact (1- n) n)
+ x (* x xnegsqr)
+ newsum (+ sum (/ x nfact)))
+ (if (~= newsum sum) ; If newsum is "nearly equal to" sum,
+ (break)) ; then we are done.
+ (setq sum newsum))
+ sum))
+@end smallexample
+
+The actual @code{sin} function in Calc works by first reducing the problem
+to a sine or cosine of a nonnegative number less than @cpiover{4}. This
+ensures that the Taylor series will converge quickly. Also, the calculation
+is carried out with two extra digits of precision to guard against cumulative
+round-off in @samp{sum}. Finally, complex arguments are allowed and handled
+by a separate algorithm.
+
+@smallexample
+(defmath mysin ((float (scalarp x)))
+ (interactive 1 "mysn")
+ (setq x (to-radians x)) ; Convert from current angular mode.
+ (with-extra-prec 2 ; Evaluate with extra precision.
+ (cond ((complexp x)
+ (mysin-complex x))
+ ((< x 0)
+ (- (mysin-raw (- x))) ; Always call mysin-raw with x >= 0.
+ (t (mysin-raw x))))))
+
+(defmath mysin-raw (x)
+ (cond ((>= x 7)
+ (mysin-raw (% x (two-pi)))) ; Now x < 7.
+ ((> x (pi-over-2))
+ (- (mysin-raw (- x (pi))))) ; Now -pi/2 <= x <= pi/2.
+ ((> x (pi-over-4))
+ (mycos-raw (- x (pi-over-2)))) ; Now -pi/2 <= x <= pi/4.
+ ((< x (- (pi-over-4)))
+ (- (mycos-raw (+ x (pi-over-2))))) ; Now -pi/4 <= x <= pi/4,
+ (t (mysin-series x)))) ; so the series will be efficient.
+@end smallexample
+
+@noindent
+where @code{mysin-complex} is an appropriate function to handle complex
+numbers, @code{mysin-series} is the routine to compute the sine Taylor
+series as before, and @code{mycos-raw} is a function analogous to
+@code{mysin-raw} for cosines.
+
+The strategy is to ensure that @expr{x} is nonnegative before calling
+@code{mysin-raw}. This function then recursively reduces its argument
+to a suitable range, namely, plus-or-minus @cpiover{4}. Note that each
+test, and particularly the first comparison against 7, is designed so
+that small roundoff errors cannot produce an infinite loop. (Suppose
+we compared with @samp{(two-pi)} instead; if due to roundoff problems
+the modulo operator ever returned @samp{(two-pi)} exactly, an infinite
+recursion could result!) We use modulo only for arguments that will
+clearly get reduced, knowing that the next rule will catch any reductions
+that this rule misses.
+
+If a program is being written for general use, it is important to code
+it carefully as shown in this second example. For quick-and-dirty programs,
+when you know that your own use of the sine function will never encounter
+a large argument, a simpler program like the first one shown is fine.
+
+@node Calling Calc from Your Programs, Internals, Example Definitions, Lisp Definitions
+@subsection Calling Calc from Your Lisp Programs
+
+@noindent
+A later section (@pxref{Internals}) gives a full description of
+Calc's internal Lisp functions. It's not hard to call Calc from
+inside your programs, but the number of these functions can be daunting.
+So Calc provides one special ``programmer-friendly'' function called
+@code{calc-eval} that can be made to do just about everything you
+need. It's not as fast as the low-level Calc functions, but it's
+much simpler to use!
+
+It may seem that @code{calc-eval} itself has a daunting number of
+options, but they all stem from one simple operation.
+
+In its simplest manifestation, @samp{(calc-eval "1+2")} parses the
+string @code{"1+2"} as if it were a Calc algebraic entry and returns
+the result formatted as a string: @code{"3"}.
+
+Since @code{calc-eval} is on the list of recommended @code{autoload}
+functions, you don't need to make any special preparations to load
+Calc before calling @code{calc-eval} the first time. Calc will be
+loaded and initialized for you.
+
+All the Calc modes that are currently in effect will be used when
+evaluating the expression and formatting the result.
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@subsubsection Additional Arguments to @code{calc-eval}
+
+@noindent
+If the input string parses to a list of expressions, Calc returns
+the results separated by @code{", "}. You can specify a different
+separator by giving a second string argument to @code{calc-eval}:
+@samp{(calc-eval "1+2,3+4" ";")} returns @code{"3;7"}.
+
+The ``separator'' can also be any of several Lisp symbols which
+request other behaviors from @code{calc-eval}. These are discussed
+one by one below.
+
+You can give additional arguments to be substituted for
+@samp{$}, @samp{$$}, and so on in the main expression. For
+example, @samp{(calc-eval "$/$$" nil "7" "1+1")} evaluates the
+expression @code{"7/(1+1)"} to yield the result @code{"3.5"}
+(assuming Fraction mode is not in effect). Note the @code{nil}
+used as a placeholder for the item-separator argument.
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@subsubsection Error Handling
+
+@noindent
+If @code{calc-eval} encounters an error, it returns a list containing
+the character position of the error, plus a suitable message as a
+string. Note that @samp{1 / 0} is @emph{not} an error by Calc's
+standards; it simply returns the string @code{"1 / 0"} which is the
+division left in symbolic form. But @samp{(calc-eval "1/")} will
+return the list @samp{(2 "Expected a number")}.
+
+If you bind the variable @code{calc-eval-error} to @code{t}
+using a @code{let} form surrounding the call to @code{calc-eval},
+errors instead call the Emacs @code{error} function which aborts
+to the Emacs command loop with a beep and an error message.
+
+If you bind this variable to the symbol @code{string}, error messages
+are returned as strings instead of lists. The character position is
+ignored.
+
+As a courtesy to other Lisp code which may be using Calc, be sure
+to bind @code{calc-eval-error} using @code{let} rather than changing
+it permanently with @code{setq}.
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@subsubsection Numbers Only
+
+@noindent
+Sometimes it is preferable to treat @samp{1 / 0} as an error
+rather than returning a symbolic result. If you pass the symbol
+@code{num} as the second argument to @code{calc-eval}, results
+that are not constants are treated as errors. The error message
+reported is the first @code{calc-why} message if there is one,
+or otherwise ``Number expected.''
+
+A result is ``constant'' if it is a number, vector, or other
+object that does not include variables or function calls. If it
+is a vector, the components must themselves be constants.
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@subsubsection Default Modes
+
+@noindent
+If the first argument to @code{calc-eval} is a list whose first
+element is a formula string, then @code{calc-eval} sets all the
+various Calc modes to their default values while the formula is
+evaluated and formatted. For example, the precision is set to 12
+digits, digit grouping is turned off, and the Normal language
+mode is used.
+
+This same principle applies to the other options discussed below.
+If the first argument would normally be @var{x}, then it can also
+be the list @samp{(@var{x})} to use the default mode settings.
+
+If there are other elements in the list, they are taken as
+variable-name/value pairs which override the default mode
+settings. Look at the documentation at the front of the
+@file{calc.el} file to find the names of the Lisp variables for
+the various modes. The mode settings are restored to their
+original values when @code{calc-eval} is done.
+
+For example, @samp{(calc-eval '("$+$$" calc-internal-prec 8) 'num a b)}
+computes the sum of two numbers, requiring a numeric result, and
+using default mode settings except that the precision is 8 instead
+of the default of 12.
+
+It's usually best to use this form of @code{calc-eval} unless your
+program actually considers the interaction with Calc's mode settings
+to be a feature. This will avoid all sorts of potential ``gotchas'';
+consider what happens with @samp{(calc-eval "sqrt(2)" 'num)}
+when the user has left Calc in Symbolic mode or No-Simplify mode.
+
+As another example, @samp{(equal (calc-eval '("$<$$") nil a b) "1")}
+checks if the number in string @expr{a} is less than the one in
+string @expr{b}. Without using a list, the integer 1 might
+come out in a variety of formats which would be hard to test for
+conveniently: @code{"1"}, @code{"8#1"}, @code{"00001"}. (But
+see ``Predicates'' mode, below.)
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@subsubsection Raw Numbers
+
+@noindent
+Normally all input and output for @code{calc-eval} is done with strings.
+You can do arithmetic with, say, @samp{(calc-eval "$+$$" nil a b)}
+in place of @samp{(+ a b)}, but this is very inefficient since the
+numbers must be converted to and from string format as they are passed
+from one @code{calc-eval} to the next.
+
+If the separator is the symbol @code{raw}, the result will be returned
+as a raw Calc data structure rather than a string. You can read about
+how these objects look in the following sections, but usually you can
+treat them as ``black box'' objects with no important internal
+structure.
+
+There is also a @code{rawnum} symbol, which is a combination of
+@code{raw} (returning a raw Calc object) and @code{num} (signaling
+an error if that object is not a constant).
+
+You can pass a raw Calc object to @code{calc-eval} in place of a
+string, either as the formula itself or as one of the @samp{$}
+arguments. Thus @samp{(calc-eval "$+$$" 'raw a b)} is an
+addition function that operates on raw Calc objects. Of course
+in this case it would be easier to call the low-level @code{math-add}
+function in Calc, if you can remember its name.
+
+In particular, note that a plain Lisp integer is acceptable to Calc
+as a raw object. (All Lisp integers are accepted on input, but
+integers of more than six decimal digits are converted to ``big-integer''
+form for output. @xref{Data Type Formats}.)
+
+When it comes time to display the object, just use @samp{(calc-eval a)}
+to format it as a string.
+
+It is an error if the input expression evaluates to a list of
+values. The separator symbol @code{list} is like @code{raw}
+except that it returns a list of one or more raw Calc objects.
+
+Note that a Lisp string is not a valid Calc object, nor is a list
+containing a string. Thus you can still safely distinguish all the
+various kinds of error returns discussed above.
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@subsubsection Predicates
+
+@noindent
+If the separator symbol is @code{pred}, the result of the formula is
+treated as a true/false value; @code{calc-eval} returns @code{t} or
+@code{nil}, respectively. A value is considered ``true'' if it is a
+non-zero number, or false if it is zero or if it is not a number.
+
+For example, @samp{(calc-eval "$<$$" 'pred a b)} tests whether
+one value is less than another.
+
+As usual, it is also possible for @code{calc-eval} to return one of
+the error indicators described above. Lisp will interpret such an
+indicator as ``true'' if you don't check for it explicitly. If you
+wish to have an error register as ``false'', use something like
+@samp{(eq (calc-eval ...) t)}.
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@subsubsection Variable Values
+
+@noindent
+Variables in the formula passed to @code{calc-eval} are not normally
+replaced by their values. If you wish this, you can use the
+@code{evalv} function (@pxref{Algebraic Manipulation}). For example,
+if 4 is stored in Calc variable @code{a} (i.e., in Lisp variable
+@code{var-a}), then @samp{(calc-eval "a+pi")} will return the
+formula @code{"a + pi"}, but @samp{(calc-eval "evalv(a+pi)")}
+will return @code{"7.14159265359"}.
+
+To store in a Calc variable, just use @code{setq} to store in the
+corresponding Lisp variable. (This is obtained by prepending
+@samp{var-} to the Calc variable name.) Calc routines will
+understand either string or raw form values stored in variables,
+although raw data objects are much more efficient. For example,
+to increment the Calc variable @code{a}:
+
+@example
+(setq var-a (calc-eval "evalv(a+1)" 'raw))
+@end example
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@subsubsection Stack Access
+
+@noindent
+If the separator symbol is @code{push}, the formula argument is
+evaluated (with possible @samp{$} expansions, as usual). The
+result is pushed onto the Calc stack. The return value is @code{nil}
+(unless there is an error from evaluating the formula, in which
+case the return value depends on @code{calc-eval-error} in the
+usual way).
+
+If the separator symbol is @code{pop}, the first argument to
+@code{calc-eval} must be an integer instead of a string. That
+many values are popped from the stack and thrown away. A negative
+argument deletes the entry at that stack level. The return value
+is the number of elements remaining in the stack after popping;
+@samp{(calc-eval 0 'pop)} is a good way to measure the size of
+the stack.
+
+If the separator symbol is @code{top}, the first argument to
+@code{calc-eval} must again be an integer. The value at that
+stack level is formatted as a string and returned. Thus
+@samp{(calc-eval 1 'top)} returns the top-of-stack value. If the
+integer is out of range, @code{nil} is returned.
+
+The separator symbol @code{rawtop} is just like @code{top} except
+that the stack entry is returned as a raw Calc object instead of
+as a string.
+
+In all of these cases the first argument can be made a list in
+order to force the default mode settings, as described above.
+Thus @samp{(calc-eval '(2 calc-number-radix 16) 'top)} returns the
+second-to-top stack entry, formatted as a string using the default
+instead of current display modes, except that the radix is
+hexadecimal instead of decimal.
+
+It is, of course, polite to put the Calc stack back the way you
+found it when you are done, unless the user of your program is
+actually expecting it to affect the stack.
+
+Note that you do not actually have to switch into the @samp{*Calculator*}
+buffer in order to use @code{calc-eval}; it temporarily switches into
+the stack buffer if necessary.
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@subsubsection Keyboard Macros
+
+@noindent
+If the separator symbol is @code{macro}, the first argument must be a
+string of characters which Calc can execute as a sequence of keystrokes.
+This switches into the Calc buffer for the duration of the macro.
+For example, @samp{(calc-eval "vx5\rVR+" 'macro)} pushes the
+vector @samp{[1,2,3,4,5]} on the stack and then replaces it
+with the sum of those numbers. Note that @samp{\r} is the Lisp
+notation for the carriage-return, @key{RET}, character.
+
+If your keyboard macro wishes to pop the stack, @samp{\C-d} is
+safer than @samp{\177} (the @key{DEL} character) because some
+installations may have switched the meanings of @key{DEL} and
+@kbd{C-h}. Calc always interprets @kbd{C-d} as a synonym for
+``pop-stack'' regardless of key mapping.
+
+If you provide a third argument to @code{calc-eval}, evaluation
+of the keyboard macro will leave a record in the Trail using
+that argument as a tag string. Normally the Trail is unaffected.
+
+The return value in this case is always @code{nil}.
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@subsubsection Lisp Evaluation
+
+@noindent
+Finally, if the separator symbol is @code{eval}, then the Lisp
+@code{eval} function is called on the first argument, which must
+be a Lisp expression rather than a Calc formula. Remember to
+quote the expression so that it is not evaluated until inside
+@code{calc-eval}.
+
+The difference from plain @code{eval} is that @code{calc-eval}
+switches to the Calc buffer before evaluating the expression.
+For example, @samp{(calc-eval '(setq calc-internal-prec 17) 'eval)}
+will correctly affect the buffer-local Calc precision variable.
+
+An alternative would be @samp{(calc-eval '(calc-precision 17) 'eval)}.
+This is evaluating a call to the function that is normally invoked
+by the @kbd{p} key, giving it 17 as its ``numeric prefix argument.''
+Note that this function will leave a message in the echo area as
+a side effect. Also, all Calc functions switch to the Calc buffer
+automatically if not invoked from there, so the above call is
+also equivalent to @samp{(calc-precision 17)} by itself.
+In all cases, Calc uses @code{save-excursion} to switch back to
+your original buffer when it is done.
+
+As usual the first argument can be a list that begins with a Lisp
+expression to use default instead of current mode settings.
+
+The result of @code{calc-eval} in this usage is just the result
+returned by the evaluated Lisp expression.
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@subsubsection Example
+
+@noindent
+@findex convert-temp
+Here is a sample Emacs command that uses @code{calc-eval}. Suppose
+you have a document with lots of references to temperatures on the
+Fahrenheit scale, say ``98.6 F'', and you wish to convert these
+references to Centigrade. The following command does this conversion.
+Place the Emacs cursor right after the letter ``F'' and invoke the
+command to change ``98.6 F'' to ``37 C''. Or, if the temperature is
+already in Centigrade form, the command changes it back to Fahrenheit.
+
+@example
+(defun convert-temp ()
+ (interactive)
+ (save-excursion
+ (re-search-backward "[^-.0-9]\\([-.0-9]+\\) *\\([FC]\\)")
+ (let* ((top1 (match-beginning 1))
+ (bot1 (match-end 1))
+ (number (buffer-substring top1 bot1))
+ (top2 (match-beginning 2))
+ (bot2 (match-end 2))
+ (type (buffer-substring top2 bot2)))
+ (if (equal type "F")
+ (setq type "C"
+ number (calc-eval "($ - 32)*5/9" nil number))
+ (setq type "F"
+ number (calc-eval "$*9/5 + 32" nil number)))
+ (goto-char top2)
+ (delete-region top2 bot2)
+ (insert-before-markers type)
+ (goto-char top1)
+ (delete-region top1 bot1)
+ (if (string-match "\\.$" number) ; change "37." to "37"
+ (setq number (substring number 0 -1)))
+ (insert number))))
+@end example
+
+Note the use of @code{insert-before-markers} when changing between
+``F'' and ``C'', so that the character winds up before the cursor
+instead of after it.
+
+@node Internals, , Calling Calc from Your Programs, Lisp Definitions
+@subsection Calculator Internals
+
+@noindent
+This section describes the Lisp functions defined by the Calculator that
+may be of use to user-written Calculator programs (as described in the
+rest of this chapter). These functions are shown by their names as they
+conventionally appear in @code{defmath}. Their full Lisp names are
+generally gotten by prepending @samp{calcFunc-} or @samp{math-} to their
+apparent names. (Names that begin with @samp{calc-} are already in
+their full Lisp form.) You can use the actual full names instead if you
+prefer them, or if you are calling these functions from regular Lisp.
+
+The functions described here are scattered throughout the various
+Calc component files. Note that @file{calc.el} includes @code{autoload}s
+for only a few component files; when Calc wants to call an advanced
+function it calls @samp{(calc-extensions)} first; this function
+autoloads @file{calc-ext.el}, which in turn autoloads all the functions
+in the remaining component files.
+
+Because @code{defmath} itself uses the extensions, user-written code
+generally always executes with the extensions already loaded, so
+normally you can use any Calc function and be confident that it will
+be autoloaded for you when necessary. If you are doing something
+special, check carefully to make sure each function you are using is
+from @file{calc.el} or its components, and call @samp{(calc-extensions)}
+before using any function based in @file{calc-ext.el} if you can't
+prove this file will already be loaded.
+
+@menu
+* Data Type Formats::
+* Interactive Lisp Functions::
+* Stack Lisp Functions::
+* Predicates::
+* Computational Lisp Functions::
+* Vector Lisp Functions::
+* Symbolic Lisp Functions::
+* Formatting Lisp Functions::
+* Hooks::
+@end menu
+
+@node Data Type Formats, Interactive Lisp Functions, Internals, Internals
+@subsubsection Data Type Formats
+
+@noindent
+Integers are stored in either of two ways, depending on their magnitude.
+Integers less than one million in absolute value are stored as standard
+Lisp integers. This is the only storage format for Calc data objects
+which is not a Lisp list.
+
+Large integers are stored as lists of the form @samp{(bigpos @var{d0}
+@var{d1} @var{d2} @dots{})} for positive integers 1000000 or more, or
+@samp{(bigneg @var{d0} @var{d1} @var{d2} @dots{})} for negative integers
+@mathit{-1000000} or less. Each @var{d} is a base-1000 ``digit,'' a Lisp integer
+from 0 to 999. The least significant digit is @var{d0}; the last digit,
+@var{dn}, which is always nonzero, is the most significant digit. For
+example, the integer @mathit{-12345678} is stored as @samp{(bigneg 678 345 12)}.
+
+The distinction between small and large integers is entirely hidden from
+the user. In @code{defmath} definitions, the Lisp predicate @code{integerp}
+returns true for either kind of integer, and in general both big and small
+integers are accepted anywhere the word ``integer'' is used in this manual.
+If the distinction must be made, native Lisp integers are called @dfn{fixnums}
+and large integers are called @dfn{bignums}.
+
+Fractions are stored as a list of the form, @samp{(frac @var{n} @var{d})}
+where @var{n} is an integer (big or small) numerator, @var{d} is an
+integer denominator greater than one, and @var{n} and @var{d} are relatively
+prime. Note that fractions where @var{d} is one are automatically converted
+to plain integers by all math routines; fractions where @var{d} is negative
+are normalized by negating the numerator and denominator.
+
+Floating-point numbers are stored in the form, @samp{(float @var{mant}
+@var{exp})}, where @var{mant} (the ``mantissa'') is an integer less than
+@samp{10^@var{p}} in absolute value (@var{p} represents the current
+precision), and @var{exp} (the ``exponent'') is a fixnum. The value of
+the float is @samp{@var{mant} * 10^@var{exp}}. For example, the number
+@mathit{-3.14} is stored as @samp{(float -314 -2) = -314*10^-2}. Other constraints
+are that the number 0.0 is always stored as @samp{(float 0 0)}, and,
+except for the 0.0 case, the rightmost base-10 digit of @var{mant} is
+always nonzero. (If the rightmost digit is zero, the number is
+rearranged by dividing @var{mant} by ten and incrementing @var{exp}.)
+
+Rectangular complex numbers are stored in the form @samp{(cplx @var{re}
+@var{im})}, where @var{re} and @var{im} are each real numbers, either
+integers, fractions, or floats. The value is @samp{@var{re} + @var{im}i}.
+The @var{im} part is nonzero; complex numbers with zero imaginary
+components are converted to real numbers automatically.
+
+Polar complex numbers are stored in the form @samp{(polar @var{r}
+@var{theta})}, where @var{r} is a positive real value and @var{theta}
+is a real value or HMS form representing an angle. This angle is
+usually normalized to lie in the interval @samp{(-180 ..@: 180)} degrees,
+or @samp{(-pi ..@: pi)} radians, according to the current angular mode.
+If the angle is 0 the value is converted to a real number automatically.
+(If the angle is 180 degrees, the value is usually also converted to a
+negative real number.)
+
+Hours-minutes-seconds forms are stored as @samp{(hms @var{h} @var{m}
+@var{s})}, where @var{h} is an integer or an integer-valued float (i.e.,
+a float with @samp{@var{exp} >= 0}), @var{m} is an integer or integer-valued
+float in the range @w{@samp{[0 ..@: 60)}}, and @var{s} is any real number
+in the range @samp{[0 ..@: 60)}.
+
+Date forms are stored as @samp{(date @var{n})}, where @var{n} is
+a real number that counts days since midnight on the morning of
+January 1, 1 AD. If @var{n} is an integer, this is a pure date
+form. If @var{n} is a fraction or float, this is a date/time form.
+
+Modulo forms are stored as @samp{(mod @var{n} @var{m})}, where @var{m} is a
+positive real number or HMS form, and @var{n} is a real number or HMS
+form in the range @samp{[0 ..@: @var{m})}.
+
+Error forms are stored as @samp{(sdev @var{x} @var{sigma})}, where @var{x}
+is the mean value and @var{sigma} is the standard deviation. Each
+component is either a number, an HMS form, or a symbolic object
+(a variable or function call). If @var{sigma} is zero, the value is
+converted to a plain real number. If @var{sigma} is negative or
+complex, it is automatically normalized to be a positive real.
+
+Interval forms are stored as @samp{(intv @var{mask} @var{lo} @var{hi})},
+where @var{mask} is one of the integers 0, 1, 2, or 3, and @var{lo} and
+@var{hi} are real numbers, HMS forms, or symbolic objects. The @var{mask}
+is a binary integer where 1 represents the fact that the interval is
+closed on the high end, and 2 represents the fact that it is closed on
+the low end. (Thus 3 represents a fully closed interval.) The interval
+@w{@samp{(intv 3 @var{x} @var{x})}} is converted to the plain number @var{x};
+intervals @samp{(intv @var{mask} @var{x} @var{x})} for any other @var{mask}
+represent empty intervals. If @var{hi} is less than @var{lo}, the interval
+is converted to a standard empty interval by replacing @var{hi} with @var{lo}.
+
+Vectors are stored as @samp{(vec @var{v1} @var{v2} @dots{})}, where @var{v1}
+is the first element of the vector, @var{v2} is the second, and so on.
+An empty vector is stored as @samp{(vec)}. A matrix is simply a vector
+where all @var{v}'s are themselves vectors of equal lengths. Note that
+Calc vectors are unrelated to the Emacs Lisp ``vector'' type, which is
+generally unused by Calc data structures.
+
+Variables are stored as @samp{(var @var{name} @var{sym})}, where
+@var{name} is a Lisp symbol whose print name is used as the visible name
+of the variable, and @var{sym} is a Lisp symbol in which the variable's
+value is actually stored. Thus, @samp{(var pi var-pi)} represents the
+special constant @samp{pi}. Almost always, the form is @samp{(var
+@var{v} var-@var{v})}. If the variable name was entered with @code{#}
+signs (which are converted to hyphens internally), the form is
+@samp{(var @var{u} @var{v})}, where @var{u} is a symbol whose name
+contains @code{#} characters, and @var{v} is a symbol that contains
+@code{-} characters instead. The value of a variable is the Calc
+object stored in its @var{sym} symbol's value cell. If the symbol's
+value cell is void or if it contains @code{nil}, the variable has no
+value. Special constants have the form @samp{(special-const
+@var{value})} stored in their value cell, where @var{value} is a formula
+which is evaluated when the constant's value is requested. Variables
+which represent units are not stored in any special way; they are units
+only because their names appear in the units table. If the value
+cell contains a string, it is parsed to get the variable's value when
+the variable is used.
+
+A Lisp list with any other symbol as the first element is a function call.
+The symbols @code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^},
+and @code{|} represent special binary operators; these lists are always
+of the form @samp{(@var{op} @var{lhs} @var{rhs})} where @var{lhs} is the
+sub-formula on the lefthand side and @var{rhs} is the sub-formula on the
+right. The symbol @code{neg} represents unary negation; this list is always
+of the form @samp{(neg @var{arg})}. Any other symbol @var{func} represents a
+function that would be displayed in function-call notation; the symbol
+@var{func} is in general always of the form @samp{calcFunc-@var{name}}.
+The function cell of the symbol @var{func} should contain a Lisp function
+for evaluating a call to @var{func}. This function is passed the remaining
+elements of the list (themselves already evaluated) as arguments; such
+functions should return @code{nil} or call @code{reject-arg} to signify
+that they should be left in symbolic form, or they should return a Calc
+object which represents their value, or a list of such objects if they
+wish to return multiple values. (The latter case is allowed only for
+functions which are the outer-level call in an expression whose value is
+about to be pushed on the stack; this feature is considered obsolete
+and is not used by any built-in Calc functions.)
+
+@node Interactive Lisp Functions, Stack Lisp Functions, Data Type Formats, Internals
+@subsubsection Interactive Functions
+
+@noindent
+The functions described here are used in implementing interactive Calc
+commands. Note that this list is not exhaustive! If there is an
+existing command that behaves similarly to the one you want to define,
+you may find helpful tricks by checking the source code for that command.
+
+@defun calc-set-command-flag flag
+Set the command flag @var{flag}. This is generally a Lisp symbol, but
+may in fact be anything. The effect is to add @var{flag} to the list
+stored in the variable @code{calc-command-flags}, unless it is already
+there. @xref{Defining Simple Commands}.
+@end defun
+
+@defun calc-clear-command-flag flag
+If @var{flag} appears among the list of currently-set command flags,
+remove it from that list.
+@end defun
+
+@defun calc-record-undo rec
+Add the ``undo record'' @var{rec} to the list of steps to take if the
+current operation should need to be undone. Stack push and pop functions
+automatically call @code{calc-record-undo}, so the kinds of undo records
+you might need to create take the form @samp{(set @var{sym} @var{value})},
+which says that the Lisp variable @var{sym} was changed and had previously
+contained @var{value}; @samp{(store @var{var} @var{value})} which says that
+the Calc variable @var{var} (a string which is the name of the symbol that
+contains the variable's value) was stored and its previous value was
+@var{value} (either a Calc data object, or @code{nil} if the variable was
+previously void); or @samp{(eval @var{undo} @var{redo} @var{args} @dots{})},
+which means that to undo requires calling the function @samp{(@var{undo}
+@var{args} @dots{})} and, if the undo is later redone, calling
+@samp{(@var{redo} @var{args} @dots{})}.
+@end defun
+
+@defun calc-record-why msg args
+Record the error or warning message @var{msg}, which is normally a string.
+This message will be replayed if the user types @kbd{w} (@code{calc-why});
+if the message string begins with a @samp{*}, it is considered important
+enough to display even if the user doesn't type @kbd{w}. If one or more
+@var{args} are present, the displayed message will be of the form,
+@samp{@var{msg}: @var{arg1}, @var{arg2}, @dots{}}, where the arguments are
+formatted on the assumption that they are either strings or Calc objects of
+some sort. If @var{msg} is a symbol, it is the name of a Calc predicate
+(such as @code{integerp} or @code{numvecp}) which the arguments did not
+satisfy; it is expanded to a suitable string such as ``Expected an
+integer.'' The @code{reject-arg} function calls @code{calc-record-why}
+automatically; @pxref{Predicates}.
+@end defun
+
+@defun calc-is-inverse
+This predicate returns true if the current command is inverse,
+i.e., if the Inverse (@kbd{I} key) flag was set.
+@end defun
+
+@defun calc-is-hyperbolic
+This predicate is the analogous function for the @kbd{H} key.
+@end defun
+
+@node Stack Lisp Functions, Predicates, Interactive Lisp Functions, Internals
+@subsubsection Stack-Oriented Functions
+
+@noindent
+The functions described here perform various operations on the Calc
+stack and trail. They are to be used in interactive Calc commands.
+
+@defun calc-push-list vals n
+Push the Calc objects in list @var{vals} onto the stack at stack level
+@var{n}. If @var{n} is omitted it defaults to 1, so that the elements
+are pushed at the top of the stack. If @var{n} is greater than 1, the
+elements will be inserted into the stack so that the last element will
+end up at level @var{n}, the next-to-last at level @var{n}+1, etc.
+The elements of @var{vals} are assumed to be valid Calc objects, and
+are not evaluated, rounded, or renormalized in any way. If @var{vals}
+is an empty list, nothing happens.
+
+The stack elements are pushed without any sub-formula selections.
+You can give an optional third argument to this function, which must
+be a list the same size as @var{vals} of selections. Each selection
+must be @code{eq} to some sub-formula of the corresponding formula
+in @var{vals}, or @code{nil} if that formula should have no selection.
+@end defun
+
+@defun calc-top-list n m
+Return a list of the @var{n} objects starting at level @var{m} of the
+stack. If @var{m} is omitted it defaults to 1, so that the elements are
+taken from the top of the stack. If @var{n} is omitted, it also
+defaults to 1, so that the top stack element (in the form of a
+one-element list) is returned. If @var{m} is greater than 1, the
+@var{m}th stack element will be at the end of the list, the @var{m}+1st
+element will be next-to-last, etc. If @var{n} or @var{m} are out of
+range, the command is aborted with a suitable error message. If @var{n}
+is zero, the function returns an empty list. The stack elements are not
+evaluated, rounded, or renormalized.
+
+If any stack elements contain selections, and selections have not
+been disabled by the @kbd{j e} (@code{calc-enable-selections}) command,
+this function returns the selected portions rather than the entire
+stack elements. It can be given a third ``selection-mode'' argument
+which selects other behaviors. If it is the symbol @code{t}, then
+a selection in any of the requested stack elements produces an
+``invalid operation on selections'' error. If it is the symbol @code{full},
+the whole stack entry is always returned regardless of selections.
+If it is the symbol @code{sel}, the selected portion is always returned,
+or @code{nil} if there is no selection. (This mode ignores the @kbd{j e}
+command.) If the symbol is @code{entry}, the complete stack entry in
+list form is returned; the first element of this list will be the whole
+formula, and the third element will be the selection (or @code{nil}).
+@end defun
+
+@defun calc-pop-stack n m
+Remove the specified elements from the stack. The parameters @var{n}
+and @var{m} are defined the same as for @code{calc-top-list}. The return
+value of @code{calc-pop-stack} is uninteresting.
+
+If there are any selected sub-formulas among the popped elements, and
+@kbd{j e} has not been used to disable selections, this produces an
+error without changing the stack. If you supply an optional third
+argument of @code{t}, the stack elements are popped even if they
+contain selections.
+@end defun
+
+@defun calc-record-list vals tag
+This function records one or more results in the trail. The @var{vals}
+are a list of strings or Calc objects. The @var{tag} is the four-character
+tag string to identify the values. If @var{tag} is omitted, a blank tag
+will be used.
+@end defun
+
+@defun calc-normalize n
+This function takes a Calc object and ``normalizes'' it. At the very
+least this involves re-rounding floating-point values according to the
+current precision and other similar jobs. Also, unless the user has
+selected No-Simplify mode (@pxref{Simplification Modes}), this involves
+actually evaluating a formula object by executing the function calls
+it contains, and possibly also doing algebraic simplification, etc.
+@end defun
+
+@defun calc-top-list-n n m
+This function is identical to @code{calc-top-list}, except that it calls
+@code{calc-normalize} on the values that it takes from the stack. They
+are also passed through @code{check-complete}, so that incomplete
+objects will be rejected with an error message. All computational
+commands should use this in preference to @code{calc-top-list}; the only
+standard Calc commands that operate on the stack without normalizing
+are stack management commands like @code{calc-enter} and @code{calc-roll-up}.
+This function accepts the same optional selection-mode argument as
+@code{calc-top-list}.
+@end defun
+
+@defun calc-top-n m
+This function is a convenient form of @code{calc-top-list-n} in which only
+a single element of the stack is taken and returned, rather than a list
+of elements. This also accepts an optional selection-mode argument.
+@end defun
+
+@defun calc-enter-result n tag vals
+This function is a convenient interface to most of the above functions.
+The @var{vals} argument should be either a single Calc object, or a list
+of Calc objects; the object or objects are normalized, and the top @var{n}
+stack entries are replaced by the normalized objects. If @var{tag} is
+non-@code{nil}, the normalized objects are also recorded in the trail.
+A typical stack-based computational command would take the form,
+
+@smallexample
+(calc-enter-result @var{n} @var{tag} (cons 'calcFunc-@var{func}
+ (calc-top-list-n @var{n})))
+@end smallexample
+
+If any of the @var{n} stack elements replaced contain sub-formula
+selections, and selections have not been disabled by @kbd{j e},
+this function takes one of two courses of action. If @var{n} is
+equal to the number of elements in @var{vals}, then each element of
+@var{vals} is spliced into the corresponding selection; this is what
+happens when you use the @key{TAB} key, or when you use a unary
+arithmetic operation like @code{sqrt}. If @var{vals} has only one
+element but @var{n} is greater than one, there must be only one
+selection among the top @var{n} stack elements; the element from
+@var{vals} is spliced into that selection. This is what happens when
+you use a binary arithmetic operation like @kbd{+}. Any other
+combination of @var{n} and @var{vals} is an error when selections
+are present.
+@end defun
+
+@defun calc-unary-op tag func arg
+This function implements a unary operator that allows a numeric prefix
+argument to apply the operator over many stack entries. If the prefix
+argument @var{arg} is @code{nil}, this uses @code{calc-enter-result}
+as outlined above. Otherwise, it maps the function over several stack
+elements; @pxref{Prefix Arguments}. For example,
+
+@smallexample
+(defun calc-zeta (arg)
+ (interactive "P")
+ (calc-unary-op "zeta" 'calcFunc-zeta arg))
+@end smallexample
+@end defun
+
+@defun calc-binary-op tag func arg ident unary
+This function implements a binary operator, analogously to
+@code{calc-unary-op}. The optional @var{ident} and @var{unary}
+arguments specify the behavior when the prefix argument is zero or
+one, respectively. If the prefix is zero, the value @var{ident}
+is pushed onto the stack, if specified, otherwise an error message
+is displayed. If the prefix is one, the unary function @var{unary}
+is applied to the top stack element, or, if @var{unary} is not
+specified, nothing happens. When the argument is two or more,
+the binary function @var{func} is reduced across the top @var{arg}
+stack elements; when the argument is negative, the function is
+mapped between the next-to-top @mathit{-@var{arg}} stack elements and the
+top element.
+@end defun
+
+@defun calc-stack-size
+Return the number of elements on the stack as an integer. This count
+does not include elements that have been temporarily hidden by stack
+truncation; @pxref{Truncating the Stack}.
+@end defun
+
+@defun calc-cursor-stack-index n
+Move the point to the @var{n}th stack entry. If @var{n} is zero, this
+will be the @samp{.} line. If @var{n} is from 1 to the current stack size,
+this will be the beginning of the first line of that stack entry's display.
+If line numbers are enabled, this will move to the first character of the
+line number, not the stack entry itself.
+@end defun
+
+@defun calc-substack-height n
+Return the number of lines between the beginning of the @var{n}th stack
+entry and the bottom of the buffer. If @var{n} is zero, this
+will be one (assuming no stack truncation). If all stack entries are
+one line long (i.e., no matrices are displayed), the return value will
+be equal @var{n}+1 as long as @var{n} is in range. (Note that in Big
+mode, the return value includes the blank lines that separate stack
+entries.)
+@end defun
+
+@defun calc-refresh
+Erase the @code{*Calculator*} buffer and reformat its contents from memory.
+This must be called after changing any parameter, such as the current
+display radix, which might change the appearance of existing stack
+entries. (During a keyboard macro invoked by the @kbd{X} key, refreshing
+is suppressed, but a flag is set so that the entire stack will be refreshed
+rather than just the top few elements when the macro finishes.)
+@end defun
+
+@node Predicates, Computational Lisp Functions, Stack Lisp Functions, Internals
+@subsubsection Predicates
+
+@noindent
+The functions described here are predicates, that is, they return a
+true/false value where @code{nil} means false and anything else means
+true. These predicates are expanded by @code{defmath}, for example,
+from @code{zerop} to @code{math-zerop}. In many cases they correspond
+to native Lisp functions by the same name, but are extended to cover
+the full range of Calc data types.
+
+@defun zerop x
+Returns true if @var{x} is numerically zero, in any of the Calc data
+types. (Note that for some types, such as error forms and intervals,
+it never makes sense to return true.) In @code{defmath}, the expression
+@samp{(= x 0)} will automatically be converted to @samp{(math-zerop x)},
+and @samp{(/= x 0)} will be converted to @samp{(not (math-zerop x))}.
+@end defun
+
+@defun negp x
+Returns true if @var{x} is negative. This accepts negative real numbers
+of various types, negative HMS and date forms, and intervals in which
+all included values are negative. In @code{defmath}, the expression
+@samp{(< x 0)} will automatically be converted to @samp{(math-negp x)},
+and @samp{(>= x 0)} will be converted to @samp{(not (math-negp x))}.
+@end defun
+
+@defun posp x
+Returns true if @var{x} is positive (and non-zero). For complex
+numbers, none of these three predicates will return true.
+@end defun
+
+@defun looks-negp x
+Returns true if @var{x} is ``negative-looking.'' This returns true if
+@var{x} is a negative number, or a formula with a leading minus sign
+such as @samp{-a/b}. In other words, this is an object which can be
+made simpler by calling @code{(- @var{x})}.
+@end defun
+
+@defun integerp x
+Returns true if @var{x} is an integer of any size.
+@end defun
+
+@defun fixnump x
+Returns true if @var{x} is a native Lisp integer.
+@end defun
+
+@defun natnump x
+Returns true if @var{x} is a nonnegative integer of any size.
+@end defun
+
+@defun fixnatnump x
+Returns true if @var{x} is a nonnegative Lisp integer.
+@end defun
+
+@defun num-integerp x
+Returns true if @var{x} is numerically an integer, i.e., either a
+true integer or a float with no significant digits to the right of
+the decimal point.
+@end defun
+
+@defun messy-integerp x
+Returns true if @var{x} is numerically, but not literally, an integer.
+A value is @code{num-integerp} if it is @code{integerp} or
+@code{messy-integerp} (but it is never both at once).
+@end defun
+
+@defun num-natnump x
+Returns true if @var{x} is numerically a nonnegative integer.
+@end defun
+
+@defun evenp x
+Returns true if @var{x} is an even integer.
+@end defun
+
+@defun looks-evenp x
+Returns true if @var{x} is an even integer, or a formula with a leading
+multiplicative coefficient which is an even integer.
+@end defun
+
+@defun oddp x
+Returns true if @var{x} is an odd integer.
+@end defun
+
+@defun ratp x
+Returns true if @var{x} is a rational number, i.e., an integer or a
+fraction.
+@end defun
+
+@defun realp x
+Returns true if @var{x} is a real number, i.e., an integer, fraction,
+or floating-point number.
+@end defun
+
+@defun anglep x
+Returns true if @var{x} is a real number or HMS form.
+@end defun
+
+@defun floatp x
+Returns true if @var{x} is a float, or a complex number, error form,
+interval, date form, or modulo form in which at least one component
+is a float.
+@end defun
+
+@defun complexp x
+Returns true if @var{x} is a rectangular or polar complex number
+(but not a real number).
+@end defun
+
+@defun rect-complexp x
+Returns true if @var{x} is a rectangular complex number.
+@end defun
+
+@defun polar-complexp x
+Returns true if @var{x} is a polar complex number.
+@end defun
+
+@defun numberp x
+Returns true if @var{x} is a real number or a complex number.
+@end defun
+
+@defun scalarp x
+Returns true if @var{x} is a real or complex number or an HMS form.
+@end defun
+
+@defun vectorp x
+Returns true if @var{x} is a vector (this simply checks if its argument
+is a list whose first element is the symbol @code{vec}).
+@end defun
+
+@defun numvecp x
+Returns true if @var{x} is a number or vector.
+@end defun
+
+@defun matrixp x
+Returns true if @var{x} is a matrix, i.e., a vector of one or more vectors,
+all of the same size.
+@end defun
+
+@defun square-matrixp x
+Returns true if @var{x} is a square matrix.
+@end defun
+
+@defun objectp x
+Returns true if @var{x} is any numeric Calc object, including real and
+complex numbers, HMS forms, date forms, error forms, intervals, and
+modulo forms. (Note that error forms and intervals may include formulas
+as their components; see @code{constp} below.)
+@end defun
+
+@defun objvecp x
+Returns true if @var{x} is an object or a vector. This also accepts
+incomplete objects, but it rejects variables and formulas (except as
+mentioned above for @code{objectp}).
+@end defun
+
+@defun primp x
+Returns true if @var{x} is a ``primitive'' or ``atomic'' Calc object,
+i.e., one whose components cannot be regarded as sub-formulas. This
+includes variables, and all @code{objectp} types except error forms
+and intervals.
+@end defun
+
+@defun constp x
+Returns true if @var{x} is constant, i.e., a real or complex number,
+HMS form, date form, or error form, interval, or vector all of whose
+components are @code{constp}.
+@end defun
+
+@defun lessp x y
+Returns true if @var{x} is numerically less than @var{y}. Returns false
+if @var{x} is greater than or equal to @var{y}, or if the order is
+undefined or cannot be determined. Generally speaking, this works
+by checking whether @samp{@var{x} - @var{y}} is @code{negp}. In
+@code{defmath}, the expression @samp{(< x y)} will automatically be
+converted to @samp{(lessp x y)}; expressions involving @code{>}, @code{<=},
+and @code{>=} are similarly converted in terms of @code{lessp}.
+@end defun
+
+@defun beforep x y
+Returns true if @var{x} comes before @var{y} in a canonical ordering
+of Calc objects. If @var{x} and @var{y} are both real numbers, this
+will be the same as @code{lessp}. But whereas @code{lessp} considers
+other types of objects to be unordered, @code{beforep} puts any two
+objects into a definite, consistent order. The @code{beforep}
+function is used by the @kbd{V S} vector-sorting command, and also
+by @kbd{a s} to put the terms of a product into canonical order:
+This allows @samp{x y + y x} to be simplified easily to @samp{2 x y}.
+@end defun
+
+@defun equal x y
+This is the standard Lisp @code{equal} predicate; it returns true if
+@var{x} and @var{y} are structurally identical. This is the usual way
+to compare numbers for equality, but note that @code{equal} will treat
+0 and 0.0 as different.
+@end defun
+
+@defun math-equal x y
+Returns true if @var{x} and @var{y} are numerically equal, either because
+they are @code{equal}, or because their difference is @code{zerop}. In
+@code{defmath}, the expression @samp{(= x y)} will automatically be
+converted to @samp{(math-equal x y)}.
+@end defun
+
+@defun equal-int x n
+Returns true if @var{x} and @var{n} are numerically equal, where @var{n}
+is a fixnum which is not a multiple of 10. This will automatically be
+used by @code{defmath} in place of the more general @code{math-equal}
+whenever possible.
+@end defun
+
+@defun nearly-equal x y
+Returns true if @var{x} and @var{y}, as floating-point numbers, are
+equal except possibly in the last decimal place. For example,
+314.159 and 314.166 are considered nearly equal if the current
+precision is 6 (since they differ by 7 units), but not if the current
+precision is 7 (since they differ by 70 units). Most functions which
+use series expansions use @code{with-extra-prec} to evaluate the
+series with 2 extra digits of precision, then use @code{nearly-equal}
+to decide when the series has converged; this guards against cumulative
+error in the series evaluation without doing extra work which would be
+lost when the result is rounded back down to the current precision.
+In @code{defmath}, this can be written @samp{(~= @var{x} @var{y})}.
+The @var{x} and @var{y} can be numbers of any kind, including complex.
+@end defun
+
+@defun nearly-zerop x y
+Returns true if @var{x} is nearly zero, compared to @var{y}. This
+checks whether @var{x} plus @var{y} would by be @code{nearly-equal}
+to @var{y} itself, to within the current precision, in other words,
+if adding @var{x} to @var{y} would have a negligible effect on @var{y}
+due to roundoff error. @var{X} may be a real or complex number, but
+@var{y} must be real.
+@end defun
+
+@defun is-true x
+Return true if the formula @var{x} represents a true value in
+Calc, not Lisp, terms. It tests if @var{x} is a non-zero number
+or a provably non-zero formula.
+@end defun
+
+@defun reject-arg val pred
+Abort the current function evaluation due to unacceptable argument values.
+This calls @samp{(calc-record-why @var{pred} @var{val})}, then signals a
+Lisp error which @code{normalize} will trap. The net effect is that the
+function call which led here will be left in symbolic form.
+@end defun
+
+@defun inexact-value
+If Symbolic mode is enabled, this will signal an error that causes
+@code{normalize} to leave the formula in symbolic form, with the message
+``Inexact result.'' (This function has no effect when not in Symbolic mode.)
+Note that if your function calls @samp{(sin 5)} in Symbolic mode, the
+@code{sin} function will call @code{inexact-value}, which will cause your
+function to be left unsimplified. You may instead wish to call
+@samp{(normalize (list 'calcFunc-sin 5))}, which in Symbolic mode will
+return the formula @samp{sin(5)} to your function.
+@end defun
+
+@defun overflow
+This signals an error that will be reported as a floating-point overflow.
+@end defun
+
+@defun underflow
+This signals a floating-point underflow.
+@end defun
+
+@node Computational Lisp Functions, Vector Lisp Functions, Predicates, Internals
+@subsubsection Computational Functions
+
+@noindent
+The functions described here do the actual computational work of the
+Calculator. In addition to these, note that any function described in
+the main body of this manual may be called from Lisp; for example, if
+the documentation refers to the @code{calc-sqrt} [@code{sqrt}] command,
+this means @code{calc-sqrt} is an interactive stack-based square-root
+command and @code{sqrt} (which @code{defmath} expands to @code{calcFunc-sqrt})
+is the actual Lisp function for taking square roots.
+
+The functions @code{math-add}, @code{math-sub}, @code{math-mul},
+@code{math-div}, @code{math-mod}, and @code{math-neg} are not included
+in this list, since @code{defmath} allows you to write native Lisp
+@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, and unary @code{-},
+respectively, instead.
+
+@defun normalize val
+(Full form: @code{math-normalize}.)
+Reduce the value @var{val} to standard form. For example, if @var{val}
+is a fixnum, it will be converted to a bignum if it is too large, and
+if @var{val} is a bignum it will be normalized by clipping off trailing
+(i.e., most-significant) zero digits and converting to a fixnum if it is
+small. All the various data types are similarly converted to their standard
+forms. Variables are left alone, but function calls are actually evaluated
+in formulas. For example, normalizing @samp{(+ 2 (calcFunc-abs -4))} will
+return 6.
+
+If a function call fails, because the function is void or has the wrong
+number of parameters, or because it returns @code{nil} or calls
+@code{reject-arg} or @code{inexact-result}, @code{normalize} returns
+the formula still in symbolic form.
+
+If the current simplification mode is ``none'' or ``numeric arguments
+only,'' @code{normalize} will act appropriately. However, the more
+powerful simplification modes (like Algebraic Simplification) are
+not handled by @code{normalize}. They are handled by @code{calc-normalize},
+which calls @code{normalize} and possibly some other routines, such
+as @code{simplify} or @code{simplify-units}. Programs generally will
+never call @code{calc-normalize} except when popping or pushing values
+on the stack.
+@end defun
+
+@defun evaluate-expr expr
+Replace all variables in @var{expr} that have values with their values,
+then use @code{normalize} to simplify the result. This is what happens
+when you press the @kbd{=} key interactively.
+@end defun
+
+@defmac with-extra-prec n body
+Evaluate the Lisp forms in @var{body} with precision increased by @var{n}
+digits. This is a macro which expands to
+
+@smallexample
+(math-normalize
+ (let ((calc-internal-prec (+ calc-internal-prec @var{n})))
+ @var{body}))
+@end smallexample
+
+The surrounding call to @code{math-normalize} causes a floating-point
+result to be rounded down to the original precision afterwards. This
+is important because some arithmetic operations assume a number's
+mantissa contains no more digits than the current precision allows.
+@end defmac
+
+@defun make-frac n d
+Build a fraction @samp{@var{n}:@var{d}}. This is equivalent to calling
+@samp{(normalize (list 'frac @var{n} @var{d}))}, but more efficient.
+@end defun
+
+@defun make-float mant exp
+Build a floating-point value out of @var{mant} and @var{exp}, both
+of which are arbitrary integers. This function will return a
+properly normalized float value, or signal an overflow or underflow
+if @var{exp} is out of range.
+@end defun
+
+@defun make-sdev x sigma
+Build an error form out of @var{x} and the absolute value of @var{sigma}.
+If @var{sigma} is zero, the result is the number @var{x} directly.
+If @var{sigma} is negative or complex, its absolute value is used.
+If @var{x} or @var{sigma} is not a valid type of object for use in
+error forms, this calls @code{reject-arg}.
+@end defun
+
+@defun make-intv mask lo hi
+Build an interval form out of @var{mask} (which is assumed to be an
+integer from 0 to 3), and the limits @var{lo} and @var{hi}. If
+@var{lo} is greater than @var{hi}, an empty interval form is returned.
+This calls @code{reject-arg} if @var{lo} or @var{hi} is unsuitable.
+@end defun
+
+@defun sort-intv mask lo hi
+Build an interval form, similar to @code{make-intv}, except that if
+@var{lo} is less than @var{hi} they are simply exchanged, and the
+bits of @var{mask} are swapped accordingly.
+@end defun
+
+@defun make-mod n m
+Build a modulo form out of @var{n} and the modulus @var{m}. Since modulo
+forms do not allow formulas as their components, if @var{n} or @var{m}
+is not a real number or HMS form the result will be a formula which
+is a call to @code{makemod}, the algebraic version of this function.
+@end defun
+
+@defun float x
+Convert @var{x} to floating-point form. Integers and fractions are
+converted to numerically equivalent floats; components of complex
+numbers, vectors, HMS forms, date forms, error forms, intervals, and
+modulo forms are recursively floated. If the argument is a variable
+or formula, this calls @code{reject-arg}.
+@end defun
+
+@defun compare x y
+Compare the numbers @var{x} and @var{y}, and return @mathit{-1} if
+@samp{(lessp @var{x} @var{y})}, 1 if @samp{(lessp @var{y} @var{x})},
+0 if @samp{(math-equal @var{x} @var{y})}, or 2 if the order is
+undefined or cannot be determined.
+@end defun
+
+@defun numdigs n
+Return the number of digits of integer @var{n}, effectively
+@samp{ceil(log10(@var{n}))}, but much more efficient. Zero is
+considered to have zero digits.
+@end defun
+
+@defun scale-int x n
+Shift integer @var{x} left @var{n} decimal digits, or right @mathit{-@var{n}}
+digits with truncation toward zero.
+@end defun
+
+@defun scale-rounding x n
+Like @code{scale-int}, except that a right shift rounds to the nearest
+integer rather than truncating.
+@end defun
+
+@defun fixnum n
+Return the integer @var{n} as a fixnum, i.e., a native Lisp integer.
+If @var{n} is outside the permissible range for Lisp integers (usually
+24 binary bits) the result is undefined.
+@end defun
+
+@defun sqr x
+Compute the square of @var{x}; short for @samp{(* @var{x} @var{x})}.
+@end defun
+
+@defun quotient x y
+Divide integer @var{x} by integer @var{y}; return an integer quotient
+and discard the remainder. If @var{x} or @var{y} is negative, the
+direction of rounding is undefined.
+@end defun
+
+@defun idiv x y
+Perform an integer division; if @var{x} and @var{y} are both nonnegative
+integers, this uses the @code{quotient} function, otherwise it computes
+@samp{floor(@var{x}/@var{y})}. Thus the result is well-defined but
+slower than for @code{quotient}.
+@end defun
+
+@defun imod x y
+Divide integer @var{x} by integer @var{y}; return the integer remainder
+and discard the quotient. Like @code{quotient}, this works only for
+integer arguments and is not well-defined for negative arguments.
+For a more well-defined result, use @samp{(% @var{x} @var{y})}.
+@end defun
+
+@defun idivmod x y
+Divide integer @var{x} by integer @var{y}; return a cons cell whose
+@code{car} is @samp{(quotient @var{x} @var{y})} and whose @code{cdr}
+is @samp{(imod @var{x} @var{y})}.
+@end defun
+
+@defun pow x y
+Compute @var{x} to the power @var{y}. In @code{defmath} code, this can
+also be written @samp{(^ @var{x} @var{y})} or
+@w{@samp{(expt @var{x} @var{y})}}.
+@end defun
+
+@defun abs-approx x
+Compute a fast approximation to the absolute value of @var{x}. For
+example, for a rectangular complex number the result is the sum of
+the absolute values of the components.
+@end defun
+
+@findex e
+@findex gamma-const
+@findex ln-2
+@findex ln-10
+@findex phi
+@findex pi-over-2
+@findex pi-over-4
+@findex pi-over-180
+@findex sqrt-two-pi
+@findex sqrt-e
+@findex two-pi
+@defun pi
+The function @samp{(pi)} computes @samp{pi} to the current precision.
+Other related constant-generating functions are @code{two-pi},
+@code{pi-over-2}, @code{pi-over-4}, @code{pi-over-180}, @code{sqrt-two-pi},
+@code{e}, @code{sqrt-e}, @code{ln-2}, @code{ln-10}, @code{phi} and
+@code{gamma-const}. Each function returns a floating-point value in the
+current precision, and each uses caching so that all calls after the
+first are essentially free.
+@end defun
+
+@defmac math-defcache @var{func} @var{initial} @var{form}
+This macro, usually used as a top-level call like @code{defun} or
+@code{defvar}, defines a new cached constant analogous to @code{pi}, etc.
+It defines a function @code{func} which returns the requested value;
+if @var{initial} is non-@code{nil} it must be a @samp{(float @dots{})}
+form which serves as an initial value for the cache. If @var{func}
+is called when the cache is empty or does not have enough digits to
+satisfy the current precision, the Lisp expression @var{form} is evaluated
+with the current precision increased by four, and the result minus its
+two least significant digits is stored in the cache. For example,
+calling @samp{(pi)} with a precision of 30 computes @samp{pi} to 34
+digits, rounds it down to 32 digits for future use, then rounds it
+again to 30 digits for use in the present request.
+@end defmac
+
+@findex half-circle
+@findex quarter-circle
+@defun full-circle symb
+If the current angular mode is Degrees or HMS, this function returns the
+integer 360. In Radians mode, this function returns either the
+corresponding value in radians to the current precision, or the formula
+@samp{2*pi}, depending on the Symbolic mode. There are also similar
+function @code{half-circle} and @code{quarter-circle}.
+@end defun
+
+@defun power-of-2 n
+Compute two to the integer power @var{n}, as a (potentially very large)
+integer. Powers of two are cached, so only the first call for a
+particular @var{n} is expensive.
+@end defun
+
+@defun integer-log2 n
+Compute the base-2 logarithm of @var{n}, which must be an integer which
+is a power of two. If @var{n} is not a power of two, this function will
+return @code{nil}.
+@end defun
+
+@defun div-mod a b m
+Divide @var{a} by @var{b}, modulo @var{m}. This returns @code{nil} if
+there is no solution, or if any of the arguments are not integers.
+@end defun
+
+@defun pow-mod a b m
+Compute @var{a} to the power @var{b}, modulo @var{m}. If @var{a},
+@var{b}, and @var{m} are integers, this uses an especially efficient
+algorithm. Otherwise, it simply computes @samp{(% (^ a b) m)}.
+@end defun
+
+@defun isqrt n
+Compute the integer square root of @var{n}. This is the square root
+of @var{n} rounded down toward zero, i.e., @samp{floor(sqrt(@var{n}))}.
+If @var{n} is itself an integer, the computation is especially efficient.
+@end defun
+
+@defun to-hms a ang
+Convert the argument @var{a} into an HMS form. If @var{ang} is specified,
+it is the angular mode in which to interpret @var{a}, either @code{deg}
+or @code{rad}. Otherwise, the current angular mode is used. If @var{a}
+is already an HMS form it is returned as-is.
+@end defun
+
+@defun from-hms a ang
+Convert the HMS form @var{a} into a real number. If @var{ang} is specified,
+it is the angular mode in which to express the result, otherwise the
+current angular mode is used. If @var{a} is already a real number, it
+is returned as-is.
+@end defun
+
+@defun to-radians a
+Convert the number or HMS form @var{a} to radians from the current
+angular mode.
+@end defun
+
+@defun from-radians a
+Convert the number @var{a} from radians to the current angular mode.
+If @var{a} is a formula, this returns the formula @samp{deg(@var{a})}.
+@end defun
+
+@defun to-radians-2 a
+Like @code{to-radians}, except that in Symbolic mode a degrees to
+radians conversion yields a formula like @samp{@var{a}*pi/180}.
+@end defun
+
+@defun from-radians-2 a
+Like @code{from-radians}, except that in Symbolic mode a radians to
+degrees conversion yields a formula like @samp{@var{a}*180/pi}.
+@end defun
+
+@defun random-digit
+Produce a random base-1000 digit in the range 0 to 999.
+@end defun
+
+@defun random-digits n
+Produce a random @var{n}-digit integer; this will be an integer
+in the interval @samp{[0, 10^@var{n})}.
+@end defun
+
+@defun random-float
+Produce a random float in the interval @samp{[0, 1)}.
+@end defun
+
+@defun prime-test n iters
+Determine whether the integer @var{n} is prime. Return a list which has
+one of these forms: @samp{(nil @var{f})} means the number is non-prime
+because it was found to be divisible by @var{f}; @samp{(nil)} means it
+was found to be non-prime by table look-up (so no factors are known);
+@samp{(nil unknown)} means it is definitely non-prime but no factors
+are known because @var{n} was large enough that Fermat's probabilistic
+test had to be used; @samp{(t)} means the number is definitely prime;
+and @samp{(maybe @var{i} @var{p})} means that Fermat's test, after @var{i}
+iterations, is @var{p} percent sure that the number is prime. The
+@var{iters} parameter is the number of Fermat iterations to use, in the
+case that this is necessary. If @code{prime-test} returns ``maybe,''
+you can call it again with the same @var{n} to get a greater certainty;
+@code{prime-test} remembers where it left off.
+@end defun
+
+@defun to-simple-fraction f
+If @var{f} is a floating-point number which can be represented exactly
+as a small rational number. return that number, else return @var{f}.
+For example, 0.75 would be converted to 3:4. This function is very
+fast.
+@end defun
+
+@defun to-fraction f tol
+Find a rational approximation to floating-point number @var{f} to within
+a specified tolerance @var{tol}; this corresponds to the algebraic
+function @code{frac}, and can be rather slow.
+@end defun
+
+@defun quarter-integer n
+If @var{n} is an integer or integer-valued float, this function
+returns zero. If @var{n} is a half-integer (i.e., an integer plus
+@mathit{1:2} or 0.5), it returns 2. If @var{n} is a quarter-integer,
+it returns 1 or 3. If @var{n} is anything else, this function
+returns @code{nil}.
+@end defun
+
+@node Vector Lisp Functions, Symbolic Lisp Functions, Computational Lisp Functions, Internals
+@subsubsection Vector Functions
+
+@noindent
+The functions described here perform various operations on vectors and
+matrices.
+
+@defun math-concat x y
+Do a vector concatenation; this operation is written @samp{@var{x} | @var{y}}
+in a symbolic formula. @xref{Building Vectors}.
+@end defun
+
+@defun vec-length v
+Return the length of vector @var{v}. If @var{v} is not a vector, the
+result is zero. If @var{v} is a matrix, this returns the number of
+rows in the matrix.
+@end defun
+
+@defun mat-dimens m
+Determine the dimensions of vector or matrix @var{m}. If @var{m} is not
+a vector, the result is an empty list. If @var{m} is a plain vector
+but not a matrix, the result is a one-element list containing the length
+of the vector. If @var{m} is a matrix with @var{r} rows and @var{c} columns,
+the result is the list @samp{(@var{r} @var{c})}. Higher-order tensors
+produce lists of more than two dimensions. Note that the object
+@samp{[[1, 2, 3], [4, 5]]} is a vector of vectors not all the same size,
+and is treated by this and other Calc routines as a plain vector of two
+elements.
+@end defun
+
+@defun dimension-error
+Abort the current function with a message of ``Dimension error.''
+The Calculator will leave the function being evaluated in symbolic
+form; this is really just a special case of @code{reject-arg}.
+@end defun
+
+@defun build-vector args
+Return a Calc vector with @var{args} as elements.
+For example, @samp{(build-vector 1 2 3)} returns the Calc vector
+@samp{[1, 2, 3]}, stored internally as the list @samp{(vec 1 2 3)}.
+@end defun
+
+@defun make-vec obj dims
+Return a Calc vector or matrix all of whose elements are equal to
+@var{obj}. For example, @samp{(make-vec 27 3 4)} returns a 3x4 matrix
+filled with 27's.
+@end defun
+
+@defun row-matrix v
+If @var{v} is a plain vector, convert it into a row matrix, i.e.,
+a matrix whose single row is @var{v}. If @var{v} is already a matrix,
+leave it alone.
+@end defun
+
+@defun col-matrix v
+If @var{v} is a plain vector, convert it into a column matrix, i.e., a
+matrix with each element of @var{v} as a separate row. If @var{v} is
+already a matrix, leave it alone.
+@end defun
+
+@defun map-vec f v
+Map the Lisp function @var{f} over the Calc vector @var{v}. For example,
+@samp{(map-vec 'math-floor v)} returns a vector of the floored components
+of vector @var{v}.
+@end defun
+
+@defun map-vec-2 f a b
+Map the Lisp function @var{f} over the two vectors @var{a} and @var{b}.
+If @var{a} and @var{b} are vectors of equal length, the result is a
+vector of the results of calling @samp{(@var{f} @var{ai} @var{bi})}
+for each pair of elements @var{ai} and @var{bi}. If either @var{a} or
+@var{b} is a scalar, it is matched with each value of the other vector.
+For example, @samp{(map-vec-2 'math-add v 1)} returns the vector @var{v}
+with each element increased by one. Note that using @samp{'+} would not
+work here, since @code{defmath} does not expand function names everywhere,
+just where they are in the function position of a Lisp expression.
+@end defun
+
+@defun reduce-vec f v
+Reduce the function @var{f} over the vector @var{v}. For example, if
+@var{v} is @samp{[10, 20, 30, 40]}, this calls @samp{(f (f (f 10 20) 30) 40)}.
+If @var{v} is a matrix, this reduces over the rows of @var{v}.
+@end defun
+
+@defun reduce-cols f m
+Reduce the function @var{f} over the columns of matrix @var{m}. For
+example, if @var{m} is @samp{[[1, 2], [3, 4], [5, 6]]}, the result
+is a vector of the two elements @samp{(f (f 1 3) 5)} and @samp{(f (f 2 4) 6)}.
+@end defun
+
+@defun mat-row m n
+Return the @var{n}th row of matrix @var{m}. This is equivalent to
+@samp{(elt m n)}. For a slower but safer version, use @code{mrow}.
+(@xref{Extracting Elements}.)
+@end defun
+
+@defun mat-col m n
+Return the @var{n}th column of matrix @var{m}, in the form of a vector.
+The arguments are not checked for correctness.
+@end defun
+
+@defun mat-less-row m n
+Return a copy of matrix @var{m} with its @var{n}th row deleted. The
+number @var{n} must be in range from 1 to the number of rows in @var{m}.
+@end defun
+
+@defun mat-less-col m n
+Return a copy of matrix @var{m} with its @var{n}th column deleted.
+@end defun
+
+@defun transpose m
+Return the transpose of matrix @var{m}.
+@end defun
+
+@defun flatten-vector v
+Flatten nested vector @var{v} into a vector of scalars. For example,
+if @var{v} is @samp{[[1, 2, 3], [4, 5]]} the result is @samp{[1, 2, 3, 4, 5]}.
+@end defun
+
+@defun copy-matrix m
+If @var{m} is a matrix, return a copy of @var{m}. This maps
+@code{copy-sequence} over the rows of @var{m}; in Lisp terms, each
+element of the result matrix will be @code{eq} to the corresponding
+element of @var{m}, but none of the @code{cons} cells that make up
+the structure of the matrix will be @code{eq}. If @var{m} is a plain
+vector, this is the same as @code{copy-sequence}.
+@end defun
+
+@defun swap-rows m r1 r2
+Exchange rows @var{r1} and @var{r2} of matrix @var{m} in-place. In
+other words, unlike most of the other functions described here, this
+function changes @var{m} itself rather than building up a new result
+matrix. The return value is @var{m}, i.e., @samp{(eq (swap-rows m 1 2) m)}
+is true, with the side effect of exchanging the first two rows of
+@var{m}.
+@end defun
+
+@node Symbolic Lisp Functions, Formatting Lisp Functions, Vector Lisp Functions, Internals
+@subsubsection Symbolic Functions
+
+@noindent
+The functions described here operate on symbolic formulas in the
+Calculator.
+
+@defun calc-prepare-selection num
+Prepare a stack entry for selection operations. If @var{num} is
+omitted, the stack entry containing the cursor is used; otherwise,
+it is the number of the stack entry to use. This function stores
+useful information about the current stack entry into a set of
+variables. @code{calc-selection-cache-num} contains the number of
+the stack entry involved (equal to @var{num} if you specified it);
+@code{calc-selection-cache-entry} contains the stack entry as a
+list (such as @code{calc-top-list} would return with @code{entry}
+as the selection mode); and @code{calc-selection-cache-comp} contains
+a special ``tagged'' composition (@pxref{Formatting Lisp Functions})
+which allows Calc to relate cursor positions in the buffer with
+their corresponding sub-formulas.
+
+A slight complication arises in the selection mechanism because
+formulas may contain small integers. For example, in the vector
+@samp{[1, 2, 1]} the first and last elements are @code{eq} to each
+other; selections are recorded as the actual Lisp object that
+appears somewhere in the tree of the whole formula, but storing
+@code{1} would falsely select both @code{1}'s in the vector. So
+@code{calc-prepare-selection} also checks the stack entry and
+replaces any plain integers with ``complex number'' lists of the form
+@samp{(cplx @var{n} 0)}. This list will be displayed the same as a
+plain @var{n} and the change will be completely invisible to the
+user, but it will guarantee that no two sub-formulas of the stack
+entry will be @code{eq} to each other. Next time the stack entry
+is involved in a computation, @code{calc-normalize} will replace
+these lists with plain numbers again, again invisibly to the user.
+@end defun
+
+@defun calc-encase-atoms x
+This modifies the formula @var{x} to ensure that each part of the
+formula is a unique atom, using the @samp{(cplx @var{n} 0)} trick
+described above. This function may use @code{setcar} to modify
+the formula in-place.
+@end defun
+
+@defun calc-find-selected-part
+Find the smallest sub-formula of the current formula that contains
+the cursor. This assumes @code{calc-prepare-selection} has been
+called already. If the cursor is not actually on any part of the
+formula, this returns @code{nil}.
+@end defun
+
+@defun calc-change-current-selection selection
+Change the currently prepared stack element's selection to
+@var{selection}, which should be @code{eq} to some sub-formula
+of the stack element, or @code{nil} to unselect the formula.
+The stack element's appearance in the Calc buffer is adjusted
+to reflect the new selection.
+@end defun
+
+@defun calc-find-nth-part expr n
+Return the @var{n}th sub-formula of @var{expr}. This function is used
+by the selection commands, and (unless @kbd{j b} has been used) treats
+sums and products as flat many-element formulas. Thus if @var{expr}
+is @samp{((a + b) - c) + d}, calling @code{calc-find-nth-part} with
+@var{n} equal to four will return @samp{d}.
+@end defun
+
+@defun calc-find-parent-formula expr part
+Return the sub-formula of @var{expr} which immediately contains
+@var{part}. If @var{expr} is @samp{a*b + (c+1)*d} and @var{part}
+is @code{eq} to the @samp{c+1} term of @var{expr}, then this function
+will return @samp{(c+1)*d}. If @var{part} turns out not to be a
+sub-formula of @var{expr}, the function returns @code{nil}. If
+@var{part} is @code{eq} to @var{expr}, the function returns @code{t}.
+This function does not take associativity into account.
+@end defun
+
+@defun calc-find-assoc-parent-formula expr part
+This is the same as @code{calc-find-parent-formula}, except that
+(unless @kbd{j b} has been used) it continues widening the selection
+to contain a complete level of the formula. Given @samp{a} from
+@samp{((a + b) - c) + d}, @code{calc-find-parent-formula} will
+return @samp{a + b} but @code{calc-find-assoc-parent-formula} will
+return the whole expression.
+@end defun
+
+@defun calc-grow-assoc-formula expr part
+This expands sub-formula @var{part} of @var{expr} to encompass a
+complete level of the formula. If @var{part} and its immediate
+parent are not compatible associative operators, or if @kbd{j b}
+has been used, this simply returns @var{part}.
+@end defun
+
+@defun calc-find-sub-formula expr part
+This finds the immediate sub-formula of @var{expr} which contains
+@var{part}. It returns an index @var{n} such that
+@samp{(calc-find-nth-part @var{expr} @var{n})} would return @var{part}.
+If @var{part} is not a sub-formula of @var{expr}, it returns @code{nil}.
+If @var{part} is @code{eq} to @var{expr}, it returns @code{t}. This
+function does not take associativity into account.
+@end defun
+
+@defun calc-replace-sub-formula expr old new
+This function returns a copy of formula @var{expr}, with the
+sub-formula that is @code{eq} to @var{old} replaced by @var{new}.
+@end defun
+
+@defun simplify expr
+Simplify the expression @var{expr} by applying various algebraic rules.
+This is what the @w{@kbd{a s}} (@code{calc-simplify}) command uses. This
+always returns a copy of the expression; the structure @var{expr} points
+to remains unchanged in memory.
+
+More precisely, here is what @code{simplify} does: The expression is
+first normalized and evaluated by calling @code{normalize}. If any
+@code{AlgSimpRules} have been defined, they are then applied. Then
+the expression is traversed in a depth-first, bottom-up fashion; at
+each level, any simplifications that can be made are made until no
+further changes are possible. Once the entire formula has been
+traversed in this way, it is compared with the original formula (from
+before the call to @code{normalize}) and, if it has changed,
+the entire procedure is repeated (starting with @code{normalize})
+until no further changes occur. Usually only two iterations are
+needed:@: one to simplify the formula, and another to verify that no
+further simplifications were possible.
+@end defun
+
+@defun simplify-extended expr
+Simplify the expression @var{expr}, with additional rules enabled that
+help do a more thorough job, while not being entirely ``safe'' in all
+circumstances. (For example, this mode will simplify @samp{sqrt(x^2)}
+to @samp{x}, which is only valid when @var{x} is positive.) This is
+implemented by temporarily binding the variable @code{math-living-dangerously}
+to @code{t} (using a @code{let} form) and calling @code{simplify}.
+Dangerous simplification rules are written to check this variable
+before taking any action.
+@end defun
+
+@defun simplify-units expr
+Simplify the expression @var{expr}, treating variable names as units
+whenever possible. This works by binding the variable
+@code{math-simplifying-units} to @code{t} while calling @code{simplify}.
+@end defun
+
+@defmac math-defsimplify funcs body
+Register a new simplification rule; this is normally called as a top-level
+form, like @code{defun} or @code{defmath}. If @var{funcs} is a symbol
+(like @code{+} or @code{calcFunc-sqrt}), this simplification rule is
+applied to the formulas which are calls to the specified function. Or,
+@var{funcs} can be a list of such symbols; the rule applies to all
+functions on the list. The @var{body} is written like the body of a
+function with a single argument called @code{expr}. The body will be
+executed with @code{expr} bound to a formula which is a call to one of
+the functions @var{funcs}. If the function body returns @code{nil}, or
+if it returns a result @code{equal} to the original @code{expr}, it is
+ignored and Calc goes on to try the next simplification rule that applies.
+If the function body returns something different, that new formula is
+substituted for @var{expr} in the original formula.
+
+At each point in the formula, rules are tried in the order of the
+original calls to @code{math-defsimplify}; the search stops after the
+first rule that makes a change. Thus later rules for that same
+function will not have a chance to trigger until the next iteration
+of the main @code{simplify} loop.
+
+Note that, since @code{defmath} is not being used here, @var{body} must
+be written in true Lisp code without the conveniences that @code{defmath}
+provides. If you prefer, you can have @var{body} simply call another
+function (defined with @code{defmath}) which does the real work.
+
+The arguments of a function call will already have been simplified
+before any rules for the call itself are invoked. Since a new argument
+list is consed up when this happens, this means that the rule's body is
+allowed to rearrange the function's arguments destructively if that is
+convenient. Here is a typical example of a simplification rule:
+
+@smallexample
+(math-defsimplify calcFunc-arcsinh
+ (or (and (math-looks-negp (nth 1 expr))
+ (math-neg (list 'calcFunc-arcsinh
+ (math-neg (nth 1 expr)))))
+ (and (eq (car-safe (nth 1 expr)) 'calcFunc-sinh)
+ (or math-living-dangerously
+ (math-known-realp (nth 1 (nth 1 expr))))
+ (nth 1 (nth 1 expr)))))
+@end smallexample
+
+This is really a pair of rules written with one @code{math-defsimplify}
+for convenience; the first replaces @samp{arcsinh(-x)} with
+@samp{-arcsinh(x)}, and the second, which is safe only for real @samp{x},
+replaces @samp{arcsinh(sinh(x))} with @samp{x}.
+@end defmac
+
+@defun common-constant-factor expr
+Check @var{expr} to see if it is a sum of terms all multiplied by the
+same rational value. If so, return this value. If not, return @code{nil}.
+For example, if called on @samp{6x + 9y + 12z}, it would return 3, since
+3 is a common factor of all the terms.
+@end defun
+
+@defun cancel-common-factor expr factor
+Assuming @var{expr} is a sum with @var{factor} as a common factor,
+divide each term of the sum by @var{factor}. This is done by
+destructively modifying parts of @var{expr}, on the assumption that
+it is being used by a simplification rule (where such things are
+allowed; see above). For example, consider this built-in rule for
+square roots:
+
+@smallexample
+(math-defsimplify calcFunc-sqrt
+ (let ((fac (math-common-constant-factor (nth 1 expr))))
+ (and fac (not (eq fac 1))
+ (math-mul (math-normalize (list 'calcFunc-sqrt fac))
+ (math-normalize
+ (list 'calcFunc-sqrt
+ (math-cancel-common-factor
+ (nth 1 expr) fac)))))))
+@end smallexample
+@end defun
+
+@defun frac-gcd a b
+Compute a ``rational GCD'' of @var{a} and @var{b}, which must both be
+rational numbers. This is the fraction composed of the GCD of the
+numerators of @var{a} and @var{b}, over the GCD of the denominators.
+It is used by @code{common-constant-factor}. Note that the standard
+@code{gcd} function uses the LCM to combine the denominators.
+@end defun
+
+@defun map-tree func expr many
+Try applying Lisp function @var{func} to various sub-expressions of
+@var{expr}. Initially, call @var{func} with @var{expr} itself as an
+argument. If this returns an expression which is not @code{equal} to
+@var{expr}, apply @var{func} again until eventually it does return
+@var{expr} with no changes. Then, if @var{expr} is a function call,
+recursively apply @var{func} to each of the arguments. This keeps going
+until no changes occur anywhere in the expression; this final expression
+is returned by @code{map-tree}. Note that, unlike simplification rules,
+@var{func} functions may @emph{not} make destructive changes to
+@var{expr}. If a third argument @var{many} is provided, it is an
+integer which says how many times @var{func} may be applied; the
+default, as described above, is infinitely many times.
+@end defun
+
+@defun compile-rewrites rules
+Compile the rewrite rule set specified by @var{rules}, which should
+be a formula that is either a vector or a variable name. If the latter,
+the compiled rules are saved so that later @code{compile-rules} calls
+for that same variable can return immediately. If there are problems
+with the rules, this function calls @code{error} with a suitable
+message.
+@end defun
+
+@defun apply-rewrites expr crules heads
+Apply the compiled rewrite rule set @var{crules} to the expression
+@var{expr}. This will make only one rewrite and only checks at the
+top level of the expression. The result @code{nil} if no rules
+matched, or if the only rules that matched did not actually change
+the expression. The @var{heads} argument is optional; if is given,
+it should be a list of all function names that (may) appear in
+@var{expr}. The rewrite compiler tags each rule with the
+rarest-looking function name in the rule; if you specify @var{heads},
+@code{apply-rewrites} can use this information to narrow its search
+down to just a few rules in the rule set.
+@end defun
+
+@defun rewrite-heads expr
+Compute a @var{heads} list for @var{expr} suitable for use with
+@code{apply-rewrites}, as discussed above.
+@end defun
+
+@defun rewrite expr rules many
+This is an all-in-one rewrite function. It compiles the rule set
+specified by @var{rules}, then uses @code{map-tree} to apply the
+rules throughout @var{expr} up to @var{many} (default infinity)
+times.
+@end defun
+
+@defun match-patterns pat vec not-flag
+Given a Calc vector @var{vec} and an uncompiled pattern set or
+pattern set variable @var{pat}, this function returns a new vector
+of all elements of @var{vec} which do (or don't, if @var{not-flag} is
+non-@code{nil}) match any of the patterns in @var{pat}.
+@end defun
+
+@defun deriv expr var value symb
+Compute the derivative of @var{expr} with respect to variable @var{var}
+(which may actually be any sub-expression). If @var{value} is specified,
+the derivative is evaluated at the value of @var{var}; otherwise, the
+derivative is left in terms of @var{var}. If the expression contains
+functions for which no derivative formula is known, new derivative
+functions are invented by adding primes to the names; @pxref{Calculus}.
+However, if @var{symb} is non-@code{nil}, the presence of undifferentiable
+functions in @var{expr} instead cancels the whole differentiation, and
+@code{deriv} returns @code{nil} instead.
+
+Derivatives of an @var{n}-argument function can be defined by
+adding a @code{math-derivative-@var{n}} property to the property list
+of the symbol for the function's derivative, which will be the
+function name followed by an apostrophe. The value of the property
+should be a Lisp function; it is called with the same arguments as the
+original function call that is being differentiated. It should return
+a formula for the derivative. For example, the derivative of @code{ln}
+is defined by
+
+@smallexample
+(put 'calcFunc-ln\' 'math-derivative-1
+ (function (lambda (u) (math-div 1 u))))
+@end smallexample
+
+The two-argument @code{log} function has two derivatives,
+@smallexample
+(put 'calcFunc-log\' 'math-derivative-2 ; d(log(x,b)) / dx
+ (function (lambda (x b) ... )))
+(put 'calcFunc-log\'2 'math-derivative-2 ; d(log(x,b)) / db
+ (function (lambda (x b) ... )))
+@end smallexample
+@end defun
+
+@defun tderiv expr var value symb
+Compute the total derivative of @var{expr}. This is the same as
+@code{deriv}, except that variables other than @var{var} are not
+assumed to be constant with respect to @var{var}.
+@end defun
+
+@defun integ expr var low high
+Compute the integral of @var{expr} with respect to @var{var}.
+@xref{Calculus}, for further details.
+@end defun
+
+@defmac math-defintegral funcs body
+Define a rule for integrating a function or functions of one argument;
+this macro is very similar in format to @code{math-defsimplify}.
+The main difference is that here @var{body} is the body of a function
+with a single argument @code{u} which is bound to the argument to the
+function being integrated, not the function call itself. Also, the
+variable of integration is available as @code{math-integ-var}. If
+evaluation of the integral requires doing further integrals, the body
+should call @samp{(math-integral @var{x})} to find the integral of
+@var{x} with respect to @code{math-integ-var}; this function returns
+@code{nil} if the integral could not be done. Some examples:
+
+@smallexample
+(math-defintegral calcFunc-conj
+ (let ((int (math-integral u)))
+ (and int
+ (list 'calcFunc-conj int))))
+
+(math-defintegral calcFunc-cos
+ (and (equal u math-integ-var)
+ (math-from-radians-2 (list 'calcFunc-sin u))))
+@end smallexample
+
+In the @code{cos} example, we define only the integral of @samp{cos(x) dx},
+relying on the general integration-by-substitution facility to handle
+cosines of more complicated arguments. An integration rule should return
+@code{nil} if it can't do the integral; if several rules are defined for
+the same function, they are tried in order until one returns a non-@code{nil}
+result.
+@end defmac
+
+@defmac math-defintegral-2 funcs body
+Define a rule for integrating a function or functions of two arguments.
+This is exactly analogous to @code{math-defintegral}, except that @var{body}
+is written as the body of a function with two arguments, @var{u} and
+@var{v}.
+@end defmac
+
+@defun solve-for lhs rhs var full
+Attempt to solve the equation @samp{@var{lhs} = @var{rhs}} by isolating
+the variable @var{var} on the lefthand side; return the resulting righthand
+side, or @code{nil} if the equation cannot be solved. The variable
+@var{var} must appear at least once in @var{lhs} or @var{rhs}. Note that
+the return value is a formula which does not contain @var{var}; this is
+different from the user-level @code{solve} and @code{finv} functions,
+which return a rearranged equation or a functional inverse, respectively.
+If @var{full} is non-@code{nil}, a full solution including dummy signs
+and dummy integers will be produced. User-defined inverses are provided
+as properties in a manner similar to derivatives:
+
+@smallexample
+(put 'calcFunc-ln 'math-inverse
+ (function (lambda (x) (list 'calcFunc-exp x))))
+@end smallexample
+
+This function can call @samp{(math-solve-get-sign @var{x})} to create
+a new arbitrary sign variable, returning @var{x} times that sign, and
+@samp{(math-solve-get-int @var{x})} to create a new arbitrary integer
+variable multiplied by @var{x}. These functions simply return @var{x}
+if the caller requested a non-``full'' solution.
+@end defun
+
+@defun solve-eqn expr var full
+This version of @code{solve-for} takes an expression which will
+typically be an equation or inequality. (If it is not, it will be
+interpreted as the equation @samp{@var{expr} = 0}.) It returns an
+equation or inequality, or @code{nil} if no solution could be found.
+@end defun
+
+@defun solve-system exprs vars full
+This function solves a system of equations. Generally, @var{exprs}
+and @var{vars} will be vectors of equal length.
+@xref{Solving Systems of Equations}, for other options.
+@end defun
+
+@defun expr-contains expr var
+Returns a non-@code{nil} value if @var{var} occurs as a subexpression
+of @var{expr}.
+
+This function might seem at first to be identical to
+@code{calc-find-sub-formula}. The key difference is that
+@code{expr-contains} uses @code{equal} to test for matches, whereas
+@code{calc-find-sub-formula} uses @code{eq}. In the formula
+@samp{f(a, a)}, the two @samp{a}s will be @code{equal} but not
+@code{eq} to each other.
+@end defun
+
+@defun expr-contains-count expr var
+Returns the number of occurrences of @var{var} as a subexpression
+of @var{expr}, or @code{nil} if there are no occurrences.
+@end defun
+
+@defun expr-depends expr var
+Returns true if @var{expr} refers to any variable the occurs in @var{var}.
+In other words, it checks if @var{expr} and @var{var} have any variables
+in common.
+@end defun
+
+@defun expr-contains-vars expr
+Return true if @var{expr} contains any variables, or @code{nil} if @var{expr}
+contains only constants and functions with constant arguments.
+@end defun
+
+@defun expr-subst expr old new
+Returns a copy of @var{expr}, with all occurrences of @var{old} replaced
+by @var{new}. This treats @code{lambda} forms specially with respect
+to the dummy argument variables, so that the effect is always to return
+@var{expr} evaluated at @var{old} = @var{new}.
+@end defun
+
+@defun multi-subst expr old new
+This is like @code{expr-subst}, except that @var{old} and @var{new}
+are lists of expressions to be substituted simultaneously. If one
+list is shorter than the other, trailing elements of the longer list
+are ignored.
+@end defun
+
+@defun expr-weight expr
+Returns the ``weight'' of @var{expr}, basically a count of the total
+number of objects and function calls that appear in @var{expr}. For
+``primitive'' objects, this will be one.
+@end defun
+
+@defun expr-height expr
+Returns the ``height'' of @var{expr}, which is the deepest level to
+which function calls are nested. (Note that @samp{@var{a} + @var{b}}
+counts as a function call.) For primitive objects, this returns zero.
+@end defun
+
+@defun polynomial-p expr var
+Check if @var{expr} is a polynomial in variable (or sub-expression)
+@var{var}. If so, return the degree of the polynomial, that is, the
+highest power of @var{var} that appears in @var{expr}. For example,
+for @samp{(x^2 + 3)^3 + 4} this would return 6. This function returns
+@code{nil} unless @var{expr}, when expanded out by @kbd{a x}
+(@code{calc-expand}), would consist of a sum of terms in which @var{var}
+appears only raised to nonnegative integer powers. Note that if
+@var{var} does not occur in @var{expr}, then @var{expr} is considered
+a polynomial of degree 0.
+@end defun
+
+@defun is-polynomial expr var degree loose
+Check if @var{expr} is a polynomial in variable or sub-expression
+@var{var}, and, if so, return a list representation of the polynomial
+where the elements of the list are coefficients of successive powers of
+@var{var}: @samp{@var{a} + @var{b} x + @var{c} x^3} would produce the
+list @samp{(@var{a} @var{b} 0 @var{c})}, and @samp{(x + 1)^2} would
+produce the list @samp{(1 2 1)}. The highest element of the list will
+be non-zero, with the special exception that if @var{expr} is the
+constant zero, the returned value will be @samp{(0)}. Return @code{nil}
+if @var{expr} is not a polynomial in @var{var}. If @var{degree} is
+specified, this will not consider polynomials of degree higher than that
+value. This is a good precaution because otherwise an input of
+@samp{(x+1)^1000} will cause a huge coefficient list to be built. If
+@var{loose} is non-@code{nil}, then a looser definition of a polynomial
+is used in which coefficients are no longer required not to depend on
+@var{var}, but are only required not to take the form of polynomials
+themselves. For example, @samp{sin(x) x^2 + cos(x)} is a loose
+polynomial with coefficients @samp{((calcFunc-cos x) 0 (calcFunc-sin
+x))}. The result will never be @code{nil} in loose mode, since any
+expression can be interpreted as a ``constant'' loose polynomial.
+@end defun
+
+@defun polynomial-base expr pred
+Check if @var{expr} is a polynomial in any variable that occurs in it;
+if so, return that variable. (If @var{expr} is a multivariate polynomial,
+this chooses one variable arbitrarily.) If @var{pred} is specified, it should
+be a Lisp function which is called as @samp{(@var{pred} @var{subexpr})},
+and which should return true if @code{mpb-top-expr} (a global name for
+the original @var{expr}) is a suitable polynomial in @var{subexpr}.
+The default predicate uses @samp{(polynomial-p mpb-top-expr @var{subexpr})};
+you can use @var{pred} to specify additional conditions. Or, you could
+have @var{pred} build up a list of every suitable @var{subexpr} that
+is found.
+@end defun
+
+@defun poly-simplify poly
+Simplify polynomial coefficient list @var{poly} by (destructively)
+clipping off trailing zeros.
+@end defun
+
+@defun poly-mix a ac b bc
+Mix two polynomial lists @var{a} and @var{b} (in the form returned by
+@code{is-polynomial}) in a linear combination with coefficient expressions
+@var{ac} and @var{bc}. The result is a (not necessarily simplified)
+polynomial list representing @samp{@var{ac} @var{a} + @var{bc} @var{b}}.
+@end defun
+
+@defun poly-mul a b
+Multiply two polynomial coefficient lists @var{a} and @var{b}. The
+result will be in simplified form if the inputs were simplified.
+@end defun
+
+@defun build-polynomial-expr poly var
+Construct a Calc formula which represents the polynomial coefficient
+list @var{poly} applied to variable @var{var}. The @kbd{a c}
+(@code{calc-collect}) command uses @code{is-polynomial} to turn an
+expression into a coefficient list, then @code{build-polynomial-expr}
+to turn the list back into an expression in regular form.
+@end defun
+
+@defun check-unit-name var
+Check if @var{var} is a variable which can be interpreted as a unit
+name. If so, return the units table entry for that unit. This
+will be a list whose first element is the unit name (not counting
+prefix characters) as a symbol and whose second element is the
+Calc expression which defines the unit. (Refer to the Calc sources
+for details on the remaining elements of this list.) If @var{var}
+is not a variable or is not a unit name, return @code{nil}.
+@end defun
+
+@defun units-in-expr-p expr sub-exprs
+Return true if @var{expr} contains any variables which can be
+interpreted as units. If @var{sub-exprs} is @code{t}, the entire
+expression is searched. If @var{sub-exprs} is @code{nil}, this
+checks whether @var{expr} is directly a units expression.
+@end defun
+
+@defun single-units-in-expr-p expr
+Check whether @var{expr} contains exactly one units variable. If so,
+return the units table entry for the variable. If @var{expr} does
+not contain any units, return @code{nil}. If @var{expr} contains
+two or more units, return the symbol @code{wrong}.
+@end defun
+
+@defun to-standard-units expr which
+Convert units expression @var{expr} to base units. If @var{which}
+is @code{nil}, use Calc's native base units. Otherwise, @var{which}
+can specify a units system, which is a list of two-element lists,
+where the first element is a Calc base symbol name and the second
+is an expression to substitute for it.
+@end defun
+
+@defun remove-units expr
+Return a copy of @var{expr} with all units variables replaced by ones.
+This expression is generally normalized before use.
+@end defun
+
+@defun extract-units expr
+Return a copy of @var{expr} with everything but units variables replaced
+by ones.
+@end defun
+
+@node Formatting Lisp Functions, Hooks, Symbolic Lisp Functions, Internals
+@subsubsection I/O and Formatting Functions
+
+@noindent
+The functions described here are responsible for parsing and formatting
+Calc numbers and formulas.
+
+@defun calc-eval str sep arg1 arg2 @dots{}
+This is the simplest interface to the Calculator from another Lisp program.
+@xref{Calling Calc from Your Programs}.
+@end defun
+
+@defun read-number str
+If string @var{str} contains a valid Calc number, either integer,
+fraction, float, or HMS form, this function parses and returns that
+number. Otherwise, it returns @code{nil}.
+@end defun
+
+@defun read-expr str
+Read an algebraic expression from string @var{str}. If @var{str} does
+not have the form of a valid expression, return a list of the form
+@samp{(error @var{pos} @var{msg})} where @var{pos} is an integer index
+into @var{str} of the general location of the error, and @var{msg} is
+a string describing the problem.
+@end defun
+
+@defun read-exprs str
+Read a list of expressions separated by commas, and return it as a
+Lisp list. If an error occurs in any expressions, an error list as
+shown above is returned instead.
+@end defun
+
+@defun calc-do-alg-entry initial prompt no-norm
+Read an algebraic formula or formulas using the minibuffer. All
+conventions of regular algebraic entry are observed. The return value
+is a list of Calc formulas; there will be more than one if the user
+entered a list of values separated by commas. The result is @code{nil}
+if the user presses Return with a blank line. If @var{initial} is
+given, it is a string which the minibuffer will initially contain.
+If @var{prompt} is given, it is the prompt string to use; the default
+is ``Algebraic:''. If @var{no-norm} is @code{t}, the formulas will
+be returned exactly as parsed; otherwise, they will be passed through
+@code{calc-normalize} first.
+
+To support the use of @kbd{$} characters in the algebraic entry, use
+@code{let} to bind @code{calc-dollar-values} to a list of the values
+to be substituted for @kbd{$}, @kbd{$$}, and so on, and bind
+@code{calc-dollar-used} to 0. Upon return, @code{calc-dollar-used}
+will have been changed to the highest number of consecutive @kbd{$}s
+that actually appeared in the input.
+@end defun
+
+@defun format-number a
+Convert the real or complex number or HMS form @var{a} to string form.
+@end defun
+
+@defun format-flat-expr a prec
+Convert the arbitrary Calc number or formula @var{a} to string form,
+in the style used by the trail buffer and the @code{calc-edit} command.
+This is a simple format designed
+mostly to guarantee the string is of a form that can be re-parsed by
+@code{read-expr}. Most formatting modes, such as digit grouping,
+complex number format, and point character, are ignored to ensure the
+result will be re-readable. The @var{prec} parameter is normally 0; if
+you pass a large integer like 1000 instead, the expression will be
+surrounded by parentheses unless it is a plain number or variable name.
+@end defun
+
+@defun format-nice-expr a width
+This is like @code{format-flat-expr} (with @var{prec} equal to 0),
+except that newlines will be inserted to keep lines down to the
+specified @var{width}, and vectors that look like matrices or rewrite
+rules are written in a pseudo-matrix format. The @code{calc-edit}
+command uses this when only one stack entry is being edited.
+@end defun
+
+@defun format-value a width
+Convert the Calc number or formula @var{a} to string form, using the
+format seen in the stack buffer. Beware the string returned may
+not be re-readable by @code{read-expr}, for example, because of digit
+grouping. Multi-line objects like matrices produce strings that
+contain newline characters to separate the lines. The @var{w}
+parameter, if given, is the target window size for which to format
+the expressions. If @var{w} is omitted, the width of the Calculator
+window is used.
+@end defun
+
+@defun compose-expr a prec
+Format the Calc number or formula @var{a} according to the current
+language mode, returning a ``composition.'' To learn about the
+structure of compositions, see the comments in the Calc source code.
+You can specify the format of a given type of function call by putting
+a @code{math-compose-@var{lang}} property on the function's symbol,
+whose value is a Lisp function that takes @var{a} and @var{prec} as
+arguments and returns a composition. Here @var{lang} is a language
+mode name, one of @code{normal}, @code{big}, @code{c}, @code{pascal},
+@code{fortran}, @code{tex}, @code{eqn}, @code{math}, or @code{maple}.
+In Big mode, Calc actually tries @code{math-compose-big} first, then
+tries @code{math-compose-normal}. If this property does not exist,
+or if the function returns @code{nil}, the function is written in the
+normal function-call notation for that language.
+@end defun
+
+@defun composition-to-string c w
+Convert a composition structure returned by @code{compose-expr} into
+a string. Multi-line compositions convert to strings containing
+newline characters. The target window size is given by @var{w}.
+The @code{format-value} function basically calls @code{compose-expr}
+followed by @code{composition-to-string}.
+@end defun
+
+@defun comp-width c
+Compute the width in characters of composition @var{c}.
+@end defun
+
+@defun comp-height c
+Compute the height in lines of composition @var{c}.
+@end defun
+
+@defun comp-ascent c
+Compute the portion of the height of composition @var{c} which is on or
+above the baseline. For a one-line composition, this will be one.
+@end defun
+
+@defun comp-descent c
+Compute the portion of the height of composition @var{c} which is below
+the baseline. For a one-line composition, this will be zero.
+@end defun
+
+@defun comp-first-char c
+If composition @var{c} is a ``flat'' composition, return the first
+(leftmost) character of the composition as an integer. Otherwise,
+return @code{nil}.
+@end defun
+
+@defun comp-last-char c
+If composition @var{c} is a ``flat'' composition, return the last
+(rightmost) character, otherwise return @code{nil}.
+@end defun
+
+@comment @node Lisp Variables, Hooks, Formatting Lisp Functions, Internals
+@comment @subsubsection Lisp Variables
+@comment
+@comment @noindent
+@comment (This section is currently unfinished.)
+
+@node Hooks, , Formatting Lisp Functions, Internals
+@subsubsection Hooks
+
+@noindent
+Hooks are variables which contain Lisp functions (or lists of functions)
+which are called at various times. Calc defines a number of hooks
+that help you to customize it in various ways. Calc uses the Lisp
+function @code{run-hooks} to invoke the hooks shown below. Several
+other customization-related variables are also described here.
+
+@defvar calc-load-hook
+This hook is called at the end of @file{calc.el}, after the file has
+been loaded, before any functions in it have been called, but after
+@code{calc-mode-map} and similar variables have been set up.
+@end defvar
+
+@defvar calc-ext-load-hook
+This hook is called at the end of @file{calc-ext.el}.
+@end defvar
+
+@defvar calc-start-hook
+This hook is called as the last step in a @kbd{M-x calc} command.
+At this point, the Calc buffer has been created and initialized if
+necessary, the Calc window and trail window have been created,
+and the ``Welcome to Calc'' message has been displayed.
+@end defvar
+
+@defvar calc-mode-hook
+This hook is called when the Calc buffer is being created. Usually
+this will only happen once per Emacs session. The hook is called
+after Emacs has switched to the new buffer, the mode-settings file
+has been read if necessary, and all other buffer-local variables
+have been set up. After this hook returns, Calc will perform a
+@code{calc-refresh} operation, set up the mode line display, then
+evaluate any deferred @code{calc-define} properties that have not
+been evaluated yet.
+@end defvar
+
+@defvar calc-trail-mode-hook
+This hook is called when the Calc Trail buffer is being created.
+It is called as the very last step of setting up the Trail buffer.
+Like @code{calc-mode-hook}, this will normally happen only once
+per Emacs session.
+@end defvar
+
+@defvar calc-end-hook
+This hook is called by @code{calc-quit}, generally because the user
+presses @kbd{q} or @kbd{C-x * c} while in Calc. The Calc buffer will
+be the current buffer. The hook is called as the very first
+step, before the Calc window is destroyed.
+@end defvar
+
+@defvar calc-window-hook
+If this hook is non-@code{nil}, it is called to create the Calc window.
+Upon return, this new Calc window should be the current window.
+(The Calc buffer will already be the current buffer when the
+hook is called.) If the hook is not defined, Calc will
+generally use @code{split-window}, @code{set-window-buffer},
+and @code{select-window} to create the Calc window.
+@end defvar
+
+@defvar calc-trail-window-hook
+If this hook is non-@code{nil}, it is called to create the Calc Trail
+window. The variable @code{calc-trail-buffer} will contain the buffer
+which the window should use. Unlike @code{calc-window-hook}, this hook
+must @emph{not} switch into the new window.
+@end defvar
+
+@defvar calc-embedded-mode-hook
+This hook is called the first time that Embedded mode is entered.
+@end defvar
+
+@defvar calc-embedded-new-buffer-hook
+This hook is called each time that Embedded mode is entered in a
+new buffer.
+@end defvar
+
+@defvar calc-embedded-new-formula-hook
+This hook is called each time that Embedded mode is enabled for a
+new formula.
+@end defvar
+
+@defvar calc-edit-mode-hook
+This hook is called by @code{calc-edit} (and the other ``edit''
+commands) when the temporary editing buffer is being created.
+The buffer will have been selected and set up to be in
+@code{calc-edit-mode}, but will not yet have been filled with
+text. (In fact it may still have leftover text from a previous
+@code{calc-edit} command.)
+@end defvar
+
+@defvar calc-mode-save-hook
+This hook is called by the @code{calc-save-modes} command,
+after Calc's own mode features have been inserted into the
+Calc init file and just before the ``End of mode settings''
+message is inserted.
+@end defvar
+
+@defvar calc-reset-hook
+This hook is called after @kbd{C-x * 0} (@code{calc-reset}) has
+reset all modes. The Calc buffer will be the current buffer.
+@end defvar
+
+@defvar calc-other-modes
+This variable contains a list of strings. The strings are
+concatenated at the end of the modes portion of the Calc
+mode line (after standard modes such as ``Deg'', ``Inv'' and
+``Hyp''). Each string should be a short, single word followed
+by a space. The variable is @code{nil} by default.
+@end defvar
+
+@defvar calc-mode-map
+This is the keymap that is used by Calc mode. The best time
+to adjust it is probably in a @code{calc-mode-hook}. If the
+Calc extensions package (@file{calc-ext.el}) has not yet been
+loaded, many of these keys will be bound to @code{calc-missing-key},
+which is a command that loads the extensions package and
+``retypes'' the key. If your @code{calc-mode-hook} rebinds
+one of these keys, it will probably be overridden when the
+extensions are loaded.
+@end defvar
+
+@defvar calc-digit-map
+This is the keymap that is used during numeric entry. Numeric
+entry uses the minibuffer, but this map binds every non-numeric
+key to @code{calcDigit-nondigit} which generally calls
+@code{exit-minibuffer} and ``retypes'' the key.
+@end defvar
+
+@defvar calc-alg-ent-map
+This is the keymap that is used during algebraic entry. This is
+mostly a copy of @code{minibuffer-local-map}.
+@end defvar
+
+@defvar calc-store-var-map
+This is the keymap that is used during entry of variable names for
+commands like @code{calc-store} and @code{calc-recall}. This is
+mostly a copy of @code{minibuffer-local-completion-map}.
+@end defvar
+
+@defvar calc-edit-mode-map
+This is the (sparse) keymap used by @code{calc-edit} and other
+temporary editing commands. It binds @key{RET}, @key{LFD},
+and @kbd{C-c C-c} to @code{calc-edit-finish}.
+@end defvar
+
+@defvar calc-mode-var-list
+This is a list of variables which are saved by @code{calc-save-modes}.
+Each entry is a list of two items, the variable (as a Lisp symbol)
+and its default value. When modes are being saved, each variable
+is compared with its default value (using @code{equal}) and any
+non-default variables are written out.
+@end defvar
+
+@defvar calc-local-var-list
+This is a list of variables which should be buffer-local to the
+Calc buffer. Each entry is a variable name (as a Lisp symbol).
+These variables also have their default values manipulated by
+the @code{calc} and @code{calc-quit} commands; @pxref{Multiple Calculators}.
+Since @code{calc-mode-hook} is called after this list has been
+used the first time, your hook should add a variable to the
+list and also call @code{make-local-variable} itself.
+@end defvar
+
+@node Copying, GNU Free Documentation License, Programming, Top
+@appendix GNU GENERAL PUBLIC LICENSE
+@include gpl.texi
+
+@node GNU Free Documentation License, Customizing Calc, Copying, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Customizing Calc, Reporting Bugs, GNU Free Documentation License, Top
+@appendix Customizing Calc
+
+The usual prefix for Calc is the key sequence @kbd{C-x *}. If you wish
+to use a different prefix, you can put
+
+@example
+(global-set-key "NEWPREFIX" 'calc-dispatch)
+@end example
+
+@noindent
+in your .emacs file.
+(@xref{Key Bindings,,Customizing Key Bindings,emacs,
+The GNU Emacs Manual}, for more information on binding keys.)
+A convenient way to start Calc is with @kbd{C-x * *}; to make it equally
+convenient for users who use a different prefix, the prefix can be
+followed by @kbd{=}, @kbd{&}, @kbd{#}, @kbd{\}, @kbd{/}, @kbd{+} or
+@kbd{-} as well as @kbd{*} to start Calc, and so in many cases the last
+character of the prefix can simply be typed twice.
+
+Calc is controlled by many variables, most of which can be reset
+from within Calc. Some variables are less involved with actual
+calculation, and can be set outside of Calc using Emacs's
+customization facilities. These variables are listed below.
+Typing @kbd{M-x customize-variable RET @var{variable-name} RET}
+will bring up a buffer in which the variable's value can be redefined.
+Typing @kbd{M-x customize-group RET calc RET} will bring up a buffer which
+contains all of Calc's customizable variables. (These variables can
+also be reset by putting the appropriate lines in your .emacs file;
+@xref{Init File, ,Init File, emacs, The GNU Emacs Manual}.)
+
+Some of the customizable variables are regular expressions. A regular
+expression is basically a pattern that Calc can search for.
+See @ref{Regexp Search,, Regular Expression Search, emacs, The GNU Emacs Manual}
+to see how regular expressions work.
+
+@defvar calc-settings-file
+The variable @code{calc-settings-file} holds the file name in
+which commands like @kbd{m m} and @kbd{Z P} store ``permanent''
+definitions.
+If @code{calc-settings-file} is not your user init file (typically
+@file{~/.emacs}) and if the variable @code{calc-loaded-settings-file} is
+@code{nil}, then Calc will automatically load your settings file (if it
+exists) the first time Calc is invoked.
+
+The default value for this variable is @code{"~/.calc.el"}.
+@end defvar
+
+@defvar calc-gnuplot-name
+See @ref{Graphics}.@*
+The variable @code{calc-gnuplot-name} should be the name of the
+GNUPLOT program (a string). If you have GNUPLOT installed on your
+system but Calc is unable to find it, you may need to set this
+variable. You may also need to set some Lisp variables to show Calc how
+to run GNUPLOT on your system, see @ref{Devices, ,Graphical Devices} .
+The default value of @code{calc-gnuplot-name} is @code{"gnuplot"}.
+@end defvar
+
+@defvar calc-gnuplot-plot-command
+@defvarx calc-gnuplot-print-command
+See @ref{Devices, ,Graphical Devices}.@*
+The variables @code{calc-gnuplot-plot-command} and
+@code{calc-gnuplot-print-command} represent system commands to
+display and print the output of GNUPLOT, respectively. These may be
+@code{nil} if no command is necessary, or strings which can include
+@samp{%s} to signify the name of the file to be displayed or printed.
+Or, these variables may contain Lisp expressions which are evaluated
+to display or print the output.
+
+The default value of @code{calc-gnuplot-plot-command} is @code{nil},
+and the default value of @code{calc-gnuplot-print-command} is
+@code{"lp %s"}.
+@end defvar
+
+@defvar calc-language-alist
+See @ref{Basic Embedded Mode}.@*
+The variable @code{calc-language-alist} controls the languages that
+Calc will associate with major modes. When Calc embedded mode is
+enabled, it will try to use the current major mode to
+determine what language should be used. (This can be overridden using
+Calc's mode changing commands, @xref{Mode Settings in Embedded Mode}.)
+The variable @code{calc-language-alist} consists of a list of pairs of
+the form @code{(@var{MAJOR-MODE} . @var{LANGUAGE})}; for example,
+@code{(latex-mode . latex)} is one such pair. If Calc embedded is
+activated in a buffer whose major mode is @var{MAJOR-MODE}, it will set itself
+to use the language @var{LANGUAGE}.
+
+The default value of @code{calc-language-alist} is
+@example
+ ((latex-mode . latex)
+ (tex-mode . tex)
+ (plain-tex-mode . tex)
+ (context-mode . tex)
+ (nroff-mode . eqn)
+ (pascal-mode . pascal)
+ (c-mode . c)
+ (c++-mode . c)
+ (fortran-mode . fortran)
+ (f90-mode . fortran))
+@end example
+@end defvar
+
+@defvar calc-embedded-announce-formula
+@defvarx calc-embedded-announce-formula-alist
+See @ref{Customizing Embedded Mode}.@*
+The variable @code{calc-embedded-announce-formula} helps determine
+what formulas @kbd{C-x * a} will activate in a buffer. It is a
+regular expression, and when activating embedded formulas with
+@kbd{C-x * a}, it will tell Calc that what follows is a formula to be
+activated. (Calc also uses other patterns to find formulas, such as
+@samp{=>} and @samp{:=}.)
+
+The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, which checks
+for @samp{%Embed} followed by any number of lines beginning with
+@samp{%} and a space.
+
+The variable @code{calc-embedded-announce-formula-alist} is used to
+set @code{calc-embedded-announce-formula} to different regular
+expressions depending on the major mode of the editing buffer.
+It consists of a list of pairs of the form @code{(@var{MAJOR-MODE} .
+@var{REGEXP})}, and its default value is
+@example
+ ((c++-mode . "//Embed\n\\(// .*\n\\)*")
+ (c-mode . "/\\*Embed\\*/\n\\(/\\* .*\\*/\n\\)*")
+ (f90-mode . "!Embed\n\\(! .*\n\\)*")
+ (fortran-mode . "C Embed\n\\(C .*\n\\)*")
+ (html-helper-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
+ (html-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
+ (nroff-mode . "\\\\\"Embed\n\\(\\\\\" .*\n\\)*")
+ (pascal-mode . "@{Embed@}\n\\(@{.*@}\n\\)*")
+ (sgml-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
+ (xml-mode . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
+ (texinfo-mode . "@@c Embed\n\\(@@c .*\n\\)*"))
+@end example
+Any major modes added to @code{calc-embedded-announce-formula-alist}
+should also be added to @code{calc-embedded-open-close-plain-alist}
+and @code{calc-embedded-open-close-mode-alist}.
+@end defvar
+
+@defvar calc-embedded-open-formula
+@defvarx calc-embedded-close-formula
+@defvarx calc-embedded-open-close-formula-alist
+See @ref{Customizing Embedded Mode}.@*
+The variables @code{calc-embedded-open-formula} and
+@code{calc-embedded-open-formula} control the region that Calc will
+activate as a formula when Embedded mode is entered with @kbd{C-x * e}.
+They are regular expressions;
+Calc normally scans backward and forward in the buffer for the
+nearest text matching these regular expressions to be the ``formula
+delimiters''.
+
+The simplest delimiters are blank lines. Other delimiters that
+Embedded mode understands by default are:
+@enumerate
+@item
+The @TeX{} and La@TeX{} math delimiters @samp{$ $}, @samp{$$ $$},
+@samp{\[ \]}, and @samp{\( \)};
+@item
+Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters);
+@item
+Lines beginning with @samp{@@} (Texinfo delimiters).
+@item
+Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters);
+@item
+Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else.
+@end enumerate
+
+The variable @code{calc-embedded-open-close-formula-alist} is used to
+set @code{calc-embedded-open-formula} and
+@code{calc-embedded-close-formula} to different regular
+expressions depending on the major mode of the editing buffer.
+It consists of a list of lists of the form
+@code{(@var{MAJOR-MODE} @var{OPEN-FORMULA-REGEXP}
+@var{CLOSE-FORMULA-REGEXP})}, and its default value is
+@code{nil}.
+@end defvar
+
+@defvar calc-embedded-open-word
+@defvarx calc-embedded-close-word
+@defvarx calc-embedded-open-close-word-alist
+See @ref{Customizing Embedded Mode}.@*
+The variables @code{calc-embedded-open-word} and
+@code{calc-embedded-close-word} control the region that Calc will
+activate when Embedded mode is entered with @kbd{C-x * w}. They are
+regular expressions.
+
+The default values of @code{calc-embedded-open-word} and
+@code{calc-embedded-close-word} are @code{"^\\|[^-+0-9.eE]"} and
+@code{"$\\|[^-+0-9.eE]"} respectively.
+
+The variable @code{calc-embedded-open-close-word-alist} is used to
+set @code{calc-embedded-open-word} and
+@code{calc-embedded-close-word} to different regular
+expressions depending on the major mode of the editing buffer.
+It consists of a list of lists of the form
+@code{(@var{MAJOR-MODE} @var{OPEN-WORD-REGEXP}
+@var{CLOSE-WORD-REGEXP})}, and its default value is
+@code{nil}.
+@end defvar
+
+@defvar calc-embedded-open-plain
+@defvarx calc-embedded-close-plain
+@defvarx calc-embedded-open-close-plain-alist
+See @ref{Customizing Embedded Mode}.@*
+The variables @code{calc-embedded-open-plain} and
+@code{calc-embedded-open-plain} are used to delimit ``plain''
+formulas. Note that these are actual strings, not regular
+expressions, because Calc must be able to write these string into a
+buffer as well as to recognize them.
+
+The default string for @code{calc-embedded-open-plain} is
+@code{"%%% "}, note the trailing space. The default string for
+@code{calc-embedded-close-plain} is @code{" %%%\n"}, without
+the trailing newline here, the first line of a Big mode formula
+that followed might be shifted over with respect to the other lines.
+
+The variable @code{calc-embedded-open-close-plain-alist} is used to
+set @code{calc-embedded-open-plain} and
+@code{calc-embedded-close-plain} to different strings
+depending on the major mode of the editing buffer.
+It consists of a list of lists of the form
+@code{(@var{MAJOR-MODE} @var{OPEN-PLAIN-STRING}
+@var{CLOSE-PLAIN-STRING})}, and its default value is
+@example
+ ((c++-mode "// %% " " %%\n")
+ (c-mode "/* %% " " %% */\n")
+ (f90-mode "! %% " " %%\n")
+ (fortran-mode "C %% " " %%\n")
+ (html-helper-mode "<!-- %% " " %% -->\n")
+ (html-mode "<!-- %% " " %% -->\n")
+ (nroff-mode "\\\" %% " " %%\n")
+ (pascal-mode "@{%% " " %%@}\n")
+ (sgml-mode "<!-- %% " " %% -->\n")
+ (xml-mode "<!-- %% " " %% -->\n")
+ (texinfo-mode "@@c %% " " %%\n"))
+@end example
+Any major modes added to @code{calc-embedded-open-close-plain-alist}
+should also be added to @code{calc-embedded-announce-formula-alist}
+and @code{calc-embedded-open-close-mode-alist}.
+@end defvar
+
+@defvar calc-embedded-open-new-formula
+@defvarx calc-embedded-close-new-formula
+@defvarx calc-embedded-open-close-new-formula-alist
+See @ref{Customizing Embedded Mode}.@*
+The variables @code{calc-embedded-open-new-formula} and
+@code{calc-embedded-close-new-formula} are strings which are
+inserted before and after a new formula when you type @kbd{C-x * f}.
+
+The default value of @code{calc-embedded-open-new-formula} is
+@code{"\n\n"}. If this string begins with a newline character and the
+@kbd{C-x * f} is typed at the beginning of a line, @kbd{C-x * f} will skip
+this first newline to avoid introducing unnecessary blank lines in the
+file. The default value of @code{calc-embedded-close-new-formula} is
+also @code{"\n\n"}. The final newline is omitted by @w{@kbd{C-x * f}}
+if typed at the end of a line. (It follows that if @kbd{C-x * f} is
+typed on a blank line, both a leading opening newline and a trailing
+closing newline are omitted.)
+
+The variable @code{calc-embedded-open-close-new-formula-alist} is used to
+set @code{calc-embedded-open-new-formula} and
+@code{calc-embedded-close-new-formula} to different strings
+depending on the major mode of the editing buffer.
+It consists of a list of lists of the form
+@code{(@var{MAJOR-MODE} @var{OPEN-NEW-FORMULA-STRING}
+@var{CLOSE-NEW-FORMULA-STRING})}, and its default value is
+@code{nil}.
+@end defvar
+
+@defvar calc-embedded-open-mode
+@defvarx calc-embedded-close-mode
+@defvarx calc-embedded-open-close-mode-alist
+See @ref{Customizing Embedded Mode}.@*
+The variables @code{calc-embedded-open-mode} and
+@code{calc-embedded-close-mode} are strings which Calc will place before
+and after any mode annotations that it inserts. Calc never scans for
+these strings; Calc always looks for the annotation itself, so it is not
+necessary to add them to user-written annotations.
+
+The default value of @code{calc-embedded-open-mode} is @code{"% "}
+and the default value of @code{calc-embedded-close-mode} is
+@code{"\n"}.
+If you change the value of @code{calc-embedded-close-mode}, it is a good
+idea still to end with a newline so that mode annotations will appear on
+lines by themselves.
+
+The variable @code{calc-embedded-open-close-mode-alist} is used to
+set @code{calc-embedded-open-mode} and
+@code{calc-embedded-close-mode} to different strings
+expressions depending on the major mode of the editing buffer.
+It consists of a list of lists of the form
+@code{(@var{MAJOR-MODE} @var{OPEN-MODE-STRING}
+@var{CLOSE-MODE-STRING})}, and its default value is
+@example
+ ((c++-mode "// " "\n")
+ (c-mode "/* " " */\n")
+ (f90-mode "! " "\n")
+ (fortran-mode "C " "\n")
+ (html-helper-mode "<!-- " " -->\n")
+ (html-mode "<!-- " " -->\n")
+ (nroff-mode "\\\" " "\n")
+ (pascal-mode "@{ " " @}\n")
+ (sgml-mode "<!-- " " -->\n")
+ (xml-mode "<!-- " " -->\n")
+ (texinfo-mode "@@c " "\n"))
+@end example
+Any major modes added to @code{calc-embedded-open-close-mode-alist}
+should also be added to @code{calc-embedded-announce-formula-alist}
+and @code{calc-embedded-open-close-plain-alist}.
+@end defvar
+
+@defvar calc-multiplication-has-precedence
+The variable @code{calc-multiplication-has-precedence} determines
+whether multiplication has precedence over division in algebraic formulas
+in normal language modes. If @code{calc-multiplication-has-precedence}
+is non-@code{nil}, then multiplication has precedence, and so for
+example @samp{a/b*c} will be interpreted as @samp{a/(b*c)}. If
+@code{calc-multiplication-has-precedence} is @code{nil}, then
+multiplication has the same precedence as division, and so for example
+@samp{a/b*c} will be interpreted as @samp{(a/b)*c}. The default value
+of @code{calc-multiplication-has-precedence} is @code{t}.
+@end defvar
+
+@node Reporting Bugs, Summary, Customizing Calc, Top
+@appendix Reporting Bugs
+
+@noindent
+If you find a bug in Calc, send e-mail to Jay Belanger,
+
+@example
+jay.p.belanger@@gmail.com
+@end example
+
+@noindent
+There is an automatic command @kbd{M-x report-calc-bug} which helps
+you to report bugs. This command prompts you for a brief subject
+line, then leaves you in a mail editing buffer. Type @kbd{C-c C-c} to
+send your mail. Make sure your subject line indicates that you are
+reporting a Calc bug; this command sends mail to the maintainer's
+regular mailbox.
+
+If you have suggestions for additional features for Calc, please send
+them. Some have dared to suggest that Calc is already top-heavy with
+features; this obviously cannot be the case, so if you have ideas, send
+them right in.
+
+At the front of the source file, @file{calc.el}, is a list of ideas for
+future work. If any enthusiastic souls wish to take it upon themselves
+to work on these, please send a message (using @kbd{M-x report-calc-bug})
+so any efforts can be coordinated.
+
+The latest version of Calc is available from Savannah, in the Emacs
+CVS tree. See @uref{http://savannah.gnu.org/projects/emacs}.
+
+@c [summary]
+@node Summary, Key Index, Reporting Bugs, Top
+@appendix Calc Summary
+
+@noindent
+This section includes a complete list of Calc 2.1 keystroke commands.
+Each line lists the stack entries used by the command (top-of-stack
+last), the keystrokes themselves, the prompts asked by the command,
+and the result of the command (also with top-of-stack last).
+The result is expressed using the equivalent algebraic function.
+Commands which put no results on the stack show the full @kbd{M-x}
+command name in that position. Numbers preceding the result or
+command name refer to notes at the end.
+
+Algebraic functions and @kbd{M-x} commands that don't have corresponding
+keystrokes are not listed in this summary.
+@xref{Command Index}. @xref{Function Index}.
+
+@iftex
+@begingroup
+@tex
+\vskip-2\baselineskip \null
+\gdef\sumrow#1{\sumrowx#1\relax}%
+\gdef\sumrowx#1\:#2\:#3\:#4\:#5\:#6\relax{%
+\leavevmode%
+{\smallfonts
+\hbox to5em{\sl\hss#1}%
+\hbox to5em{\tt#2\hss}%
+\hbox to4em{\sl#3\hss}%
+\hbox to5em{\rm\hss#4}%
+\thinspace%
+{\tt#5}%
+{\sl#6}%
+}}%
+\gdef\sumlpar{{\rm(}}%
+\gdef\sumrpar{{\rm)}}%
+\gdef\sumcomma{{\rm,\thinspace}}%
+\gdef\sumexcl{{\rm!}}%
+\gdef\sumbreak{\vskip-2.5\baselineskip\goodbreak}%
+\gdef\minus#1{{\tt-}}%
+@end tex
+@let@:=@sumsep
+@let@r=@sumrow
+@catcode`@(=@active @let(=@sumlpar
+@catcode`@)=@active @let)=@sumrpar
+@catcode`@,=@active @let,=@sumcomma
+@catcode`@!=@active @let!=@sumexcl
+@end iftex
+@format
+@iftex
+@advance@baselineskip-2.5pt
+@let@c@sumbreak
+@end iftex
+@r{ @: C-x * a @: @: 33 @:calc-embedded-activate@:}
+@r{ @: C-x * b @: @: @:calc-big-or-small@:}
+@r{ @: C-x * c @: @: @:calc@:}
+@r{ @: C-x * d @: @: @:calc-embedded-duplicate@:}
+@r{ @: C-x * e @: @: 34 @:calc-embedded@:}
+@r{ @: C-x * f @:formula @: @:calc-embedded-new-formula@:}
+@r{ @: C-x * g @: @: 35 @:calc-grab-region@:}
+@r{ @: C-x * i @: @: @:calc-info@:}
+@r{ @: C-x * j @: @: @:calc-embedded-select@:}
+@r{ @: C-x * k @: @: @:calc-keypad@:}
+@r{ @: C-x * l @: @: @:calc-load-everything@:}
+@r{ @: C-x * m @: @: @:read-kbd-macro@:}
+@r{ @: C-x * n @: @: 4 @:calc-embedded-next@:}
+@r{ @: C-x * o @: @: @:calc-other-window@:}
+@r{ @: C-x * p @: @: 4 @:calc-embedded-previous@:}
+@r{ @: C-x * q @:formula @: @:quick-calc@:}
+@r{ @: C-x * r @: @: 36 @:calc-grab-rectangle@:}
+@r{ @: C-x * s @: @: @:calc-info-summary@:}
+@r{ @: C-x * t @: @: @:calc-tutorial@:}
+@r{ @: C-x * u @: @: @:calc-embedded-update-formula@:}
+@r{ @: C-x * w @: @: @:calc-embedded-word@:}
+@r{ @: C-x * x @: @: @:calc-quit@:}
+@r{ @: C-x * y @: @:1,28,49 @:calc-copy-to-buffer@:}
+@r{ @: C-x * z @: @: @:calc-user-invocation@:}
+@r{ @: C-x * : @: @: 36 @:calc-grab-sum-down@:}
+@r{ @: C-x * _ @: @: 36 @:calc-grab-sum-across@:}
+@r{ @: C-x * ` @:editing @: 30 @:calc-embedded-edit@:}
+@r{ @: C-x * 0 @:(zero) @: @:calc-reset@:}
+
+@c
+@r{ @: 0-9 @:number @: @:@:number}
+@r{ @: . @:number @: @:@:0.number}
+@r{ @: _ @:number @: @:-@:number}
+@r{ @: e @:number @: @:@:1e number}
+@r{ @: # @:number @: @:@:current-radix@tfn{#}number}
+@r{ @: P @:(in number) @: @:+/-@:}
+@r{ @: M @:(in number) @: @:mod@:}
+@r{ @: @@ ' " @: (in number)@: @:@:HMS form}
+@r{ @: h m s @: (in number)@: @:@:HMS form}
+
+@c
+@r{ @: ' @:formula @: 37,46 @:@:formula}
+@r{ @: $ @:formula @: 37,46 @:$@:formula}
+@r{ @: " @:string @: 37,46 @:@:string}
+
+@c
+@r{ a b@: + @: @: 2 @:add@:(a,b) a+b}
+@r{ a b@: - @: @: 2 @:sub@:(a,b) a@minus{}b}
+@r{ a b@: * @: @: 2 @:mul@:(a,b) a b, a*b}
+@r{ a b@: / @: @: 2 @:div@:(a,b) a/b}
+@r{ a b@: ^ @: @: 2 @:pow@:(a,b) a^b}
+@r{ a b@: I ^ @: @: 2 @:nroot@:(a,b) a^(1/b)}
+@r{ a b@: % @: @: 2 @:mod@:(a,b) a%b}
+@r{ a b@: \ @: @: 2 @:idiv@:(a,b) a\b}
+@r{ a b@: : @: @: 2 @:fdiv@:(a,b)}
+@r{ a b@: | @: @: 2 @:vconcat@:(a,b) a|b}
+@r{ a b@: I | @: @: @:vconcat@:(b,a) b|a}
+@r{ a b@: H | @: @: 2 @:append@:(a,b)}
+@r{ a b@: I H | @: @: @:append@:(b,a)}
+@r{ a@: & @: @: 1 @:inv@:(a) 1/a}
+@r{ a@: ! @: @: 1 @:fact@:(a) a!}
+@r{ a@: = @: @: 1 @:evalv@:(a)}
+@r{ a@: M-% @: @: @:percent@:(a) a%}
+
+@c
+@r{ ... a@: @key{RET} @: @: 1 @:@:... a a}
+@r{ ... a@: @key{SPC} @: @: 1 @:@:... a a}
+@r{... a b@: @key{TAB} @: @: 3 @:@:... b a}
+@r{. a b c@: M-@key{TAB} @: @: 3 @:@:... b c a}
+@r{... a b@: @key{LFD} @: @: 1 @:@:... a b a}
+@r{ ... a@: @key{DEL} @: @: 1 @:@:...}
+@r{... a b@: M-@key{DEL} @: @: 1 @:@:... b}
+@r{ @: M-@key{RET} @: @: 4 @:calc-last-args@:}
+@r{ a@: ` @:editing @: 1,30 @:calc-edit@:}
+
+@c
+@r{ ... a@: C-d @: @: 1 @:@:...}
+@r{ @: C-k @: @: 27 @:calc-kill@:}
+@r{ @: C-w @: @: 27 @:calc-kill-region@:}
+@r{ @: C-y @: @: @:calc-yank@:}
+@r{ @: C-_ @: @: 4 @:calc-undo@:}
+@r{ @: M-k @: @: 27 @:calc-copy-as-kill@:}
+@r{ @: M-w @: @: 27 @:calc-copy-region-as-kill@:}
+
+@c
+@r{ @: [ @: @: @:@:[...}
+@r{[.. a b@: ] @: @: @:@:[a,b]}
+@r{ @: ( @: @: @:@:(...}
+@r{(.. a b@: ) @: @: @:@:(a,b)}
+@r{ @: , @: @: @:@:vector or rect complex}
+@r{ @: ; @: @: @:@:matrix or polar complex}
+@r{ @: .. @: @: @:@:interval}
+
+@c
+@r{ @: ~ @: @: @:calc-num-prefix@:}
+@r{ @: < @: @: 4 @:calc-scroll-left@:}
+@r{ @: > @: @: 4 @:calc-scroll-right@:}
+@r{ @: @{ @: @: 4 @:calc-scroll-down@:}
+@r{ @: @} @: @: 4 @:calc-scroll-up@:}
+@r{ @: ? @: @: @:calc-help@:}
+
+@c
+@r{ a@: n @: @: 1 @:neg@:(a) @minus{}a}
+@r{ @: o @: @: 4 @:calc-realign@:}
+@r{ @: p @:precision @: 31 @:calc-precision@:}
+@r{ @: q @: @: @:calc-quit@:}
+@r{ @: w @: @: @:calc-why@:}
+@r{ @: x @:command @: @:M-x calc-@:command}
+@r{ a@: y @: @:1,28,49 @:calc-copy-to-buffer@:}
+
+@c
+@r{ a@: A @: @: 1 @:abs@:(a)}
+@r{ a b@: B @: @: 2 @:log@:(a,b)}
+@r{ a b@: I B @: @: 2 @:alog@:(a,b) b^a}
+@r{ a@: C @: @: 1 @:cos@:(a)}
+@r{ a@: I C @: @: 1 @:arccos@:(a)}
+@r{ a@: H C @: @: 1 @:cosh@:(a)}
+@r{ a@: I H C @: @: 1 @:arccosh@:(a)}
+@r{ @: D @: @: 4 @:calc-redo@:}
+@r{ a@: E @: @: 1 @:exp@:(a)}
+@r{ a@: H E @: @: 1 @:exp10@:(a) 10.^a}
+@r{ a@: F @: @: 1,11 @:floor@:(a,d)}
+@r{ a@: I F @: @: 1,11 @:ceil@:(a,d)}
+@r{ a@: H F @: @: 1,11 @:ffloor@:(a,d)}
+@r{ a@: I H F @: @: 1,11 @:fceil@:(a,d)}
+@r{ a@: G @: @: 1 @:arg@:(a)}
+@r{ @: H @:command @: 32 @:@:Hyperbolic}
+@r{ @: I @:command @: 32 @:@:Inverse}
+@r{ a@: J @: @: 1 @:conj@:(a)}
+@r{ @: K @:command @: 32 @:@:Keep-args}
+@r{ a@: L @: @: 1 @:ln@:(a)}
+@r{ a@: H L @: @: 1 @:log10@:(a)}
+@r{ @: M @: @: @:calc-more-recursion-depth@:}
+@r{ @: I M @: @: @:calc-less-recursion-depth@:}
+@r{ a@: N @: @: 5 @:evalvn@:(a)}
+@r{ @: P @: @: @:@:pi}
+@r{ @: I P @: @: @:@:gamma}
+@r{ @: H P @: @: @:@:e}
+@r{ @: I H P @: @: @:@:phi}
+@r{ a@: Q @: @: 1 @:sqrt@:(a)}
+@r{ a@: I Q @: @: 1 @:sqr@:(a) a^2}
+@r{ a@: R @: @: 1,11 @:round@:(a,d)}
+@r{ a@: I R @: @: 1,11 @:trunc@:(a,d)}
+@r{ a@: H R @: @: 1,11 @:fround@:(a,d)}
+@r{ a@: I H R @: @: 1,11 @:ftrunc@:(a,d)}
+@r{ a@: S @: @: 1 @:sin@:(a)}
+@r{ a@: I S @: @: 1 @:arcsin@:(a)}
+@r{ a@: H S @: @: 1 @:sinh@:(a)}
+@r{ a@: I H S @: @: 1 @:arcsinh@:(a)}
+@r{ a@: T @: @: 1 @:tan@:(a)}
+@r{ a@: I T @: @: 1 @:arctan@:(a)}
+@r{ a@: H T @: @: 1 @:tanh@:(a)}
+@r{ a@: I H T @: @: 1 @:arctanh@:(a)}
+@r{ @: U @: @: 4 @:calc-undo@:}
+@r{ @: X @: @: 4 @:calc-call-last-kbd-macro@:}
+
+@c
+@r{ a b@: a = @: @: 2 @:eq@:(a,b) a=b}
+@r{ a b@: a # @: @: 2 @:neq@:(a,b) a!=b}
+@r{ a b@: a < @: @: 2 @:lt@:(a,b) a<b}
+@r{ a b@: a > @: @: 2 @:gt@:(a,b) a>b}
+@r{ a b@: a [ @: @: 2 @:leq@:(a,b) a<=b}
+@r{ a b@: a ] @: @: 2 @:geq@:(a,b) a>=b}
+@r{ a b@: a @{ @: @: 2 @:in@:(a,b)}
+@r{ a b@: a & @: @: 2,45 @:land@:(a,b) a&&b}
+@r{ a b@: a | @: @: 2,45 @:lor@:(a,b) a||b}
+@r{ a@: a ! @: @: 1,45 @:lnot@:(a) !a}
+@r{ a b c@: a : @: @: 45 @:if@:(a,b,c) a?b:c}
+@r{ a@: a . @: @: 1 @:rmeq@:(a)}
+@r{ a@: a " @: @: 7,8 @:calc-expand-formula@:}
+
+@c
+@r{ a@: a + @:i, l, h @: 6,38 @:sum@:(a,i,l,h)}
+@r{ a@: a - @:i, l, h @: 6,38 @:asum@:(a,i,l,h)}
+@r{ a@: a * @:i, l, h @: 6,38 @:prod@:(a,i,l,h)}
+@r{ a b@: a _ @: @: 2 @:subscr@:(a,b) a_b}
+
+@c
+@r{ a b@: a \ @: @: 2 @:pdiv@:(a,b)}
+@r{ a b@: a % @: @: 2 @:prem@:(a,b)}
+@r{ a b@: a / @: @: 2 @:pdivrem@:(a,b) [q,r]}
+@r{ a b@: H a / @: @: 2 @:pdivide@:(a,b) q+r/b}
+
+@c
+@r{ a@: a a @: @: 1 @:apart@:(a)}
+@r{ a@: a b @:old, new @: 38 @:subst@:(a,old,new)}
+@r{ a@: a c @:v @: 38 @:collect@:(a,v)}
+@r{ a@: a d @:v @: 4,38 @:deriv@:(a,v)}
+@r{ a@: H a d @:v @: 4,38 @:tderiv@:(a,v)}
+@r{ a@: a e @: @: @:esimplify@:(a)}
+@r{ a@: a f @: @: 1 @:factor@:(a)}
+@r{ a@: H a f @: @: 1 @:factors@:(a)}
+@r{ a b@: a g @: @: 2 @:pgcd@:(a,b)}
+@r{ a@: a i @:v @: 38 @:integ@:(a,v)}
+@r{ a@: a m @:pats @: 38 @:match@:(a,pats)}
+@r{ a@: I a m @:pats @: 38 @:matchnot@:(a,pats)}
+@r{ data x@: a p @: @: 28 @:polint@:(data,x)}
+@r{ data x@: H a p @: @: 28 @:ratint@:(data,x)}
+@r{ a@: a n @: @: 1 @:nrat@:(a)}
+@r{ a@: a r @:rules @:4,8,38 @:rewrite@:(a,rules,n)}
+@r{ a@: a s @: @: @:simplify@:(a)}
+@r{ a@: a t @:v, n @: 31,39 @:taylor@:(a,v,n)}
+@r{ a@: a v @: @: 7,8 @:calc-alg-evaluate@:}
+@r{ a@: a x @: @: 4,8 @:expand@:(a)}
+
+@c
+@r{ data@: a F @:model, vars @: 48 @:fit@:(m,iv,pv,data)}
+@r{ data@: I a F @:model, vars @: 48 @:xfit@:(m,iv,pv,data)}
+@r{ data@: H a F @:model, vars @: 48 @:efit@:(m,iv,pv,data)}
+@r{ a@: a I @:v, l, h @: 38 @:ninteg@:(a,v,l,h)}
+@r{ a b@: a M @:op @: 22 @:mapeq@:(op,a,b)}
+@r{ a b@: I a M @:op @: 22 @:mapeqr@:(op,a,b)}
+@r{ a b@: H a M @:op @: 22 @:mapeqp@:(op,a,b)}
+@r{ a g@: a N @:v @: 38 @:minimize@:(a,v,g)}
+@r{ a g@: H a N @:v @: 38 @:wminimize@:(a,v,g)}
+@r{ a@: a P @:v @: 38 @:roots@:(a,v)}
+@r{ a g@: a R @:v @: 38 @:root@:(a,v,g)}
+@r{ a g@: H a R @:v @: 38 @:wroot@:(a,v,g)}
+@r{ a@: a S @:v @: 38 @:solve@:(a,v)}
+@r{ a@: I a S @:v @: 38 @:finv@:(a,v)}
+@r{ a@: H a S @:v @: 38 @:fsolve@:(a,v)}
+@r{ a@: I H a S @:v @: 38 @:ffinv@:(a,v)}
+@r{ a@: a T @:i, l, h @: 6,38 @:table@:(a,i,l,h)}
+@r{ a g@: a X @:v @: 38 @:maximize@:(a,v,g)}
+@r{ a g@: H a X @:v @: 38 @:wmaximize@:(a,v,g)}
+
+@c
+@r{ a b@: b a @: @: 9 @:and@:(a,b,w)}
+@r{ a@: b c @: @: 9 @:clip@:(a,w)}
+@r{ a b@: b d @: @: 9 @:diff@:(a,b,w)}
+@r{ a@: b l @: @: 10 @:lsh@:(a,n,w)}
+@r{ a n@: H b l @: @: 9 @:lsh@:(a,n,w)}
+@r{ a@: b n @: @: 9 @:not@:(a,w)}
+@r{ a b@: b o @: @: 9 @:or@:(a,b,w)}
+@r{ v@: b p @: @: 1 @:vpack@:(v)}
+@r{ a@: b r @: @: 10 @:rsh@:(a,n,w)}
+@r{ a n@: H b r @: @: 9 @:rsh@:(a,n,w)}
+@r{ a@: b t @: @: 10 @:rot@:(a,n,w)}
+@r{ a n@: H b t @: @: 9 @:rot@:(a,n,w)}
+@r{ a@: b u @: @: 1 @:vunpack@:(a)}
+@r{ @: b w @:w @: 9,50 @:calc-word-size@:}
+@r{ a b@: b x @: @: 9 @:xor@:(a,b,w)}
+
+@c
+@r{c s l p@: b D @: @: @:ddb@:(c,s,l,p)}
+@r{ r n p@: b F @: @: @:fv@:(r,n,p)}
+@r{ r n p@: I b F @: @: @:fvb@:(r,n,p)}
+@r{ r n p@: H b F @: @: @:fvl@:(r,n,p)}
+@r{ v@: b I @: @: 19 @:irr@:(v)}
+@r{ v@: I b I @: @: 19 @:irrb@:(v)}
+@r{ a@: b L @: @: 10 @:ash@:(a,n,w)}
+@r{ a n@: H b L @: @: 9 @:ash@:(a,n,w)}
+@r{ r n a@: b M @: @: @:pmt@:(r,n,a)}
+@r{ r n a@: I b M @: @: @:pmtb@:(r,n,a)}
+@r{ r n a@: H b M @: @: @:pmtl@:(r,n,a)}
+@r{ r v@: b N @: @: 19 @:npv@:(r,v)}
+@r{ r v@: I b N @: @: 19 @:npvb@:(r,v)}
+@r{ r n p@: b P @: @: @:pv@:(r,n,p)}
+@r{ r n p@: I b P @: @: @:pvb@:(r,n,p)}
+@r{ r n p@: H b P @: @: @:pvl@:(r,n,p)}
+@r{ a@: b R @: @: 10 @:rash@:(a,n,w)}
+@r{ a n@: H b R @: @: 9 @:rash@:(a,n,w)}
+@r{ c s l@: b S @: @: @:sln@:(c,s,l)}
+@r{ n p a@: b T @: @: @:rate@:(n,p,a)}
+@r{ n p a@: I b T @: @: @:rateb@:(n,p,a)}
+@r{ n p a@: H b T @: @: @:ratel@:(n,p,a)}
+@r{c s l p@: b Y @: @: @:syd@:(c,s,l,p)}
+
+@r{ r p a@: b # @: @: @:nper@:(r,p,a)}
+@r{ r p a@: I b # @: @: @:nperb@:(r,p,a)}
+@r{ r p a@: H b # @: @: @:nperl@:(r,p,a)}
+@r{ a b@: b % @: @: @:relch@:(a,b)}
+
+@c
+@r{ a@: c c @: @: 5 @:pclean@:(a,p)}
+@r{ a@: c 0-9 @: @: @:pclean@:(a,p)}
+@r{ a@: H c c @: @: 5 @:clean@:(a,p)}
+@r{ a@: H c 0-9 @: @: @:clean@:(a,p)}
+@r{ a@: c d @: @: 1 @:deg@:(a)}
+@r{ a@: c f @: @: 1 @:pfloat@:(a)}
+@r{ a@: H c f @: @: 1 @:float@:(a)}
+@r{ a@: c h @: @: 1 @:hms@:(a)}
+@r{ a@: c p @: @: @:polar@:(a)}
+@r{ a@: I c p @: @: @:rect@:(a)}
+@r{ a@: c r @: @: 1 @:rad@:(a)}
+
+@c
+@r{ a@: c F @: @: 5 @:pfrac@:(a,p)}
+@r{ a@: H c F @: @: 5 @:frac@:(a,p)}
+
+@c
+@r{ a@: c % @: @: @:percent@:(a*100)}
+
+@c
+@r{ @: d . @:char @: 50 @:calc-point-char@:}
+@r{ @: d , @:char @: 50 @:calc-group-char@:}
+@r{ @: d < @: @: 13,50 @:calc-left-justify@:}
+@r{ @: d = @: @: 13,50 @:calc-center-justify@:}
+@r{ @: d > @: @: 13,50 @:calc-right-justify@:}
+@r{ @: d @{ @:label @: 50 @:calc-left-label@:}
+@r{ @: d @} @:label @: 50 @:calc-right-label@:}
+@r{ @: d [ @: @: 4 @:calc-truncate-up@:}
+@r{ @: d ] @: @: 4 @:calc-truncate-down@:}
+@r{ @: d " @: @: 12,50 @:calc-display-strings@:}
+@r{ @: d @key{SPC} @: @: @:calc-refresh@:}
+@r{ @: d @key{RET} @: @: 1 @:calc-refresh-top@:}
+
+@c
+@r{ @: d 0 @: @: 50 @:calc-decimal-radix@:}
+@r{ @: d 2 @: @: 50 @:calc-binary-radix@:}
+@r{ @: d 6 @: @: 50 @:calc-hex-radix@:}
+@r{ @: d 8 @: @: 50 @:calc-octal-radix@:}
+
+@c
+@r{ @: d b @: @:12,13,50 @:calc-line-breaking@:}
+@r{ @: d c @: @: 50 @:calc-complex-notation@:}
+@r{ @: d d @:format @: 50 @:calc-date-notation@:}
+@r{ @: d e @: @: 5,50 @:calc-eng-notation@:}
+@r{ @: d f @:num @: 31,50 @:calc-fix-notation@:}
+@r{ @: d g @: @:12,13,50 @:calc-group-digits@:}
+@r{ @: d h @:format @: 50 @:calc-hms-notation@:}
+@r{ @: d i @: @: 50 @:calc-i-notation@:}
+@r{ @: d j @: @: 50 @:calc-j-notation@:}
+@r{ @: d l @: @: 12,50 @:calc-line-numbering@:}
+@r{ @: d n @: @: 5,50 @:calc-normal-notation@:}
+@r{ @: d o @:format @: 50 @:calc-over-notation@:}
+@r{ @: d p @: @: 12,50 @:calc-show-plain@:}
+@r{ @: d r @:radix @: 31,50 @:calc-radix@:}
+@r{ @: d s @: @: 5,50 @:calc-sci-notation@:}
+@r{ @: d t @: @: 27 @:calc-truncate-stack@:}
+@r{ @: d w @: @: 12,13 @:calc-auto-why@:}
+@r{ @: d z @: @: 12,50 @:calc-leading-zeros@:}
+
+@c
+@r{ @: d B @: @: 50 @:calc-big-language@:}
+@r{ @: d C @: @: 50 @:calc-c-language@:}
+@r{ @: d E @: @: 50 @:calc-eqn-language@:}
+@r{ @: d F @: @: 50 @:calc-fortran-language@:}
+@r{ @: d M @: @: 50 @:calc-mathematica-language@:}
+@r{ @: d N @: @: 50 @:calc-normal-language@:}
+@r{ @: d O @: @: 50 @:calc-flat-language@:}
+@r{ @: d P @: @: 50 @:calc-pascal-language@:}
+@r{ @: d T @: @: 50 @:calc-tex-language@:}
+@r{ @: d L @: @: 50 @:calc-latex-language@:}
+@r{ @: d U @: @: 50 @:calc-unformatted-language@:}
+@r{ @: d W @: @: 50 @:calc-maple-language@:}
+
+@c
+@r{ a@: f [ @: @: 4 @:decr@:(a,n)}
+@r{ a@: f ] @: @: 4 @:incr@:(a,n)}
+
+@c
+@r{ a b@: f b @: @: 2 @:beta@:(a,b)}
+@r{ a@: f e @: @: 1 @:erf@:(a)}
+@r{ a@: I f e @: @: 1 @:erfc@:(a)}
+@r{ a@: f g @: @: 1 @:gamma@:(a)}
+@r{ a b@: f h @: @: 2 @:hypot@:(a,b)}
+@r{ a@: f i @: @: 1 @:im@:(a)}
+@r{ n a@: f j @: @: 2 @:besJ@:(n,a)}
+@r{ a b@: f n @: @: 2 @:min@:(a,b)}
+@r{ a@: f r @: @: 1 @:re@:(a)}
+@r{ a@: f s @: @: 1 @:sign@:(a)}
+@r{ a b@: f x @: @: 2 @:max@:(a,b)}
+@r{ n a@: f y @: @: 2 @:besY@:(n,a)}
+
+@c
+@r{ a@: f A @: @: 1 @:abssqr@:(a)}
+@r{ x a b@: f B @: @: @:betaI@:(x,a,b)}
+@r{ x a b@: H f B @: @: @:betaB@:(x,a,b)}
+@r{ a@: f E @: @: 1 @:expm1@:(a)}
+@r{ a x@: f G @: @: 2 @:gammaP@:(a,x)}
+@r{ a x@: I f G @: @: 2 @:gammaQ@:(a,x)}
+@r{ a x@: H f G @: @: 2 @:gammag@:(a,x)}
+@r{ a x@: I H f G @: @: 2 @:gammaG@:(a,x)}
+@r{ a b@: f I @: @: 2 @:ilog@:(a,b)}
+@r{ a b@: I f I @: @: 2 @:alog@:(a,b) b^a}
+@r{ a@: f L @: @: 1 @:lnp1@:(a)}
+@r{ a@: f M @: @: 1 @:mant@:(a)}
+@r{ a@: f Q @: @: 1 @:isqrt@:(a)}
+@r{ a@: I f Q @: @: 1 @:sqr@:(a) a^2}
+@r{ a n@: f S @: @: 2 @:scf@:(a,n)}
+@r{ y x@: f T @: @: @:arctan2@:(y,x)}
+@r{ a@: f X @: @: 1 @:xpon@:(a)}
+
+@c
+@r{ x y@: g a @: @: 28,40 @:calc-graph-add@:}
+@r{ @: g b @: @: 12 @:calc-graph-border@:}
+@r{ @: g c @: @: @:calc-graph-clear@:}
+@r{ @: g d @: @: 41 @:calc-graph-delete@:}
+@r{ x y@: g f @: @: 28,40 @:calc-graph-fast@:}
+@r{ @: g g @: @: 12 @:calc-graph-grid@:}
+@r{ @: g h @:title @: @:calc-graph-header@:}
+@r{ @: g j @: @: 4 @:calc-graph-juggle@:}
+@r{ @: g k @: @: 12 @:calc-graph-key@:}
+@r{ @: g l @: @: 12 @:calc-graph-log-x@:}
+@r{ @: g n @:name @: @:calc-graph-name@:}
+@r{ @: g p @: @: 42 @:calc-graph-plot@:}
+@r{ @: g q @: @: @:calc-graph-quit@:}
+@r{ @: g r @:range @: @:calc-graph-range-x@:}
+@r{ @: g s @: @: 12,13 @:calc-graph-line-style@:}
+@r{ @: g t @:title @: @:calc-graph-title-x@:}
+@r{ @: g v @: @: @:calc-graph-view-commands@:}
+@r{ @: g x @:display @: @:calc-graph-display@:}
+@r{ @: g z @: @: 12 @:calc-graph-zero-x@:}
+
+@c
+@r{ x y z@: g A @: @: 28,40 @:calc-graph-add-3d@:}
+@r{ @: g C @:command @: @:calc-graph-command@:}
+@r{ @: g D @:device @: 43,44 @:calc-graph-device@:}
+@r{ x y z@: g F @: @: 28,40 @:calc-graph-fast-3d@:}
+@r{ @: g H @: @: 12 @:calc-graph-hide@:}
+@r{ @: g K @: @: @:calc-graph-kill@:}
+@r{ @: g L @: @: 12 @:calc-graph-log-y@:}
+@r{ @: g N @:number @: 43,51 @:calc-graph-num-points@:}
+@r{ @: g O @:filename @: 43,44 @:calc-graph-output@:}
+@r{ @: g P @: @: 42 @:calc-graph-print@:}
+@r{ @: g R @:range @: @:calc-graph-range-y@:}
+@r{ @: g S @: @: 12,13 @:calc-graph-point-style@:}
+@r{ @: g T @:title @: @:calc-graph-title-y@:}
+@r{ @: g V @: @: @:calc-graph-view-trail@:}
+@r{ @: g X @:format @: @:calc-graph-geometry@:}
+@r{ @: g Z @: @: 12 @:calc-graph-zero-y@:}
+
+@c
+@r{ @: g C-l @: @: 12 @:calc-graph-log-z@:}
+@r{ @: g C-r @:range @: @:calc-graph-range-z@:}
+@r{ @: g C-t @:title @: @:calc-graph-title-z@:}
+
+@c
+@r{ @: h b @: @: @:calc-describe-bindings@:}
+@r{ @: h c @:key @: @:calc-describe-key-briefly@:}
+@r{ @: h f @:function @: @:calc-describe-function@:}
+@r{ @: h h @: @: @:calc-full-help@:}
+@r{ @: h i @: @: @:calc-info@:}
+@r{ @: h k @:key @: @:calc-describe-key@:}
+@r{ @: h n @: @: @:calc-view-news@:}
+@r{ @: h s @: @: @:calc-info-summary@:}
+@r{ @: h t @: @: @:calc-tutorial@:}
+@r{ @: h v @:var @: @:calc-describe-variable@:}
+
+@c
+@r{ @: j 1-9 @: @: @:calc-select-part@:}
+@r{ @: j @key{RET} @: @: 27 @:calc-copy-selection@:}
+@r{ @: j @key{DEL} @: @: 27 @:calc-del-selection@:}
+@r{ @: j ' @:formula @: 27 @:calc-enter-selection@:}
+@r{ @: j ` @:editing @: 27,30 @:calc-edit-selection@:}
+@r{ @: j " @: @: 7,27 @:calc-sel-expand-formula@:}
+
+@c
+@r{ @: j + @:formula @: 27 @:calc-sel-add-both-sides@:}
+@r{ @: j - @:formula @: 27 @:calc-sel-sub-both-sides@:}
+@r{ @: j * @:formula @: 27 @:calc-sel-mul-both-sides@:}
+@r{ @: j / @:formula @: 27 @:calc-sel-div-both-sides@:}
+@r{ @: j & @: @: 27 @:calc-sel-invert@:}
+
+@c
+@r{ @: j a @: @: 27 @:calc-select-additional@:}
+@r{ @: j b @: @: 12 @:calc-break-selections@:}
+@r{ @: j c @: @: @:calc-clear-selections@:}
+@r{ @: j d @: @: 12,50 @:calc-show-selections@:}
+@r{ @: j e @: @: 12 @:calc-enable-selections@:}
+@r{ @: j l @: @: 4,27 @:calc-select-less@:}
+@r{ @: j m @: @: 4,27 @:calc-select-more@:}
+@r{ @: j n @: @: 4 @:calc-select-next@:}
+@r{ @: j o @: @: 4,27 @:calc-select-once@:}
+@r{ @: j p @: @: 4 @:calc-select-previous@:}
+@r{ @: j r @:rules @:4,8,27 @:calc-rewrite-selection@:}
+@r{ @: j s @: @: 4,27 @:calc-select-here@:}
+@r{ @: j u @: @: 27 @:calc-unselect@:}
+@r{ @: j v @: @: 7,27 @:calc-sel-evaluate@:}
+
+@c
+@r{ @: j C @: @: 27 @:calc-sel-commute@:}
+@r{ @: j D @: @: 4,27 @:calc-sel-distribute@:}
+@r{ @: j E @: @: 27 @:calc-sel-jump-equals@:}
+@r{ @: j I @: @: 27 @:calc-sel-isolate@:}
+@r{ @: H j I @: @: 27 @:calc-sel-isolate@: (full)}
+@r{ @: j L @: @: 4,27 @:calc-commute-left@:}
+@r{ @: j M @: @: 27 @:calc-sel-merge@:}
+@r{ @: j N @: @: 27 @:calc-sel-negate@:}
+@r{ @: j O @: @: 4,27 @:calc-select-once-maybe@:}
+@r{ @: j R @: @: 4,27 @:calc-commute-right@:}
+@r{ @: j S @: @: 4,27 @:calc-select-here-maybe@:}
+@r{ @: j U @: @: 27 @:calc-sel-unpack@:}
+
+@c
+@r{ @: k a @: @: @:calc-random-again@:}
+@r{ n@: k b @: @: 1 @:bern@:(n)}
+@r{ n x@: H k b @: @: 2 @:bern@:(n,x)}
+@r{ n m@: k c @: @: 2 @:choose@:(n,m)}
+@r{ n m@: H k c @: @: 2 @:perm@:(n,m)}
+@r{ n@: k d @: @: 1 @:dfact@:(n) n!!}
+@r{ n@: k e @: @: 1 @:euler@:(n)}
+@r{ n x@: H k e @: @: 2 @:euler@:(n,x)}
+@r{ n@: k f @: @: 4 @:prfac@:(n)}
+@r{ n m@: k g @: @: 2 @:gcd@:(n,m)}
+@r{ m n@: k h @: @: 14 @:shuffle@:(n,m)}
+@r{ n m@: k l @: @: 2 @:lcm@:(n,m)}
+@r{ n@: k m @: @: 1 @:moebius@:(n)}
+@r{ n@: k n @: @: 4 @:nextprime@:(n)}
+@r{ n@: I k n @: @: 4 @:prevprime@:(n)}
+@r{ n@: k p @: @: 4,28 @:calc-prime-test@:}
+@r{ m@: k r @: @: 14 @:random@:(m)}
+@r{ n m@: k s @: @: 2 @:stir1@:(n,m)}
+@r{ n m@: H k s @: @: 2 @:stir2@:(n,m)}
+@r{ n@: k t @: @: 1 @:totient@:(n)}
+
+@c
+@r{ n p x@: k B @: @: @:utpb@:(x,n,p)}
+@r{ n p x@: I k B @: @: @:ltpb@:(x,n,p)}
+@r{ v x@: k C @: @: @:utpc@:(x,v)}
+@r{ v x@: I k C @: @: @:ltpc@:(x,v)}
+@r{ n m@: k E @: @: @:egcd@:(n,m)}
+@r{v1 v2 x@: k F @: @: @:utpf@:(x,v1,v2)}
+@r{v1 v2 x@: I k F @: @: @:ltpf@:(x,v1,v2)}
+@r{ m s x@: k N @: @: @:utpn@:(x,m,s)}
+@r{ m s x@: I k N @: @: @:ltpn@:(x,m,s)}
+@r{ m x@: k P @: @: @:utpp@:(x,m)}
+@r{ m x@: I k P @: @: @:ltpp@:(x,m)}
+@r{ v x@: k T @: @: @:utpt@:(x,v)}
+@r{ v x@: I k T @: @: @:ltpt@:(x,v)}
+
+@c
+@r{ @: m a @: @: 12,13 @:calc-algebraic-mode@:}
+@r{ @: m d @: @: @:calc-degrees-mode@:}
+@r{ @: m e @: @: @:calc-embedded-preserve-modes@:}
+@r{ @: m f @: @: 12 @:calc-frac-mode@:}
+@r{ @: m g @: @: 52 @:calc-get-modes@:}
+@r{ @: m h @: @: @:calc-hms-mode@:}
+@r{ @: m i @: @: 12,13 @:calc-infinite-mode@:}
+@r{ @: m m @: @: @:calc-save-modes@:}
+@r{ @: m p @: @: 12 @:calc-polar-mode@:}
+@r{ @: m r @: @: @:calc-radians-mode@:}
+@r{ @: m s @: @: 12 @:calc-symbolic-mode@:}
+@r{ @: m t @: @: 12 @:calc-total-algebraic-mode@:}
+@r{ @: m v @: @: 12,13 @:calc-matrix-mode@:}
+@r{ @: m w @: @: 13 @:calc-working@:}
+@r{ @: m x @: @: @:calc-always-load-extensions@:}
+
+@c
+@r{ @: m A @: @: 12 @:calc-alg-simplify-mode@:}
+@r{ @: m B @: @: 12 @:calc-bin-simplify-mode@:}
+@r{ @: m C @: @: 12 @:calc-auto-recompute@:}
+@r{ @: m D @: @: @:calc-default-simplify-mode@:}
+@r{ @: m E @: @: 12 @:calc-ext-simplify-mode@:}
+@r{ @: m F @:filename @: 13 @:calc-settings-file-name@:}
+@r{ @: m N @: @: 12 @:calc-num-simplify-mode@:}
+@r{ @: m O @: @: 12 @:calc-no-simplify-mode@:}
+@r{ @: m R @: @: 12,13 @:calc-mode-record-mode@:}
+@r{ @: m S @: @: 12 @:calc-shift-prefix@:}
+@r{ @: m U @: @: 12 @:calc-units-simplify-mode@:}
+
+@c
+@r{ @: s c @:var1, var2 @: 29 @:calc-copy-variable@:}
+@r{ @: s d @:var, decl @: @:calc-declare-variable@:}
+@r{ @: s e @:var, editing @: 29,30 @:calc-edit-variable@:}
+@r{ @: s i @:buffer @: @:calc-insert-variables@:}
+@r{ @: s k @:const, var @: 29 @:calc-copy-special-constant@:}
+@r{ a b@: s l @:var @: 29 @:@:a (letting var=b)}
+@r{ a ...@: s m @:op, var @: 22,29 @:calc-store-map@:}
+@r{ @: s n @:var @: 29,47 @:calc-store-neg@: (v/-1)}
+@r{ @: s p @:var @: 29 @:calc-permanent-variable@:}
+@r{ @: s r @:var @: 29 @:@:v (recalled value)}
+@r{ @: r 0-9 @: @: @:calc-recall-quick@:}
+@r{ a@: s s @:var @: 28,29 @:calc-store@:}
+@r{ a@: s 0-9 @: @: @:calc-store-quick@:}
+@r{ a@: s t @:var @: 29 @:calc-store-into@:}
+@r{ a@: t 0-9 @: @: @:calc-store-into-quick@:}
+@r{ @: s u @:var @: 29 @:calc-unstore@:}
+@r{ a@: s x @:var @: 29 @:calc-store-exchange@:}
+
+@c
+@r{ @: s A @:editing @: 30 @:calc-edit-AlgSimpRules@:}
+@r{ @: s D @:editing @: 30 @:calc-edit-Decls@:}
+@r{ @: s E @:editing @: 30 @:calc-edit-EvalRules@:}
+@r{ @: s F @:editing @: 30 @:calc-edit-FitRules@:}
+@r{ @: s G @:editing @: 30 @:calc-edit-GenCount@:}
+@r{ @: s H @:editing @: 30 @:calc-edit-Holidays@:}
+@r{ @: s I @:editing @: 30 @:calc-edit-IntegLimit@:}
+@r{ @: s L @:editing @: 30 @:calc-edit-LineStyles@:}
+@r{ @: s P @:editing @: 30 @:calc-edit-PointStyles@:}
+@r{ @: s R @:editing @: 30 @:calc-edit-PlotRejects@:}
+@r{ @: s T @:editing @: 30 @:calc-edit-TimeZone@:}
+@r{ @: s U @:editing @: 30 @:calc-edit-Units@:}
+@r{ @: s X @:editing @: 30 @:calc-edit-ExtSimpRules@:}
+
+@c
+@r{ a@: s + @:var @: 29,47 @:calc-store-plus@: (v+a)}
+@r{ a@: s - @:var @: 29,47 @:calc-store-minus@: (v-a)}
+@r{ a@: s * @:var @: 29,47 @:calc-store-times@: (v*a)}
+@r{ a@: s / @:var @: 29,47 @:calc-store-div@: (v/a)}
+@r{ a@: s ^ @:var @: 29,47 @:calc-store-power@: (v^a)}
+@r{ a@: s | @:var @: 29,47 @:calc-store-concat@: (v|a)}
+@r{ @: s & @:var @: 29,47 @:calc-store-inv@: (v^-1)}
+@r{ @: s [ @:var @: 29,47 @:calc-store-decr@: (v-1)}
+@r{ @: s ] @:var @: 29,47 @:calc-store-incr@: (v-(-1))}
+@r{ a b@: s : @: @: 2 @:assign@:(a,b) a @tfn{:=} b}
+@r{ a@: s = @: @: 1 @:evalto@:(a,b) a @tfn{=>}}
+
+@c
+@r{ @: t [ @: @: 4 @:calc-trail-first@:}
+@r{ @: t ] @: @: 4 @:calc-trail-last@:}
+@r{ @: t < @: @: 4 @:calc-trail-scroll-left@:}
+@r{ @: t > @: @: 4 @:calc-trail-scroll-right@:}
+@r{ @: t . @: @: 12 @:calc-full-trail-vectors@:}
+
+@c
+@r{ @: t b @: @: 4 @:calc-trail-backward@:}
+@r{ @: t d @: @: 12,50 @:calc-trail-display@:}
+@r{ @: t f @: @: 4 @:calc-trail-forward@:}
+@r{ @: t h @: @: @:calc-trail-here@:}
+@r{ @: t i @: @: @:calc-trail-in@:}
+@r{ @: t k @: @: 4 @:calc-trail-kill@:}
+@r{ @: t m @:string @: @:calc-trail-marker@:}
+@r{ @: t n @: @: 4 @:calc-trail-next@:}
+@r{ @: t o @: @: @:calc-trail-out@:}
+@r{ @: t p @: @: 4 @:calc-trail-previous@:}
+@r{ @: t r @:string @: @:calc-trail-isearch-backward@:}
+@r{ @: t s @:string @: @:calc-trail-isearch-forward@:}
+@r{ @: t y @: @: 4 @:calc-trail-yank@:}
+
+@c
+@r{ d@: t C @:oz, nz @: @:tzconv@:(d,oz,nz)}
+@r{d oz nz@: t C @:$ @: @:tzconv@:(d,oz,nz)}
+@r{ d@: t D @: @: 15 @:date@:(d)}
+@r{ d@: t I @: @: 4 @:incmonth@:(d,n)}
+@r{ d@: t J @: @: 16 @:julian@:(d,z)}
+@r{ d@: t M @: @: 17 @:newmonth@:(d,n)}
+@r{ @: t N @: @: 16 @:now@:(z)}
+@r{ d@: t P @:1 @: 31 @:year@:(d)}
+@r{ d@: t P @:2 @: 31 @:month@:(d)}
+@r{ d@: t P @:3 @: 31 @:day@:(d)}
+@r{ d@: t P @:4 @: 31 @:hour@:(d)}
+@r{ d@: t P @:5 @: 31 @:minute@:(d)}
+@r{ d@: t P @:6 @: 31 @:second@:(d)}
+@r{ d@: t P @:7 @: 31 @:weekday@:(d)}
+@r{ d@: t P @:8 @: 31 @:yearday@:(d)}
+@r{ d@: t P @:9 @: 31 @:time@:(d)}
+@r{ d@: t U @: @: 16 @:unixtime@:(d,z)}
+@r{ d@: t W @: @: 17 @:newweek@:(d,w)}
+@r{ d@: t Y @: @: 17 @:newyear@:(d,n)}
+
+@c
+@r{ a b@: t + @: @: 2 @:badd@:(a,b)}
+@r{ a b@: t - @: @: 2 @:bsub@:(a,b)}
+
+@c
+@r{ @: u a @: @: 12 @:calc-autorange-units@:}
+@r{ a@: u b @: @: @:calc-base-units@:}
+@r{ a@: u c @:units @: 18 @:calc-convert-units@:}
+@r{ defn@: u d @:unit, descr @: @:calc-define-unit@:}
+@r{ @: u e @: @: @:calc-explain-units@:}
+@r{ @: u g @:unit @: @:calc-get-unit-definition@:}
+@r{ @: u p @: @: @:calc-permanent-units@:}
+@r{ a@: u r @: @: @:calc-remove-units@:}
+@r{ a@: u s @: @: @:usimplify@:(a)}
+@r{ a@: u t @:units @: 18 @:calc-convert-temperature@:}
+@r{ @: u u @:unit @: @:calc-undefine-unit@:}
+@r{ @: u v @: @: @:calc-enter-units-table@:}
+@r{ a@: u x @: @: @:calc-extract-units@:}
+@r{ a@: u 0-9 @: @: @:calc-quick-units@:}
+
+@c
+@r{ v1 v2@: u C @: @: 20 @:vcov@:(v1,v2)}
+@r{ v1 v2@: I u C @: @: 20 @:vpcov@:(v1,v2)}
+@r{ v1 v2@: H u C @: @: 20 @:vcorr@:(v1,v2)}
+@r{ v@: u G @: @: 19 @:vgmean@:(v)}
+@r{ a b@: H u G @: @: 2 @:agmean@:(a,b)}
+@r{ v@: u M @: @: 19 @:vmean@:(v)}
+@r{ v@: I u M @: @: 19 @:vmeane@:(v)}
+@r{ v@: H u M @: @: 19 @:vmedian@:(v)}
+@r{ v@: I H u M @: @: 19 @:vhmean@:(v)}
+@r{ v@: u N @: @: 19 @:vmin@:(v)}
+@r{ v@: u S @: @: 19 @:vsdev@:(v)}
+@r{ v@: I u S @: @: 19 @:vpsdev@:(v)}
+@r{ v@: H u S @: @: 19 @:vvar@:(v)}
+@r{ v@: I H u S @: @: 19 @:vpvar@:(v)}
+@r{ @: u V @: @: @:calc-view-units-table@:}
+@r{ v@: u X @: @: 19 @:vmax@:(v)}
+
+@c
+@r{ v@: u + @: @: 19 @:vsum@:(v)}
+@r{ v@: u * @: @: 19 @:vprod@:(v)}
+@r{ v@: u # @: @: 19 @:vcount@:(v)}
+
+@c
+@r{ @: V ( @: @: 50 @:calc-vector-parens@:}
+@r{ @: V @{ @: @: 50 @:calc-vector-braces@:}
+@r{ @: V [ @: @: 50 @:calc-vector-brackets@:}
+@r{ @: V ] @:ROCP @: 50 @:calc-matrix-brackets@:}
+@r{ @: V , @: @: 50 @:calc-vector-commas@:}
+@r{ @: V < @: @: 50 @:calc-matrix-left-justify@:}
+@r{ @: V = @: @: 50 @:calc-matrix-center-justify@:}
+@r{ @: V > @: @: 50 @:calc-matrix-right-justify@:}
+@r{ @: V / @: @: 12,50 @:calc-break-vectors@:}
+@r{ @: V . @: @: 12,50 @:calc-full-vectors@:}
+
+@c
+@r{ s t@: V ^ @: @: 2 @:vint@:(s,t)}
+@r{ s t@: V - @: @: 2 @:vdiff@:(s,t)}
+@r{ s@: V ~ @: @: 1 @:vcompl@:(s)}
+@r{ s@: V # @: @: 1 @:vcard@:(s)}
+@r{ s@: V : @: @: 1 @:vspan@:(s)}
+@r{ s@: V + @: @: 1 @:rdup@:(s)}
+
+@c
+@r{ m@: V & @: @: 1 @:inv@:(m) 1/m}
+
+@c
+@r{ v@: v a @:n @: @:arrange@:(v,n)}
+@r{ a@: v b @:n @: @:cvec@:(a,n)}
+@r{ v@: v c @:n >0 @: 21,31 @:mcol@:(v,n)}
+@r{ v@: v c @:n <0 @: 31 @:mrcol@:(v,-n)}
+@r{ m@: v c @:0 @: 31 @:getdiag@:(m)}
+@r{ v@: v d @: @: 25 @:diag@:(v,n)}
+@r{ v m@: v e @: @: 2 @:vexp@:(v,m)}
+@r{ v m f@: H v e @: @: 2 @:vexp@:(v,m,f)}
+@r{ v a@: v f @: @: 26 @:find@:(v,a,n)}
+@r{ v@: v h @: @: 1 @:head@:(v)}
+@r{ v@: I v h @: @: 1 @:tail@:(v)}
+@r{ v@: H v h @: @: 1 @:rhead@:(v)}
+@r{ v@: I H v h @: @: 1 @:rtail@:(v)}
+@r{ @: v i @:n @: 31 @:idn@:(1,n)}
+@r{ @: v i @:0 @: 31 @:idn@:(1)}
+@r{ h t@: v k @: @: 2 @:cons@:(h,t)}
+@r{ h t@: H v k @: @: 2 @:rcons@:(h,t)}
+@r{ v@: v l @: @: 1 @:vlen@:(v)}
+@r{ v@: H v l @: @: 1 @:mdims@:(v)}
+@r{ v m@: v m @: @: 2 @:vmask@:(v,m)}
+@r{ v@: v n @: @: 1 @:rnorm@:(v)}
+@r{ a b c@: v p @: @: 24 @:calc-pack@:}
+@r{ v@: v r @:n >0 @: 21,31 @:mrow@:(v,n)}
+@r{ v@: v r @:n <0 @: 31 @:mrrow@:(v,-n)}
+@r{ m@: v r @:0 @: 31 @:getdiag@:(m)}
+@r{ v i j@: v s @: @: @:subvec@:(v,i,j)}
+@r{ v i j@: I v s @: @: @:rsubvec@:(v,i,j)}
+@r{ m@: v t @: @: 1 @:trn@:(m)}
+@r{ v@: v u @: @: 24 @:calc-unpack@:}
+@r{ v@: v v @: @: 1 @:rev@:(v)}
+@r{ @: v x @:n @: 31 @:index@:(n)}
+@r{ n s i@: C-u v x @: @: @:index@:(n,s,i)}
+
+@c
+@r{ v@: V A @:op @: 22 @:apply@:(op,v)}
+@r{ v1 v2@: V C @: @: 2 @:cross@:(v1,v2)}
+@r{ m@: V D @: @: 1 @:det@:(m)}
+@r{ s@: V E @: @: 1 @:venum@:(s)}
+@r{ s@: V F @: @: 1 @:vfloor@:(s)}
+@r{ v@: V G @: @: @:grade@:(v)}
+@r{ v@: I V G @: @: @:rgrade@:(v)}
+@r{ v@: V H @:n @: 31 @:histogram@:(v,n)}
+@r{ v w@: H V H @:n @: 31 @:histogram@:(v,w,n)}
+@r{ v1 v2@: V I @:mop aop @: 22 @:inner@:(mop,aop,v1,v2)}
+@r{ m@: V J @: @: 1 @:ctrn@:(m)}
+@r{ m@: V L @: @: 1 @:lud@:(m)}
+@r{ v@: V M @:op @: 22,23 @:map@:(op,v)}
+@r{ v@: V N @: @: 1 @:cnorm@:(v)}
+@r{ v1 v2@: V O @:op @: 22 @:outer@:(op,v1,v2)}
+@r{ v@: V R @:op @: 22,23 @:reduce@:(op,v)}
+@r{ v@: I V R @:op @: 22,23 @:rreduce@:(op,v)}
+@r{ a n@: H V R @:op @: 22 @:nest@:(op,a,n)}
+@r{ a@: I H V R @:op @: 22 @:fixp@:(op,a)}
+@r{ v@: V S @: @: @:sort@:(v)}
+@r{ v@: I V S @: @: @:rsort@:(v)}
+@r{ m@: V T @: @: 1 @:tr@:(m)}
+@r{ v@: V U @:op @: 22 @:accum@:(op,v)}
+@r{ v@: I V U @:op @: 22 @:raccum@:(op,v)}
+@r{ a n@: H V U @:op @: 22 @:anest@:(op,a,n)}
+@r{ a@: I H V U @:op @: 22 @:afixp@:(op,a)}
+@r{ s t@: V V @: @: 2 @:vunion@:(s,t)}
+@r{ s t@: V X @: @: 2 @:vxor@:(s,t)}
+
+@c
+@r{ @: Y @: @: @:@:user commands}
+
+@c
+@r{ @: z @: @: @:@:user commands}
+
+@c
+@r{ c@: Z [ @: @: 45 @:calc-kbd-if@:}
+@r{ c@: Z | @: @: 45 @:calc-kbd-else-if@:}
+@r{ @: Z : @: @: @:calc-kbd-else@:}
+@r{ @: Z ] @: @: @:calc-kbd-end-if@:}
+
+@c
+@r{ @: Z @{ @: @: 4 @:calc-kbd-loop@:}
+@r{ c@: Z / @: @: 45 @:calc-kbd-break@:}
+@r{ @: Z @} @: @: @:calc-kbd-end-loop@:}
+@r{ n@: Z < @: @: @:calc-kbd-repeat@:}
+@r{ @: Z > @: @: @:calc-kbd-end-repeat@:}
+@r{ n m@: Z ( @: @: @:calc-kbd-for@:}
+@r{ s@: Z ) @: @: @:calc-kbd-end-for@:}
+
+@c
+@r{ @: Z C-g @: @: @:@:cancel if/loop command}
+
+@c
+@r{ @: Z ` @: @: @:calc-kbd-push@:}
+@r{ @: Z ' @: @: @:calc-kbd-pop@:}
+@r{ @: Z # @: @: @:calc-kbd-query@:}
+
+@c
+@r{ comp@: Z C @:func, args @: 50 @:calc-user-define-composition@:}
+@r{ @: Z D @:key, command @: @:calc-user-define@:}
+@r{ @: Z E @:key, editing @: 30 @:calc-user-define-edit@:}
+@r{ defn@: Z F @:k, c, f, a, n@: 28 @:calc-user-define-formula@:}
+@r{ @: Z G @:key @: @:calc-get-user-defn@:}
+@r{ @: Z I @: @: @:calc-user-define-invocation@:}
+@r{ @: Z K @:key, command @: @:calc-user-define-kbd-macro@:}
+@r{ @: Z P @:key @: @:calc-user-define-permanent@:}
+@r{ @: Z S @: @: 30 @:calc-edit-user-syntax@:}
+@r{ @: Z T @: @: 12 @:calc-timing@:}
+@r{ @: Z U @:key @: @:calc-user-undefine@:}
+
+@end format
+
+@noindent
+NOTES
+
+@enumerate
+@c 1
+@item
+Positive prefix arguments apply to @expr{n} stack entries.
+Negative prefix arguments apply to the @expr{-n}th stack entry.
+A prefix of zero applies to the entire stack. (For @key{LFD} and
+@kbd{M-@key{DEL}}, the meaning of the sign is reversed.)
+
+@c 2
+@item
+Positive prefix arguments apply to @expr{n} stack entries.
+Negative prefix arguments apply to the top stack entry
+and the next @expr{-n} stack entries.
+
+@c 3
+@item
+Positive prefix arguments rotate top @expr{n} stack entries by one.
+Negative prefix arguments rotate the entire stack by @expr{-n}.
+A prefix of zero reverses the entire stack.
+
+@c 4
+@item
+Prefix argument specifies a repeat count or distance.
+
+@c 5
+@item
+Positive prefix arguments specify a precision @expr{p}.
+Negative prefix arguments reduce the current precision by @expr{-p}.
+
+@c 6
+@item
+A prefix argument is interpreted as an additional step-size parameter.
+A plain @kbd{C-u} prefix means to prompt for the step size.
+
+@c 7
+@item
+A prefix argument specifies simplification level and depth.
+1=Default, 2=like @kbd{a s}, 3=like @kbd{a e}.
+
+@c 8
+@item
+A negative prefix operates only on the top level of the input formula.
+
+@c 9
+@item
+Positive prefix arguments specify a word size of @expr{w} bits, unsigned.
+Negative prefix arguments specify a word size of @expr{w} bits, signed.
+
+@c 10
+@item
+Prefix arguments specify the shift amount @expr{n}. The @expr{w} argument
+cannot be specified in the keyboard version of this command.
+
+@c 11
+@item
+From the keyboard, @expr{d} is omitted and defaults to zero.
+
+@c 12
+@item
+Mode is toggled; a positive prefix always sets the mode, and a negative
+prefix always clears the mode.
+
+@c 13
+@item
+Some prefix argument values provide special variations of the mode.
+
+@c 14
+@item
+A prefix argument, if any, is used for @expr{m} instead of taking
+@expr{m} from the stack. @expr{M} may take any of these values:
+@iftex
+{@advance@tableindent10pt
+@end iftex
+@table @asis
+@item Integer
+Random integer in the interval @expr{[0 .. m)}.
+@item Float
+Random floating-point number in the interval @expr{[0 .. m)}.
+@item 0.0
+Gaussian with mean 1 and standard deviation 0.
+@item Error form
+Gaussian with specified mean and standard deviation.
+@item Interval
+Random integer or floating-point number in that interval.
+@item Vector
+Random element from the vector.
+@end table
+@iftex
+}
+@end iftex
+
+@c 15
+@item
+A prefix argument from 1 to 6 specifies number of date components
+to remove from the stack. @xref{Date Conversions}.
+
+@c 16
+@item
+A prefix argument specifies a time zone; @kbd{C-u} says to take the
+time zone number or name from the top of the stack. @xref{Time Zones}.
+
+@c 17
+@item
+A prefix argument specifies a day number (0-6, 0-31, or 0-366).
+
+@c 18
+@item
+If the input has no units, you will be prompted for both the old and
+the new units.
+
+@c 19
+@item
+With a prefix argument, collect that many stack entries to form the
+input data set. Each entry may be a single value or a vector of values.
+
+@c 20
+@item
+With a prefix argument of 1, take a single
+@texline @var{n}@math{\times2}
+@infoline @mathit{@var{N}x2}
+matrix from the stack instead of two separate data vectors.
+
+@c 21
+@item
+The row or column number @expr{n} may be given as a numeric prefix
+argument instead. A plain @kbd{C-u} prefix says to take @expr{n}
+from the top of the stack. If @expr{n} is a vector or interval,
+a subvector/submatrix of the input is created.
+
+@c 22
+@item
+The @expr{op} prompt can be answered with the key sequence for the
+desired function, or with @kbd{x} or @kbd{z} followed by a function name,
+or with @kbd{$} to take a formula from the top of the stack, or with
+@kbd{'} and a typed formula. In the last two cases, the formula may
+be a nameless function like @samp{<#1+#2>} or @samp{<x, y : x+y>}, or it
+may include @kbd{$}, @kbd{$$}, etc. (where @kbd{$} will correspond to the
+last argument of the created function), or otherwise you will be
+prompted for an argument list. The number of vectors popped from the
+stack by @kbd{V M} depends on the number of arguments of the function.
+
+@c 23
+@item
+One of the mapping direction keys @kbd{_} (horizontal, i.e., map
+by rows or reduce across), @kbd{:} (vertical, i.e., map by columns or
+reduce down), or @kbd{=} (map or reduce by rows) may be used before
+entering @expr{op}; these modify the function name by adding the letter
+@code{r} for ``rows,'' @code{c} for ``columns,'' @code{a} for ``across,''
+or @code{d} for ``down.''
+
+@c 24
+@item
+The prefix argument specifies a packing mode. A nonnegative mode
+is the number of items (for @kbd{v p}) or the number of levels
+(for @kbd{v u}). A negative mode is as described below. With no
+prefix argument, the mode is taken from the top of the stack and
+may be an integer or a vector of integers.
+@iftex
+{@advance@tableindent-20pt
+@end iftex
+@table @cite
+@item -1
+(@var{2}) Rectangular complex number.
+@item -2
+(@var{2}) Polar complex number.
+@item -3
+(@var{3}) HMS form.
+@item -4
+(@var{2}) Error form.
+@item -5
+(@var{2}) Modulo form.
+@item -6
+(@var{2}) Closed interval.
+@item -7
+(@var{2}) Closed .. open interval.
+@item -8
+(@var{2}) Open .. closed interval.
+@item -9
+(@var{2}) Open interval.
+@item -10
+(@var{2}) Fraction.
+@item -11
+(@var{2}) Float with integer mantissa.
+@item -12
+(@var{2}) Float with mantissa in @expr{[1 .. 10)}.
+@item -13
+(@var{1}) Date form (using date numbers).
+@item -14
+(@var{3}) Date form (using year, month, day).
+@item -15
+(@var{6}) Date form (using year, month, day, hour, minute, second).
+@end table
+@iftex
+}
+@end iftex
+
+@c 25
+@item
+A prefix argument specifies the size @expr{n} of the matrix. With no
+prefix argument, @expr{n} is omitted and the size is inferred from
+the input vector.
+
+@c 26
+@item
+The prefix argument specifies the starting position @expr{n} (default 1).
+
+@c 27
+@item
+Cursor position within stack buffer affects this command.
+
+@c 28
+@item
+Arguments are not actually removed from the stack by this command.
+
+@c 29
+@item
+Variable name may be a single digit or a full name.
+
+@c 30
+@item
+Editing occurs in a separate buffer. Press @kbd{C-c C-c} (or
+@key{LFD}, or in some cases @key{RET}) to finish the edit, or kill the
+buffer with @kbd{C-x k} to cancel the edit. The @key{LFD} key prevents evaluation
+of the result of the edit.
+
+@c 31
+@item
+The number prompted for can also be provided as a prefix argument.
+
+@c 32
+@item
+Press this key a second time to cancel the prefix.
+
+@c 33
+@item
+With a negative prefix, deactivate all formulas. With a positive
+prefix, deactivate and then reactivate from scratch.
+
+@c 34
+@item
+Default is to scan for nearest formula delimiter symbols. With a
+prefix of zero, formula is delimited by mark and point. With a
+non-zero prefix, formula is delimited by scanning forward or
+backward by that many lines.
+
+@c 35
+@item
+Parse the region between point and mark as a vector. A nonzero prefix
+parses @var{n} lines before or after point as a vector. A zero prefix
+parses the current line as a vector. A @kbd{C-u} prefix parses the
+region between point and mark as a single formula.
+
+@c 36
+@item
+Parse the rectangle defined by point and mark as a matrix. A positive
+prefix @var{n} divides the rectangle into columns of width @var{n}.
+A zero or @kbd{C-u} prefix parses each line as one formula. A negative
+prefix suppresses special treatment of bracketed portions of a line.
+
+@c 37
+@item
+A numeric prefix causes the current language mode to be ignored.
+
+@c 38
+@item
+Responding to a prompt with a blank line answers that and all
+later prompts by popping additional stack entries.
+
+@c 39
+@item
+Answer for @expr{v} may also be of the form @expr{v = v_0} or
+@expr{v - v_0}.
+
+@c 40
+@item
+With a positive prefix argument, stack contains many @expr{y}'s and one
+common @expr{x}. With a zero prefix, stack contains a vector of
+@expr{y}s and a common @expr{x}. With a negative prefix, stack
+contains many @expr{[x,y]} vectors. (For 3D plots, substitute
+@expr{z} for @expr{y} and @expr{x,y} for @expr{x}.)
+
+@c 41
+@item
+With any prefix argument, all curves in the graph are deleted.
+
+@c 42
+@item
+With a positive prefix, refines an existing plot with more data points.
+With a negative prefix, forces recomputation of the plot data.
+
+@c 43
+@item
+With any prefix argument, set the default value instead of the
+value for this graph.
+
+@c 44
+@item
+With a negative prefix argument, set the value for the printer.
+
+@c 45
+@item
+Condition is considered ``true'' if it is a nonzero real or complex
+number, or a formula whose value is known to be nonzero; it is ``false''
+otherwise.
+
+@c 46
+@item
+Several formulas separated by commas are pushed as multiple stack
+entries. Trailing @kbd{)}, @kbd{]}, @kbd{@}}, @kbd{>}, and @kbd{"}
+delimiters may be omitted. The notation @kbd{$$$} refers to the value
+in stack level three, and causes the formula to replace the top three
+stack levels. The notation @kbd{$3} refers to stack level three without
+causing that value to be removed from the stack. Use @key{LFD} in place
+of @key{RET} to prevent evaluation; use @kbd{M-=} in place of @key{RET}
+to evaluate variables.
+
+@c 47
+@item
+The variable is replaced by the formula shown on the right. The
+Inverse flag reverses the order of the operands, e.g., @kbd{I s - x}
+assigns
+@texline @math{x \coloneq a-x}.
+@infoline @expr{x := a-x}.
+
+@c 48
+@item
+Press @kbd{?} repeatedly to see how to choose a model. Answer the
+variables prompt with @expr{iv} or @expr{iv;pv} to specify
+independent and parameter variables. A positive prefix argument
+takes @mathit{@var{n}+1} vectors from the stack; a zero prefix takes a matrix
+and a vector from the stack.
+
+@c 49
+@item
+With a plain @kbd{C-u} prefix, replace the current region of the
+destination buffer with the yanked text instead of inserting.
+
+@c 50
+@item
+All stack entries are reformatted; the @kbd{H} prefix inhibits this.
+The @kbd{I} prefix sets the mode temporarily, redraws the top stack
+entry, then restores the original setting of the mode.
+
+@c 51
+@item
+A negative prefix sets the default 3D resolution instead of the
+default 2D resolution.
+
+@c 52
+@item
+This grabs a vector of the form [@var{prec}, @var{wsize}, @var{ssize},
+@var{radix}, @var{flfmt}, @var{ang}, @var{frac}, @var{symb}, @var{polar},
+@var{matrix}, @var{simp}, @var{inf}]. A prefix argument from 1 to 12
+grabs the @var{n}th mode value only.
+@end enumerate
+
+@iftex
+(Space is provided below for you to keep your own written notes.)
+@page
+@endgroup
+@end iftex
+
+
+@c [end-summary]
+
+@node Key Index, Command Index, Summary, Top
+@unnumbered Index of Key Sequences
+
+@printindex ky
+
+@node Command Index, Function Index, Key Index, Top
+@unnumbered Index of Calculator Commands
+
+Since all Calculator commands begin with the prefix @samp{calc-}, the
+@kbd{x} key has been provided as a variant of @kbd{M-x} which automatically
+types @samp{calc-} for you. Thus, @kbd{x last-args} is short for
+@kbd{M-x calc-last-args}.
+
+@printindex pg
+
+@node Function Index, Concept Index, Command Index, Top
+@unnumbered Index of Algebraic Functions
+
+This is a list of built-in functions and operators usable in algebraic
+expressions. Their full Lisp names are derived by adding the prefix
+@samp{calcFunc-}, as in @code{calcFunc-sqrt}.
+@iftex
+All functions except those noted with ``*'' have corresponding
+Calc keystrokes and can also be found in the Calc Summary.
+@end iftex
+
+@printindex tp
+
+@node Concept Index, Variable Index, Function Index, Top
+@unnumbered Concept Index
+
+@printindex cp
+
+@node Variable Index, Lisp Function Index, Concept Index, Top
+@unnumbered Index of Variables
+
+The variables in this list that do not contain dashes are accessible
+as Calc variables. Add a @samp{var-} prefix to get the name of the
+corresponding Lisp variable.
+
+The remaining variables are Lisp variables suitable for @code{setq}ing
+in your Calc init file or @file{.emacs} file.
+
+@printindex vr
+
+@node Lisp Function Index, , Variable Index, Top
+@unnumbered Index of Lisp Math Functions
+
+The following functions are meant to be used with @code{defmath}, not
+@code{defun} definitions. For names that do not start with @samp{calc-},
+the corresponding full Lisp name is derived by adding a prefix of
+@samp{math-}.
+
+@printindex fn
+
+@bye
+
+
+@ignore
+ arch-tag: 77a71809-fa4d-40be-b2cc-da3e8fb137c0
+@end ignore
--- /dev/null
+\input texinfo
+@c Notes to self regarding line handling:
+@c
+@c Empty lines are often significant before @end directives; avoid them.
+@c
+@c Empty lines before and after @example directives are significant in
+@c info output but not in TeX. Empty lines inside @example directives
+@c are significant.
+
+@c Conventions for formatting examples:
+@c o If the example contains empty lines then put the surrounding empty
+@c lines inside the @example directives. Put them outside otherwise.
+@c o Use @group inside the example only if it shows indentation where
+@c the relation between lines inside is relevant.
+@c o Format line number columns like this:
+@c 1: foo
+@c 2: bar
+@c ^ one space
+@c ^^ two columns, right alignment
+@c o Check line lengths in TeX output; they can typically be no longer
+@c than 70 chars, 60 if the paragraph is indented.
+
+@comment TBD: Document the finer details of statement anchoring?
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment %**start of header (This is for running Texinfo on a region)
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment How to make the various output formats:
+@comment (Thanks to Robert Chassell for supplying this information.)
+@comment Note that Texinfo 4.7 (or later) is needed.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@ignore
+In each of the following pairs of commands, the first generates a
+version with cross references pointing to the GNU Emacs manuals,
+the second with them pointing to the XEmacs manuals.
+ ## Info output
+ makeinfo cc-mode.texi
+ makeinfo -DXEMACS cc-mode.texi
+
+ ## DVI output
+ ## You may need to set up the environment variable TEXINPUTS so
+ ## that tex can find the file texinfo.tex - See the tex
+ ## manpage.
+ texi2dvi cc-mode.texi
+ texi2dvi -t "@set XEMACS " cc-mode.texi
+
+ ## HTML output. (The --no-split parameter is optional)
+ makeinfo --html --no-split cc-mode.texi
+ makeinfo --html --no-split -DXEMACS cc-mode.texi
+
+ ## Plain text output
+ makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
+ --no-headers --output=cc-mode.txt cc-mode.texi
+ makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
+ --no-headers --output=cc-mode.txt -DXEMACS cc-mode.texi
+
+ ## DocBook output
+ makeinfo --docbook --no-split --paragraph-indent=0 \
+ cc-mode.texi
+ makeinfo --docbook --no-split --paragraph-indent=0 \
+ -DXEMACS cc-mode.texi
+
+ ## XML output
+ makeinfo --xml --no-split --paragraph-indent=0 \
+ cc-mode.texi
+ makeinfo --xml --no-split --paragraph-indent=0 \
+ -DXEMACS cc-mode.texi
+
+ #### (You must be in the same directory as the viewed file.)
+
+ ## View DVI output
+ xdvi cc-mode.dvi &
+
+ ## View HTML output
+ mozilla cc-mode.html
+@end ignore
+
+@comment No overfull hbox marks in the dvi file.
+@finalout
+
+@setfilename ../info/ccmode
+@settitle CC Mode Manual
+@footnotestyle end
+
+@c The following four macros generate the filenames and titles of the
+@c main (X)Emacs manual and the Elisp/Lispref manual. Leave the
+@c Texinfo variable `XEMACS' unset to generate a GNU Emacs version, set it
+@c to generate an XEmacs version, e.g. with
+@c "makeinfo -DXEMACS cc-mode.texi".
+@ifset XEMACS
+@macro emacsman
+xemacs
+@end macro
+@macro emacsmantitle
+XEmacs User's Manual
+@end macro
+@macro lispref
+lispref
+@end macro
+@macro lispreftitle
+XEmacs Lisp Reference Manual
+@end macro
+@end ifset
+
+@ifclear XEMACS
+@macro emacsman
+emacs
+@end macro
+@macro emacsmantitle
+GNU Emacs Manual
+@end macro
+@macro lispref
+elisp
+@end macro
+@macro lispreftitle
+GNU Emacs Lisp Reference Manual
+@end macro
+@end ifclear
+
+
+@macro ccmode
+CC Mode
+@end macro
+
+@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 Authors:
+@comment Barry A. Warsaw
+@comment Martin Stjernholm
+@comment Alan Mackenzie
+@comment
+@comment Maintained by Martin Stjernholm and Alan Mackenzie <bug-cc-mode@gnu.org>
+@comment
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@comment Define an index for syntactic symbols.
+@ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss
+ @c For Info, unlike tex, @syncodeindex needs a matching @defindex.
+@defindex ss
+@end ifnottex
+
+@comment Combine key, syntactic symbol and concept indices into one.
+@syncodeindex ss cp
+@syncodeindex ky cp
+
+@copying
+This manual is for CC Mode in Emacs.
+
+Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
+``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@comment Info directory entry for use by install-info. The indentation
+@comment here is by request from the FSF folks.
+@dircategory Emacs
+@direntry
+* CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C,
+ Java, Pike, AWK, and CORBA IDL code.
+@end direntry
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment TeX title page
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@titlepage
+@sp 10
+
+@center @titlefont{CC Mode 5.31}
+@sp 2
+@center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
+@sp 2
+@center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+
+This manual was generated from $Revision$ of $RCSfile$, which can be
+downloaded from
+@url{http://cvs.savannah.gnu.org/viewcvs/emacs/emacs/man/cc-mode.texi}.
+@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
+
+@ifinfo
+@top @ccmode{}
+
+@ccmode{} is a GNU Emacs mode for editing files containing C, C++,
+Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike
+and AWK code. It provides syntax-based indentation, font locking, and
+has several handy commands and some minor modes to make the editing
+easier. It does not provide tools to look up and navigate between
+functions, classes etc - there are other packages for that.
+@end ifinfo
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@menu
+* Introduction::
+* Overview::
+* Getting Started::
+* Commands::
+* Font Locking::
+* Config Basics::
+* Custom Filling and Breaking::
+* Custom Auto-newlines::
+* Clean-ups::
+* Indentation Engine Basics::
+* Customizing Indentation::
+* Custom Macros::
+* Odds and Ends::
+* Sample .emacs File::
+* Performance Issues::
+* Limitations and Known Bugs::
+* FAQ::
+* Updating CC Mode::
+* Mailing Lists and Bug Reports::
+* GNU Free Documentation License::
+* Command and Function Index::
+* Variable Index::
+* Concept and Key Index::
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Commands
+
+* Indentation Commands::
+* Comment Commands::
+* Movement Commands::
+* Filling and Breaking::
+* Minor Modes::
+* Electric Keys::
+* Auto-newlines::
+* Hungry WS Deletion::
+* Subword Movement::
+* Other Commands::
+
+Font Locking
+
+* Font Locking Preliminaries::
+* Faces::
+* Doc Comments::
+* AWK Mode Font Locking::
+
+Configuration Basics
+
+* CC Hooks::
+* Style Variables::
+* Styles::
+
+Styles
+
+* Built-in Styles::
+* Choosing a Style::
+* Adding Styles::
+* File Styles::
+
+Customizing Auto-newlines
+
+* Hanging Braces::
+* Hanging Colons::
+* Hanging Semicolons and Commas::
+
+Hanging Braces
+
+* Custom Braces::
+
+Indentation Engine Basics
+
+* Syntactic Analysis::
+* Syntactic Symbols::
+* Indentation Calculation::
+
+Syntactic Symbols
+
+* Function Symbols::
+* Class Symbols::
+* Conditional Construct Symbols::
+* Switch Statement Symbols::
+* Brace List Symbols::
+* External Scope Symbols::
+* Paren List Symbols::
+* Literal Symbols::
+* Multiline Macro Symbols::
+* Objective-C Method Symbols::
+* Anonymous Class Symbol::
+* Statement Block Symbols::
+* K&R Symbols::
+
+Customizing Indentation
+
+* c-offsets-alist::
+* Interactive Customization::
+* Line-Up Functions::
+* Custom Line-Up::
+* Other Indentation::
+
+Line-Up Functions
+
+* Brace/Paren Line-Up::
+* List Line-Up::
+* Operator Line-Up::
+* Comment Line-Up::
+* Misc Line-Up::
+
+@end detailmenu
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Introduction, Overview, Top, Top
+@comment node-name, next, previous, up
+@chapter Introduction
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex BOCM
+@cindex history
+@cindex awk-mode.el
+@cindex c-mode.el
+@cindex c++-mode.el
+
+Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C,
+C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and
+CIDL), Pike and AWK code. This incarnation of the mode is descended
+from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM
+@t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been
+maintaining since 1992, and @file{awk-mode.el}, a long neglected mode
+in the (X)Emacs base.
+
+Late in 1997, Martin Stjernholm joined Barry on the @ccmode{}
+Maintainers Team, and implemented the Pike support. In 2000 Martin
+took over as the sole maintainer. In 2001 Alan Mackenzie joined the
+team, implementing AWK support in version 5.30. @ccmode{} did not
+originally contain the font lock support for its languages --- that
+was added in version 5.30.
+
+This manual describes @ccmode{}
+@comment The following line must appear on its own, so that the
+version 5.31.
+@comment Release.py script can update the version number automatically
+
+@ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C,
+Java, CORBA's Interface Definition Language, Pike@footnote{A C-like
+scripting language with its roots in the LPC language used in some MUD
+engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this
+way, you can easily set up consistent font locking and coding styles for
+use in editing all of these languages, although AWK is not yet as
+uniformly integrated as the other languages.
+
+@findex c-mode
+@findex c++-mode
+@findex objc-mode
+@findex java-mode
+@findex idl-mode
+@findex pike-mode
+@findex awk-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},
+@code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are
+provided. This package is intended to be a replacement for
+@file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}.
+
+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 Overview, Getting Started, Introduction, Top
+@comment node-name, next, previous, up@cindex organization of the manual
+@chapter Overview of the Manual
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@noindent
+The manual starts with several introductory chapters (including this
+one).
+
+@noindent
+The next chunk of the manual describes the day to day @emph{use} of
+@ccmode{} (as contrasted with how to customize it).
+
+@itemize @bullet
+@item
+The chapter ``Commands'' describes in detail how to use (nearly) all
+of @ccmode{}'s features. There are extensive cross-references from
+here to the corresponding sections later in the manual which tell you
+how to customize these features.
+
+@item
+``Font Locking'' describes how ``syntax highlighting'' is applied to
+your buffers. It is mainly background information and can be skipped
+over at a first reading.
+@end itemize
+
+@noindent
+The next chunk of the manual describes how to @emph{customize}
+@ccmode{}. Typically, an overview of a topic is given at the chapter
+level, then the sections and subsections describe the material in
+increasing detail.
+
+@itemize @bullet
+@item
+The chapter ``Configuration Basics'' tells you @emph{how} to write
+customizations - whether in hooks, in styles, in both, or in neither,
+depending on your needs. It describes the @ccmode{} style system and
+lists the standard styles that @ccmode{} supplies.
+
+@item
+The next few chapters describe in detail how to customize the various
+features of @ccmode{}.
+
+@item
+Finally, there is a sample @file{.emacs} fragment, which might help you
+in creating your own customization.
+@end itemize
+
+@noindent
+The manual ends with ``this and that'', things that don't fit cleanly
+into any of the previous chunks.
+
+@itemize @bullet
+@item
+Two chapters discuss the performance of @ccmode{} and known
+bugs/limitations.
+
+@item
+The FAQ contains a list of common problems and questions.
+
+@item
+The next two chapters tell you how to get in touch with the @ccmode{}
+project - whether for updating @ccmode{} or submitting bug reports.
+@end itemize
+
+@noindent
+Finally, there are the customary indices.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Getting Started, Commands, Overview, Top
+@comment node-name, next, previous, up
+@chapter Getting Started
+@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 might not
+have the latest @ccmode{} release and might want to upgrade your copy
+(see below).
+
+You should probably start by skimming through the entire chapter
+@ref{Commands} to get an overview of @ccmode{}'s capabilities.
+
+After trying out some commands, you may dislike some aspects of
+@ccmode{}'s default configuration. Here is an outline of how to
+change some of the settings that newcomers to @ccmode{} most often
+want to change:
+
+@table @asis
+@item c-basic-offset
+This Lisp variable holds an integer, the number of columns @ccmode{}
+indents nested code. To set this value to 6, customize
+@code{c-basic-offset} or put this into your @file{.emacs}:
+
+@example
+(setq c-basic-offset 6)
+@end example
+
+@item The (indentation) style
+The basic ``shape'' of indentation created by @ccmode{}---by default,
+this is @code{gnu} style (except for Java and AWK buffers). A list of
+the available styles and their descriptions can be found in
+@ref{Built-in Styles}. A complete specification of the @ccmode{}
+style system, including how to create your own style, can be found in
+the chapter @ref{Styles}. To set your style to @code{linux}, either
+customize @code{c-default-style} or put this into your @file{.emacs}:
+
+@example
+(setq c-default-style '((java-mode . "java")
+ (awk-mode . "awk")
+ (other . "linux")))
+@end example
+
+@item Electric Indentation
+Normally, when you type ``punctuation'' characters such as @samp{;} or
+@samp{@{}, @ccmode{} instantly reindents the current line. This can
+be disconcerting until you get used to it. To disable @dfn{electric
+indentation} in the current buffer, type @kbd{C-c C-l}. Type the same
+thing to enable it again. To have electric indentation disabled by
+default, put the following into your @file{.emacs} file@footnote{There
+is no ``easy customization'' facility for making this change.}:
+
+@example
+(setq-default c-electric-flag nil)
+@end example
+
+@noindent
+Details of this and other similar ``Minor Modes'' appear in the
+section @ref{Minor Modes}.
+
+@item Making the @key{RET} key indent the new line
+The standard Emacs binding for @key{RET} just adds a new line. If you
+want it to reindent the new line as well, rebind the key. Note that
+the action of rebinding would fail if the pertinent keymap didn't yet
+exist---we thus need to delay the action until after @ccmode{} has
+been loaded. Put the following code into your @file{.emacs}:
+
+@example
+(defun my-make-CR-do-indent ()
+ (define-key c-mode-base-map "\C-m" 'c-context-line-break))
+(add-hook 'c-initialization-hook 'my-make-CR-do-indent)
+@end example
+
+@noindent
+This example demonstrates the use of a very powerful @ccmode{} (and
+Emacs) facility, the hook. The use of @ccmode{}'s hooks is described
+in @ref{CC Hooks}.
+@end table
+
+All these settings should occur in your @file{.emacs} @emph{before}
+any @ccmode{} buffers get loaded---in particular, before any call of
+@code{desktop-read}.
+
+As you get to know the mode better, you may want to make more
+ambitious changes to your configuration. For this, you should start
+reading the chapter @ref{Config Basics}.
+
+If you are upgrading an existing @ccmode{} installation, please see
+the @file{README} file for installation details. In particular, if
+you are going to be editing AWK files, @file{README} describes how to
+configure your (X)Emacs so that @ccmode{} will supersede the obsolete
+@code{awk-mode.el} which might have been supplied with your (X)Emacs.
+@ccmode{} might not work with older versions of Emacs or XEmacs. See
+the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net}
+for the latest information on Emacs version and package compatibility
+(@pxref{Updating CC Mode}).
+
+@deffn Command 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.
+@end deffn
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Commands, Font Locking, Getting Started, Top
+@comment node-name, next, previous, up
+@chapter Commands
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+This chapter specifies all of CC Mode's commands, and thus contains
+nearly everything you need to know to @emph{use} @ccmode{} (as
+contrasted with configuring it). @dfn{Commands} here means both
+control key sequences and @dfn{electric keys}, these being characters
+such as @samp{;} which, as well as inserting themselves into the
+buffer, also do other things.
+
+You might well want to review
+@ifset XEMACS
+@ref{Lists,,,@emacsman{}, @emacsmantitle{}},
+@end ifset
+@ifclear XEMACS
+@ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}},
+@end ifclear
+which describes commands for moving around brace and parenthesis
+structures.
+
+
+@menu
+* Indentation Commands::
+* Comment Commands::
+* Movement Commands::
+* Filling and Breaking::
+* Minor Modes::
+* Electric Keys::
+* Auto-newlines::
+* Hungry WS Deletion::
+* Subword Movement::
+* Other Commands::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Indentation Commands, Comment Commands, Commands, Commands
+@comment node-name, next, previous,up
+@section Indentation Commands
+@cindex indentation
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The following commands reindent C constructs. Note that when you
+change your coding style, either interactively or through some other
+means, your file does @emph{not} automatically get reindented. You
+will need to execute one of the following commands to see the effects
+of your changes.
+
+@cindex GNU indent program
+Also, variables like @code{c-hanging-*} and @code{c-cleanup-list}
+(@pxref{Custom Auto-newlines}) only affect how on-the-fly code is
+formatted. Changing the ``hanginess'' of a brace and then
+reindenting, will not move the brace to a different line. For this,
+you're better off getting an external program like GNU @code{indent},
+which will rearrange brace location, amongst other things.
+
+Preprocessor directives are handled as syntactic whitespace from other
+code, i.e. they can be interspersed anywhere without affecting the
+indentation of the surrounding code, just like comments.
+
+The code inside macro definitions is, by default, still analyzed
+syntactically so that you get relative indentation there just as you'd
+get if the same code was outside a macro. However, since there is no
+hint about the syntactic context, i.e. whether the macro expands to an
+expression, to some statements, or perhaps to whole functions, the
+syntactic recognition can be wrong. @ccmode{} manages to figure it
+out correctly most of the time, though.
+
+Reindenting large sections of code can take a long time. When
+@ccmode{} reindents a region of code, it is essentially equivalent to
+hitting @key{TAB} on every line of the region.
+
+These commands indent code:
+
+@table @asis
+@item @kbd{@key{TAB}} (@code{c-indent-command})
+@kindex TAB
+@findex c-indent-command
+@findex indent-command (c-)
+This command indents the current line. That is all you need to know
+about it for normal use.
+
+@code{c-indent-command} does different things, depending on the
+setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
+Basics}):
+
+@itemize @bullet
+@item
+When it's non-@code{nil} (which it normally is), the command indents
+the line according to its syntactic context. With a prefix argument
+(@kbd{C-u @key{TAB}}), it will re-indent the entire
+expression@footnote{this is only useful for a line starting with a
+comment opener or an opening brace, parenthesis, or string quote.}
+that begins at the line's left margin.
+
+@item
+When it's @code{nil}, the command indents the line by an extra
+@code{c-basic-offset} columns. A prefix argument acts as a
+multiplier. A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to -1,
+removing @code{c-basic-offset} columns from the indentation.
+@end itemize
+
+The precise behavior is modified by several variables: With
+@code{c-tab-always-indent}, you can make @key{TAB} insert whitespace
+in some circumstances---@code{c-insert-tab-function} then defines
+precisely what sort of ``whitespace'' this will be. Set the standard
+Emacs variable @code{indent-tabs-mode} to @code{t} if you want real
+@samp{tab} characters to be used in the indentation, to @code{nil} if
+you want only spaces. @xref{Just Spaces,,, @emacsman{},
+@emacsmantitle{}}.
+
+@defopt c-tab-always-indent
+@vindex tab-always-indent (c-)
+@cindex literal
+This variable modifies how @key{TAB} operates.
+@itemize @bullet
+@item
+When it is @code{t} (the default), @key{TAB} simply indents the
+current line.
+@item
+When it is @code{nil}, @key{TAB} (re)indents the line only if point is
+to the left of the first non-whitespace character on the line.
+Otherwise it inserts some whitespace (a tab or an equivalent number of
+spaces - see below) at point.
+@item
+With some other value, the line is reindented. Additionally, if point
+is within a string or comment, some whitespace is inserted.
+@end itemize
+@end defopt
+
+@defopt c-insert-tab-function
+@vindex insert-tab-function (c-)
+@findex tab-to-tab-stop
+When ``some whitespace'' is inserted as described above, what actually
+happens is that the function stored in @code{c-insert-tab-function} is
+called. Normally, this is @code{insert-tab}, which inserts a real tab
+character or the equivalent number of spaces (depending on
+@code{indent-tabs-mode}). Some people, however, set
+@code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get
+hard tab stops when indenting.
+@end defopt
+@end table
+
+@noindent
+The kind of indentation the next five commands do depends on the
+setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
+Basics}):
+@itemize @bullet
+@item
+when it is non-@code{nil} (the default), the commands indent lines
+according to their syntactic context;
+@item
+when it is @code{nil}, they just indent each line the same amount as
+the previous non-blank line. The commands that indent a region aren't
+very useful in this case.
+@end itemize
+
+@table @asis
+@item @kbd{C-j} (@code{newline-and-indent})
+@kindex C-j
+@findex newline-and-indent
+Inserts a newline and indents the new blank line, ready to start
+typing. This is a standard (X)Emacs command.
+
+@item @kbd{C-M-q} (@code{c-indent-exp})
+@kindex C-M-q
+@findex c-indent-exp
+@findex indent-exp (c-)
+Indents an entire balanced brace or parenthesis expression. Note that
+point must be on the opening brace or parenthesis of the expression
+you want to indent.
+
+@item @kbd{C-c C-q} (@code{c-indent-defun})
+@kindex C-c C-q
+@findex c-indent-defun
+@findex indent-defun (c-)
+Indents the entire top-level function, class or macro definition
+encompassing point. It leaves point unchanged. This function can't be
+used to reindent a nested brace construct, such as a nested class or
+function, or a Java method. The top-level construct being reindented
+must be complete, i.e. it must have both a beginning brace and an ending
+brace.
+
+@item @kbd{C-M-\} (@code{indent-region})
+@kindex C-M-\
+@findex indent-region
+Indents an arbitrary region of code. This is a standard Emacs command,
+tailored for C code in a @ccmode{} buffer. Note, of course, that point
+and mark must delineate the region you want to indent.
+
+@item @kbd{C-M-h} (@code{c-mark-function})
+@kindex C-M-h
+@findex c-mark-function
+@findex mark-function (c-)
+While not strictly an indentation command, this is useful for marking
+the current top-level function or class definition as the current
+region. As with @code{c-indent-defun}, this command operates on
+top-level constructs, and can't be used to mark say, a Java method.
+@end table
+
+These variables are also useful when indenting code:
+
+@defopt indent-tabs-mode
+This is a standard Emacs variable that controls how line indentation
+is composed. When it's non-@code{nil}, tabs can be used in a line's
+indentation, otherwise only spaces are used.
+@end defopt
+
+@defopt c-progress-interval
+@vindex progress-interval (c-)
+When indenting large regions of code, this variable controls how often a
+progress message is displayed. Set this variable to @code{nil} to
+inhibit the progress messages, or set it to an integer which is how
+often (in seconds) progress messages are to be displayed.
+@end defopt
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Comment Commands, Movement Commands, Indentation Commands, Commands
+@comment node-name, next, previous, up
+@section Comment Commands
+@cindex comments (insertion of)
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@table @asis
+@item @kbd{C-c C-c} (@code{comment-region})
+@kindex C-c C-c
+@findex comment-region
+This command comments out the lines that start in the region. With a
+negative argument, it does the opposite - it deletes the comment
+delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU
+Emacs Manual}, for fuller details. @code{comment-region} isn't
+actually part of @ccmode{} - it is given a @ccmode{} binding for
+convenience.
+
+@item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.})
+@kindex M-;
+@findex comment-dwim
+@findex indent-for-comment
+Insert a comment at the end of the current line, if none is there
+already. Then reindent the comment according to @code{comment-column}
+@ifclear XEMACS
+(@pxref{Options for Comments,,, emacs, GNU Emacs Manual})
+@end ifclear
+@ifset XEMACS
+(@pxref{Comments,,, xemacs, XEmacs User's Manual})
+@end ifset
+and the variables below. Finally, position the point after the
+comment starter. @kbd{C-u M-;} kills any comment on the current line,
+together with any whitespace before it. This is a standard Emacs
+command, but @ccmode{} enhances it a bit with two variables:
+
+@defopt c-indent-comment-alist
+@vindex indent-comment-alist (c-)
+@vindex comment-column
+This style variable allows you to vary the column that @kbd{M-;} puts
+the comment at, depending on what sort of code is on the line, and
+possibly the indentation of any similar comment on the preceding line.
+It is an association list that maps different types of lines to
+actions describing how they should be handled. If a certain line type
+isn't present on the list then the line is indented to the column
+specified by @code{comment-column}.
+
+See the documentation string for a full description of this
+variable (use @kbd{C-h v c-indent-comment-alist}).
+@end defopt
+
+@defopt c-indent-comments-syntactically-p
+@vindex indent-comments-syntactically-p (c-)
+Normally, when this style variable is @code{nil}, @kbd{M-;} will
+indent comment-only lines according to @code{c-indent-comment-alist},
+just as it does with lines where other code precede the comments.
+However, if you want it to act just like @key{TAB} for comment-only
+lines you can get that by setting
+@code{c-indent-comments-syntactically-p} to non-@code{nil}.
+
+If @code{c-indent-comments-syntactically-p} is non-@code{nil} then
+@code{c-indent-comment-alist} won't be consulted at all for comment-only
+lines.
+@end defopt
+@end table
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Movement Commands, Filling and Breaking, Comment Commands, Commands
+@comment node-name, next, previous, up
+@section Movement Commands
+@cindex movement
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ccmode{} contains some useful commands for moving around in C code.
+
+@table @asis
+@item @kbd{C-M-a} (@code{c-beginning-of-defun})
+@itemx @kbd{C-M-e} (@code{c-end-of-defun})
+@findex c-beginning-of-defun
+@findex c-end-of-defun
+
+Move to the beginning or end of the current or next function. Other
+constructs (such as a structs or classes) which have a brace block
+also count as ``functions'' here. To move over several functions, you
+can give these commands a repeat count.
+
+The start of a function is at its header. The end of the function is
+after its closing brace, or after the semicolon of a construct (such
+as a @code{struct}) which doesn't end at the brace. These two
+commands try to leave point at the beginning of a line near the actual
+start or end of the function. This occasionally causes point not to
+move at all.
+
+These functions are analogous to the Emacs built-in commands
+@code{beginning-of-defun} and @code{end-of-defun}, except they
+eliminate the constraint that the top-level opening brace of the defun
+must be in column zero. See @ref{Defuns,,,@emacsman{},
+@emacsmantitle{}}, for more information.
+
+@item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun})
+@itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun})
+@kindex C-M-a (AWK Mode)
+@kindex C-M-e (AWK Mode)
+@findex c-awk-beginning-of-defun
+@findex awk-beginning-of-defun (c-)
+@findex c-awk-end-of-defun
+@findex awk-end-of-defun (c-)
+Move to the beginning or end of the current or next AWK defun. These
+commands can take prefix-arguments, their functionality being entirely
+equivalent to @code{beginning-of-defun} and @code{end-of-defun}.
+
+AWK Mode @dfn{defuns} are either pattern/action pairs (either of which
+might be implicit) or user defined functions. Having the @samp{@{} and
+@samp{@}} (if there are any) in column zero, as is suggested for some
+modes, is neither necessary nor helpful in AWK mode.
+
+@item @kbd{M-a} (@code{c-beginning-of-statement})
+@itemx @kbd{M-e} (@code{c-end-of-statement})
+@kindex M-a
+@kindex M-e
+@findex c-beginning-of-statement
+@findex c-end-of-statement
+@findex beginning-of-statement (c-)
+@findex end-of-statement (c-)
+Move to the beginning or end of the innermost C statement. If point
+is already there, move to the next beginning or end of a statement,
+even if that means moving into a block. (Use @kbd{C-M-b} or
+@kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n}
+means move over @var{n} statements.
+
+If point is within or next to a comment or a string which spans more
+than one line, these commands move by sentences instead of statements.
+
+When called from a program, these functions take three optional
+arguments: the repetition count, a buffer position limit which is the
+farthest back to search for the syntactic context, and a flag saying
+whether to do sentence motion in or near comments and multiline
+strings.
+
+@item @kbd{C-c C-u} (@code{c-up-conditional})
+@kindex C-c C-u
+@findex c-up-conditional
+@findex up-conditional (c-)
+Move back to the containing preprocessor conditional, leaving the mark
+behind. A prefix argument acts as a repeat count. With a negative
+argument, move forward to the end of the containing preprocessor
+conditional.
+
+@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
+function stops at them when going backward, but not when going
+forward.
+
+This key sequence is not bound in AWK Mode, which doesn't have
+preprocessor statements.
+
+@item @kbd{M-x c-up-conditional-with-else}
+@findex c-up-conditional-with-else
+@findex up-conditional-with-else (c-)
+A variety of @code{c-up-conditional} that also stops at @samp{#else}
+lines. Normally those lines are ignored.
+
+@item @kbd{M-x c-down-conditional}
+@findex c-down-conditional
+@findex down-conditional (c-)
+Move forward into the next nested preprocessor conditional, leaving
+the mark behind. A prefix argument acts as a repeat count. With a
+negative argument, move backward into the previous nested preprocessor
+conditional.
+
+@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
+function stops at them when going forward, but not when going backward.
+
+@item @kbd{M-x c-down-conditional-with-else}
+@findex c-down-conditional-with-else
+@findex down-conditional-with-else (c-)
+A variety of @code{c-down-conditional} that also stops at @samp{#else}
+lines. Normally those lines are ignored.
+
+@item @kbd{C-c C-p} (@code{c-backward-conditional})
+@itemx @kbd{C-c C-n} (@code{c-forward-conditional})
+@kindex C-c C-p
+@kindex C-c C-n
+@findex c-backward-conditional
+@findex c-forward-conditional
+@findex backward-conditional (c-)
+@findex forward-conditional (c-)
+Move backward or forward across a preprocessor conditional, leaving
+the mark behind. A prefix argument acts as a repeat count. With a
+negative argument, move in the opposite direction.
+
+These key sequences are not bound in AWK Mode, which doesn't have
+preprocessor statements.
+
+@item @kbd{M-x c-backward-into-nomenclature}
+@itemx @kbd{M-x c-forward-into-nomenclature}
+@findex c-backward-into-nomenclature
+@findex c-forward-into-nomenclature
+@findex backward-into-nomenclature (c-)
+@findex forward-into-nomenclature (c-)
+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}.
+
+These commands move backward or forward to the beginning of the next
+capitalized word. With prefix argument @var{n}, move @var{n} times.
+If @var{n} is negative, move in the opposite direction.
+
+Note that these two commands have been superseded by
+@code{c-subword-mode}, which you should use instead. @xref{Subword
+Movement}. They might be removed from a future release of @ccmode{}.
+@end table
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Filling and Breaking, Minor Modes, Movement Commands, Commands
+@comment node-name, next, previous, up
+@section Filling and Line Breaking Commands
+@cindex text filling
+@cindex line breaking
+@cindex comment handling
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Since there's a lot of normal text in comments and string literals,
+@ccmode{} provides features to edit these like in text mode. The goal
+is to do it seamlessly, i.e. you can use auto fill mode, sentence and
+paragraph movement, paragraph filling, adaptive filling etc. wherever
+there's a piece of normal text without having to think much about it.
+@ccmode{} keeps the indentation, fixes suitable comment line prefixes,
+and so on.
+
+You can configure the exact way comments get filled and broken, and
+where Emacs does auto-filling (see @pxref{Custom Filling and
+Breaking}). Typically, the style system (@pxref{Styles}) will have
+set this up for you, so you probably won't have to bother.
+
+@findex auto-fill-mode
+@cindex Auto Fill mode
+@cindex paragraph filling
+Line breaks are by default handled (almost) the same regardless of
+whether they are made by auto fill mode (@pxref{Auto Fill,,,
+@emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with
+@kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In
+string literals, the new line gets the same indentation as the
+previous nonempty line.@footnote{You can change this default by
+setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols}
+and @pxref{Customizing Indentation})}.
+
+@table @asis
+@item @kbd{M-q} (@code{c-fill-paragraph})
+@kindex M-q
+@findex c-fill-paragraph
+@findex fill-paragraph (c-)
+@cindex Javadoc markup
+@cindex Pike autodoc markup
+This command fills multiline string literals and both block
+and line style comments. In Java buffers, the Javadoc markup words
+are recognized as paragraph starters. The line oriented Pike autodoc
+markup words are recognized in the same way in Pike mode.
+
+The formatting of the starters (@code{/*}) and enders (@code{*/}) of
+block comments are kept as they were before the filling. I.e., if
+either the starter or ender were on a line of its own, then it stays
+on its own line; conversely, if the delimiter has comment text on its
+line, it keeps at least one word of that text with it on the line.
+
+This command is the replacement for @code{fill-paragraph} in @ccmode{}
+buffers.
+
+@item @kbd{M-j} (@code{c-indent-new-comment-line})
+@kindex M-j
+@findex c-indent-new-comment-line
+@findex indent-new-comment-line (c-)
+This breaks the current line at point and indents the new line. If
+point was in a comment, the new line gets the proper comment line
+prefix. If point was inside a macro, a backslash is inserted before
+the line break. It is the replacement for
+@code{indent-new-comment-line}.
+
+@item @kbd{M-x c-context-line-break}
+@findex c-context-line-break
+@findex context-line-break (c-)
+Insert a line break suitable to the context: If the point is inside a
+comment, the new line gets the suitable indentation and comment line
+prefix like @code{c-indent-new-comment-line}. In normal code it's
+indented like @code{newline-and-indent} would do. In macros it acts
+like @code{newline-and-indent} but additionally inserts and optionally
+aligns the line ending backslash so that the macro remains unbroken.
+@xref{Custom Macros}, for details about the backslash alignment. In a
+string, a backslash is inserted only if the string is within a
+macro@footnote{In GCC, unescaped line breaks within strings are
+valid.}.
+
+This function is not bound to a key by default, but it's intended to be
+used on the @kbd{RET} key. If you like the behavior of
+@code{newline-and-indent} on @kbd{RET}, you should consider switching to
+this function. @xref{Sample .emacs File}.
+
+@item @kbd{M-x c-context-open-line}
+@findex c-context-open-line
+@findex context-open-line (c-)
+This is to @kbd{C-o} (@kbd{M-x open-line}) as
+@code{c-context-line-break} is to @kbd{RET}. I.e. it works just like
+@code{c-context-line-break} but leaves the point before the inserted
+line break.
+@end table
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Minor Modes, Electric Keys, Filling and Breaking, Commands
+@comment node-name, next, previous, up
+@section Minor Modes
+@cindex Minor Modes
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ccmode{} contains several minor-mode-like features that you might
+find useful while writing new code or editing old code:
+
+@table @asis
+@item electric mode
+When this is enabled, certain visible characters cause reformatting as
+they are typed. This is normally helpful, but can be a nuisance when
+editing chaotically formatted code. It can also be disconcerting,
+especially for users who are new to @ccmode{}.
+@item auto-newline mode
+This automatically inserts newlines where you'd probably want to type
+them yourself, e.g. after typing @samp{@}}s. Its action is suppressed
+when electric mode is disabled.
+@item hungry-delete mode
+This lets you delete a contiguous block of whitespace with a single
+key - for example, the newline and indentation just inserted by
+auto-newline when you want to back up and write a comment after the
+last statement.
+@item subword mode
+This mode makes basic word movement commands like @kbd{M-f}
+(@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the
+parts of sillycapsed symbols as different words.
+E.g. @samp{NSGraphicsContext} is treated as three words @samp{NS},
+@samp{Graphics}, and @samp{Context}.
+@item syntactic-indentation mode
+When this is enabled (which it normally is), indentation commands such
+as @kbd{C-j} indent lines of code according to their syntactic
+structure. Otherwise, a line is simply indented to the same level as
+the previous one and @kbd{@key{TAB}} adjusts the indentation in steps
+of `c-basic-offset'.
+@end table
+
+Full details on how these minor modes work are at @ref{Electric Keys},
+@ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement},
+and @ref{Indentation Engine Basics}.
+
+You can toggle each of these minor modes on and off, and you can
+configure @ccmode{} so that it starts up with your favourite
+combination of them (@pxref{Sample .emacs File}). By default, when
+you initialize a buffer, electric mode and syntactic-indentation mode
+are enabled but the other two modes are disabled.
+
+@ccmode{} displays the current state of the first four of these minor
+modes on the modeline by appending letters to the major mode's name,
+one letter for each enabled minor mode - @samp{l} for electric mode,
+@samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and
+@samp{w} for subword mode. If all these modes were enabled, you'd see
+@samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of
+the language in question for the other languages @ccmode{} supports.}.
+
+Here are the commands to toggle these modes:
+
+@table @asis
+@item @kbd{C-c C-l} (@code{c-toggle-electric-state})
+@kindex C-c C-l
+@findex c-toggle-electric-state
+@findex toggle-electric-state (c-)
+Toggle electric minor mode. When the command turns the mode off, it
+also suppresses auto-newline mode.
+
+@item @kbd{C-c C-a} (@code{c-toggle-auto-newline})
+@kindex C-c C-a
+@findex c-toggle-auto-newline
+@findex toggle-auto-newline (c-)
+Toggle auto-newline minor mode. When the command turns the mode on,
+it also enables electric minor mode.
+
+@item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.}
+@findex c-toggle-hungry-state
+@findex toggle-hungry-state (c-)
+Toggle hungry-delete minor mode.
+
+@item @kbd{M-x c-toggle-auto-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-t}.}
+@findex c-toggle-auto-hungry-state
+@findex toggle-auto-hungry-state (c-)
+Toggle both auto-newline and hungry delete minor modes.
+
+@item @kbd{C-c C-w} (@code{M-x c-subword-mode})
+@kindex C-c C-w
+@findex c-subword-mode
+@findex subword-mode (c-)
+Toggle subword mode.
+
+@item @kbd{M-x c-toggle-syntactic-indentation}
+@findex c-toggle-syntactic-indentation
+@findex toggle-syntactic-indentation (c-)
+Toggle syntactic-indentation mode.
+@end table
+
+Common to all the toggle functions above is that if they are called
+programmatically, they take an optional numerical argument. A
+positive value will turn on the minor mode (or both of them in the
+case of @code{c-toggle-auto-hungry-state}) and a negative value will
+turn it (or them) off.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Electric Keys, Auto-newlines, Minor Modes, Commands
+@comment node-name, next, previous, up
+@section Electric Keys and Keywords
+@cindex electric characters
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Most punctuation keys provide @dfn{electric} behavior - as well as
+inserting themselves they perform some other action, such as
+reindenting the line. This reindentation saves you from having to
+reindent a line manually after typing, say, a @samp{@}}. A few
+keywords, such as @code{else}, also trigger electric action.
+
+You can inhibit the electric behaviour described here by disabling
+electric minor mode (@pxref{Minor Modes}).
+
+Common to all these keys is that they only behave electrically when
+used in normal code (as contrasted with getting typed in a string
+literal or comment). Those which cause re-indentation do so only when
+@code{c-syntactic-indentation} has a non-@code{nil} value (which it
+does by default).
+
+These keys and keywords are:
+@c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more
+@c like a bug in the code than a bug in this document. It'll get
+@c fixed in the code sometime.
+
+@table @kbd
+@item #
+@kindex #
+@findex c-electric-pound
+@findex electric-pound (c-)
+@vindex c-electric-pound-behavior
+@vindex electric-pound-behavior (c-)
+Pound (bound to @code{c-electric-pound}) is electric when typed as the
+first non-whitespace character on a line and not within a macro
+definition. 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 preprocessor macro definitions.
+
+Pound is not electric in AWK buffers, where @samp{#} starts a comment,
+and is bound to @code{self-insert-command} like any typical printable
+character.
+@c ACM, 2004/8/24: Change this (and the code) to do AWK comment
+@c reindentation.
+
+@item *
+@kindex *
+@itemx /
+@kindex /
+@findex c-electric-star
+@findex electric-star (c-)
+@findex c-electric-slash
+@findex electric-slash (c-)
+A star (bound to @code{c-electric-star}) or a slash
+(@code{c-electric-slash}) causes reindentation when you type it as the
+second component of a C style block comment opener (@samp{/*}) or a
+C++ line comment opener (@samp{//}) respectively, but only if the
+comment opener is the first thing on the line (i.e. there's only
+whitespace before it).
+
+Additionally, you can configure @ccmode{} so that typing a slash at
+the start of a line within a block comment will terminate the
+comment. You don't need to have electric minor mode enabled to get
+this behaviour. @xref{Clean-ups}.
+
+In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not
+electric.
+
+@item <
+@kindex <
+@itemx >
+@kindex >
+@findex c-electric-lt-gt
+@findex electric-lt-gt (c-)
+A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is
+electric in two circumstances: when it is an angle bracket in a C++
+@samp{template} declaration (and similar constructs in other
+languages) and when it is the second of two @kbd{<} or @kbd{>}
+characters in a C++ style stream operator. In either case, the line
+is reindented. Angle brackets in C @samp{#include} directives are not
+electric.
+
+@item (
+@kindex (
+@itemx )
+@kindex )
+@findex c-electric-paren
+@findex electric-paren (c-)
+The normal parenthesis characters @samp{(} and @samp{)} (bound to
+@code{c-electric-paren}) reindent the current line. This is useful
+for getting the closing parenthesis of an argument list aligned
+automatically.
+
+You can also configure @ccmode{} to insert a space automatically
+between a function name and the @samp{(} you've just typed, and to
+remove it automatically after typing @samp{)}, should the argument
+list be empty. You don't need to have electric minor mode enabled to
+get these actions. @xref{Clean-ups}.
+
+@item @{
+@kindex @{
+@itemx @}
+@kindex @}
+@findex c-electric-brace
+@findex electric-brace (c-)
+Typing a brace (bound to @code{c-electric-brace}) reindents the
+current line. Also, one or more newlines might be inserted if
+auto-newline minor mode is enabled. @xref{Auto-newlines}.
+Additionally, you can configure @ccmode{} to compact excess whitespace
+inserted by auto-newline mode in certain circumstances.
+@xref{Clean-ups}.
+
+@item :
+@kindex :
+@findex c-electric-colon
+@findex electric-colon (c-)
+Typing a colon (bound to @code{c-electric-colon}) reindents the
+current line. Additionally, one or more newlines might be inserted if
+auto-newline minor mode is enabled. @xref{Auto-newlines}. If you
+type a second colon immediately after such an auto-newline, by default
+the whitespace between the two colons is removed, leaving a C++ scope
+operator. @xref{Clean-ups}.
+
+If you prefer, you can insert @samp{::} in a single operation,
+avoiding all these spurious reindentations, newlines, and clean-ups.
+@xref{Other Commands}.
+
+@item ;
+@kindex ;
+@itemx ,
+@kindex ,
+@findex c-electric-semi&comma
+@findex electric-semi&comma (c-)
+Typing a semicolon or comma (bound to @code{c-electric-semi&comma})
+reindents the current line. Also, a newline might be inserted if
+auto-newline minor mode is enabled. @xref{Auto-newlines}.
+Additionally, you can configure @ccmode{} so that when auto-newline
+has inserted whitespace after a @samp{@}}, it will be removed again
+when you type a semicolon or comma just after it. @xref{Clean-ups}.
+
+@end table
+
+@deffn Command c-electric-continued-statement
+@findex electric-continued-statement (c-)
+
+Certain keywords are electric, causing reindentation when they are
+preceded only by whitespace on the line. The keywords are those that
+continue an earlier statement instead of starting a new one:
+@code{else}, @code{while}, @code{catch} (only in C++ and Java) and
+@code{finally} (only in Java).
+
+An example:
+
+@example
+@group
+for (i = 0; i < 17; i++)
+ if (a[i])
+ res += a[i]->offset;
+else
+@end group
+@end example
+
+Here, the @code{else} should be indented like the preceding @code{if},
+since it continues that statement. @ccmode{} will automatically
+reindent it after the @code{else} has been typed in full, since only
+then is it possible to decide whether it's a new statement or a
+continuation of the preceding @code{if}.
+
+@vindex abbrev-mode
+@findex abbrev-mode
+@cindex Abbrev mode
+@ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, @emacsman{}, @emacsmantitle{}})
+to accomplish this. It's therefore turned on by default in all language
+modes except IDL mode, since CORBA IDL doesn't have any statements.
+@end deffn
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands
+@comment node-name, next, previous, up
+@section Auto-newline Insertion
+@cindex auto-newline
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor
+Modes}), @ccmode{} inserts newlines for you automatically (in certain
+syntactic contexts) when you type a left or right brace, a colon, a
+semicolon, or a comma. Sometimes a newline appears before the
+character you type, sometimes after it, sometimes both.
+
+Auto-newline only triggers when the following conditions hold:
+
+@itemize @bullet
+@item
+Auto-newline minor mode is enabled, as evidenced by the indicator
+@samp{a} after the mode name on the modeline (e.g. @samp{C/a} or
+@samp{C/la}).
+
+@item
+The character was typed at the end of a line, or with only whitespace
+after it, and possibly a @samp{\} escaping the newline.
+
+@item
+The character is not on its own line already. (This applies only to
+insertion of a newline @emph{before} the character.)
+
+@item
+@cindex literal
+@cindex syntactic whitespace
+The character was not typed inside of a literal @footnote{A
+@dfn{literal} is defined as any comment, string, or preprocessor macro
+definition. These constructs are also known as @dfn{syntactic
+whitespace} since they are usually ignored when scanning C code.}.
+
+@item
+No numeric argument was supplied to the command (i.e. it was typed as
+normal, with no @kbd{C-u} prefix).
+@end itemize
+
+You can configure the precise circumstances in which newlines get
+inserted (see @pxref{Custom Auto-newlines}). Typically, the style
+system (@pxref{Styles}) will have set this up for you, so you probably
+won't have to bother.
+
+Sometimes @ccmode{} inserts an auto-newline where you don't want one,
+such as after a @samp{@}} when you're about to type a @samp{;}.
+Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can
+activate an appropriate @dfn{clean-up}, which will remove the excess
+whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a
+full description. See also @ref{Electric Keys} for a summary of
+clean-ups listed by key.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands
+@comment node-name, next, previous, up
+@section Hungry Deletion of Whitespace
+@cindex hungry-deletion
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+If you want to delete an entire block of whitespace at point, you can
+use @dfn{hungry deletion}. This deletes all the contiguous whitespace
+either before point or after point in a single operation.
+``Whitespace'' here includes tabs and newlines, but not comments or
+preprocessor commands. Hungry deletion can markedly cut down on the
+number of times you have to hit deletion keys when, for example,
+you've made a mistake on the preceding line and have already pressed
+@kbd{C-j}.
+
+Hungry deletion is a simple feature that some people find extremely
+useful. In fact, you might find yourself wanting it in @strong{all}
+your editing modes!
+
+Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the
+backspace key'' and @dfn{@key{DELETE}} means ``the forward delete
+key''. This is discussed in more detail below.
+
+There are two different ways you can use hungry deletion:
+
+@table @asis
+@item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d}
+Here you toggle Hungry Delete minor mode with @kbd{M-x
+c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command
+was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding
+for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This
+makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry
+deletion.
+
+@table @asis
+@item @kbd{@key{DEL}} (@code{c-electric-backspace})
+@kindex DEL
+@findex c-electric-backspace
+@findex electric-backspace (c-)
+This command is run by default when you hit the @kbd{DEL} key. When
+hungry delete mode is enabled, it deletes any amount of whitespace in
+the backwards direction. Otherwise, or when used with a prefix
+argument or in a literal (@pxref{Auto-newlines}), the command just
+deletes backwards in the usual way. (More precisely, it calls the
+function contained in the variable @code{c-backspace-function},
+passing it the prefix argument, if any.)
+
+@item @code{c-backspace-function}
+@vindex c-backspace-function
+@vindex backspace-function (c-)
+@findex backward-delete-char-untabify
+Hook that gets called by @code{c-electric-backspace} when it doesn't
+do an ``electric'' deletion of the preceding whitespace. The default
+value is @code{backward-delete-char-untabify}
+(@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which
+deletes a single character.
+
+@item @kbd{C-d} (@code{c-electric-delete-forward})
+@kindex C-d
+@findex c-electric-delete-forward
+@findex electric-delete-forward (c-)
+This function, which is bound to @kbd{C-d} by default, works just like
+@code{c-electric-backspace} but in the forward direction. When it
+doesn't do an ``electric'' deletion of the following whitespace, it
+just does @code{delete-char}, more or less. (Strictly speaking, it
+calls the function in @code{c-delete-function} with the prefix
+argument.)
+
+@item @code{c-delete-function}
+@vindex c-delete-function
+@vindex delete-function (c-)
+@findex delete-char
+Hook that gets called by @code{c-electric-delete-forward} when it
+doesn't do an ``electric'' deletion of the following whitespace. The
+default value is @code{delete-char}.
+@end table
+
+@item Using Distinct Bindings
+The other (newer and recommended) way to use hungry deletion is to
+perform @code{c-hungry-delete-backwards} and
+@code{c-hungry-delete-forward} directly through their key sequences
+rather than using the minor mode toggling.
+
+@table @asis
+@item @kbd{C-c C-@key{DEL}}, or @kbd{C-c @key{DEL}} (@code{c-hungry-delete-backwards})@footnote{This command was formerly known as @code{c-hungry-backspace}.}
+@kindex C-c C-<backspace>
+@kindex C-c <backspace>
+@kindex C-c C-DEL
+@kindex C-c DEL
+@findex c-hungry-delete-backwards
+@findex hungry-delete-backwards (c-)
+Delete any amount of whitespace in the backwards direction (regardless
+whether hungry-delete mode is enabled or not). This command is bound
+to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more
+natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at
+a character terminal.
+
+@item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward})
+@kindex C-c C-d
+@kindex C-c C-<DELETE>
+@kindex C-c <DELETE>
+@findex c-hungry-delete-forward
+@findex hungry-delete-forward (c-)
+Delete any amount of whitespace in the forward direction (regardless
+whether hungry-delete mode is enabled or not). This command is bound
+to both @kbd{C-c C-@key{DELETE}} and @kbd{C-c @key{DELETE}} for the
+same reason as for @key{DEL} above.
+@end table
+@end table
+
+@kindex <delete>
+@kindex <backspace>
+
+When we talk about @kbd{@key{DEL}}, and @kbd{@key{DELETE}} above, we
+actually do so without connecting them to the physical keys commonly
+known as @key{Backspace} and @key{Delete}. The default bindings to
+those two keys depends on the flavor of (X)Emacs you are using.
+
+@findex c-electric-delete
+@findex electric-delete (c-)
+@findex c-hungry-delete
+@findex hungry-delete (c-)
+@vindex delete-key-deletes-forward
+In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to
+@code{c-electric-backspace} and the @key{Delete} key is bound to
+@code{c-electric-delete}. You control the direction it deletes in by
+setting the variable @code{delete-key-deletes-forward}, a standard
+XEmacs variable.
+@c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...).
+When this variable is non-@code{nil}, @code{c-electric-delete} will do
+forward deletion with @code{c-electric-delete-forward}, otherwise it
+does backward deletion with @code{c-electric-backspace}. Similarly,
+@kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to
+@code{c-hungry-delete} which is controlled in the same way by
+@code{delete-key-deletes-forward}.
+
+@findex normal-erase-is-backspace-mode
+
+Emacs 21 and later automatically binds @key{Backspace} and
+@key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment,
+and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}}
+etc. If you need to change the bindings through
+@code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt
+its extended bindings accordingly.
+
+In earlier (X)Emacs versions, @ccmode{} doesn't bind either
+@key{Backspace} or @key{Delete} directly. Only the key codes
+@kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings
+to map the physical keys to them. You might need to modify this
+yourself if the defaults are unsuitable.
+
+Getting your @key{Backspace} and @key{Delete} keys properly set up can
+sometimes be tricky. The information in @ref{DEL Does Not
+Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having
+trouble with this in GNU Emacs.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Subword Movement, Other Commands, Hungry WS Deletion, Commands
+@comment node-name, next, previous, up
+@section Subword Movement and Editing
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex nomenclature
+@cindex subword
+In spite of the GNU Coding Standards, it is popular to name a symbol
+by mixing uppercase and lowercase letters, e.g. @samp{GtkWidget},
+@samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call
+these mixed case symbols @dfn{nomenclatures}. Also, each capitalized
+(or completely uppercase) part of a nomenclature is called a
+@dfn{subword}. Here are some examples:
+
+@multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}}
+@c This could be converted to @headitem when we require Texinfo 4.7
+@iftex
+@item @b{Nomenclature}
+ @tab @b{Subwords}
+@end iftex
+@ifnottex
+@item Nomenclature
+ @tab Subwords
+@item ---------------------------------------------------------
+@end ifnottex
+@item @samp{GtkWindow}
+ @tab @samp{Gtk} and @samp{Window}
+@item @samp{EmacsFrameClass}
+ @tab @samp{Emacs}, @samp{Frame}, and @samp{Class}
+@item @samp{NSGraphicsContext}
+ @tab @samp{NS}, @samp{Graphics}, and @samp{Context}
+@end multitable
+
+The subword minor mode replaces the basic word oriented movement and
+editing commands with variants that recognize subwords in a
+nomenclature and treat them as separate words:
+
+@findex c-forward-subword
+@findex forward-subword (c-)
+@findex c-backward-subword
+@findex backward-subword (c-)
+@findex c-mark-subword
+@findex mark-subword (c-)
+@findex c-kill-subword
+@findex kill-subword (c-)
+@findex c-backward-kill-subword
+@findex backward-kill-subword (c-)
+@findex c-transpose-subwords
+@findex transpose-subwords (c-)
+@findex c-capitalize-subword
+@findex capitalize-subword (c-)
+@findex c-upcase-subword
+@findex upcase-subword (c-)
+@findex c-downcase-subword
+@findex downcase-subword (c-)
+@multitable @columnfractions .20 .40 .40
+@c This could be converted to @headitem when we require Texinfo 4.7
+@iftex
+@item @b{Key} @tab @b{Word oriented command} @tab @b{Subword oriented command}
+@end iftex
+@ifnottex
+@item Key @tab Word oriented command @tab Subword oriented command
+@item ----------------------------------------------------------------------------
+@end ifnottex
+@item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword}
+@item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword}
+@item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword}
+@item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword}
+@item @kbd{M-DEL} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword}
+@item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords}
+@item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword}
+@item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword}
+@item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword}
+@end multitable
+
+Note that if you have changed the key bindings for the word oriented
+commands in your @file{.emacs} or a similar place, the keys you have
+configured are also used for the corresponding subword oriented
+commands.
+
+Type @kbd{C-c C-w} to toggle subword mode on and off. To make the
+mode turn on automatically, put the following code in your
+@file{.emacs}:
+
+@example
+(add-hook 'c-mode-common-hook
+ (lambda () (c-subword-mode 1)))
+@end example
+
+As a bonus, you can also use @code{c-subword-mode} in non-@ccmode{}
+buffers by typing @kbd{M-x c-subword-mode}.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Other Commands, , Subword Movement, Commands
+@comment node-name, next, previous, up
+@section Other Commands
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Here are the various other commands that didn't fit anywhere else:
+
+@table @asis
+@item @kbd{C-c .} (@code{c-set-style})
+@kindex C-c .
+@findex c-set-style
+@findex set-style (c-)
+Switch to the specified style in the current buffer. Use like this:
+
+@example
+@kbd{C-c . @var{style-name} @key{RET}}
+@end example
+
+You can use the @key{TAB} in the normal way to do completion on the
+style name. Note that all style names are case insensitive, even the
+ones you define yourself.
+
+Setting a style in this way does @emph{not} automatically reindent your
+file. For commands that you can use to view the effect of your changes,
+see @ref{Indentation Commands} and @ref{Filling and Breaking}.
+
+For details of the @ccmode{} style system, see @ref{Styles}.
+@item @kbd{C-c :} (@code{c-scope-operator})
+@kindex C-c :
+@findex c-scope-operator
+@findex scope-operator (c-)
+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.
+
+@item @kbd{C-c C-\} (@code{c-backslash-region})
+@kindex C-c C-\
+@findex c-backslash-region
+@findex backslash-region (c-)
+This function inserts and aligns or deletes end-of-line backslashes in
+the current region. These are typically used in multi-line macros.
+
+With no prefix argument, it inserts any missing backslashes and aligns
+them according to the @code{c-backslash-column} and
+@code{c-backslash-max-column} variables. With a prefix argument, it
+deletes any backslashes.
+
+The function does not modify blank lines at the start of the region. If
+the region ends at the start of a line, it always deletes the backslash
+(if any) at the end of the previous line.
+
+To customize the precise workings of this command, @ref{Custom Macros}.
+@end table
+
+@noindent
+The recommended line breaking function, @code{c-context-line-break}
+(@pxref{Filling and Breaking}), is especially nice if you edit
+multiline macros frequently. When used inside a macro, it
+automatically inserts and adjusts the mandatory backslash at the end
+of the line to keep the macro together, and it leaves the point at the
+right indentation column for the code. Thus you can write code inside
+macros almost exactly as you can elsewhere, without having to bother
+with the trailing backslashes.
+
+@table @asis
+@item @kbd{C-c C-e} (@code{c-macro-expand})
+@kindex C-c C-e
+@findex c-macro-expand
+@findex macro-expand (c-)
+This command expands C, C++, Objective C or Pike macros in the region,
+using an appropriate external preprocessor program. Normally it
+displays its output in a temporary buffer, but if you give it a prefix
+arg (with @kbd{C-u C-c C-e}) it will overwrite the original region
+with the expansion.
+
+The command does not work in any of the other modes, and the key
+sequence is not bound in these other modes.
+
+@code{c-macro-expand} isn't actually part of @ccmode{}, even though it
+is bound to a @ccmode{} key sequence. If you need help setting it up
+or have other problems with it, you can either read its source code or
+ask for help in the standard (X)Emacs forums.
+@end table
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Font Locking, Config Basics, Commands, Top
+@comment node-name, next, previous, up
+@chapter Font Locking
+@cindex font locking
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex Font Lock mode
+
+@ccmode{} provides font locking for its supported languages by
+supplying patterns for use with Font Lock mode. This means that you
+get distinct faces on the various syntactic parts such as comments,
+strings, keywords and types, which is very helpful in telling them
+apart at a glance and discovering syntactic errors. @xref{Font
+Lock,,, emacs, GNU Emacs Manual}, for ways to enable font locking in
+@ccmode{} buffers.
+
+@strong{Please note:} The font locking in AWK mode is currently not
+integrated with the rest of @ccmode{}. Only the last section of this
+chapter, @ref{AWK Mode Font Locking}, applies to AWK. The other
+sections apply to the other languages.
+
+@menu
+* Font Locking Preliminaries::
+* Faces::
+* Doc Comments::
+* AWK Mode Font Locking::
+@end menu
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Font Locking Preliminaries, Faces, Font Locking, Font Locking
+@comment node-name, next, previous, up
+@section Font Locking Preliminaries
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The font locking for most of the @ccmode{} languages were provided
+directly by the Font Lock package prior to version 5.30 of @ccmode{}.
+In the transition to @ccmode{} the patterns have been reworked
+completely and are applied uniformly across all the languages except AWK
+mode, just like the indentation rules (although each language still has
+some peculiarities of its own, of course). Since the languages
+previously had completely separate font locking patterns, this means
+that it's a bit different in most languages now.
+
+The main goal for the font locking in @ccmode{} is accuracy, to provide
+a dependable aid in recognizing the various constructs. Some, like
+strings and comments, are easy to recognize while others, like
+declarations and types, can be very tricky. @ccmode{} can go to great
+lengths to recognize declarations and casts correctly, especially when
+the types aren't recognized by standard patterns. This is a fairly
+demanding analysis which can be slow on older hardware, and it can
+therefore be disabled by choosing a lower decoration level with the
+variable @code{font-lock-maximum-decoration} (@pxref{Font Lock,,,
+emacs, GNU Emacs Manual}).
+
+@vindex font-lock-maximum-decoration
+
+The decoration levels are used as follows:
+
+@enumerate
+@comment 1
+@item
+Minimal font locking: Fontify only comments, strings and preprocessor
+directives (in the languages that use cpp).
+
+@comment 2
+@item
+Fast font locking: In addition to level 1, fontify keywords, simple
+types and declarations that are easy to recognize. The variables
+@code{*-font-lock-extra-types} (where @samp{*} is the name of the
+language) are used to recognize types (see below). Documentation
+comments like Javadoc are fontified according to
+@code{c-doc-comment-style} (@pxref{Doc Comments}).
+
+Use this if you think the font locking is too slow. It's the closest
+corresponding level to level 3 in the old font lock patterns.
+
+@comment 3
+@item
+Accurate font locking: Like level 2 but uses a different approach that
+can recognize types and declarations much more accurately. The
+@code{*-font-lock-extra-types} variables are still used, but user
+defined types are recognized correctly anyway in most cases. Therefore
+those variables should be fairly restrictive and not contain patterns
+that are uncertain.
+
+@cindex Lazy Lock mode
+@cindex Just-in-time Lock mode
+
+This level is designed for fairly modern hardware and a font lock
+support mode like Lazy Lock or Just-in-time Lock mode that only
+fontifies the parts that are actually shown. Fontifying the whole
+buffer at once can easily get bothersomely slow even on contemporary
+hardware. @xref{Font Lock,,,@emacsman{}, @emacsmantitle{}}.
+@end enumerate
+
+@cindex user defined types
+@cindex types, user defined
+
+Since user defined types are hard to recognize you can provide
+additional regexps to match those you use:
+
+@defopt c-font-lock-extra-types
+@defoptx c++-font-lock-extra-types
+@defoptx objc-font-lock-extra-types
+@defoptx java-font-lock-extra-types
+@defoptx idl-font-lock-extra-types
+@defoptx pike-font-lock-extra-types
+For each language there's a variable @code{*-font-lock-extra-types},
+where @samp{*} stands for the language in question. It contains a list
+of regexps that matches identifiers that should be recognized as types,
+e.g. @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t}
+as is customary in C code. Each regexp should not match more than a
+single identifier.
+
+The default values contain regexps for many types in standard runtime
+libraries that are otherwise difficult to recognize, and patterns for
+standard type naming conventions like the @samp{_t} suffix in C and C++.
+Java, Objective-C and Pike have as a convention to start class names
+with capitals, so there are patterns for that in those languages.
+
+Despite the names of these variables, they are not only used for
+fontification but in other places as well where @ccmode{} needs to
+recognize types.
+@end defopt
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Faces, Doc Comments, Font Locking Preliminaries, Font Locking
+@comment node-name, next, previous, up
+@section Faces
+@cindex faces
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ccmode{} attempts to use the standard faces for programming languages
+in accordance with their intended purposes as far as possible. No extra
+faces are currently provided, with the exception of a replacement face
+@code{c-invalid-face} for emacsen that don't provide
+@code{font-lock-warning-face}.
+
+@itemize @bullet
+@item
+@vindex font-lock-comment-face
+Normal comments are fontified in @code{font-lock-comment-face}.
+
+@item
+@vindex font-lock-doc-face
+@vindex font-lock-doc-string-face
+@vindex font-lock-comment-face
+Comments that are recognized as documentation (@pxref{Doc Comments})
+get @code{font-lock-doc-face} (Emacs) or
+@code{font-lock-doc-string-face} (XEmacs) if those faces exist. If
+they don't then @code{font-lock-comment-face} is used.
+
+@item
+@vindex font-lock-string-face
+String and character literals are fontified in
+@code{font-lock-string-face}.
+
+@item
+@vindex font-lock-keyword-face
+Keywords are fontified with @code{font-lock-keyword-face}.
+
+@item
+@vindex font-lock-function-name-face
+@code{font-lock-function-name-face} is used for function names in
+declarations and definitions, and classes in those contexts. It's also
+used for preprocessor defines with arguments.
+
+@item
+@vindex font-lock-variable-name-face
+Variables in declarations and definitions, and other identifiers in such
+variable contexts, get @code{font-lock-variable-name-face}. It's also
+used for preprocessor defines without arguments.
+
+@item
+@vindex font-lock-constant-face
+@vindex font-lock-reference-face
+Builtin constants are fontified in @code{font-lock-constant-face} if it
+exists, @code{font-lock-reference-face} otherwise. As opposed to the
+preceding two faces, this is used on the names in expressions, and it's
+not used in declarations, even if there happen to be a @samp{const} in
+them somewhere.
+
+@item
+@vindex font-lock-type-face
+@code{font-lock-type-face} is put on types (both predefined and user
+defined) and classes in type contexts.
+
+@item
+@vindex font-lock-constant-face
+@vindex font-lock-reference-face
+Label identifiers get @code{font-lock-constant-face} if it exists,
+@code{font-lock-reference-face} otherwise.
+
+@item
+Name qualifiers and identifiers for scope constructs are fontified like
+labels.
+
+@item
+Special markup inside documentation comments are also fontified like
+labels.
+
+@item
+@vindex font-lock-preprocessor-face
+@vindex font-lock-builtin-face
+@vindex font-lock-reference-face
+Preprocessor directives get @code{font-lock-preprocessor-face} if it
+exists (i.e. XEmacs). In Emacs they get @code{font-lock-builtin-face}
+or @code{font-lock-reference-face}, for lack of a closer equivalent.
+
+@item
+@vindex font-lock-warning-face
+@vindex c-invalid-face
+@vindex invalid-face (c-)
+Some kinds of syntactic errors are fontified with
+@code{font-lock-warning-face} in Emacs. In older XEmacs versions
+there's no corresponding standard face, so there a special
+@code{c-invalid-face} is used, which is defined to stand out sharply by
+default.
+
+Note that it's not used for @samp{#error} or @samp{#warning} directives,
+since those aren't syntactic errors in themselves.
+@end itemize
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Doc Comments, AWK Mode Font Locking, Faces, Font Locking
+@comment node-name, next, previous, up
+@section Documentation Comments
+@cindex documentation comments
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+There are various tools to supply documentation in the source as
+specially structured comments, e.g. the standard Javadoc tool in Java.
+@ccmode{} provides an extensible mechanism to fontify such comments and
+the special markup inside them.
+
+@defopt c-doc-comment-style
+@vindex doc-comment-style (c-)
+This is a style variable that specifies which documentation comment
+style to recognize, e.g. @code{javadoc} for Javadoc comments.
+
+The value may also be a list of styles, in which case all of them are
+recognized simultaneously (presumably with markup cues that don't
+conflict).
+
+The value may also be an association list to specify different comment
+styles for different languages. The symbol for the major mode is then
+looked up in the alist, and the value of that element is interpreted as
+above if found. If it isn't found then the symbol `other' is looked up
+and its value is used instead.
+
+The default value for @code{c-doc-comment-style} is
+@w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}.
+
+Note that @ccmode{} uses this variable to set other variables that
+handle fontification etc. That's done at mode initialization or when
+you switch to a style which sets this variable. Thus, if you change it
+in some other way, e.g. interactively in a CC Mode buffer, you will need
+to do @kbd{M-x java-mode} (or whatever mode you're currently using) to
+reinitialize.
+
+@findex c-setup-doc-comment-style
+@findex setup-doc-comment-style (c-)
+Note also that when @ccmode{} starts up, the other variables are
+modified before the mode hooks are run. If you change this variable in
+a mode hook, you'll have to call @code{c-setup-doc-comment-style}
+afterwards to redo that work.
+@end defopt
+
+@ccmode{} currently provides handing of the following doc comment
+styles:
+
+@table @code
+@item javadoc
+@cindex Javadoc markup
+Javadoc comments, the standard tool in Java.
+
+@item autodoc
+@cindex Pike autodoc markup
+For Pike autodoc markup, the standard in Pike.
+
+@item gtkdoc
+@cindex GtkDoc markup
+For GtkDoc markup, widely used in the Gnome community.
+@end table
+
+The above is by no means complete. If you'd like to see support for
+other doc comment styles, please let us know (@pxref{Mailing Lists and
+Bug Reports}).
+
+You can also write your own doc comment fontification support to use
+with @code{c-doc-comment-style}: Supply a variable or function
+@code{*-font-lock-keywords} where @samp{*} is the name you want to use
+in @code{c-doc-comment-style}. If it's a variable, it's prepended to
+@code{font-lock-keywords}. If it's a function, it's called at mode
+initialization and the result is prepended. For an example, see
+@code{javadoc-font-lock-keywords} in @file{cc-fonts.el}.
+
+If you add support for another doc comment style, please consider
+contributing it - send a note to @email{bug-cc-mode@@gnu.org}.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node AWK Mode Font Locking, , Doc Comments, Font Locking
+@comment node-name, next, previous, up
+@section AWK Mode Font Locking
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The general appearance of font-locking in AWK mode is much like in any
+other programming mode. @xref{Faces For Font Lock,,,elisp, GNU Emacs
+Lisp Reference Manual}.
+
+The following faces are, however, used in a non-standard fashion in
+AWK mode:
+
+@table @asis
+@item @code{font-lock-variable-name-face}
+This face was intended for variable declarations. Since variables are
+not declared in AWK, this face is used instead for AWK system
+variables (such as @code{NF}) and ``Special File Names'' (such as
+@code{"/dev/stderr"}).
+
+@item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs)
+This face is normally used for preprocessor directives in @ccmode{}.
+There are no such things in AWK, so this face is used instead for
+standard functions (such as @code{match}).
+
+@item @code{font-lock-string-face}
+As well as being used for strings, including localizable strings,
+(delimited by @samp{"} and @samp{_"}), this face is also used for AWK
+regular expressions (delimited by @samp{/}).
+
+@item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs)
+This face highlights the following syntactically invalid AWK
+constructs:
+
+@itemize @bullet
+@item
+An unterminated string or regular expression. Here the opening
+delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in
+@code{font-lock-warning-face}. This is most noticeable when typing in a
+new string/regular expression into a buffer, when the warning-face
+serves as a continual reminder to terminate the construct.
+
+AWK mode fontifies unterminated strings/regular expressions
+differently from other modes: Only the text up to the end of the line
+is fontified as a string (escaped newlines being handled correctly),
+rather than the text up to the next string quote.
+
+@item
+A space between the function name and opening parenthesis when calling
+a user function. The last character of the function name and the
+opening parenthesis are highlighted. This font-locking rule will
+spuriously highlight a valid concatenation expression where an
+identifier precedes a parenthesised expression. Unfortunately.
+
+@item
+Whitespace following the @samp{\} in what otherwise looks like an
+escaped newline. The @samp{\} is highlighted.
+@end itemize
+@end table
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Config Basics, Custom Filling and Breaking, Font Locking, Top
+@comment node-name, next, previous, up
+@chapter Configuration Basics
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex Emacs Initialization File
+@cindex Configuration
+You configure @ccmode{} by setting Lisp variables and calling (and
+perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't
+difficult.}, which is usually done by adding code to an Emacs
+initialization file. This file might be @file{site-start.el} or
+@file{.emacs} or @file{init.el} or @file{default.el} or perhaps some
+other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For
+the sake of conciseness, we just call this file ``your @file{.emacs}''
+throughout the rest of the manual.
+
+Several of these variables (currently 16), are known collectively as
+@dfn{style variables}. @ccmode{} provides a special mechanism, known
+as @dfn{styles} to make it easier to set these variables as a group,
+to ``inherit'' settings from one style into another, and so on. Style
+variables remain ordinary Lisp variables, whose values can be read and
+changed independently of the style system. @xref{Style Variables}.
+
+There are several ways you can write the code, depending on the
+precise effect you want---they are described further down on this page.
+If you are new to @ccmode{}, we suggest you begin with the simplest
+method, ``Top-level commands or the customization interface''.
+
+If you make conflicting settings in several of these ways, the way
+that takes precedence is the one that appears latest in this list:
+@itemize @asis
+@item
+@table @asis
+@item Style
+@itemx Top-level command or ``customization interface''
+@itemx Hook
+@itemx File Style
+@end table
+@end itemize
+
+Here is a summary of the different ways of writing your configuration
+settings:
+
+@table @asis
+@item Top-level commands or the ``customization interface''
+Most simply, you can write @code{setq} and similar commands at the top
+level of your @file{.emacs} file. When you load a @ccmode{} buffer,
+it initializes its configuration from these global values (at least,
+for those settings you have given values to), so it makes sense to
+have these @code{setq} commands run @emph{before} @ccmode{} is first
+initialized---in particular, before any call to @code{desktop-read}
+(@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For
+example, you might set c-basic-offset thus:
+
+@example
+(setq c-basic-offset 4)
+@end example
+
+You can use the more user friendly Customization interface instead,
+but this manual does not cover in detail how that works. To do this,
+start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}.
+@xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}.
+@c The following note really belongs in the Emacs manual.
+Emacs normally writes the customizations at the end of your
+@file{.emacs} file. If you use @code{desktop-read}, you should edit
+your @file{.emacs} to place the call to @code{desktop-read} @emph{after}
+the customizations.
+
+The first initialization of @ccmode{} puts a snapshot of the
+configuration settings into the special style @code{user}.
+@xref{Built-in Styles}.
+
+For basic use of Emacs, either of these ways of configuring is
+adequate. However, the settings are then the same in all @ccmode{}
+buffers and it can be clumsy to communicate them between programmers.
+For more flexibility, you'll want to use one (or both) of @ccmode{}'s
+more sophisticated facilities, hooks and styles.
+
+@item Hooks
+An Emacs @dfn{hook} is a place to put Lisp functions that you want
+Emacs to execute later in specific circumstances.
+@xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main
+hook and a language-specific hook for each language it supports - any
+functions you put onto these hooks get executed as the last part of a
+buffer's initialization. Typically you put most of your customization
+within the main hook, and use the language-specific hooks to vary the
+customization settings between language modes. For example, if you
+wanted different (non-standard) values of @code{c-basic-offset} in C
+Mode and Java Mode buffers, you could do it like this:
+
+@example
+@group
+(defun my-c-mode-hook ()
+ (setq c-basic-offset 3))
+(add-hook 'c-mode-hook 'my-c-mode-hook)
+
+(defun my-java-mode-hook ()
+ (setq c-basic-offset 6))
+(add-hook 'java-mode-hook 'my-java-mode-hook)
+@end group
+@end example
+
+See @ref{CC Hooks} for more details on the use of @ccmode{} hooks.
+
+@item Styles
+A @ccmode{} @dfn{style} is a coherent collection of customizations
+with a name. At any time, exactly one style is active in each
+@ccmode{} buffer, either the one you have selected or a default.
+@ccmode{} is delivered with several existing styles. Additionally,
+you can create your own styles, possibly based on these existing
+styles. If you worked in a programming team called the ``Free
+Group'', which had its own coding standards, you might well have this
+in your @file{.emacs} file:
+
+@example
+(setq c-default-style '((java-mode . "java")
+ (awk-mode . "awk")
+ (other . "free-group-style")))
+@end example
+
+See @ref{Styles} for fuller details on using @ccmode{} styles and how
+to create them.
+
+@item File Styles
+A @dfn{file style} is a rarely used variant of the ``style'' mechanism
+described above, which applies to an individual source file. To use
+it, you set certain Emacs local variables in a special block at the
+end of the source file. @xref{File Styles}.
+
+@item Hooks with Styles
+For ultimate flexibility, you can use hooks and styles together. For
+example, if your team were developing a product which required a
+Linux driver, you'd probably want to use the ``linux'' style for the
+driver, and your own team's style for the rest of the code. You
+could achieve this with code like this in your @file{.emacs}:
+
+@example
+@group
+(defun my-c-mode-hook ()
+ (c-set-style
+ (if (and (buffer-file-name)
+ (string-match "/usr/src/linux" (buffer-file-name)))
+ "linux"
+ "free-group-style")))
+(add-hook 'c-mode-hook 'my-c-mode-hook)
+@end group
+@end example
+
+In a programming team, a hook is a also a good place for each member
+to put his own personal preferences. For example, you might be the
+only person in your team who likes Auto-newline minor mode. You could
+have it enabled by default by placing the following in your
+@file{.emacs}:
+
+@example
+@group
+(defun my-turn-on-auto-newline ()
+ (c-toggle-auto-newline 1))
+(add-hook 'c-mode-common-hook 'my-turn-on-auto-newline)
+@end group
+@end example
+@end table
+
+@menu
+* CC Hooks::
+* Style Variables::
+* Styles::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node CC Hooks, Style Variables, Config Basics, Config Basics
+@comment node-name, next, previous, up
+@section Hooks
+@cindex mode hooks
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@c The node name is "CC Hooks" rather than "Hooks" because of a bug in
+@c some older versions of Info, e.g. the info.el in GNU Emacs 21.3.
+@c If you go to "Config Basics" and hit <CR> on the xref to "CC
+@c Hooks" the function Info-follow-reference searches for "*Note: CC
+@c Hooks" from the beginning of the page. If this node were instead
+@c named "Hooks", that search would spuriously find "*Note:
+@c Hooks(elisp)" and go to the wrong node.
+
+@ccmode{} provides several hooks that you can use to customize the
+mode for your coding style. The main hook is
+@code{c-mode-common-hook}; typically, you'll put the bulk of your
+customizations here. In addition, each language mode has its own
+hook, allowing you to fine tune your settings individually for the
+different @ccmode{} languages, and there is a package initialization
+hook. Finally, there is @code{c-special-indent-hook}, which enables
+you to solve anomalous indentation problems. It is described in
+@ref{Other Indentation}, not here. All these hooks adhere to the
+standard Emacs conventions.
+
+When you open a buffer, @ccmode{} first initializes it with the
+currently active style (@pxref{Styles}). Then it calls
+@code{c-mode-common-hook}, and finally it calls the language-specific
+hook. Thus, any style settings done in these hooks will override
+those set by @code{c-default-style}.
+
+@defvar c-initialization-hook
+@vindex initialization-hook (c-)
+Hook run only once per Emacs session, when @ccmode{} is initialized.
+This is a good place to change key bindings (or add new ones) in any
+of the @ccmode{} key maps. @xref{Sample .emacs File}.
+@end defvar
+
+@defvar c-mode-common-hook
+@vindex mode-common-hook (c-)
+Common hook across all languages. It's run immediately before the
+language specific hook.
+@end defvar
+
+@defvar c-mode-hook
+@defvarx c++-mode-hook
+@defvarx objc-mode-hook
+@defvarx java-mode-hook
+@defvarx idl-mode-hook
+@defvarx pike-mode-hook
+@defvarx awk-mode-hook
+The language specific mode hooks. The appropriate one is run as the
+last thing when you enter that language mode.
+@end defvar
+
+Although these hooks are variables defined in @ccmode{}, you can give
+them values before @ccmode{}'s code is loaded---indeed, this is the
+only way to use @code{c-initialization-hook}. Their values aren't
+overwritten when @ccmode{} gets loaded.
+
+Here's a simplified example of what you can add to your @file{.emacs}
+file to do things whenever any @ccmode{} language is edited. 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
+(defun my-c-mode-common-hook ()
+ ;; my customizations for all of c-mode and related modes
+ (no-case-fold-search)
+ )
+(add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
+@end example
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Style Variables, Styles, CC Hooks, Config Basics
+@comment node-name, next, previous, up
+@section Style Variables
+@cindex styles
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex style variables
+The variables that @ccmode{}'s style system control are called
+@dfn{style variables}. Note that style variables are ordinary Lisp
+variables, which the style system initializes; you can change their
+values at any time (e.g. in a hook function). The style system can
+also set other variables, to some extent. @xref{Styles}.
+
+@dfn{Style variables} are handled specially in several ways:
+
+@itemize @bullet
+@item
+Style variables are by default buffer-local variables. However, they
+can instead be made global by setting
+@code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is
+initialized.
+
+@item
+@vindex c-old-style-variable-behavior
+@vindex old-style-variable-behavior (c-)
+The default global binding of any style variable (with two exceptions
+- see below) is the special symbol @code{set-from-style}. When the
+style system initializes a buffer-local copy of a style variable for a
+@ccmode{} buffer, if its global binding is still that symbol then it
+will be set from the current style. Otherwise it will retain its
+global default@footnote{This is a big change from versions of
+@ccmode{} earlier than 5.26, where such settings would get overridden
+by the style system unless special precautions were taken. That was
+changed since it was counterintuitive and confusing, especially to
+novice users. If your configuration depends on the old overriding
+behavior, you can set the variable
+@code{c-old-style-variable-behavior} to non-@code{nil}.}. This
+``otherwise'' happens, for example, when you've set the variable with
+@code{setq} at the top level of your @file{.emacs} (@pxref{Config
+Basics}).
+
+@item
+The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is
+an association list with an element for each syntactic symbol. It's
+handled a little differently from the other style variables. It's
+default global binding is the empty list @code{nil}, rather than
+@code{set-from-style}. Before the style system is initialized, you
+can add individual elements to @code{c-offsets-alist} by calling
+@code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set
+other style variables with @code{setq}. Those elements will then
+prevail when the style system later initializes a buffer-local copy of
+@code{c-offsets-alist}.
+
+@item
+The style variable @code{c-special-indent-hook} is also handled in a
+special way. Styles can only add functions to this hook, not remove
+them, so any global settings you put on it are always
+preserved@footnote{This did not change in version 5.26.}. The value
+you give this variable in a style definition can be either a function
+or a list of functions.
+
+@item
+The global bindings of the style variables get captured in the special
+@code{user} style when the style system is first initialized.
+@xref{Built-in Styles}, for details.
+@end itemize
+
+The style variables are:@*
+@code{c-indent-comment-alist},
+@code{c-indent-comments-syntactically-p} (@pxref{Indentation
+Commands});@*
+@code{c-doc-comment-style} (@pxref{Doc Comments});@*
+@code{c-block-comment-prefix}, @code{c-comment-prefix-regexp}
+(@pxref{Custom Filling and Breaking});@*
+@code{c-hanging-braces-alist} (@pxref{Hanging Braces});@*
+@code{c-hanging-colons-alist} (@pxref{Hanging Colons});@*
+@code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and
+Commas});@*
+@code{c-cleanup-list} (@pxref{Clean-ups});@*
+@code{c-basic-offset} (@pxref{Customizing Indentation});@*
+@code{c-offsets-alist} (@pxref{c-offsets-alist});@*
+@code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@*
+@code{c-special-indent-hook}, @code{c-label-minimum-indentation}
+(@pxref{Other Indentation});@*
+@code{c-backslash-column}, @code{c-backslash-max-column}
+(@pxref{Custom Macros}).
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Styles, , Style Variables, Config Basics
+@comment node-name, next, previous, up
+@section Styles
+@cindex styles
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+By @dfn{style} we mean the layout of the code---things like how many
+columns to indent a block of code, whether an opening brace gets
+indented to the level of the code it encloses, or of the construct
+that introduces it, or ``hangs'' at the end of a line.
+
+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.
+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::
+* Choosing a Style::
+* Adding Styles::
+* File Styles::
+@end menu
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Built-in Styles, Choosing a Style, Styles, Styles
+@comment node-name, next, previous, up
+@subsection Built-in Styles
+@cindex styles, built-in
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+If you're lucky, one of @ccmode{}'s built-in styles might be just
+what you're looking for. These are:
+
+@table @code
+@item gnu
+@cindex GNU style
+Coding style blessed by the Free Software Foundation
+for C code in GNU programs.
+
+@item k&r
+@cindex K&R style
+The classic Kernighan and Ritchie style for C code.
+
+@item bsd
+@cindex BSD style
+Also known as ``Allman style'' after Eric Allman.
+
+@item whitesmith
+@cindex Whitesmith style
+Popularized by the examples that came with Whitesmiths C, an early
+commercial C compiler.
+
+@item stroustrup
+@cindex Stroustrup style
+The classic Stroustrup style for C++ code.
+
+@item ellemtel
+@cindex Ellemtel style
+Popular C++ coding standards as defined by ``Programming in C++, Rules
+and Recommendations,'' Erik Nyquist and Mats Henricson,
+Ellemtel@footnote{This document is available at
+@uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other
+places.}.
+@c N.B. This URL was still valid at 2005/8/28 (ACM).
+
+@item linux
+@cindex Linux style
+C coding standard for Linux (the kernel).
+
+@item python
+@cindex Python style
+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 @uref{http://www.python.org/}.}.
+
+@item java
+@cindex Java style
+The style for editing Java code. Note that the default
+value for @code{c-default-style} installs this style when you enter
+@code{java-mode}.
+
+@item awk
+@cindex AWK style
+The style for editing AWK code. Note that the default value for
+@code{c-default-style} installs this style when you enter
+@code{awk-mode}.
+
+@item user
+@cindex User style
+This is a special style created by you. It consists of the factory
+defaults for all the style variables as modified by the customizations
+you do either with the Customization interface or by writing
+@code{setq}s and @code{c-set-offset}s at the top level of your
+@file{.emacs} file (@pxref{Config Basics}). The style system creates
+this style as part of its initialization and doesn't modify it
+afterwards.
+@end table
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Choosing a Style, Adding Styles, Built-in Styles, Styles
+@comment node-name, next, previous, up
+@subsection Choosing a Style
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+When you create a new buffer, its style will be set from
+@code{c-default-style}. The factory default is the style @code{gnu},
+except in Java and AWK modes where it's @code{java} and @code{awk}.
+
+Remember that if you set a style variable with the Customization
+interface or at the top level of your @file{.emacs} file before the
+style system is initialised (@pxref{Config Basics}), this setting will
+override the one that the style system would have given the variable.
+
+To set a buffer's style interactively, use the command @kbd{C-c .}
+(@pxref{Other Commands}). To set it from a file's local variable
+list, @ref{File Styles}.
+
+@defopt c-default-style
+@vindex default-style (c-)
+This variable specifies which style to install by default in new
+buffers. It takes either a style name string, or an association list
+of major mode symbols to style names:
+
+@enumerate
+@item
+When @code{c-default-style} is a string, it must be an existing style
+name. This style is then used for all modes.
+
+@item
+When @code{c-default-style} is an association list, the mode language
+is looked up to find a style name string.
+
+@item
+If @code{c-default-style} is an association list where the mode
+language mode isn't found then the special symbol @samp{other} is
+looked up. If it's found then the associated style is used.
+
+@item
+If @samp{other} is not found then the @samp{gnu} style is used.
+@end enumerate
+
+In all cases, the style described in @code{c-default-style} is installed
+@emph{before} the language hooks are run, so you can always override
+this setting by including an explicit call to @code{c-set-style} in your
+language mode hook, or in @code{c-mode-common-hook}.
+
+The standard value of @code{c-default-style} is @w{@code{((java-mode
+. "java") (awk-mode . "awk") (other . "gnu"))}}.
+@end defopt
+
+@defvar c-indentation-style
+@vindex indentation-style (c-)
+This variable always contains the buffer's current style name, as a
+string.
+@end defvar
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Adding Styles, File Styles, Choosing a Style, Styles
+@comment node-name, next, previous, up
+@subsection Adding and Amending Styles
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+If none of the built-in styles is appropriate, you'll probably want to
+create a new @dfn{style definition}, possibly based on an existing
+style. To do this, put the new style's settings into a list with the
+following format - the list can then be passed as an argument to the
+function @code{c-add-style}. You can see an example of a style
+definition in @ref{Sample .emacs File}.
+
+@cindex style definition
+@c @defvr {List} style definition
+@table @asis
+@item Structure of a Style Definition List
+([@var{base-style}] [(@var{variable} . @var{value}) @dots{}])
+
+Optional @var{base-style}, if present, must be a string which is the
+name of the @dfn{base style} from which this style inherits. At most
+one @var{base-style} is allowed in a style definition. If
+@var{base-style} is not specified, the style inherits from the table
+of factory default values@footnote{This table is stored internally in
+the variable c-fallback-style.} instead. All styles eventually
+inherit from this internal table. Style loops generate errors. The
+list of pre-existing styles can be seen in @ref{Built-in Styles}.
+
+The dotted pairs (@var{variable} . @var{value}) each consist of a
+variable and the value it is to be set to when the style is later
+activated.@footnote{Note that if the variable has been given a value
+by the Customization interface or a @code{setq} at the top level of
+your @file{.emacs}, this value will override the one the style system
+tries to give it. @xref{Config Basics}.} The variable can be either a
+@ccmode{} style variable or an arbitrary Emacs variable. In the
+latter case, it is @emph{not} made buffer-local by the @ccmode{} style
+system.
+@c @end defvr
+
+Two variables are treated specially in the dotted pair list:
+
+@table @code
+@item c-offsets-alist
+The value is in turn a list of dotted pairs of the form
+
+@example
+(@r{@var{syntactic-symbol}} . @r{@var{offset}})
+@end example
+
+as described in @ref{c-offsets-alist}. These are passed to
+@code{c-set-offset} so there is no need to set every syntactic symbol
+in your style, only those that are different from the inherited style.
+
+@item c-special-indent-hook
+The value is added to @code{c-special-indent-hook} using
+@code{add-hook}, so any functions already on it are kept. If the value
+is a list, each element of the list is added with @code{add-hook}.
+@end table
+@end table
+
+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} for this purpose.
+
+@defun c-add-style stylename description &optional set-p
+@findex add-style (c-)
+Add or update a style called @var{stylename}, a string.
+@var{description} is the new style definition in the form described
+above. If @var{stylename} already exists in @code{c-style-alist} then
+it is replaced by @var{description}. (Note, this replacement is
+total. The old style is @emph{not} merged into the new one.)
+Otherwise, a new style is added.
+
+If the optional @var{set-p} is non-@code{nil} then the new style is
+applied to the current buffer as well. The use of this facility is
+deprecated and it might be removed from @ccmode{} in a future release.
+You should use @code{c-set-style} instead.
+
+The sample @file{.emacs} file provides a concrete example of how a new
+style can be added and automatically set. @xref{Sample .emacs File}.
+@end defun
+
+@defvar c-style-alist
+@vindex style-alist (c-)
+This is the variable that holds the definitions for the styles. It
+should not be changed directly; use @code{c-add-style} instead.
+@end defvar
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node File Styles, , Adding Styles, Styles
+@comment node-name, next, previous, up
+@subsection File Styles
+@cindex styles, file local
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex file local variables
+
+The Emacs manual describes how you can customize certain variables on a
+per-file basis by including a @dfn{file local variable} block at the end
+of the file (@pxref{File Variables,, Local Variables in Files, @emacsman{},
+@emacsmantitle{}}).
+
+So far, you've only seen a functional interface for setting styles in
+@ccmode{}, and this can't be used here. @ccmode{} fills the gap by
+providing two variables for use in a file's local variable list.
+Don't use them anywhere else! These allow you to customize the style
+on a per-file basis:
+
+@defvar c-file-style
+@vindex file-style (c-)
+Set this variable to a style name string in the Local Variables list.
+From now on, when you visit the file, @ccmode{} will automatically set
+the file's style to this one using @code{c-set-style}.
+@end defvar
+
+@defvar c-file-offsets
+@vindex file-offsets (c-)
+Set this variable (in the Local Variables list) to an association list
+of the same format as @code{c-offsets-alist}. From now on, when you
+visit the file, @ccmode{} will automatically institute these offsets
+using @code{c-set-offset}.
+@end defvar
+
+Note that file style settings (i.e. @code{c-file-style}) are applied
+before file offset settings
+(i.e. @code{c-file-offsets})@footnote{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, even if
+@code{c-style-variables-are-local-p} is @code{nil}. Since this
+variable is virtually always non-@code{nil} anyhow, you're unlikely to
+notice this effect.}.
+
+If you set any variables, including style variables, by the file local
+variables mechanism, these settings take priority over all other
+settings, even those in your mode hooks (@pxref{CC Hooks}). If you
+use @code{c-file-style} or @code{c-file-offsets} and also explicitly
+set a style variable in a local variable block, the explicit setting
+will take priority.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top
+@comment node-name, next, previous, up
+@chapter Customizing Filling and Line Breaking
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Since there's a lot of normal text in comments and string literals,
+@ccmode{} provides features to edit these like in text mode. It does
+this by hooking in on the different line breaking functions and tuning
+relevant variables as necessary.
+
+@vindex c-comment-prefix-regexp
+@vindex comment-prefix-regexp (c-)
+@cindex comment line prefix
+@vindex comment-start
+@vindex comment-end
+@vindex comment-start-skip
+@vindex paragraph-start
+@vindex paragraph-separate
+@vindex paragraph-ignore-fill-prefix
+@vindex adaptive-fill-mode
+@vindex adaptive-fill-regexp
+@vindex adaptive-fill-first-line-regexp
+To make Emacs recognize comments and treat text in them as normal
+paragraphs, @ccmode{} makes several standard
+variables@footnote{@code{comment-start}, @code{comment-end},
+@code{comment-start-skip}, @code{paragraph-start},
+@code{paragraph-separate}, @code{paragraph-ignore-fill-prefix},
+@code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and
+@code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them
+according to the language syntax and the comment line prefix.
+
+@defopt c-comment-prefix-regexp
+@vindex comment-prefix-regexp (c-)
+This style variable contains the regexp used to recognize the
+@dfn{comment line prefix}, which is the line decoration that starts
+every line in a comment. The variable is either the comment line
+prefix itself, or (more usually) an association list with different
+values for different languages. The symbol for the major mode is
+looked up in the alist to get the regexp for the language, and if it
+isn't found then the special symbol @samp{other} is looked up instead.
+
+When a comment line gets divided by @kbd{M-j} or the like, @ccmode{}
+inserts the comment line prefix from a neighbouring line at the start
+of the new line. The default value of c-comment-prefix-regexp is
+@samp{//+\\|\\**}, which matches C++ style line comments like
+
+@example
+// blah blah
+@end example
+
+@noindent
+with two or more slashes in front of them, and the second and
+subsequent lines of C style block comments like
+
+@example
+@group
+/*
+ * blah blah
+ */
+@end group
+@end example
+
+@noindent
+with zero or more stars at the beginning of every line. If you change
+this variable, please make sure it still matches the comment starter
+(i.e. @code{//}) of line comments @emph{and} the line prefix inside
+block comments.
+
+@findex c-setup-paragraph-variables
+@findex setup-paragraph-variables (c-)
+Also note that since @ccmode{} uses the value of
+@code{c-comment-prefix-regexp} to set up several other variables at
+mode initialization, there won't be any effect if you just change it
+inside a @ccmode{} buffer. You need to call the command
+@code{c-setup-paragraph-variables} too, to update those other
+variables. That's also the case if you modify
+@code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will
+already have set up these variables before calling the hook.
+@end defopt
+
+In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt
+the line prefix from the other lines in the comment.
+
+@vindex adaptive-fill-mode
+@cindex Adaptive Fill mode
+@ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU
+Emacs Manual}) to make Emacs correctly keep the line prefix when
+filling paragraphs. That also makes Emacs preserve the text
+indentation @emph{inside} the comment line prefix. E.g. in the
+following comment, both paragraphs will be filled with the left
+margins of the texts kept intact:
+
+@example
+@group
+/* Make a balanced b-tree of the nodes in the incoming
+ * stream. But, to quote the famous words of Donald E.
+ * Knuth,
+ *
+ * Beware of bugs in the above code; I have only
+ * proved it correct, not tried it.
+ */
+@end group
+@end example
+
+@findex c-setup-filladapt
+@findex setup-filladapt (c-)
+@findex filladapt-mode
+@vindex filladapt-mode
+@cindex Filladapt mode
+It's also possible to use other adaptive filling packages, notably Kyle
+E. Jones' Filladapt package@footnote{It's available from
+@uref{http://www.wonderworks.com/}. As of version 2.12, it does however
+lack a feature that makes it work suboptimally when
+@code{c-comment-prefix-regexp} matches the empty string (which it does
+by default). A patch for that is available from
+@uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.},
+@c 2005/11/22: The above is still believed to be the case.
+which handles things like bulleted lists nicely. There's a convenience
+function @code{c-setup-filladapt} that tunes the relevant variables in
+Filladapt for use in @ccmode{}. Call it from a mode hook, e.g. with
+something like this in your @file{.emacs}:
+
+@example
+(defun my-c-mode-common-hook ()
+ (c-setup-filladapt)
+ (filladapt-mode 1))
+(add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
+@end example
+
+@defopt c-block-comment-prefix
+@vindex block-comment-prefix (c-)
+@vindex c-comment-continuation-stars
+@vindex comment-continuation-stars (c-)
+Normally the comment line prefix inserted for a new line inside a
+comment is deduced from other lines in it. However there's one
+situation when there's no hint about what the prefix should look like,
+namely when a block comment is broken for the first time. This style
+variable@footnote{In versions before 5.26, this variable was called
+@code{c-comment-continuation-stars}. As a compatibility measure,
+@ccmode{} still uses the value on that variable if it's set.} is used
+then as the comment prefix. It defaults to @samp{*
+}@footnote{Actually, this default setting of
+@code{c-block-comment-prefix} typically gets overridden by the default
+style @code{gnu}, which sets it to blank. You can see the line
+splitting effect described here by setting a different style,
+e.g. @code{k&r} @xref{Choosing a Style}.}, which makes a comment
+
+@example
+/* Got O(n^2) here, which is a Bad Thing. */
+@end example
+
+@noindent
+break into
+
+@example
+@group
+/* Got O(n^2) here, which
+ * is a Bad Thing. */
+@end group
+@end example
+
+Note that it won't work to adjust the indentation by putting leading
+spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the
+normal indentation engine to indent the line. Thus, the right way to
+fix the indentation is by customizing the @code{c} syntactic symbol. It
+defaults to @code{c-lineup-C-comments}, which handles the indentation of
+most common comment styles, see @ref{Line-Up Functions}.
+@end defopt
+
+@defopt c-ignore-auto-fill
+@vindex ignore-auto-fill (c-)
+When auto fill mode is enabled, @ccmode{} can selectively ignore it
+depending on the context the line break would occur in, e.g. to never
+break a line automatically inside a string literal. This variable
+takes a list of symbols for the different contexts where auto-filling
+never should occur:
+
+@table @code
+@item string
+Inside a string or character literal.
+@item c
+Inside a C style block comment.
+@item c++
+Inside a C++ style line comment.
+@item cpp
+Inside a preprocessor directive.
+@item code
+Anywhere else, i.e. in normal code.
+@end table
+
+By default, @code{c-ignore-auto-fill} is set to @code{(string cpp
+code)}, which means that when auto-fill mode is activated,
+auto-filling only occurs in comments. In literals, it's often
+desirable to have explicit control over newlines. In preprocessor
+directives, the necessary @samp{\} escape character before the newline
+is not automatically inserted, so an automatic line break would
+produce invalid code. In normal code, line breaks are normally
+dictated by some logical structure in the code rather than the last
+whitespace character, so automatic line breaks there will produce poor
+results in the current implementation.
+@end defopt
+
+@vindex comment-multi-line
+If inside a comment and @code{comment-multi-line} (@pxref{Auto Fill,,,
+@emacsman{}, @emacsmantitle{}} is non-@code{nil}, the indentation and
+line prefix are preserved. If inside a comment and
+@code{comment-multi-line} is @code{nil}, a new comment of the same
+type is started on the next line and indented as appropriate for
+comments.
+
+Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at
+startup. The reason is that @kbd{M-j} could otherwise produce sequences
+of single line block comments for texts that should logically be treated
+as one comment, and the rest of the paragraph handling code
+(e.g. @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to
+inconsistent behavior.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top
+@comment node-name, next, previous, up
+@chapter Customizing Auto-newlines
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ccmode{} determines whether to insert auto-newlines in two basically
+different ways, depending on the character just typed:
+
+@table @asis
+@item Braces and Colons
+@ccmode{} first determines the syntactic context of the brace or colon
+(@pxref{Syntactic Symbols}), then looks for a corresponding element in
+an alist. This element specifies where to put newlines - this is any
+combination of before and after the brace or colon. If no alist
+element is found, newlines are inserted both before and after a brace,
+but none are inserted around a colon. See @ref{Hanging Braces} and
+@ref{Hanging Colons}.
+
+@item Semicolons and Commas
+The variable @code{c-hanging-semi&comma-criteria} contains a list of
+functions which determine whether to insert a newline after a newly
+typed semicolon or comma. @xref{Hanging Semicolons and Commas}.
+@end table
+
+The names of these configuration variables contain @samp{hanging}
+because they let you @dfn{hang} the pertinent characters. A character
+which introduces a C construct is said to @dfn{hang on the right} when
+it appears at the end of a line after other code, being separated by a
+line break from the construct it introduces, like the opening brace in:
+
+@example
+@group
+while (i < MAX) @{
+ total += entry[i];
+ entry [i++] = 0;
+@}
+@end group
+@end example
+
+@noindent
+A character @dfn{hangs on the left} when it appears at the start of
+the line after the construct it closes off, like the above closing
+brace.
+
+The next chapter, ``Clean-ups'', describes how to configure @ccmode{}
+to remove these automatically added newlines in certain specific
+circumstances. @xref{Clean-ups}.
+
+@menu
+* Hanging Braces::
+* Hanging Colons::
+* Hanging Semicolons and Commas::
+@end menu
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines
+@comment node-name, next, previous, up
+@section Hanging Braces
+@cindex hanging braces
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+To specify which kinds of braces you want auto-newlines put around,
+you set the style variable @code{c-hanging-braces-alist}. Its
+structure and semantics are described in this section. Details of how
+to set it up, and its relationship to CC Mode's style system are given
+in @ref{Style Variables}.
+
+Say you wanted an auto-newline after (but not before) the following
+@samp{@{}:
+
+@example
+if (foo < 17) @{
+@end example
+
+@noindent
+First you need to find the @dfn{syntactic context} of the brace---type
+a @key{RET} before the brace to get it on a line of its
+own@footnote{Also insert a @samp{\} at the end of the previous line if
+you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you
+something like:
+
+@example
+((substatement-open 1061))
+@end example
+
+@noindent
+So here you need to put the entry @code{(substatement-open . (after))}
+into @code{c-hanging-braces-alist}.
+
+If you don't want any auto-newlines for a particular syntactic symbol,
+put this into @code{c-hanging-braces-alist}:
+
+@example
+(brace-entry-open)
+@end example
+
+If some brace syntactic symbol is not in @code{c-hanging-brace-alist},
+its entry is taken by default as @code{(before after)}---insert a
+newline both before and after the brace. In place of a
+``before/after'' list you can specify a function in this alist---this
+is useful when the auto newlines depend on the code around the brace.
+
+@defopt c-hanging-braces-alist
+@vindex hanging-braces-alist (c-)
+
+This variable is an association list which maps syntactic symbols to
+lists of places to insert a newline. @xref{Association
+Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the
+syntactic symbol, the associated value is either @code{nil}, a list,
+or a function.
+
+@table @asis
+@item The Key - the syntactic symbol
+The syntactic symbols that are useful as keys in this list are
+@code{brace-list-intro}, @code{statement-cont},
+@code{inexpr-class-open}, @code{inexpr-class-close}, and all the
+@code{*-open} and @code{*-close} symbols. @xref{Syntactic Symbols},
+for a more detailed description of these syntactic symbols, except for
+@code{inexpr-class-open} and @code{inexpr-class-close}, which aren't
+actual syntactic symbols. Elements with any other value as a key get
+ignored.
+
+The braces of anonymous inner classes in Java are given the special
+symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that
+they can be distinguished from the braces of normal classes@footnote{The
+braces of anonymous classes produce a combination of
+@code{inexpr-class}, and @code{class-open} or @code{class-close} in
+normal indentation analysis.}.
+
+Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})},
+@samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace
+lists in this regard, even though they do for normal indentation
+purposes. It's currently not possible to set automatic newlines on
+these constructs.
+
+@item The associated value - the ``ACTION'' list or function
+The value associated with each syntactic symbol in this association
+list is called an @var{action}, which can be either a list or a
+function which returns a list. @xref{Custom Braces}, for how to use
+a function as a brace hanging @var{action}.
+
+The list @var{action} (or the list returned by @var{action} when it's
+a function) contains some 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 hangs on the right side
+of the line, as in:
+
+@example
+// here, open braces always `hang'
+void spam( int i ) @{
+ if( i == 7 ) @{
+ dosomething(i);
+ @}
+@}
+@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 newlines
+are added neither before nor after the brace.
+@end table
+
+If a syntactic symbol is missing entirely from
+@code{c-hanging-braces-alist}, it's treated in the same way as an
+@var{action} with a list containing @code{before} and @code{after}, so
+that braces by default end up on their own line.
+
+For example, the default value of @code{c-hanging-braces-alist} is:
+
+@example
+((brace-list-open)
+ (brace-entry-open)
+ (statement-cont)
+ (substatement-open after)
+ (block-close . c-snug-do-while)
+ (extern-lang-open after)
+ (namespace-open after)
+ (module-open after)
+ (composition-open after)
+ (inexpr-class-open after)
+ (inexpr-class-close before))
+@end example
+
+@noindent which says that @code{brace-list-open},
+@code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists
+inside statements, such as initializers for static array variables
+inside functions in C, are recognized as @code{statement-cont}. All
+normal substatement blocks are recognized with other symbols.} 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},
+@code{extern-lang-open}, and @code{inexpr-class-open} braces should hang
+on the right side, but subsequent text should follow on the next line.
+The opposite holds for @code{inexpr-class-close} braces; they won't
+hang, but the following text continues on the same line. Here, in the
+@code{block-close} entry, you also see an example of using a function as
+an @var{action}. In all other cases, braces are put on a line by
+themselves.
+@end defopt
+
+@menu
+* Custom Braces::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Custom Braces, , Hanging Braces, Hanging Braces
+@comment node-name, next, previous, up
+@subsection Custom Brace Hanging
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@vindex c-hanging-braces-alist
+@vindex hanging-braces-alist (c-)
+@cindex action functions
+Syntactic symbols aren't the only place where you can customize
+@ccmode{} with the lisp equivalent of callback functions. Remember
+that @var{action}s are usually a list containing some combination of
+the symbols @code{before} and @code{after} (@pxref{Hanging Braces}).
+For more flexibility, you can instead specify brace ``hanginess'' by
+giving a syntactic symbol an @dfn{action function} in
+@code{c-hanging-braces-alist}; this function determines the
+``hanginess'' of a brace, usually by looking at the code near it.
+
+@cindex customization, brace hanging
+An action function is called with two arguments: the syntactic symbol
+for the brace (e.g. @code{substatement-open}), and the buffer position
+where the brace has been inserted. Point is undefined on entry to an
+action function, but the function must preserve it (e.g. by using
+@code{save-excursion}). The return value should be a list containing
+some combination of @code{before} and @code{after}, including neither
+of them (i.e. @code{nil}).
+
+@defvar c-syntactic-context
+@vindex syntactic-context (c-)
+During the call to the indentation or brace hanging @var{action}
+function, this variable is bound to the full syntactic analysis list.
+This might be, for example, @samp{((block-close 73))}. Don't ever
+give @code{c-syntactic-context} a value yourself---this would disrupt
+the proper functioning of @ccmode{}.
+
+This variable is also bound in three other circumstances:
+(i)@w{ }when calling a c-hanging-semi&comma-criteria function
+(@pxref{Hanging Semicolons and Commas}); (ii)@w{ }when calling a
+line-up function (@pxref{Custom Line-Up}); (iii)@w{ }when calling a
+c-special-indent-hook function (@pxref{Other Indentation}).
+@end defvar
+
+As an example, @ccmode{} itself uses this feature to dynamically
+determine the hanginess of braces which close ``do-while''
+constructs:
+
+@example
+void do_list( int count, char** atleast_one_string )
+@{
+ int i=0;
+ do @{
+ handle_string( atleast_one_string[i] );
+ i++;
+ @} while( i < count );
+@}
+@end example
+
+@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."
+ (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
+
+@findex c-snug-do-while
+@findex snug-do-while (c-)
+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.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines
+@comment node-name, next, previous, up
+@section Hanging Colons
+@cindex hanging colons
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex customization, colon hanging
+@vindex c-hanging-colons-alist
+@vindex hanging-colons-alist (c-)
+
+Using a mechanism similar to brace hanging (@pxref{Hanging Braces}),
+colons can also be made to hang using the style variable
+@code{c-hanging-colons-alist} - When a colon is typed, @ccmode
+determines its syntactic context, looks this up in the alist
+@code{c-changing-colons-alist} and inserts up to two newlines
+accordingly. Here, however, If @ccmode fails to find an entry for a
+syntactic symbol in the alist, no newlines are inserted around the
+newly typed colon.
+
+@defopt c-hanging-colons-alist
+@vindex hanging-colons-alist (c-)
+
+@table @asis
+@item The Key - the syntactic symbol
+The syntactic symbols appropriate as keys in this association list
+are: @code{case-label}, @code{label}, @code{access-label},
+@code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic
+Symbols}. Elements with any other value as a key get ignored.
+
+@item The associate value - the ``ACTION'' list
+The @var{action} here is simply a list containing a combination of the
+symbols @code{before} and @code{after}. Unlike in
+@code{c-hanging-braces-alist}, functions as @var{actions} are not
+supported - there doesn't seem to be any need for them.
+@end table
+@end defopt
+
+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 Semicolons and Commas, , Hanging Colons, Custom Auto-newlines
+@comment node-name, next, previous, up
+@section Hanging Semicolons and Commas
+@cindex hanging semicolons
+@cindex hanging commas
+@cindex customization, semicolon newlines
+@cindex customization, comma newlines
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@defopt c-hanging-semi&comma-criteria
+@vindex hanging-semi&comma-criteria (c-)
+This style variable takes a list of functions; these get called when
+you type a semicolon or comma. The functions are called in order
+without arguments. When these functions are entered, point is just
+after the newly inserted @samp{;} or @samp{,} and they must preserve
+point (e.g., by using @code{save-excursion}). During the call, the
+variable @code{c-syntactic-context} is bound to the syntactic context
+of the current line@footnote{This was first introduced in @ccmode{}
+5.31.} @pxref{Custom Braces}. These functions don't insert newlines
+themselves, rather they direct @ccmode{} whether or not to do so.
+They should return one of the following values:
+
+@table @code
+@item t
+A newline is to be inserted after the @samp{;} or @samp{,}, and no
+more functions from the list are to be called.
+@item stop
+No more functions from the list are to be called, and no newline is to
+be inserted.
+@item nil
+No determination has been made, and the next function in the list is
+to be called.
+@end table
+
+Note that auto-newlines are never inserted @emph{before} a semicolon
+or comma. If every function in the list is called without a
+determination being made, then no newline is added.
+
+In AWK mode, this variable is set by default to @code{nil}. In the
+other modes, the default value is a list containing a single function,
+@code{c-semi&comma-inside-parenlist}. This inserts newlines after all
+semicolons, apart from those separating @code{for}-clause statements.
+@end defopt
+
+@defun c-semi&comma-no-newlines-before-nonblanks
+@findex semi&comma-no-newlines-before-nonblanks (c-)
+This is an example of a criteria function, provided by @ccmode{}. It
+prevents newlines from being inserted after semicolons when there is a
+non-blank following line. Otherwise, it makes no determination. To
+use, add this function to the front of the
+@code{c-hanging-semi&comma-criteria} list.
+
+@example
+(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 example
+@end defun
+
+@defun c-semi&comma-inside-parenlist
+@findex semi&comma-inside-parenlist (c-)
+@defunx c-semi&comma-no-newlines-for-oneline-inliners
+@findex semi&comma-no-newlines-for-oneline-inliners (c-)
+The function @code{c-semi&comma-inside-parenlist} is what prevents
+newlines from being inserted inside the parenthesis list of @code{for}
+statements. 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
+(e.g. in C++ or Java).
+@end defun
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top
+@comment node-name, next, previous, up
+@chapter Clean-ups
+@cindex clean-ups
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@dfn{Clean-ups} are mechanisms which remove (or exceptionally, add)
+whitespace in specific circumstances and are complementary to colon
+and brace hanging. You enable a clean-up by adding its symbol into
+@code{c-cleanup-list}, e.g. like this:
+
+@example
+(add-to-list 'c-cleanup-list 'space-before-funcall)
+@end example
+
+On the surface, it would seem that clean-ups overlap the functionality
+provided by the @code{c-hanging-*-alist} variables. Clean-ups,
+however, are used to adjust code ``after-the-fact'', i.e. to adjust
+the whitespace in constructs later than when they were typed.
+
+Most of the clean-ups remove automatically inserted newlines, and are
+only active when auto-newline minor mode is turned on. Others will
+work all the time. Note that clean-ups are only performed when there
+is nothing but whitespace appearing between the individual components
+of the construct, and (apart from @code{comment-close-slash}) when the
+construct does not occur within a literal (@pxref{Auto-newlines}).
+
+@defopt c-cleanup-list
+@vindex cleanup-list (c-)
+@cindex literal
+
+You configure @ccmode{}'s clean-ups by setting the style 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.
+@end defopt
+
+These are the clean-ups that are only active when electric and
+auto-newline minor modes are enabled:
+
+@c TBD: Would like to use some sort of @deffoo here; @table indents a
+@c bit too much in dvi output.
+@table @code
+@item brace-else-brace
+Clean 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 last open brace is typed:
+
+@example
+@group
+void spam(int i)
+@{
+ if( i==7 ) @{
+ dosomething();
+ @} else @{
+@end group
+@end example
+
+@item 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 last open parenthesis is typed:
+
+@example
+@group
+void spam(int i)
+@{
+ if( i==7 ) @{
+ dosomething();
+ @} else if(
+@end group
+@end example
+
+@noindent
+and like this after the last open brace is typed:
+
+@example
+@group
+void spam(int i)
+@{
+ if( i==7 ) @{
+ dosomething();
+ @} else if( i==3 ) @{
+@end group
+@end example
+
+@item brace-catch-brace
+Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch
+(...) @{} in C++ and Java mode.
+
+@item empty-defun-braces
+Clean 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 defun-close-semi
+Clean up the terminating semicolon on top-level function or class
+definitions when they follow a close brace. Clean up occurs when the
+semicolon is typed. So for example, the following:
+
+@example
+@group
+class Spam
+@{
+...
+@}
+;
+@end group
+@end example
+
+@noindent
+is transformed into this when the semicolon is typed:
+
+@example
+@group
+class Spam
+@{
+...
+@};
+@end group
+@end example
+
+@item list-close-comma
+Clean up commas following braces in array and aggregate initializers.
+Clean up occurs when the comma is typed. The space before the comma
+is zapped just like the space before the semicolon in
+@code{defun-close-semi}.
+
+@item scope-operator
+Clean up double colons which might designate a C++ scope operator split
+across multiple lines@footnote{Certain C++ constructs introduce
+ambiguous situations, so @code{scope-operator} clean-ups might 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.
+
+@item one-liner-defun
+Clean up a single line of code enclosed by defun braces by removing
+the whitespace before and after the code. The clean-up happens when
+the closing brace is typed. If the variable
+@code{c-max-one-liner-length} is set, the cleanup is only done if the
+resulting line would be no longer than the value of that variable.
+
+For example, consider this AWK code:
+
+@example
+@group
+BEGIN @{
+ FS = "\t" # use <TAB> as a field separator
+@}
+@end group
+@end example
+
+@noindent
+It gets compacted to the following when the closing brace is typed:
+
+@example
+@group
+BEGIN @{FS = "\t"@} # use <TAB> as a field separator
+@end group
+@end example
+
+@defopt c-max-one-liner-length
+@vindex max-one-liner-length (c-)
+The maximum length of the resulting line for which the clean-up
+@code{one-liner-defun} will be triggered. This length is that of the entire
+line, including any leading whitespace and any trailing comment. Its
+default value is 80. If the value is zero or @code{nil}, no limit
+applies.
+@end defopt
+@end table
+
+The following clean-ups are always active when they occur on
+@code{c-cleanup-list}, regardless of whether Electric minor mode or
+Auto-newline minor mode are enabled:
+
+@table @code
+@item space-before-funcall
+Insert a space between the function name and the opening parenthesis
+of a function call. This produces function calls in the style
+mandated by the GNU coding standards, e.g. @samp{signal@w{ }(SIGINT,
+SIG_IGN)} and @samp{abort@w{ }()}. Clean up occurs when the opening
+parenthesis is typed. This clean-up should never be active in AWK
+Mode, since such a space is syntactically invalid for user defined
+functions.
+
+@item compact-empty-funcall
+Clean up any space between the function name and the opening parenthesis
+of a function call that has no arguments. This is typically used
+together with @code{space-before-funcall} if you prefer the GNU function
+call style for functions with arguments but think it looks ugly when
+it's only an empty parenthesis pair. I.e. you will get @samp{signal
+(SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the
+closing parenthesis is typed.
+
+@item comment-close-slash
+When inside a block comment, terminate the comment when you type a slash
+at the beginning of a line (i.e. immediately after the comment prefix).
+This clean-up removes whitespace preceding the slash and if needed,
+inserts a star to complete the token @samp{*/}. Type @kbd{C-q /} in this
+situation if you just want a literal @samp{/} inserted.
+@end table
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top
+@comment node-name, next, previous, up
+@chapter Indentation Engine Basics
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+This chapter will briefly cover how @ccmode{} indents lines of code.
+It is helpful to understand the indentation model being used so that
+you will know how to customize @ccmode{} for your personal coding
+style. All the details are in @ref{Customizing Indentation}.
+
+@ccmode{} has an indentation engine that provides a flexible and
+general mechanism for customizing indentation. When @ccmode{} indents
+a line of code, it separates its calculations into two steps:
+
+@enumerate
+@item
+@cindex syntactic symbol
+@cindex anchor position
+It analyzes the line to determine its @dfn{syntactic symbol(s)} (the
+kind of language construct it's looking at) and its @dfn{anchor
+position} (the position earlier in the file that @ccmode{} will indent
+the line relative to). The anchor position might be the location of
+an opening brace in the previous line, for example. @xref{Syntactic
+Analysis}.
+@item
+@cindex offsets
+@cindex indentation offset specifications
+It looks up the syntactic symbol(s) in the configuration to get the
+corresponding @dfn{offset(s)}. The symbol @code{+}, which means
+``indent this line one more level'' is a typical offset. @ccmode{}
+then applies these offset(s) to the anchor position, giving the
+indentation for the line. The different sorts of offsets are
+described in @ref{c-offsets-alist}.
+@end enumerate
+
+In exceptional circumstances, the syntax directed indentation
+described here may be a nuisance rather than a help. You can disable
+it by setting @code{c-syntactic-indentation} to @code{nil}. (To set
+the variable interactively, @ref{Minor Modes}).
+
+@defopt c-syntactic-indentation
+@vindex syntactic-indentation (c-)
+When this is non-@code{nil} (which it is by default), the indentation
+of code is done according to its syntactic structure. When it's
+@code{nil}, every line is just indented to the same level as the
+previous one, and @kbd{TAB} (@code{c-indent-command}) adjusts the
+indentation in steps of @code{c-basic-offset}. The current style
+(@pxref{Config Basics}) then has no effect on indentation, nor do any
+of the variables associated with indentation, not even
+@code{c-special-indent-hook}.
+@end defopt
+
+@menu
+* Syntactic Analysis::
+* Syntactic Symbols::
+* Indentation Calculation::
+@end menu
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics
+@comment node-name, next, previous, up
+@section Syntactic Analysis
+@cindex syntactic analysis
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex syntactic element
+@cindex syntactic context
+The first thing @ccmode{} does when indenting a line of code, is to
+analyze the line, determining the @dfn{syntactic context} of the
+(first) construct on that line. It's a list of @dfn{syntactic
+elements}, where each syntactic element in turn is a list@footnote{In
+@ccmode 5.28 and earlier, a syntactic element was a dotted pair; the
+cons was the syntactic symbol and the cdr was the anchor position.
+For compatibility's sake, the parameter passed to a line-up function
+still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a
+brief and typical example:
+
+@example
+((defun-block-intro 1959))
+@end example
+
+@cindex syntactic symbol
+@noindent
+The first thing inside each syntactic element is always a
+@dfn{syntactic symbol}. It describes the kind of construct that was
+recognized, 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 remaining entries are various data associated
+with the recognized construct - there might be zero or more.
+
+@cindex anchor position
+Conceptually, a line of code is always indented relative to some
+position higher up in the buffer (typically the indentation of the
+previous line). That position is the @dfn{anchor position} in the
+syntactic element. If there is an entry after the syntactic symbol in
+the syntactic element list then it's either nil or that anchor position.
+
+Here is an example. Suppose we had the following code as the only thing
+in a C++ buffer @footnote{The line numbers in this and future examples
+don't actually appear in the buffer, of course!}:
+
+@example
+ 1: void swap( int& a, int& b )
+ 2: @{
+ 3: int tmp = a;
+ 4: a = b;
+ 5: b = tmp;
+ 6: @}
+@end example
+
+@noindent
+We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to
+report what the syntactic analysis is for the current line:
+
+@table @asis
+@item @kbd{C-c C-s} (@code{c-show-syntactic-information})
+@kindex C-c C-s
+@findex c-show-syntactic-information
+@findex show-syntactic-information (c-)
+This command calculates the syntactic analysis of the current line and
+displays it in the minibuffer. The command also highlights the anchor
+position(s).
+@end table
+
+ 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
+
+@noindent
+and the @samp{i} of @code{int} on line 3 would be highlighted. This
+tells us that the line is a statement and it is indented relative to
+buffer position 35, the highlighted position. 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
+
+@noindent
+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
+ 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
+Hitting @kbd{C-c C-s} on line 4 gives us:
+
+@example
+((substatement-open 46))
+@end example
+
+@cindex substatement
+@cindex substatement 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 contexts can contain more than one element, and syntactic
+elements need not have anchor positions. The most common example of
+this is a @dfn{comment-only line}:
+
+@example
+ 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 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 context contains two syntactic
+elements. Notice that the first element, @samp{(comment-intro)}, has no
+anchor position.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics
+@comment node-name, next, previous, up
+@section Syntactic Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex syntactic symbols, brief list
+@vindex c-offsets-alist
+@vindex offsets-alist (c-)
+This section is a complete list of the syntactic symbols which appear
+in the @code{c-offsets-alist} style variable, along with brief
+descriptions. The previous section (@pxref{Syntactic Analysis})
+states what syntactic symbols are and how the indentation engine uses
+them.
+
+More detailed descriptions of these symbols, together with snippets of
+source code to which they apply, appear in the examples in the
+subsections below. Note that, in the interests of brevity, the anchor
+position associated with most syntactic symbols is @emph{not}
+specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent
+line---this highlights the anchor position.
+
+@ssindex -open symbols
+@ssindex -close symbols
+@ssindex -block-intro symbols
+The syntactic symbols which indicate brace constructs follow a general
+naming convention. When a line begins with an open or close brace,
+its syntactic symbol will contain the suffix @code{-open} or
+@code{-close} respectively. The first line within the brace block
+construct will contain the suffix @code{-block-intro}.
+
+@ssindex -intro symbols
+@ssindex -cont symbols
+In constructs which can span several lines, a distinction is usually
+made between the first line that introduces the construct and the
+lines that continue it. The syntactic symbols that indicate these
+lines will contain the suffixes @code{-intro} or @code{-cont}
+respectively.
+
+The best way to understand how all this works is by looking at some
+examples. Remember that you can see the syntax of any source code
+line by using @kbd{C-c C-s}.
+
+@table @code
+@item string
+Inside a multiline string. @ref{Literal Symbols}.
+@item c
+Inside a multiline C style block comment. @ref{Literal Symbols}.
+@item defun-open
+Brace that opens a top-level function definition. @ref{Function
+Symbols}.
+@item defun-close
+Brace that closes a top-level function definition. @ref{Function
+Symbols}.
+@item defun-block-intro
+The first line in a top-level defun. @ref{Function Symbols}.
+@item class-open
+Brace that opens a class definition. @ref{Class Symbols}.
+@item class-close
+Brace that closes a class definition. @ref{Class Symbols}.
+@item inline-open
+Brace that opens an in-class inline method. @ref{Class Symbols}.
+@item inline-close
+Brace that closes an in-class inline method. @ref{Class Symbols}.
+@item 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 in this region,
+however in C++ and Java, @code{throws} declarations and other things
+can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not
+@c go somewhere better?}
+@item knr-argdecl-intro
+First line of a K&R C argument declaration. @ref{K&R Symbols}.
+@item knr-argdecl
+Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}.
+@item topmost-intro
+The first line in a ``topmost'' definition. @ref{Function Symbols}.
+@item topmost-intro-cont
+Topmost definition continuation lines. This is only used in the parts
+that aren't covered by other symbols such as @code{func-decl-cont} and
+@code{knr-argdecl}. @ref{Function Symbols}.
+@item member-init-intro
+First line in a member initialization list. @ref{Class Symbols}.
+@item member-init-cont
+Subsequent member initialization list lines. @ref{Class Symbols}.
+@item inher-intro
+First line of a multiple inheritance list. @ref{Class Symbols}.
+@item inher-cont
+Subsequent multiple inheritance lines. @ref{Class Symbols}.
+@item block-open
+Statement block open brace. @ref{Literal Symbols}.
+@item block-close
+Statement block close brace. @ref{Conditional Construct Symbols}.
+@item brace-list-open
+Open brace of an enum or static array list. @ref{Brace List Symbols}.
+@item brace-list-close
+Close brace of an enum or static array list. @ref{Brace List Symbols}.
+@item brace-list-intro
+First line in an enum or static array list. @ref{Brace List Symbols}.
+@item brace-list-entry
+Subsequent lines in an enum or static array list. @ref{Brace List
+Symbols}.
+@item brace-entry-open
+Subsequent lines in an enum or static array list where the line begins
+with an open brace. @ref{Brace List Symbols}.
+@item statement
+A statement. @ref{Function Symbols}.
+@item statement-cont
+A continuation of a statement. @ref{Function Symbols}.
+@item statement-block-intro
+The first line in a new statement block. @ref{Conditional Construct
+Symbols}.
+@item statement-case-intro
+The first line in a case block. @ref{Switch Statement Symbols}.
+@item statement-case-open
+The first line in a case block that starts with a brace. @ref{Switch
+Statement Symbols}.
+@item substatement
+The first line after a conditional or loop construct.
+@ref{Conditional Construct Symbols}.
+@item substatement-open
+The brace that opens a substatement block. @ref{Conditional Construct
+Symbols}.
+@item substatement-label
+The first line after a conditional or loop construct if it's a label.
+@ref{Conditional Construct Symbols}.
+@item case-label
+A label in a @code{switch} block. @ref{Switch Statement Symbols}.
+@item access-label
+C++ access control label. @ref{Class Symbols}.
+@item label
+Any other label. @ref{Literal Symbols}.
+@item do-while-closure
+The @code{while} line that ends a @code{do}-@code{while} construct.
+@ref{Conditional Construct Symbols}.
+@item else-clause
+The @code{else} line of an @code{if}-@code{else} construct.
+@ref{Conditional Construct Symbols}.
+@item catch-clause
+The @code{catch} or @code{finally} (in Java) line of a
+@code{try}-@code{catch} construct. @ref{Conditional Construct
+Symbols}.
+@item comment-intro
+A line containing only a comment introduction. @ref{Literal Symbols}.
+@item arglist-intro
+The first line in an argument list. @ref{Paren List Symbols}.
+@item arglist-cont
+Subsequent argument list lines when no arguments follow on the same
+line as the arglist opening paren. @ref{Paren List Symbols}.
+@item arglist-cont-nonempty
+Subsequent argument list lines when at least one argument follows on
+the same line as the arglist opening paren. @ref{Paren List Symbols}.
+@item arglist-close
+The solo close paren of an argument list. @ref{Paren List Symbols}.
+@item stream-op
+Lines continuing a stream operator (C++ only). @ref{Literal
+Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?}
+@item inclass
+The line is nested inside a class definition. @ref{Class Symbols}.
+@item cpp-macro
+The start of a preprocessor macro definition. @ref{Literal Symbols}.
+@item cpp-define-intro
+The first line inside a multiline preprocessor macro if
+@code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro
+Symbols}.
+@item cpp-macro-cont
+All lines inside multiline preprocessor macros if
+@code{c-syntactic-indentation-in-macros} is @code{nil}.
+@ref{Multiline Macro Symbols}.
+@item friend
+A C++ friend declaration. @ref{Class Symbols}.
+@item objc-method-intro
+The first line of an Objective-C method definition. @ref{Objective-C
+Method Symbols}.
+@item objc-method-args-cont
+Lines continuing an Objective-C method definition. @ref{Objective-C
+Method Symbols}.
+@item objc-method-call-cont
+Lines continuing an Objective-C method call. @ref{Objective-C Method
+Symbols}.
+@item extern-lang-open
+Brace that opens an @code{extern} block (e.g. @code{extern "C"
+@{...@}}). @ref{External Scope Symbols}.
+@item extern-lang-close
+Brace that closes an @code{extern} block. @ref{External Scope
+Symbols}.
+@item inextern-lang
+Analogous to @code{inclass} syntactic symbol, but used inside
+@code{extern} blocks. @ref{External Scope Symbols}.
+@item namespace-open
+@itemx namespace-close
+@itemx innamespace
+These are analogous to the three @code{extern-lang} symbols above, but
+are returned for C++ namespace blocks. @ref{External Scope Symbols}.
+@item module-open
+@itemx module-close
+@itemx inmodule
+Analogous to the above, but for CORBA IDL @code{module} blocks.
+@ref{External Scope Symbols}.
+@item composition-open
+@itemx composition-close
+@itemx incomposition
+Analogous to the above, but for CORBA CIDL @code{composition} blocks.
+@ref{External Scope Symbols}.
+@item template-args-cont
+C++ template argument list continuations. @ref{Class Symbols}.
+@item inlambda
+Analogous to @code{inclass} syntactic symbol, but used inside lambda
+(i.e. anonymous) functions. Only used in Pike mode. @ref{Statement
+Block Symbols}.
+@item lambda-intro-cont
+Lines continuing the header of a lambda function, i.e. between the
+@code{lambda} keyword and the function body. Only used in Pike mode.
+@ref{Statement Block Symbols}.
+@item inexpr-statement
+A statement block inside an expression. The gcc C and C++ extension
+for this is recognized. It's also used for the special functions that
+take a statement block as an argument in Pike. @ref{Statement Block
+Symbols}.
+@item inexpr-class
+A class definition inside an expression. This is used for anonymous
+classes in Java. It's also used for anonymous array initializers in
+Java. @ref{Anonymous Class Symbol}.
+@end table
+
+@menu
+* Function Symbols::
+* Class Symbols::
+* Conditional Construct Symbols::
+* Switch Statement Symbols::
+* Brace List Symbols::
+* External Scope Symbols::
+* Paren List Symbols::
+* Literal Symbols::
+* Multiline Macro Symbols::
+* Objective-C Method Symbols::
+* Anonymous Class Symbol::
+* Statement Block Symbols::
+* K&R Symbols::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Function Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+This example shows a typical function declaration.
+
+@example
+ 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 example
+
+@ssindex topmost-intro
+@ssindex topmost-intro-cont
+@ssindex defun-open
+@ssindex defun-close
+@ssindex defun-block-intro
+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 the
+corresponding
+@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.
+
+@ssindex statement
+@ssindex statement-cont
+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.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Class related Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Here's an example which illustrates some C++ class syntactic symbols:
+
+@example
+ 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 example
+
+@ssindex class-open
+@ssindex class-close
+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.
+
+@ssindex inher-intro
+@ssindex inher-cont
+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.
+
+@ssindex access-label
+@ssindex inclass
+Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
+
+@example
+((inclass 58) (access-label 58))
+@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
+((inclass 58) (topmost-intro 60))
+@end example
+
+@ssindex member-init-intro
+@ssindex member-init-cont
+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
+@ssindex inline-open
+@ssindex inline-close
+Line 11's analysis is a bit more complicated:
+
+@example
+((inclass 58) (inline-open))
+@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.
+However, if 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
+ 1: class Bass
+ 2: : public Guitar,
+ 3: public Amplifiable
+ 4: @{
+ 5: public:
+ 6: Bass();
+ 7: @};
+ 8:
+ 9: inline
+10: Bass::Bass()
+11: : eString( new BassString( 0.105 )),
+12: aString( new BassString( 0.085 )),
+13: dString( new BassString( 0.065 )),
+14: gString( new BassString( 0.045 ))
+15: @{
+16: eString.tune( 'E' );
+17: aString.tune( 'A' );
+18: dString.tune( 'D' );
+19: gString.tune( 'G' );
+20: @}
+@end example
+
+@ssindex friend
+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
+((inclass 58) (topmost-intro 380) (friend))
+@end example
+
+The @code{friend} and @code{inline-open} syntactic symbols are
+modifiers that do not have anchor positions.
+
+@ssindex template-args-cont
+Template definitions introduce yet another syntactic symbol:
+
+@example
+ 1: ThingManager <int,
+ 2: Framework::Callback *,
+ 3: Mutex> framework_callbacks;
+@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.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Conditional Construct Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Here is a (totally contrived) example which illustrates how syntax is
+assigned to various conditional constructs:
+
+@example
+ 1: void spam( int index )
+ 2: @{
+ 3: for( int i=0; i<index; i++ )
+ 4: @{
+ 5: if( i == 10 )
+ 6: do_something_special();
+ 7: else
+ 8: silly_label:
+ 9: do_something( i );
+10: @}
+11: do @{
+12: another_thing( i-- );
+13: @}
+14: while( i > 0 );
+15: @}
+@end example
+
+Only the lines that illustrate new syntactic symbols will be discussed.
+
+@ssindex substatement-open
+@ssindex statement-block-intro
+@ssindex block-close
+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{statement-block-intro} syntax. Line 10 contains the brace
+that closes the inner substatement block, and is therefore given the
+syntax @code{block-close}@footnote{@code{block-open} is used only for
+``free-standing'' blocks, and is somewhat rare (@pxref{Literal
+Symbols} for an example.)}. Line 13 is treated the same way.
+
+@ssindex substatement
+Lines 6 and 9 are also substatements of conditionals, but since they
+don't start blocks they are given @code{substatement} syntax
+instead of @code{substatement-open}.
+
+@ssindex substatement-label
+Line 8 contains a label, which is normally given @code{label} syntax.
+This one is however a bit special since it's between a conditional and
+its substatement. It's analyzed as @code{substatement-label} to let you
+handle this rather odd case differently from normal labels.
+
+@ssindex else-clause
+@ssindex catch-clause
+Line 7 start with an @code{else} that matches the @code{if} statement on
+line 5. It is therefore given the @code{else-clause} syntax and is
+anchored on the matching @code{if}. The @code{try}-@code{catch}
+constructs in C++ and Java are treated this way too, except that
+@code{catch} and (in Java) @code{finally}, are marked with
+@code{catch-clause}.
+
+@ssindex do-while-closure
+The @code{while} construct on line 14 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 still have
+@code{block-close} syntax.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Switch Statement Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Switch statements have their own set of syntactic symbols. Here's an
+example:
+
+@example
+ 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 example
+
+@ssindex case-label
+@ssindex statement-case-intro
+@ssindex statement-case-open
+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.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Brace List Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@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. The three special aggregate constructs
+in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as
+brace lists too. An example:
+
+@example
+ 1: static char* ingredients[] =
+ 2: @{
+ 3: "Ham",
+ 4: "Salt",
+ 5: NULL
+ 6: @};
+@end example
+
+@ssindex brace-list-open
+@ssindex brace-list-intro
+@ssindex brace-list-close
+@ssindex brace-list-entry
+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.
+
+@ssindex brace-entry-open
+Your static initializer might be initializing nested structures, for
+example:
+
+@example
+ 1: struct intpairs[] =
+ 2: @{
+ 3: @{ 1, 2 @},
+ 4: @{
+ 5: 3,
+ 6: 4
+ 7: @}
+ 8: @{ 1,
+ 9: 2 @},
+10: @{ 3, 4 @}
+11: @};
+@end example
+
+Here, you've already seen the analysis of lines 1, 2, 3, and 11. On
+line 4, things get interesting; this line is assigned
+@code{brace-entry-open} syntactic symbol because it's a bracelist entry
+line that starts with an open brace. Lines 5 and 6 (and line 9) are
+pretty standard, and line 7 is a @code{brace-list-close} as you'd
+expect. Once again, line 8 is assigned as @code{brace-entry-open} as is
+line 10.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection External Scope Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+External language definition blocks also have their own syntactic
+symbols. In this example:
+
+@example
+ 1: extern "C"
+ 2: @{
+ 3: int thing_one( int );
+ 4: int thing_two( double );
+ 5: @}
+@end example
+
+@ssindex extern-lang-open
+@ssindex extern-lang-close
+@ssindex inextern-lang
+@ssindex inclass
+@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:
+
+@example
+((inextern-lang) (topmost-intro 14))
+@end example
+
+@noindent
+where @code{inextern-lang} is a modifier similar in purpose to
+@code{inclass}.
+
+There are various other top level blocks like @code{extern}, and they
+are all treated in the same way except that the symbols are named after
+the keyword that introduces the block. E.g. C++ namespace blocks get
+the three symbols @code{namespace-open}, @code{namespace-close} and
+@code{innamespace}. The currently recognized top level blocks are:
+
+@table @asis
+@item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang}
+@code{extern} blocks in C and C++.@footnote{These should logically be
+named @code{extern-open}, @code{extern-close} and @code{inextern}, but
+that isn't the case for historical reasons.}
+
+@item @code{namespace-open}, @code{namespace-close}, @code{innamespace}
+@ssindex namespace-open
+@ssindex namespace-close
+@ssindex innamespace
+@code{namespace} blocks in C++.
+
+@item @code{module-open}, @code{module-close}, @code{inmodule}
+@ssindex module-open
+@ssindex module-close
+@ssindex inmodule
+@code{module} blocks in CORBA IDL.
+
+@item @code{composition-open}, @code{composition-close}, @code{incomposition}
+@ssindex composition-open
+@ssindex composition-close
+@ssindex incomposition
+@code{composition} blocks in CORBA CIDL.
+@end table
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Parenthesis (Argument) List Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+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
+ 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 example
+
+@ssindex arglist-intro
+@ssindex arglist-close
+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.
+
+@ssindex arglist-cont-nonempty
+@ssindex arglist-cont
+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.
+
+Syntactic elements with @code{arglist-intro},
+@code{arglist-cont-nonempty}, and @code{arglist-close} contain two
+buffer positions: the anchor position (the beginning of the
+declaration or statement) and the position of the open parenthesis.
+The latter position can be used in a line-up function (@pxref{Line-Up
+Functions}).
+
+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.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Comment String Label and Macro Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+A few miscellaneous syntactic symbols that haven't been previously
+covered are illustrated by this C++ example:
+
+@example
+ 1: void Bass::play( int volume )
+ 2: const
+ 3: @{
+ 4: /* this line starts a multiline
+ 5: * comment. This line should get `c' syntax */
+ 6:
+ 7: char* a_multiline_string = "This line starts a multiline \
+ 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 example
+
+The lines to note in this example include:
+
+@itemize @bullet
+@item
+@ssindex func-decl-cont
+Line 2 is assigned the @code{func-decl-cont} syntax.
+
+@item
+@ssindex comment-intro
+Line 4 is assigned both @code{defun-block-intro} @emph{and}
+@code{comment-intro} syntax. A syntactic element with
+@code{comment-intro} has no anchor point --- It is always accompanied
+by another syntactic element which does have one.
+
+@item
+@ssindex c
+Line 5 is 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.
+
+@item
+@ssindex string
+Line 8 is assigned @code{string} syntax.
+
+@item
+@ssindex label
+Line 10 is assigned @code{label} syntax.
+
+@item
+@ssindex block-open
+Line 11 is assigned @code{block-open} as well as @code{statement}
+syntax. A @code{block-open} syntactic element doesn't have an anchor
+position, since it always appears with another syntactic element which
+does have one.
+
+@item
+@ssindex cpp-macro
+Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the
+normal syntactic symbols (@code{statement-block-intro} and
+@code{statement}, respectively). Normally @code{cpp-macro} is
+configured to cancel out the normal syntactic context to make all
+preprocessor directives stick to the first column, but that's easily
+changed if you want preprocessor directives to be indented like the rest
+of the code. Like @code{comment-intro}, a syntactic element with
+@code{cpp-macro} doesn't contain an anchor position.
+
+@item
+@ssindex stream-op
+Line 17 is assigned @code{stream-op} syntax.
+@end itemize
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Multiline Macro Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex multiline macros
+@cindex syntactic whitespace
+@ssindex cpp-define-intro
+@ssindex cpp-macro-cont
+Multiline preprocessor macro definitions are normally handled just like
+other code, i.e. the lines inside them are indented according to the
+syntactic analysis of the preceding lines inside the macro. The first
+line inside a macro definition (i.e. the line after the starting line of
+the cpp directive itself) gets @code{cpp-define-intro}. In this example:
+
+@example
+ 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 example
+
+@noindent
+line 1 is given the syntactic symbol @code{cpp-macro}. The first line
+of a cpp directive is always given that symbol. Line 2 is given
+@code{cpp-define-intro}, so that you can give the macro body as a whole
+some extra indentation. Lines 3 through 5 are then analyzed as normal
+code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause}
+on line 5.
+
+The syntactic analysis inside macros can be turned off with
+@code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In
+that case, lines 2 through 5 would all be given @code{cpp-macro-cont}
+with an anchor position pointing to the @code{#} which starts the cpp
+directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed
+macros.}.
+
+@xref{Custom Macros}, for more info about the treatment of macros.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Objective-C Method Symbols, Anonymous Class Symbol, Multiline Macro Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Objective-C Method Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+In Objective-C buffers, there are three additional syntactic symbols
+assigned to various message calling constructs. Here's an example
+illustrating these:
+
+@example
+ 1: - (void)setDelegate:anObject
+ 2: withStuff:stuff
+ 3: @{
+ 4: [delegate masterWillRebind:self
+ 5: toDelegate:anObject
+ 6: withExtraStuff:stuff];
+ 7: @}
+@end example
+
+@ssindex objc-method-intro
+@ssindex objc-method-args-cont
+@ssindex objc-method-call-cont
+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.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Anonymous Class Symbol, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Anonymous Class Symbol (Java)
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Java has a concept of anonymous classes which can look something like
+this:
+
+@example
+ 1: public void watch(Observable o) @{
+ 2: o.addObserver(new Observer() @{
+ 3: public void update(Observable o, Object arg) @{
+ 4: history.addElement(arg);
+ 5: @}
+ 6: @});
+ 7: @}
+@end example
+
+@ssindex inexpr-class
+The brace following the @code{new} operator opens the anonymous class.
+Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the
+@code{inclass} symbol used in normal classes. Thus, the class will be
+indented just like a normal class, with the added indentation given to
+@code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't
+have an anchor position.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Statement Block Symbols, K&R Symbols, Anonymous Class Symbol, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Statement Block Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+There are a few occasions where a statement block might be used inside
+an expression. One is in C or C++ code using the gcc extension for
+this, e.g:
+
+@example
+ 1: int res = (@{
+ 2: int y = foo (); int z;
+ 3: if (y > 0) z = y; else z = - y;
+ 4: z;
+ 5: @});
+@end example
+
+@ssindex inexpr-statement
+Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the
+symbols they'd get in a normal block. Therefore, the indentation put on
+@code{inexpr-statement} is added to the normal statement block
+indentation. An @code{inexpr-statement} syntactic element doesn't
+contain an anchor position.
+
+In Pike code, there are a few other situations where blocks occur inside
+statements, as illustrated here:
+
+@example
+ 1: array itgob()
+ 2: @{
+ 3: string s = map (backtrace()[-2][3..],
+ 4: lambda
+ 5: (mixed arg)
+ 6: @{
+ 7: return sprintf ("%t", arg);
+ 8: @}) * ", " + "\n";
+ 9: return catch @{
+10: write (s + "\n");
+11: @};
+12: @}
+@end example
+
+@ssindex inlambda
+@ssindex lambda-intro-cont
+Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes
+by the @code{lambda} keyword. If the function argument list is put
+on a line of its own, as in line 5, it gets the @code{lambda-intro-cont}
+syntax. The function body is handled as an inline method body, with the
+addition of the @code{inlambda} syntactic symbol. This means that line
+6 gets @code{inlambda} and @code{inline-open}, and line 8 gets
+@code{inline-close}@footnote{You might wonder why it doesn't get
+@code{inlambda} too. It's because the closing brace is relative to the
+opening brace, which stands on its own line in this example. If the
+opening brace was hanging on the previous line, then the closing brace
+would get the @code{inlambda} syntax too to be indented correctly.}.
+
+@ssindex inexpr-statement
+On line 9, @code{catch} is a special function taking a statement block
+as its argument. The block is handled as an in-expression statement
+with the @code{inexpr-statement} syntax, just like the gcc extended C
+example above. The other similar special function, @code{gauge}, is
+handled like this too.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node K&R Symbols, , Statement Block Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection K&R Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ssindex knr-argdecl-intro
+@ssindex knr-argdecl
+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
+ 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 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 Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics
+@comment node-name, next, previous, up
+@section Indentation Calculation
+@cindex indentation
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Indentation for a line is calculated from the syntactic context
+(@pxref{Syntactic Analysis}).
+
+First, a buffer position is found whose column will be the base for the
+indentation calculation. It's the anchor position in the first
+syntactic element that provides one that is used. If no syntactic
+element has an anchor position then column zero is used.
+
+Second, the syntactic symbols in each syntactic element are looked up
+in the @code{c-offsets-alist} style variable
+(@pxref{c-offsets-alist}), which is an association list of syntactic
+symbols and the offsets to apply for those symbols. These offsets are
+added together with the base column to produce the new indentation
+column.
+
+Let's use our two code examples above to see how this works. Here is
+our first example again:
+
+@example
+ 1: void swap( int& a, int& b )
+ 2: @{
+ 3: int tmp = a;
+ 4: a = b;
+ 5: b = tmp;
+ 6: @}
+@end example
+
+Let's say point is on line 3 and we hit the @key{TAB} key to reindent
+the line. The syntactic context for that line is:
+
+@example
+((defun-block-intro 29))
+@end example
+
+@noindent
+Since buffer position 29 is the first and only anchor position in the
+list, @ccmode{} goes there and asks for the current column. This brace
+is in column zero, so @ccmode{} uses @samp{0} as the base column.
+
+Next, @ccmode{} looks up @code{defun-block-intro} in the
+@code{c-offsets-alist} style variable. Let's say it finds the value
+@samp{4}; it adds this to the base column @samp{0}, yielding a running
+total indentation of 4 spaces.
+
+Since there is only one syntactic element 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
+ 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 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
+context. The context for this line is:
+
+@example
+((substatement-open 46))
+@end example
+
+Here, @ccmode{} 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 the base column is @samp{4}. Then @ccmode{} looks up the
+@code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it
+finds the value @samp{4}. It's added with the base column and yields an
+indentation for the line of 8 spaces.
+
+Simple, huh?
+
+Actually, it's a bit more complicated than that since the entries on
+@code{c-offsets-alist} can be much more than plain offsets.
+@xref{c-offsets-alist}, for the full story.
+
+Anyway, 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.
+
+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 context and calculated offset always is echoed in the
+minibuffer when you hit @kbd{TAB}.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top
+@comment node-name, next, previous, up
+@chapter Customizing Indentation
+@cindex customization, indentation
+@cindex indentation
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The principal variable for customizing indentation is the style
+variable @code{c-offsets-alist}, which gives an @dfn{offset} (an
+indentation rule) for each syntactic symbol. Its structure and
+semantics are completely described in @ref{c-offsets-alist}. The
+various ways you can set the variable, including the use of the
+@ccmode{} style system, are described in @ref{Config Basics} and its
+sections, in particular @ref{Style Variables}.
+
+The simplest and most used kind of ``offset'' setting in
+@code{c-offsets-alist} is in terms of multiples of
+@code{c-basic-offset}:
+
+@defopt c-basic-offset
+@vindex basic-offset (c-)
+This style variable holds the basic offset between indentation levels.
+It's factory default is 4, but all the built-in styles set it
+themselves, to some value between 2 (for @code{gnu} style) and 8 (for
+@code{bsd}, @code{linux}, and @code{python} styles).
+@end defopt
+
+The most flexible ``offset'' setting you can make in
+@code{c-offsets-alist} is a line-up function (or even a list of them),
+either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one
+you write yourself (@pxref{Custom Line-Up}).
+
+Finally, in @ref{Other Indentation} you'll find the tool of last
+resort: a hook which is called after a line has been indented. You
+can install functions here to make ad-hoc adjustments to any line's
+indentation.
+
+@menu
+* c-offsets-alist::
+* Interactive Customization::
+* Line-Up Functions::
+* Custom Line-Up::
+* Other Indentation::
+@end menu
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation
+@comment node-name, next, previous, up
+@section c-offsets-alist
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+This section explains the structure and semantics of the style
+variable @code{c-offset-alist}, the principal variable for configuring
+indentation. Details of how to set it up, and its relationship to
+@ccmode{}'s style system are given in @ref{Style Variables}.
+
+@defopt c-offsets-alist
+@vindex offsets-alist (c-)
+This is an alist which associates an offset with each syntactic
+symbol. This @dfn{offset} is a rule specifying how to indent a line
+whose syntactic context matches the symbol. @xref{Syntactic
+Analysis}.
+
+Note that the buffer-local binding of this alist in a @ccmode{} buffer
+contains an entry for @emph{every} syntactic symbol. Its global
+binding and its settings within style specifications usually contain
+only a few entries. @xref{Style Variables}.
+
+The offset specification associated with any particular syntactic
+symbol can be an integer, a variable name, a vector, a function or
+lambda expression, a list, or one of the following special symbols:
+@code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The
+meanings of these values are described in detail below.
+
+Here is an example fragment of a @code{c-offsets-alist}, showing some
+of these kinds of offsets:
+
+@example
+((statement . 0)
+ (substatement . +)
+ (cpp-macro . [0])
+ (topmost-intro-cont . c-lineup-topmost-intro-cont)
+ (statement-block-intro . (add c-lineup-whitesmith-in-block
+ c-indent-multi-line-block))
+ @dots{}
+@*)
+@end example
+@end defopt
+
+@deffn Command c-set-offset (@kbd{C-c C-o})
+@findex set-offset (c-)
+@kindex C-c C-o
+This command changes the entry for a syntactic symbol in the current
+binding of @code{c-offsets-alist}, or it inserts a new entry if there
+isn't already one for that syntactic symbol.
+
+You can use @code{c-set-offsets} interactively within a @ccmode{}
+buffer to make experimental changes to your indentation settings.
+@kbd{C-c C-o} prompts you for the syntactic symbol to change
+(defaulting to that of the current line) and the new offset
+(defaulting to the current offset).
+
+@code{c-set-offsets} takes two arguments when used programmatically:
+@var{symbol}, the syntactic element symbol to change and @var{offset},
+the new offset for that syntactic element. You can call the command
+in your @file{.emacs} to change the global binding of
+@code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a
+hook function to make changes from the current style. @ccmode{}
+itself uses this function when initializing styles.
+@end deffn
+
+@cindex offset specification
+The ``offset specifications'' in @code{c-offsets-alist} can be any of
+the following:
+
+@table @asis
+@item An integer
+The integer specifies a relative offset. All relative
+offsets@footnote{The syntactic context @code{@w{((defun-block-intro
+2724) (comment-intro))}} would likely have two relative offsets.} will
+be added together and used to calculate the indentation relative to an
+anchor position earlier in the buffer. @xref{Indentation
+Calculation}, for details. Most of the time, it's probably better to
+use one of the special symbols like @code{+} than an integer (apart
+from zero).
+
+@item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}
+These special symbols describe a relative offset in multiples of
+@code{c-basic-offset}:
+
+By defining a style's indentation in terms of @code{c-basic-offset},
+you can change the amount of whitespace given to an indentation level
+while maintaining the same basic shape of your code. 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
+
+@item A vector
+The first element of the vector, an integer, sets the absolute
+indentation column. This will override any previously calculated
+indentation, but won't override relative indentation calculated from
+syntactic elements later on in the syntactic context of the line being
+indented. @xref{Indentation Calculation}. Any elements in the vector
+beyond the first will be ignored.
+
+@item A function or lambda expression
+The function will be called and its return value will in turn be
+evaluated as an offset specification. Functions are useful when more
+context than just the syntactic symbol is needed to get the desired
+indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for
+details about them.
+
+@item A symbol with a variable binding
+If the symbol also has a function binding, the function takes
+precedence over the variable. Otherwise the value of the variable is
+used. It must be an integer (which is used as relative offset) or a
+vector (an absolute offset).
+
+@item A list
+The offset can also be a list containing several offset
+specifications; these are evaluated recursively and combined. A list
+is typically only useful when some of the offsets are line-up
+functions. A common strategy is calling a sequence of functions in
+turn until one of them recognizes that it is appropriate for the
+source line and returns a non-@code{nil} value.
+
+@code{nil} values are always ignored when the offsets are combined.
+The first element of the list specifies the method of combining the
+non-@code{nil} offsets from the remaining elements:
+
+@table @code
+@item first
+Use the first offset that doesn't evaluate to @code{nil}. Subsequent
+elements of the list don't get evaluated.
+@item min
+Use the minimum of all the offsets. All must be either relative or
+absolute - they can't be mixed.
+@item max
+Use the maximum of all the offsets. All must be either relative or
+absolute - they can't be mixed.
+@item add
+Add all the evaluated offsets together. Exactly one of them may be
+absolute, in which case the result is absolute. Any relative offsets
+that preceded the absolute one in the list will be ignored in that case.
+@end table
+
+As a compatibility measure, if the first element is none of the above
+then it too will be taken as an offset specification and the whole list
+will be combined according to the method @code{first}.
+@end table
+
+@vindex c-strict-syntax-p
+@vindex strict-syntax-p (c-)
+If an offset specification evaluates to @code{nil}, then a relative
+offset of 0 (zero) is used@footnote{There is however a variable
+@code{c-strict-syntax-p} that when set to non-@code{nil} will cause an
+error to be signaled in that case. It's now considered obsolete since
+it doesn't work well with some of the alignment functions that return
+@code{nil} instead of zero. You should therefore leave
+@code{c-strict-syntax-p} set to @code{nil}.}.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation
+@comment node-name, next, previous, up
+@section Interactive Customization
+@cindex customization, interactive
+@cindex interactive customization
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+As an example of how to customize indentation, let's change the
+style of this example@footnote{In this and 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 symbols affect the offset calculations
+for that line. Hitting @kbd{C-c C-s} on line 4 yields:
+
+@example
+((substatement-open 44))
+@end example
+
+@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}. 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}.
+
+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 might not always work. The general approach
+to take is to always start adjusting offsets for lines higher up in the
+file, then reindent and see if any following lines need further
+adjustments.
+
+@c Move this bit to "Styles" (2005/10/7)
+@deffn Command c-set-offset symbol offset
+@findex set-offset (c-)
+@kindex C-c C-o
+This is the command bound to @kbd{C-c C-o}. It provides a convenient
+way to set offsets on @code{c-offsets-alist} both interactively (see
+the example above) and from your mode hook.
+
+It takes two arguments when used programmatically: @var{symbol} is the
+syntactic element symbol to change and @var{offset} is the new offset
+for that syntactic element.
+@end deffn
+@c End of MOVE THIS BIT.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation
+@comment node-name, next, previous, up
+@section Line-Up Functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex line-up function
+@cindex indentation function
+Often there are cases when a simple offset setting on a syntactic
+symbol isn't enough to get the desired indentation---for example, you
+might want to line up a closing parenthesis with the matching opening
+one rather than indenting relative to its ``anchor point''. @ccmode{}
+provides this flexibility with @dfn{line-up functions}.
+
+The way you associate a line-up function with a syntactic symbol is
+described in @ref{c-offsets-alist}. @ccmode{} comes with many
+predefined line-up functions for common situations. If none of these
+does what you want, you can write your own. @xref{Custom Line-Up}.
+Sometimes, it is easier to tweak the standard indentation by adding a
+function to @code{c-special-indent-hook} (@pxref{Other Indentation}).
+
+The line-up functions haven't been adapted for AWK buffers or tested
+with them. Some of them might work serendipitously. There shouldn't be
+any problems writing custom line-up functions for AWK mode.
+
+The calling convention for line-up functions is described fully in
+@ref{Custom Line-Up}. Roughly speaking, the return value is either an
+offset itself (such as @code{+} or @code{[0]}) or it's @code{nil},
+meaning ``this function is inappropriate in this case - try a
+different one''. @xref{c-offsets-alist}.
+
+The subsections below describe all the standard line-up functions,
+categorized by the sort of token the lining-up centers around. For
+each of these functions there is a ``works with'' list that indicates
+which syntactic symbols the function is intended to be used with.
+
+@macro workswith
+@emph{Works with:@ }
+@end macro
+@ifinfo
+@unmacro workswith
+@macro workswith
+Works with:
+@end macro
+@end ifinfo
+
+@macro sssTBasicOffset
+<--> @i{c-basic-offset}@c
+@end macro
+
+@macro sssTsssTBasicOffset
+<--><--> @i{c-basic-offset}@c
+@end macro
+
+@macro hereFn{func}
+<- @i{\func\}@c
+@end macro
+
+@c The TeX backend seems to insert extra spaces around the argument. :P
+@iftex
+@unmacro hereFn
+@macro hereFn{func}
+<-@i{\func\}@c
+@end macro
+@end iftex
+
+@menu
+* Brace/Paren Line-Up::
+* List Line-Up::
+* Operator Line-Up::
+* Comment Line-Up::
+* Misc Line-Up::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions
+@comment node-name, next, previous, up
+@subsection Brace and Parenthesis Line-Up Functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The line-up functions here calculate the indentation for braces,
+parentheses and statements within brace blocks.
+
+@defun c-lineup-close-paren
+@findex lineup-close-paren (c-)
+Line up the closing paren under its corresponding open paren if the
+open paren is followed by code. If the open paren ends its line, no
+indentation is added. E.g:
+
+@example
+@group
+main (int,
+ char **
+ ) @hereFn{c-lineup-close-paren}
+@end group
+@end example
+
+@noindent
+and
+
+@example
+@group
+main (
+ int, char **
+) @hereFn{c-lineup-close-paren}
+@end group
+@end example
+
+As a special case, if a brace block is opened at the same line as the
+open parenthesis of the argument list, the indentation is
+@code{c-basic-offset} instead of the open paren column. See
+@code{c-lineup-arglist} for further discussion of this ``DWIM'' measure.
+
+@workswith All @code{*-close} symbols.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@anchor{c-lineup-arglist-close-under-paren}
+@defun c-lineup-arglist-close-under-paren
+@findex lineup-arglist-close-under-paren (c-)
+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. It can also be used with
+@code{arglist-cont} and @code{arglist-cont-nonempty} to line up all
+lines inside a parenthesis under the open paren.
+
+As a special case, if a brace block is opened at the same line as the
+open parenthesis of the argument list, the indentation is
+@code{c-basic-offset} only. See @code{c-lineup-arglist} for further
+discussion of this ``DWIM'' measure.
+
+@workswith Almost all symbols, but are typically most useful on
+@code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and
+@code{arglist-cont-nonempty}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-indent-one-line-block
+@findex indent-one-line-block (c-)
+Indent a one line block @code{c-basic-offset} extra. E.g:
+
+@example
+@group
+if (n > 0)
+ @{m+=n; n=0;@} @hereFn{c-indent-one-line-block}
+@sssTBasicOffset{}
+@end group
+@end example
+
+@noindent
+and
+
+@example
+@group
+if (n > 0)
+@{ @hereFn{c-indent-one-line-block}
+ m+=n; n=0;
+@}
+@end group
+@end example
+
+The block may be surrounded by any kind of parenthesis characters.
+@code{nil} is returned if the line doesn't start with a one line block,
+which makes the function usable in list expressions.
+
+@workswith Almost all syntactic symbols, but most useful on the
+@code{-open} symbols.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-indent-multi-line-block
+@findex indent-multi-line-block (c-)
+Indent a multiline block @code{c-basic-offset} extra. E.g:
+
+@example
+@group
+int *foo[] = @{
+ NULL,
+ @{17@}, @hereFn{c-indent-multi-line-block}
+@end group
+@end example
+
+@noindent
+and
+
+@example
+@group
+int *foo[] = @{
+ NULL,
+ @{ @hereFn{c-indent-multi-line-block}
+ 17
+ @},
+ @sssTBasicOffset{}
+@end group
+@end example
+
+The block may be surrounded by any kind of parenthesis characters.
+@code{nil} is returned if the line doesn't start with a multiline
+block, which makes the function usable in list expressions.
+
+@workswith Almost all syntactic symbols, but most useful on the
+@code{-open} symbols.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-runin-statements
+@findex lineup-runin-statements (c-)
+Line up statements 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 line-up functions to better support this style.}. E.g:
+
+@example
+@group
+int main()
+@{ puts ("Hello!");
+ return 0; @hereFn{c-lineup-runin-statements}
+@}
+@end group
+@end example
+
+If there is no statement after the opening brace to align with,
+@code{nil} is returned. This makes the function usable in list
+expressions.
+
+@workswith The @code{statement} syntactic symbol.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-inexpr-block
+@findex lineup-inexpr-block (c-)
+This can be used with the in-expression block symbols to indent the
+whole block to the column where the construct is started. E.g. for Java
+anonymous classes, this lines up the class under the @samp{new} keyword,
+and in Pike it lines up the lambda function body under the @samp{lambda}
+keyword. Returns @code{nil} if the block isn't part of such a
+construct.
+
+@workswith @code{inlambda}, @code{inexpr-statement},
+@code{inexpr-class}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-after-whitesmith-blocks
+@findex lineup-after-whitesmith-blocks (c-)
+Compensate for Whitesmith style indentation of blocks. Due to the way
+@ccmode{} calculates anchor positions for normal lines inside blocks,
+this function is necessary for those lines to get correct Whitesmith
+style indentation. Consider the following examples:
+
+@example
+@group
+int foo()
+ @{
+ a;
+ x; @hereFn{c-lineup-after-whitesmith-blocks}
+@end group
+@end example
+
+@example
+@group
+int foo()
+ @{
+ @{
+ a;
+ @}
+ x; @hereFn{c-lineup-after-whitesmith-blocks}
+@end group
+@end example
+
+The fact that the line with @code{x} is preceded by a Whitesmith style
+indented block in the latter case and not the first should not affect
+its indentation. But since CC Mode in cases like this uses the
+indentation of the preceding statement as anchor position, the @code{x}
+would in the second case be indented too much if the offset for
+@code{statement} was set simply to zero.
+
+This lineup function corrects for this situation by detecting if the
+anchor position is at an open paren character. In that case, it instead
+indents relative to the surrounding block just like
+@code{c-lineup-whitesmith-in-block}.
+
+@workswith @code{brace-list-entry}, @code{brace-entry-open},
+@code{statement}, @code{arglist-cont}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-whitesmith-in-block
+@findex lineup-whitesmith-in-block (c-)
+Line up lines inside a block in Whitesmith style. It's done in a way
+that works both when the opening brace hangs and when it doesn't. E.g:
+
+@example
+@group
+something
+ @{
+ foo; @hereFn{c-lineup-whitesmith-in-block}
+ @}
+@end group
+@end example
+
+@noindent
+and
+
+@example
+@group
+something @{
+ foo; @hereFn{c-lineup-whitesmith-in-block}
+ @}
+@sssTBasicOffset{}
+@end group
+@end example
+
+In the first case the indentation is kept unchanged, in the second
+@code{c-basic-offset} is added.
+
+@workswith @code{defun-close}, @code{defun-block-intro},
+@code{inline-close}, @code{block-close}, @code{brace-list-close},
+@code{brace-list-intro}, @code{statement-block-intro},
+@code{arglist-intro}, @code{arglist-cont-nonempty},
+@code{arglist-close}, and all @code{in*} symbols, e.g. @code{inclass}
+and @code{inextern-lang}.
+@end defun
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions
+@comment node-name, next, previous, up
+@subsection List Line-Up Functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The line-up functions here calculate the indentation for lines which
+form lists of items, usually separated by commas.
+
+The function @ref{c-lineup-arglist-close-under-paren}, which is mainly
+for indenting a close parenthesis, is also useful for the lines
+contained within parentheses.
+
+@defun c-lineup-arglist
+@findex lineup-arglist (c-)
+Line up the current argument line under the first argument.
+
+As a special case, if an argument on the same line as the open
+parenthesis starts with a brace block opener, the indentation is
+@code{c-basic-offset} only. This is intended as a ``DWIM'' measure in
+cases like macros that contain statement blocks, e.g:
+
+@example
+@group
+A_VERY_LONG_MACRO_NAME (@{
+ some (code, with + long, lines * in[it]);
+ @});
+@sssTBasicOffset{}
+@end group
+@end example
+
+This is motivated partly because it's more in line with how code
+blocks are handled, and partly since it approximates the behavior of
+earlier CC Mode versions, which due to inaccurate analysis tended to
+indent such cases this way.
+
+@workswith @code{arglist-cont-nonempty}, @code{arglist-close}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-arglist-intro-after-paren
+@findex lineup-arglist-intro-after-paren (c-)
+Line up a line to just after the open paren of the surrounding paren or
+brace block.
+
+@workswith @code{defun-block-intro}, @code{brace-list-intro},
+@code{statement-block-intro}, @code{statement-case-intro},
+@code{arglist-intro}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-multi-inher
+@findex lineup-multi-inher (c-)
+Line up the classes in C++ multiple inheritance clauses and member
+initializers under each other. E.g:
+
+@example
+@group
+Foo::Foo (int a, int b):
+ Cyphr (a),
+ Bar (b) @hereFn{c-lineup-multi-inher}
+@end group
+@end example
+
+@noindent
+and
+
+@example
+@group
+class Foo
+ : public Cyphr,
+ public Bar @hereFn{c-lineup-multi-inher}
+@end group
+@end example
+
+@noindent
+and
+
+@example
+@group
+Foo::Foo (int a, int b)
+ : Cyphr (a)
+ , Bar (b) @hereFn{c-lineup-multi-inher}
+@end group
+@end example
+
+@workswith @code{inher-cont}, @code{member-init-cont}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-java-inher
+@findex lineup-java-inher (c-)
+Line up Java implements and extends declarations. If class names
+follow on the same line as the @samp{implements}/@samp{extends}
+keyword, they are lined up under each other. Otherwise, they are
+indented by adding @code{c-basic-offset} to the column of the keyword.
+E.g:
+
+@example
+@group
+class Foo
+ extends
+ Bar @hereFn{c-lineup-java-inher}
+ @sssTBasicOffset{}
+@end group
+@end example
+
+@noindent
+and
+
+@example
+@group
+class Foo
+ extends Cyphr,
+ Bar @hereFn{c-lineup-java-inher}
+@end group
+@end example
+
+@workswith @code{inher-cont}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-java-throws
+@findex lineup-java-throws (c-)
+Line up Java throws declarations. If exception names follow on the
+same line as the throws keyword, they are lined up under each other.
+Otherwise, they are indented by adding @code{c-basic-offset} to the
+column of the @samp{throws} keyword. The @samp{throws} keyword itself
+is also indented by @code{c-basic-offset} from the function declaration
+start if it doesn't hang. E.g:
+
+@example
+@group
+int foo()
+ throws @hereFn{c-lineup-java-throws}
+ Bar @hereFn{c-lineup-java-throws}
+@sssTsssTBasicOffset{}
+@end group
+@end example
+
+@noindent
+and
+
+@example
+@group
+int foo() throws Cyphr,
+ Bar, @hereFn{c-lineup-java-throws}
+ Vlod @hereFn{c-lineup-java-throws}
+@end group
+@end example
+
+@workswith @code{func-decl-cont}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-template-args
+@findex lineup-template-args (c-)
+Line up the arguments of a template argument list under each other, but
+only in the case where the first argument is on the same line as the
+opening @samp{<}.
+
+To allow this function to be used in a list expression, @code{nil} is
+returned if there's no template argument on the first line.
+
+@workswith @code{template-args-cont}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-ObjC-method-call
+@findex lineup-ObjC-method-call (c-)
+For Objective-C code, line up selector args as Emacs Lisp mode does
+with function args: go to the position right after the message receiver,
+and if you are at the end of the line, indent the current line
+c-basic-offset columns from the opening bracket; otherwise you are
+looking at the first character of the first method call argument, so
+lineup the current line with it.
+
+@workswith @code{objc-method-call-cont}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-ObjC-method-args
+@findex lineup-ObjC-method-args (c-)
+For Objective-C code, line up the colons that separate args. The colon
+on the current line is aligned with the one on the first line.
+
+@workswith @code{objc-method-args-cont}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-ObjC-method-args-2
+@findex lineup-ObjC-method-args-2 (c-)
+Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on
+the current line with the colon on the previous line.
+
+@workswith @code{objc-method-args-cont}.
+@end defun
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions
+@comment node-name, next, previous, up
+@subsection Operator Line-Up Functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The line-up functions here calculate the indentation for lines which
+start with an operator, by lining it up with something on the previous
+line.
+
+@defun c-lineup-argcont
+@findex lineup-argcont (c-)
+Line up a continued argument. E.g:
+
+@example
+@group
+foo (xyz, aaa + bbb + ccc
+ + ddd + eee + fff); @hereFn{c-lineup-argcont}
+@end group
+@end example
+
+Only continuation lines like this are touched, @code{nil} is returned on
+lines which are the start of an argument.
+
+Within a gcc @code{asm} block, @code{:} is recognised as an argument
+separator, but of course only between operand specifications, not in the
+expressions for the operands.
+
+@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-arglist-operators
+@findex lineup-arglist-operators (c-)
+Line up lines starting with an infix operator under the open paren.
+Return @code{nil} on lines that don't start with an operator, to leave
+those cases to other line-up functions. Example:
+
+@example
+@group
+if ( x < 10
+ || at_limit (x, @hereFn{c-lineup-arglist-operators}
+ list) @hereFn{c-lineup-arglist-operators@r{ returns nil}}
+ )
+@end group
+@end example
+
+Since this function doesn't do anything for lines without an infix
+operator you typically want to use it together with some other lineup
+settings, e.g. as follows (the @code{arglist-close} setting is just a
+suggestion to get a consistent style):
+
+@example
+(c-set-offset 'arglist-cont
+ '(c-lineup-arglist-operators 0))
+(c-set-offset 'arglist-cont-nonempty
+ '(c-lineup-arglist-operators c-lineup-arglist))
+(c-set-offset 'arglist-close
+ '(c-lineup-arglist-close-under-paren))
+@end example
+
+@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-assignments
+@findex lineup-assignments (c-)
+Line up the current line after the assignment operator on the first line
+in the statement. If there isn't any, return nil to allow stacking with
+other line-up functions. If the current line contains an assignment
+operator too, try to align it with the first one.
+
+@workswith @code{topmost-intro-cont}, @code{statement-cont},
+@code{arglist-cont}, @code{arglist-cont-nonempty}.
+
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-math
+@findex lineup-math (c-)
+Like @code{c-lineup-assignments} but indent with @code{c-basic-offset}
+if no assignment operator was found on the first line. I.e. this
+function is the same as specifying a list @code{(c-lineup-assignments
++)}. It's provided for compatibility with old configurations.
+
+@workswith @code{topmost-intro-cont}, @code{statement-cont},
+@code{arglist-cont}, @code{arglist-cont-nonempty}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-cascaded-calls
+@findex lineup-cascaded-calls (c-)
+Line up ``cascaded calls'' under each other. If the line begins with
+@code{->} or @code{.} and the preceding line ends with one or more
+function calls preceded by the same token, then the arrow is lined up
+with the first of those tokens. E.g:
+
+@example
+@group
+r = proc->add(17)->add(18)
+ ->add(19) + @hereFn{c-lineup-cascaded-calls}
+ offset; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}}
+@end group
+@end example
+
+In any other situation @code{nil} is returned to allow use in list
+expressions.
+
+@workswith @code{topmost-intro-cont}, @code{statement-cont},
+@code{arglist-cont}, @code{arglist-cont-nonempty}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-streamop
+@findex lineup-streamop (c-)
+Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}).
+
+@workswith @code{stream-op}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-string-cont
+@findex lineup-string-cont (c-)
+Line up a continued string under the one it continues. A continued
+string in this sense is where a string literal follows directly after
+another one. E.g:
+
+@example
+@group
+result = prefix + "A message "
+ "string."; @hereFn{c-lineup-string-cont}
+@end group
+@end example
+
+@code{nil} is returned in other situations, to allow stacking with other
+lineup functions.
+
+@workswith @code{topmost-intro-cont}, @code{statement-cont},
+@code{arglist-cont}, @code{arglist-cont-nonempty}.
+@end defun
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions
+@comment node-name, next, previous, up
+@subsection Comment Line-Up Functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The lineup functions here calculate the indentation for several types
+of comment structure.
+
+@defun c-lineup-C-comments
+@findex lineup-C-comments (c-)
+Line up C block comment continuation lines. Various heuristics are used
+to handle most of the common comment styles. Some examples:
+
+@example
+@group
+/* /** /*
+ * text * text text
+ */ */ */
+@end group
+@end example
+
+@example
+@group
+/* text /* /**
+ text ** text ** text
+*/ */ */
+@end group
+@end example
+
+@example
+@group
+/**************************************************
+ * text
+ *************************************************/
+@end group
+@end example
+
+@vindex comment-start-skip
+@example
+@group
+/**************************************************
+ Free form text comments:
+ In comments with a long delimiter line at the
+ start, the indentation is kept unchanged for lines
+ that start with an empty comment line prefix. The
+ delimiter line is whatever matches the
+ @code{comment-start-skip} regexp.
+**************************************************/
+@end group
+@end example
+
+The style variable @code{c-comment-prefix-regexp} is used to recognize
+the comment line prefix, e.g. the @samp{*} that usually starts every
+line inside a comment.
+
+@workswith The @code{c} syntactic symbol.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-comment
+@findex lineup-comment (c-)
+Line up a comment-only line according to the style variable
+@code{c-comment-only-line-offset}. If the comment is lined up with a
+comment starter on the previous line, that alignment is preserved.
+
+@defopt c-comment-only-line-offset
+@vindex comment-only-line-offset (c-)
+This style variable specifies the extra offset for the line. It can
+contain an integer or a cons cell of the form
+
+@example
+(@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}})
+@end example
+
+@noindent
+where @var{non-anchored-offset} is the amount of offset given to
+non-column-zero anchored lines, and @var{anchored-offset} is the amount
+of offset to give column-zero anchored lines. Just an integer as value
+is equivalent to @code{(@r{@var{value}} . -1000)}.
+@end defopt
+
+@workswith @code{comment-intro}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-knr-region-comment
+@findex lineup-knr-region-comment (c-)
+Line up a comment in the ``K&R region'' with the declaration. That is
+the region between the function or class header and the beginning of the
+block. E.g:
+
+@example
+@group
+int main()
+/* Called at startup. */ @hereFn{c-lineup-knr-region-comment}
+@{
+ return 0;
+@}
+@end group
+@end example
+
+Return @code{nil} if called in any other situation, to be useful in list
+expressions.
+
+@workswith @code{comment-intro}.
+@end defun
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Misc Line-Up, , Comment Line-Up, Line-Up Functions
+@comment node-name, next, previous, up
+@subsection Miscellaneous Line-Up Functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The line-up functions here are the odds and ends which didn't fit into
+any earlier category.
+
+@defun c-lineup-dont-change
+@findex lineup-dont-change (c-)
+This lineup function makes the line stay at whatever indentation it
+already has; think of it as an identity function for lineups.
+
+@workswith Any syntactic symbol.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-cpp-define
+@findex lineup-cpp-define (c-)
+Line up macro continuation lines according to the indentation of the
+construct preceding the macro. E.g:
+
+@example
+@group
+const char msg[] = @hereFn{@r{The beginning of the preceding construct.}}
+ \"Some text.\";
+
+#define X(A, B) \
+do @{ \ @hereFn{c-lineup-cpp-define}
+ printf (A, B); \
+@} while (0)
+@end group
+@end example
+
+@noindent
+and:
+
+@example
+@group
+int dribble() @{
+ if (!running) @hereFn{@r{The beginning of the preceding construct.}}
+ error(\"Not running!\");
+
+#define X(A, B) \
+ do @{ \ @hereFn{c-lineup-cpp-define}
+ printf (A, B); \
+ @} while (0)
+@end group
+@end example
+
+If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the
+function returns the relative indentation to the macro start line to
+allow accumulation with other offsets. E.g. in the following cases,
+@code{cpp-define-intro} is combined with the
+@code{statement-block-intro} that comes from the @samp{do @{} that hangs
+on the @samp{#define} line:
+
+@example
+@group
+const char msg[] =
+ \"Some text.\";
+
+#define X(A, B) do @{ \
+ printf (A, B); \ @hereFn{c-lineup-cpp-define}
+ this->refs++; \
+@} while (0) @hereFn{c-lineup-cpp-define}
+@end group
+@end example
+
+@noindent
+and:
+
+@example
+@group
+int dribble() @{
+ if (!running)
+ error(\"Not running!\");
+
+#define X(A, B) do @{ \
+ printf (A, B); \ @hereFn{c-lineup-cpp-define}
+ this->refs++; \
+ @} while (0) @hereFn{c-lineup-cpp-define}
+@end group
+@end example
+
+The relative indentation returned by @code{c-lineup-cpp-define} is zero
+and two, respectively, on the two lines in each of these examples. They
+are then added to the two column indentation that
+@code{statement-block-intro} gives in both cases here.
+
+If the relative indentation is zero, then @code{nil} is returned
+instead. That is useful in a list expression to specify the default
+indentation on the top level.
+
+If @code{c-syntactic-indentation-in-macros} is @code{nil} then this
+function keeps the current indentation, except for empty lines (ignoring
+the ending backslash) where it takes the indentation from the closest
+preceding nonempty line in the macro. If there's no such line in the
+macro then the indentation is taken from the construct preceding it, as
+described above.
+
+@workswith @code{cpp-define-intro}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-gcc-asm-reg
+@findex lineup-gcc-asm-reg (c-)
+Line up a gcc asm register under one on a previous line.
+
+@example
+@group
+ asm ("foo %1, %0\n"
+ "bar %0, %1"
+ : "=r" (w),
+ "=r" (x)
+ : "0" (y),
+ "1" (z));
+@end group
+@end example
+
+The @samp{x} line is aligned to the text after the @samp{:} on the
+@samp{w} line, and similarly @samp{z} under @samp{y}.
+
+This is done only in an @samp{asm} or @samp{__asm__} block, and only to
+those lines mentioned. Anywhere else @code{nil} is returned. The usual
+arrangement is to have this routine as an extra feature at the start of
+arglist lineups, e.g.
+
+@example
+(c-lineup-gcc-asm-reg c-lineup-arglist)
+@end example
+
+@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-topmost-intro-cont
+@findex lineup-topmost-intro-cont (c-)
+Line up declaration continuation lines zero or one indentation
+step@footnote{This function is mainly provided to mimic the behavior of
+CC Mode 5.28 and earlier where this case wasn't handled consistently so
+that those lines could be analyzed as either topmost-intro-cont or
+statement-cont. It's used for @code{topmost-intro-cont} by default, but
+you might consider using @code{+} instead.}. For lines preceding a
+definition, zero is used. For other lines, @code{c-basic-offset} is
+added to the indentation. E.g:
+
+@example
+@group
+int
+neg (int i) @hereFn{c-lineup-topmost-intro-cont}
+@{
+ return -i;
+@}
+@end group
+@end example
+
+@noindent
+and
+
+@example
+@group
+struct
+larch @hereFn{c-lineup-topmost-intro-cont}
+@{
+ double height;
+@}
+ the_larch, @hereFn{c-lineup-topmost-intro-cont}
+ another_larch; @hereFn{c-lineup-topmost-intro-cont}
+@sssTBasicOffset{}
+@end group
+@end example
+
+@noindent
+and
+
+@example
+@group
+struct larch
+the_larch, @hereFn{c-lineup-topmost-intro-cont}
+ another_larch; @hereFn{c-lineup-topmost-intro-cont}
+@end group
+@end example
+
+@workswith @code{topmost-intro-cont}.
+@end defun
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation
+@comment node-name, next, previous, up
+@section Custom Line-Up Functions
+@cindex customization, indentation functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The most flexible way to customize indentation is by writing custom
+line-up functions, and associating them with specific syntactic
+symbols (@pxref{c-offsets-alist}). Depending on the effect you want,
+it might be better to write a @code{c-special-indent-hook} function
+rather than a line-up function (@pxref{Other Indentation}).
+
+@ccmode{} comes with an extensive set of predefined line-up functions,
+not all of which are used by the default styles. So there's a good
+chance the function you want already exists. @xref{Line-Up
+Functions}, for a list of them. If you write your own line-up
+function, it's probably a good idea to start working from one of these
+predefined functions, which can be found in the file
+@file{cc-align.el}. If you have written a line-up function that you
+think is generally useful, you're very welcome to contribute it;
+please contact @email{bug-cc-mode@@gnu.org}.
+
+ Line-up functions are passed a single argument, the syntactic
+element (see below). The return value is a @code{c-offsets-alist}
+offset specification: for example, an integer, a symbol such as
+@code{+}, a vector, @code{nil}@footnote{Returning @code{nil} is useful
+when the offset specification for a syntactic element is a list
+containing the line-up function (@pxref{c-offsets-alist}).}, or even
+another line-up function. Full details of these are in
+@ref{c-offsets-alist}.
+
+Line-up functions must not move point or change the content of the
+buffer (except temporarily). They are however allowed to do
+@dfn{hidden buffer changes}, i.e. setting text properties for caching
+purposes etc. Buffer undo recording is disabled while they run.
+
+The syntactic element passed as the parameter to a line-up function is
+a cons cell of the form
+
+@example
+(@r{@var{syntactic-symbol}} . @r{@var{anchor-position}})
+@end example
+
+@noindent
+@c FIXME!!! The following sentence might be better omitted, since the
+@c information is in the cross reference "Syntactic Analysis". 2005/10/2.
+where @var{syntactic-symbol} is the symbol that the function was
+called for, and @var{anchor-position} is the anchor position (if any)
+for the construct that triggered the syntactic symbol
+(@pxref{Syntactic Analysis}). This cons cell is how the syntactic
+element of a line used to be represented in @ccmode{} 5.28 and
+earlier. Line-up functions are still passed this cons cell, so as to
+preserve compatibility with older configurations. In the future, we
+may decide to convert to using the full list format---you can prepare
+your setup for this by using the access functions
+(@code{c-langelem-sym}, etc.) described below.
+
+@vindex c-syntactic-element
+@vindex syntactic-element (c-)
+@vindex c-syntactic-context
+@vindex syntactic-context (c-)
+Some syntactic symbols, e.g. @code{arglist-cont-nonempty}, have more
+info in the syntactic element - typically other positions that can be
+interesting besides the anchor position. That info can't be accessed
+through the passed argument, which is a cons cell. Instead, you can
+get this information from the variable @code{c-syntactic-element},
+which is dynamically bound to the complete syntactic element. The
+variable @code{c-syntactic-context} might also be useful - it gets
+dynamically bound to the complete syntactic context. @xref{Custom
+Braces}.
+
+@ccmode{} provides a few functions to access parts of syntactic
+elements in a more abstract way. Besides making the code easier to
+read, they also hide the difference between the old cons cell form
+used in the line-up function argument and the new list form used in
+@code{c-syntactic-element} and everywhere else. The functions are:
+
+@defun c-langelem-sym langelem
+@findex langelem-sym (c-)
+Return the syntactic symbol in @var{langelem}.
+@end defun
+
+@defun c-langelem-pos langelem
+@findex langelem-pos (c-)
+Return the anchor position in @var{langelem}, or nil if there is none.
+@end defun
+
+@defun c-langelem-col langelem &optional preserve-point
+@findex langelem-col (c-)
+Return the column of the anchor position in @var{langelem}. Also move
+the point to that position unless @var{preserve-point} is
+non-@code{nil}.
+@end defun
+
+@defun c-langelem-2nd-pos langelem
+@findex langelem-2nd-pos (c-)
+Return the secondary position in @var{langelem}, or @code{nil} if there
+is none.
+
+Note that the return value of this function is always @code{nil} if
+@var{langelem} is in the old cons cell form. Thus this function is
+only meaningful when used on syntactic elements taken from
+@code{c-syntactic-element} or @code{c-syntactic-context}.
+@end defun
+
+Custom line-up 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 line-up function associated with it.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Other Indentation, , Custom Line-Up, Customizing Indentation
+@comment node-name, next, previous, up
+@section Other Special Indentations
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Here are the remaining odds and ends regarding indentation:
+
+@defopt c-label-minimum-indentation
+@vindex label-minimum-indentation (c-)
+In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is
+imposed on lines inside code blocks. This minimum indentation is
+controlled by this style variable. The default value is 1.
+
+@findex c-gnu-impose-minimum
+@findex gnu-impose-minimum (c-)
+It's the function @code{c-gnu-impose-minimum} that enforces this minimum
+indentation. It must be present on @code{c-special-indent-hook} to
+work.
+@end defopt
+
+@defopt c-special-indent-hook
+@vindex special-indent-hook (c-)
+This style variable is a standard hook variable that is called after
+every line is indented by @ccmode{}. It is called only if
+@code{c-syntactic-indentation} is non-@code{nil} (which it is by
+default (@pxref{Indentation Engine Basics})). You can put a function
+on this hook to do any special indentation or ad hoc line adjustments
+your style dictates, such as adding extra indentation to constructors
+or destructor declarations in a class definition, etc. Sometimes it
+is better to write a custom Line-up Function instead (@pxref{Custom
+Line-Up}).
+
+When the indentation engine calls this hook, the variable
+@code{c-syntactic-context} is bound to the current syntactic context
+(i.e. what you would get by typing @kbd{C-c C-s} on the source line.
+@xref{Custom Braces}.). Note that you should not change point or mark
+inside a @code{c-special-indent-hook} function, i.e. you'll probably
+want to wrap your function in a @code{save-excursion}@footnote{The
+numerical value returned by @code{point} will change if you change the
+indentation of the line within a @code{save-excursion} form, but point
+itself will still be over the same piece of text.}.
+
+Setting @code{c-special-indent-hook} in style definitions is handled
+slightly differently from other variables---A style can only add
+functions to this hook, not remove them. @xref{Style Variables}.
+@end defopt
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Custom Macros, Odds and Ends, Customizing Indentation, Top
+@comment node-name, next, previous, up
+@chapter Customizing Macros
+@cindex macros
+@cindex preprocessor directives
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Normally, the lines in a multi-line macro are indented relative to
+each other as though they were code. You can suppress this behaviour
+by setting the following user option:
+
+@defopt c-syntactic-indentation-in-macros
+@vindex syntactic-indentation-in-macros (c-)
+Enable syntactic analysis inside macros, which is the default. If this
+is @code{nil}, all lines inside macro definitions are analyzed as
+@code{cpp-macro-cont}.
+@end defopt
+
+@ccmode{} provides some tools to help keep the line continuation
+backslashes in macros neat and tidy. Their precise action is
+customized with these variables:
+
+@defopt c-backslash-column
+@vindex backslash-column (c-)
+@defoptx c-backslash-max-column
+@vindex backslash-max-column (c-)
+These variables control the alignment columns for line continuation
+backslashes in multiline macros. They are used by the functions that
+automatically insert or align such backslashes,
+e.g. @code{c-backslash-region} and @code{c-context-line-break}.
+
+@code{c-backslash-column} specifies the minimum column for the
+backslashes. If any line in the macro goes past this column, then the
+next tab stop (i.e. next multiple of @code{tab-width}) in that line is
+used as the alignment column for all the backslashes, so that they
+remain in a single column. However, if any lines go past
+@code{c-backslash-max-column} then the backslashes in the rest of the
+macro will be kept at that column, so that the lines which are too
+long ``stick out'' instead.
+
+Don't ever set these variables to @code{nil}. If you want to disable
+the automatic alignment of backslashes, use
+@code{c-auto-align-backslashes}.
+@end defopt
+
+@defopt c-auto-align-backslashes
+@vindex auto-align-backslashes (c-)
+Align automatically inserted line continuation backslashes if
+non-@code{nil}. When line continuation backslashes are inserted
+automatically for line breaks in multiline macros, e.g. by
+@code{c-context-line-break}, they are aligned with the other
+backslashes in the same macro if this flag is set.
+
+If @code{c-auto-align-backslashes} is @code{nil}, automatically
+inserted backslashes are preceded by a single space, and backslashes
+get aligned only when you explicitly invoke the command
+@code{c-backslash-region} (@kbd{C-c C-\}).
+@end defopt
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Odds and Ends, Sample .emacs File, Custom Macros, Top
+@comment node-name, next, previous, up
+@chapter Odds and Ends
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The stuff that didn't fit in anywhere else is documented here.
+
+@defopt c-require-final-newline
+@vindex require-final-newline (c-)
+Controls whether a final newline is enforced when the file is saved.
+The value is an association list that for each language mode specifies
+the value to give to @code{require-final-newline} (@pxref{Saving
+Buffers,,, @lispref{}, @lispreftitle{}}) at mode initialization. If a
+language isn't present on the association list, CC Mode won't touch
+@code{require-final-newline} in buffers for that language.
+
+The default is to set @code{require-final-newline} to @code{t} in the
+languages that mandate that source files should end with newlines.
+These are C, C++ and Objective-C.
+@end defopt
+
+@defopt c-echo-syntactic-information-p
+@vindex echo-syntactic-information-p (c-)
+If non-@code{nil}, the syntactic analysis for the current line is shown
+in the echo area when it's indented (unless
+@code{c-syntactic-indentation} is @code{nil}). That's useful when
+finding out which syntactic symbols to modify to get the indentation you
+want.
+@end defopt
+
+@defopt c-report-syntactic-errors
+@vindex report-syntactic-errors (c-)
+If non-@code{nil}, certain syntactic errors are reported with a ding and
+a message, for example when an @code{else} is indented for which there
+is no corresponding @code{if}.
+
+Note however that @ccmode{} doesn't make any special effort to check for
+syntactic errors; that's the job of the compiler. The reason it can
+report cases like the one above is that it can't find the correct
+anchoring position to indent the line in that case.
+@end defopt
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Sample .emacs File, Performance Issues, Odds and Ends, Top
+@comment node-name, next, previous, up
+@appendix Sample .emacs File
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Here's a sample .emacs file fragment that might help you along the way.
+Just copy this region and paste it into your .emacs file. You might want
+to change some of the actual values.
+
+@verbatim
+;; Make a non-standard key binding. We can put this in
+;; c-mode-base-map because c-mode-map, c++-mode-map, and so on,
+;; inherit from it.
+(defun my-c-initialization-hook ()
+ (define-key c-mode-base-map "\C-m" 'c-context-line-break))
+(add-hook 'c-initialization-hook 'my-c-initialization-hook)
+
+;; offset customizations not in my-c-style
+;; This will take precedence over any setting of the syntactic symbol
+;; made by a style.
+(setq c-offsets-alist '((member-init-intro . ++)))
+
+;; Create my personal style.
+(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")
+(c-add-style "PERSONAL" my-c-style)
+
+;; Customizations for all modes in CC Mode.
+(defun my-c-mode-common-hook ()
+ ;; set my personal style for the current buffer
+ (c-set-style "PERSONAL")
+ ;; other customizations
+ (setq tab-width 8
+ ;; this will make sure spaces are used instead of tabs
+ indent-tabs-mode nil)
+ ;; we like auto-newline, but not hungry-delete
+ (c-toggle-auto-newline 1))
+(add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
+@end verbatim
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Performance Issues, Limitations and Known Bugs, Sample .emacs File, Top
+@comment node-name, next, previous, up
+@chapter Performance Issues
+@cindex performance
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here.
+
+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 can cause @ccmode{} to perform fairly badly. This
+section gives some insight in how @ccmode{} operates, how that interacts
+with some coding styles, and what you can use to improve performance.
+
+The overall goal is that @ccmode{} shouldn't be overly slow (i.e. take
+more than a fraction of a second) in any interactive operation.
+I.e. it's tuned to limit the maximum response time in single operations,
+which is sometimes at the expense of batch-like operations like
+reindenting whole blocks. If you find that @ccmode{} gradually gets
+slower and slower in certain situations, perhaps as the file grows in
+size or as the macro or comment you're editing gets bigger, then chances
+are that something isn't working right. You should consider reporting
+it, unless it's something that's mentioned in this section.
+
+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
+(it's typically an opening or closing parenthesis of some kind). The
+farther this position is from the current insertion point, the slower it
+gets.
+
+@findex beginning-of-defun
+In earlier versions of @ccmode{}, we used to recommend putting the
+opening brace of a top-level construct@footnote{E.g. a function in C,
+or outermost class definition in C++ or Java.} into the leftmost
+column. Earlier still, this used to be a rigid Emacs constraint, as
+embodied in the @code{beginning-of-defun} function. @ccmode now
+caches syntactic information much better, so that the delay caused by
+searching for such a brace when it's not in column 0 is minimal,
+except perhaps when you've just moved a long way inside the file.
+
+@findex defun-prompt-regexp
+@vindex c-Java-defun-prompt-regexp
+@vindex Java-defun-prompt-regexp (c-)
+A special note about @code{defun-prompt-regexp} in Java mode: The common
+style is to hang the opening braces of functions and classes on the
+right side of the line, and that doesn't work well with the Emacs
+approach. @ccmode{} comes with a constant
+@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 relying on @code{defun-prompt-regexp} will definitely slow
+things down because (X)Emacs will be doing regular expression searches a
+lot, so you'll probably be taking a hit either way!
+
+@ccmode{} maintains a cache of the opening parentheses of the blocks
+surrounding the point, and it adapts that cache as the point is moved
+around. That means that in bad cases it can take noticeable time to
+indent a line in a new surrounding, but after that it gets fast as long
+as the point isn't moved far off. The farther the point is moved, the
+less useful is the cache. Since editing typically is done in ``chunks''
+rather than on single lines far apart from each other, the cache
+typically gives good performance even when the code doesn't fit the
+Emacs approach to finding the defun starts.
+
+@vindex c-enable-xemacs-performance-kludge-p
+@vindex enable-xemacs-performance-kludge-p (c-)
+XEmacs users can set the variable
+@code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This
+tells @ccmode{} to use XEmacs-specific built-in functions which, in some
+circumstances, can locate the top-most opening brace much more quickly than
+@code{beginning-of-defun}. Preliminary testing has shown that for
+styles where these braces are hung (e.g. most JDK-derived Java styles),
+this hack can improve performance of the core syntax parsing routines
+from 3 to 60 times. However, for styles which @emph{do} conform to
+Emacs' recommended style of putting top-level braces in column zero,
+this hack can degrade performance by about as much. Thus this variable
+is set to @code{nil} by default, since the Emacs-friendly styles should
+be more common (and encouraged!). Note that this variable has no effect
+in Emacs since the necessary built-in functions don't exist (in Emacs
+22.1 as of this writing in February 2007).
+
+Text properties are used to speed up skipping over syntactic whitespace,
+i.e. comments and preprocessor directives. Indenting a line after a
+huge macro definition can be slow the first time, but after that the
+text properties are in place and it should be fast (even after you've
+edited other parts of the file and then moved back).
+
+Font locking can be a CPU hog, especially the font locking done on
+decoration level 3 which tries to be very accurate. Note that that
+level is designed to be used with a font lock support mode that only
+fontifies the text that's actually shown, i.e. Lazy Lock or Just-in-time
+Lock mode, so make sure you use one of them. Fontification of a whole
+buffer with some thousand lines can often take over a minute. That is
+a known weakness; the idea is that it never should happen.
+
+The most effective way to speed up font locking is to reduce the
+decoration level to 2 by setting @code{font-lock-maximum-decoration}
+appropriately. That level is designed to be as pretty as possible
+without sacrificing performance. @xref{Font Locking Preliminaries}, for
+more info.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Limitations and Known Bugs, FAQ, Performance Issues, Top
+@comment node-name, next, previous, up
+@chapter Limitations and Known Bugs
+@cindex limitations
+@cindex bugs
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@itemize @bullet
+@item
+@ccmode{} doesn't support trigraphs. (These are character sequences
+such as @samp{??(}, which represents @samp{[}. They date from a time
+when some character sets didn't have all the characters that C needs,
+and are now utterly obsolete.)
+
+@item
+There is no way to apply auto newline settings (@pxref{Auto-newlines})
+on already typed lines. That's only a feature to ease interactive
+editing.
+
+To generalize this issue a bit: @ccmode{} is not intended to be used as
+a reformatter for old code in some more or less batch-like way. With
+the exception of some functions like @code{c-indent-region}, it's only
+geared to be used interactively to edit new code. There's currently no
+intention to change this goal.
+
+If you want to reformat old code, you're probably better off using some
+other tool instead, e.g. @ref{Top, , GNU indent, indent, The `indent'
+Manual}, which has more powerful reformatting capabilities than
+@ccmode{}.
+
+@item
+The support for C++ templates (in angle brackets) is not yet complete.
+When a non-nested template is used in a declaration, @ccmode{} indents
+it and font-locks it OK. Templates used in expressions, and nested
+templates do not fare so well. Sometimes a workaround is to refontify
+the expression after typing the closing @samp{>}.
+
+@item
+On loading @ccmode{}, sometimes this error message appears:
+
+@example
+File mode specification error: (void-variable c-font-lock-keywords-3)
+@end example
+
+This is due to a bug in the function @code{eval-after-load} in some
+versions of (X)Emacs. It can manifest itself when there is a symbolic
+link in the path of the directory which contains (X)Emacs. As a
+workaround, put the following into your @file{.emacs} file, fairly
+early on:
+
+@example
+(defun my-load-cc-fonts ()
+ (require "cc-fonts"))
+(add-hook 'c-initialization-hook 'my-load-cc-fonts)
+@end example
+@end itemize
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node FAQ, Updating CC Mode, Limitations and Known Bugs, Top
+@comment node-name, next, previous, up
+@appendix Frequently Asked Questions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@itemize @bullet
+@item
+@emph{How can I change the indent level from 4 spaces to 2 spaces?}
+
+Set the variable @code{c-basic-offset}. @xref{Getting Started}.
+
+@item
+@kindex RET
+@kindex C-j
+@emph{Why doesn't the @kbd{RET} key indent the new line?}
+
+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-initialization-hook}:
+
+@example
+(define-key c-mode-base-map "\C-m" 'c-context-line-break)
+@end example
+
+@xref{Getting Started}. This is a very common question. If you want
+this to be the default behavior, don't lobby us, lobby RMS! @t{:-)}
+
+@item
+@emph{How do I stop my code jumping all over the place when I type?}
+
+Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting
+Started}.
+
+@item
+@kindex C-x h
+@kindex C-M-\
+@emph{How do I reindent the whole file?}
+
+Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit
+@kbd{C-M-\}. @xref{Indentation Commands}.
+
+@item
+@kindex C-M-q
+@kindex C-M-u
+@emph{How do I reindent the current block?}
+
+First move to the brace which opens the block with @kbd{C-M-u}, then
+reindent that expression with @kbd{C-M-q}. @xref{Indentation
+Commands}.
+
+@item
+@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. What's wrong?}
+
+This means that @ccmode{} hasn't yet been loaded into your Emacs
+session by the time the @code{c-set-offset} call is reached, most
+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-initialization-hook} (@pxref{CC Hooks}), or simply
+modify @code{c-offsets-alist} directly:
+
+@example
+(setq c-offsets-alist '((substatement-open . 0)))
+@end example
+
+@item
+@cindex open paren in column zero
+@emph{I have an open paren character at column zero inside a comment or
+multiline string literal, and it causes the fontification and/or
+indentation to go haywire. What gives?}
+
+It's due to the ad-hoc rule in (X)Emacs that such open parens always
+start defuns (which translates to functions, classes, namespaces or any
+other top-level block constructs in the @ccmode{} languages).
+@ifset XEMACS
+@xref{Defuns,,, xemacs, XEmacs User's Manual}, for details.
+@end ifset
+@ifclear XEMACS
+@xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details
+(@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual).
+@end ifclear
+
+This heuristic is built into the core syntax analysis routines in
+(X)Emacs, so it's not really a @ccmode{} issue. However, in Emacs
+21.1 it became possible to turn it off@footnote{Using the variable
+@code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so
+there since it's got its own system to keep track of blocks.
+
+@end itemize
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top
+@comment node-name, next, previous, up
+@appendix Getting the Latest CC Mode Release
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ccmode{} has been standard with all versions of Emacs since 19.34 and
+of XEmacs since 19.16.
+
+@cindex web site
+Due to release schedule skew, it is likely that all of these Emacsen
+have old versions of @ccmode{} and so should be upgraded. Access to the
+@ccmode{} source code, as well as more detailed information on Emacsen
+compatibility, etc. are all available on the web site:
+
+@quotation
+@uref{http://cc-mode.sourceforge.net/}
+@end quotation
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Mailing Lists and Bug Reports, GNU Free Documentation License, Updating CC Mode, Top
+@comment node-name, next, previous, up
+@appendix Mailing Lists and Submitting Bug Reports
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@kindex C-c C-b
+@findex c-submit-bug-report
+@findex submit-bug-report (c-)
+To report bugs, use the @kbd{C-c C-b} (bound to
+@code{c-submit-bug-report}) command. This provides vital information
+we 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 our ability to reproduce it.
+
+Please try to produce the problem in an Emacs instance without any
+customizations loaded (i.e. start it with the @samp{-q --no-site-file}
+arguments). If it works correctly there, the problem might be caused
+by faulty customizations in either your own or your site
+configuration. In that case, we'd appreciate it if you isolate the
+Emacs Lisp code that triggers the bug and include it in your report.
+
+@cindex bug report mailing list
+Bug reports should be sent to @email{bug-cc-mode@@gnu.org}. You can
+also send other questions and suggestions (kudos? @t{;-)} to that
+address. It's a mailing list which you can join or browse an archive
+of; see the web site at @uref{http://cc-mode.sourceforge.net/} for
+further details.
+
+@cindex announcement mailing list
+If you want to get announcements of new @ccmode{} releases, send the
+word @emph{subscribe} in the body of a message to
+@email{cc-mode-announce-request@@lists.sourceforge.net}. It's possible
+to subscribe from the web site too. Announcements will also be posted
+to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs},
+@code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++},
+@code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools},
+@code{comp.lang.idl}, and @code{comp.lang.awk}.
+@c There is no newsgroup for Pike. :-(
+
+
+@node GNU Free Documentation License, Command and Function Index, Mailing Lists and Bug Reports, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+
+@c Removed the tentative node "Mode Initialization" from here, 2005/8/27.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Command and Function Index, Variable Index, GNU Free Documentation License, Top
+@comment node-name, next, previous, up
+@unnumbered Command and Function Index
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Since most @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
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Variable Index, Concept and Key Index, Command and Function Index, Top
+@comment node-name, next, previous, up
+@unnumbered Variable Index
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Since most @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
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Concept and Key Index, , Variable Index, Top
+@comment node-name, next, previous, up
+@unnumbered Concept and Key Index
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@printindex cp
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment Epilogue.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@iftex
+@page
+@summarycontents
+@contents
+@end iftex
+
+@bye
+
+@ignore
+ arch-tag: c4cab162-5e57-4366-bdce-4a9db2fc97f0
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@setfilename ../info/cl
+@settitle Common Lisp Extensions
+
+@copying
+This file documents the GNU Emacs Common Lisp emulation package.
+
+Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, 2005, 2006, 2007
+Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* CL: (cl). Partial Common Lisp support for Emacs Lisp.
+@end direntry
+
+@finalout
+
+@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
+@insertcopying
+@end titlepage
+
+@node Top, Overview, (dir), (dir)
+@chapter Introduction
+
+@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.
+* 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
+
+* GNU Free Documentation License:: The license for this documentation.
+* Function Index::
+* Variable Index::
+@end menu
+
+@node Overview, Program Structure, Top, Top
+@ifnottex
+@chapter Overview
+@end ifnottex
+
+@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.
+
+@strong{Please note:} the @dfn{CL} functions are not standard parts of
+the Emacs Lisp name space, so it is legitimate for users to define
+them with other, conflicting meanings. To avoid conflicting with
+those user activities, we have a policy that packages installed in
+Emacs must not load @dfn{CL} at run time. (It is ok for them to load
+@dfn{CL} at compile time only, with @code{eval-when-compile}, and use
+the macros it provides.) If you are writing packages that you plan to
+distribute and invite widespread use for, you might want to observe
+the same rule.
+
+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
+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 @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*
+@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
+floatp-safe lexical-let lexical-let*
+callf callf2 letf letf*
+defsubst*
+@end example
+
+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 endp
+evenp oddp plusp minusp
+caaar .. cddddr
+list* ldiff rest first .. tenth
+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
+[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.
+@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;
+@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.
+
+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, , 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 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.
+
+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 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{atom} represents all objects that are not cons
+cells. Thus @code{(typep @var{object} 'atom)} is equivalent to
+@code{(atom @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. 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.
+@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 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.
+
+@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 valid 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 (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,
+the optimizing byte compiler 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. Unlike with Emacs's built in @code{dolist}, 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. Unlike with Emacs's built in
+@code{dolist}, 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 valid 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} valid 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}.
+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
+vectors. 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 ``overlays'' of a buffer
+(the clause @code{extents} is synonymous
+with @code{overlays}). 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.
+
+@item for @var{var} being the frames
+This clause iterates over all frames, i.e., X window system windows
+open on Emacs files. 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}.
+
+@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 valid 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 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.
+
+@example
+(declaim (inline foo bar))
+(eval-when (compile load eval) (proclaim '(inline foo bar)))
+(defsubst foo (...) ...) ; instead of defun
+@end example
+
+@strong{Please 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 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 valid to use @code{getf} as a @code{setf} place, in which case
+its @var{place} argument must itself be a valid @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', `floor*', etc.
+* Random Numbers:: `random*', `make-random-state'
+* Implementation Parameters:: `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 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.
+
+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 a 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 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 valid 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.
+
+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, 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 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. This function is more general than the Emacs
+primitive @code{mapc}.
+@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 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. It should only be a
+simple accessor though, it's used heavily in the current
+implementation.
+
+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, Structures, Sequences, Top
+@chapter Lists
+
+@noindent
+The functions described here operate on lists.
+
+@menu
+* List Functions:: `caddr', `first', `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 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 @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.
+(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
+
+@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
+
+@iftex
+@chapno=18
+@end iftex
+
+@node Structures, Assertions, Lists, 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 valid 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.
+
+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
+Use of the optimizing Emacs compiler 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).
+
+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. The older package simply
+redefined these functions, overwriting the built-in meanings and
+causing serious portability problems. (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 built-ins.
+
+@node Porting Common Lisp, GNU Free Documentation License, 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 to 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 (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 has 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 GNU Free Documentation License, Function Index, Porting Common Lisp, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Function Index, Variable Index, GNU Free Documentation License, Top
+@unnumbered Function Index
+
+@printindex fn
+
+@node Variable Index, , Function Index, Top
+@unnumbered Variable Index
+
+@printindex vr
+
+@setchapternewpage odd
+@contents
+@bye
+
+@ignore
+ arch-tag: b61e7200-3bfa-4a70-a9d3-095e152696f8
+@end ignore
--- /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 [Dodd's address no longer valid.]
+@c Version: 2.53
+@c Date: 2001/02/25 14:05:46
+@c Keywords: dired extensions
+@c dired-x.el REVISION NUMBER: 2
+
+@c State: Released
+@c Ident: dired-x.texi,v 2.53 2001/02/25 14:05:46 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
+@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.)
+
+@copying
+Copyright @copyright{} 1994, 1995, 1999, 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
+``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Dired-X: (dired-x). Dired Extra Features.
+@end direntry
+
+@c @smallbook
+@tex
+\overfullrule=0pt
+%\global\baselineskip 30pt % For printing in double spaces
+@end tex
+
+@titlepage
+@sp 6
+@c dired-x.el REVISION NUMBER
+@center @titlefont{Dired Extra Version 2}
+@sp 2
+@center @titlefont{For The GNU Emacs}
+@sp 1
+@center @titlefont{Directory Editor}
+@sp 4
+@center Lawrence R@. Dodd
+@c @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
+@insertcopying
+@end titlepage
+
+@page
+
+@ifnottex
+
+@node Top
+@comment node-name, next, previous, up
+
+@noindent
+This documents the ``extra'' features for Dired Mode for GNU Emacs 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
+
+@c @item
+@c Revision of this manual: 2.53 (2001/02/25 14:05:46)
+
+@c @item
+@c Bugs to Lawrence R. Dodd <dodd@@roebling.poly.edu>. @emph{Please} type
+@c @kbd{M-x dired-x-submit-report} to submit a bug report (@pxref{Bugs}).
+
+@c @item
+@c You can obtain a copy of this package via anonymous ftp in
+@c @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::
+
+* GNU Free Documentation License::
+* Concept Index::
+* Command Index::
+* Key Index::
+* Variable Index::
+
+@end menu
+
+@end ifnottex
+
+@node Introduction, Installation, Top, Top
+@comment node-name, next, previous, up
+@chapter Introduction
+
+This documents the @emph{extra} features for Dired Mode for GNU Emacs. It
+is derived from version 1.191 of Sebastian Kremer's @file{dired-x.el}.
+
+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. Finally, a few other
+features have been added and a few more functions have been bound to keys.
+
+@ifnottex
+@menu
+* Features::
+* Technical Details::
+@end menu
+@end ifnottex
+
+@node Features, Technical Details, , Introduction
+@comment node-name, next, previous, up
+@section Features
+@cindex Features
+
+Some features provided by Dired Extra
+
+@enumerate
+@item
+Omitting 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 (@pxref{Key
+Index}) and also binds @kbd{C-x C-j} and @kbd{C-x 4 C-j} @emph{globally} to
+@code{dired-jump} (@pxref{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 (@pxref{Find File At
+Point}).
+
+@node Technical Details, , 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
+
+@node Installation, Omitting Files in Dired, Introduction, 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
+ (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
+ (lambda ()
+ ;; Set dired-x buffer-local variables here. For example:
+ ;; (dired-omit-mode 1)
+ ))
+@end example
+
+@noindent
+This will load @file{dired-x.el} when Dired is first invoked (for example,
+when you first type @kbd{C-x d}).
+
+@ifnottex
+@menu
+* Optional Installation Dired Jump::
+* Optional Installation File At Point::
+@end menu
+@end ifnottex
+
+@node Optional Installation Dired Jump, Optional Installation File At Point, , 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}
+(@pxref{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, , 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} (@pxref{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
+ (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
+ (lambda ()
+ ;; Bind dired-x-find-file.
+ (setq dired-x-hands-off-my-keys nil)
+ (load "dired-x")
+ ))
+@end example
+
+@node Omitting Files in Dired, Local Variables, Installation, Top
+@comment node-name, next, previous, up
+@chapter Omitting Files in Dired
+
+@cindex Omitting Files in Dired
+@cindex Uninteresting files
+@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-mode
+(@code{dired-omit-mode}) Toggle between displaying and omitting
+``uninteresting'' files.
+@item * O
+@kindex * O
+@findex dired-mark-omitted
+(@code{dired-mark-omitted}) Mark ``uninteresting'' files.
+@end table
+
+@noindent
+In order to make Dired Omit work you first need to load @file{dired-x.el}
+inside @code{dired-load-hook} (@pxref{Installation}) and then evaluate
+@code{(dired-omit-mode 1)} in some way (@pxref{Omitting Variables}).
+
+@ifnottex
+@menu
+* Omitting Variables::
+* Omitting Examples::
+* Omitting Technical::
+@end menu
+@end ifnottex
+
+@node Omitting Variables, Omitting Examples, , Omitting Files in Dired
+@comment node-name, next, previous, up
+
+@section Omitting Variables
+
+@cindex Customizing file omitting
+The following variables can be used to customize omitting.
+
+@table @code
+
+@vindex dired-omit-mode
+@item dired-omit-mode
+
+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 files whose names match regexp
+@code{dired-omit-files}, plus those ending with extensions in
+@code{dired-omit-extensions}. @kbd{M-o} (@code{dired-omit-mode})
+toggles its value, which is buffer-local. Put
+
+@example
+(dired-omit-mode 1)
+@end example
+
+@noindent
+inside your @code{dired-mode-hook} to have omitting initially turned on in
+@emph{every} Dired buffer (@pxref{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-mode: t
+End:
+@end example
+
+@noindent
+into a file @file{.dired} (the default value of
+@code{dired-local-variables-file}) in that directory (@pxref{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 (@pxref{Local Variables}).
+@end table
+
+@vindex dired-omit-files
+@item dired-omit-files
+
+Default: @code{"^#\\|\\.$"}
+
+Files whose names match this buffer-local regexp will not be displayed.
+This only has effect when @code{dired-omit-mode}'s value is @code{t}.
+
+The default value omits the special directories @file{.} and @file{..} and
+autosave files (plus other files ending in @file{.}) (@pxref{Omitting Examples}).
+
+@vindex dired-omit-extensions
+@item dired-omit-extensions
+
+Default: The elements of @code{completion-ignored-extensions},
+@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 file name. Set it
+to @code{nil} if you need to match the whole file name or @code{t} to match the
+file name 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 Dired to implement omitting. Should never be used
+as marker by the user or other packages. There is one exception to this rule:
+by adding
+
+@example
+(setq dired-mark-keys "\C-o")
+;; i.e., the value of dired-omit-marker-char
+;; (which is not defined yet)
+@end example
+
+@noindent
+to your @file{~/.emacs}, you can 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 @file{RCS} directory, then put
+
+@example
+(setq dired-omit-files
+ (concat dired-omit-files "\\|^RCS$\\|,v$"))
+@end example
+
+@noindent
+in the @code{dired-load-hook} (@pxref{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 @code{tib}, the bibliography program for use with @TeX{} and
+La@TeX{}, and you
+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} (@pxref{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 @file{.}),
+then put
+
+@example
+(setq dired-omit-files
+ (concat dired-omit-files "\\|^\\..+$"))
+@end example
+
+@noindent
+in the @code{dired-load-hook} (@pxref{Installation}).
+
+@end itemize
+
+@node Omitting Technical, , 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 Files in Dired, 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-mode: 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}, file name 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 @code{hack-local-variables}.
+
+@vindex dired-enable-local-variables
+@item dired-enable-local-variables
+Default: @code{t}
+
+Controls the 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 file, 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 is mentioned in brackets and you can type @kbd{M-p} to get
+the default into the minibuffer and then edit it, e.g., to change
+@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
+
+@noindent
+where each @var{command} can either be a string or a Lisp expression
+that evaluates to a string. If several commands are given, all of
+them will temporarily be pushed onto the history.
+
+If @samp{*} in the shell command, that means to substitute the file
+name.
+
+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 @samp{z} switch.
+Default: @code{nil}
+
+If non-@code{nil}, this is the 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 @code{gzip}
+Default: @code{t}
+
+A non-@code{nil} value means that @samp{-q} is passed to @code{gzip}
+overriding a verbose option in the @env{GZIP} environment variable.
+
+@item dired-guess-shell-znew-switches nil
+@vindex dired-guess-shell-znew-switches nil
+@cindex @code{znew}
+Default: @code{nil}
+
+A string of switches passed to @code{znew}. An example is
+@samp{-K} which will make @code{znew} keep a @file{.Z} file when it is
+smaller than the @file{.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 @code{ls} listings
+@cindex @code{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
+
+@noindent
+The regexp is a bit more complicated than usual to exclude @file{.dired}
+local-variable files.
+
+@node Advanced Mark Commands, Multiple Dired Directories, 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
+them simultaneously. If optional @var{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, you must type it
+explicitly.
+
+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
+
+@ifnottex
+@menu
+* Advanced Cleaning Functions::
+* Advanced Cleaning Variables::
+* Special Marking Function::
+@end menu
+@end ifnottex
+
+@node Advanced Cleaning Functions, Advanced Cleaning Variables, , 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 (@pxref{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 @file{*.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}, @pxref{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, , 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 @code{""}
+@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, Advanced Mark Commands, 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 it still has only 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 notion of @code{default-directory}, as a
+Lisp expression to evaluate. A resulting value of @code{nil} is ignored
+in favor of @code{default-directory}.
+
+@item dired-default-directory
+@findex dired-default-directory
+Use this function like you would use the variable
+@code{default-directory}, except that @code{dired-default-directory}
+also consults the 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
+@file{README} file, etc.) or to test if that file exists. You can then modify
+this in the minibuffer after snatching the file name.
+
+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}
+(@pxref{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 file name 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
+
+@noindent
+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
+
+@noindent
+with the point after the last @code{/}. If you hit @key{RET}, 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 @code{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-subdir
+@kindex M-G
+@item M-G
+(@code{dired-goto-subdir}) Go to the header line of an inserted directory.
+This command reads its argument, with completion derived from the names of the
+inserted subdirectories.
+@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, edit the current
+directory and move to file's line. If in Dired already, pop up a level and
+go to 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 (@pxref{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 @code{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 @code{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 @code{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 @kbd{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 @code{nroff}
+format).
+
+@vindex dired-bind-man
+If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not
+be bound to @kbd{N}.
+
+@item dired-do-relsymlink
+@cindex Relative symbolic links.
+@kindex Y
+@findex dired-do-relsymlink
+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
+
+@example
+ foo -> ../bar/foo
+@end example
+
+@noindent
+not absolute ones like
+
+@example
+ foo -> /ugly/path/that/may/change/any/day/bar/foo
+@end example
+
+@item dired-do-relsymlink-regexp
+@kindex %Y
+@findex dired-do-relsymlink-regexp
+Bound to @kbd{%Y}. Relative symlink all marked files containing
+@var{regexp} to @var{newname}. See functions
+@code{dired-do-rename-regexp} and @code{dired-do-relsymlink} for more
+info.
+@end table
+
+@node Bugs, GNU Free Documentation License, 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
+@c <dodd@@roebling.poly.edu>
+
+@node GNU Free Documentation License, Concept Index, Bugs, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Concept Index, Command Index, GNU Free Documentation License, 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
+
+@setchapternewpage odd
+@c @summarycontents
+@contents
+
+@bye
+@c dired-x.texi ends here.
+
+@ignore
+ arch-tag: 201727aa-9318-4c74-a0d7-4f51c550c4de
+@end ignore
--- /dev/null
+@c -*-texinfo-*-
+@center Version 1.2, November 2002
+
+@display
+Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+@sp 1
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document ``free'' in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft,'' which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@sp 1
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document,'' below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you.'' You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque.''
+
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements,''
+``Dedications,'' ``Endorsements,'' or ``History.'') To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+@sp 1
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+@sp 1
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+@sp 1
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+A. Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.@*
+B. List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.@*
+C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.@*
+D. Preserve all the copyright notices of the Document.@*
+E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.@*
+F. Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.@*
+G. Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.@*
+H. Include an unaltered copy of this License.@*
+I. Preserve the section Entitled ``History,'' Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled ``History'' in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.@*
+J. Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the ``History'' section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.@*
+K. For any section Entitled ``Acknowledgements'' or ``Dedications,''
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.@*
+L. Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.@*
+M. Delete any section Entitled ``Endorsements.'' Such a section
+ may not be included in the Modified Version.@*
+N. Do not retitle any existing section to be Entitled ``Endorsements''
+ or to conflict in title with any Invariant Section.@*
+O. Preserve any Warranty Disclaimers.@*
+@sp 1
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements,'' provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+@sp 1
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements,''
+and any sections Entitled ``Dedications.'' You must delete all sections
+Entitled ``Endorsements.''
+@sp 1
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+@sp 1
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+@sp 1
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements,''
+``Dedications,'' or ``History,'' the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+@sp 1
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document 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.
+@sp 1
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation 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. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+@end enumerate
+
+@unnumberedsec ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+Copyright (C) @var{year} @var{your name}.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+A copy of the license is included in the section entitled ``GNU
+Free Documentation License.''
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with...Texts.'' line with this:
+
+@smallexample
+@group
+with the Invariant Sections being @var{list their titles}, with the
+Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
+@var{list}.
+@end group
+@end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@ignore
+ arch-tag: c1679162-1d8a-4f02-bc52-2e71765f0165
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+
+@comment %**start of header
+@setfilename ../info/ebrowse
+@settitle A Class Browser for C++
+@setchapternewpage odd
+@syncodeindex fn cp
+@comment %**end of header
+
+@copying
+This file documents Ebrowse, a C++ class browser for GNU Emacs.
+
+Copyright @copyright{} 2000, 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Ebrowse: (ebrowse). A C++ class browser for Emacs.
+@end direntry
+
+@titlepage
+@title Ebrowse User's Manual
+@sp 4
+@subtitle Ebrowse/Emacs
+@sp 5
+@author Gerd Moellmann
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@node Top, Overview, (dir), (dir)
+
+@ifnottex
+You can browse C++ class hierarchies from within Emacs by using
+Ebrowse.
+@end ifnottex
+
+@menu
+* Overview:: What is it and how does it work?
+* Generating browser files:: How to process C++ source files
+* Loading a Tree:: How to start browsing
+* Tree Buffers:: Traversing class hierarchies
+* Member Buffers:: Looking at member information
+* Tags-like Functions:: Finding members from source files
+* GNU Free Documentation License:: The license for this documentation.
+* Concept Index:: An entry for each concept defined
+@end menu
+
+
+
+
+@node Overview, Generating browser files, Top, Top
+@chapter Introduction
+
+When working in software projects using C++, I frequently missed
+software support for two things:
+
+@itemize @bullet
+@item
+When you get a new class library, or you have to work on source code you
+haven't written yourself (or written sufficiently long ago), you need a
+tool to let you navigate class hierarchies and investigate
+features of the software. Without such a tool you often end up
+@command{grep}ing through dozens or even hundreds of files.
+
+@item
+Once you are productive, it would be nice to have a tool that knows your
+sources and can help you while you are editing source code. Imagine to
+be able to jump to the definition of an identifier while you are
+editing, or something that can complete long identifier names because it
+knows what identifiers are defined in your program@dots{}.
+@end itemize
+
+The design of Ebrowse reflects these two needs.
+
+How does it work?
+
+@cindex parser for C++ sources
+A fast parser written in C is used to process C++ source files.
+The parser generates a data base containing information about classes,
+members, global functions, defines, types etc.@: found in the sources.
+
+The second part of Ebrowse is a Lisp program. This program reads
+the data base generated by the parser. It displays its contents in
+various forms and allows you to perform operations on it, or do
+something with the help of the knowledge contained in the data base.
+
+@cindex major modes, of Ebrowse buffers
+@dfn{Navigational} use of Ebrowse is centered around two
+types of buffers which define their own major modes:
+
+@cindex tree buffer
+@dfn{Tree buffers} are used to view class hierarchies in tree form.
+They allow you to quickly find classes, find or view class declarations,
+perform operations like query replace on sets of your source files, and
+finally tree buffers are used to produce the second buffer form---member
+buffers. @xref{Tree Buffers}.
+
+@cindex member buffer
+Members are displayed in @dfn{member buffers}. Ebrowse
+distinguishes between six different types of members; each type is
+displayed as a member list of its own:
+
+@itemize @bullet
+@item
+Instance member variables;
+
+@item
+Instance member functions;
+
+@item
+Static member variables;
+
+@item
+Static member functions;
+
+@item
+Friends/Defines. The list of defines is contained in the friends
+list of the pseudo-class @samp{*Globals*};
+
+@item
+Types (@code{enum}s, and @code{typedef}s defined with class
+scope).@refill
+@end itemize
+
+You can switch member buffers from one list to another, or to another
+class. You can include inherited members in the display, you can set
+filters that remove categories of members from the display, and most
+importantly you can find or view member declarations and definitions
+with a keystroke. @xref{Member Buffers}.
+
+These two buffer types and the commands they provide support the
+navigational use of the browser. The second form resembles Emacs' Tags
+package for C and other procedural languages. Ebrowse's commands of
+this type are not confined to special buffers; they are most often used
+while you are editing your source code.
+
+To list just a subset of what you can use the Tags part of Ebrowse for:
+
+@itemize @bullet
+@item
+Jump to the definition or declaration of an identifier in your source
+code, with an electric position stack that lets you easily navigate
+back and forth.
+
+@item
+Complete identifiers in your source with a completion list containing
+identifiers from your source code only.
+
+@item
+Perform search and query replace operations over some or all of your
+source files.
+
+@item
+Show all identifiers matching a regular expression---and jump to one of
+them, if you like.
+@end itemize
+
+
+
+
+@node Generating browser files, Loading a Tree, Overview, Top
+@comment node-name, next, previous, up
+@chapter Processing Source Files
+
+@cindex @command{ebrowse}, the program
+@cindex class data base creation
+Before you can start browsing a class hierarchy, you must run the parser
+@command{ebrowse} on your source files in order to generate a Lisp data
+base describing your program.
+
+@cindex command line for @command{ebrowse}
+The operation of @command{ebrowse} can be tailored with command line
+options. Under normal circumstances it suffices to let the parser use
+its default settings. If you want to do that, call it with a command
+line like:
+
+@example
+ebrowse *.h *.cc
+@end example
+
+@noindent
+or, if your shell doesn't allow all the file names to be specified on
+the command line,
+
+@example
+ebrowse --files=@var{file}
+@end example
+
+@noindent
+where @var{file} contains the names of the files to be parsed, one
+per line.
+
+@findex --help
+When invoked with option @samp{--help}, @command{ebrowse} prints a list of
+available command line options.@refill
+
+@menu
+* Input files:: Specifying which files to parse
+* Output file:: Changing the output file name
+* Structs and unions:: Omitting @code{struct}s and @code{union}s
+* Matching:: Setting regular expression lengths
+* Verbosity:: Getting feedback for lengthy operations
+@end menu
+
+
+
+
+@comment name, next, prev, up
+@node Input files, Output file, Generating browser files, Generating browser files
+@section Specifying Input Files
+
+@table @samp
+@cindex input files, for @command{ebrowse}
+@item file
+Each file name on the command line tells @command{ebrowse} to parse
+that file.
+
+@cindex response files
+@findex --files
+@item --files=@var{file}
+This command line switch specifies that @var{file} contains a list of
+file names to parse. Each line in @var{file} must contain one file
+name. More than one option of this kind is allowed. You might, for
+instance, want to use one file for header files, and another for source
+files.
+
+@cindex standard input, specifying input files
+@item standard input
+When @command{ebrowse} finds no file names on the command line, and no
+@samp{--file} option is specified, it reads file names from standard
+input. This is sometimes convenient when @command{ebrowse} is used as part
+of a command pipe.
+
+@findex --search-path
+@item --search-path=@var{paths}
+This option lets you specify search paths for your input files.
+@var{paths} is a list of directory names, separated from each other by a
+either a colon or a semicolon, depending on the operating system.
+@end table
+
+@cindex header files
+@cindex friend functions
+It is generally a good idea to specify input files so that header files
+are parsed before source files. This facilitates the parser's work of
+properly identifying friend functions of a class.
+
+
+
+@comment name, next, prev, up
+@node Output file, Structs and unions, Input files, Generating browser files
+@section Changing the Output File Name
+
+@table @samp
+@cindex output file name
+@findex --output-file
+@cindex @file{BROWSE} file
+@item --output-file=@var{file}
+This option instructs @command{ebrowse} to generate a Lisp data base with
+name @var{file}. By default, the data base is named @file{BROWSE}, and
+is written in the directory in which @command{ebrowse} is invoked.
+
+If you regularly use data base names different from the default, you
+might want to add this to your init file:
+
+@lisp
+(add-to-list 'auto-mode-alist '(@var{NAME} . ebrowse-tree-mode))
+@end lisp
+
+@noindent
+where @var{NAME} is the Lisp data base name you are using.
+
+@findex --append
+@cindex appending output to class data base
+@item --append
+By default, each run of @command{ebrowse} erases the old contents of the
+output file when writing to it. You can instruct @command{ebrowse} to
+append its output to an existing file produced by @command{ebrowse}
+with this command line option.
+@end table
+
+
+
+
+@comment name, next, prev, up
+@node Structs and unions, Matching, Output file, Generating browser files
+@section Structs and Unions
+@cindex structs
+@cindex unions
+
+@table @samp
+@findex --no-structs-or-unions
+@item --no-structs-or-unions
+This switch suppresses all classes in the data base declared as
+@code{struct} or @code{union} in the output.
+
+This is mainly useful when you are converting an existing
+C program to C++, and do not want to see the old C structs in a class
+tree.
+@end table
+
+
+
+
+@comment name, next, prev, up
+@node Matching, Verbosity, Structs and unions, Generating browser files
+@section Regular Expressions
+
+@cindex regular expressions, recording
+The parser @command{ebrowse} normally writes regular expressions to its
+output file that help the Lisp part of Ebrowse to find functions,
+variables etc.@: in their source files.
+
+You can instruct @command{ebrowse} to omit these regular expressions by
+calling it with the command line switch @samp{--no-regexps}.
+
+When you do this, the Lisp part of Ebrowse tries to guess, from member
+or class names, suitable regular expressions to locate that class or
+member in source files. This works fine in most cases, but the
+automatic generation of regular expressions can be too weak if unusual
+coding styles are used.
+
+@table @samp
+@findex --no-regexps
+@item --no-regexps
+This option turns off regular expression recording.
+
+@findex --min-regexp-length
+@cindex minimum regexp length for recording
+@item --min-regexp-length=@var{n}
+The number @var{n} following this option specifies the minimum length of
+the regular expressions recorded to match class and member declarations
+and definitions. The default value is set at compilation time of
+@command{ebrowse}.
+
+The smaller the minimum length, the higher the probability that
+Ebrowse will find a wrong match. The larger the value, the
+larger the output file and therefore the memory consumption once the
+file is read from Emacs.
+
+@findex --max-regexp-length
+@cindex maximum regexp length for recording
+@item --max-regexp-length=@var{n}
+The number following this option specifies the maximum length of the
+regular expressions used to match class and member declarations and
+definitions. The default value is set at compilation time of
+@command{ebrowse}.
+
+The larger the maximum length, the higher the probability that the
+browser will find a correct match, but the larger the value the larger
+the output file and therefore the memory consumption once the data is
+read. As a second effect, the larger the regular expression, the higher
+the probability that it will no longer match after editing the file.
+@end table
+
+
+
+
+@node Verbosity, , Matching, Generating browser files
+@comment node-name, next, previous, up
+@section Verbose Mode
+@cindex verbose operation
+
+@table @samp
+@findex --verbose
+@item --verbose
+When this option is specified on the command line, @command{ebrowse} prints
+a period for each file parsed, and it displays a @samp{+} for each
+class written to the output file.
+
+@findex --very-verbose
+@item --very-verbose
+This option makes @command{ebrowse} print out the names of the files and
+the names of the classes seen.
+@end table
+
+
+
+
+@node Loading a Tree, Tree Buffers, Generating browser files, Top
+@comment node-name, next, previous, up
+@chapter Starting to Browse
+@cindex loading
+@cindex browsing
+
+You start browsing a class hierarchy parsed by @command{ebrowse} by just
+finding the @file{BROWSE} file with @kbd{C-x C-f}.
+
+An example of a tree buffer display is shown below.
+
+@example
+| Collection
+| IndexedCollection
+| Array
+| FixedArray
+| Set
+| Dictionary
+@end example
+
+@cindex mouse highlight in tree buffers
+When you run Emacs on a display which supports colors and the mouse, you
+will notice that certain areas in the tree buffer are highlighted
+when you move the mouse over them. This highlight marks mouse-sensitive
+regions in the buffer. Please notice the help strings in the echo area
+when the mouse moves over a sensitive region.
+
+@cindex context menu
+A click with @kbd{Mouse-3} on a mouse-sensitive region opens a context
+menu. In addition to this, each buffer also has a buffer-specific menu
+that is opened with a click with @kbd{Mouse-3} somewhere in the buffer
+where no highlight is displayed.
+
+
+
+@comment ****************************************************************
+@comment ***
+@comment *** TREE BUFFERS
+@comment ***
+@comment ****************************************************************
+
+@node Tree Buffers, Member Buffers, Loading a Tree, Top
+@comment node-name, next, previous, up
+@chapter Tree Buffers
+@cindex tree buffer mode
+@cindex class trees
+
+Class trees are displayed in @dfn{tree buffers} which install their own
+major mode. Most Emacs keys work in tree buffers in the usual way,
+e.g.@: you can move around in the buffer with the usual @kbd{C-f},
+@kbd{C-v} etc., or you can search with @kbd{C-s}.
+
+Tree-specific commands are bound to simple keystrokes, similar to
+@code{Gnus}. You can take a look at the key bindings by entering
+@kbd{?} which calls @code{M-x describe-mode} in both tree and member
+buffers.
+
+@menu
+* Source Display:: Viewing and finding a class declaration
+* Member Display:: Showing members, switching to member buffers
+* Go to Class:: Finding a class
+* Quitting:: Discarding and burying the tree buffer
+* File Name Display:: Showing file names in the tree
+* Expanding and Collapsing:: Expanding and collapsing branches
+* Tree Indentation:: Changing the tree indentation
+* Killing Classes:: Removing class from the tree
+* Saving a Tree:: Saving a modified tree
+* Statistics:: Displaying class tree statistics
+* Marking Classes:: Marking and unmarking classes
+@end menu
+
+
+
+@node Source Display, Member Display, Tree Buffers, Tree Buffers
+@comment node-name, next, previous, up
+@section Viewing and Finding Class Declarations
+@cindex viewing, class
+@cindex finding a class
+@cindex class declaration
+
+You can view or find a class declaration when the cursor is on a class
+name.
+
+@table @kbd
+@item SPC
+This command views the class declaration if the database
+contains informations about it. If you don't parse the entire source
+you are working on, some classes will only be known to exist but the
+location of their declarations and definitions will not be known.@refill
+
+@item RET
+Works like @kbd{SPC}, except that it finds the class
+declaration rather than viewing it, so that it is ready for
+editing.@refill
+@end table
+
+The same functionality is available from the menu opened with
+@kbd{Mouse-3} on the class name.
+
+
+
+
+@node Member Display, Go to Class, Source Display, Tree Buffers
+@comment node-name, next, previous, up
+@section Displaying Members
+@cindex @samp{*Members*} buffer
+@cindex @samp{*Globals*}
+@cindex freezing a member buffer
+@cindex member lists, in tree buffers
+
+Ebrowse distinguishes six different kinds of members, each of
+which is displayed as a separate @dfn{member list}: instance variables,
+instance functions, static variables, static functions, friend
+functions, and types.
+
+Each of these lists can be displayed in a member buffer with a command
+starting with @kbd{L} when the cursor is on a class name. By default,
+there is only one member buffer named @dfn{*Members*} that is reused
+each time you display a member list---this has proven to be more
+practical than to clutter up the buffer list with dozens of member
+buffers.
+
+If you want to display more than one member list at a time you can
+@dfn{freeze} its member buffer. Freezing a member buffer prevents it
+from being overwritten the next time you display a member list. You can
+toggle this buffer status at any time.
+
+Every member list display command in the tree buffer can be used with a
+prefix argument (@kbd{C-u}). Without a prefix argument, the command will
+pop to a member buffer displaying the member list. With prefix argument,
+the member buffer will additionally be @dfn{frozen}.
+
+@table @kbd
+@cindex instance member variables, list
+@item L v
+This command displays the list of instance member variables.
+
+@cindex static variables, list
+@item L V
+Display the list of static variables.
+
+@cindex friend functions, list
+@item L d
+Display the list of friend functions. This list is used for defines if
+you are viewing the class @samp{*Globals*} which is a place holder for
+global symbols.
+
+@cindex member functions, list
+@item L f
+Display the list of member functions.
+
+@cindex static member functions, list
+@item L F
+Display the list of static member functions.
+
+@cindex types, list
+@item L t
+Display a list of types.
+@end table
+
+These lists are also available from the class' context menu invoked with
+@kbd{Mouse-3} on the class name.
+
+
+
+
+@node Go to Class, Quitting, Member Display, Tree Buffers
+@comment node-name, next, previous, up
+@section Finding a Class
+@cindex locate class
+@cindex expanding branches
+@cindex class location
+
+@table @kbd
+@cindex search for class
+@item /
+This command reads a class name from the minibuffer with completion and
+positions the cursor on the class in the class tree.
+
+If the branch of the class tree containing the class searched for is
+currently collapsed, the class itself and all its base classes are
+recursively made visible. (See also @ref{Expanding and
+Collapsing}.)@refill
+
+This function is also available from the tree buffer's context menu.
+
+@item n
+Repeat the last search done with @kbd{/}. Each tree buffer has its own
+local copy of the regular expression last searched in it.
+@end table
+
+
+
+
+@node Quitting, File Name Display, Go to Class, Tree Buffers
+@comment node-name, next, previous, up
+@section Burying a Tree Buffer
+@cindex burying tree buffer
+
+@table @kbd
+@item q
+Is a synonym for @kbd{M-x bury-buffer}.
+@end table
+
+
+
+
+@node File Name Display, Expanding and Collapsing, Quitting, Tree Buffers
+@comment node-name, next, previous, up
+@section Displaying File Names
+
+@table @kbd
+@cindex file names in tree buffers
+@item T f
+This command toggles the display of file names in a tree buffer. If
+file name display is switched on, the names of the files containing the
+class declaration are shown to the right of the class names. If the
+file is not known, the string @samp{unknown} is displayed.
+
+This command is also provided in the tree buffer's context menu.
+
+@item s
+Display file names for the current line, or for the number of lines
+given by a prefix argument.
+@end table
+
+Here is an example of a tree buffer with file names displayed.
+
+@example
+| Collection (unknown)
+| IndexedCollection (indexedcltn.h)
+| Array (array.h)
+| FixedArray (fixedarray.h)
+| Set (set.h)
+| Dictionary (dict.h)
+@end example
+
+
+
+
+@node Expanding and Collapsing, Tree Indentation, File Name Display, Tree Buffers
+@comment node-name, next, previous, up
+@section Expanding and Collapsing a Tree
+@cindex expand tree branch
+@cindex collapse tree branch
+@cindex branches of class tree
+@cindex class tree, collapse or expand
+
+You can expand and collapse parts of a tree to reduce the complexity of
+large class hierarchies. Expanding or collapsing branches of a tree has
+no impact on the functionality of other commands, like @kbd{/}. (See
+also @ref{Go to Class}.)@refill
+
+Collapsed branches are indicated with an ellipsis following the class
+name like in the example below.
+
+@example
+| Collection
+| IndexedCollection...
+| Set
+| Dictionary
+@end example
+
+@table @kbd
+@item -
+This command collapses the branch of the tree starting at the class the
+cursor is on.
+
+@item +
+This command expands the branch of the tree starting at the class the
+cursor is on. Both commands for collapsing and expanding branches are
+also available from the class' object menu.
+
+@item *
+This command expands all collapsed branches in the tree.
+@end table
+
+
+
+
+@node Tree Indentation, Killing Classes, Expanding and Collapsing, Tree Buffers
+@comment node-name, next, previous, up
+@section Changing the Tree Indentation
+@cindex tree indentation
+@cindex indentation of the tree
+
+@table @kbd
+@item T w
+This command reads a new indentation width from the minibuffer and
+redisplays the tree buffer with the new indentation It is also
+available from the tree buffer's context menu.
+@end table
+
+
+
+
+@node Killing Classes, Saving a Tree, Tree Indentation, Tree Buffers
+@comment node-name, next, previous, up
+@section Removing Classes from the Tree
+@cindex killing classes
+@cindex class, remove from tree
+
+@table @kbd
+@item C-k
+This command removes the class the cursor is on and all its derived
+classes from the tree. The user is asked for confirmation before the
+deletion is actually performed.
+@end table
+
+
+
+
+@node Saving a Tree, Statistics, Killing Classes, Tree Buffers
+@comment node-name, next, previous, up
+@comment node-name, next, previous, up
+@section Saving a Tree
+@cindex save tree to a file
+@cindex tree, save to a file
+@cindex class tree, save to a file
+
+@table @kbd
+@item C-x C-s
+This command writes a class tree to the file from which it was read.
+This is useful after classes have been deleted from a tree.
+
+@item C-x C-w
+Writes the tree to a file whose name is read from the minibuffer.
+@end table
+
+
+
+
+@node Statistics, Marking Classes, Saving a Tree, Tree Buffers
+@comment node-name, next, previous, up
+@cindex statistics for a tree
+@cindex tree statistics
+@cindex class statistics
+
+@table @kbd
+@item x
+Display statistics for the tree, like number of classes in it, number of
+member functions, etc. This command can also be found in the buffer's
+context menu.
+@end table
+
+
+
+
+@node Marking Classes, , Statistics, Tree Buffers
+@comment node-name, next, previous, up
+@cindex marking classes
+@cindex operations on marked classes
+
+Classes can be marked for operations similar to the standard Emacs
+commands @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} (see
+also @xref{Tags-like Functions}.)@refill
+
+@table @kbd
+@cindex toggle mark
+@item M t
+Toggle the mark of the line point is in or for as many lines as given by
+a prefix command. This command can also be found in the class' context
+menu.
+
+@cindex unmark all
+@item M a
+Unmark all classes. With prefix argument @kbd{C-u}, mark all classes in
+the tree. Since this command operates on the whole buffer, it can also be
+found in the buffer's object menu.
+@end table
+
+Marked classes are displayed with an @code{>} in column one of the tree
+display, like in the following example
+
+@example
+|> Collection
+| IndexedCollection...
+|> Set
+| Dictionary
+@end example
+
+
+
+
+@c ****************************************************************
+@c ***
+@c *** MEMBER BUFFERS
+@c ***
+@c ****************************************************************
+
+@node Member Buffers, Tags-like Functions, Tree Buffers, Top
+@comment node-name, next, previous, up
+@chapter Member Buffers
+@cindex members
+@cindex member buffer mode
+
+@cindex class members, types
+@cindex types of class members
+@dfn{Member buffers} are used to operate on lists of members of a class.
+Ebrowse distinguishes six kinds of lists:
+
+@itemize @bullet
+@item
+Instance variables (normal member variables);
+@item
+Instance functions (normal member functions);
+@item
+Static variables;
+@item
+Static member functions;
+@item
+Friend functions;
+@item
+Types (@code{enum}s and @code{typedef}s defined with class scope.
+Nested classes will be shown in the class tree like normal classes.
+@end itemize
+
+Like tree buffers, member buffers install their own major mode. Also
+like in tree buffers, menus are provided for certain areas in the
+buffer: members, classes, and the buffer itself.
+
+@menu
+* Switching Member Lists:: Choosing which members to display
+* Finding/Viewing:: Modifying source code
+* Inherited Members:: Display of Inherited Members
+* Searching Members:: Finding members in member buffer
+* Switching to Tree:: Going back to the tree buffer
+* Filters:: Selective member display
+* Attributes:: Display of @code{virtual} etc.
+* Long and Short Display:: Comprehensive and verbose display
+* Regexp Display:: Showing matching regular expressions
+* Switching Classes:: Displaying another class
+* Killing/Burying:: Getting rid of the member buffer
+* Column Width:: Display style
+* Redisplay:: Redrawing the member list
+* Getting Help:: How to get help for key bindings
+@end menu
+
+
+
+
+@node Switching Member Lists, Finding/Viewing, Member Buffers, Member Buffers
+@comment node-name, next, previous, up
+@section Switching Member Lists
+@cindex member lists, in member buffers
+@cindex static members
+@cindex friends
+@cindex types
+@cindex defines
+
+@table @kbd
+@cindex next member list
+@item L n
+This command switches the member buffer display to the next member list.
+
+@cindex previous member list
+@item L p
+This command switches the member buffer display to the previous member
+list.
+
+@item L f
+Switch to the list of member functions.
+
+@cindex static
+@item L F
+Switch to the list of static member functions.
+
+@item L v
+Switch to the list of member variables.
+
+@item L V
+Switch to the list of static member variables.
+
+@item L d
+Switch to the list of friends or defines.
+
+@item L t
+Switch to the list of types.
+@end table
+
+Both commands cycle through the member list.
+
+Most of the commands are also available from the member buffer's
+context menu.
+
+
+
+
+@node Finding/Viewing, Inherited Members, Switching Member Lists, Member Buffers
+@comment node-name, next, previous, up
+@section Finding and Viewing Member Source
+@cindex finding members, in member buffers
+@cindex viewing members, in member buffers
+@cindex member definitions, in member buffers
+@cindex member declarations, in member buffers
+@cindex definition of a member, in member buffers
+@cindex declaration of a member, in member buffers
+
+@table @kbd
+@item RET
+This command finds the definition of the member the cursor is on.
+Finding involves roughly the same as the standard Emacs tags facility
+does---loading the file and searching for a regular expression matching
+the member.
+
+@item f
+This command finds the declaration of the member the cursor is on.
+
+@item SPC
+This is the same command as @kbd{RET}, but views the member definition
+instead of finding the member's source file.
+
+@item v
+This is the same command as @kbd{f}, but views the member's declaration
+instead of finding the file the declaration is in.
+@end table
+
+You can install a hook function to perform actions after a member or
+class declaration or definition has been found, or when it is not found.
+
+All the commands described above can also be found in the context menu
+displayed when clicking @kbd{Mouse-2} on a member name.
+
+
+
+
+@node Inherited Members, Searching Members, Finding/Viewing, Member Buffers
+@comment node-name, next, previous, up
+@section Display of Inherited Members
+@cindex superclasses, members
+@cindex base classes, members
+@cindex inherited members
+
+@table @kbd
+@item D b
+This command toggles the display of inherited members in the member
+buffer. This is also in the buffer's context menu.
+@end table
+
+
+
+
+@node Searching Members, Switching to Tree, Inherited Members, Member Buffers
+@comment node-name, next, previous, up
+@section Searching Members
+@cindex searching members
+
+@table @kbd
+@item G v
+Position the cursor on a member whose name is read from the minibuffer;
+only members shown in the current member buffer appear in the completion
+list.
+
+@item G m
+Like the above command, but all members for the current class appear in
+the completion list. If necessary, the current member list is switched
+to the one containing the member.
+
+With a prefix argument (@kbd{C-u}), all members in the class tree,
+i.e.@: all members the browser knows about appear in the completion
+list. The member display will be switched to the class and member list
+containing the member.
+
+@item G n
+Repeat the last member search.
+@end table
+
+Look into the buffer's context menu for a convenient way to do this with
+a mouse.
+
+
+
+@node Switching to Tree, Filters, Searching Members, Member Buffers
+@comment node-name, next, previous, up
+@section Switching to Tree Buffer
+@cindex tree buffer, switch to
+@cindex buffer switching
+@cindex switching buffers
+
+@table @kbd
+@item @key{TAB}
+Pop up the tree buffer to which the member buffer belongs.
+
+@item t
+Do the same as @key{TAB} but also position the cursor on the class
+displayed in the member buffer.
+@end table
+
+
+
+
+@node Filters, Attributes, Switching to Tree, Member Buffers
+@comment node-name, next, previous, up
+@section Filters
+@cindex filters
+
+@table @kbd
+@cindex @code{public} members
+@item F a u
+This command toggles the display of @code{public} members. The
+@samp{a} stands for `access'.
+
+@cindex @code{protected} members
+@item F a o
+This command toggles the display of @code{protected} members.
+
+@cindex @code{private} members
+@item F a i
+This command toggles the display of @code{private} members.
+
+@cindex @code{virtual} members
+@item F v
+This command toggles the display of @code{virtual} members.
+
+@cindex @code{inline} members
+@item F i
+This command toggles the display of @code{inline} members.
+
+@cindex @code{const} members
+@item F c
+This command toggles the display of @code{const} members.
+
+@cindex pure virtual members
+@item F p
+This command toggles the display of pure virtual members.
+
+@cindex remove filters
+@item F r
+This command removes all filters.
+@end table
+
+These commands are also found in the buffer's context menu.
+
+
+
+
+@node Attributes, Long and Short Display, Filters, Member Buffers
+@comment node-name, next, previous, up
+@section Displaying Member Attributes
+@cindex attributes
+@cindex member attribute display
+
+@table @kbd
+@item D a
+Toggle the display of member attributes (default is on).
+
+The nine member attributes Ebrowse knows about are displayed
+as a list a single-characters flags enclosed in angle brackets in front
+the of the member's name. A @samp{-} at a given position means that
+the attribute is false. The list of attributes from left to right is
+
+@table @samp
+@cindex @code{template} attribute
+@item T
+The member is a template.
+
+@cindex @code{extern "C"} attribute
+@item C
+The member is declared @code{extern "C"}.
+
+@cindex @code{virtual} attribute
+@item v
+Means the member is declared @code{virtual}.
+
+@cindex @code{inline}
+@item i
+The member is declared @code{inline}.
+
+@cindex @code{const} attribute
+@item c
+The member is @code{const}.
+
+@cindex pure virtual function attribute
+@item 0
+The member is a pure virtual function.
+
+@cindex @code{mutable} attribute
+@item m
+The member is declared @code{mutable}.
+
+@cindex @code{explicit} attribute
+@item e
+The member is declared @code{explicit}.
+
+@item t
+The member is a function with a throw list.
+@end table
+@end table
+
+This command is also in the buffer's context menu.
+
+
+
+@node Long and Short Display, Regexp Display, Attributes, Member Buffers
+@comment node-name, next, previous, up
+@section Long and Short Member Display
+@cindex display form
+@cindex long display
+@cindex short display
+
+@table @kbd
+@item D l
+This command toggles the member buffer between short and long display
+form. The short display form displays member names, only:
+
+@example
+| isEmpty contains hasMember create
+| storeSize hash isEqual restoreGuts
+| saveGuts
+@end example
+
+The long display shows one member per line with member name and regular
+expressions matching the member (if known):
+
+@example
+| isEmpty Bool isEmpty () const...
+| hash unsigned hash () const...
+| isEqual int isEqual (...
+@end example
+
+Regular expressions will only be displayed when the Lisp database has
+not been produced with the @command{ebrowse} option @samp{--no-regexps}.
+@xref{Matching, --no-regexps, Regular Expressions}.
+@end table
+
+
+
+
+@node Regexp Display, Switching Classes, Long and Short Display, Member Buffers
+@comment node-name, next, previous, up
+@section Display of Regular Expressions
+@cindex regular expression display
+
+@table @kbd
+@item D r
+This command toggles the long display form from displaying the regular
+expressions matching the member declarations to those expressions
+matching member definitions.
+@end table
+
+Regular expressions will only be displayed when the Lisp database has
+not been produced with the @command{ebrowse} option @samp{--no-regexps},
+see @ref{Matching, --no-regexps, Regular Expressions}.
+
+
+
+
+@node Switching Classes, Killing/Burying, Regexp Display, Member Buffers
+@comment node-name, next, previous, up
+@section Displaying Another Class
+@cindex base class, display
+@cindex derived class, display
+@cindex superclass, display
+@cindex subclass, display
+@cindex class display
+
+@table @kbd
+@item C c
+This command lets you switch the member buffer to another class. It
+reads the name of the new class from the minibuffer with completion.
+
+@item C b
+This is the same command as @kbd{C c} but restricts the classes shown in
+the completion list to immediate base classes, only. If only one base
+class exists, this one is immediately shown in the minibuffer.
+
+@item C d
+Same as @kbd{C b}, but for derived classes.
+
+@item C p
+Switch to the previous class in the class hierarchy on the same level as
+the class currently displayed.
+
+@item C n
+Switch to the next sibling of the class in the class tree.
+@end table
+
+
+
+
+@node Killing/Burying, Column Width, Switching Classes, Member Buffers
+@comment node-name, next, previous, up
+@section Burying a Member Buffer
+@cindex burying member buffers
+
+@table @kbd
+@item q
+This command is a synonym for @kbd{M-x bury-buffer}.
+@end table
+
+
+
+
+@node Column Width, Redisplay, Killing/Burying, Member Buffers
+@comment node-name, next, previous, up
+@section Setting the Column Width
+@cindex column width
+@cindex member indentation
+@cindex indentation, member
+
+@table @kbd
+@item D w
+This command sets the column width depending on the display form used
+(long or short display).
+@end table
+
+
+
+
+@node Redisplay, Getting Help, Column Width, Member Buffers
+@comment node-name, next, previous, up
+@section Forced Redisplay
+@cindex redisplay of member buffers
+
+@table @kbd
+@item C-l
+This command forces a redisplay of the member buffer. If the width
+of the window displaying the member buffer is changed this command
+redraws the member list with the appropriate column widths and number of
+columns.
+@end table
+
+
+
+
+@node Getting Help, , Redisplay, Member Buffers
+@comment node-name, next, previous, up
+@cindex help
+
+@table @kbd
+@item ?
+This key is bound to @code{describe-mode}.
+@end table
+
+
+
+
+@comment **************************************************************
+@comment *** TAGS LIKE FUNCTIONS
+@comment **************************************************************
+
+@node Tags-like Functions, GNU Free Documentation License, Member Buffers, Top
+@comment node-name, next, previous, up
+@chapter Tags-like Functions
+
+Ebrowse provides tags functions similar to those of the standard
+Emacs Tags facility, but better suited to the needs of C++ programmers.
+
+@menu
+* Finding and Viewing:: Going to a member declaration/definition
+* Position Stack:: Moving to previous locations
+* Search & Replace:: Searching and replacing over class tree files
+* Members in Files:: Listing all members in a given file
+* Apropos:: Listing members matching a regular expression
+* Symbol Completion:: Completing names while editing
+* Member Buffer Display:: Quickly display a member buffer for some
+ identifier
+@end menu
+
+
+
+@node Finding and Viewing, Position Stack, Tags-like Functions, Tags-like Functions
+@comment node-name, next, previous, up
+@section Finding and Viewing Members
+@cindex finding class member, in C++ source
+@cindex viewing class member, in C++ source
+@cindex tags
+@cindex member definition, finding, in C++ source
+@cindex member declaration, finding, in C++ source
+
+The functions in this section are similar to those described in
+@ref{Source Display}, and also in @ref{Finding/Viewing}, except that
+they work in a C++ source buffer, not in member and tree buffers created
+by Ebrowse.
+
+@table @kbd
+@item C-c C-m f
+Find the definition of the member around point. If you invoke this
+function with a prefix argument, the declaration is searched.
+
+If more than one class contains a member with the given name you can
+select the class with completion. If there is a scope declaration in
+front of the member name, this class name is used as initial input for
+the completion.
+
+@item C-c C-m F
+Find the declaration of the member around point.
+
+@item C-c C-m v
+View the definition of the member around point.
+
+@item C-c C-m V
+View the declaration of the member around point.
+
+@item C-c C-m 4 f
+Find a member's definition in another window.
+
+@item C-c C-m 4 F
+Find a member's declaration in another window.
+
+@item C-c C-m 4 v
+View a member's definition in another window.
+
+@item C-c C-m 4 V
+View a member's declaration in another window.
+
+@item C-c C-m 5 f
+Find a member's definition in another frame.
+
+@item C-c C-m 5 F
+Find a member's declaration in another frame.
+
+@item C-c C-m 5 v
+View a member's definition in another frame.
+
+@item C-c C-m 5 V
+View a member's declaration in another frame.
+@end table
+
+
+
+@node Position Stack, Search & Replace, Finding and Viewing, Tags-like Functions
+@comment node-name, next, previous, up
+@section The Position Stack
+@cindex position stack
+
+When jumping to a member declaration or definition with one of
+Ebrowse's commands, the position from where you performed the
+jump and the position where you jumped to are recorded in a
+@dfn{position stack}. There are several ways in which you can quickly
+move to positions in the stack:@refill
+
+@table @kbd
+@cindex return to original position
+@item C-c C-m -
+This command sets point to the previous position in the position stack.
+Directly after you performed a jump, this will put you back to the
+position where you came from.
+
+The stack is not popped, i.e.@: you can always switch back and forth
+between positions in the stack. To avoid letting the stack grow to
+infinite size there is a maximum number of positions defined. When this
+number is reached, older positions are discarded when new positions are
+pushed on the stack.
+
+@item C-c C-m +
+This command moves forward in the position stack, setting point to
+the next position stored in the position stack.
+
+@item C-c C-m p
+Displays an electric buffer showing all positions saved in the stack.
+You can select a position by pressing @kbd{SPC} in a line. You can
+view a position with @kbd{v}.
+@end table
+
+
+
+
+@node Search & Replace, Members in Files, Position Stack, Tags-like Functions
+@comment node-name, next, previous, up
+@section Searching and Replacing
+@cindex searching multiple C++ files
+@cindex replacing in multiple C++ files
+@cindex restart tags-operation
+
+Ebrowse allows you to perform operations on all or a subset of the files
+mentioned in a class tree. When you invoke one of the following
+functions and more than one class tree is loaded, you must choose a
+class tree to use from an electric tree menu. If the selected tree
+contains marked classes, the following commands operate on the files
+mentioned in the marked classes only. Otherwise all files in the class
+tree are used.
+
+@table @kbd
+@item C-c C-m s
+This function performs a regular expression search in the chosen set of
+files.
+
+@item C-c C-m u
+This command performs a search for calls of a given member which is
+selected in the usual way with completion.
+
+@item C-c C-m %
+Perform a query replace over the set of files.
+
+@item C-c C-m ,
+All three operations above stop when finding a match. You can restart
+the operation with this command.
+
+@item C-c C-m n
+This restarts the last tags operation with the next file in the list.
+@end table
+
+
+
+
+@node Members in Files, Apropos, Search & Replace, Tags-like Functions
+@comment node-name, next, previous, up
+@section Members in Files
+@cindex files
+@cindex members in file, listing
+@cindex list class members in a file
+@cindex file, members
+
+The command @kbd{C-c C-m l}, lists all members in a given file. The file
+name is read from the minibuffer with completion.
+
+
+
+
+@node Apropos, Symbol Completion, Members in Files, Tags-like Functions
+@comment node-name, next, previous, up
+@section Member Apropos
+@cindex apropos on class members
+@cindex members, matching regexp
+
+The command @kbd{C-c C-m a} can be used to display all members matching a
+given regular expression. This command can be very useful if you
+remember only part of a member name, and not its beginning.
+
+A special buffer is popped up containing all identifiers matching the
+regular expression, and what kind of symbol it is (e.g.@: a member
+function, or a type). You can then switch to this buffer, and use the
+command @kbd{C-c C-m f}, for example, to jump to a specific member.
+
+
+
+
+@node Symbol Completion, Member Buffer Display, Apropos, Tags-like Functions
+@comment node-name, next, previous, up
+@section Symbol Completion
+@cindex completion
+@cindex symbol completion
+
+The command @kbd{C-c C-m @key{TAB}} completes the symbol in front of point.
+
+
+
+
+@node Member Buffer Display, , Symbol Completion, Tags-like Functions
+@section Quick Member Display
+@cindex member buffer, for member at point
+
+You can quickly display a member buffer containing the member the cursor
+in on with the command @kbd{C-c C-m m}.
+
+
+@node GNU Free Documentation License, Concept Index, Tags-like Functions, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+
+@node Concept Index, , GNU Free Documentation License, Top
+@unnumbered Concept Index
+@printindex cp
+
+@contents
+@bye
+
+@ignore
+ arch-tag: 52fe78ac-a1c4-48e7-815e-0a31acfad4bf
+@end ignore
--- /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
+@synindex ky cp
+
+@iftex
+@finalout
+@end iftex
+@c @smallbook
+@comment %**end of header (This is for running Texinfo on a region.)
+
+@copying
+This file documents Ediff, a comprehensive visual interface to Unix diff
+and patch utilities.
+
+Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Ediff: (ediff). A visual interface for comparing and merging programs.
+@end direntry
+
+@titlepage
+@title Ediff User's Manual
+@sp 4
+@subtitle Ediff version 2.81.1
+@sp 1
+@subtitle April 2007
+@sp 5
+@author Michael Kifer
+@page
+
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+
+@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.
+* GNU Free Documentation License:: The license for this documentation.
+* 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 through
+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 @code{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
+
+When Ediff starts up, it displays a small control window, which accepts the
+Ediff commands, and two or three windows displaying the files to be compared
+or merged. The control window can be in its own small frame or it can be
+part of a bigger frame that displays other buffers. In any case, it is
+important that the control window be active (i.e., be the one receiving the
+keystrokes) when you use Ediff. You can switch to other Emacs buffers at
+will and even edit the files currently being compared with Ediff and then
+switch back to Ediff at any time by activating the appropriate Emacs windows.
+
+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-backup
+@findex ediff-backup
+Compare a file with its backup. If there are several numerical backups, use
+the latest. If the file is itself a backup, then compare it with its
+original.
+
+@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. The regions can come from the same buffer
+and they can even overlap. You will be asked to specify the buffers that
+contain the regions, which you want to compare. For each buffer, you will
+also be asked to mark the regions to be compared. Pay attention to the
+messages that appear in the minibuffer.
+
+@item ediff-regions-linewise
+@findex ediff-regions-linewise
+Similar to @code{ediff-windows-linewise}, but compares the regions
+line-by-line. See @code{ediff-windows-linewise} for more details.
+
+@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.
+
+Since the patch might be in a buffer or a file, you will be asked which is
+the case. To avoid this extra prompt, you can invoke this command with a
+prefix argument. With an odd prefix argument, Ediff assumes the patch
+is in a file; with an even argument, a buffer is assumed.
+
+Note that @code{ediff-patch-file} will actually use the @code{patch}
+utility to change 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 Control in
+the 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 @code{patch} utility).
+
+Since the patch might be in a buffer or a file, you will be asked which is
+the case. To avoid this extra prompt, you can invoke this command with a
+prefix argument. With an odd prefix argument, Ediff assumes the patch
+is in a file; with an even argument, a buffer is assumed.
+
+@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 @code{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 commands @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. The commands @code{ediff-windows-wordwise} and
+@code{ediff-regions-wordwise} are intended for relatively small segments
+of buffers (e.g., up to 100 lines, depending on the speed of your machine),
+as they perform comparison on the basis of words rather than lines.
+(Word-wise comparison of large chunks of text can be slow.)
+
+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 ?
+@kindex ?
+Toggles the Ediff Quick Help window ON and OFF.
+@item G
+@kindex G
+Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer.
+
+@item E
+@kindex 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
+@kindex v
+Scrolls up buffers A and B (and buffer C where appropriate) in a
+coordinated fashion.
+@item V
+@kindex V
+Scrolls the buffers down.
+
+@item <
+@kindex <
+Scrolls the buffers to the left simultaneously.
+@item >
+@kindex >
+Scrolls buffers to the right.
+
+@item wd
+@kindex wd
+Saves the output from the diff utility, for further reference.
+
+With prefix argument, saves the plain output from @code{diff} (see
+@code{ediff-diff-program} and @code{ediff-diff-options}). Without the
+argument, it saves customized @code{diff} output (see
+@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}), if
+it is available.
+
+@item wa
+@kindex wa
+Saves buffer A, if it was modified.
+@item wb
+@kindex wb
+Saves buffer B, if it was modified.
+@item wc
+@kindex wc
+Saves buffer C, if it was modified (if you are in a session that
+compares three files simultaneously).
+
+@item a
+@kindex 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
+@kindex 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
+@kindex 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
+@kindex 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
+@kindex 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
+@kindex bc
+Copies the difference region from buffer B to buffer C.
+The command @kbd{rc} undoes this.
+@item ca
+@kindex ca
+Copies the difference region from buffer C to buffer A.
+The command @kbd{ra} undoes this.
+@item cb
+@kindex cb
+Copies the difference region from buffer C to buffer B.
+The command @kbd{rb} undoes this.
+
+@item p
+@itemx DEL
+@kindex p
+@kindex DEL
+Makes the previous difference region current.
+@item n
+@itemx SPC
+@kindex n
+@kindex SPC
+Makes the next difference region current.
+
+@item j
+@itemx -j
+@itemx Nj
+@kindex j
+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
+@kindex 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
+@kindex 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
+@kindex 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 !
+@kindex !
+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 *
+@kindex *
+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
+@kindex 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 |
+@kindex |
+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 @@
+@kindex @@
+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
+@kindex h
+Cycles between full highlighting, the mode where fine differences are not
+highlighted (but computed), and the mode where highlighting is done with
+@acronym{ASCII} strings. The latter is not really recommended, unless on a dumb TTY.
+
+@item r
+@kindex 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
+@kindex 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
+@kindex 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
+@kindex 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 ##
+@kindex ##
+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 #c
+@kindex #c
+@vindex ediff-ignore-case-option
+@vindex ediff-ignore-case-option3
+@vindex ediff-ignore-case
+Toggle case sensitivity in the diff program. All diffs are recomputed.
+Case sensitivity is controlled by the variables
+@code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3},
+and @code{ediff-ignore-case}, which are explained elsewhere.
+
+@item #h
+@itemx #f
+@kindex #f
+@kindex #h
+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
+@kindex 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
+@kindex 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
+@kindex 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 ~
+@kindex ~
+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
+@kindex i
+Displays all kinds of useful data about the current Ediff session.
+@item D
+@kindex 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 @code{diff} output.
+@xref{Patch and Diff Programs}, for details.
+
+@item R
+@kindex 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
+@kindex M
+Shows the session group buffer that invoked the current Ediff session.
+@xref{Session Groups}, for more information on session groups.
+
+@item z
+@kindex 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
+@kindex 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 %
+@kindex %
+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
+@kindex 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 $$
+@kindex $$
+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 $*
+@kindex $*
+When merging files with large number of differences, it is sometimes
+convenient to be able to skip the difference regions for which you already
+decided which variant is most appropriate. Typing @kbd{$*} will accomplish
+precisely this.
+
+To be more precise, this toggles the check for whether the current merge is
+identical to its default setting, as originally decided by Ediff. For
+instance, if Ediff is merging according to the `combined' policy, then the
+merge region is skipped over if it is different from the combination of the
+regions in buffers A and B. (Warning: swapping buffers A and B will confuse
+things in this respect.) If the merge region is marked as `prefer-A' then
+this region will be skipped if it differs from the current difference
+region in buffer A, etc.
+
+@item /
+@kindex /
+Displays the ancestor file during merges.
+@item &
+@kindex &
+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
+@kindex 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 +
+@kindex +
+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 =
+@kindex =
+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.
+
+In other situations, the currently highlighted region might be big and you
+might want to reconcile of them interactively.
+
+All of this can be done with the above command, @kbd{=}, which
+compares regions within Ediff buffers. Typing @kbd{=} creates a
+child Ediff session for comparing regions in buffers A, B, or
+C as follows.
+
+First, you will be asked whether you want to compare the fine differences
+between the currently highlighted buffers on a word-by-word basis. If you
+accept, a child Ediff session will start using the currently highlighted
+regions. Ediff will let you step over the differences word-wise.
+
+If you reject the offer, you will be asked to select regions of your choice.
+
+@emph{If you are comparing 2 files or buffers:}
+Ediff will ask you to select regions in buffers A and B.
+
+@emph{If you are comparing 3 files or buffers simultaneously:} Ediff will
+ask you to choose buffers and then select regions inside those buffers.
+
+@emph{If you are merging files or buffers (with or without ancestor):}
+Ediff will ask you to choose which buffer (A or B) to compare with the
+merge buffer and then select regions in those buffers.
+
+@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-toggle-use-toolbar
+@findex ediff-toggle-use-toolbar
+Available in XEmacs only. The Ediff toolbar provides quick access to some
+of the common Ediff functions. This function toggles the display of the
+toolbar. If invoked from the menubar, the function may take sometimes
+effect only after you execute an Ediff command, such as going to the next
+difference.
+
+@item ediff-use-toolbar-p
+@vindex ediff-use-toolbar-p
+The use of the toolbar can also be specified via the variable
+@code{ediff-use-toolbar-p} (default is @code{t}). This variable can be set
+only in @file{.emacs} --- do @strong{not} change it interactively. Use the
+function @code{ediff-toggle-use-toolbar} instead.
+
+@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 @emph{directory difference 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.
+
+@cindex Directory difference buffer
+Sometimes it is desirable to copy some files from one directory to another
+without exiting Ediff. The @emph{directory difference buffer}, which is
+displayed by typing @kbd{D} as discussed above, can be used for this
+purpose. If a file is, say, in Ediff's Directory A, but is missing in
+Ediff's Directory B (Ediff will refuse to override existing files), then
+typing @kbd{C} or clicking mouse button 2 over that file (which must be
+displayed in directory difference buffer) will copy that file from
+Directory A to Directory B.
+
+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-@code{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 on a per-buffer basis. Therefore, use @code{setq-default} to change
+this variable globally.
+
+@cindex Multi-file patches
+A multi-file patch is a concatenated output of several runs of the Unix
+@code{diff} command (some versions of @code{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 @code{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 entries, 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.
+Likewise, you can use @kbd{=h} to mark sessions with identical entries
+for hiding or, with @kbd{=m}, for further operations.
+
+The comparison operations @kbd{==}, @kbd{=h}, and @kbd{=m} can recurse into
+subdirectories to see if they have identical contents (so the user will not
+need to descend into those subdirectories manually). These commands ask the
+user whether or not to do a recursive descent.
+
+
+
+@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-before-setup-hook
+@vindex ediff-before-setup-hook
+Hook that is run just before Ediff rearranges windows to its liking.
+Can be used to save windows configuration.
+
+@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. These hooks are run each time Ediff rearranges windows to
+its liking. This happens whenever it detects that the user changed the
+windows setup.
+
+@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-before-session-group-setup-hook
+@vindex ediff-before-session-group-setup-hook
+Hooks run before setting up a control panel for a group of related Ediff
+sessions. Can be used, for example, to save window configuration to restore
+later.
+@item ediff-after-session-group-setup-hook
+@vindex ediff-after-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 icons are allowed to accept keyboard input (which depends on the
+window manager and other factors).
+@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{Please 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.
+
+@vindex ediff-ignore-case-option
+@vindex ediff-ignore-case-option3
+@vindex ediff-ignore-case
+Finally, Ediff can be told to ignore the case of the letters. This behavior
+can be toggled with @kbd{#c} and it is controlled with three variables:
+@code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3}, and
+@code{ediff-ignore-case}.
+
+The variable @code{ediff-ignore-case-option} specifies the option to pass
+to the diff program for comparing two files or buffers. For GNU
+@code{diff}, this option is @code{"-i"}. The variable
+@code{ediff-ignore-case-option3} specifies the option to pass to the
+@code{diff3} program in order to make it case-insensitive. GNU @code{diff3}
+does not have such an option, so when merging or comparing three files with
+this program, ignoring the letter case is not supported.
+
+The variable @code{ediff-ignore-case} controls whether Ediff starts out by
+ignoring letter case or not. It can be set in @file{.emacs} using
+@code{setq-default}.
+
+When case sensitivity is toggled, all difference
+regions are recomputed.
+
+@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 windowing 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 face @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
+ (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{Please note:} to set Ediff's faces, use only @code{copy-face}
+or @code{set/make-face-@dots{}} as shown above. Emacs' low-level
+face-manipulation functions should be avoided.
+
+@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-coding-system-for-read
+@vindex ediff-coding-system-for-read
+This variable specifies the coding system to use when reading the output
+that the programs @code{diff3} and @code{diff} send to Emacs. The default
+is @code{raw-text}, and this should work fine in Unix and in most
+cases under Windows NT/95/98/2000. There are @code{diff} programs
+for which the default option doesn't work under Windows. In such cases,
+@code{raw-text-dos} might work. If not, you will have to experiment with
+other coding systems or use GNU diff.
+
+@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 @code{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:
+
+@comment Use @set to avoid triggering merge conflict detectors like CVS.
+@set seven-left <<<<<<<
+@set seven-right >>>>>>>
+@example
+@value{seven-left} variant A
+the difference region from buffer A
+@value{seven-right} variant B
+the difference region from buffer B
+####### Ancestor
+the difference region from the ancestor buffer, if available
+======= end
+@end example
+
+The above is the default template for the combined region. The user can
+customize this template using the variable
+@code{ediff-combination-pattern}.
+
+@vindex ediff-combination-pattern
+The variable @code{ediff-combination-pattern} specifies the template that
+determines how the combined merged region looks like. The template is
+represented as a list of the form @code{(STRING1 Symbol1 STRING2 Symbol2
+STRING3 Symbol3 STRING4)}. The symbols here must be atoms of the form
+@code{A}, @code{B}, or @code{Ancestor}. They determine the order in which
+the corresponding difference regions (from buffers A, B, and the ancestor
+buffer) are displayed in the merged region of buffer C. The strings in the
+template determine the text that separates the aforesaid regions. The
+default template is
+
+@smallexample
+("@value{seven-left} variant A" A "@value{seven-right} variant B" B
+ "####### Ancestor" Ancestor "======= end")
+@end smallexample
+
+@noindent
+(this is one long line) and the corresponding combined region is shown
+above. The order in which the regions are shown (and the separator
+strings) can be changed by changing the above template. It is even
+possible to add or delete region specifiers in this template (although
+the only possibly useful such modification seems to be the deletion of
+the ancestor).
+
+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.
+
+@vindex ediff-merge-filename-prefix
+When merge buffers are saved automatically as directed by
+@code{ediff-autostore-merges}, Ediff attaches a prefix to each file, as
+specified by the variable @code{ediff-merge-filename-prefix}. The default
+is @code{merge_}, but this can be changed by the user.
+
+@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} (recently renamed
+pcvs.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 @code{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-keep-tmp-versions
+@vindex @code{ediff-keep-tmp-versions}
+Default is @code{nil}. If @code{t}, the versions of the files being
+compared or merged using operations such as @code{ediff-revision} or
+@code{ediff-merge-revisions} are not deleted on exit. The normal action is
+to clean up and delete these version files.
+
+@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 @code{nil}.
+
+@item ediff-window-A
+The window displaying buffer A. If buffer A is not visible, this variable
+is @code{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-@code{nil} only if Ediff uses the multiframe display, i.e., when
+the control buffer is in its own frame.
+@end table
+
+@node Credits, GNU Free Documentation License, Customization, Top
+@chapter Credits
+
+Ediff was written by Michael Kifer <kifer@@cs.stonybrook.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@@xemacs.org>
+adapted it to the Emacs customization package.
+
+Many people provided help with bug reports, feature suggestions, and advice.
+Without them, Ediff would not be nearly as useful as it is today.
+Here is a hopefully full list of contributors:
+
+@example
+Adrian Aichner (aichner@@ecf.teradyne.com),
+Drew Adams (drew.adams@@oracle.com),
+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),
+Urban Engberg (ue@@cci.dk),
+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),
+Felix Heinrich Gatzemeier (felix.g@@tzemeier.info),
+Boris Goldowsky (boris@@cs.rochester.edu),
+Allan Gottlieb (gottlieb@@allan.ultra.nyu.edu),
+Aaron Gross (aaron@@bfr.co.il),
+Thorbjoern Hansen (thorbjoern.hansen@@mchp.siemens.de),
+Marcus Harnisch (marcus_harnisch@@mint-tech.com),
+Steven E. Harris (seh@@panix.com),
+Aaron S. Hawley (Aaron.Hawley@@uvm.edu),
+Xiaoli Huang (hxl@@epic.com),
+Andreas Jaeger (aj@@suse.de),
+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),
+Steffen Kilb (skilb@@gmx.net),
+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),
+Hannu Koivisto (azure@@iki.fi),
+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),
+Dave Love (d.love@@dl.ac.uk),
+Martin Maechler (maechler@@stat.math.ethz.ch),
+Simon Marshall (simon@@gnu.org),
+Paul C. Meuse (pmeuse@@delcomsys.com),
+Richard Mlynarik (mly@@adoc.xerox.com),
+Stefan Monnier (monnier@@cs.yale.edu),
+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),
+Dan Nicolaescu (dann@@ics.uci.edu),
+David Petchey (petchey_david@@jpmorgan.com),
+Benjamin Pierce (benjamin.pierce@@cl.cam.ac.uk),
+Francois Pinard (pinard@@iro.umontreal.ca),
+Tibor Polgar (tlp00@@spg.amdahl.com),
+David Prince (dave0d@@fegs.co.uk),
+Paul Raines (raines@@slac.stanford.edu),
+Stefan Reicher (xsteve@@riic.at),
+Charles Rich (rich@@merl.com),
+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),
+Vin Shelton (acs@@xemacs.org),
+Scott O. Sherman (Scott.Sherman@@mci.com),
+Richard Stallman (rms@@gnu.org),
+Richard Stanton (stanton@@haas.berkeley.edu),
+Sam Steingold (sds@@goems.com),
+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),
+Stephen J. Turnbull (stephen@@xemacs.org),
+Jan Vroonhof (vroonhof@@math.ethz.ch),
+Colin Walters (walters@@cis.ohio-state.edu),
+Philippe Waroquiers (philippe.waroquiers@@eurocontrol.be),
+Klaus Weber (gizmo@@zork.north.de),
+Ben Wing (ben@@xemacs.org),
+Tom Wurgler (twurgler@@goodyear.com),
+Steve Youngs (youngs@@xemacs.org),
+Ilya Zakharevich (ilya@@math.ohio-state.edu),
+Eli Zaretskii (eliz@@is.elta.co.il)
+@end example
+
+@node GNU Free Documentation License, Index, Credits, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+
+@node Index, , GNU Free Documentation License, Top
+@unnumbered Index
+@printindex cp
+
+@setchapternewpage odd
+@contents
+@bye
+
+@ignore
+ arch-tag: 165ecb88-d03c-44b1-a921-b93f50b05b46
+@end ignore
--- /dev/null
+\input texinfo
+
+@setfilename ../info/emacs-mime
+@settitle Emacs MIME Manual
+@synindex fn cp
+@synindex vr cp
+@synindex pg cp
+
+@copying
+This file documents the Emacs MIME interface functionality.
+
+Copyright @copyright{} 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
+2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@c Node ``Interface Functions'' uses Latin-1 characters
+@documentencoding ISO-8859-1
+
+@dircategory Emacs
+@direntry
+* Emacs MIME: (emacs-mime). Emacs MIME de/composition library.
+@end direntry
+@iftex
+@finalout
+@end iftex
+@setchapternewpage odd
+
+@titlepage
+@title Emacs MIME Manual
+
+@author by Lars Magne Ingebrigtsen
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@node Top
+@top Emacs MIME
+
+This manual documents the libraries used to compose and display
+@acronym{MIME} messages.
+
+This manual is directed at users who want to modify the behavior of
+the @acronym{MIME} encoding/decoding process or want a more detailed
+picture of how the Emacs @acronym{MIME} library works, and people who want
+to write functions and commands that manipulate @acronym{MIME} elements.
+
+@acronym{MIME} is short for @dfn{Multipurpose Internet Mail Extensions}.
+This standard is documented in a number of RFCs; mainly RFC2045 (Format
+of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message
+Header Extensions for Non-@acronym{ASCII} Text), RFC2048 (Registration
+Procedures), RFC2049 (Conformance Criteria and Examples). It is highly
+recommended that anyone who intends writing @acronym{MIME}-compliant software
+read at least RFC2045 and RFC2047.
+
+@menu
+* Decoding and Viewing:: A framework for decoding and viewing.
+* Composing:: @acronym{MML}; a language for describing @acronym{MIME} parts.
+* Interface Functions:: An abstraction over the basic functions.
+* Basic Functions:: Utility and basic parsing functions.
+* Standards:: A summary of RFCs and working documents used.
+* GNU Free Documentation License:: The license for this documentation.
+* Index:: Function and variable index.
+@end menu
+
+
+@node Decoding and Viewing
+@chapter Decoding and Viewing
+
+This chapter deals with decoding and viewing @acronym{MIME} messages on a
+higher level.
+
+The main idea is to first analyze a @acronym{MIME} article, and then allow
+other programs to do things based on the list of @dfn{handles} that are
+returned as a result of this analysis.
+
+@menu
+* Dissection:: Analyzing a @acronym{MIME} message.
+* Non-MIME:: Analyzing a non-@acronym{MIME} message.
+* Handles:: Handle manipulations.
+* Display:: Displaying handles.
+* Display Customization:: Variables that affect display.
+* Files and Directories:: Saving and naming attachments.
+* New Viewers:: How to write your own viewers.
+@end menu
+
+
+@node Dissection
+@section Dissection
+
+The @code{mm-dissect-buffer} is the function responsible for dissecting
+a @acronym{MIME} article. If given a multipart message, it will recursively
+descend the message, following the structure, and return a tree of
+@acronym{MIME} handles that describes the structure of the message.
+
+@node Non-MIME
+@section Non-MIME
+@vindex mm-uu-configure-list
+
+Gnus also understands some non-@acronym{MIME} attachments, such as
+postscript, uuencode, binhex, yenc, shar, forward, gnatsweb, pgp,
+diff. Each of these features can be disabled by add an item into
+@code{mm-uu-configure-list}. For example,
+
+@lisp
+(require 'mm-uu)
+(add-to-list 'mm-uu-configure-list '(pgp-signed . disabled))
+@end lisp
+
+@table @code
+@item postscript
+@findex postscript
+PostScript file.
+
+@item uu
+@findex uu
+Uuencoded file.
+
+@item binhex
+@findex binhex
+Binhex encoded file.
+
+@item yenc
+@findex yenc
+Yenc encoded file.
+
+@item shar
+@findex shar
+Shar archive file.
+
+@item forward
+@findex forward
+Non-@acronym{MIME} forwarded message.
+
+@item gnatsweb
+@findex gnatsweb
+Gnatsweb attachment.
+
+@item pgp-signed
+@findex pgp-signed
+@acronym{PGP} signed clear text.
+
+@item pgp-encrypted
+@findex pgp-encrypted
+@acronym{PGP} encrypted clear text.
+
+@item pgp-key
+@findex pgp-key
+@acronym{PGP} public keys.
+
+@item emacs-sources
+@findex emacs-sources
+@vindex mm-uu-emacs-sources-regexp
+Emacs source code. This item works only in the groups matching
+@code{mm-uu-emacs-sources-regexp}.
+
+@item diff
+@vindex diff
+@vindex mm-uu-diff-groups-regexp
+Patches. This is intended for groups where diffs of committed files
+are automatically sent to. It only works in groups matching
+@code{mm-uu-diff-groups-regexp}.
+
+@end table
+
+@node Handles
+@section Handles
+
+A @acronym{MIME} handle is a list that fully describes a @acronym{MIME}
+component.
+
+The following macros can be used to access elements in a handle:
+
+@table @code
+@item mm-handle-buffer
+@findex mm-handle-buffer
+Return the buffer that holds the contents of the undecoded @acronym{MIME}
+part.
+
+@item mm-handle-type
+@findex mm-handle-type
+Return the parsed @code{Content-Type} of the part.
+
+@item mm-handle-encoding
+@findex mm-handle-encoding
+Return the @code{Content-Transfer-Encoding} of the part.
+
+@item mm-handle-undisplayer
+@findex mm-handle-undisplayer
+Return the object that can be used to remove the displayed part (if it
+has been displayed).
+
+@item mm-handle-set-undisplayer
+@findex mm-handle-set-undisplayer
+Set the undisplayer object.
+
+@item mm-handle-disposition
+@findex mm-handle-disposition
+Return the parsed @code{Content-Disposition} of the part.
+
+@item mm-get-content-id
+Returns the handle(s) referred to by @code{Content-ID}.
+
+@end table
+
+
+@node Display
+@section Display
+
+Functions for displaying, removing and saving.
+
+@table @code
+@item mm-display-part
+@findex mm-display-part
+Display the part.
+
+@item mm-remove-part
+@findex mm-remove-part
+Remove the part (if it has been displayed).
+
+@item mm-inlinable-p
+@findex mm-inlinable-p
+Say whether a @acronym{MIME} type can be displayed inline.
+
+@item mm-automatic-display-p
+@findex mm-automatic-display-p
+Say whether a @acronym{MIME} type should be displayed automatically.
+
+@item mm-destroy-part
+@findex mm-destroy-part
+Free all resources occupied by a part.
+
+@item mm-save-part
+@findex mm-save-part
+Offer to save the part in a file.
+
+@item mm-pipe-part
+@findex mm-pipe-part
+Offer to pipe the part to some process.
+
+@item mm-interactively-view-part
+@findex mm-interactively-view-part
+Prompt for a mailcap method to use to view the part.
+
+@end table
+
+
+@node Display Customization
+@section Display Customization
+
+@table @code
+
+@item mm-inline-media-tests
+@vindex mm-inline-media-tests
+This is an alist where the key is a @acronym{MIME} type, the second element
+is a function to display the part @dfn{inline} (i.e., inside Emacs), and
+the third element is a form to be @code{eval}ed to say whether the part
+can be displayed inline.
+
+This variable specifies whether a part @emph{can} be displayed inline,
+and, if so, how to do it. It does not say whether parts are
+@emph{actually} displayed inline.
+
+@item mm-inlined-types
+@vindex mm-inlined-types
+This, on the other hand, says what types are to be displayed inline, if
+they satisfy the conditions set by the variable above. It's a list of
+@acronym{MIME} media types.
+
+@item mm-automatic-display
+@vindex mm-automatic-display
+This is a list of types that are to be displayed ``automatically'', but
+only if the above variable allows it. That is, only inlinable parts can
+be displayed automatically.
+
+@item mm-automatic-external-display
+@vindex mm-automatic-external-display
+This is a list of types that will be displayed automatically in an
+external viewer.
+
+@item mm-keep-viewer-alive-types
+@vindex mm-keep-viewer-alive-types
+This is a list of media types for which the external viewer will not
+be killed when selecting a different article.
+
+@item mm-attachment-override-types
+@vindex mm-attachment-override-types
+Some @acronym{MIME} agents create parts that have a content-disposition of
+@samp{attachment}. This variable allows overriding that disposition and
+displaying the part inline. (Note that the disposition is only
+overridden if we are able to, and want to, display the part inline.)
+
+@item mm-discouraged-alternatives
+@vindex mm-discouraged-alternatives
+List of @acronym{MIME} types that are discouraged when viewing
+@samp{multipart/alternative}. Viewing agents are supposed to view the
+last possible part of a message, as that is supposed to be the richest.
+However, users may prefer other types instead, and this list says what
+types are most unwanted. If, for instance, @samp{text/html} parts are
+very unwanted, and @samp{text/richtext} parts are somewhat unwanted,
+you could say something like:
+
+@lisp
+(setq mm-discouraged-alternatives
+ '("text/html" "text/richtext")
+ mm-automatic-display
+ (remove "text/html" mm-automatic-display))
+@end lisp
+
+Adding @code{"image/.*"} might also be useful. Spammers use images as
+the preferred part of @samp{multipart/alternative} messages, so you might
+not notice there are other parts. See also
+@code{gnus-buttonized-mime-types}, @ref{MIME Commands, ,MIME Commands,
+gnus, Gnus Manual}. After adding @code{"multipart/alternative"} to
+@code{gnus-buttonized-mime-types} you can choose manually which
+alternative you'd like to view. For example, you can set those
+variables like:
+
+@lisp
+(setq gnus-buttonized-mime-types
+ '("multipart/alternative" "multipart/signed")
+ mm-discouraged-alternatives
+ '("text/html" "image/.*"))
+@end lisp
+
+In this case, Gnus will display radio buttons for such a kind of spam
+message as follows:
+
+@example
+1. (*) multipart/alternative ( ) image/gif
+
+2. (*) text/plain ( ) text/html
+@end example
+
+@item mm-inline-large-images
+@vindex mm-inline-large-images
+When displaying inline images that are larger than the window, Emacs
+does not enable scrolling, which means that you cannot see the whole
+image. To prevent this, the library tries to determine the image size
+before displaying it inline, and if it doesn't fit the window, the
+library will display it externally (e.g. with @samp{ImageMagick} or
+@samp{xv}). Setting this variable to @code{t} disables this check and
+makes the library display all inline images as inline, regardless of
+their size.
+
+@item mm-inline-override-types
+@vindex mm-inline-override-types
+@code{mm-inlined-types} may include regular expressions, for example to
+specify that all @samp{text/.*} parts be displayed inline. If a user
+prefers to have a type that matches such a regular expression be treated
+as an attachment, that can be accomplished by setting this variable to a
+list containing that type. For example assuming @code{mm-inlined-types}
+includes @samp{text/.*}, then including @samp{text/html} in this
+variable will cause @samp{text/html} parts to be treated as attachments.
+
+@item mm-text-html-renderer
+@vindex mm-text-html-renderer
+This selects the function used to render @acronym{HTML}. The predefined
+renderers are selected by the symbols @code{w3},
+@code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more
+information about emacs-w3m}, @code{links}, @code{lynx},
+@code{w3m-standalone} or @code{html2text}. If @code{nil} use an
+external viewer. You can also specify a function, which will be
+called with a @acronym{MIME} handle as the argument.
+
+@item mm-inline-text-html-with-images
+@vindex mm-inline-text-html-with-images
+Some @acronym{HTML} mails might have the trick of spammers using
+@samp{<img>} tags. It is likely to be intended to verify whether you
+have read the mail. You can prevent your personal informations from
+leaking by setting this option to @code{nil} (which is the default).
+It is currently ignored by Emacs/w3. For emacs-w3m, you may use the
+command @kbd{t} on the image anchor to show an image even if it is
+@code{nil}.@footnote{The command @kbd{T} will load all images. If you
+have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i}
+or @kbd{I} instead.}
+
+@item mm-w3m-safe-url-regexp
+@vindex mm-w3m-safe-url-regexp
+A regular expression that matches safe URL names, i.e. URLs that are
+unlikely to leak personal information when rendering @acronym{HTML}
+email (the default value is @samp{\\`cid:}). If @code{nil} consider
+all URLs safe.
+
+@item mm-inline-text-html-with-w3m-keymap
+@vindex mm-inline-text-html-with-w3m-keymap
+You can use emacs-w3m command keys in the inlined text/html part by
+setting this option to non-@code{nil}. The default value is @code{t}.
+
+@item mm-external-terminal-program
+@vindex mm-external-terminal-program
+The program used to start an external terminal.
+
+@item mm-enable-external
+@vindex mm-enable-external
+Indicate whether external @acronym{MIME} handlers should be used.
+
+If @code{t}, all defined external @acronym{MIME} handlers are used. If
+@code{nil}, files are saved to disk (@code{mailcap-save-binary-file}).
+If it is the symbol @code{ask}, you are prompted before the external
+@acronym{MIME} handler is invoked.
+
+When you launch an attachment through mailcap (@pxref{mailcap}) an
+attempt is made to use a safe viewer with the safest options---this isn't
+the case if you save it to disk and launch it in a different way
+(command line or double-clicking). Anyhow, if you want to be sure not
+to launch any external programs, set this variable to @code{nil} or
+@code{ask}.
+
+@end table
+
+@node Files and Directories
+@section Files and Directories
+
+@table @code
+
+@item mm-default-directory
+@vindex mm-default-directory
+The default directory for saving attachments. If @code{nil} use
+@code{default-directory}.
+
+@item mm-tmp-directory
+@vindex mm-tmp-directory
+Directory for storing temporary files.
+
+@item mm-file-name-rewrite-functions
+@vindex mm-file-name-rewrite-functions
+A list of functions used for rewriting file names of @acronym{MIME}
+parts. Each function is applied successively to the file name.
+Ready-made functions include
+
+@table @code
+@item mm-file-name-delete-control
+@findex mm-file-name-delete-control
+Delete all control characters.
+
+@item mm-file-name-delete-gotchas
+@findex mm-file-name-delete-gotchas
+Delete characters that could have unintended consequences when used
+with flawed shell scripts, i.e. @samp{|}, @samp{>} and @samp{<}; and
+@samp{-}, @samp{.} as the first character.
+
+@item mm-file-name-delete-whitespace
+@findex mm-file-name-delete-whitespace
+Remove all whitespace.
+
+@item mm-file-name-trim-whitespace
+@findex mm-file-name-trim-whitespace
+Remove leading and trailing whitespace.
+
+@item mm-file-name-collapse-whitespace
+@findex mm-file-name-collapse-whitespace
+Collapse multiple whitespace characters.
+
+@item mm-file-name-replace-whitespace
+@findex mm-file-name-replace-whitespace
+@vindex mm-file-name-replace-whitespace
+Replace whitespace with underscores. Set the variable
+@code{mm-file-name-replace-whitespace} to any other string if you do
+not like underscores.
+@end table
+
+The standard Emacs functions @code{capitalize}, @code{downcase},
+@code{upcase} and @code{upcase-initials} might also prove useful.
+
+@item mm-path-name-rewrite-functions
+@vindex mm-path-name-rewrite-functions
+List of functions used for rewriting the full file names of @acronym{MIME}
+parts. This is used when viewing parts externally, and is meant for
+transforming the absolute name so that non-compliant programs can find
+the file where it's saved.
+
+@end table
+
+@node New Viewers
+@section New Viewers
+
+Here's an example viewer for displaying @code{text/enriched} inline:
+
+@lisp
+(defun mm-display-enriched-inline (handle)
+ (let (text)
+ (with-temp-buffer
+ (mm-insert-part handle)
+ (save-window-excursion
+ (enriched-decode (point-min) (point-max))
+ (setq text (buffer-string))))
+ (mm-insert-inline handle text)))
+@end lisp
+
+We see that the function takes a @acronym{MIME} handle as its parameter. It
+then goes to a temporary buffer, inserts the text of the part, does some
+work on the text, stores the result, goes back to the buffer it was
+called from and inserts the result.
+
+The two important helper functions here are @code{mm-insert-part} and
+@code{mm-insert-inline}. The first function inserts the text of the
+handle in the current buffer. It handles charset and/or content
+transfer decoding. The second function just inserts whatever text you
+tell it to insert, but it also sets things up so that the text can be
+``undisplayed'' in a convenient manner.
+
+
+@node Composing
+@chapter Composing
+@cindex Composing
+@cindex MIME Composing
+@cindex MML
+@cindex MIME Meta Language
+
+Creating a @acronym{MIME} message is boring and non-trivial. Therefore,
+a library called @code{mml} has been defined that parses a language
+called @acronym{MML} (@acronym{MIME} Meta Language) and generates
+@acronym{MIME} messages.
+
+@findex mml-generate-mime
+The main interface function is @code{mml-generate-mime}. It will
+examine the contents of the current (narrowed-to) buffer and return a
+string containing the @acronym{MIME} message.
+
+@menu
+* Simple MML Example:: An example @acronym{MML} document.
+* MML Definition:: All valid @acronym{MML} elements.
+* Advanced MML Example:: Another example @acronym{MML} document.
+* Encoding Customization:: Variables that affect encoding.
+* Charset Translation:: How charsets are mapped from @sc{mule} to @acronym{MIME}.
+* Conversion:: Going from @acronym{MIME} to @acronym{MML} and vice versa.
+* Flowed text:: Soft and hard newlines.
+@end menu
+
+
+@node Simple MML Example
+@section Simple MML Example
+
+Here's a simple @samp{multipart/alternative}:
+
+@example
+<#multipart type=alternative>
+This is a plain text part.
+<#part type=text/enriched>
+<center>This is a centered enriched part</center>
+<#/multipart>
+@end example
+
+After running this through @code{mml-generate-mime}, we get this:
+
+@example
+Content-Type: multipart/alternative; boundary="=-=-="
+
+
+--=-=-=
+
+
+This is a plain text part.
+
+--=-=-=
+Content-Type: text/enriched
+
+
+<center>This is a centered enriched part</center>
+
+--=-=-=--
+@end example
+
+
+@node MML Definition
+@section MML Definition
+
+The @acronym{MML} language is very simple. It looks a bit like an SGML
+application, but it's not.
+
+The main concept of @acronym{MML} is the @dfn{part}. Each part can be of a
+different type or use a different charset. The way to delineate a part
+is with a @samp{<#part ...>} tag. Multipart parts can be introduced
+with the @samp{<#multipart ...>} tag. Parts are ended by the
+@samp{<#/part>} or @samp{<#/multipart>} tags. Parts started with the
+@samp{<#part ...>} tags are also closed by the next open tag.
+
+There's also the @samp{<#external ...>} tag. These introduce
+@samp{external/message-body} parts.
+
+Each tag can contain zero or more parameters on the form
+@samp{parameter=value}. The values may be enclosed in quotation marks,
+but that's not necessary unless the value contains white space. So
+@samp{filename=/home/user/#hello$^yes} is perfectly valid.
+
+The following parameters have meaning in @acronym{MML}; parameters that have no
+meaning are ignored. The @acronym{MML} parameter names are the same as the
+@acronym{MIME} parameter names; the things in the parentheses say which
+header it will be used in.
+
+@table @samp
+@item type
+The @acronym{MIME} type of the part (@code{Content-Type}).
+
+@item filename
+Use the contents of the file in the body of the part
+(@code{Content-Disposition}).
+
+@item charset
+The contents of the body of the part are to be encoded in the character
+set specified (@code{Content-Type}). @xref{Charset Translation}.
+
+@item name
+Might be used to suggest a file name if the part is to be saved
+to a file (@code{Content-Type}).
+
+@item disposition
+Valid values are @samp{inline} and @samp{attachment}
+(@code{Content-Disposition}).
+
+@item encoding
+Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and
+@samp{base64} (@code{Content-Transfer-Encoding}). @xref{Charset
+Translation}.
+
+@item description
+A description of the part (@code{Content-Description}).
+
+@item creation-date
+RFC822 date when the part was created (@code{Content-Disposition}).
+
+@item modification-date
+RFC822 date when the part was modified (@code{Content-Disposition}).
+
+@item read-date
+RFC822 date when the part was read (@code{Content-Disposition}).
+
+@item recipients
+Who to encrypt/sign the part to. This field is used to override any
+auto-detection based on the To/CC headers.
+
+@item sender
+Identity used to sign the part. This field is used to override the
+default key used.
+
+@item size
+The size (in octets) of the part (@code{Content-Disposition}).
+
+@item sign
+What technology to sign this @acronym{MML} part with (@code{smime}, @code{pgp}
+or @code{pgpmime})
+
+@item encrypt
+What technology to encrypt this @acronym{MML} part with (@code{smime},
+@code{pgp} or @code{pgpmime})
+
+@end table
+
+Parameters for @samp{text/plain}:
+
+@table @samp
+@item format
+Formatting parameter for the text, valid values include @samp{fixed}
+(the default) and @samp{flowed}. Normally you do not specify this
+manually, since it requires the textual body to be formatted in a
+special way described in RFC 2646. @xref{Flowed text}.
+@end table
+
+Parameters for @samp{application/octet-stream}:
+
+@table @samp
+@item type
+Type of the part; informal---meant for human readers
+(@code{Content-Type}).
+@end table
+
+Parameters for @samp{message/external-body}:
+
+@table @samp
+@item access-type
+A word indicating the supported access mechanism by which the file may
+be obtained. Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp},
+@samp{localfile}, and @samp{mailserver}. (@code{Content-Type}.)
+
+@item expiration
+The RFC822 date after which the file may no longer be fetched.
+(@code{Content-Type}.)
+
+@item size
+The size (in octets) of the file. (@code{Content-Type}.)
+
+@item permission
+Valid values are @samp{read} and @samp{read-write}
+(@code{Content-Type}).
+
+@end table
+
+Parameters for @samp{sign=smime}:
+
+@table @samp
+
+@item keyfile
+File containing key and certificate for signer.
+
+@end table
+
+Parameters for @samp{encrypt=smime}:
+
+@table @samp
+
+@item certfile
+File containing certificate for recipient.
+
+@end table
+
+
+@node Advanced MML Example
+@section Advanced MML Example
+
+Here's a complex multipart message. It's a @samp{multipart/mixed} that
+contains many parts, one of which is a @samp{multipart/alternative}.
+
+@example
+<#multipart type=mixed>
+<#part type=image/jpeg filename=~/rms.jpg disposition=inline>
+<#multipart type=alternative>
+This is a plain text part.
+<#part type=text/enriched name=enriched.txt>
+<center>This is a centered enriched part</center>
+<#/multipart>
+This is a new plain text part.
+<#part disposition=attachment>
+This plain text part is an attachment.
+<#/multipart>
+@end example
+
+And this is the resulting @acronym{MIME} message:
+
+@example
+Content-Type: multipart/mixed; boundary="=-=-="
+
+
+--=-=-=
+
+
+
+--=-=-=
+Content-Type: image/jpeg;
+ filename="~/rms.jpg"
+Content-Disposition: inline;
+ filename="~/rms.jpg"
+Content-Transfer-Encoding: base64
+
+/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof
+Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAAwADABAREA/8QAHwAA
+AQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQR
+BRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RF
+RkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ip
+qrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEB
+AAA/AO/rifFHjldNuGsrDa0qcSSHkA+gHrXKw+LtWLrMb+RgTyhbr+HSug07xNqV9fQtZrNI
+AyiaE/NuBPOOOP0rvRNE880KOC8TbXXGCv1FPqjrF4LDR7u5L7SkTFT/ALWOP1xXgTuXfc7E
+sx6nua6rwp4IvvEM8chCxWxOdzn7wz6V9AaB4S07w9p5itow0rDLSY5Pt9K43xO66P4xs71m
+2QXiGCbA4yOVJ9+1aYORkdK434lyNH4ahCnG66VT9Nj15JFbPdX0MS43M4VQf5/yr2vSpLnw
+5ZW8dlCZ8KFXjOPX0/mK6rSPEGt3Angu44fNEReHYNvIH3TzXDeKNO8RX+kSX2ouZkicTIOc
+L+g7E810ulFjpVtv3bwgB3HJyK5L4quY/C9sVxk3ij/xx6850u7t1mtp/wDlpEw3An3Jr3Dw
+34gsbWza4nBlhC5LDsaW6+IFgupQyCF3iHH7gA7c9R9ay7zx6t7aX9jHC4smhfBkGCvHGfrm
+tLQ7hbnRrV1GPkAP1x1/Hr+Ncr8Vzjwrbf8AX6v/AKA9eQRyYlQk8Yx9K6XTNbkgia2ciSIn
+7p5Ga9Atte0LTLKO6it4i7dVRFJDcZ4PvXN+JvEMF9bILVGXJLSZ4zkjivRPDaeX4b08HOTC
+pOffmua+KkbS+GLVUGT9tT/0B68eeIpIFYjB70+OOVXyoOM9+M1eaWeCLzHPyHGO/NVWvJJm
+jQ8KGH1NfQWhXSXmh2c8eArRLwO3HSv/2Q==
+
+--=-=-=
+Content-Type: multipart/alternative; boundary="==-=-="
+
+
+--==-=-=
+
+
+This is a plain text part.
+
+--==-=-=
+Content-Type: text/enriched;
+ name="enriched.txt"
+
+
+<center>This is a centered enriched part</center>
+
+--==-=-=--
+
+--=-=-=
+
+This is a new plain text part.
+
+--=-=-=
+Content-Disposition: attachment
+
+
+This plain text part is an attachment.
+
+--=-=-=--
+@end example
+
+@node Encoding Customization
+@section Encoding Customization
+
+@table @code
+
+@item mm-body-charset-encoding-alist
+@vindex mm-body-charset-encoding-alist
+Mapping from @acronym{MIME} charset to encoding to use. This variable is
+usually used except, e.g., when other requirements force a specific
+encoding (digitally signed messages require 7bit encodings). The
+default is
+
+@lisp
+((iso-2022-jp . 7bit)
+ (iso-2022-jp-2 . 7bit)
+ (utf-16 . base64)
+ (utf-16be . base64)
+ (utf-16le . base64))
+@end lisp
+
+As an example, if you do not want to have ISO-8859-1 characters
+quoted-printable encoded, you may add @code{(iso-8859-1 . 8bit)} to
+this variable. You can override this setting on a per-message basis
+by using the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}).
+
+@item mm-coding-system-priorities
+@vindex mm-coding-system-priorities
+Prioritize coding systems to use for outgoing messages. The default
+is @code{nil}, which means to use the defaults in Emacs, but is
+@code{(iso-8859-1 iso-2022-jp iso-2022-jp-2 shift_jis utf-8)} when
+running Emacs in the Japanese language environment. It is a list of
+coding system symbols (aliases of coding systems are also allowed, use
+@kbd{M-x describe-coding-system} to make sure you are specifying correct
+coding system names). For example, if you have configured Emacs
+to prefer UTF-8, but wish that outgoing messages should be sent in
+ISO-8859-1 if possible, you can set this variable to
+@code{(iso-8859-1)}. You can override this setting on a per-message
+basis by using the @code{charset} @acronym{MML} tag (@pxref{MML Definition}).
+
+@item mm-content-transfer-encoding-defaults
+@vindex mm-content-transfer-encoding-defaults
+Mapping from @acronym{MIME} types to encoding to use. This variable is usually
+used except, e.g., when other requirements force a safer encoding
+(digitally signed messages require 7bit encoding). Besides the normal
+@acronym{MIME} encodings, @code{qp-or-base64} may be used to indicate that for
+each case the most efficient of quoted-printable and base64 should be
+used.
+
+@code{qp-or-base64} has another effect. It will fold long lines so that
+MIME parts may not be broken by MTA. So do @code{quoted-printable} and
+@code{base64}.
+
+Note that it affects body encoding only when a part is a raw forwarded
+message (which will be made by @code{gnus-summary-mail-forward} with the
+arg 2 for example) or is neither the @samp{text/*} type nor the
+@samp{message/*} type. Even though in those cases, you can override
+this setting on a per-message basis by using the @code{encoding}
+@acronym{MML} tag (@pxref{MML Definition}).
+
+@item mm-use-ultra-safe-encoding
+@vindex mm-use-ultra-safe-encoding
+When this is non-@code{nil}, it means that textual parts are encoded as
+quoted-printable if they contain lines longer than 76 characters or
+starting with "From " in the body. Non-7bit encodings (8bit, binary)
+are generally disallowed. This reduce the probability that a non-8bit
+clean MTA or MDA changes the message. This should never be set
+directly, but bound by other functions when necessary (e.g., when
+encoding messages that are to be digitally signed).
+
+@end table
+
+@node Charset Translation
+@section Charset Translation
+@cindex charsets
+
+During translation from @acronym{MML} to @acronym{MIME}, for each
+@acronym{MIME} part which has been composed inside Emacs, an appropriate
+charset has to be chosen.
+
+@vindex mail-parse-charset
+If you are running a non-@sc{mule} Emacs, this process is simple: If the
+part contains any non-@acronym{ASCII} (8-bit) characters, the @acronym{MIME} charset
+given by @code{mail-parse-charset} (a symbol) is used. (Never set this
+variable directly, though. If you want to change the default charset,
+please consult the documentation of the package which you use to process
+@acronym{MIME} messages.
+@xref{Various Message Variables, , Various Message Variables, message,
+ Message Manual}, for example.)
+If there are only @acronym{ASCII} characters, the @acronym{MIME} charset US-ASCII is
+used, of course.
+
+@cindex MULE
+@cindex UTF-8
+@cindex Unicode
+@vindex mm-mime-mule-charset-alist
+Things are slightly more complicated when running Emacs with @sc{mule}
+support. In this case, a list of the @sc{mule} charsets used in the
+part is obtained, and the @sc{mule} charsets are translated to
+@acronym{MIME} charsets by consulting the table provided by Emacs itself
+or the variable @code{mm-mime-mule-charset-alist} for XEmacs.
+If this results in a single @acronym{MIME} charset, this is used to encode
+the part. But if the resulting list of @acronym{MIME} charsets contains more
+than one element, two things can happen: If it is possible to encode the
+part via UTF-8, this charset is used. (For this, Emacs must support
+the @code{utf-8} coding system, and the part must consist entirely of
+characters which have Unicode counterparts.) If UTF-8 is not available
+for some reason, the part is split into several ones, so that each one
+can be encoded with a single @acronym{MIME} charset. The part can only be
+split at line boundaries, though---if more than one @acronym{MIME} charset is
+required to encode a single line, it is not possible to encode the part.
+
+When running Emacs with @sc{mule} support, the preferences for which
+coding system to use is inherited from Emacs itself. This means that
+if Emacs is set up to prefer UTF-8, it will be used when encoding
+messages. You can modify this by altering the
+@code{mm-coding-system-priorities} variable though (@pxref{Encoding
+Customization}).
+
+The charset to be used can be overridden by setting the @code{charset}
+@acronym{MML} tag (@pxref{MML Definition}) when composing the message.
+
+The encoding of characters (quoted-printable, 8bit etc) is orthogonal
+to the discussion here, and is controlled by the variables
+@code{mm-body-charset-encoding-alist} and
+@code{mm-content-transfer-encoding-defaults} (@pxref{Encoding
+Customization}).
+
+@node Conversion
+@section Conversion
+
+@findex mime-to-mml
+A (multipart) @acronym{MIME} message can be converted to @acronym{MML}
+with the @code{mime-to-mml} function. It works on the message in the
+current buffer, and substitutes @acronym{MML} markup for @acronym{MIME}
+boundaries. Non-textual parts do not have their contents in the buffer,
+but instead have the contents in separate buffers that are referred to
+from the @acronym{MML} tags.
+
+@findex mml-to-mime
+An @acronym{MML} message can be converted back to @acronym{MIME} by the
+@code{mml-to-mime} function.
+
+These functions are in certain senses ``lossy''---you will not get back
+an identical message if you run @code{mime-to-mml} and then
+@code{mml-to-mime}. Not only will trivial things like the order of the
+headers differ, but the contents of the headers may also be different.
+For instance, the original message may use base64 encoding on text,
+while @code{mml-to-mime} may decide to use quoted-printable encoding, and
+so on.
+
+In essence, however, these two functions should be the inverse of each
+other. The resulting contents of the message should remain equivalent,
+if not identical.
+
+
+@node Flowed text
+@section Flowed text
+@cindex format=flowed
+
+The Emacs @acronym{MIME} library will respect the @code{use-hard-newlines}
+variable (@pxref{Hard and Soft Newlines, ,Hard and Soft Newlines,
+emacs, Emacs Manual}) when encoding a message, and the
+``format=flowed'' Content-Type parameter when decoding a message.
+
+On encoding text, regardless of @code{use-hard-newlines}, lines
+terminated by soft newline characters are filled together and wrapped
+after the column decided by @code{fill-flowed-encode-column}.
+Quotation marks (matching @samp{^>* ?}) are respected. The variable
+controls how the text will look in a client that does not support
+flowed text, the default is to wrap after 66 characters. If hard
+newline characters are not present in the buffer, no flow encoding
+occurs.
+
+On decoding flowed text, lines with soft newline characters are filled
+together and wrapped after the column decided by
+@code{fill-flowed-display-column}. The default is to wrap after
+@code{fill-column}.
+
+@table @code
+@item mm-fill-flowed
+@vindex mm-fill-flowed
+If non-@code{nil} a format=flowed article will be displayed flowed.
+@end table
+
+
+@node Interface Functions
+@chapter Interface Functions
+@cindex interface functions
+@cindex mail-parse
+
+The @code{mail-parse} library is an abstraction over the actual
+low-level libraries that are described in the next chapter.
+
+Standards change, and so programs have to change to fit in the new
+mold. For instance, RFC2045 describes a syntax for the
+@code{Content-Type} header that only allows @acronym{ASCII} characters in the
+parameter list. RFC2231 expands on RFC2045 syntax to provide a scheme
+for continuation headers and non-@acronym{ASCII} characters.
+
+The traditional way to deal with this is just to update the library
+functions to parse the new syntax. However, this is sometimes the wrong
+thing to do. In some instances it may be vital to be able to understand
+both the old syntax as well as the new syntax, and if there is only one
+library, one must choose between the old version of the library and the
+new version of the library.
+
+The Emacs @acronym{MIME} library takes a different tack. It defines a
+series of low-level libraries (@file{rfc2047.el}, @file{rfc2231.el}
+and so on) that parses strictly according to the corresponding
+standard. However, normal programs would not use the functions
+provided by these libraries directly, but instead use the functions
+provided by the @code{mail-parse} library. The functions in this
+library are just aliases to the corresponding functions in the latest
+low-level libraries. Using this scheme, programs get a consistent
+interface they can use, and library developers are free to create
+write code that handles new standards.
+
+The following functions are defined by this library:
+
+@table @code
+@item mail-header-parse-content-type
+@findex mail-header-parse-content-type
+Parse a @code{Content-Type} header and return a list on the following
+format:
+
+@lisp
+("type/subtype"
+ (attribute1 . value1)
+ (attribute2 . value2)
+ ...)
+@end lisp
+
+Here's an example:
+
+@example
+(mail-header-parse-content-type
+ "image/gif; name=\"b980912.gif\"")
+@result{} ("image/gif" (name . "b980912.gif"))
+@end example
+
+@item mail-header-parse-content-disposition
+@findex mail-header-parse-content-disposition
+Parse a @code{Content-Disposition} header and return a list on the same
+format as the function above.
+
+@item mail-content-type-get
+@findex mail-content-type-get
+Takes two parameters---a list on the format above, and an attribute.
+Returns the value of the attribute.
+
+@example
+(mail-content-type-get
+ '("image/gif" (name . "b980912.gif")) 'name)
+@result{} "b980912.gif"
+@end example
+
+@item mail-header-encode-parameter
+@findex mail-header-encode-parameter
+Takes a parameter string and returns an encoded version of the string.
+This is used for parameters in headers like @code{Content-Type} and
+@code{Content-Disposition}.
+
+@item mail-header-remove-comments
+@findex mail-header-remove-comments
+Return a comment-free version of a header.
+
+@example
+(mail-header-remove-comments
+ "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
+@result{} "Gnus/5.070027 "
+@end example
+
+@item mail-header-remove-whitespace
+@findex mail-header-remove-whitespace
+Remove linear white space from a header. Space inside quoted strings
+and comments is preserved.
+
+@example
+(mail-header-remove-whitespace
+ "image/gif; name=\"Name with spaces\"")
+@result{} "image/gif;name=\"Name with spaces\""
+@end example
+
+@item mail-header-get-comment
+@findex mail-header-get-comment
+Return the last comment in a header.
+
+@example
+(mail-header-get-comment
+ "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
+@result{} "Finnish Landrace"
+@end example
+
+@item mail-header-parse-address
+@findex mail-header-parse-address
+Parse an address and return a list containing the mailbox and the
+plaintext name.
+
+@example
+(mail-header-parse-address
+ "Hrvoje Niksic <hniksic@@srce.hr>")
+@result{} ("hniksic@@srce.hr" . "Hrvoje Niksic")
+@end example
+
+@item mail-header-parse-addresses
+@findex mail-header-parse-addresses
+Parse a string with list of addresses and return a list of elements like
+the one described above.
+
+@example
+(mail-header-parse-addresses
+ "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>")
+@result{} (("hniksic@@srce.hr" . "Hrvoje Niksic")
+ ("sb@@metis.no" . "Steinar Bang"))
+@end example
+
+@item mail-header-parse-date
+@findex mail-header-parse-date
+Parse a date string and return an Emacs time structure.
+
+@item mail-narrow-to-head
+@findex mail-narrow-to-head
+Narrow the buffer to the header section of the buffer. Point is placed
+at the beginning of the narrowed buffer.
+
+@item mail-header-narrow-to-field
+@findex mail-header-narrow-to-field
+Narrow the buffer to the header under point. Understands continuation
+headers.
+
+@item mail-header-fold-field
+@findex mail-header-fold-field
+Fold the header under point.
+
+@item mail-header-unfold-field
+@findex mail-header-unfold-field
+Unfold the header under point.
+
+@item mail-header-field-value
+@findex mail-header-field-value
+Return the value of the field under point.
+
+@item mail-encode-encoded-word-region
+@findex mail-encode-encoded-word-region
+Encode the non-@acronym{ASCII} words in the region. For instance,
+@samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}.
+
+@item mail-encode-encoded-word-buffer
+@findex mail-encode-encoded-word-buffer
+Encode the non-@acronym{ASCII} words in the current buffer. This function is
+meant to be called narrowed to the headers of a message.
+
+@item mail-encode-encoded-word-string
+@findex mail-encode-encoded-word-string
+Encode the words that need encoding in a string, and return the result.
+
+@example
+(mail-encode-encoded-word-string
+ "This is naïve, baby")
+@result{} "This is =?iso-8859-1?q?na=EFve,?= baby"
+@end example
+
+@item mail-decode-encoded-word-region
+@findex mail-decode-encoded-word-region
+Decode the encoded words in the region.
+
+@item mail-decode-encoded-word-string
+@findex mail-decode-encoded-word-string
+Decode the encoded words in the string and return the result.
+
+@example
+(mail-decode-encoded-word-string
+ "This is =?iso-8859-1?q?na=EFve,?= baby")
+@result{} "This is naïve, baby"
+@end example
+
+@end table
+
+Currently, @code{mail-parse} is an abstraction over @code{ietf-drums},
+@code{rfc2047}, @code{rfc2045} and @code{rfc2231}. These are documented
+in the subsequent sections.
+
+
+
+@node Basic Functions
+@chapter Basic Functions
+
+This chapter describes the basic, ground-level functions for parsing and
+handling. Covered here is parsing @code{From} lines, removing comments
+from header lines, decoding encoded words, parsing date headers and so
+on. High-level functionality is dealt with in the first chapter
+(@pxref{Decoding and Viewing}).
+
+@menu
+* rfc2045:: Encoding @code{Content-Type} headers.
+* rfc2231:: Parsing @code{Content-Type} headers.
+* ietf-drums:: Handling mail headers defined by RFC822bis.
+* rfc2047:: En/decoding encoded words in headers.
+* time-date:: Functions for parsing dates and manipulating time.
+* qp:: Quoted-Printable en/decoding.
+* base64:: Base64 en/decoding.
+* binhex:: Binhex decoding.
+* uudecode:: Uuencode decoding.
+* yenc:: Yenc decoding.
+* rfc1843:: Decoding HZ-encoded text.
+* mailcap:: How parts are displayed is specified by the @file{.mailcap} file
+@end menu
+
+
+@node rfc2045
+@section rfc2045
+
+RFC2045 is the ``main'' @acronym{MIME} document, and as such, one would
+imagine that there would be a lot to implement. But there isn't, since
+most of the implementation details are delegated to the subsequent
+RFCs.
+
+So @file{rfc2045.el} has only a single function:
+
+@table @code
+@item rfc2045-encode-string
+@findex rfc2045-encode-string
+Takes a parameter and a value and returns a @samp{PARAM=VALUE} string.
+@var{value} will be quoted if there are non-safe characters in it.
+@end table
+
+
+@node rfc2231
+@section rfc2231
+
+RFC2231 defines a syntax for the @code{Content-Type} and
+@code{Content-Disposition} headers. Its snappy name is @dfn{MIME
+Parameter Value and Encoded Word Extensions: Character Sets, Languages,
+and Continuations}.
+
+In short, these headers look something like this:
+
+@example
+Content-Type: application/x-stuff;
+ title*0*=us-ascii'en'This%20is%20even%20more%20;
+ title*1*=%2A%2A%2Afun%2A%2A%2A%20;
+ title*2="isn't it!"
+@end example
+
+They usually aren't this bad, though.
+
+The following functions are defined by this library:
+
+@table @code
+@item rfc2231-parse-string
+@findex rfc2231-parse-string
+Parse a @code{Content-Type} header and return a list describing its
+elements.
+
+@example
+(rfc2231-parse-string
+ "application/x-stuff;
+ title*0*=us-ascii'en'This%20is%20even%20more%20;
+ title*1*=%2A%2A%2Afun%2A%2A%2A%20;
+ title*2=\"isn't it!\"")
+@result{} ("application/x-stuff"
+ (title . "This is even more ***fun*** isn't it!"))
+@end example
+
+@item rfc2231-get-value
+@findex rfc2231-get-value
+Takes one of the lists on the format above and returns
+the value of the specified attribute.
+
+@item rfc2231-encode-string
+@findex rfc2231-encode-string
+Encode a parameter in headers likes @code{Content-Type} and
+@code{Content-Disposition}.
+
+@end table
+
+
+@node ietf-drums
+@section ietf-drums
+
+@dfn{drums} is an IETF working group that is working on the replacement
+for RFC822.
+
+The functions provided by this library include:
+
+@table @code
+@item ietf-drums-remove-comments
+@findex ietf-drums-remove-comments
+Remove the comments from the argument and return the results.
+
+@item ietf-drums-remove-whitespace
+@findex ietf-drums-remove-whitespace
+Remove linear white space from the string and return the results.
+Spaces inside quoted strings and comments are left untouched.
+
+@item ietf-drums-get-comment
+@findex ietf-drums-get-comment
+Return the last most comment from the string.
+
+@item ietf-drums-parse-address
+@findex ietf-drums-parse-address
+Parse an address string and return a list that contains the mailbox and
+the plain text name.
+
+@item ietf-drums-parse-addresses
+@findex ietf-drums-parse-addresses
+Parse a string that contains any number of comma-separated addresses and
+return a list that contains mailbox/plain text pairs.
+
+@item ietf-drums-parse-date
+@findex ietf-drums-parse-date
+Parse a date string and return an Emacs time structure.
+
+@item ietf-drums-narrow-to-header
+@findex ietf-drums-narrow-to-header
+Narrow the buffer to the header section of the current buffer.
+
+@end table
+
+
+@node rfc2047
+@section rfc2047
+
+RFC2047 (Message Header Extensions for Non-@acronym{ASCII} Text) specifies how
+non-@acronym{ASCII} text in headers are to be encoded. This is actually rather
+complicated, so a number of variables are necessary to tweak what this
+library does.
+
+The following variables are tweakable:
+
+@table @code
+@item rfc2047-header-encoding-alist
+@vindex rfc2047-header-encoding-alist
+This is an alist of header / encoding-type pairs. Its main purpose is
+to prevent encoding of certain headers.
+
+The keys can either be header regexps, or @code{t}.
+
+The values can be @code{nil}, in which case the header(s) in question
+won't be encoded, @code{mime}, which means that they will be encoded, or
+@code{address-mime}, which means the header(s) will be encoded carefully
+assuming they contain addresses.
+
+@item rfc2047-charset-encoding-alist
+@vindex rfc2047-charset-encoding-alist
+RFC2047 specifies two forms of encoding---@code{Q} (a
+Quoted-Printable-like encoding) and @code{B} (base64). This alist
+specifies which charset should use which encoding.
+
+@item rfc2047-encode-function-alist
+@vindex rfc2047-encode-function-alist
+This is an alist of encoding / function pairs. The encodings are
+@code{Q}, @code{B} and @code{nil}.
+
+@item rfc2047-encoded-word-regexp
+@vindex rfc2047-encoded-word-regexp
+When decoding words, this library looks for matches to this regexp.
+
+@item rfc2047-encode-encoded-words
+@vindex rfc2047-encode-encoded-words
+The boolean variable specifies whether encoded words
+(e.g. @samp{=?hello?=}) should be encoded again.
+
+@end table
+
+Those were the variables, and these are this functions:
+
+@table @code
+@item rfc2047-narrow-to-field
+@findex rfc2047-narrow-to-field
+Narrow the buffer to the header on the current line.
+
+@item rfc2047-encode-message-header
+@findex rfc2047-encode-message-header
+Should be called narrowed to the header of a message. Encodes according
+to @code{rfc2047-header-encoding-alist}.
+
+@item rfc2047-encode-region
+@findex rfc2047-encode-region
+Encodes all encodable words in the region specified.
+
+@item rfc2047-encode-string
+@findex rfc2047-encode-string
+Encode a string and return the results.
+
+@item rfc2047-decode-region
+@findex rfc2047-decode-region
+Decode the encoded words in the region.
+
+@item rfc2047-decode-string
+@findex rfc2047-decode-string
+Decode a string and return the results.
+
+@item rfc2047-encode-parameter
+@findex rfc2047-encode-parameter
+Encode a parameter in the RFC2047-like style. This is a replacement for
+the @code{rfc2231-encode-string} function. @xref{rfc2231}.
+
+When attaching files as @acronym{MIME} parts, we should use the RFC2231
+encoding to specify the file names containing non-@acronym{ASCII}
+characters. However, many mail softwares don't support it in practice
+and recipients won't be able to extract files with correct names.
+Instead, the RFC2047-like encoding is acceptable generally. This
+function provides the very RFC2047-like encoding, resigning to such a
+regrettable trend. To use it, put the following line in your
+@file{~/.gnus.el} file:
+
+@lisp
+(defalias 'mail-header-encode-parameter 'rfc2047-encode-parameter)
+@end lisp
+
+@end table
+
+
+@node time-date
+@section time-date
+
+While not really a part of the @acronym{MIME} library, it is convenient to
+document this library here. It deals with parsing @code{Date} headers
+and manipulating time. (Not by using tesseracts, though, I'm sorry to
+say.)
+
+These functions convert between five formats: A date string, an Emacs
+time structure, a decoded time list, a second number, and a day number.
+
+Here's a bunch of time/date/second/day examples:
+
+@example
+(parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
+@result{} (54 21 12 12 9 1998 6 nil 7200)
+
+(date-to-time "Sat Sep 12 12:21:54 1998 +0200")
+@result{} (13818 19266)
+
+(time-to-seconds '(13818 19266))
+@result{} 905595714.0
+
+(seconds-to-time 905595714.0)
+@result{} (13818 19266 0)
+
+(time-to-days '(13818 19266))
+@result{} 729644
+
+(days-to-time 729644)
+@result{} (961933 65536)
+
+(time-since '(13818 19266))
+@result{} (0 430)
+
+(time-less-p '(13818 19266) '(13818 19145))
+@result{} nil
+
+(subtract-time '(13818 19266) '(13818 19145))
+@result{} (0 121)
+
+(days-between "Sat Sep 12 12:21:54 1998 +0200"
+ "Sat Sep 07 12:21:54 1998 +0200")
+@result{} 5
+
+(date-leap-year-p 2000)
+@result{} t
+
+(time-to-day-in-year '(13818 19266))
+@result{} 255
+
+(time-to-number-of-days
+ (time-since
+ (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT")))
+@result{} 4.146122685185185
+@end example
+
+And finally, we have @code{safe-date-to-time}, which does the same as
+@code{date-to-time}, but returns a zero time if the date is
+syntactically malformed.
+
+The five data representations used are the following:
+
+@table @var
+@item date
+An RFC822 (or similar) date string. For instance: @code{"Sat Sep 12
+12:21:54 1998 +0200"}.
+
+@item time
+An internal Emacs time. For instance: @code{(13818 26466)}.
+
+@item seconds
+A floating point representation of the internal Emacs time. For
+instance: @code{905595714.0}.
+
+@item days
+An integer number representing the number of days since 00000101. For
+instance: @code{729644}.
+
+@item decoded time
+A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 t
+7200)}.
+@end table
+
+All the examples above represent the same moment.
+
+These are the functions available:
+
+@table @code
+@item date-to-time
+Take a date and return a time.
+
+@item time-to-seconds
+Take a time and return seconds.
+
+@item seconds-to-time
+Take seconds and return a time.
+
+@item time-to-days
+Take a time and return days.
+
+@item days-to-time
+Take days and return a time.
+
+@item date-to-day
+Take a date and return days.
+
+@item time-to-number-of-days
+Take a time and return the number of days that represents.
+
+@item safe-date-to-time
+Take a date and return a time. If the date is not syntactically valid,
+return a ``zero'' time.
+
+@item time-less-p
+Take two times and say whether the first time is less (i. e., earlier)
+than the second time.
+
+@item time-since
+Take a time and return a time saying how long it was since that time.
+
+@item subtract-time
+Take two times and subtract the second from the first. I. e., return
+the time between the two times.
+
+@item days-between
+Take two days and return the number of days between those two days.
+
+@item date-leap-year-p
+Take a year number and say whether it's a leap year.
+
+@item time-to-day-in-year
+Take a time and return the day number within the year that the time is
+in.
+
+@end table
+
+
+@node qp
+@section qp
+
+This library deals with decoding and encoding Quoted-Printable text.
+
+Very briefly explained, qp encoding means translating all 8-bit
+characters (and lots of control characters) into things that look like
+@samp{=EF}; that is, an equal sign followed by the byte encoded as a hex
+string.
+
+The following functions are defined by the library:
+
+@table @code
+@item quoted-printable-decode-region
+@findex quoted-printable-decode-region
+QP-decode all the encoded text in the specified region.
+
+@item quoted-printable-decode-string
+@findex quoted-printable-decode-string
+Decode the QP-encoded text in a string and return the results.
+
+@item quoted-printable-encode-region
+@findex quoted-printable-encode-region
+QP-encode all the encodable characters in the specified region. The third
+optional parameter @var{fold} specifies whether to fold long lines.
+(Long here means 72.)
+
+@item quoted-printable-encode-string
+@findex quoted-printable-encode-string
+QP-encode all the encodable characters in a string and return the
+results.
+
+@end table
+
+
+@node base64
+@section base64
+@cindex base64
+
+Base64 is an encoding that encodes three bytes into four characters,
+thereby increasing the size by about 33%. The alphabet used for
+encoding is very resistant to mangling during transit.
+
+The following functions are defined by this library:
+
+@table @code
+@item base64-encode-region
+@findex base64-encode-region
+base64 encode the selected region. Return the length of the encoded
+text. Optional third argument @var{no-line-break} means do not break
+long lines into shorter lines.
+
+@item base64-encode-string
+@findex base64-encode-string
+base64 encode a string and return the result.
+
+@item base64-decode-region
+@findex base64-decode-region
+base64 decode the selected region. Return the length of the decoded
+text. If the region can't be decoded, return @code{nil} and don't
+modify the buffer.
+
+@item base64-decode-string
+@findex base64-decode-string
+base64 decode a string and return the result. If the string can't be
+decoded, @code{nil} is returned.
+
+@end table
+
+
+@node binhex
+@section binhex
+@cindex binhex
+@cindex Apple
+@cindex Macintosh
+
+@code{binhex} is an encoding that originated in Macintosh environments.
+The following function is supplied to deal with these:
+
+@table @code
+@item binhex-decode-region
+@findex binhex-decode-region
+Decode the encoded text in the region. If given a third parameter, only
+decode the @code{binhex} header and return the filename.
+
+@end table
+
+@node uudecode
+@section uudecode
+@cindex uuencode
+@cindex uudecode
+
+@code{uuencode} is probably still the most popular encoding of binaries
+used on Usenet, although @code{base64} rules the mail world.
+
+The following function is supplied by this package:
+
+@table @code
+@item uudecode-decode-region
+@findex uudecode-decode-region
+Decode the text in the region.
+@end table
+
+
+@node yenc
+@section yenc
+@cindex yenc
+
+@code{yenc} is used for encoding binaries on Usenet. The following
+function is supplied by this package:
+
+@table @code
+@item yenc-decode-region
+@findex yenc-decode-region
+Decode the encoded text in the region.
+
+@end table
+
+
+@node rfc1843
+@section rfc1843
+@cindex rfc1843
+@cindex HZ
+@cindex Chinese
+
+RFC1843 deals with mixing Chinese and @acronym{ASCII} characters in messages. In
+essence, RFC1843 switches between @acronym{ASCII} and Chinese by doing this:
+
+@example
+This sentence is in @acronym{ASCII}.
+The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye.
+@end example
+
+Simple enough, and widely used in China.
+
+The following functions are available to handle this encoding:
+
+@table @code
+@item rfc1843-decode-region
+Decode HZ-encoded text in the region.
+
+@item rfc1843-decode-string
+Decode a HZ-encoded string and return the result.
+
+@end table
+
+
+@node mailcap
+@section mailcap
+
+The @file{~/.mailcap} file is parsed by most @acronym{MIME}-aware message
+handlers and describes how elements are supposed to be displayed.
+Here's an example file:
+
+@example
+image/*; gimp -8 %s
+audio/wav; wavplayer %s
+application/msword; catdoc %s ; copiousoutput ; nametemplate=%s.doc
+@end example
+
+This says that all image files should be displayed with @code{gimp},
+that WAVE audio files should be played by @code{wavplayer}, and that
+MS-WORD files should be inlined by @code{catdoc}.
+
+The @code{mailcap} library parses this file, and provides functions for
+matching types.
+
+@table @code
+@item mailcap-mime-data
+@vindex mailcap-mime-data
+This variable is an alist of alists containing backup viewing rules.
+
+@end table
+
+Interface functions:
+
+@table @code
+@item mailcap-parse-mailcaps
+@findex mailcap-parse-mailcaps
+Parse the @file{~/.mailcap} file.
+
+@item mailcap-mime-info
+Takes a @acronym{MIME} type as its argument and returns the matching viewer.
+
+@end table
+
+
+
+
+@node Standards
+@chapter Standards
+
+The Emacs @acronym{MIME} library implements handling of various elements
+according to a (somewhat) large number of RFCs, drafts and standards
+documents. This chapter lists the relevant ones. They can all be
+fetched from @uref{http://quimby.gnus.org/notes/}.
+
+@table @dfn
+@item RFC822
+@itemx STD11
+Standard for the Format of ARPA Internet Text Messages.
+
+@item RFC1036
+Standard for Interchange of USENET Messages
+
+@item RFC2045
+Format of Internet Message Bodies
+
+@item RFC2046
+Media Types
+
+@item RFC2047
+Message Header Extensions for Non-@acronym{ASCII} Text
+
+@item RFC2048
+Registration Procedures
+
+@item RFC2049
+Conformance Criteria and Examples
+
+@item RFC2231
+@acronym{MIME} Parameter Value and Encoded Word Extensions: Character Sets,
+Languages, and Continuations
+
+@item RFC1843
+HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and
+@acronym{ASCII} characters
+
+@item draft-ietf-drums-msg-fmt-05.txt
+Draft for the successor of RFC822
+
+@item RFC2112
+The @acronym{MIME} Multipart/Related Content-type
+
+@item RFC1892
+The Multipart/Report Content Type for the Reporting of Mail System
+Administrative Messages
+
+@item RFC2183
+Communicating Presentation Information in Internet Messages: The
+Content-Disposition Header Field
+
+@item RFC2646
+Documentation of the text/plain format parameter for flowed text.
+
+@end table
+
+@node GNU Free Documentation License
+@chapter GNU Free Documentation License
+@include doclicense.texi
+
+@node Index
+@chapter Index
+@printindex cp
+
+@summarycontents
+@contents
+@bye
+
+\f
+@c Local Variables:
+@c mode: texinfo
+@c coding: iso-8859-1
+@c End:
+
+@ignore
+ arch-tag: c7ef2fd0-a91c-4e10-aa52-c1a2b11b1a8d
+@end ignore
--- /dev/null
+\input texinfo
+@c %**start of header
+@setfilename ../info/erc
+@settitle ERC Manual
+@c %**end of header
+
+@dircategory Emacs
+@direntry
+* ERC: (erc). Powerful, modular, and extensible IRC client for Emacs.
+@end direntry
+
+@syncodeindex fn cp
+
+@copying
+This manual is for ERC version 5.2.
+
+Copyright @copyright{} 2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, Front-Cover texts, or Back-Cover Texts. A copy of
+the license is included in the section entitled ``GNU Free
+Documentation License'' in the Emacs manual.
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+
+All Emacs Lisp code contained in this document may be used, distributed,
+and modified without restriction.
+@end quotation
+@end copying
+
+@titlepage
+@title ERC manual
+@subtitle a full-featured IRC client
+@subtitle for GNU Emacs and XEmacs
+
+@c The following two commands
+@c start the copyright page.
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@c So the toc is printed at the start
+@contents
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@comment node-name, next, previous, up
+@top ERC
+
+@insertcopying
+@end ifnottex
+
+@menu
+* Introduction:: What is ERC?
+* Obtaining ERC:: How to get ERC releases and development
+ versions.
+* Installation:: Compiling and installing ERC.
+* Getting Started:: Quick Start guide to using ERC.
+* Keystroke Summary:: Keystrokes used in ERC buffers.
+* Modules:: Available modules for ERC.
+* Advanced Usage:: Cool ways of using ERC.
+* Getting Help and Reporting Bugs::
+* History:: The history of ERC.
+* GNU Free Documentation License:: The license for this documentation.
+* Concept Index:: Search for terms.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Obtaining ERC
+
+* Releases:: Released versions of ERC.
+* Development:: Latest unreleased development changes.
+
+Getting Started
+
+* Sample Session:: Example of connecting to the #emacs channel
+* Special Features:: Differences from standalone IRC clients
+
+Advanced Usage
+
+* Connecting:: Ways of connecting to an IRC server.
+* Sample Configuration:: An example configuration file.
+* Options:: Options that are available for ERC.
+
+@end detailmenu
+@end menu
+
+@node Introduction, Obtaining ERC, Top, Top
+@comment node-name, next, previous, up
+@chapter Introduction
+
+ERC is a powerful, modular, and extensible IRC client for Emacs.
+
+It comes with the following capabilities enabled by default.
+
+@itemize @bullet
+@item Flood control
+@item Timestamps
+@item Join channels automatically
+@item Buttonize URLs, nicknames, and other text
+@item Wrap long lines
+@item Highlight or remove IRC control characters
+@item Highlight pals, fools, and other keywords
+@item Detect netsplits
+@item Complete nicknames and commands in a programmable fashion
+@item Make displayed lines read-only
+@item Input history
+@item Track channel activity in the mode-line
+
+@end itemize
+
+@node Obtaining ERC, Installation, Introduction, Top
+@comment node-name, next, previous, up
+@chapter Obtaining ERC
+
+@menu
+* Releases:: Released versions of ERC.
+* Development:: Latest unreleased development changes.
+@end menu
+
+Note that some ERC files are not included with Emacs due to copyright or
+dependency issues. If desired, they may be found at the following
+locations, or from your local GNU mirror.
+
+@itemize @bullet
+@item @uref{http://ftp.gnu.org/gnu/erc/erc-5.2-extras.tar.gz}
+@item @uref{http://ftp.gnu.org/gnu/erc/erc-5.2-extras.zip}
+@end itemize
+
+The rest of this chapter may be skipped if you are using the version of
+ERC that comes with Emacs.
+
+@node Releases, Development, Obtaining ERC, Obtaining ERC
+@comment node-name, next, previous, up
+@section Releases
+
+Choose to install a release if you want to minimize risk.
+
+Errors are corrected in development first. User-visible changes will be
+announced on the @email{erc-discuss@@gnu.org} mailing list.
+@pxref{Getting Help and Reporting Bugs}.
+
+@cindex releases, Debian package
+@cindex Debian package for ERC
+Debian users can get ERC via apt-get. The @file{erc} package is
+available in the official Debian repository.
+
+@cindex releases, from source
+Alternatively, you can download the latest release from
+@uref{http://ftp.gnu.org/gnu/erc}, or your local GNU mirror.
+
+@node Development, , Releases, Obtaining ERC
+@comment node-name, next, previous, up
+@section Development
+@cindex development
+
+Choose the development version if you want to live on the bleeding edge
+of ERC development or try out new features before release.
+
+@subheading GNU Arch
+
+ERC is developed using GNU Arch. Downloading ERC with Arch and staying
+up-to-date involves the following steps.
+
+@enumerate
+@cindex GNU Arch, installing
+@item Install arch
+
+@itemize @bullet
+@item Debian: @kbd{apt-get install tla}.
+@item Other distributions: see @uref{ftp://ftp.gnu.org/gnu/gnu-arch/}.
+@end itemize
+
+@cindex GNU Arch, downloading ERC
+@item Register the archive.
+@example
+tla register-archive -f http://arch.sv.gnu.org/archives/erc/erc
+@end example
+
+@item Download the ERC source code.
+@example
+# Download ERC into the @file{erc} directory.
+tla get erc@@sv.gnu.org/erc--main--0 erc
+@end example
+
+@item List upstream changes that are missing from your local copy.
+Do this whenever you want to see whether new changes have been committed
+to ERC.
+
+@example
+# Change to the source directory you are interested in.
+cd erc/
+
+# Display the summary of changes
+tla missing --summary
+@end example
+
+@cindex GNU Arch, updating ERC
+@item Update to the latest version by replaying missing changes.
+@example
+cd erc
+tla update
+@end example
+
+@end enumerate
+
+If you are new to Arch and want to learn more about developing ERC with
+it, visit @uref{http://emacswiki.org/cgi-bin/wiki/ErcDevelopment} for
+full instructions.
+
+@subheading Development snapshots
+
+@cindex development snapshot
+Alternatively, the latest development snapshot may be downloaded in both
+``.tar.gz'' and ``.zip'' forms.
+
+@itemize @bullet
+@item @uref{http://www.mwolson.org/static/dist/erc-latest.tar.gz}
+@item @uref{http://www.mwolson.org/static/dist/erc-latest.zip}
+@end itemize
+
+
+@node Installation, Getting Started, Obtaining ERC, Top
+@comment node-name, next, previous, up
+@chapter Installation
+
+ERC may be compiled and installed on your machine.
+
+This section may be skipped if you are using the version of ERC that
+comes with Emacs.
+
+@subsubheading Compilation
+
+This is an optional step, since Emacs Lisp source code does not
+necessarily have to be byte-compiled. It will yield a speed increase,
+though.
+
+A working copy of Emacs or XEmacs is needed in order to compile ERC. By
+default, the program that is installed with the name @command{emacs}
+will be used.
+
+If you want to use the @command{xemacs} binary to perform the
+compilation, you would need to edit @file{Makefile} in the top-level
+directory as follows. You can put either a full path to an Emacs or
+XEmacs binary or just the command name, as long as it is in the
+@env{PATH}.
+
+@example
+EMACS = xemacs
+SITEFLAG = -no-site-file
+@end example
+
+Running @code{make} should compile the ERC source files in the
+@file{lisp} directory.
+
+@subsubheading Installation
+
+ERC may be installed into your file hierarchy by doing the following.
+
+Edit the @file{Makefile} file so that @env{ELISPDIR} points to where you
+want the source and compiled ERC files to be installed and
+@env{INFODIR} indicates where to put the ERC manual. Of course, you
+will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the
+Compilation section if you are using XEmacs.
+
+If you are installing ERC on a Debian system, you might want to change
+the value of @env{INSTALLINFO} as specified in @file{Makefile}.
+
+Run @code{make} as a normal user.
+
+Run @code{make install} as the root user if you have chosen installation
+locations that require this.
+
+
+@node Getting Started, Keystroke Summary, Installation, Top
+@comment node-name, next, previous, up
+@chapter Getting Started
+@cindex settings
+
+To use ERC, add the directory containing its files to your
+@code{load-path} variable, in your @file{.emacs} file. Then, load ERC
+itself. An example follows.
+
+@lisp
+(require 'erc)
+@end lisp
+
+Once ERC is loaded, the command @kbd{M-x erc} will start ERC and
+prompt for the server to connect to.
+
+If you want to place ERC settings in their own file, you can place them
+in @file{~/.emacs.d/.ercrc.el}, creating it if necessary.
+
+If you would rather use the Customize interface to change how ERC works,
+do @kbd{M-x customize-group RET erc RET}. In particular, ERC comes with
+lots of modules that may be enabled or disabled; to select which ones
+you want, do @kbd{M-x customize-variable RET erc-modules RET}.
+
+@menu
+* Sample Session:: Example of connecting to the #emacs channel
+* Special Features:: Differences from standalone IRC clients
+@end menu
+
+@node Sample Session, Special Features, Getting Started, Getting Started
+@comment node-name, next, previous, up
+@section Sample Session
+
+This is an example ERC session which shows how to connect to the #emacs
+channel on Freenode. Another IRC channel on Freenode that may be of
+interest is #erc, which is a channel where ERC users and developers hang
+out.
+
+@itemize @bullet
+
+@item Connect to Freenode
+
+Run @kbd{M-x erc}. Use ``irc.freenode.net'' as the IRC server, ``6667''
+as the port, and choose a nickname.
+
+@item Get used to the interface
+
+Switch to the ``irc.freenode.net:6667'' buffer, if you're not already
+there. You will see first some messages about checking for ident, and
+then a bunch of other messages that describe the current IRC server.
+
+@item Join the #emacs channel
+
+In that buffer, type ``/join SPC #emacs'' and hit @kbd{RET}. Depending
+on how you've set up ERC, either a new buffer for ``#emacs'' will be
+displayed, or a new buffer called ``#emacs'' will be created in the
+background. If the latter, switch to the ``#emacs'' buffer. You will
+see the channel topic and a list of the people who are currently on the
+channel.
+
+@item Register your nickname with Freenode
+
+If you would like to be able to talk with people privately on the
+Freenode network, you will have to ``register'' your nickname. To do
+so, switch to the ``irc.freenode.net:6667'' buffer and type ``/msg
+NickServ register <password>'', replacing ``<password>'' with your
+desired password. It should tell you that the operation was successful.
+
+@item Talk to people in the channel
+
+If you switch back to the ``#emacs'' buffer, you can type a message, and
+everyone on the channel will see it.
+
+@item Open a query buffer to talk to someone
+
+If you want to talk with someone in private (this should usually not be
+done for technical help, only for personal questions), type ``/query
+<nick>'', replacing ``<nick>'' with the nickname of the person you would
+like to talk to. Depending on how ERC is set up, you will either see a
+new buffer with the name of the person, or such a buffer will be created
+in the background and you will have to switch to it. Begin typing
+messages, and you will be able to have a conversation.
+
+Note that if the other person is not registered, you will not be able to
+talk with them.
+
+@end itemize
+
+@node Special Features, , Sample Session, Getting Started
+@comment node-name, next, previous, up
+@section Special Features
+
+ERC has some features that distinguish it from some IRC clients.
+
+@itemize @bullet
+
+@item multiple channels and multiple servers
+
+Every channel is put in a separate buffer. Several IRC servers may be
+connected to at the same time.
+
+@cindex query buffers
+@item private message separation
+
+Private conversations are treated as channels, and are put into separate
+buffers in Emacs. We call these ``query buffers''.
+
+@item highlighting
+
+Some occurences of words can be highlighted, which makes it easier to
+track different kinds of conversations.
+
+@item notification
+
+ERC can notify you that certain users are online.
+
+@item channel tracking
+
+Channels can be hidden and conversation continue in the background. You
+are notified when something is said in such a channel that is not
+currently visible. This makes it easy to get Real Work done while still
+maintaining an IRC presence.
+
+@item nick completion
+
+ERC can complete words upon hitting @kbd{TAB}, which eases the writing
+of nicknames in messages.
+
+@cindex history ring
+@item history
+
+Past actions are kept in history rings for future use. To navigate a
+history ring, hit @kbd{M-p} to go backwards and @kbd{M-n} to go
+forwards.
+
+@item multiple languages
+
+Different channels and servers may have different language encodings.
+
+In addition, it is possible to translate the messages that ERC uses into
+multiple languages. Please contact the developers of ERC at
+@email{erc-discuss@@gnu.org} if you are interested in helping with the
+translation effort.
+
+@item user scripting
+
+Users can load scripts (e.g. auto greeting scripts) when ERC starts up.
+
+It is also possible to make custom IRC commands, if you know a little
+Emacs Lisp. Just make an Emacs Lisp function and call it
+@code{erc-cmd-NEWCOMMAND}, where @code{NEWCOMMAND} is the name of the
+new command in capital letters.
+
+@item auto reconnect
+
+If the connection goes away at some point, ERC will try to reconnect
+automatically. If it fails to reconnect, and you want to try to
+manually reestablish the connection at some later point, switch to an
+ERC buffer and run the @code{/RECONNECT} command.
+
+@end itemize
+
+
+@node Keystroke Summary, Modules, Getting Started, Top
+@comment node-name, next, previous, up
+@chapter Keys Used in ERC
+@cindex keystrokes
+
+This is a summary of keystrokes available in every ERC buffer.
+
+@table @kbd
+
+@item C-a or <home> (`erc-bol')
+Go to beginning of line or end of prompt.
+
+@item RET (`erc-send-current-line')
+Send the current line
+
+@item TAB (`erc-complete-word')
+If at prompt, complete the current word.
+Otherwise, move to the next link or button.
+
+@item M-TAB (`ispell-complete-word')
+Complete the given word, using ispell.
+
+@item C-c C-a (`erc-bol')
+Go to beginning of line or end of prompt.
+
+@item C-c C-b (`erc-iswitchb')
+Use `iswitchb-read-buffer' to prompt for a ERC buffer to switch to.
+
+@item C-c C-c (`erc-toggle-interpret-controls')
+Toggle interpretation of control sequences in messages.
+
+@item C-c C-d (`erc-input-action')
+Interactively input a user action and send it to IRC.
+
+@item C-c C-e (`erc-toggle-ctcp-autoresponse')
+Toggle automatic CTCP replies (like VERSION and PING).
+
+@item C-c C-f (`erc-toggle-flood-control')
+Toggle use of flood control on sent messages.
+
+@item C-c TAB (`erc-invite-only-mode')
+Turn on the invite only mode (+i) for the current channel.
+
+@item C-c C-j (`erc-join-channel')
+Join channel. If point is at the beginning of a channel name, use that
+as default.
+
+@item C-c C-k (`erc-go-to-log-matches-buffer')
+Interactively open an erc-log-matches buffer
+
+@item C-c C-l (`erc-save-buffer-in-logs')
+Append buffer contents to the log file, if logging is enabled.
+
+@item C-c C-n (`erc-channel-names')
+Run "/names #channel" in the current channel.
+
+@item C-c C-o (`erc-get-channel-mode-from-keypress')
+Read a key sequence and call the corresponding channel mode function.
+After doing @kbd{C-c C-o}, type in a channel mode letter.
+
+@kbd{C-g} means quit.
+@kbd{RET} lets you type more than one mode at a time.
+If @kbd{l} is pressed, @code{erc-set-channel-limit} gets called.
+If @kbd{k} is pressed, @code{erc-set-channel-key} gets called.
+Anything else will be sent to `erc-toggle-channel-mode'.
+
+@item C-c C-p (`erc-part-from-channel')
+Part from the current channel and prompt for a reason.
+
+@item C-c C-q (`erc-quit-server')
+Disconnect from current server after prompting for reason.
+
+@item C-c C-r (`erc-remove-text-properties-region')
+Clears the region (start,end) in object from all colors, etc.
+
+@item C-c C-t (`erc-set-topic')
+Prompt for a topic for the current channel.
+
+@item C-c C-u (`erc-kill-input')
+Kill current input line using `erc-bol' followed by `kill-line'.
+
+@end table
+
+
+@node Modules, Advanced Usage, Keystroke Summary, Top
+@comment node-name, next, previous, up
+@chapter Modules
+@cindex modules
+
+One way to add functionality to ERC is to customize which of its many
+modules are loaded.
+
+There is a spiffy customize interface, which may be reached by typing
+@kbd{M-x customize-option erc-modules RET}. Alternatively, set
+@code{erc-modules} manually and then call @code{erc-update-modules}.
+
+The following is a list of available modules.
+
+@table @code
+
+@cindex modules, autoaway
+@item autoaway
+Set away status automatically
+
+@cindex modules, autojoin
+@item autojoin
+Join channels automatically
+
+@cindex modules, bbdb
+@item bbdb
+Integrate with the Big Brother Database
+
+@cindex modules, button
+@item button
+Buttonize URLs, nicknames, and other text
+
+@cindex modules, capab-identify
+@item capab-identify
+Mark unidentified users on freenode and other servers supporting CAPAB.
+
+@cindex modules, completion
+@cindex modules, pcomplete
+@item completion (aka pcomplete)
+Complete nicknames and commands (programmable)
+
+@cindex modules, fill
+@item fill
+Wrap long lines
+
+@cindex modules, hecomplete
+@item hecomplete
+Complete nicknames and commands (old). This is the old module---you
+might prefer the ``completion'' module instead.
+
+@cindex modules, identd
+@item identd
+Launch an identd server on port 8113
+
+@cindex modules, irccontrols
+@item irccontrols
+Highlight or remove IRC control characters
+
+@cindex modules, log
+@item log
+Save buffers in logs
+
+@cindex modules, match
+@item match
+Highlight pals, fools, and other keywords
+
+@cindex modules, menu
+@item menu
+Display a menu in ERC buffers
+
+@cindex modules, netsplit
+@item netsplit
+Detect netsplits
+
+@cindex modules, noncommands
+@item noncommands
+Don't display non-IRC commands after evaluation
+
+@cindex modules, notify
+@item notify
+Notify when the online status of certain users changes
+
+@cindex modules, page
+@item page
+Process CTCP PAGE requests from IRC
+
+@cindex modules, readonly
+@item readonly
+Make displayed lines read-only
+
+@cindex modules, replace
+@item replace
+Replace text in messages
+
+@cindex modules, ring
+@item ring
+Enable an input history
+
+@cindex modules, scrolltobottom
+@item scrolltobottom
+Scroll to the bottom of the buffer
+
+@cindex modules, services
+@item services
+Identify to Nickserv (IRC Services) automatically
+
+@cindex modules, smiley
+@item smiley
+Convert smileys to pretty icons
+
+@cindex modules, sound
+@item sound
+Play sounds when you receive CTCP SOUND requests
+
+@cindex modules, spelling
+@item spelling
+Check spelling of messages
+
+@cindex modules, stamp
+@item stamp
+Add timestamps to messages
+
+@cindex modules, track
+@item track
+Track channel activity in the mode-line
+
+@cindex modules, truncate
+@item truncate
+Truncate buffers to a certain size
+
+@cindex modules, unmorse
+@item unmorse
+Translate morse code in messages
+
+@end table
+
+@c PRE5_3: Document every option of every module in its own subnode
+
+
+@node Advanced Usage, Getting Help and Reporting Bugs, Modules, Top
+@comment node-name, next, previous, up
+@chapter Advanced Usage
+@cindex advanced topics
+
+@menu
+* Connecting:: Ways of connecting to an IRC server.
+* Sample Configuration:: An example configuration file.
+* Options:: Options that are available for ERC.
+@end menu
+
+@node Connecting, Sample Configuration, Advanced Usage, Advanced Usage
+@comment node-name, next, previous, up
+@section Connecting to an IRC Server
+@cindex connecting
+
+The easiest way to connect to an IRC server is to call @kbd{M-x erc}.
+If you want to assign this function to a keystroke, the following will
+help you figure out its parameters.
+
+@defun erc
+Select connection parameters and run ERC.
+Non-interactively, it takes the following keyword arguments.
+
+@itemize @bullet
+@item @var{server}
+@item @var{port}
+@item @var{nick}
+@item @var{password}
+@item @var{full-name}
+@end itemize
+
+That is, if called with the following arguments, @var{server} and
+@var{full-name} will be set to those values, whereas
+@code{erc-compute-port}, @code{erc-compute-nick} and
+@code{erc-compute-full-name} will be invoked for the values of the other
+parameters.
+
+@example
+(erc :server "irc.freenode.net" :full-name "Harry S Truman")
+@end example
+@end defun
+
+@subheading Server
+
+@defun erc-compute-server &optional server
+Return an IRC server name.
+
+This tries a number of increasingly more default methods until a non-nil
+value is found.
+
+@itemize @bullet
+@item @var{server} (the argument passed to this function)
+@item The @code{erc-server} option
+@item The value of the IRCSERVER environment variable
+@item The @code{erc-default-server} variable
+@end itemize
+
+@end defun
+
+@defopt erc-server nil
+IRC server to use if one is not provided.
+@end defopt
+
+@subheading Port
+
+@defun erc-compute-port &optional port
+Return a port for an IRC server.
+
+This tries a number of increasingly more default methods until a non-nil
+value is found.
+
+@itemize @bullet
+@item @var{port} (the argument passed to this function)
+@item The @code{erc-port} option
+@item The @code{erc-default-port} variable
+@end itemize
+
+@end defun
+
+@defopt erc-port
+IRC port to use if not specified.
+
+This can be either a string or a number.
+@end defopt
+
+@subheading Nick
+
+@defun erc-compute-nick &optional nick
+Return user's IRC nick.
+
+This tries a number of increasingly more default methods until a
+non-nil value is found.
+
+@itemize
+@item @var{nick} (the argument passed to this function)
+@item The @code{erc-nick} option
+@item The value of the IRCNICK environment variable
+@item The result from the @code{user-login-name} function
+@end itemize
+
+@end defun
+
+@defopt erc-nick
+Nickname to use if one is not provided.
+
+This can be either a string, or a list of strings.
+In the latter case, if the first nick in the list is already in use,
+other nicks are tried in the list order.
+@end defopt
+
+@defopt erc-nick-uniquifier
+The string to append to the nick if it is already in use.
+@end defopt
+
+@defopt erc-try-new-nick-p
+If the nickname you chose isn't available, and this option is non-nil,
+ERC should automatically attempt to connect with another nickname.
+
+You can manually set another nickname with the /NICK command.
+@end defopt
+
+@subheading Full name
+
+@defun erc-compute-full-name &optional full-name
+Return user's full name.
+
+This tries a number of increasingly more default methods until a
+non-nil value is found.
+
+@itemize @bullet
+@item @var{full-name} (the argument passed to this function)
+@item The @code{erc-user-full-name} option
+@item The value of the IRCNAME environment variable
+@item The result from the @code{user-full-name} function
+@end itemize
+
+@end defun
+
+@defopt erc-user-full-name
+User full name.
+
+This can be either a string or a function to call.
+@end defopt
+
+@node Sample Configuration, Options, Connecting, Advanced Usage
+@comment node-name, next, previous, up
+@section Sample Configuration
+@cindex configuration, sample
+
+Here is an example of configuration settings for ERC. This can go into
+your Emacs configuration file. Everything after the @code{(require
+'erc)} command can optionally go into @file{~/.emacs.d/.ercrc.el}.
+
+@lisp
+;;; Sample ERC configuration
+
+;; Add the ERC directory to load path -- you don't need this if you are
+;; using the version of ERC that comes with Emacs
+(add-to-list 'load-path "~/elisp/erc")
+
+;; Load ERC
+(require 'erc)
+
+;; Load authentication info from an external source. Put sensitive
+;; passwords and the like in here.
+(load "~/.emacs.d/.erc-auth")
+
+;; This is an example of how to make a new command. Type "/uptime" to
+;; use it.
+(defun erc-cmd-UPTIME (&rest ignore)
+ "Display the uptime of the system, as well as some load-related
+stuff, to the current ERC buffer."
+ (let ((uname-output
+ (replace-regexp-in-string
+ ", load average: " "] @{Load average@} ["
+ ;; Collapse spaces, remove
+ (replace-regexp-in-string
+ " +" " "
+ ;; Remove beginning and trailing whitespace
+ (replace-regexp-in-string
+ "^ +\\|[ \n]+$" ""
+ (shell-command-to-string "uptime"))))))
+ (erc-send-message
+ (concat "@{Uptime@} [" uname-output "]"))))
+
+;; This causes ERC to connect to the Freenode network upon hitting
+;; C-c e f. Replace MYNICK with your IRC nick.
+(global-set-key "\C-cef" (lambda () (interactive)
+ (erc :server "irc.freenode.net" :port "6667"
+ :nick "MYNICK")))
+
+;; This causes ERC to connect to the IRC server on your own machine (if
+;; you have one) upon hitting C-c e b. Replace MYNICK with your IRC
+;; nick. Often, people like to run bitlbee (http://bitlbee.org/) as an
+;; AIM/Jabber/MSN to IRC gateway, so that they can use ERC to chat with
+;; people on those networks.
+(global-set-key "\C-ceb" (lambda () (interactive)
+ (erc :server "localhost" :port "6667"
+ :nick "MYNICK")))
+
+;; Make C-c RET (or C-c C-RET) send messages instead of RET. This has
+;; been commented out to avoid confusing new users.
+;; (define-key erc-mode-map (kbd "RET") nil)
+;; (define-key erc-mode-map (kbd "C-c RET") 'erc-send-current-line)
+;; (define-key erc-mode-map (kbd "C-c C-RET") 'erc-send-current-line)
+
+;;; Options
+
+;; Join the #emacs and #erc channels whenever connecting to Freenode.
+(setq erc-autojoin-channels-alist '(("freenode.net" "#emacs" "#erc")))
+
+;; Interpret mIRC-style color commands in IRC chats
+(setq erc-interpret-mirc-color t)
+
+;; The following are commented out by default, but users of other
+;; non-Emacs IRC clients might find them useful.
+;; Kill buffers for channels after /part
+;; (setq erc-kill-buffer-on-part t)
+;; Kill buffers for private queries after quitting the server
+;; (setq erc-kill-queries-on-quit t)
+;; Kill buffers for server messages after quitting the server
+;; (setq erc-kill-server-buffer-on-quit t)
+@end lisp
+
+@node Options, , Sample Configuration, Advanced Usage
+@comment node-name, next, previous, up
+@section Options
+@cindex options
+
+@c PRE5_3: (Node) Document every ERC option (module options go in
+@c previous chapter)
+
+This section has not yet been written. For now, the easiest way to
+check out the available option for ERC is to do
+@kbd{M-x customize-group erc RET}.
+
+
+@node Getting Help and Reporting Bugs, History, Advanced Usage, Top
+@comment node-name, next, previous, up
+@chapter Getting Help and Reporting Bugs
+@cindex help, getting
+@cindex bugs, reporting
+
+After you have read this guide, if you still have questions about ERC,
+or if you have bugs to report, there are several places you can go.
+
+@itemize @bullet
+
+@item
+@uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsIRCClient} is the
+emacswiki.org page for ERC. Anyone may add tips, hints, or bug
+descriptions to it.
+
+@item
+There are several mailing lists for ERC. To subscribe, visit
+@uref{http://savannah.gnu.org/mail/?group=erc}.
+
+The mailing lists are also available on Gmane.
+(@url{http://gmane.org/}). Gmane provides additional methods for
+accessing the mailing lists, adding content to them, and searching them.
+
+@enumerate
+@item gmane.emacs.erc.announce
+Announcements
+
+@item gmane.emacs.erc.discuss
+General discussion
+
+@item gmane.emacs.erc.cvs
+Log messages for changes to the ERC source code
+
+@end enumerate
+
+@item
+You can visit the IRC Freenode channel @samp{#emacs}. Many of the
+contributors are frequently around and willing to answer your
+questions.
+
+@end itemize
+
+
+@node History, GNU Free Documentation License, Getting Help and Reporting Bugs, Top
+@comment node-name, next, previous, up
+@chapter History
+@cindex history, of ERC
+
+ERC was originally written by Alexander L. Belikoff
+@email{abel@@bfr.co.il} and Sergey Berezin
+@email{sergey.berezin@@cs.cmu.edu}. They stopped development around
+December 1999. Their last released version was ERC 2.0.
+
+P.S.: If one of the original developers of ERC reads this, we'd like to
+receive additional information for this file and hear comments in
+general.
+
+@itemize
+@item 2001
+
+In June 2001, Mario Lang @email{mlang@@delysid.org} and Alex Schroeder
+@email{alex@@gnu.org} took over development and created a ERC Project at
+@uref{http://sourceforge.net/projects/erc}.
+
+In reaction to a mail about the new ERC development effort, Sergey
+Berezin said, ``First of all, I'm glad that my version of ERC is being
+used out there. The thing is, I do not have free time and enough
+incentive anymore to work on ERC, so I would be happy if you guys take
+over the project entirely.''
+
+So we happily hacked away on ERC, and soon after (September 2001)
+released the next "stable" version, 2.1.
+
+Most of the development of the new ERC happened on #emacs on
+irc.openprojects.net. Over time, many people contributed code, ideas,
+bugfixes, and a lot of alpha/beta/gamma testing.
+
+See the @file{CREDITS} file for a list of contributors.
+
+@item 2003
+
+ERC 3.0 was released.
+
+@item 2004
+
+ERC 4.0 was released.
+
+@item 2005
+
+ERC 5.0 was released. Michael Olson @email{mwolson@@gnu.org} became
+the release manager and eventually the maintainer.
+
+After some discussion between him and the Emacs developers, it was
+decided to include ERC in Emacs.
+
+@item 2006
+
+ERC 5.1 was released. It was subsequently included in Emacs 22.
+
+ERC became an official GNU project, and development moved to
+@uref{http://sv.gnu.org/projects/erc}. We switched to using GNU Arch as
+our revision control system. Our mailing list address changed as well.
+
+@end itemize
+
+@node GNU Free Documentation License, Concept Index, History, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Concept Index, , GNU Free Documentation License, Top
+@comment node-name, next, previous, up
+@unnumbered Index
+
+@printindex cp
+
+@bye
+
+@ignore
+ arch-tag: cf9cfaff-fc12-4297-ad15-ec2493002b1e
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename ../info/eshell
+@settitle Eshell: The Emacs Shell
+@synindex vr fn
+@c %**end of header
+
+@copying
+This manual is for Eshell, the Emacs shell.
+
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Eshell: (eshell). A command shell implemented in Emacs Lisp.
+@end direntry
+
+@setchapternewpage on
+
+@titlepage
+@sp 4
+@c The title is printed in a large font.
+@center @titlefont{User's Guide}
+@sp
+@center @titlefont{to}
+@sp
+@center @titlefont{Eshell: The Emacs Shell}
+@ignore
+@sp 2
+@center release 2.4
+@c -release-
+@end ignore
+@sp 3
+@center John Wiegley
+@c -date-
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@c ================================================================
+@c The real text starts here
+@c ================================================================
+
+@ifnottex
+@node Top, What is Eshell?, (dir), (dir)
+@top Eshell
+
+This manual documents Eshell, a shell-like command interpretor
+implemented in Emacs Lisp. It invokes no external processes except for
+those requested by the user. It is intended to be a functional
+replacement for command shells such as @command{bash}, @command{zsh},
+@command{rc}, or @command{4dos}; since Emacs itself is capable of
+handling the sort of tasks accomplished by those tools.
+@c This manual is updated to release 2.4 of Eshell.
+@end ifnottex
+
+@menu
+* What is Eshell?:: A brief introduction to the Emacs Shell.
+* Command basics:: The basics of command usage.
+* Commands::
+* Arguments::
+* Input/Output::
+* Process control::
+* Extension modules::
+* Extras and Goodies::
+* Bugs and ideas:: Known problems, and future ideas.
+* GNU Free Documentation License:: The license for this documentation.
+* Concept Index::
+* Function and Variable Index::
+* Key Index::
+@end menu
+
+@node What is Eshell?
+@chapter What is Eshell?
+@cindex what is Eshell?
+@cindex Eshell, what it is
+
+Eshell is a @dfn{command shell} written in Emacs Lisp. Everything it
+does, it uses Emacs' facilities to do. This means that Eshell is as
+portable as Emacs itself. It also means that cooperation with Lisp code
+is natural and seamless.
+
+What is a command shell? To properly understand the role of a shell,
+it's necessary to visualize what a computer does for you. Basically, a
+computer is a tool; in order to use that tool, you must tell it what to
+do---or give it ``commands.'' These commands take many forms, such as
+clicking with a mouse on certain parts of the screen. But that is only
+one form of command input.
+
+By far the most versatile way to express what you want the computer to
+do is by using an abbreviated language called @dfn{script}. In
+script, instead of telling the computer, ``list my files, please'',
+one writes a standard abbreviated command word---@samp{ls}. Typing
+@samp{ls} in a command shell is a script way of telling the computer
+to list your files.@footnote{This is comparable to viewing the
+contents of a folder using a graphical display.}
+
+The real flexibility of this approach is apparent only when you realize
+that there are many, many different ways to list files. Perhaps you
+want them sorted by name, sorted by date, in reverse order, or grouped
+by type. Most graphical browsers have simple ways to express this. But
+what about showing only a few files, or only files that meet a certain
+criteria? In very complex and specific situations, the request becomes
+too difficult to express using a mouse or pointing device. It is just
+these kinds of requests that are easily solved using a command shell.
+
+For example, what if you want to list every Word file on your hard
+drive, larger than 100 kilobytes in size, and which hasn't been looked
+at in over six months? That is a good candidate list for deletion, when
+you go to clean up your hard drive. But have you ever tried asking your
+computer for such a list? There is no way to do it! At least, not
+without using a command shell.
+
+The role of a command shell is to give you more control over what your
+computer does for you. Not everyone needs this amount of control, and
+it does come at a cost: Learning the necessary script commands to
+express what you want done. A complicated query, such as the example
+above, takes time to learn. But if you find yourself using your
+computer frequently enough, it is more than worthwhile in the long run.
+Any tool you use often deserves the time spent learning to master it.
+@footnote{For the understandably curious, here is what that command
+looks like: But don't let it fool you; once you know what's going on,
+it's easier than it looks: @code{ls -lt **/*.doc(Lk+50aM+5)}.}
+
+@menu
+* Contributors to Eshell:: People who have helped out!
+@end menu
+
+@node Contributors to Eshell
+@section Contributors to Eshell
+@cindex contributors
+@cindex authors
+
+Contributions to Eshell are welcome. I have limited time to work on
+this project, but I will gladly add any code you contribute to me to
+this package.
+
+The following persons have made contributions to Eshell.
+
+@itemize @bullet
+@item
+Eli Zaretskii made it possible for Eshell to run without requiring
+asynchronous subprocess support. This is important for MS-DOS, which
+does not have such support.@refill
+
+@item
+Miles Bader contributed many fixes during the port to Emacs 21.@refill
+
+@item
+Stefan Monnier fixed the things which bothered him, which of course made
+things better for all.@refill
+
+@item
+Gerd Moellmann also helped to contribute bug fixes during the initial
+integration with Emacs 21.@refill
+
+@item
+Alex Schroeder contributed code for interactively querying the user
+before overwriting files.@refill
+
+@item
+Sudish Joseph helped with some XEmacs compatibility issues.@refill
+@end itemize
+
+Apart from these, a lot of people have sent suggestions, ideas,
+requests, bug reports and encouragement. Thanks a lot! Without you
+there would be no new releases of Eshell.
+
+@node Command basics
+@chapter Basic overview
+
+A command shell is a means of entering verbally-formed commands. This
+is really all that it does, and every feature described in this manual
+is a means to that end. Therefore, it's important to take firm hold on
+exactly what a command is, and how it fits in the overall picture of
+things.
+
+@menu
+* Commands verbs:: Commands always begin with a verb.
+* Command arguments:: Some verbs require arguments.
+@end menu
+
+@node Commands verbs
+@section Commands verbs
+
+Commands are expressed using @dfn{script}, a special shorthand language
+computers can understand with no trouble. Script is an extremely simple
+language; oddly enough, this is what makes it look so complicated!
+Whereas normal languages use a variety of embellishments, the form of a
+script command is always:
+
+@example
+@var{verb} [@var{arguments}]
+@end example
+
+The verb expresses what you want your computer to do. There are a fixed
+number of verbs, although this number is usually quite large. On the
+author's computer, it reaches almost 1400 in number. But of course,
+only a handful of these are really necessary.
+
+Sometimes, the verb is all that's written. A verb is always a single
+word, usually related to the task it performs. @command{reboot} is a
+good example. Entering that on GNU/Linux will reboot the
+computer---assuming you have sufficient privileges.
+
+Other verbs require more information. These are usually very capable
+verbs, and must be told specifically what to do. The extra information
+is given in the form of @dfn{arguments}. For example, the
+@command{echo} verb prints back whatever arguments you type. It
+requires these arguments to know what to echo. A proper use of
+@command{echo} looks like this:
+
+@example
+echo This is an example of using echo!
+@end example
+
+This script command causes the computer to echo back: ``This is an
+example of using echo!''
+
+Although command verbs are always simple words, like @command{reboot} or
+@command{echo}, arguments may have a wide variety of forms. There are
+textual arguments, numerical arguments---even Lisp arguments.
+Distinguishing these different types of arguments requires special
+typing, for the computer to know exactly what you mean.
+
+@node Command arguments
+@section Command arguments
+
+Eshell recognizes several different kinds of command arguments:
+
+@enumerate
+@item Strings (also called textual arguments)
+@item Numbers (floating point or integer)
+@item Lisp lists
+@item Lisp symbols
+@item Emacs buffers
+@item Emacs process handles
+@end enumerate
+
+Most users need to worry only about the first two. The third, Lisp lists,
+occur very frequently, but almost always behind the scenes.
+
+Strings are the most common type of argument, and consist of nearly any
+character. Special characters---those used by Eshell
+specifically---must be preceded by a backslash (@samp{\}). When in doubt, it
+is safe to add backslashes anywhere and everywhere.
+
+Here is a more complicated @command{echo} example:
+
+@example
+echo A\ Multi-word\ Argument\ With\ A\ \$\ dollar
+@end example
+
+Beyond this, things get a bit more complicated. While not beyond the
+reach of someone wishing to learn, it is definitely beyond the scope of
+this manual to present it all in a simplistic manner. Get comfortable
+with Eshell as a basic command invocation tool, and learn more about the
+commands on your system; then come back when it all sits more familiarly
+on your mind. Have fun!
+
+@node Commands
+@chapter Commands
+
+@menu
+* Invocation::
+* Completion::
+* Aliases::
+* History::
+* Scripts::
+* Built-ins::
+@end menu
+
+Essentially, a command shell is all about invoking commands---and
+everything that entails. So understanding how Eshell invokes commands
+is the key to comprehending how it all works.
+
+@node Invocation
+@section Invocation
+
+Unlike regular system shells, Eshell never invokes kernel functions
+directly, such as @code{exec(3)}. Instead, it uses the Lisp functions
+available in the Emacs Lisp library. It does this by transforming the
+command you specify into a callable Lisp form.@footnote{To see the Lisp
+form that will be invoked, type: @samp{eshell-parse-command "echo
+hello"}}
+
+This transformation, from the string of text typed at the command
+prompt, to the ultimate invocation of either a Lisp function or external
+command, follows these steps:
+
+@enumerate
+@item Parse the command string into separate arguments.
+@item
+@end enumerate
+
+@node Completion
+@section Completion
+
+@node Aliases
+@section Aliases
+
+@node History
+@section History
+
+Eshell knows a few built-in variables:
+
+@table @code
+
+@item $+
+@vindex $+
+This variable always contains the current working directory.
+
+@item $-
+@vindex $-
+This variable always contains the previous working directory (the
+current working directory from before the last @code{cd} command).
+
+@end table
+
+@node Scripts
+@section Scripts
+
+
+@node Built-ins
+@section Built-in commands
+
+Here is a list of built-in commands that Eshell knows about:
+
+@table @code
+
+@item cd
+@findex cd
+This command changes the current working directory. Usually, it is
+invoked as @samp{cd foo} where @file{foo} is the new working
+directory. But @code{cd} knows about a few special arguments:
+
+When it receives no argument at all, it changes to the home directory.
+
+Giving the command @samp{cd -} changes back to the previous working
+directory (this is the same as @samp{cd $-}).
+
+The command @samp{cd =} shows the directory stack. Each line is
+numbered.
+
+With @samp{cd =foo}, Eshell searches the directory stack for a
+directory matching the regular expression @samp{foo} and changes to
+that directory.
+
+With @samp{cd -42}, you can access the directory stack by number.
+
+@end table
+
+
+@node Arguments
+@chapter Arguments
+
+@menu
+* The Parser::
+* Variables::
+* Substitution::
+* Globbing::
+* Predicates::
+@end menu
+
+@node The Parser
+@section The Parser
+
+@node Variables
+@section Variables
+
+@node Substitution
+@section Substitution
+
+@node Globbing
+@section Globbing
+
+@node Predicates
+@section Predicates
+
+
+@node Input/Output
+@chapter Input/Output
+
+@node Process control
+@chapter Process control
+
+
+@node Extension modules
+@chapter Extension modules
+
+@menu
+* Writing a module::
+* Module testing::
+* Directory handling::
+* Key rebinding::
+* Smart scrolling::
+* Terminal emulation::
+* Built-in UNIX commands::
+@end menu
+
+@node Writing a module
+@section Writing a module
+
+@node Module testing
+@section Module testing
+
+@node Directory handling
+@section Directory handling
+
+@node Key rebinding
+@section Key rebinding
+
+@node Smart scrolling
+@section Smart scrolling
+
+@node Terminal emulation
+@section Terminal emulation
+
+@node Built-in UNIX commands
+@section Built-in UNIX commands
+
+
+@node Extras and Goodies
+@chapter Extras and Goodies
+
+@node Bugs and ideas
+@chapter Bugs and ideas
+@cindex reporting bugs and ideas
+@cindex bugs, how to report them
+@cindex author, how to reach
+@cindex email to the author
+@cindex FAQ
+@cindex problems, list of common
+
+If you find a bug or misfeature, don't hesitate to let me know! Send
+email to @email{johnw@@gnu.org}. Feature requests should also be sent
+there. I prefer discussing one thing at a time. If you find several
+unrelated bugs, please report them separately.
+
+If you have ideas for improvements, or if you have written some
+extensions to this package, I would like to hear from you. I hope you
+find this package useful!
+
+@menu
+* Known problems::
+@end menu
+
+@node Known problems
+@section Known problems
+@cindex known bugs
+@cindex bugs, known
+
+Below is complete list of known problems with Eshell version 2.4.2,
+which is the version included with Emacs 22.
+
+@table @asis
+@item Documentation incomplete
+
+@item Differentiate between aliases and functions
+
+Allow for a bash-compatible syntax, such as:
+
+@example
+alias arg=blah
+function arg () @{ blah $* @}
+@end example
+
+@item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} outputs result after prompt
+
+In fact, piping to a process from a looping construct doesn't work in
+general. If I change the call to @code{eshell-copy-handles} in
+@code{eshell-rewrite-for-command} to use @code{eshell-protect}, it seems
+to work, but the output occurs after the prompt is displayed. The whole
+structured command thing is too complicated at present.
+
+@item Error with @command{bc} in @code{eshell-test}
+
+On some XEmacs system, the subprocess interaction test fails
+inexplicably, although @command{bc} works fine at the command prompt.
+
+@item Eshell does not delete @file{*Help*} buffers in XEmacs 21.1.8+
+
+In XEmacs 21.1.8, the @file{*Help*} buffer has been renamed such that
+multiple instances of the @file{*Help*} buffer can exist.
+
+@item Pcomplete sometimes gets stuck
+
+You press @key{TAB}, but no completions appear, even though the
+directory has matching files. This behavior is rare.
+
+@item @samp{grep python $<rpm -qa>} doesn't work, but using @samp{*grep} does
+
+This happens because the @code{grep} Lisp function returns immediately,
+and then the asynchronous @command{grep} process expects to examine the
+temporary file, which has since been deleted.
+
+@item Problem with C-r repeating text
+
+If the text @emph{before point} reads "./run", and you type @kbd{C-r r u
+n}, it will repeat the line for every character typed.
+
+@item Backspace doesn't scroll back after continuing (in smart mode)
+
+Hitting space during a process invocation, such as @command{make}, will
+cause it to track the bottom of the output; but backspace no longer
+scrolls back.
+
+@item It's not possible to fully @code{unload-feature} Eshell
+
+@item Menu support was removed, but never put back
+
+@item Using C-p and C-n with rebind gets into a locked state
+
+This happened a few times in Emacs 21, but has been unreproducible
+since.
+
+@item If an interactive process is currently running, @kbd{M-!} doesn't work
+
+@item Use a timer instead of @code{sleep-for} when killing child processes
+
+@item Piping to a Lisp function is not supported
+
+Make it so that the Lisp command on the right of the pipe is repeatedly
+called with the input strings as arguments. This will require changing
+@code{eshell-do-pipeline} to handle non-process targets.
+
+@item Input redirection is not supported
+
+See the above entry.
+
+@item Problem running @command{less} without arguments on Windows
+
+The result in the Eshell buffer is:
+
+@example
+Spawning child process: invalid argument
+@end example
+
+Also a new @command{less} buffer was created with nothing in it@dots{}
+(presumably this holds the output of @command{less}).
+
+If @command{less.exe} is invoked from the Eshell command line, the
+expected output is written to the buffer.
+
+Note that this happens on NT-Emacs 20.6.1 on Windows 2000. The term.el
+package and the supplied shell both use the @command{cmdproxy} program
+for running shells.
+
+@item Implement @samp{-r}, @samp{-n} and @samp{-s} switches for @command{cp}
+
+@item Make @kbd{M-5 M-x eshell} switch to ``*eshell<5>*'', creating if need be
+
+@item @samp{mv @var{dir} @var{file}.tar} does not remove directories
+
+This is because the tar option --remove-files doesn't do so. Should it
+be Eshell's job?
+
+@item Bind @code{standard-output} and @code{standard-error}
+
+This would be so that if a Lisp function calls @code{print}, everything
+will happen as it should (albeit slowly).
+
+@item When an extension module fails to load, @samp{cd /} gives a Lisp error
+
+@item If a globbing pattern returns one match, should it be a list?
+
+@item Make sure syntax table is correct in Eshell mode
+
+So that @kbd{M-DEL} acts in a predictable manner, etc.
+
+@item Allow all Eshell buffers to share the same history and list-dir
+
+@item There is a problem with script commands that output to @file{/dev/null}
+
+If a script file, somewhere in the middle, uses @samp{> /dev/null},
+output from all subsequent commands is swallowed.
+
+@item Split up parsing of text after @samp{$} in @file{esh-var.el}
+
+Make it similar to the way that @file{esh-arg.el} is structured.
+Then add parsing of @samp{$[?\n]}.
+
+@item After pressing @kbd{M-RET}, redisplay before running the next command
+
+@item Argument predicates and modifiers should work anywhere in a path
+
+@example
+/usr/local/src/editors/vim $ vi **/CVS(/)/Root(.)
+Invalid regexp: "Unmatched ( or \\("
+@end example
+
+With @command{zsh}, the glob above expands to all files named
+@file{Root} in directories named @file{CVS}.
+
+@item Typing @samp{echo $@{locate locate@}/bin<TAB>} results in a Lisp error
+
+Perhaps it should interpolate all permutations, and make that the
+globbing result, since otherwise hitting return here will result in
+``(list of filenames)/bin'', which is never valuable. Thus, one could
+@command{cat} only C backup files by using @samp{ls $@{identity *.c@}~}.
+In that case, having an alias command name @command{glob} for
+@command{identity} would be useful.
+
+@item Once symbolic mode is supported for @command{umask}, implement @command{chmod} in Lisp
+
+@item Create @code{eshell-expand-file-name}
+
+This would use a data table to transform things such as @samp{~+},
+@samp{...}, etc.
+
+@item Abstract @file{em-smart.el} into @file{smart-scroll.el}
+
+It only really needs: to be hooked onto the output filter and the
+pre-command hook, and to have the input-end and input-start markers.
+And to know whether the last output group was ``successful.''
+
+@item Allow for fully persisting the state of Eshell
+
+This would include: variables, history, buffer, input, dir stack, etc.
+
+@item Implement D as an argument predicate
+
+It means that files beginning with a dot should be included in the
+glob match.
+
+@item A comma in a predicate list should mean OR
+
+At the moment, this is not supported.
+
+@item Error if a glob doesn't expand due to a predicate
+
+An error should be generated only if @code{eshell-error-if-no-glob} is
+non-@code{nil}.
+
+@item @samp{(+ RET SPC TAB} does not cause @code{indent-according-to-mode} to occur
+
+@item Create @code{eshell-auto-accumulate-list}
+
+This is a list of commands for which, if the user presses @kbd{RET}, the
+text is staged as the next Eshell command, rather than being sent to the
+current interactive process.
+
+@item Display file and line number if an error occurs in a script
+
+@item @command{wait} doesn't work with process ids at the moment
+
+@item Enable the direct-to-process input code in @file{em-term.el}
+
+@item Problem with repeating @samp{echo $@{find /tmp@}}
+
+With smart display active, if @kbd{RET} is held down, after a while it
+can't keep up anymore and starts outputting blank lines. It only
+happens if an asynchronous process is involved@dots{}
+
+I think the problem is that @code{eshell-send-input} is resetting the
+input target location, so that if the asynchronous process is not done
+by the time the next @kbd{RET} is received, the input processor thinks
+that the input is meant for the process; which, when smart display is
+enabled, will be the text of the last command line! That is a bug in
+itself.
+
+In holding down @kbd{RET} while an asynchronous process is running,
+there will be a point in between termination of the process, and the
+running of @code{eshell-post-command-hook}, which would cause
+@code{eshell-send-input} to call @code{eshell-copy-old-input}, and then
+process that text as a command to be run after the process. Perhaps
+there should be a way of killing pending input between the death of the
+process, and the @code{post-command-hook}.
+
+@item Allow for a more aggressive smart display mode
+
+Perhaps toggled by a command, that makes each output block a smart
+display block.
+
+@item Create more meta variables
+
+@table @samp
+@item $!
+The reason for the failure of the last disk command, or the text of the
+last Lisp error.
+
+@item $=
+A special associate array, which can take references of the form
+@samp{$=[REGEXP]}. It indexes into the directory ring.
+@end table
+
+@item Eshell scripts can't execute in the background
+
+@item Support zsh's ``Parameter Expansion'' syntax, i.e. @samp{$@{@var{name}:-@var{val}@}}
+
+@item Write an @command{info} alias that can take arguments
+
+So that the user can enter @samp{info chmod}, for example.
+
+@item Create a mode @code{eshell-browse}
+
+It would treat the Eshell buffer as a outline. Collapsing the outline
+hides all of the output text. Collapsing again would show only the
+first command run in each directory
+
+@item Allow other revisions of a file to be referenced using @samp{file@{rev@}}
+
+This would be expanded by @code{eshell-expand-file-name} (see above).
+
+@item Print ``You have new mail'' when the ``Mail'' icon is turned on
+
+@item Implement @kbd{M-|} for Eshell
+
+@item Implement input redirection
+
+If it's a Lisp function, input redirection implies @command{xargs} (in a
+way@dots{}). If input redirection is added, also update the
+@code{file-name-quote-list}, and the delimiter list.
+
+@item Allow @samp{#<@var{word} @var{arg}>} as a generic syntax
+
+With the handling of @emph{word} specified by an
+@code{eshell-special-alist}.
+
+@item In @code{eshell-veal-using-options}, allow a @code{:complete} tag
+
+It would be used to provide completion rules for that command. Then the
+macro will automagically define the completion function.
+
+@item For @code{eshell-command-on-region}, apply redirections to the result
+
+So that @samp{+ > 'blah} would cause the result of the @code{+} (using
+input from the current region) to be inserting into the symbol
+@code{blah}.
+
+If an external command is being invoked, the input is sent as standard
+input, as if a @samp{cat <region> |} had been invoked.
+
+If a Lisp command, or an alias, is invoked, then if the line has no
+newline characters, it is divided by whitespace and passed as arguments
+to the Lisp function. Otherwise, it is divided at the newline
+characters. Thus, invoking @code{+} on a series of numbers will add
+them; @code{min} would display the smallest figure, etc.
+
+@item Write @code{eshell-script-mode} as a minor mode
+
+It would provide syntax, abbrev, highlighting and indenting support like
+@code{emacs-lisp-mode} and @code{shell-mode}.
+
+@item In the history mechanism, finish the @command{bash}-style support
+
+This means @samp{!n}, @samp{!#}, @samp{!:%}, and @samp{!:1-} as separate
+from @samp{!:1*}.
+
+@item Support the -n command line option for @command{history}
+
+@item Implement @command{fc} in Lisp
+
+@item Specifying a frame as a redirection target should imply the currently active window's buffer
+
+@item Implement @samp{>@var{func-or-func-list}}
+
+This would allow for an ``output translators'', that take a function to
+modify output with, and a target. Devise a syntax that works well with
+pipes, and can accommodate multiple functions (i.e., @samp{>'(upcase
+regexp-quote)} or @samp{>'upcase}).
+
+@item Allow Eshell to read/write to/from standard input and output
+
+This would be optional, rather than always using the Eshell buffer.
+This would allow it to be run from the command line (perhaps).
+
+@item Write a @command{help} command
+
+It would call subcommands with @option{--help}, or @option{-h} or
+@option{/?}, as appropriate.
+
+@item Implement @command{stty} in Lisp
+
+@item Support @command{rc}'s matching operator, e.g. @samp{~ (@var{list}) @var{regexp}}
+
+@item Implement @command{bg} and @command{fg} as editors of @code{eshell-process-list}
+
+Using @command{bg} on a process that is already in the background does
+nothing. Specifying redirection targets replaces (or adds) to the list
+current being used.
+
+@item Have @command{jobs} print only the processes for the current shell
+
+@item How can Eshell learn if a background process has requested input?
+
+@item Support @samp{2>&1} and @samp{>&} and @samp{2>} and @samp{|&}
+
+The syntax table for parsing these should be customizable, such that the
+user could change it to use rc syntax: @samp{>[2=1]}.
+
+@item Allow @samp{$_[-1]}, which would indicate the last element of the array
+
+@item Make @samp{$x[*]} equal to listing out the full contents of @samp{x}
+
+Return them as a list, so that @samp{$_[*]} is all the arguments of the
+last command.
+
+@item Copy ANSI code handling from @file{term.el} into @file{em-term.el}
+
+Make it possible for the user to send char-by-char to the underlying
+process. Ultimately, I should be able to move away from using term.el
+altogether, since everything but the ANSI code handling is already part
+of Eshell. Then, things would work correctly on MS-Windows as well
+(which doesn't have @file{/bin/sh}, although @file{term.el} tries to use
+it).
+
+@item Make the shell spawning commands be visual
+
+That is, make (@command{su}, @command{bash}, @command{telnet},
+@command{rlogin}, @command{rsh}, etc.) be part of
+@code{eshell-visual-commands}. The only exception is if the shell is
+being used to invoke a single command. Then, the behavior should be
+based on what that command is.
+
+@item Create a smart viewing command named @command{open}
+
+This would search for some way to open its argument (similar to opening
+a file in the Windows Explorer).
+
+@item Alias @command{read} to be the same as @command{open}, only read-only
+
+@item Write a @command{tail} command which uses @code{view-file}
+
+It would move point to the end of the buffer, and then turns on
+auto-revert mode in that buffer at frequent intervals---and a
+@command{head} alias which assumes an upper limit of
+@code{eshell-maximum-line-length} characters per line.
+
+@item Make @command{dgrep} load @code{dired}, mark everything, then invoke @code{dired-do-search}
+
+@item Write mesh.c
+
+This would run Emacs with the appropriate arguments to invoke Eshell
+only. That way, it could be listed as a login shell.
+
+@item Use an intangible @code{PS2} string for multi-line input prompts
+
+@item Auto-detect when a command is visual, by checking @code{TERMCAP} usage
+
+@item The first keypress after @kbd{M-x watson} triggers `eshell-send-input'
+
+@item Make @kbd{/} electric
+
+So that it automatically expands and corrects pathnames. Or make
+pathname completion for Pcomplete auto-expand @samp{/u/i/std<TAB>} to
+@samp{/usr/include/std<TAB>}.
+
+@item Write the @command{pushd} stack to disk along with @code{last-dir-ring}
+
+@item Add options to @code{eshell/cat} which would allow it to sort and uniq
+
+@item Implement @command{wc} in Lisp
+
+Add support for counting sentences, paragraphs, pages, etc.
+
+@item Once piping is added, implement @command{sort} and @command{uniq} in Lisp
+
+@item Implement @command{touch} in Lisp
+
+@item Implement @command{comm} in Lisp
+
+@item Implement an @command{epatch} command in Lisp
+
+This would call @code{ediff-patch-file}, or @code{ediff-patch-buffer},
+depending on its argument.
+
+@item Have an option such that @samp{ls -l} generates a dired buffer
+
+@item Write a version of @command{xargs} based on command rewriting
+
+That is, @samp{find X | xargs Y} would be indicated using @samp{Y
+$@{find X@}}. Maybe @code{eshell-do-pipelines} could be changed to
+perform this on-thy-fly rewriting.
+
+@item Write an alias for @command{less} that brings up a @code{view-mode} buffer
+
+Such that the user can press @key{SPC} and @key{DEL}, and then @key{q}
+to return to Eshell. It would be equivalent to:
+@samp{X > #<buffer Y>; view-buffer #<buffer Y>}.
+
+@item Make @code{eshell-mode} as much a full citizen as @code{shell-mode}
+
+Everywhere in Emacs where @code{shell-mode} is specially noticed, add
+@code{eshell-mode} there.
+
+@item Permit the umask to be selectively set on a @command{cp} target
+
+@item Problem using @kbd{M-x eshell} after using @code{eshell-command}
+
+If the first thing that I do after entering Emacs is to run
+@code{eshell-command} and invoke @command{ls}, and then use @kbd{M-x
+eshell}, it doesn't display anything.
+
+@item @kbd{M-RET} during a long command (using smart display) doesn't work
+
+Since it keeps the cursor up where the command was invoked.
+
+@end table
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
+@node Function and Variable Index
+@unnumbered Function and Variable Index
+
+@printindex fn
+
+@node Key Index
+@unnumbered Key Index
+
+@printindex ky
+@bye
+
+@ignore
+ arch-tag: 776409ba-cb15-42b9-b2b6-d2bdc7ebad01
+@end ignore
--- /dev/null
+\input texinfo.tex
+@c %**start of header
+@setfilename ../info/eudc
+@settitle Emacs Unified Directory Client (EUDC) Manual
+@afourpaper
+@c %**end of header
+
+@copying
+This file documents EUDC v1.30b.
+
+EUDC is the Emacs Unified Directory Client, a common interface to
+directory servers using various protocols such as LDAP or the CCSO white
+pages directory system (PH/QI)
+
+Copyright @copyright{} 1998, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
+Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* EUDC: (eudc). An Emacs client for directory servers (LDAP, PH).
+@end direntry
+
+@footnotestyle end
+
+@titlepage
+@title{EUDC Manual}
+@subtitle{The Emacs Unified Directory Client}
+@author by Oscar Figueiredo
+@code{1.30b}
+
+@page
+@vskip 0pt plus 1fill
+@insertcopying
+@end titlepage
+
+@ifnottex
+@node Top, Overview, (dir), (dir)
+@comment node-name, next, previous, up
+
+
+This manual documents EUDC v1.30b, the Emacs Unified Directory Client.
+
+A common interface to directory servers using various protocols such as
+LDAP or the CCSO white pages directory system (PH/QI)
+
+@end ifnottex
+
+@menu
+* Overview:: Summary of EUDC features
+* Installation:: How to install EUDC
+* Usage:: The various usage possibilities explained
+* Credits:: Who's done what
+* GNU Free Documentation License:: The license for this documentation.
+* Command and Function Index::
+* Variables Index::
+@end menu
+
+
+
+
+
+@node Overview, Installation, Top, Top
+@comment node-name, next, previous, up
+@chapter Overview
+
+EUDC, the @dfn{Emacs Unified Directory Client}, provides a common user
+interface to access directory servers using different directory
+protocols.
+
+Currently supported back-ends are:
+
+@itemize @bullet
+@item
+LDAP, Lightweight Directory Access Protocol
+@item
+CCSO PH/QI
+@item
+BBDB, Big Brother's Insidious Database
+@end itemize
+
+The main features of the EUDC interface are:
+
+@itemize @bullet
+@item
+Queries using a customizable form
+@item
+Inline query expansion (for instance you can expand a name
+to an email address in a mail message buffer using a server as an
+address book)
+@item
+Multiple servers can be tried in turn until a match is found for an
+inline query
+@item
+Fast minibuffer queries for email addresses and phone numbers
+@item
+Interface to BBDB to let you insert server records into your own BBDB database
+(@pxref{Top,,BBDB,bbdb,BBDB Manual})
+@end itemize
+
+@menu
+* LDAP:: What is LDAP ?
+* CCSO PH/QI:: What is CCSO, PH, QI ?
+* BBDB:: What is BBDB ?
+@end menu
+
+
+
+@node LDAP, CCSO PH/QI, Overview, Overview
+@comment node-name, next, previous, up
+@section LDAP
+
+LDAP, @dfn{the Lightweight Directory Access Protocol}, is a communication
+protocol for directory applications defined in RFC 1777.
+
+Quoted from RFC 1777:
+
+@quotation
+[LDAP] is designed to provide access to the X.500 Directory while not
+incurring the resource requirements of the Directory Access Protocol
+(DAP). This protocol is specifically targeted at simple management
+applications and browser applications that provide simple read/write
+interactive access to the X.500 Directory, and is intended to be a
+complement to the DAP itself.
+@end quotation
+
+LDAP servers usually store (but are not limited to) information about
+people such as their name, phone number, email address, office
+location, etc@enddots{} More information about LDAP can be found at
+@url{http://www.openldap.org/}
+
+EUDC requires external support to access LDAP directory servers
+(@pxref{LDAP Requirements})
+
+
+@node CCSO PH/QI, BBDB, LDAP, Overview
+@comment node-name, next, previous, up
+@section CCSO PH/QI
+
+The Central Computing Services Office (CCSO) of the University of
+Illinois at Urbana Champaign (UIUC) created and freely distributes a
+directory system that is currently in use in more than 300 organizations
+around the world. The system records information about people such as
+their address, phone number, email, academic information or any other
+details it was configured to.
+
+The system consists of two parts: a database server traditionally called
+@samp{qi} and a command-line client called @samp{ph}.
+@url{ftp://uiarchive.cso.uiuc.edu/pub/packages/ph} is the main
+distribution site. @url{http://www.uiuc.edu/cgi-bin/ph/lookup?Query=.}
+provides a listing of the active @samp{qi} servers.
+
+The original command-line @samp{ph} client that comes with the
+@samp{ph/qi} distribution provides additional features like the
+possibility to communicate with the server in login-mode which makes it
+possible to change records in the database. This is not implemented in
+EUDC.
+
+
+@node BBDB, , CCSO PH/QI, Overview
+@comment node-name, next, previous, up
+@section BBDB
+
+BBDB is the @dfn{Big Brother's Insidious Database}, a package for Emacs
+originally written by Jamie Zawinski which provides rolodex-like
+database functionality featuring tight integration with the Emacs mail
+and news readers.
+
+It is often used as an enhanced email address book.
+
+EUDC considers BBDB as a directory server back end just like LDAP or
+PH/QI servers, though BBDB has no client/server protocol and thus always
+resides locally on your machine. The point in this is not to offer an
+alternate way to query your BBDB database (BBDB itself provides much
+more flexible ways to do that), but rather to offer an interface to your
+local directory that is consistent with the interface to external
+directories (LDAP, PH/QI). This is particularly interesting when
+performing queries on multiple servers.
+
+EUDC also offers a means to insert results from directory queries into
+your own local BBDB (@pxref{Creating BBDB Records})
+
+@node Installation, Usage, Overview, Top
+@comment node-name, next, previous, up
+@chapter Installation
+
+Add the following to your @file{.emacs} init file:
+@lisp
+(require 'eudc)
+@end lisp
+This will install EUDC at startup.
+
+After installing EUDC you will find (the next time you launch Emacs) a
+new @code{Directory Search} submenu in the @samp{Tools} menu that will
+give you access to EUDC.
+
+You may also find it useful to add the following to your @file{.emacs}
+initialization file to add a shortcut for email address expansion in
+email composition buffers (@pxref{Inline Query Expansion})
+
+@lisp
+(eval-after-load
+ "message"
+ '(define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
+(eval-after-load
+ "sendmail"
+ '(define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
+@end lisp
+
+@menu
+* LDAP Requirements:: EUDC needs external support for LDAP
+@end menu
+
+@node LDAP Requirements, , Installation, Installation
+@comment node-name, next, previous, up
+@section LDAP Requirements
+
+LDAP support is added by means of @file{ldap.el} which is part of Emacs.
+@file{ldap.el} needs an external command line utility named
+@file{ldapsearch} which is available as part of LDAP toolkits:
+
+@itemize @bullet
+@item
+Open LDAP Libraries
+(@url{http://www.openldap.org/})
+@item
+University of Michigan's LDAP Client software
+(@url{http://www.umich.edu/~dirsvcs/ldap/})
+@end itemize
+
+
+@node Usage, Credits, Installation, Top
+@comment node-name, next, previous, up
+@chapter Usage
+
+This chapter describes the usage of EUDC. Most functions and
+customization options are available through the @samp{Directory Search}
+submenu of the @samp{Tools} submenu.
+
+@menu
+* Querying Servers:: How queries are performed and handled
+* Query Form:: How to use and customize the query form
+* Display of Query Results:: Controlling how query results are presented
+* Inline Query Expansion:: How to use and customize inline queries
+* The Server Hotlist:: How to use and manage the server hotlist
+* Multi-server Queries:: How to query multiple servers successively
+* Creating BBDB Records:: How to insert query results into your BBDB
+* Server/Protocol Locals:: Customizing on a per server/protocol basis
+@end menu
+
+
+@node Querying Servers, Query Form, Usage, Usage
+@comment node-name, next, previous, up
+@section Querying Servers
+
+EUDC's basic functionality is to let you query a directory server and
+return the results back to you. There are several things you may want
+to customize in this process.
+
+
+@menu
+* Selecting a Server:: The first thing to do
+* Return Attributes:: Configuring what the server should return
+* Duplicate Attributes:: What to do when records have duplicate attributes
+@end menu
+
+@node Selecting a Server, Return Attributes, Querying Servers, Querying Servers
+@subsection Selecting a Server
+
+Before doing any query you will need to set the directory server. You
+need to specify the name of the host machine running the server software
+and the protocol to use. If you do not set the server in any fashion,
+EUDC will ask you for one when you make your first query.
+
+You can set the server by selecting one from your hotlist of servers
+(@pxref{The Server Hotlist}) available in the @samp{Server} submenu or
+by selecting @samp{New Server} in that same menu.
+
+LDAP servers generally require some configuration before you can perform
+queries on them. In particular, the @dfn{search base} must be
+configured. If the server you select has no configured search base then
+EUDC will propose you to configure it at this point. A customization
+buffer will be displayed where you can edit the search base and other
+parameters for the server.
+
+@defvar eudc-server
+The name or IP address of the remote directory server. A TCP port number
+may be specified by appending a colon and a number to the name of the
+server. You will not need this unless your server runs on a port other
+than the default (which depends on the protocol).
+If the directory server resides on your own computer (which is the case
+if you use the BBDB back end) then `localhost' is a reasonable value but
+it will be ignored anyway.
+@end defvar
+
+@defvar eudc-protocol
+The directory protocol to use to query the server. Currently supported
+protocols in this version of EUDC are @code{ph}, @code{ldap} and @code{bbdb}.
+@end defvar
+
+@deffn Command eudc-set-server
+This command accessible from @samp{New Server} submenu lets you specify a
+new directory server and protocol.
+@end deffn
+
+@node Return Attributes, Duplicate Attributes, Selecting a Server, Querying Servers
+@subsection Return Attributes
+
+Directory servers may be configured to return a default set of
+attributes for each record matching a query if the query specifies none.
+The variable @code{eudc-default-return-attributes} controls the return
+attributes you want to see, if different from the server defaults.
+
+@defvar eudc-default-return-attributes
+A list of the default attributes to extract from directory entries. If
+set to the symbol @code{all} then all available attributes are
+returned. A value of @code{nil}, the default, means to return the
+default attributes as configured in the server.
+@end defvar
+
+The server may return several matching records to a query. Some of the
+records may however not contain all the attributes you requested. You can
+discard those records.
+
+@defopt eudc-strict-return-matches
+If non-@code{nil}, entries that do not contain all the requested return
+attributes are ignored. Default is @code{t}.
+@end defopt
+
+@node Duplicate Attributes, , Return Attributes, Querying Servers
+@subsection Duplicate Attributes
+
+Directory standards may authorize different instances of the same
+attribute in a record. For instance the record of a person may contain
+several email fields containing different email addresses. When using
+a QI directory server this is difficult to distinguish from attributes
+having multi-line values such as the postal address that may contain a
+line for the street and another one for the zip code and city name. In
+both cases, EUDC will consider the attribute duplicated.
+
+EUDC has several methods to deal with duplicated attributes. The
+available methods are:
+
+@table @code
+@item list
+Makes a list with the different values of the duplicate attribute. The
+record is returned with only one instance of the attribute with a list
+of all the different values as a value. This is the default method that
+is used to handle duplicate fields for which no other method has been
+specified.
+@item first
+Discards all the duplicate values of the field keeping only the first
+one.
+@item concat
+Concatenates the different values using a newline as a separator. The
+record keeps only one instance of the field the value of which is a
+single multi-line string.
+@item duplicate
+Duplicates the whole record into as many instances as there are different
+values for the field. This is the default for the email field. Thus a
+record containing 3 different email addresses is duplicated into three
+different records each having a single email address. This is
+particularly useful in combination with @code{select} as the method to
+handle multiple matches in inline expansion queries (@pxref{Inline Query
+Expansion}) because you are presented with the 3 addresses in a
+selection buffer
+@end table
+
+Because a method may not be applicable to all fields, the variable
+@code{eudc-duplicate-attribute-handling-method} lets you specify either a
+default method for all fields or a method for each individual field.
+
+@defvar eudc-duplicate-attribute-handling-method
+A method to handle entries containing duplicate attributes. This is
+either an alist of elements @code{(@var{attr} . @var{method})}, or a symbol
+@var{method}. The alist form of the variable associates a method to an
+individual attribute name; the second form specifies a method applicable
+to all attribute names. Available methods are: @code{list},
+@code{first}, @code{concat}, and @code{duplicate} (see above). The default is
+@code{list}.
+@end defvar
+
+
+
+@node Query Form, Display of Query Results, Querying Servers, Usage
+@comment node-name, next, previous, up
+@section Query Form
+
+The simplest way to query your directory server is to use the query
+form. You display the query form with the @samp{Query with Form} menu
+item or by invoking the command @kbd{M-x eudc-query-form}. The attribute
+names presented in this form are defined by the
+@code{eudc-query-form-attributes} variable (unless a non-@code{nil}
+argument is supplied to @code{eudc-query-form}).
+
+Since the different directory protocols to which EUDC interfaces may
+use different names for equivalent attributes, EUDC defines its own set
+of attribute names and a mapping between these names and their
+protocol-specific equivalent through the variable
+@code{eudc-protocol-attributes-translation-alist}. Names currently
+defined by EUDC are @code{name}, @code{firstname}, @code{email} and
+@code{phone}.
+
+@defvar eudc-query-form-attributes
+@findex eudc-get-attribute-list
+A list of attributes presented in the query form. Attribute names in
+this list should be either EUDC attribute names or valid attribute
+names. You can get a list of valid attribute names for the current
+protocol with the @samp{List Valid Attribute Names} menu item or the
+@kbd{M-x eudc-get-attribute-list} command. Defaults to @code{name},
+@code{email} and @code{phone}.
+@end defvar
+
+@deffn Command eudc-query-form get-fields-from-server
+Display a form to query the directory server. If given a non-@code{nil}
+argument the function first queries the server for the existing fields
+and displays a corresponding form. Not all protocols may support a
+non-@code{nil} argument here.
+@end deffn
+
+Since the names of the fields may not be explicit enough or adapted to
+be directly displayed as prompt strings in the form, the variable
+@code{eudc-user-attribute-names-alist} lets you define more explicit
+names for directory attribute names. This variable is ignored if
+@code{eudc-use-raw-directory-names} is non-@code{nil}.
+
+@defvar eudc-user-attribute-names-alist
+This is an alist of user-defined names for the directory attributes used in
+query/response forms. Prompt strings for attributes that are not in this
+alist are derived by splitting the attribute name at underscores and
+capitalizing the individual words.
+@end defvar
+
+@defvar eudc-use-raw-directory-names
+If non-@code{nil}, use attributes names as defined in the directory.
+Otherwise, directory query/response forms display the user attribute
+names defined in @code{eudc-user-attribute-names-alist}.
+@end defvar
+
+@node Display of Query Results, Inline Query Expansion, Query Form, Usage
+@comment node-name, next, previous, up
+@section Display of Query Results
+
+Upon successful completion of a form query, EUDC will display a buffer
+containing the results of the query.
+
+The fields that are returned for each record
+are controlled by @code{eudc-default-return-attributes} (@pxref{Return
+Attributes}).
+
+The display of each individual field can be performed by an arbitrary
+function which allows specific processing for binary values, such as
+images or audio samples, as well as values with semantics, such as
+URLs.
+
+@defvar eudc-attribute-display-method-alist
+An alist specifying methods to display attribute values. Each member of
+the list is of the form @code{(@var{name} . @var{func})} where
+@var{name} is a lowercased string naming a directory attribute
+(translated according to @code{eudc-user-attribute-names-alist} if
+@code{eudc-use-raw-directory-names} is non-@code{nil}) and @var{func} a
+function that will be passed the corresponding attribute values for
+display.
+@end defvar
+
+This variable has protocol-local definitions (see @pxref{Server/Protocol
+Locals}). For instance, it is defined as follows for LDAP:
+
+@lisp
+(eudc-protocol-set 'eudc-attribute-display-method-alist
+ '(("jpegphoto" . eudc-display-jpeg-inline)
+ ("labeledurl" . eudc-display-url)
+ ("audio" . eudc-display-sound)
+ ("labeledurl" . eudc-display-url)
+ ("url" . eudc-display-url))
+ 'ldap)
+@end lisp
+
+EUDC provides a set of built-in functions to display binary value types:
+
+@defun eudc-display-generic-binary data
+Display a button for unidentified binary @var{data}.
+@end defun
+
+@defun eudc-display-url url
+Display URL and make it clickable.
+@end defun
+
+@defun eudc-display-sound data
+Display a button to play the sound @var{data}.
+@end defun
+
+@defun eudc-display-jpeg-inline data
+Display the JPEG @var{data} inline at point if possible.
+@end defun
+
+@defun eudc-display-jpeg-as-button data
+Display a button for the JPEG @var{data}.
+@end defun
+
+Right-clicking on a binary value button pops up a contextual menu with
+options to process the value. Among these are saving the attribute
+value to a file or sending it to an external viewer command. External
+viewers should expect the value on their standard input and should
+display it or perform arbitrary processing on it. Messages sent to
+standard output are discarded. External viewers are listed in the
+variable @code{eudc-external-viewers} which you can customize.
+
+@defvar eudc-external-viewers
+This is a list of viewer program specifications. Each specification is
+a list whose first element is a string naming the viewer for unique
+identification, the second element is the executable program which
+should be invoked and the following elements are arguments that should
+be passed to the program.
+@end defvar
+
+
+@node Inline Query Expansion, The Server Hotlist, Display of Query Results, Usage
+@comment node-name, next, previous, up
+@section Inline Query Expansion
+
+Inline query expansion is a powerful method to get completion from your
+directory server. The most common usage is for expanding names to email
+addresses in mail message buffers. The expansion is performed by the
+command @kbd{M-x eudc-expand-inline} which is available from the
+@samp{Expand Inline Query} menu item but can also be conveniently
+bound to a key shortcut (@pxref{Installation}). The operation is
+controlled by the variables @code{eudc-inline-expansion-format},
+@code{eudc-inline-query-format},
+@code{eudc-expanding-overwrites-query} and
+@code{eudc-multiple-match-handling-method}.
+
+If the query fails for a server, other servers may be tried successively
+until one of them finds a match (@pxref{Multi-server Queries}).
+
+@deffn Command eudc-expand-inline replace-p
+Query the server and expand the query string before point. The query
+string consists of the buffer substring from the point back to the
+preceding comma, colon or beginning of
+line. @code{eudc-inline-query-format} controls how individual words
+are mapped onto directory attribute names. After querying the server
+for the given string, the expansion specified by
+@code{eudc-inline-expansion-format} is inserted in the buffer at
+point. If @var{replace-p} is @code{t} then this expansion replaces the
+query string in the buffer. If @code{eudc-expanding-overwrites-query}
+is non-@code{nil} then the meaning of @var{replace-p} is negated.
+@end deffn
+
+@defvar eudc-inline-query-format
+Format of an inline expansion query.
+This is actually a list of @var{format}s. A @var{format} is a list of
+one or more EUDC attribute names. A @var{format} applies if it contains
+as many attributes as individual words in the inline query string. If
+several @var{format}s apply then they are tried in order until a match
+is found. If @code{nil} all the words will be mapped onto the default
+server/protocol attribute name (generally @code{name}).
+
+For instance, use the following
+@lisp
+(setq eudc-inline-query-format '((name)
+ (firstname)
+ (firstname name)))
+@end lisp
+@noindent
+to indicate that single word expansion queries are to be considered as
+surnames and if no match is found then they should be tried as first
+names. Inline queries consisting of two words are considered as
+consisting of a first name followed by a surname. If the query consists
+of more than two words, then the first one is considered as the first
+name and the remaining words are all considered as surname constituents.
+
+@var{format}s are in fact not limited to EUDC attribute names, you can
+use server or protocol specific names in them. It may be safer if you
+do so, to set the variable @code{eudc-inline-query-format} in a protocol
+or server local fashion (see @pxref{Server/Protocol Locals}).
+
+For instance you could use the following to match up to three words
+against the @code{cn} attribute of LDAP servers:
+@lisp
+(eudc-protocol-set 'eudc-inline-query-format
+ '((cn)
+ (cn cn)
+ (cn cn cn))
+ 'ldap)
+@end lisp
+@end defvar
+
+@defvar eudc-inline-expansion-format
+This variable lets you control exactly what is inserted into the buffer
+upon an inline expansion request. It is a list whose first element is a
+string passed to @code{format}. Remaining elements are symbols
+corresponding to directory attribute names. The corresponding attribute
+values are passed as additional arguments to @code{format}. Default is
+@code{("%s" email)} but you may want to consider a value like @code{("%s
+<%s>" name email)}
+@end defvar
+
+@defvar eudc-multiple-match-handling-method
+This variable controls what to do when multiple entries match a query
+for an inline expansion. Possible values are:
+@table @code
+@item first
+The first match is considered as being the only one, the others are
+discarded.
+@item select
+A selection buffer pops up where you can choose a particular match. This
+is the default value of the variable.
+@item all
+The expansion uses all records successively
+@item abort
+An error is signaled. The expansion aborts.
+@end table
+
+Default is @code{select}
+@end defvar
+
+
+
+@node The Server Hotlist, Multi-server Queries, Inline Query Expansion, Usage
+@comment node-name, next, previous, up
+@section The Server Hotlist
+
+EUDC lets you maintain a list of frequently used servers so that you
+can easily switch from one to another. This hotlist appears in the
+@samp{Server} submenu. You select a server in this list by clicking on
+its name. You can add the current server to the list with the command
+@kbd{M-x eudc-bookmark-current-server}. The list is contained in the variable
+@code{eudc-server-hotlist} which is stored in and retrieved from the file
+designated by @code{eudc-options-file}. EUDC also provides a facility to
+edit the hotlist interactively (@pxref{The Hotlist Edit Buffer}).
+
+The hotlist is also used to make queries on multiple servers
+successively (@pxref{Multi-server Queries}). The order in which the
+servers are tried is the order they appear in the hotlist, therefore it
+is important to sort the hotlist appropriately.
+
+@deffn Command eudc-bookmark-server server
+Add @var{server} to the hotlist of servers
+@end deffn
+
+@deffn Command eudc-bookmark-current-server
+Add the current server to the hotlist of servers
+@end deffn
+
+@defvar eudc-options-file
+The name of a file where EUDC stores its internal variables
+(the hotlist and the current server). EUDC will try to load
+that file upon initialization so, if you choose a file name
+different from the defaults @file{~/.eudc-options}, be sure to set this
+variable to the appropriate value @emph{before} EUDC is itself
+loaded.
+@end defvar
+
+@menu
+* The Hotlist Edit Buffer:: An interactive hotlist editing facility
+@end menu
+
+@node The Hotlist Edit Buffer, , The Server Hotlist, The Server Hotlist
+@comment node-name, next, previous, up
+@subsection The Hotlist Edit Buffer
+
+The hotlist edit buffer offers a means to manage a list of frequently
+used servers. Commands are available in the context pop-up menu
+generally bound to the right mouse button. Those commands also have
+equivalent key bindings.
+
+@deffn Command eudc-hotlist-add-server
+Bound to @kbd{a}.
+Add a new server to the hotlist on the line after point
+@end deffn
+
+@deffn Command eudc-hotlist-delete-server
+Bound to @kbd{d}.
+Delete the server on the line point is on
+@end deffn
+
+@deffn Command eudc-hotlist-select-server
+Bound to @kbd{s}.
+Select the server the point is on as the current directory server for
+the next queries
+@end deffn
+
+@deffn Command eudc-hotlist-transpose-servers
+Bound to @kbd{t}.
+Bubble up the server the point is on to the top of the list
+@end deffn
+
+@deffn Command eudc-hotlist-quit-edit
+Bound to @kbd{q}.
+Save the changes and quit the hotlist edit buffer. Use @kbd{x} or
+@kbd{M-x kill-buffer} to exit without saving.
+@end deffn
+
+
+@node Multi-server Queries, Creating BBDB Records, The Server Hotlist, Usage
+@comment node-name, next, previous, up
+@section Multi-server Queries
+
+When using inline query expansion (@pxref{Inline Query Expansion}), EUDC
+can try to query successively a sequence of directory servers until one
+of them successfully finds a match for the query.
+
+@defvar eudc-inline-expansion-servers
+This variable controls which servers are tried and in which order when
+trying to perform an inline query. Possible values are:
+@table @code
+@item current-server
+Only the current directory server is tried
+@item hotlist
+The servers in the hotlist are tried in order until one finds a match
+for the query or `eudc-max-servers-to-query' is reached
+@item server-then-hotlist
+The current server then the servers in the hotlist are tried in the
+order they appear in the hotlist until one of them finds a match or
+`eudc-max-servers-to-query' is reached. This is the default.
+@end table
+@end defvar
+
+@defvar eudc-max-servers-to-query
+This variable indicates the maximum number of servers to query when
+performing a multi-server query. The default, @code{nil}, indicates
+that all available servers should be tried.
+@end defvar
+
+
+
+@node Creating BBDB Records, Server/Protocol Locals, Multi-server Queries, Usage
+@comment node-name, next, previous, up
+@section Creating BBDB Records
+
+@findex eudc-insert-record-at-point-into-bbdb
+@findex eudc-try-bbdb-insert
+With EUDC, you can automatically create BBDB records
+(@pxref{Top,,BBDB,bbdb,BBDB Manual}) from records you get from a
+directory server. You do this by moving point to the appropriate
+record in a query result display buffer and invoking the command
+@kbd{M-x eudc-insert-record-at-point-into-bbdb} with the
+keyboard binding @kbd{b}@footnote{This key binding does not actually
+call @code{eudc-insert-record-at-point-into-bbdb} but uses
+@code{eudc-try-bbdb-insert} instead.}, or with the menu. EUDC
+cannot update an existing BBDB record and will signal an error if you
+try to insert a record matching an existing one.
+
+@findex eudc-batch-export-records-to-bbdb
+It is also possible to export to BBDB the whole batch of records
+contained in the directory query result with the command
+@kbd{M-x eudc-batch-export-records-to-bbdb}.
+
+Because directory systems may not enforce a strict record format, local
+server installations may use different attribute names and have
+different ways to organize the information. Furthermore BBDB has its own
+record structure. For these reasons converting a record from its
+external directory format to the BBDB format is a highly customizable
+process.
+
+@defvar eudc-bbdb-conversion-alist
+The value of this variable should be a symbol naming an alist defining a
+mapping between BBDB field names onto directory attribute names records.
+This is a protocol-local variable and is initialized upon protocol
+switch (@pxref{Server/Protocol Locals}). The alist is made of cells of the
+form @code{(@var{bbdb-field} . @var{spec-or-list})}.
+@var{bbdb-field} is the name of a field
+that must be defined in your BBDB environment (standard field names are
+@code{name}, @code{company}, @code{net}, @code{phone}, @code{address}
+and @code{notes}).
+@var{spec-or-list} is either a single mapping specification or a list of
+mapping specifications. Lists of mapping specifications are valid for
+the @code{phone} and @code{address} BBDB fields only. @var{spec}s are
+actually s-expressions which are evaluated as follows:
+
+@table @asis
+@item a string
+evaluates to itself
+@item a symbol
+evaluates to the symbol value. Symbols corresponding to directory
+attribute names present in the record evaluate to the value of the field
+in the record
+@item a form
+is evaluated as a function. The argument list may contain attribute
+names which evaluate to the corresponding values in the record. The form
+evaluation should return something appropriate for the particular
+@var{bbdb-field} (see @code{bbdb-create-internal}).
+@code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as
+convenience functions to parse phones and addresses.
+@end table
+@end defvar
+
+The default value of the PH-specific value of that variable is
+@code{eudc-ph-bbdb-conversion-alist}:
+
+@lisp
+((name . name)
+ (net . email)
+ (address . (eudc-bbdbify-address address "Address"))
+ (phone . ((eudc-bbdbify-phone phone "Phone")
+ (eudc-bbdbify-phone office_phone "Office Phone"))))
+@end lisp
+
+This means that:
+
+@itemize @bullet
+@item
+the @code{name} field of the BBDB record gets its value
+from the @code{name} attribute of the directory record
+@item
+the @code{net} field of the BBDB record gets its value
+from the @code{email} attribute of the directory record
+@item
+the @code{address} field of the BBDB record is obtained by parsing the
+@code{address} attribute of the directory record with the function
+@code{eudc-bbdbify-address}
+@item
+two @code{phone} fields are created (when possible) in the BBDB record.
+The first one has @cite{Phone} for location and its value is obtained by
+parsing the @code{phone} attribute of the PH/QI record with the function
+@code{eudc-bbdbify-phone}. The second one has @cite{Office Phone} for location
+its value is obtained by parsing the @code{office_phone} attribute of the
+PH/QI record with the function @code{eudc-bbdbify-phone}.
+@end itemize
+
+@defun eudc-bbdbify-phone phone location
+This is a convenience function provided for use in
+@code{eudc-bbdb-conversion-alist}. It parses @var{phone} into a vector
+compatible with @code{bbdb-create-internal}. @var{phone} is either a string
+supposedly containing a phone number or a list of such strings which are
+concatenated. @var{location} is used as the phone location for BBDB.
+@end defun
+
+@defun eudc-bbdbify-address addr location
+This is a convenience function provided for use in
+@code{eudc-bbdb-conversion-alist}. It parses @var{addr} into a vector
+compatible with @code{bbdb-create-internal}. @var{addr} should be an
+address string of no more than four lines or a list of lines. The last
+line is searched for the zip code, city and state name. @var{location}
+is used as the phone location for BBDB.
+@end defun
+
+Note that only a subset of the attributes you selected with
+@code{eudc-default-return-attributes} and that are actually displayed may
+actually be inserted as part of the newly created BBDB record.
+
+
+@node Server/Protocol Locals, , Creating BBDB Records, Usage
+@comment node-name, next, previous, up
+@section Server/Protocol Locals
+
+EUDC can be customized independently for each server or directory
+protocol. All variables can be given local bindings that are activated
+when a particular server and/or protocol becomes active. This is much
+like buffer-local bindings but on a per server or per protocol basis.
+
+@menu
+* Manipulating local bindings:: Functions to set and query local bindings
+@end menu
+
+@node Manipulating local bindings, , Server/Protocol Locals, Server/Protocol Locals
+@comment node-name, next, previous, up
+@subsection Manipulating local bindings
+
+EUDC offers functions that let you set and query variables on a per
+server or per protocol basis.
+
+The following predicates allow you to test the existence of
+server/protocol local bindings for a particular variable.
+
+@defun eudc-server-local-variable-p var
+Return non-@code{nil} if @var{var} has server-local bindings
+@end defun
+
+@defun eudc-protocol-local-variable-p var
+Return non-@code{nil} if @var{var} has protocol-local bindings
+@end defun
+
+The following functions allow you to set the value of a variable with
+various degrees of locality.
+
+@defun eudc-default-set var val
+Set the EUDC default value of @var{var} to @var{val}.
+The current binding of @var{var} (if local to the current server or
+protocol) is not changed.
+@end defun
+
+@defun eudc-protocol-set var val &optional protocol
+Set the binding of @var{var} local to @var{protocol} to @var{val}. If
+omitted, @var{protocol} defaults to the current value of
+@code{eudc-protocol}. The current binding of @var{var} is changed only
+if @var{protocol} is omitted.
+@end defun
+
+@defun eudc-server-set var val &optional server
+Set the binding of @var{var} local to @var{server} to @var{val}. If
+omitted, @var{server} defaults to the current value of
+@code{eudc-server}. The current binding of @var{var} is changed only if
+@var{server} is omitted.
+@end defun
+
+@defun eudc-set var val
+Set the most local (server, protocol or default) binding of @var{var} to
+@var{val}. The current binding of @var{var} is also set to @var{val}.
+@end defun
+
+The following variables allow you to query the various bindings of a
+variable (local or non-local).
+
+@defun eudc-variable-default-value var
+Return the default binding of @var{var} (outside of a particular server
+or protocol local binding).
+Return @code{unbound} if @var{var} has no EUDC default value.
+@end defun
+
+@defun eudc-variable-protocol-value var &optional protocol
+Return the value of @var{var} local to @var{protocol}. Return
+@code{unbound} if @var{var} has no value local to @var{protocol}.
+@var{protocol} defaults to @code{eudc-protocol}.
+@end defun
+
+@defun eudc-variable-server-value var [server]
+Return the value of @var{var} local to @var{server}.
+Return @code{unbound} if @var{var} has no value local to @var{server}.
+@var{server} defaults to @code{eudc-server}.
+@end defun
+
+Changing a protocol-local or server-local value of a variable has no
+effect on its current value. The following command is used to
+synchronize the current values of variables with their local values
+given the current @code{eudc-server} and @code{eudc-protocol}:
+
+@defun eudc-update-local-variables
+Update all EUDC variables according to their local settings.
+@end defun
+
+
+
+@node Credits, GNU Free Documentation License, Usage, Top
+@comment node-name, next, previous, up
+@chapter Credits
+
+EUDC was written by Oscar Figueiredo based on @file{ph.el} by the
+same author.
+
+Thanks to Soren Dayton for his suggestions, his enthusiasm and his help
+in testing and proofreading the code and docs of @file{ph.el}.
+
+@node GNU Free Documentation License, Command and Function Index, Credits, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Command and Function Index, Variables Index, GNU Free Documentation License, Top
+@comment node-name, next, previous, up
+@unnumbered Command and Function Index
+
+@printindex fn
+
+@node Variables Index, , Command and Function Index, Top
+@comment node-name, next, previous, up
+@unnumbered Variables Index
+
+@printindex vr
+
+@setchapternewpage odd
+@contents
+@bye
+
+@ignore
+ arch-tag: 1b79460b-4ea1-441d-ab45-05ddd16ef241
+@end ignore
--- /dev/null
+\input texinfo @c -*- mode: texinfo; -*-
+@c %**start of header
+@setfilename ../info/efaq
+@settitle GNU Emacs FAQ
+@c %**end of header
+
+@setchapternewpage odd
+
+@c This is used in many places
+@set VER 22.1
+
+@c This file is maintained by Romain Francoise <rfrancoise@gnu.org>.
+@c Feel free to install changes without prior permission (but I'd
+@c appreciate a notice if you do).
+
+@copying
+Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007
+Free Software Foundation, Inc.@*
+Copyright 1994,1995,1996,1997,1998,1999,2000 Reuven M. Lerner@*
+Copyright 1992,1993 Steven Byrnes@*
+Copyright 1990,1991,1992 Joseph Brian Wells@*
+
+@quotation
+This list of frequently asked questions about GNU Emacs with answers
+(``FAQ'') may be translated into other languages, transformed into other
+formats (e.g. Texinfo, Info, WWW, WAIS), and updated with new information.
+
+The same conditions apply to any derivative of the FAQ as apply to the FAQ
+itself. Every copy of the FAQ must include this notice or an approved
+translation, information on who is currently maintaining the FAQ and how to
+contact them (including their e-mail address), and information on where the
+latest version of the FAQ is archived (including FTP information).
+
+The FAQ may be copied and redistributed under these conditions, except that
+the FAQ may not be embedded in a larger literary work unless that work
+itself allows free copying and redistribution.
+
+[This version has been heavily edited since it was included in the Emacs
+distribution.]
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Emacs FAQ: (efaq). Frequently Asked Questions about Emacs.
+@end direntry
+
+@c The @titlepage stuff only appears in the printed version
+@titlepage
+@sp 10
+@center @titlefont{GNU Emacs FAQ}
+
+@c The following two commands start the copyright page.
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@node Top, FAQ notation, (dir), (dir)
+
+This is the GNU Emacs FAQ, last updated on @today{}.
+
+This FAQ is maintained as a part of GNU Emacs. If you find any errors,
+or have any suggestions, please use @kbd{M-x report-emacs-bug} to report
+them.
+
+@menu
+* FAQ notation::
+* General questions::
+* Getting help::
+* Status of Emacs::
+* Common requests::
+* Bugs and problems::
+* Compiling and installing Emacs::
+* Finding Emacs and related packages::
+* Major packages and programs::
+* Key bindings::
+* Alternate character sets::
+* Mail and news::
+* Concept index::
+@end menu
+
+@c ------------------------------------------------------------
+@node FAQ notation, General questions, Top, Top
+@chapter FAQ notation
+@cindex FAQ notation
+
+This chapter describes notation used in the GNU Emacs FAQ, as well as in
+the Emacs documentation. Consult this section if this is the first time
+you are reading the FAQ, or if you are confused by notation or terms
+used in the FAQ.
+
+@menu
+* Basic keys::
+* Extended commands::
+* On-line manual::
+* File-name conventions::
+* Common acronyms::
+@end menu
+
+@node Basic keys, Extended commands, FAQ notation, FAQ notation
+@section What do these mean: @kbd{C-h}, @kbd{C-M-a}, @key{RET}, @kbd{@key{ESC} a}, etc.?
+@cindex Basic keys
+@cindex Control key, notation for
+@cindex @key{Meta} key, notation for
+@cindex Control-Meta characters, notation for
+@cindex @kbd{C-h}, definition of
+@cindex @kbd{C-M-h}, definition of
+@cindex @key{DEL}, definition of
+@cindex @key{ESC}, definition of
+@cindex @key{LFD}, definition of
+@cindex @key{RET}, definition of
+@cindex @key{SPC}, definition of
+@cindex @key{TAB}, definition of
+@cindex Notation for keys
+
+@itemize @bullet
+
+@item
+@kbd{C-x}: press the @key{x} key while holding down the @key{Control} key
+
+@item
+@kbd{M-x}: press the @key{x} key while holding down the @key{Meta} key
+(if your computer doesn't have a @key{Meta} key, @pxref{No Meta key})
+
+@item
+@kbd{M-C-x}: press the @key{x} key while holding down both @key{Control}
+and @key{Meta}
+
+@item
+@kbd{C-M-x}: a synonym for the above
+
+@item
+@key{LFD}: Linefeed or Newline; same as @kbd{C-j}
+
+@item
+@key{RET}: @key{Return}, sometimes marked @key{Enter}; same as @kbd{C-m}
+
+@item
+@key{DEL}: @key{Delete}, usually @strong{not} the same as
+@key{Backspace}; same as @kbd{C-?} (see @ref{Backspace invokes help}, if
+deleting invokes Emacs help)
+
+@item
+@key{ESC}: Escape; same as @kbd{C-[}
+
+@item
+@key{TAB}: Tab; same as @kbd{C-i}
+
+@item
+@key{SPC}: Space bar
+
+@end itemize
+
+Key sequences longer than one key (and some single-key sequences) are
+written inside quotes or on lines by themselves, like this:
+
+@display
+ @kbd{M-x frobnicate-while-foo RET}
+@end display
+
+@noindent
+Any real spaces in such a key sequence should be ignored; only @key{SPC}
+really means press the space key.
+
+The @acronym{ASCII} code sent by @kbd{C-x} (except for @kbd{C-?}) is the value
+that would be sent by pressing just @key{x} minus 96 (or 64 for
+upper-case @key{X}) and will be from 0 to 31. On Unix and GNU/Linux
+terminals, the @acronym{ASCII} code sent by @kbd{M-x} is the sum of 128 and the
+@acronym{ASCII} code that would be sent by pressing just @key{x}. Essentially,
+@key{Control} turns off bits 5 and 6 and @key{Meta} turns on bit
+7@footnote{
+DOS and Windows terminals don't set bit 7 when the @key{Meta} key is
+pressed.}.
+
+@kbd{C-?} (aka @key{DEL}) is @acronym{ASCII} code 127. It is a misnomer to call
+@kbd{C-?} a ``control'' key, since 127 has both bits 5 and 6 turned ON.
+Also, on very few keyboards does @kbd{C-?} generate @acronym{ASCII} code 127.
+
+@inforef{Text Characters, Text Characters, emacs}, and @inforef{Keys,
+Keys, emacs}, for more information. (@xref{On-line manual}, for more
+information about Info.)
+
+@node Extended commands, On-line manual, Basic keys, FAQ notation
+@section What does @file{M-x @var{command}} mean?
+@cindex Extended commands
+@cindex Commands, extended
+@cindex M-x, meaning of
+
+@kbd{M-x @var{command}} means type @kbd{M-x}, then type the name of the
+command, then type @key{RET}. (@xref{Basic keys}, if you're not sure
+what @kbd{M-x} and @key{RET} mean.)
+
+@kbd{M-x} (by default) invokes the command
+@code{execute-extended-command}. This command allows you to run any
+Emacs command if you can remember the command's name. If you can't
+remember the command's name, you can type @key{TAB} and @key{SPC} for
+completion, @key{?} for a list of possibilities, and @kbd{M-p} and
+@kbd{M-n} (or up-arrow and down-arrow on terminals that have these
+editing keys) to see previous commands entered. An Emacs @dfn{command}
+is an @dfn{interactive} Emacs function.
+
+@cindex @key{Do} key
+Your system administrator may have bound other key sequences to invoke
+@code{execute-extended-command}. A function key labeled @kbd{Do} is a
+good candidate for this, on keyboards that have such a key.
+
+If you need to run non-interactive Emacs functions, see @ref{Evaluating
+Emacs Lisp code}.
+
+@node On-line manual, File-name conventions, Extended commands, FAQ notation
+@section How do I read topic XXX in the on-line manual?
+@cindex On-line manual, reading topics in
+@cindex Reading topics in the on-line manual
+@cindex Finding topics in the on-line manual
+@cindex Info, finding topics in
+
+When we refer you to some @var{topic} in the on-line manual, you can
+read this manual node inside Emacs (assuming nothing is broken) by
+typing @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET}}.
+
+This invokes Info, the GNU hypertext documentation browser. If you don't
+already know how to use Info, type @key{?} from within Info.
+
+If we refer to @var{topic}:@var{subtopic}, type @kbd{C-h i m emacs
+@key{RET} m @var{topic} @key{RET} m @var{subtopic} @key{RET}}.
+
+If these commands don't work as expected, your system administrator may
+not have installed the Info files, or may have installed them
+improperly. In this case you should complain.
+
+@xref{Getting a printed manual}, if you would like a paper copy of the
+Emacs manual.
+
+@node File-name conventions, Common acronyms, On-line manual, FAQ notation
+@section What are @file{etc/SERVICE}, @file{src/config.h}, and @file{lisp/default.el}?
+@cindex File-name conventions
+@cindex Conventions for file names
+@cindex Directories and files that come with Emacs
+
+These are files that come with Emacs. The Emacs distribution is divided
+into subdirectories; the important ones are @file{etc}, @file{lisp}, and
+@file{src}.
+
+If you use Emacs, but don't know where it is kept on your system, start
+Emacs, then type @kbd{C-h v data-directory @key{RET}}. The directory
+name displayed by this will be the full pathname of the installed
+@file{etc} directory. (This full path is recorded in the Emacs variable
+@code{data-directory}, and @kbd{C-h v} displays the value and the
+documentation of a variable.)
+
+The location of your Info directory (i.e., where on-line documentation
+is stored) is kept in the variable @code{Info-default-directory-list}. Use
+@kbd{C-h v Info-default-directory-list @key{RET}} to see the value of
+this variable, which will be a list of directory names. The last
+directory in that list is probably where most Info files are stored. By
+default, Info documentation is placed in @file{/usr/local/info}.
+
+Some of these files are available individually via FTP or e-mail; see
+@ref{Informational files for Emacs}. They all are available in the
+source distribution. Many of the files in the @file{etc} directory are
+also available via the Emacs @samp{Help} menu, or by typing @kbd{C-h ?}
+(@kbd{M-x help-for-help}).
+
+Your system administrator may have removed the @file{src} directory and
+many files from the @file{etc} directory.
+
+@node Common acronyms, , File-name conventions, FAQ notation
+@section What are FSF, LPF, OSF, GNU, RMS, FTP, and GPL?
+@cindex FSF, definition of
+@cindex LPF, definition of
+@cindex OSF, definition of
+@cindex GNU, definition of
+@cindex RMS, definition of
+@cindex Stallman, Richard, acronym for
+@cindex Richard Stallman, acronym for
+@cindex FTP, definition of
+@cindex GPL, definition of
+@cindex Acronyms, definitions for
+@cindex Common acronyms, definitions for
+
+@table @asis
+
+@item FSF
+Free Software Foundation
+
+@item LPF
+League for Programming Freedom
+
+@item OSF
+Open Software Foundation
+
+@item GNU
+GNU's Not Unix
+
+@item RMS
+Richard Matthew Stallman
+
+@item FTP
+File Transfer Protocol
+
+@item GPL
+GNU General Public License
+
+@end table
+
+Avoid confusing the FSF, the LPF, and the OSF. The LPF opposes
+look-and-feel copyrights and software patents. The FSF aims to make
+high quality free software available for everyone. The OSF is a
+consortium of computer vendors which develops commercial software for
+Unix systems.
+
+The word ``free'' in the title of the Free Software Foundation refers to
+``freedom,'' not ``zero cost.'' Anyone can charge any price for
+GPL-covered software that they want to. However, in practice, the
+freedom enforced by the GPL leads to low prices, because you can always
+get the software for less money from someone else, since everyone has
+the right to resell or give away GPL-covered software.
+
+@c ------------------------------------------------------------
+@node General questions, Getting help, FAQ notation, Top
+@chapter General questions
+@cindex General questions
+
+This chapter contains general questions having to do with Emacs, the
+Free Software Foundation, and related organizations.
+
+@menu
+* The LPF::
+* Real meaning of copyleft::
+* Guidelines for newsgroup postings::
+* Newsgroup archives::
+* Reporting bugs::
+* Unsubscribing from Emacs lists::
+* Contacting the FSF::
+@end menu
+
+@node The LPF, Real meaning of copyleft, General questions, General questions
+@section What is the LPF?
+@cindex LPF, description of
+@cindex League for Programming Freedom
+@cindex Software patents, opposition to
+@cindex Patents for software, opposition to
+
+The LPF opposes the expanding danger of software patents and
+look-and-feel copyrights. To get more information, feel free to contact
+the LPF via e-mail or otherwise. You may also contact
+@email{jbw@@cs.bu.edu, Joe Wells}; he will be happy to talk to you
+about the LPF.
+
+You can find more information about the LPF in the file @file{etc/LPF}.
+More papers describing the LPF's views are available on the Internet and
+also from @uref{http://lpf.ai.mit.edu/, the LPF home page}.
+
+@node Real meaning of copyleft, Guidelines for newsgroup postings, The LPF, General questions
+@section What is the real legal meaning of the GNU copyleft?
+@cindex Copyleft, real meaning of
+@cindex GPL, real meaning of
+@cindex General Public License, real meaning of
+@cindex Discussion of the GPL
+
+The real legal meaning of the GNU General Public License (copyleft) will
+only be known if and when a judge rules on its validity and scope.
+There has never been a copyright infringement case involving the GPL to
+set any precedents. Please take any discussion regarding this issue to
+the newsgroup @uref{news:gnu.misc.discuss}, which was created to hold the
+extensive flame wars on the subject.
+
+RMS writes:
+
+@quotation
+The legal meaning of the GNU copyleft is less important than the spirit,
+which is that Emacs is a free software project and that work pertaining
+to Emacs should also be free software. ``Free'' means that all users
+have the freedom to study, share, change and improve Emacs. To make
+sure everyone has this freedom, pass along source code when you
+distribute any version of Emacs or a related program, and give the
+recipients the same freedom that you enjoyed.
+@end quotation
+
+@node Guidelines for newsgroup postings, Newsgroup archives, Real meaning of copyleft, General questions
+@section What are appropriate messages for @uref{news:gnu.emacs.help}, @uref{news:gnu.emacs.bug}, @uref{news:comp.emacs}, etc.?
+@cindex Newsgroups, appropriate messages for
+@cindex GNU newsgroups, appropriate messages for
+@cindex Usenet groups, appropriate messages for
+@cindex Mailing lists, appropriate messages for
+@cindex Posting messages to newsgroups
+
+@cindex GNU mailing lists
+The file @file{etc/MAILINGLISTS} describes the purpose of each GNU
+mailing list. (@xref{Informational files for Emacs}, if you want a copy
+of the file.) For those lists which are gatewayed with newsgroups, it
+lists both the newsgroup name and the mailing list address.
+
+The newsgroup @uref{news:comp.emacs} is for discussion of Emacs programs
+in general. This includes Emacs along with various other
+implementations, such as XEmacs, JOVE, MicroEmacs, Freemacs, MG,
+Unipress, CCA, and Epsilon.
+
+Many people post Emacs questions to @uref{news:comp.emacs} because they
+don't receive any of the @code{gnu.*} newsgroups. Arguments have been
+made both for and against posting GNU-Emacs-specific material to
+@uref{news:comp.emacs}. You have to decide for yourself.
+
+Messages advocating ``non-free'' software are considered unacceptable on
+any of the @code{gnu.*} newsgroups except for @uref{news:gnu.misc.discuss},
+which was created to hold the extensive flame-wars on the subject.
+``Non-free'' software includes any software for which the end user can't
+freely modify the source code and exchange enhancements. Be careful to
+remove the @code{gnu.*} groups from the @samp{Newsgroups:} line when
+posting a followup that recommends such software.
+
+@uref{news:gnu.emacs.bug} is a place where bug reports appear, but avoid
+posting bug reports to this newsgroup directly (@pxref{Reporting bugs}).
+
+@node Newsgroup archives, Reporting bugs, Guidelines for newsgroup postings, General questions
+@section Where can I get old postings to @uref{news:gnu.emacs.help} and other GNU groups?
+@cindex Archived postings from @code{gnu.emacs.help}
+@cindex Usenet archives for GNU groups
+@cindex Old Usenet postings for GNU groups
+
+The FSF has maintained archives of all of the GNU mailing lists for many
+years, although there may be some unintentional gaps in coverage. The
+archive is not particularly well organized or easy to retrieve
+individual postings from, but pretty much everything is there.
+
+The archive is at @uref{ftp://lists.gnu.org/}.
+
+The archive can be browsed over the web at
+@uref{http://lists.gnu.org/archive/html/, the GNU mail archive}.
+
+Web-based Usenet search services, such as
+@uref{http://groups.google.com/groups/dir?sel=33592484, Google}, also
+archive the @code{gnu.*} groups.
+
+You can read the archives of the @code{gnu.*} groups and post new
+messages at @uref{http://gmane.org/, Gmane}.
+
+@node Reporting bugs, Unsubscribing from Emacs lists, Newsgroup archives, General questions
+@section Where should I report bugs and other problems with Emacs?
+@cindex Bug reporting
+@cindex Good bug reports
+@cindex How to submit a bug report
+@cindex Reporting bugs
+
+The correct way to report Emacs bugs is to use the command
+@kbd{M-x report-emacs-bug}. It sets up a mail buffer with the
+essential information and the correct e-mail address which is
+@email{bug-gnu-emacs@@gnu.org} for the released versions of Emacs.
+Anything sent to @email{bug-gnu-emacs@@gnu.org} also appears in the
+newsgroup @uref{news:gnu.emacs.bug}, but please use e-mail instead of
+news to submit the bug report. This ensures a reliable return address
+so you can be contacted for further details.
+
+Be sure to read the ``Bugs'' section of the Emacs manual before reporting
+a bug! The manual describes in detail how to submit a useful bug
+report (@pxref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}).
+(@xref{On-line manual}, if you don't know how to read the manual.)
+
+RMS says:
+
+@quotation
+Sending bug reports to @email{help-gnu-emacs@@gnu.org} (which has the
+effect of posting on @uref{news:gnu.emacs.help}) is undesirable because
+it takes the time of an unnecessarily large group of people, most of
+whom are just users and have no idea how to fix these problem.
+@email{bug-gnu-emacs@@gnu.org} reaches a much smaller group of people
+who are more likely to know what to do and have expressed a wish to
+receive more messages about Emacs than the others.
+@end quotation
+
+RMS says it is sometimes fine to post to @uref{news:gnu.emacs.help}:
+
+@quotation
+If you have reported a bug and you don't hear about a possible fix,
+then after a suitable delay (such as a week) it is okay to post on
+@code{gnu.emacs.help} asking if anyone can help you.
+@end quotation
+
+If you are unsure whether you have found a bug, consider the following
+non-exhaustive list, courtesy of RMS:
+
+@quotation
+If Emacs crashes, that is a bug. If Emacs gets compilation errors
+while building, that is a bug. If Emacs crashes while building, that
+is a bug. If Lisp code does not do what the documentation says it
+does, that is a bug.
+@end quotation
+
+@node Unsubscribing from Emacs lists, Contacting the FSF, Reporting bugs, General questions
+@section How do I unsubscribe from this mailing list?
+@cindex Unsubscribing from GNU mailing lists
+@cindex Removing yourself from GNU mailing lists
+
+If you are receiving a GNU mailing list named @var{list}, you might be
+able to unsubscribe from it by sending a request to the address
+@email{@var{list}-request@@gnu.org}. However, this will not work if you are
+not listed on the main mailing list, but instead receive the mail from a
+distribution point. In that case, you will have to track down at which
+distribution point you are listed. Inspecting the @samp{Received} headers
+on the mail messages may help, along with liberal use of the @samp{EXPN} or
+@samp{VRFY} sendmail commands through @samp{telnet @var{site-address}
+smtp}. Ask your postmaster for help, if you cannot figure out these
+details.
+
+@node Contacting the FSF, , Unsubscribing from Emacs lists, General questions
+@section What is the current address of the FSF?
+@cindex Snail mail address of the FSF
+@cindex Postal address of the FSF
+@cindex Contracting the FSF
+@cindex Free Software Foundation, contacting
+
+@table @asis
+
+@item E-mail
+gnu@@gnu.org
+
+@item Telephone
++1-617-542-5942
+
+@item Fax
++1-617-542-2652
+
+@item World Wide Web
+@uref{http://www.gnu.org/}
+
+@item Postal address
+Free Software Foundation@*
+51 Franklin Street, Fifth Floor@*
+Boston, MA 02110-1301@*
+USA@*
+
+@end table
+
+@cindex Ordering GNU software
+For details on how to order items directly from the FSF, see the
+@uref{http://www.gnu.org/order/order.html, GNU Web site}.
+
+@c ------------------------------------------------------------
+@node Getting help, Status of Emacs, General questions, Top
+@chapter Getting help
+@cindex Getting help
+
+This chapter tells you how to get help with Emacs
+
+@menu
+* Basic editing::
+* Learning how to do something::
+* Getting a printed manual::
+* Emacs Lisp documentation::
+* Installing Texinfo documentation::
+* Printing a Texinfo file::
+* Viewing Info files outside of Emacs::
+* Informational files for Emacs::
+* Help installing Emacs::
+* Obtaining the FAQ::
+@end menu
+
+@node Basic editing, Learning how to do something, Getting help, Getting help
+@section I'm just starting Emacs; how do I do basic editing?
+@cindex Basic editing with Emacs
+@cindex Beginning editing
+@cindex Tutorial, invoking the
+@cindex Self-paced tutorial, invoking the
+@cindex Help system, entering the
+
+Type @kbd{C-h t} to invoke the self-paced tutorial. Just typing
+@kbd{C-h} enters the help system. Starting with Emacs 22, the tutorial
+is available in many foreign languages such as French, German, Japanese,
+Russian, etc. Use @kbd{M-x help-with-tutorial-spec-language @key{RET}}
+to choose your language and start the tutorial.
+
+Your system administrator may have changed @kbd{C-h} to act like
+@key{DEL} to deal with local keyboards. You can use @kbd{M-x
+help-for-help} instead to invoke help. To discover what key (if any)
+invokes help on your system, type @kbd{M-x where-is @key{RET}
+help-for-help @key{RET}}. This will print a comma-separated list of key
+sequences in the echo area. Ignore the last character in each key
+sequence listed. Each of the resulting key sequences invokes help.
+
+Emacs help works best if it is invoked by a single key whose value
+should be stored in the variable @code{help-char}.
+
+@node Learning how to do something, Getting a printed manual, Basic editing, Getting help
+@section How do I find out how to do something in Emacs?
+@cindex Help for Emacs
+@cindex Learning to do something in Emacs
+@cindex Reference card for Emacs
+@cindex Overview of help systems
+
+There are several methods for finding out how to do things in Emacs.
+
+@itemize @bullet
+
+@cindex Reading the Emacs manual
+@item
+The complete text of the Emacs manual is available on-line via the Info
+hypertext reader. Type @kbd{C-h r} to display the manual in Info mode.
+Typing @key{h} immediately after entering Info will provide a short
+tutorial on how to use it.
+
+@cindex Lookup a subject in a manual
+@cindex Index search in a manual
+@item
+To quickly locate the section of the manual which discusses a certain
+issue, or describes a command or a variable, type @kbd{C-h i m emacs
+@key{RET} i @var{topic} @key{RET}}, where @var{topic} is the name of the
+topic, the command, or the variable which you are looking for. If this
+does not land you on the right place in the manual, press @kbd{,}
+(comma) repeatedly until you find what you need. (The @kbd{i} and
+@kbd{,} keys invoke the index-searching functions, which look for the
+@var{topic} you type in all the indices of the Emacs manual.)
+
+@cindex Apropos
+@item
+You can list all of the commands whose names contain a certain word
+(actually which match a regular expression) using @kbd{C-h a} (@kbd{M-x
+command-apropos}).
+
+@cindex Command description in the manual
+@item
+The command @kbd{C-h F} (@code{Info-goto-emacs-command-node}) prompts
+for the name of a command, and then attempts to find the section in the
+Emacs manual where that command is described.
+
+@cindex Finding commands and variables
+@item
+You can list all of the functions and variables whose names contain a
+certain word using @kbd{M-x apropos}.
+
+@item
+You can list all of the functions and variables whose documentation
+matches a regular expression or a string, using @kbd{M-x
+apropos-documentation}.
+
+@item
+You can order a hardcopy of the manual from the FSF. @xref{Getting a
+printed manual}.
+
+@cindex Reference cards, in other languages
+@item
+You can get a printed reference card listing commands and keys to
+invoke them. You can order one from the FSF for $1 (or 10 for $5),
+or you can print your own from the @file{etc/refcards/refcard.tex} or
+@file{etc/refcards/refcard.ps} files in the Emacs distribution.
+Beginning with version 21.1, the Emacs distribution comes with
+translations of the reference card into several languages; look for
+files named @file{etc/refcards/@var{lang}-refcard.*}, where @var{lang}
+is a two-letter code of the language. For example, the German version
+of the reference card is in the files @file{etc/refcards/de-refcard.tex}
+and @file{etc/recards/de-refcard.ps}.
+
+@item
+There are many other commands in Emacs for getting help and
+information. To get a list of these commands, type @samp{?} after
+@kbd{C-h}.
+
+@end itemize
+
+@node Getting a printed manual, Emacs Lisp documentation, Learning how to do something, Getting help
+@section How do I get a printed copy of the Emacs manual?
+@cindex Printed Emacs manual, obtaining
+@cindex Manual, obtaining a printed or HTML copy of
+@cindex Emacs manual, obtaining a printed or HTML copy of
+
+You can order a printed copy of the Emacs manual from the FSF. For
+details see the @uref{http://www.gnu.org/order/order.html, GNU Web site}.
+
+@c The number 620 below is version-dependent!
+The full Texinfo source for the manual also comes in the @file{man}
+directory of the Emacs distribution, if you're daring enough to try to
+print out this 620-page manual yourself (@pxref{Printing a Texinfo
+file}).
+
+If you absolutely have to print your own copy, and you don't have @TeX{},
+you can get a PostScript version from
+
+@uref{http://www.gnu.org/software/emacs/manual/emacs.ps.gz}
+
+@cindex HTML version of Emacs manual, obtaining
+An HTML version of the manual is at
+
+@uref{http://www.gnu.org/software/emacs/manual/emacs.html}
+
+The manual is available in other formats at
+
+@uref{http://www.gnu.org/software/emacs/manual/}
+
+@xref{Learning how to do something}, for how to view the manual on-line.
+
+@node Emacs Lisp documentation, Installing Texinfo documentation, Getting a printed manual, Getting help
+@section Where can I get documentation on Emacs Lisp?
+@cindex Documentation on Emacs Lisp
+@cindex Function documentation
+@cindex Variable documentation
+@cindex Emacs Lisp Reference Manual
+@cindex Reference manual for Emacs Lisp
+
+Within Emacs, you can type @kbd{C-h f} to get the documentation for a
+function, @kbd{C-h v} for a variable.
+
+For more information, the Emacs Lisp Reference Manual is available
+on-line, in Info format. @xref{Top, Emacs Lisp,, elisp, The
+Emacs Lisp Reference Manual}.
+
+You can also order a hardcopy of the manual, details on ordering it from
+FSF are on the @uref{http://www.gnu.org/order/order.html, GNU Web site}.
+
+An HTML version of the Emacs Lisp Reference Manual is available at
+
+@uref{http://www.gnu.org/software/emacs/elisp-manual/elisp.html}
+
+@node Installing Texinfo documentation, Printing a Texinfo file, Emacs Lisp documentation, Getting help
+@section How do I install a piece of Texinfo documentation?
+@cindex Texinfo documentation, installing
+@cindex Installing Texinfo documentation
+@cindex New Texinfo files, installing
+@cindex Documentation, installing new Texinfo files
+@cindex Info files, how to install
+
+First, you must turn the Texinfo files into Info files. You may do this
+using the stand-alone @file{makeinfo} program, available as part of the latest
+Texinfo package at
+
+@uref{ftp://ftp.gnu.org/pub/gnu/texinfo/texinfo-4.8.tar.gz}
+
+and all mirrors of @samp{ftp.gnu.org} (for a list, @pxref{Current GNU
+distributions}).
+
+For information about the Texinfo format, read the Texinfo manual which
+comes with the Texinfo package. This manual also comes installed in
+Info format, so you can read it on-line; type @kbd{C-h i m texinfo
+@key{RET}}.
+
+Alternatively, you could use the Emacs command @kbd{M-x
+texinfo-format-buffer}, after visiting the Texinfo source file of the
+manual you want to convert.
+
+Neither @code{texinfo-format-buffer} nor @file{makeinfo} installs the
+resulting Info files in Emacs's Info tree. To install Info files,
+perform these steps:
+
+@enumerate
+@item
+Move the files to the @file{info} directory in the installed Emacs
+distribution. @xref{File-name conventions}, if you don't know where that
+is.
+
+@item
+Run the @code{install-info} command, which is part of the Texinfo
+distribution, to update the main Info directory menu, like this:
+
+@example
+ install-info --info-dir=@var{dir-path} @var{dir-path}/@var{file}
+@end example
+
+@noindent
+where @var{dir-path} is the full path to the directory where you copied
+the produced Info file(s), and @var{file} is the name of the Info file
+you produced and want to install.
+
+If you don't have the @code{install-info} command installed, you can
+edit the file @file{info/dir} in the installed Emacs distribution, and
+add a line for the top level node in the Info package that you are
+installing. Follow the examples already in this file. The format is:
+
+@example
+* Topic: (relative-pathname). Short description of topic.
+@end example
+
+@end enumerate
+
+If you want to install Info files and you don't have the necessary
+privileges, you have several options:
+
+@itemize @bullet
+@item
+Info files don't actually need to be installed before being used.
+You can use a prefix argument for the @code{info} command and specify
+the name of the Info file in the minibuffer. This goes to the node
+named @samp{Top} in that file. For example, to view a Info file named
+@file{@var{info-file}} in your home directory, you can type this:
+
+@example
+@kbd{C-u C-h i ~/@var{info-file} @key{RET}}
+@end example
+
+Alternatively, you can feed a file name to the @code{Info-goto-node}
+command (invoked by pressing @key{g} in Info mode) by typing the name
+of the file in parentheses, like this:
+
+@example
+@kbd{C-h i g (~/@var{info-file}) @key{RET}}
+@end example
+
+@item
+You can create your own Info directory. You can tell Emacs where that
+Info directory is by adding its pathname to the value of the variable
+@code{Info-default-directory-list}. For example, to use a private Info
+directory which is a subdirectory of your home directory named @file{Info},
+you could put this in your @file{.emacs} file:
+
+@lisp
+(setq Info-default-directory-list
+ (cons "~/Info" Info-default-directory-list))
+@end lisp
+
+You will need a top-level Info file named @file{dir} in this directory
+which has everything the system @file{dir} file has in it, except it should
+list only entries for Info files in that directory. You might not need
+it if all files in this directory were referenced by other @file{dir}
+files. The node lists from all @file{dir} files in
+@code{Info-default-directory-list} are merged by the Info system.
+
+@end itemize
+
+@node Printing a Texinfo file, Viewing Info files outside of Emacs, Installing Texinfo documentation, Getting help
+@section How do I print a Texinfo file?
+@cindex Printing a Texinfo file
+@cindex Texinfo file, printing
+@cindex Printing documentation
+
+You can't get nicely printed output from Info files; you must still have
+the original Texinfo source file for the manual you want to print.
+
+Assuming you have @TeX{} installed on your system, follow these steps:
+
+@enumerate
+
+@item
+Make sure the first line of the Texinfo file looks like this:
+
+@example
+\input texinfo
+@end example
+
+You may need to change @samp{texinfo} to the full pathname of the
+@file{texinfo.tex} file, which comes with Emacs as
+@file{man/texinfo.tex} (or copy or link it into the current directory).
+
+@item
+Type @kbd{texi2dvi @var{texinfo-source}}, where @var{texinfo-source} is
+the name of the Texinfo source file for which you want to produce a
+printed copy.
+
+The @samp{texi2dvi} script is part of the GNU Texinfo distribution
+(@pxref{Installing Texinfo documentation}).
+
+@item
+Print the DVI file @file{@var{texinfo-source}.dvi} in the normal way for
+printing DVI files at your site. For example, if you have a PostScript
+printer, run the @code{dvips} program to print the DVI file on that
+printer.
+
+@end enumerate
+
+To get more general instructions, retrieve the latest Texinfo package
+(@pxref{Installing Texinfo documentation}).
+
+@node Viewing Info files outside of Emacs, Informational files for Emacs, Printing a Texinfo file, Getting help
+@section Can I view Info files without using Emacs?
+@cindex Viewing Info files
+@cindex Info file viewers
+@cindex Alternative Info file viewers
+
+Yes. Here are some alternative programs:
+
+@itemize @bullet
+
+@item
+@code{info}, a stand-alone version of the Info program, comes as part of
+the Texinfo package. @xref{Installing Texinfo documentation}, for
+details.
+
+@item
+Xinfo, a stand-alone version of the Info program that runs under X
+Window system. You can get it at
+@uref{ftp://ftp.gnu.org/pub/gnu/xinfo/xinfo-1.01.01.tar.gz} and all
+mirrors of @samp{ftp.gnu.org} (see @ref{Current GNU distributions}, for a
+list of mirrors).
+
+@item
+Tkinfo, an Info viewer that runs under X Window system and uses Tcl/Tk.
+You can get Tkinfo at
+@uref{http://math-www.uni-paderborn.de/~axel/tkinfo/}.
+
+@end itemize
+
+@node Informational files for Emacs, Help installing Emacs, Viewing Info files outside of Emacs, Getting help
+@section What informational files are available for Emacs?
+@cindex Informational files included with Emacs
+@cindex Files included with Emacs
+@cindex @file{COPYING}, description of file
+@cindex @file{DISTRIB}, description of file
+@cindex @file{FTP}, description of file
+@cindex @file{GNU}, description of file
+@cindex @file{INTERVIEW}, description of file
+@cindex @file{LPF}, description of file
+@cindex @file{MACHINES}, description of file
+@cindex @file{MAILINGLISTS}, description of file
+@cindex @file{NEWS}, description of file
+@cindex @file{SERVICE}, description of file
+@cindex @file{SUN-SUPPORT}, description of file
+
+This isn't a frequently asked question, but it should be! A variety of
+informational files about Emacs and relevant aspects of the GNU project
+are available for you to read.
+
+The following files are available in the @file{etc} directory of the
+Emacs distribution (see @ref{File-name conventions}, if you're not sure
+where that is).
+
+@table @file
+
+@item COPYING
+GNU General Public License
+
+@item DISTRIB
+Emacs Availability Information, including the popular Free Software
+Foundation Order Form
+
+@item FTP
+How to get GNU Software by Internet FTP or by UUCP
+
+@item GNU
+The GNU Manifesto
+
+@item INTERVIEW
+Richard Stallman discusses his public-domain UNIX-compatible software
+system with BYTE editors
+
+@item LPF
+Why you should join the League for Programming Freedom
+
+@item MACHINES
+Status of Emacs on Various Machines and Systems
+
+@item MAILINGLISTS
+GNU Project Electronic Mailing Lists
+
+@item NEWS
+Emacs news, a history of recent user-visible changes
+
+@item SERVICE
+GNU Service Directory
+
+@item SUN-SUPPORT
+including ``Using Emacstool with GNU Emacs''
+
+@end table
+
+More GNU information, including back issues of the @cite{GNU's
+Bulletin}, are at
+
+@uref{http://www.gnu.org/bulletins/bulletins.html} and
+
+@uref{http://www.cs.pdx.edu/~trent/gnu/gnu.html}
+
+@node Help installing Emacs, Obtaining the FAQ, Informational files for Emacs, Getting help
+@section Where can I get help in installing Emacs?
+@cindex Installation help
+@cindex Help installing Emacs
+
+@xref{Installing Emacs}, for some basic installation hints, and see
+@ref{Problems building Emacs}, or @ref{Linking with -lX11 fails}, if you
+have problems with the installation.
+
+The file @file{etc/SERVICE} (see @ref{File-name conventions}, if you're
+not sure where that is) lists companies and individuals willing to sell
+you help in installing or using Emacs. An up-to-date version this file
+is available on @samp{ftp.gnu.org} (@pxref{Informational files for
+Emacs}).
+
+@node Obtaining the FAQ, , Help installing Emacs, Getting help
+@section Where can I get the latest version of this FAQ?
+@cindex FAQ, obtaining the
+@cindex Latest FAQ version, obtaining the
+@cindex Retrieving the latest FAQ version
+@cindex E-mail, retrieving the FAQ via
+@cindex Web, reading the FAQ on the
+
+The Emacs FAQ is available in several ways:
+
+@itemize @bullet
+
+@item
+Inside of Emacs itself. You can get it from selecting the @samp{Emacs
+FAQ} option from the @samp{Help} menu of the Emacs menu bar at the top
+of any Emacs frame, or by typing @kbd{C-h C-f} (@kbd{M-x view-emacs-FAQ}).
+
+@item
+Via USENET. If you can read news, the FAQ should be available in your
+news spool, in both the @uref{news:gnu.emacs.help} and
+@uref{news:comp.emacs} newsgroups. Every news reader should allow you
+to read any news article that is still in the news spool, even if you
+have read the article before. You may need to read the instructions for
+your news reader to discover how to do this. In @file{rn}, this command
+will do this for you at the article selection level:
+
+@example
+?GNU Emacs Frequently Asked Questions?rc:m
+@end example
+
+In Gnus, you should type @kbd{C-u C-x C-s} from the @file{*Summary*}
+buffer or @kbd{C-u @key{SPC}} from the @file{*Newsgroup*} buffer to view
+all articles in a newsgroup.
+
+If the FAQ articles have expired and have been deleted from your news
+spool, it might (or might not) do some good to complain to your news
+administrator, because the most recent FAQ should not expire for a
+while.
+
+@item
+In the Emacs distribution. Since Emacs 18.56, the FAQ at the time
+of release has been part of the Emacs distribution as either
+@file{etc/FAQ} or @file{man/faq.texi} (@pxref{File-name conventions}).
+
+@item
+Via anonymous ftp and e-mail from @file{rtfm.mit.edu} (and its mirror in
+Europe), the main repository for FAQs and other items posted to
+news.answers. The Emacs FAQs are available at
+
+@uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/} and
+
+@uref{ftp://ftp.uni-paderborn.de/pub/doc/FAQ/comp/emacs/}
+
+If you do not have access to anonymous FTP, you can access the archives
+using the @file{rtfm.mit.edu} mail server. The Emacs FAQ can be
+retrieved by sending mail to @email{mail-server@@rtfm.mit.edu} with a
+blank subject and containing
+
+@example
+send usenet/news.answers/GNU-Emacs-FAQ/diffs
+send usenet/news.answers/GNU-Emacs-FAQ/part1
+send usenet/news.answers/GNU-Emacs-FAQ/part2
+send usenet/news.answers/GNU-Emacs-FAQ/part3
+send usenet/news.answers/GNU-Emacs-FAQ/part4
+send usenet/news.answers/GNU-Emacs-FAQ/part5
+@end example
+
+For more information, send email to @email{mail-server@@rtfm.mit.edu}
+with @samp{help} and @samp{index} in the body on separate lines.
+@end itemize
+
+@c ------------------------------------------------------------
+@node Status of Emacs, Common requests, Getting help, Top
+@chapter Status of Emacs
+@cindex Status of Emacs
+
+This chapter gives you basic information about Emacs, including its
+latest version status.
+
+@menu
+* Origin of the term Emacs::
+* Latest version of Emacs::
+* New in Emacs 20::
+* New in Emacs 21::
+* New in Emacs 22::
+@end menu
+
+@node Origin of the term Emacs, Latest version of Emacs, Status of Emacs, Status of Emacs
+@section Where does the name ``Emacs'' come from?
+@cindex Origin of the term ``Emacs''
+@cindex Emacs name origin
+@cindex TECO
+@cindex Original version of Emacs
+
+Emacs originally was an acronym for Editor MACroS. RMS says he ``picked
+the name Emacs because @key{E} was not in use as an abbreviation on ITS at
+the time.'' The first Emacs was a set of macros written in 1976 at MIT
+by RMS for the editor TECO (Text Editor and COrrector, originally Tape
+Editor and COrrector) under ITS on a PDP-10. RMS had already extended
+TECO with a ``real-time'' full-screen mode with reprogrammable keys.
+Emacs was started by @email{gls@@east.sun.com, Guy Steele} as a project
+to unify the many divergent TECO command sets and key bindings at MIT,
+and completed by RMS.
+
+Many people have said that TECO code looks a lot like line noise; you
+can read more at @uref{news:alt.lang.teco}. Someone has written a TECO
+implementation in Emacs Lisp (to find it, see @ref{Packages that do not
+come with Emacs}); it would be an interesting project to run the
+original TECO Emacs inside of Emacs.
+
+@cindex Why Emacs?
+For some not-so-serious alternative reasons for Emacs to have that
+name, check out the file @file{etc/JOKES} (@pxref{File-name
+conventions}).
+
+@node Latest version of Emacs, New in Emacs 20, Origin of the term Emacs, Status of Emacs
+@section What is the latest version of Emacs?
+@cindex Version, latest
+@cindex Latest version of Emacs
+
+Emacs @value{VER} is the current version as of this writing.
+
+@node New in Emacs 20, New in Emacs 21, Latest version of Emacs, Status of Emacs
+@section What is different about Emacs 20?
+@cindex Differences between Emacs 19 and Emacs 20
+@cindex Emacs 20, new features in
+
+To find out what has changed in recent versions, type @kbd{C-h C-n}
+(@kbd{M-x view-emacs-news}). The oldest changes are at the bottom of
+the file, so you might want to read it starting there, rather than at
+the top.
+
+The differences between Emacs versions 18 and 19 was rather dramatic;
+the introduction of frames, faces, and colors on windowing systems was
+obvious to even the most casual user.
+
+There are differences between Emacs versions 19 and 20 as well, but many
+are more subtle or harder to find. Among the changes are the inclusion
+of MULE code for languages that use non-Latin characters and for mixing
+several languages in the same document; the ``Customize'' facility for
+modifying variables without having to use Lisp; and automatic conversion
+of files from Macintosh, Microsoft, and Unix platforms.
+
+A number of older Lisp packages, such as Gnus, Supercite and the
+calendar/diary, have been updated and enhanced to work with Emacs 20,
+and are now included with the standard distribution.
+
+
+@node New in Emacs 21, New in Emacs 22, New in Emacs 20, Status of Emacs
+@section What is different about Emacs 21?
+@cindex Differences between Emacs 20 and Emacs 21
+@cindex Emacs 21, new features in
+@cindex Recently introduced features
+
+@cindex Variable-size fonts
+@cindex Toolbar support
+Emacs 21 features a thorough rewrite of the display engine. The new
+display engine supports variable-size fonts, images, and can play sounds
+on platforms which support that. As a result, the visual appearance of
+Emacs, when it runs on a windowed display, is much more reminiscent of
+modern GUI programs, and includes 3D widgets (used for the mode line and
+the scroll bars), a configurable and extensible toolbar, tooltips
+(a.k.a.@: balloon help), and other niceties.
+
+@cindex Colors on text-only terminals
+@cindex TTY colors
+In addition, Emacs 21 supports faces on text-only terminals. This means
+that you can now have colors when you run Emacs on a GNU/Linux console
+and on @code{xterm} with @kbd{emacs -nw}.
+
+@node New in Emacs 22, , New in Emacs 21, Status of Emacs
+@section What is different about Emacs 22?
+@cindex Differences between Emacs 21 and Emacs 22
+@cindex Emacs 22, new features in
+@cindex Recently introduced features
+@cindex Default features
+
+@itemize
+@cindex GTK+ Toolkit
+@cindex Drag-and-drop
+@item
+Emacs can be built with GTK+ widgets, and supports drag-and-drop
+operation on X.
+
+@cindex Supported systems
+@item
+Emacs 22 features support for GNU/Linux systems on S390 and x86-64
+machines, as well as support for the Mac OS X and Cygwin operating
+systems.
+
+@item
+The native MS-Windows, Mac OS 9 and Mac OS X builds include full support
+for images, toolbar, and tooltips.
+
+@item
+Font Lock mode, Auto Compression mode, and File Name Shadow Mode are
+enabled by default.
+
+@item
+The maximum size of buffers has been doubled and is 256M on 32-bit
+machines.
+
+@item
+Links can be followed with @kbd{mouse-1}, in addition to @kbd{mouse-2}.
+
+@cindex Mouse wheel
+@item
+Mouse wheel support is enabled by default.
+
+@item
+Window fringes are customizable.
+
+@item
+The mode line of the selected window is now highlighted.
+
+@item
+The minibuffer prompt is displayed in a distinct face.
+
+@item
+Abbrev definitions are read automatically at startup.
+
+@item
+Grep mode is separate from Compilation mode and has many new options and
+commands specific to grep.
+
+@item
+The original Emacs macro system has been replaced by the new Kmacro
+package, which provides many new commands and features and a simple
+interface that uses the function keys F3 and F4. Macros are stored in a
+macro ring, and can be debugged and edited interactively.
+
+@item
+The Grand Unified Debugger (GUD) can be used with a full graphical user
+interface to GDB; this provides many features found in traditional
+development environments, making it easy to manipulate breakpoints, add
+watch points, display the call stack, etc. Breakpoints are visually
+indicated in the source buffer.
+
+@item
+@cindex New modes
+Many new modes and packages have been included in Emacs, such as Calc,
+TRAMP, URL, IDO, CUA, ERC, rcirc, Table, Image-Dired, SES, Ruler, Org,
+PGG, Flymake, Password, Printing, Reveal, wdired, t-mouse, longlines,
+savehist, Conf mode, Python mode, DNS mode, etc.
+
+@cindex Multilingual Environment
+@item
+Leim is now part of Emacs. Unicode support has been much improved, and
+the following input methods have been added: belarusian, bulgarian-bds,
+bulgarian-phonetic, chinese-sisheng, croatian, dutch, georgian,
+latin-alt-postfix, latin-postfix, latin-prefix, latvian-keyboard,
+lithuanian-numeric, lithuanian-keyboard, malayalam-inscript, rfc1345,
+russian-computer, sgml, slovenian, tamil-inscript, ucs,
+ukrainian-computer, vietnamese-telex, and welsh.
+
+The following language environments have also been added: Belarusian,
+Bulgarian, Chinese-EUC-TW, Croatian, French, Georgian, Italian, Latin-6,
+Latin-7, Latvian, Lithuanian, Malayalam, Russian, Slovenian, Swedish,
+Tajik, Tamil, UTF-8, Ukrainian, Welsh, and Windows-1255.
+
+@cindex Documentation
+@cindex Emacs Lisp Manual
+@item
+In addition, Emacs 22 now includes the Emacs Lisp Reference Manual
+(@pxref{Emacs Lisp documentation}) and the Emacs Lisp Intro.
+@end itemize
+
+Many other changes have been made in Emacs 22, use @kbd{C-h n} to get a
+full list.
+
+@c ------------------------------------------------------------
+@node Common requests, Bugs and problems, Status of Emacs, Top
+@chapter Common requests
+@cindex Common requests
+
+@menu
+* Setting up a customization file::
+* Using Customize::
+* Colors on a TTY::
+* Debugging a customization file::
+* Displaying the current line or column::
+* Displaying the current file name in the titlebar::
+* Turning on abbrevs by default::
+* Associating modes with files::
+* Highlighting a region::
+* Replacing highlighted text::
+* Controlling case sensitivity::
+* Working with unprintable characters::
+* Searching for/replacing newlines::
+* Yanking text in isearch::
+* Wrapping words automatically::
+* Turning on auto-fill by default::
+* Spell-checkers::
+* Checking TeX and *roff documents::
+* Changing load-path::
+* Using an already running Emacs process::
+* Compiler error messages::
+* Indenting switch statements::
+* Customizing C and C++ indentation::
+* Horizontal scrolling::
+* Overwrite mode::
+* Turning off beeping::
+* Turning the volume down::
+* Automatic indentation::
+* Matching parentheses::
+* Hiding #ifdef lines::
+* Repeating commands::
+* Valid X resources::
+* Evaluating Emacs Lisp code::
+* Changing the length of a Tab::
+* Inserting text at the beginning of each line::
+* Underlining paragraphs::
+* Forcing the cursor to remain in the same column::
+* Forcing Emacs to iconify itself::
+* Using regular expressions::
+* Replacing text across multiple files::
+* Documentation for etags::
+* Disabling backups::
+* Disabling auto-save-mode::
+* Going to a line by number::
+* Modifying pull-down menus::
+* Deleting menus and menu options::
+* Turning on syntax highlighting::
+* Scrolling only one line::
+* Editing MS-DOS files::
+* Filling paragraphs with a single space::
+* Escape sequences in shell output::
+* Fullscreen mode on MS-Windows::
+@end menu
+
+@node Setting up a customization file, Using Customize, Common requests, Common requests
+@section How do I set up a @file{.emacs} file properly?
+@cindex @file{.emacs} file, setting up
+@cindex @file{.emacs} file, locating
+@cindex Init file, setting up
+@cindex Customization file, setting up
+
+@inforef{Init File, Init File, emacs}.
+
+In general, new Emacs users should not have @file{.emacs} files, because
+it causes confusing non-standard behavior. Then they send questions to
+@email{help-gnu-emacs@@gnu.org} asking why Emacs isn't behaving as
+documented.
+
+Beginning with version 20.1, Emacs includes the new Customize facility
+(@pxref{Using Customize}). This allows users who are unfamiliar with
+Emacs Lisp to modify their @file{.emacs} files in a relatively
+straightforward way, using menus rather than Lisp code. Most packages
+support Customize as of this writing.
+
+While Customize might indeed make it easier to configure Emacs,
+consider taking a bit of time to learn Emacs Lisp and modifying your
+@file{.emacs} directly. Simple configuration options are described
+rather completely in @inforef{Init File, Init File, emacs}, for users
+interested in performing frequently requested, basic tasks.
+
+Sometimes users are unsure as to where their @file{.emacs} file should
+be found. Visiting the file as @file{~/.emacs} from Emacs will find
+the correct file.
+
+@node Using Customize, Colors on a TTY, Setting up a customization file, Common requests
+@section How do I start using Customize?
+@cindex Customize groups
+@cindex Customizing variables
+@cindex Customizing faces
+
+The main Customize entry point is @kbd{M-x customize @key{RET}}. This
+command takes you to a buffer listing all the available Customize
+groups. From there, you can access all customizable options and faces,
+change their values, and save your changes to your init file.
+@inforef{Easy Customization, Easy Customization, emacs}.
+
+If you know the name of the group in advance (e.g. ``shell''), use
+@kbd{M-x customize-group @key{RET}}.
+
+If you wish to customize a single option, use @kbd{M-x customize-option
+@key{RET}}. This command prompts you for the name of the option to
+customize, with completion.
+
+@node Colors on a TTY, Debugging a customization file, Using Customize, Common requests
+@section How do I get colors and syntax highlighting on a TTY?
+@cindex Colors on a TTY
+@cindex Syntax highlighting on a TTY
+@cindex Console, colors
+
+In Emacs 21.1 and later, colors and faces are supported in non-windowed mode,
+i.e.@: on Unix and GNU/Linux text-only terminals and consoles, and when
+invoked as @samp{emacs -nw} on X, MS-Windows, and Mac. (Colors and faces were
+supported in the MS-DOS port since Emacs 19.29.) Emacs automatically
+detects color support at startup and uses it if available. If you think
+that your terminal supports colors, but Emacs won't use them, check the
+@code{termcap} entry for your display type for color-related
+capabilities.
+
+The command @kbd{M-x list-colors-display} pops up a window which
+exhibits all the colors Emacs knows about on the current display.
+
+Syntax highlighting is on by default since version 22.1.
+
+@node Debugging a customization file, Displaying the current line or column, Colors on a TTY, Common requests
+@section How do I debug a @file{.emacs} file?
+@cindex Debugging @file{.emacs} file
+@cindex @file{.emacs} debugging
+@cindex Init file debugging
+@cindex @samp{-debug-init} option
+
+Start Emacs with the @samp{-debug-init} command-line option. This
+enables the Emacs Lisp debugger before evaluating your @file{.emacs}
+file, and places you in the debugger if something goes wrong. The top
+line in the @file{trace-back} buffer will be the error message, and the
+second or third line of that buffer will display the Lisp code from your
+@file{.emacs} file that caused the problem.
+
+You can also evaluate an individual function or argument to a function
+in your @file{.emacs} file by moving the cursor to the end of the
+function or argument and typing @kbd{C-x C-e} (@kbd{M-x
+eval-last-sexp}).
+
+Use @kbd{C-h v} (@kbd{M-x describe-variable}) to check the value of
+variables which you are trying to set or use.
+
+@node Displaying the current line or column, Displaying the current file name in the titlebar, Debugging a customization file, Common requests
+@section How do I make Emacs display the current line (or column) number?
+@cindex @code{line-number-mode}
+@cindex Displaying the current line or column
+@cindex Line number, displaying the current
+@cindex Column, displaying the current
+@cindex @code{mode-line-format}
+
+To have Emacs automatically display the current line number of the point
+in the mode line, do @kbd{M-x line-number-mode}. You can also put the
+form
+
+@lisp
+(setq line-number-mode t)
+@end lisp
+
+@noindent
+in your @file{.emacs} file to achieve this whenever you start Emacs.
+(Line number display is on by default, unless your site-specific
+initialization disables it.) Note that Emacs will not display the line
+number if the buffer's size in bytes is larger than the value of the
+variable @code{line-number-display-limit}.
+
+You can similarly display the current column with
+@kbd{M-x column-number-mode}, or by putting the form
+
+@lisp
+(setq column-number-mode t)
+@end lisp
+
+@noindent
+in your @file{.emacs} file.
+
+The @code{"%c"} format specifier in the variable @code{mode-line-format}
+will insert the current column's value into the mode line. See the
+documentation for @code{mode-line-format} (using @kbd{C-h v
+mode-line-format @key{RET}}) for more information on how to set and use
+this variable.
+
+Users of all Emacs versions can display the current column using the
+@samp{column} package written by @email{abraham@@dina.kvl.dk, Per
+Abrahamsen}. @xref{Packages that do not come with Emacs}, for
+instructions on how to get it.
+
+@cindex Set number capability in @code{vi} emulators
+None of the @code{vi} emulation modes provide the ``set number''
+capability of @code{vi} (as far as we know). The @samp{setnu} package
+written by @email{kyle@@wonderworks.com, Kyle Jones} provides this
+feature. So too does @samp{wb-line-number}, written by
+@email{naoki.y.nakamura@@nifty.com, Naoki Nakamura}.
+
+@node Displaying the current file name in the titlebar, Turning on abbrevs by default, Displaying the current line or column, Common requests
+@section How can I modify the titlebar to contain the current file name?
+@cindex Titlebar, displaying the current file name in
+@cindex File name, displaying in the titlebar
+@cindex @code{frame-title-format}
+
+The contents of an Emacs frame's titlebar is controlled by the variable
+@code{frame-title-format}, which has the same structure as the variable
+@code{mode-line-format}. (Use @kbd{C-h v} or @kbd{M-x
+describe-variable} to get information about one or both of these
+variables.)
+
+By default, the titlebar for a frame does contain the name of the buffer
+currently being visited, except if there is a single frame. In such a
+case, the titlebar contains Emacs invocation name and the name of the
+machine at which Emacs was invoked. This is done by setting
+@code{frame-title-format} to the default value of
+
+@lisp
+(multiple-frames "%b" ("" invocation-name "@@" system-name))
+@end lisp
+
+To modify the behavior such that frame titlebars contain the buffer's
+name regardless of the number of existing frames, include the following
+in your @file{.emacs}:
+
+@lisp
+(setq frame-title-format "%b")
+@end lisp
+
+@node Turning on abbrevs by default, Associating modes with files, Displaying the current file name in the titlebar, Common requests
+@section How do I turn on abbrevs by default just in mode @var{mymode}?
+@cindex Abbrevs, turning on by default
+
+Put this in your @file{.emacs} file:
+
+@lisp
+(condition-case ()
+ (quietly-read-abbrev-file)
+ (file-error nil))
+
+(add-hook '@var{mymode}-mode-hook
+ (lambda ()
+ (setq abbrev-mode t)))
+@end lisp
+
+Starting with Emacs 22, the standard abbrevs file is read automatically
+at startup, so the first of these two forms becomes unnecessary.
+
+@node Associating modes with files, Highlighting a region, Turning on abbrevs by default, Common requests
+@section How do I make Emacs use a certain major mode for certain files?
+@cindex Associating modes with files
+@cindex File extensions and modes
+@cindex @code{auto-mode-alist}, modifying
+@cindex Modes, associating with file extensions
+
+If you want to use a certain mode @var{foo} for all files whose names end
+with the extension @file{.@var{bar}}, this will do it for you:
+
+@lisp
+(setq auto-mode-alist (cons '("\\.@var{bar}\\'" . @var{foo}-mode) auto-mode-alist))
+@end lisp
+
+Otherwise put this somewhere in the first line of any file you want to
+edit in the mode @var{foo} (in the second line, if the first line begins
+with @samp{#!}):
+
+@example
+-*- @var{foo} -*-
+@end example
+
+@cindex Major mode for shell scripts
+Beginning with Emacs 19, the variable @code{interpreter-mode-alist}
+specifies which mode to use when loading a shell script. (Emacs
+determines which interpreter you're using by examining the first line of
+the script.) This feature only applies when the file name doesn't
+indicate which mode to use. Use @kbd{C-h v} (or @kbd{M-x
+describe-variable}) on @code{interpreter-mode-alist} to learn more.
+
+@node Highlighting a region, Replacing highlighted text, Associating modes with files, Common requests
+@section How can I highlight a region of text in Emacs?
+@cindex Highlighting text
+@cindex Text, highlighting
+@cindex @code{transient-mark-mode}
+@cindex Region, highlighting a
+
+You can cause the region to be highlighted when the mark is active by
+including
+
+@lisp
+(transient-mark-mode t)
+@end lisp
+
+@noindent
+in your @file{.emacs} file.
+
+@node Replacing highlighted text, Controlling case sensitivity, Highlighting a region, Common requests
+@section How can I replace highlighted text with what I type?
+@cindex @code{delete-selection-mode}
+@cindex Replacing highlighted text
+@cindex Highlighting and replacing text
+
+Use @code{delete-selection-mode}, which you can start automatically by
+placing the following Lisp form in your @file{.emacs} file:
+
+@lisp
+(delete-selection-mode 1)
+@end lisp
+
+According to the documentation string for @code{delete-selection-mode}
+(which you can read using @kbd{M-x describe-function @key{RET}
+delete-selection-mode @key{RET}}):
+
+@quotation
+When ON, typed text replaces the selection if the selection is active.
+When OFF, typed text is just inserted at point.
+@end quotation
+
+This mode also allows you to delete (not kill) the highlighted region by
+pressing @key{DEL}.
+
+@node Controlling case sensitivity, Working with unprintable characters, Replacing highlighted text, Common requests
+@section How do I control Emacs's case-sensitivity when searching/replacing?
+@cindex @code{case-fold-search}
+@cindex Case sensitivity of searches
+@cindex Searching without case sensitivity
+@cindex Ignoring case in searches
+
+For searching, the value of the variable @code{case-fold-search}
+determines whether they are case sensitive:
+
+@lisp
+(setq case-fold-search nil) ; make searches case sensitive
+(setq case-fold-search t) ; make searches case insensitive
+@end lisp
+
+@cindex Case sensitivity in replacements
+@cindex Replacing, and case sensitivity
+@cindex @code{case-replace}
+Similarly, for replacing, the variable @code{case-replace} determines
+whether replacements preserve case.
+
+You can also toggle case sensitivity at will in isearch with @kbd{M-c}.
+
+To change the case sensitivity just for one major mode, use the major
+mode's hook. For example:
+
+@lisp
+(add-hook '@var{foo}-mode-hook
+ (lambda ()
+ (setq case-fold-search nil)))
+@end lisp
+
+@node Working with unprintable characters, Searching for/replacing newlines, Controlling case sensitivity, Common requests
+@section How do I search for, delete, or replace unprintable (eight-bit or control) characters?
+@cindex Unprintable characters, working with
+@cindex Working with unprintable characters
+@cindex Control characters, working with
+@cindex Eight-bit characters, working with
+@cindex Searching for unprintable characters
+@cindex Regexps and unprintable characters
+
+To search for a single character that appears in the buffer as, for
+example, @samp{\237}, you can type @kbd{C-s C-q 2 3 7}. (This assumes
+the value of @code{search-quote-char} is 17 (i.e., @kbd{C-q}).)
+Searching for @strong{all} unprintable characters is best done with a
+regular expression (@dfn{regexp}) search. The easiest regexp to use for
+the unprintable chars is the complement of the regexp for the printable
+chars.
+
+@itemize @bullet
+
+@item
+Regexp for the printable chars: @samp{[\t\n\r\f -~]}
+
+@item
+Regexp for the unprintable chars: @samp{[^\t\n\r\f -~]}
+
+@end itemize
+
+To type these special characters in an interactive argument to
+@code{isearch-forward-regexp} or @code{re-search-forward}, you need to
+use @kbd{C-q}. (@samp{\t}, @samp{\n}, @samp{\r}, and @samp{\f} stand
+respectively for @key{TAB}, @key{LFD}, @key{RET}, and @kbd{C-l}.) So,
+to search for unprintable characters using @code{re-search-forward}:
+
+@kbd{M-x re-search-forward @key{RET} [^ @key{TAB} C-q @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~] @key{RET}}
+
+Using @code{isearch-forward-regexp}:
+
+@kbd{C-M-s [^ @key{TAB} @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~]}
+
+To delete all unprintable characters, simply use replace-regexp:
+
+@kbd{M-x replace-regexp @key{RET} [^ @key{TAB} C-q @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~] @key{RET} @key{RET}}
+
+Replacing is similar to the above. To replace all unprintable
+characters with a colon, use:
+
+M-x replace-regexp @key{RET} [^ @key{TAB} C-q @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~] @key{RET} : @key{RET}
+
+@node Searching for/replacing newlines, Yanking text in isearch, Working with unprintable characters, Common requests
+@section How do I input a newline character in isearch or query-replace?
+@cindex Searching for newlines
+@cindex Replacing newlines
+
+Use @kbd{C-q C-j}. For more information, see @inforef{Special Isearch,
+Special Input for Incremental Search, emacs}.
+
+
+@node Yanking text in isearch, Wrapping words automatically, Searching for/replacing newlines, Common requests
+@section How do I copy text from the kill ring into the search string?
+@cindex Yanking text into the search string
+@cindex isearch yanking
+
+Use @kbd{M-y}. @inforef{Isearch Yank, Isearch Yanking, emacs}.
+
+@node Wrapping words automatically, Turning on auto-fill by default, Yanking text in isearch, Common requests
+@section How do I make Emacs wrap words for me?
+@cindex Wrapping word automatically
+@cindex Wrapping lines
+@cindex Line wrap
+@cindex @code{auto-fill-mode}, introduction to
+@cindex Maximum line width, default value
+@cindex @code{fill-column}, default value
+
+Use @code{auto-fill-mode}, activated by typing @kbd{M-x auto-fill-mode}.
+The default maximum line width is 70, determined by the variable
+@code{fill-column}. To learn how to turn this on automatically, see
+@ref{Turning on auto-fill by default}.
+
+@node Turning on auto-fill by default, Spell-checkers, Wrapping words automatically, Common requests
+@section How do I turn on @code{auto-fill-mode} by default?
+@cindex @code{auto-fill-mode}, activating automatically
+@cindex Filling automatically
+@cindex Automatic entry to @code{auto-fill-mode}
+
+To turn on @code{auto-fill-mode} just once for one buffer, use @kbd{M-x
+auto-fill-mode}.
+
+To turn it on for every buffer in a certain mode, you must use the hook
+for that mode. For example, to turn on @code{auto-fill} mode for all
+text buffers, including the following in your @file{.emacs} file:
+
+@lisp
+(add-hook 'text-mode-hook 'turn-on-auto-fill)
+@end lisp
+
+If you want @code{auto-fill} mode on in all major modes, do this:
+
+@lisp
+(setq-default auto-fill-function 'do-auto-fill)
+@end lisp
+
+@node Spell-checkers, Checking TeX and *roff documents, Turning on auto-fill by default, Common requests
+@section Where can I get a better spelling checker for Emacs?
+@cindex Checking spelling
+@cindex Spelling, checking text documents
+
+Use Ispell. @xref{Ispell}.
+
+@node Checking TeX and *roff documents, Changing load-path, Spell-checkers, Common requests
+@section How can I spell-check @TeX{} or *roff documents?
+@cindex Spelling, checking @TeX{} documents
+@cindex @TeX{} documents, checking spelling in
+
+Use Ispell. Ispell can handle @TeX{} and *roff documents.
+@xref{Ispell}.
+
+@node Changing load-path, Using an already running Emacs process, Checking TeX and *roff documents, Common requests
+@section How do I change @code{load-path}?
+@cindex @code{load-path}, modifying
+@cindex Modifying @code{load-path}
+@cindex Adding to @code{load-path}
+
+In general, you should only add to the @code{load-path}. You can add
+directory @var{/dir/subdir} to the load path like this:
+
+@lisp
+(setq load-path (cons "/dir/subdir/" load-path))
+@end lisp
+
+To do this relative to your home directory:
+
+@lisp
+(setq load-path (cons "~/mysubdir/" load-path))
+@end lisp
+
+@node Using an already running Emacs process, Compiler error messages, Changing load-path, Common requests
+@section How do I use an already running Emacs from another window?
+@cindex @code{emacsclient}
+@cindex Emacs server functions
+@cindex Using an existing Emacs process
+
+@code{emacsclient}, which comes with Emacs, is for editing a file using
+an already running Emacs rather than starting up a new Emacs. It does
+this by sending a request to the already running Emacs, which must be
+expecting the request.
+
+@itemize @bullet
+
+@item
+Setup:
+
+Emacs must have executed the @code{server-start} function for
+@samp{emacsclient} to work. This can be done either by a command line
+option:
+
+@example
+emacs -f server-start
+@end example
+
+or by invoking @code{server-start} from @file{.emacs}:
+
+@lisp
+(if (@var{some conditions are met}) (server-start))
+@end lisp
+
+When this is done, Emacs creates a Unix domain socket named
+@file{server} in @file{/tmp/emacs@var{userid}}. See
+@code{server-socket-dir}.
+
+To get your news reader, mail reader, etc., to invoke
+@samp{emacsclient}, try setting the environment variable @code{EDITOR}
+(or sometimes @code{VISUAL}) to the value @samp{emacsclient}. You may
+have to specify the full pathname of the @samp{emacsclient} program
+instead. Examples:
+
+@example
+# csh commands:
+setenv EDITOR emacsclient
+
+# using full pathname
+setenv EDITOR /usr/local/emacs/etc/emacsclient
+
+# sh command:
+EDITOR=emacsclient ; export EDITOR
+@end example
+
+@item
+Normal use:
+
+When @samp{emacsclient} is run, it connects to the socket and passes its
+command line options to Emacs, which at the next opportunity will visit
+the files specified. (Line numbers can be specified just like with
+Emacs.) The user will have to switch to the Emacs window by hand. When
+the user is done editing a file, the user can type @kbd{C-x #} (or
+@kbd{M-x server-edit}) to indicate this. If there is another buffer
+requested by @code{emacsclient}, Emacs will switch to it; otherwise
+@code{emacsclient} will exit, signaling the calling program to continue.
+
+@cindex @code{gnuserv}
+There is an enhanced version of @samp{emacsclient} called
+@samp{gnuserv}, written by @email{ange@@hplb.hpl.hp.com, Andy Norman}
+(@pxref{Packages that do not come with Emacs}). @samp{gnuserv} uses
+Internet domain sockets, so it can work across most network connections.
+
+The most recent @samp{gnuserv} package is available at
+
+@uref{http://meltin.net/hacks/emacs/}
+
+@end itemize
+
+@node Compiler error messages, Indenting switch statements, Using an already running Emacs process, Common requests
+@section How do I make Emacs recognize my compiler's funny error messages?
+@cindex Compiler error messages, recognizing
+@cindex Recognizing non-standard compiler errors
+@cindex Regexps for recognizing compiler errors
+@cindex Errors, recognizing compiler
+
+Customize the @code{compilation-error-regexp-alist} variable.
+
+@node Indenting switch statements, Customizing C and C++ indentation, Compiler error messages, Common requests
+@section How do I change the indentation for @code{switch}?
+@cindex @code{switch}, indenting
+@cindex Indenting of @code{switch}
+
+Many people want to indent their @code{switch} statements like this:
+
+@example
+f()
+@{
+ switch(x) @{
+ case A:
+ x1;
+ break;
+ case B:
+ x2;
+ break;
+ default:
+ x3;
+ @}
+@}
+@end example
+
+The solution at first appears to be: set @code{c-indent-level} to 4 and
+@code{c-label-offset} to -2. However, this will give you an indentation
+spacing of four instead of two.
+
+The @emph{real} solution is to use @code{cc-mode} (the default mode for
+C programming in Emacs 20 and later) and add the following line to your
+@file{.emacs}:
+
+@lisp
+(c-set-offset 'case-label '+)
+@end lisp
+
+There appears to be no way to do this with the old @code{c-mode}.
+
+@node Customizing C and C++ indentation, Horizontal scrolling, Indenting switch statements, Common requests
+@section How to customize indentation in C, C@t{++}, and Java buffers?
+@cindex Indentation, how to customize
+@cindex Customize indentation
+
+The Emacs @code{cc-mode} features an interactive procedure for
+customizing the indentation style, which is fully explained in the
+@cite{CC Mode} manual that is part of the Emacs distribution, see
+@ref{Customizing Indentation, , Customization Indentation, ccmode,
+The CC Mode Manual}. Here's a short summary of the procedure:
+
+@enumerate
+@item
+Go to the beginning of the first line where you don't like the
+indentation and type @kbd{C-c C-o}. Emacs will prompt you for the
+syntactic symbol; type @key{RET} to accept the default it suggests.
+
+@item
+Emacs now prompts for the offset of this syntactic symbol, showing the
+default (the current definition) inside parentheses. You can choose
+one of these:
+
+@table @code
+@item 0
+No extra indentation.
+@item +
+Indent one basic offset.
+@item -
+Outdent one basic offset.
+@item ++
+Indent two basic offsets
+@item --
+Outdent two basic offsets.
+@item *
+Indent half basic offset.
+@item /
+Outdent half basic offset.
+@end table
+
+@item
+After choosing one of these symbols, type @kbd{C-c C-q} to reindent
+the line or the block according to what you just specified.
+
+@item
+If you don't like the result, go back to step 1. Otherwise, add the
+following line to your @file{.emacs}:
+
+@lisp
+(c-set-offset '@var{syntactic-symbol} @var{offset})
+@end lisp
+
+@noindent
+where @var{syntactic-symbol} is the name Emacs shows in the minibuffer
+when you type @kbd{C-c C-o} at the beginning of the line, and
+@var{offset} is one of the indentation symbols listed above (@code{+},
+@code{/}, @code{0}, etc.) that you've chosen during the interactive
+procedure.
+
+@item
+Go to the next line whose indentation is not to your liking and repeat
+the process there.
+@end enumerate
+
+It is recommended to put all the resulting @code{(c-set-offset ...)}
+customizations inside a C mode hook, like this:
+
+@lisp
+(defun my-c-mode-hook ()
+ (c-set-offset ...)
+ (c-set-offset ...))
+(add-hook 'c-mode-hook 'my-c-mode-hook)
+@end lisp
+
+@noindent
+Using @code{c-mode-hook} avoids the need to put a @w{@code{(require
+'cc-mode)}} into your @file{.emacs} file, because @code{c-set-offset}
+might be unavailable when @code{cc-mode} is not loaded.
+
+Note that @code{c-mode-hook} runs for C source files only; use
+@code{c++-mode-hook} for C@t{++} sources, @code{java-mode-hook} for
+Java sources, etc. If you want the same customizations to be in
+effect in @emph{all} languages supported by @code{cc-mode}, use
+@code{c-mode-common-hook}.
+
+@node Horizontal scrolling, Overwrite mode, Customizing C and C++ indentation, Common requests
+@section How can I make Emacs automatically scroll horizontally?
+@cindex @code{hscroll-mode}
+@cindex Horizontal scrolling
+@cindex Scrolling horizontally
+
+In Emacs 21 and later, this is on by default: if the variable
+@code{truncate-lines} is non-@code{nil} in the current buffer, Emacs
+automatically scrolls the display horizontally when point moves off the
+left or right edge of the window.
+
+Note that this is overridden by the variable
+@code{truncate-partial-width-windows} if that variable is non-nil
+and the current buffer is not full-frame width.
+
+In Emacs 20, use the @code{hscroll-mode}. Here is some information from
+the documentation, available by typing @kbd{C-h f hscroll-mode @key{RET}}:
+
+Automatically scroll horizontally when the point moves off the
+left or right edge of the window.
+
+@itemize @minus
+@item
+Type @kbd{M-x hscroll-mode} to enable it in the current buffer.
+
+@item
+Type @kbd{M-x hscroll-global-mode} to enable it in every buffer.
+
+@item
+@code{turn-on-hscroll} is useful in mode hooks as in:
+
+@lisp
+(add-hook 'text-mode-hook 'turn-on-hscroll)
+@end lisp
+
+@item
+@code{hscroll-margin} controls how close the cursor can get to the
+edge of the window.
+
+@item
+@code{hscroll-step-percent} controls how far to jump once we decide to do so.
+@end itemize
+
+@node Overwrite mode, Turning off beeping, Horizontal scrolling, Common requests
+@section How do I make Emacs ``typeover'' or ``overwrite'' instead of inserting?
+@cindex @key{Insert}
+@cindex @code{overwrite-mode}
+@cindex Overwriting existing text
+@cindex Toggling @code{overwrite-mode}
+
+@kbd{M-x overwrite-mode} (a minor mode). This toggles
+@code{overwrite-mode} on and off, so exiting from @code{overwrite-mode}
+is as easy as another @kbd{M-x overwrite-mode}.
+
+On some systems, @key{Insert} toggles @code{overwrite-mode} on and off.
+
+@node Turning off beeping, Turning the volume down, Overwrite mode, Common requests
+@section How do I stop Emacs from beeping on a terminal?
+@cindex Beeping, turning off
+@cindex Visible bell
+@cindex Bell, visible
+
+@email{martin@@cc.gatech.edu, Martin R. Frank} writes:
+
+Tell Emacs to use the @dfn{visible bell} instead of the audible bell,
+and set the visible bell to nothing.
+
+That is, put the following in your @code{TERMCAP} environment variable
+(assuming you have one):
+
+@example
+... :vb=: ...
+@end example
+
+And evaluate the following Lisp form:
+
+@example
+(setq visible-bell t)
+@end example
+
+@node Turning the volume down, Automatic indentation, Turning off beeping, Common requests
+@section How do I turn down the bell volume in Emacs running under X?
+@cindex Bell, volume of
+@cindex Volume of bell
+
+On X Window system, you can adjust the bell volume and duration for all
+programs with the shell command @code{xset}.
+
+Invoking @code{xset} without any arguments produces some basic
+information, including the following:
+
+@example
+usage: xset [-display host:dpy] option ...
+ To turn bell off:
+ -b b off b 0
+ To set bell volume, pitch and duration:
+ b [vol [pitch [dur]]] b on
+@end example
+
+@node Automatic indentation, Matching parentheses, Turning the volume down, Common requests
+@section How do I tell Emacs to automatically indent a new line to the indentation of the previous line?
+@cindex Indenting new lines
+@cindex New lines, indenting of
+@cindex Previous line, indenting according to
+@cindex Text indentation
+
+Such behavior is automatic in Emacs 20 and later. From the
+@file{etc/NEWS} file for Emacs 20.2:
+
+@example
+** In Text mode, now only blank lines separate paragraphs. This makes
+it possible to get the full benefit of Adaptive Fill mode in Text mode,
+and other modes derived from it (such as Mail mode). @key{TAB} in Text
+mode now runs the command @code{indent-relative}; this makes a practical
+difference only when you use indented paragraphs.
+
+As a result, the old Indented Text mode is now identical to Text mode,
+and is an alias for it.
+
+If you want spaces at the beginning of a line to start a paragraph, use
+the new mode, Paragraph Indent Text mode.
+@end example
+
+@cindex Prefixing lines
+@cindex Fill prefix
+If you have @code{auto-fill-mode} turned on (@pxref{Turning on auto-fill
+by default}), you can tell Emacs to prefix every line with a certain
+character sequence, the @dfn{fill prefix}. Type the prefix at the
+beginning of a line, position point after it, and then type @kbd{C-x .}
+(@code{set-fill-prefix}) to set the fill prefix. Thereafter,
+auto-filling will automatically put the fill prefix at the beginning of
+new lines, and @kbd{M-q} (@code{fill-paragraph}) will maintain any fill
+prefix when refilling the paragraph.
+
+If you have paragraphs with different levels of indentation, you will
+have to set the fill prefix to the correct value each time you move to a
+new paragraph. There are many packages available to deal with this
+(@pxref{Packages that do not come with Emacs}). Look for ``fill'' and
+``indent'' keywords for guidance.
+
+@node Matching parentheses, Hiding #ifdef lines, Automatic indentation, Common requests
+@section How do I show which parenthesis matches the one I'm looking at?
+@cindex Parentheses, matching
+@cindex @file{paren.el}
+@cindex Highlighting matching parentheses
+@cindex Pairs of parentheses, highlighting
+@cindex Matching parentheses
+
+Call @code{show-paren-mode} in your @file{.emacs} file:
+
+@lisp
+(show-paren-mode 1)
+@end lisp
+
+You can also enable this mode by selecting the @samp{Paren Match
+Highlighting} option from the @samp{Options} menu of the Emacs menu bar
+at the top of any Emacs frame.
+
+Alternatives to this mode include:
+
+@itemize @bullet
+
+@item
+If you're looking at a right parenthesis (or brace or bracket) you can
+delete it and reinsert it. Emacs will momentarily move the cursor to
+the matching parenthesis.
+
+@item
+@kbd{C-M-f} (@code{forward-sexp}) and @kbd{C-M-b} (@code{backward-sexp})
+will skip over one set of balanced parentheses, so you can see which
+parentheses match. (You can train it to skip over balanced brackets
+and braces at the same time by modifying the syntax table.)
+
+@cindex Show matching paren as in @code{vi}
+@item
+Here is some Emacs Lisp that will make the @key{%} key show the matching
+parenthesis, like in @code{vi}. In addition, if the cursor isn't over a
+parenthesis, it simply inserts a % like normal.
+
+@lisp
+;; By an unknown contributor
+
+(global-set-key "%" 'match-paren)
+
+(defun match-paren (arg)
+ "Go to the matching paren if on a paren; otherwise insert %."
+ (interactive "p")
+ (cond ((looking-at "\\s\(") (forward-list 1) (backward-char 1))
+ ((looking-at "\\s\)") (forward-char 1) (backward-list 1))
+ (t (self-insert-command (or arg 1)))))
+@end lisp
+
+@end itemize
+
+@node Hiding #ifdef lines, Repeating commands, Matching parentheses, Common requests
+@section In C mode, can I show just the lines that will be left after @code{#ifdef} commands are handled by the compiler?
+@cindex @code{#ifdef}, selective display of
+@cindex @code{hide-ifdef-mode}
+@cindex Hiding @code{#ifdef} text
+@cindex Selectively displaying @code{#ifdef} code
+
+@kbd{M-x hide-ifdef-mode}. (This is a minor mode.) You might also want
+to investigate @file{cpp.el}, which is distributed with Emacs.
+
+@node Repeating commands, Valid X resources, Hiding #ifdef lines, Common requests
+@section How do I repeat a command as many times as possible?
+@cindex Repeating commands many times
+@cindex Commands, repeating many times
+@cindex @code{.}, equivalent to @code{vi} command
+
+As of Emacs 20.3, there is indeed a @code{repeat} command (@kbd{C-x z})
+that repeats the last command. If you preface it with a prefix
+argument, the prefix arg is applied to the command.
+
+You can also type @kbd{C-x @key{ESC} @key{ESC}}
+(@code{repeat-complex-command}) to reinvoke commands that used the
+minibuffer to get arguments. In @code{repeat-complex-command} you can
+type @kbd{M-p} and @kbd{M-n} (and also up-arrow and down-arrow, if your
+keyboard has these keys) to scan through all the different complex
+commands you've typed.
+
+To repeat a set of commands, use keyboard macros. Use @kbd{C-x (} and
+@kbd{C-x )} to make a keyboard macro that invokes the command and then
+type @kbd{C-x e}. (@inforef{Keyboard Macros, Keyboard Macros, emacs}.)
+
+If you're really desperate for the @code{.} command in @code{vi} that
+redoes the last insertion/deletion, use VIPER, a @code{vi} emulation
+mode which comes with Emacs, and which appears to support it.
+(@xref{VIPER}.)
+
+@node Valid X resources, Evaluating Emacs Lisp code, Repeating commands, Common requests
+@section What are the valid X resource settings (i.e., stuff in .Xdefaults)?
+@cindex Resources, X
+@cindex X resources
+@cindex Setting X resources
+
+@inforef{X Resources, X Resources, emacs}.
+
+You can also use a resource editor, such as editres (for X11R5 and
+onwards), to look at the resource names for the menu bar, assuming Emacs
+was compiled with the X toolkit.
+
+@node Evaluating Emacs Lisp code, Changing the length of a Tab, Valid X resources, Common requests
+@section How do I execute (``evaluate'') a piece of Emacs Lisp code?
+@cindex Evaluating Lisp code
+@cindex Lisp forms, evaluating
+
+There are a number of ways to execute (@dfn{evaluate}, in Lisp lingo) an
+Emacs Lisp @dfn{form}:
+
+@itemize @bullet
+
+@item
+If you want it evaluated every time you run Emacs, put it in a file
+named @file{.emacs} in your home directory. This is known as ``your
+@file{.emacs} file,'' and contains all of your personal customizations.
+
+@item
+You can type the form in the @file{*scratch*} buffer, and then type
+@key{LFD} (or @kbd{C-j}) after it. The result of evaluating the form
+will be inserted in the buffer.
+
+@item
+In @code{emacs-lisp-mode}, typing @kbd{C-M-x} evaluates a top-level form
+before or around point.
+
+@item
+Typing @kbd{C-x C-e} in any buffer evaluates the Lisp form immediately
+before point and prints its value in the echo area.
+
+@item
+Typing @kbd{M-:} or @kbd{M-x eval-expression} allows you to type a Lisp
+form in the minibuffer which will be evaluated once you press @key{RET}.
+
+@item
+You can use @kbd{M-x load-file} to have Emacs evaluate all the Lisp
+forms in a file. (To do this from Lisp use the function @code{load}
+instead.)
+
+The functions @code{load-library}, @code{eval-region},
+@code{eval-buffer}, @code{require}, and @code{autoload} are also
+useful; see @ref{Emacs Lisp documentation}, if you want to learn more
+about them.
+
+@end itemize
+
+@node Changing the length of a Tab, Inserting text at the beginning of each line, Evaluating Emacs Lisp code, Common requests
+@section How do I change Emacs's idea of the @key{TAB} character's length?
+@cindex Tab length
+@cindex Length of tab character
+@cindex @code{default-tab-width}
+
+Set the variable @code{default-tab-width}. For example, to set
+@key{TAB} stops every 10 characters, insert the following in your
+@file{.emacs} file:
+
+@lisp
+(setq default-tab-width 10)
+@end lisp
+
+Do not confuse variable @code{tab-width} with variable
+@code{tab-stop-list}. The former is used for the display of literal
+@key{TAB} characters. The latter controls what characters are inserted
+when you press the @key{TAB} character in certain modes.
+
+@node Inserting text at the beginning of each line, Underlining paragraphs, Changing the length of a Tab, Common requests
+@section How do I insert <some text> at the beginning of every line?
+@cindex Prefixing a region with some text
+@cindex Prefix character, inserting in mail/news replies
+@cindex Replies to mail/news, inserting a prefix character
+@cindex @code{mail-yank-prefix}
+@cindex Mail replies, inserting a prefix character
+@cindex News replies, inserting a prefix character
+
+To do this to an entire buffer, type @kbd{M-< M-x replace-regexp
+@key{RET} ^ @key{RET} your text @key{RET}}.
+
+To do this to a region, use @code{string-insert-rectangle}.
+Set the mark (@kbd{C-@key{SPC}}) at the beginning of the first line you
+want to prefix, move the cursor to last line to be prefixed, and type
+@kbd{M-x string-insert-rectangle @key{RET}}. To do this for the whole
+buffer, type @kbd{C-x h M-x string-insert-rectangle @key{RET}}.
+
+If you are trying to prefix a yanked mail message with @samp{>}, you
+might want to set the variable @code{mail-yank-prefix}. In Message
+buffers, you can even use @kbd{M-;} to cite yanked messages (@kbd{M-;}
+runs the function @code{comment-region}, it is a general-purpose
+mechanism to comment regions) (@pxref{Changing the included text prefix}).
+
+@node Underlining paragraphs, Forcing the cursor to remain in the same column, Inserting text at the beginning of each line, Common requests
+@section How do I insert @samp{_^H} before each character in a region to get an underlined paragraph?
+@cindex Underlining a region of text
+@cindex @code{underline-region}
+
+Mark the region and then type @kbd{M-x underline-region @key{RET}}.
+
+@node Forcing the cursor to remain in the same column, Forcing Emacs to iconify itself, Underlining paragraphs, Common requests
+@section How do I make Emacs behave like this: when I go up or down, the cursor should stay in the same column even if the line is too short?
+@cindex @code{picture-mode}
+@cindex Remaining in the same column, regardless of contents
+@cindex Vertical movement in empty documents
+
+Use @kbd{M-x picture-mode}.
+
+See also the variable @code{track-eol} and the command
+@code{set-goal-column} bound to @kbd{C-x C-n}
+(@pxref{Moving Point, , , emacs, The GNU Emacs Manual}).
+
+@node Forcing Emacs to iconify itself, Using regular expressions, Forcing the cursor to remain in the same column, Common requests
+@section How do I tell Emacs to iconify itself?
+@cindex Iconification under the X Window System
+@cindex X Window System and iconification
+@cindex Suspending Emacs
+
+@kbd{C-z} iconifies Emacs when running under X and suspends Emacs
+otherwise. @inforef{Frame Commands, Frame Commands, emacs}.
+
+@node Using regular expressions, Replacing text across multiple files, Forcing Emacs to iconify itself, Common requests
+@section How do I use regexps (regular expressions) in Emacs?
+@cindex Regexps
+@cindex Regular expressions
+@cindex Differences between Unix and Emacs regexps
+@cindex Unix regexps, differences from Emacs
+@cindex Text strings, putting regexps in
+
+@inforef{Regexp Backslash, Regexp Backslash, emacs}.
+
+The @code{or} operator is @samp{\|}, not @samp{|}, and the grouping operators
+are @samp{\(} and @samp{\)}. Also, the string syntax for a backslash is
+@samp{\\}. To specify a regular expression like @samp{xxx\(foo\|bar\)}
+in a Lisp string, use @samp{xxx\\(foo\\|bar\\)}.
+
+Note the doubled backslashes!
+
+@itemize @bullet
+
+@item
+Unlike in Unix @file{grep}, @file{sed}, etc., a complement character set
+(@samp{[^...]}) can match a newline character (@key{LFD} a.k.a.@:
+@kbd{C-j} a.k.a.@: @samp{\n}), unless newline is mentioned as one of the
+characters not to match.
+
+@item
+The character syntax regexps (e.g., @samp{\sw}) are not
+meaningful inside character set regexps (e.g., @samp{[aeiou]}). (This
+is actually typical for regexp syntax.)
+
+@end itemize
+
+@node Replacing text across multiple files, Documentation for etags, Using regular expressions, Common requests
+@section How do I perform a replace operation across more than one file?
+@cindex Replacing strings across files
+@cindex Multiple files, replacing across
+@cindex Files, replacing strings across multiple
+@cindex Recursive search/replace operations
+
+As of Emacs 19.29, Dired mode (@kbd{M-x dired @key{RET}}, or @kbd{C-x
+d}) supports the command @code{dired-do-query-replace} (@kbd{Q}), which
+allows users to replace regular expressions in multiple files.
+
+You can use this command to perform search/replace operations on
+multiple files by following the following steps:
+
+@itemize @bullet
+@item
+Assemble a list of files you want to operate on with either
+@code{find-dired}, @code{find-name-dired} or @code{find-grep-dired}.
+
+@item
+Mark all files in the resulting Dired buffer using @kbd{t}.
+
+@item
+Use @kbd{Q} to start a @code{query-replace-regexp} session on the marked
+files.
+
+@item
+To accept all replacements in each file, hit @kbd{!}.
+@end itemize
+
+Another way to do the same thing is to use the ``tags'' feature of
+Emacs: it includes the command @code{tags-query-replace} which performs
+a query-replace across all the files mentioned in the @file{TAGS} file.
+@inforef{Tags Search, Tags Search, emacs}.
+
+@node Documentation for etags, Disabling backups, Replacing text across multiple files, Common requests
+@section Where is the documentation for @code{etags}?
+@cindex Documentation for @code{etags}
+@cindex @code{etags}, documentation for
+
+The @code{etags} man page should be in the same place as the
+@code{emacs} man page.
+
+Quick command-line switch descriptions are also available. For example,
+@samp{etags -H}.
+
+@node Disabling backups, Disabling auto-save-mode, Documentation for etags, Common requests
+@section How do I disable backup files?
+@cindex Backups, disabling
+@cindex Disabling backups
+
+You probably don't want to do this, since backups are useful, especially
+when something goes wrong.
+
+To avoid seeing backup files (and other ``uninteresting'' files) in Dired,
+load @code{dired-x} by adding the following to your @file{.emacs} file:
+
+@lisp
+(add-hook 'dired-load-hook
+ (lambda ()
+ (load "dired-x")))
+@end lisp
+
+With @code{dired-x} loaded, @kbd{M-o} toggles omitting in each dired buffer.
+You can make omitting the default for new dired buffers by putting the
+following in your @file{.emacs}:
+
+@lisp
+(add-hook 'dired-mode-hook 'dired-omit-toggle)
+@end lisp
+
+If you're tired of seeing backup files whenever you do an @samp{ls} at
+the Unix shell, try GNU @code{ls} with the @samp{-B} option. GNU
+@code{ls} is part of the GNU Fileutils package, available from
+@samp{ftp.gnu.org} and its mirrors (@pxref{Current GNU distributions}).
+
+To disable or change the way backups are made, @inforef{Backup Names, ,
+emacs}.
+
+@cindex Backup files in a single directory
+Beginning with Emacs 21.1, you can control where Emacs puts backup files
+by customizing the variable @code{backup-directory-alist}. This
+variable's value specifies that files whose names match specific patters
+should have their backups put in certain directories. A typical use is
+to add the element @code{("." . @var{dir})} to force Emacs to put
+@strong{all} backup files in the directory @file{dir}.
+
+@node Disabling auto-save-mode, Going to a line by number, Disabling backups, Common requests
+@section How do I disable @code{auto-save-mode}?
+@cindex Disabling @code{auto-save-mode}
+@cindex Auto-saving
+@cindex Saving at frequent intervals
+
+You probably don't want to do this, since auto-saving is useful,
+especially when Emacs or your computer crashes while you are editing a
+document.
+
+Instead, you might want to change the variable
+@code{auto-save-interval}, which specifies how many keystrokes Emacs
+waits before auto-saving. Increasing this value forces Emacs to wait
+longer between auto-saves, which might annoy you less.
+
+You might also want to look into Sebastian Kremer's @code{auto-save}
+package (@pxref{Packages that do not come with Emacs}). This
+package also allows you to place all auto-save files in one directory,
+such as @file{/tmp}.
+
+To disable or change how @code{auto-save-mode} works, @inforef{Auto
+Save, , emacs}.
+
+@node Going to a line by number, Modifying pull-down menus, Disabling auto-save-mode, Common requests
+@section How can I go to a certain line given its number?
+@cindex Going to a line by number
+@cindex Compilation error messages
+@cindex Recompilation
+
+Are you sure you indeed need to go to a line by its number? Perhaps all
+you want is to display a line in your source file for which a compiler
+printed an error message? If so, compiling from within Emacs using the
+@kbd{M-x compile} and @kbd{M-x recompile} commands is a much more
+effective way of doing that. Emacs automatically intercepts the compile
+error messages, inserts them into a special buffer called
+@code{*compilation*}, and lets you visit the locus of each message in
+the source. Type @kbd{C-x `} to step through the offending lines one by
+one (starting with Emacs 22, you can also use @kbd{M-g M-p} and
+@kbd{M-g M-n} to go to the previous and next matches directly). Click
+@kbd{Mouse-2} or press @key{RET} on a message text in the
+@code{*compilation*} buffer to go to the line whose number is mentioned
+in that message.
+
+But if you indeed need to go to a certain text line, type @kbd{M-g M-g}
+(which is the default binding of the @code{goto-line} function starting
+with Emacs 22). Emacs will prompt you for the number of the line and go
+to that line.
+
+You can do this faster by invoking @code{goto-line} with a numeric
+argument that is the line's number. For example, @kbd{C-u 286 M-g M-g}
+will jump to line number 286 in the current buffer.
+
+@node Modifying pull-down menus, Deleting menus and menu options, Going to a line by number, Common requests
+@section How can I create or modify new pull-down menu options?
+@cindex Pull-down menus, creating or modifying
+@cindex Menus, creating or modifying
+@cindex Creating new menu options
+@cindex Modifying pull-down menus
+@cindex Menus and keymaps
+@cindex Keymaps and menus
+
+Each menu title (e.g., @samp{File}, @samp{Edit}, @samp{Buffers})
+represents a local or global keymap. Selecting a menu title with the
+mouse displays that keymap's non-@code{nil} contents in the form of a menu.
+
+So to add a menu option to an existing menu, all you have to do is add a
+new definition to the appropriate keymap. Adding a @samp{Forward Word}
+item to the @samp{Edit} menu thus requires the following Lisp code:
+
+@lisp
+(define-key global-map
+ [menu-bar edit forward]
+ '("Forward word" . forward-word))
+@end lisp
+
+@noindent
+The first line adds the entry to the global keymap, which includes
+global menu bar entries. Replacing the reference to @code{global-map}
+with a local keymap would add this menu option only within a particular
+mode.
+
+The second line describes the path from the menu-bar to the new entry.
+Placing this menu entry underneath the @samp{File} menu would mean
+changing the word @code{edit} in the second line to @code{file}.
+
+The third line is a cons cell whose first element is the title that will
+be displayed, and whose second element is the function that will be
+called when that menu option is invoked.
+
+To add a new menu, rather than a new option to an existing menu, we must
+define an entirely new keymap:
+
+@lisp
+(define-key global-map [menu-bar words]
+ (cons "Words" (make-sparse-keymap "Words")))
+@end lisp
+
+The above code creates a new sparse keymap, gives it the name
+@samp{Words}, and attaches it to the global menu bar. Adding the
+@samp{Forward Word} item to this new menu would thus require the
+following code:
+
+@lisp
+(define-key global-map
+ [menu-bar words forward]
+ '("Forward word" . forward-word))
+@end lisp
+
+@noindent
+Note that because of the way keymaps work, menu options are displayed
+with the more recently defined items at the top. Thus if you were to
+define menu options @samp{foo}, @samp{bar}, and @samp{baz} (in that
+order), the menu option @samp{baz} would appear at the top, and
+@samp{foo} would be at the bottom.
+
+One way to avoid this problem is to use the function @code{define-key-after},
+which works the same as @code{define-key}, but lets you modify where items
+appear. The following Lisp code would insert the @samp{Forward Word}
+item in the @samp{Edit} menu immediately following the @samp{Undo} item:
+
+@lisp
+(define-key-after
+ (lookup-key global-map [menu-bar edit])
+ [forward]
+ '("Forward word" . forward-word)
+ 'undo)
+@end lisp
+
+Note how the second and third arguments to @code{define-key-after} are
+different from those of @code{define-key}, and that we have added a new
+(final) argument, the function after which our new key should be
+defined.
+
+To move a menu option from one position to another, simply evaluate
+@code{define-key-after} with the appropriate final argument.
+
+More detailed information---and more examples of how to create and
+modify menu options---are in the @cite{Emacs Lisp Reference Manual}, under
+``Menu Keymaps.'' (@xref{Emacs Lisp documentation}, for information on
+this manual.)
+
+@node Deleting menus and menu options, Turning on syntax highlighting, Modifying pull-down menus, Common requests
+@section How do I delete menus and menu options?
+@cindex Deleting menus and menu options
+@cindex Menus, deleting
+
+The simplest way to remove a menu is to set its keymap to @samp{nil}.
+For example, to delete the @samp{Words} menu (@pxref{Modifying pull-down
+menus}), use:
+
+@lisp
+(define-key global-map [menu-bar words] nil)
+@end lisp
+
+Similarly, removing a menu option requires redefining a keymap entry to
+@code{nil}. For example, to delete the @samp{Forward word} menu option
+from the @samp{Edit} menu (we added it in @ref{Modifying pull-down
+menus}), use:
+
+@lisp
+(define-key global-map [menu-bar edit forward] nil)
+@end lisp
+
+@node Turning on syntax highlighting, Scrolling only one line, Deleting menus and menu options, Common requests
+@section How do I turn on syntax highlighting?
+@cindex Syntax highlighting
+@cindex @code{font-lock-mode}
+@cindex Highlighting based on syntax
+@cindex Colorizing text
+@cindex FAQ, @code{font-lock-mode}
+
+@code{font-lock-mode} is the standard way to have Emacs perform syntax
+highlighting in the current buffer. It is enabled by default in Emacs
+22.1 and later.
+
+With @code{font-lock-mode} turned on, different types of text will
+appear in different colors. For instance, in a programming mode,
+variables will appear in one face, keywords in a second, and comments in
+a third.
+
+@cindex hilit19 is deprecated
+Earlier versions of Emacs supported hilit19, a similar package. Use of
+hilit19 is now considered non-standard, although @file{hilit19.el} comes
+with the stock Emacs distribution. It is no longer maintained.
+
+To turn @code{font-lock-mode} off within an existing buffer, use
+@kbd{M-x font-lock-mode @key{RET}}.
+
+In Emacs 21 and earlier versions, you could use the following code in
+your @file{.emacs} file to turn on @code{font-lock-mode} globally:
+
+@lisp
+(global-font-lock-mode 1)
+@end lisp
+
+Highlighting a buffer with @code{font-lock-mode} can take quite a while,
+and cause an annoying delay in display, so several features exist to
+work around this.
+
+@cindex Just-In-Time syntax highlighting
+In Emacs 21 and later, turning on @code{font-lock-mode} automatically
+activates the new @dfn{Just-In-Time fontification} provided by
+@code{jit-lock-mode}. @code{jit-lock-mode} defers the fontification of
+portions of buffer until you actually need to see them, and can also
+fontify while Emacs is idle. This makes display of the visible portion
+of a buffer almost instantaneous. For details about customizing
+@code{jit-lock-mode}, type @kbd{C-h f jit-lock-mode @key{RET}}.
+
+@cindex Levels of syntax highlighting
+@cindex Decoration level, in @code{font-lock-mode}
+In versions of Emacs before 21, different levels of decoration are
+available, from slight to gaudy. More decoration means you need to wait
+more time for a buffer to be fontified (or a faster machine). To
+control how decorated your buffers should become, set the value of
+@code{font-lock-maximum-decoration} in your @file{.emacs} file, with a
+@code{nil} value indicating default (usually minimum) decoration, and a
+@code{t} value indicating the maximum decoration. For the gaudiest
+possible look, then, include the line
+
+@lisp
+(setq font-lock-maximum-decoration t)
+@end lisp
+
+@noindent
+in your @file{.emacs} file. You can also set this variable such that
+different modes are highlighted in a different ways; for more
+information, see the documentation for
+@code{font-lock-maximum-decoration} with @kbd{C-h v} (or @kbd{M-x
+describe-variable @key{RET}}).
+
+Also see the documentation for the function @code{font-lock-mode},
+available by typing @kbd{C-h f font-lock-mode} (@kbd{M-x
+describe-function @key{RET} font-lock-mode @key{RET}}).
+
+To print buffers with the faces (i.e., colors and fonts) intact, use
+@kbd{M-x ps-print-buffer-with-faces} or @kbd{M-x
+ps-print-region-with-faces}. You will need a way to send text to a
+PostScript printer, or a PostScript interpreter such as Ghostscript;
+consult the documentation of the variables @code{ps-printer-name},
+@code{ps-lpr-command}, and @code{ps-lpr-switches} for more details.
+
+@node Scrolling only one line, Editing MS-DOS files, Turning on syntax highlighting, Common requests
+@section How can I force Emacs to scroll only one line when I move past the bottom of the screen?
+@cindex Scrolling only one line
+@cindex Reducing the increment when scrolling
+
+Customize the @code{scroll-conservatively} variable with @kbd{M-x
+customize-variable @key{RET} scroll-conservatively @key{RET}} and set it
+to a large value like, say, 10000. For an explanation of what this
+means, @inforef{Auto Scrolling, Auto Scrolling, emacs}.
+
+Alternatively, use the following Lisp form in your @file{.emacs}:
+
+@lisp
+(setq scroll-conservatively most-positive-fixnum)
+@end lisp
+
+@node Editing MS-DOS files, Filling paragraphs with a single space, Scrolling only one line, Common requests
+@section How can I edit MS-DOS files using Emacs?
+@cindex Editing MS-DOS files
+@cindex MS-DOS files, editing
+@cindex Microsoft files, editing
+@cindex Windows files, editing
+
+As of Emacs 20, detection and handling of MS-DOS (and Windows) files is
+performed transparently. You can open MS-DOS files on a Unix system,
+edit it, and save it without having to worry about the file format.
+
+When editing an MS-DOS style file, the mode line will indicate that it
+is a DOS file. On Unix and GNU/Linux systems, and also on a Macintosh,
+the string @samp{(DOS)} will appear near the left edge of the mode line;
+on DOS and Windows, where the DOS end-of-line (EOL) format is the
+default, a backslash (@samp{\}) will appear in the mode line.
+
+If you are running a version of Emacs before 20.1, get @code{crypt++}
+(@pxref{Packages that do not come with Emacs}). Among other things,
+@code{crypt++} transparently modifies MS-DOS files as they are loaded
+and saved, allowing you to ignore the different conventions that Unix
+and MS-DOS have for delineating the end of a line.
+
+@node Filling paragraphs with a single space, Escape sequences in shell output, Editing MS-DOS files, Common requests
+@section How can I tell Emacs to fill paragraphs with a single space after each period?
+@cindex One space following periods
+@cindex Single space following periods
+@cindex Periods, one space following
+
+Add the following line to your @file{.emacs} file:
+
+@lisp
+(setq sentence-end-double-space nil)
+@end lisp
+
+@node Escape sequences in shell output, Fullscreen mode on MS-Windows, Filling paragraphs with a single space, Common requests
+@section Why these strange escape sequences from @code{ls} from the Shell mode?
+@cindex Escape sequences in @code{ls} output
+@cindex @code{ls} in Shell mode
+
+This happens because @code{ls} is aliased to @samp{ls --color} in your
+shell init file. You have two alternatives to solve this:
+
+@itemize @bullet
+@item
+Make the alias conditioned on the @code{EMACS} variable in the
+environment. When Emacs runs a subsidiary shell, it exports the
+@code{EMACS} variable to that shell, with value equal to the absolute
+file name of Emacs. You can
+unalias @code{ls} when that happens, thus limiting the alias to your
+interactive sessions.
+
+@item
+Install the @code{ansi-color} package (bundled with Emacs 21.1 and
+later), which converts these ANSI escape sequences into colors.
+@end itemize
+
+@node Fullscreen mode on MS-Windows, , Escape sequences in shell output, Common requests
+@section How can I start Emacs in fullscreen mode on MS-Windows?
+@cindex Maximize frame
+@cindex Fullscreen mode
+
+Use the function @code{w32-send-sys-command}. For example, you can
+put the following in your @file{.emacs} file:
+
+@lisp
+(add-hook 'term-setup-hook
+ #'(lambda () (w32-send-sys-command ?\xF030)))
+@end lisp
+
+To avoid the slightly distracting visual effect of Emacs starting with
+its default frame size and then growing to fullscreen, you can add an
+@samp{Emacs.Geometry} entry to the Windows registry settings (see
+@pxref{(emacs)X Resources}).
+
+To compute the correct values for width and height, first maximize the
+Emacs frame and then evaluate @code{(frame-height)} and
+@code{(frame-width)} with @kbd{M-:}.
+
+@c ------------------------------------------------------------
+@node Bugs and problems, Compiling and installing Emacs, Common requests, Top
+@chapter Bugs and problems
+@cindex Bugs and problems
+
+The Emacs manual lists some common kinds of trouble users could get
+into, see @ref{Lossage, , Dealing with Emacs Trouble, emacs, The GNU
+Emacs Manual}, so you might look there if the problem you encounter
+isn't described in this chapter. If you decide you've discovered a bug,
+see @ref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}, for
+instructions how to do that.
+
+The file @file{etc/PROBLEMS} in the Emacs distribution lists various
+known problems with building and using Emacs on specific platforms;
+type @kbd{C-h C-e} to read it.
+
+@menu
+* Problems with very large files::
+* ^M in the shell buffer::
+* Shell process exits abnormally::
+* Problems with Shell Mode on MS-Windows::
+* Termcap/Terminfo entries for Emacs::
+* Spontaneous entry into isearch-mode::
+* Problems talking to certain hosts::
+* Errors with init files::
+* Emacs ignores X resources::
+* Emacs ignores frame parameters::
+* Emacs takes a long time to visit files::
+* Editing files with $ in the name::
+* Shell mode loses the current directory::
+* Security risks with Emacs::
+* Dired claims that no file is on this line::
+@end menu
+
+@node Problems with very large files, ^M in the shell buffer, Bugs and problems, Bugs and problems
+@section Does Emacs have problems with files larger than 8 megabytes?
+@cindex Very large files, opening
+@cindex Large files, opening
+@cindex Opening very large files
+@cindex Maximum file size
+@cindex Files, maximum size
+
+Old versions (i.e., anything before 19.29) of Emacs had problems editing
+files larger than 8 megabytes. In versions 19.29 and later, the maximum
+buffer size is at least 2^27-1, or 134,217,727 bytes, or 132 MBytes.
+And in Emacs 22, the maximum buffer size has been increased to
+268,435,455 bytes (or 256 MBytes) on 32-bit machines.
+
+@node ^M in the shell buffer, Shell process exits abnormally, Problems with very large files, Bugs and problems
+@section How do I get rid of @samp{^M} or echoed commands in my shell buffer?
+@cindex Shell buffer, echoed commands and @samp{^M} in
+@cindex Echoed commands in @code{shell-mode}
+
+Try typing @kbd{M-x shell-strip-ctrl-m @key{RET}} while in @code{shell-mode} to
+make them go away. If that doesn't work, you have several options:
+
+For @code{tcsh}, put this in your @file{.cshrc} (or @file{.tcshrc})
+file:
+
+@example
+if ($?EMACS) then
+ if ("$EMACS" =~ /*) then
+ if ($?tcsh) unset edit
+ stty nl
+ endif
+endif
+@end example
+
+Or put this in your @file{.emacs_tcsh} or @file{~/.emacs.d/init_tcsh.sh} file:
+
+@example
+unset edit
+stty nl
+@end example
+
+Alternatively, use @code{csh} in your shell buffers instead of
+@code{tcsh}. One way is:
+
+@lisp
+(setq explicit-shell-file-name "/bin/csh")
+@end lisp
+
+@noindent
+and another is to do this in your @file{.cshrc} (or @file{.tcshrc})
+file:
+
+@example
+setenv ESHELL /bin/csh
+@end example
+
+@noindent
+(You must start Emacs over again with the environment variable properly
+set for this to take effect.)
+
+You can also set the @code{ESHELL} environment variable in Emacs Lisp
+with the following Lisp form,
+
+@lisp
+(setenv "ESHELL" "/bin/csh")
+@end lisp
+
+The above solutions try to prevent the shell from producing the
+@samp{^M} characters in the first place. If this is not possible
+(e.g., if you use a Windows shell), you can get Emacs to remove these
+characters from the buffer by adding this to your @file{.emacs} init
+file:
+
+@smalllisp
+(add-hook 'comint-output-filter-functions 'shell-strip-ctrl-m)
+@end smalllisp
+
+On a related note: if your shell is echoing your input line in the shell
+buffer, you might want to customize the @code{comint-process-echoes}
+variable in your shell buffers, or try the following command in your
+shell start-up file:
+
+@example
+stty -icrnl -onlcr -echo susp ^Z
+@end example
+
+@node Shell process exits abnormally, Problems with Shell Mode on MS-Windows, ^M in the shell buffer, Bugs and problems
+@section Why do I get ``Process shell exited abnormally with code 1''?
+@cindex Abnormal exits from @code{shell-mode}
+@cindex @code{shell-mode} exits
+@cindex Process shell exited
+
+The most likely reason for this message is that the @samp{env} program
+is not properly installed. Compile this program for your architecture,
+and install it with @samp{a+x} permission in the architecture-dependent
+Emacs program directory. (You can find what this directory is at your
+site by inspecting the value of the variable @code{exec-directory} by
+typing @kbd{C-h v exec-directory @key{RET}}.)
+
+You should also check for other programs named @samp{env} in your path
+(e.g., SunOS has a program named @file{/usr/bin/env}). We don't
+understand why this can cause a failure and don't know a general
+solution for working around the problem in this case.
+
+The @samp{make clean} command will remove @samp{env} and other vital
+programs, so be careful when using it.
+
+It has been reported that this sometimes happened when Emacs was started
+as an X client from an xterm window (i.e., had a controlling tty) but the
+xterm was later terminated.
+
+See also @samp{PROBLEMS} (in the @file{etc} subdirectory of the
+top-level directory when you unpack the Emacs source) for other
+possible causes of this message.
+
+@node Problems with Shell Mode on MS-Windows, Termcap/Terminfo entries for Emacs, Shell process exits abnormally, Bugs and problems
+@section Why do I get an error message when I try to run @kbd{M-x shell}?
+
+@cindex Shell Mode, and MS-Windows
+@cindex @code{explicit-shell-file-name}
+On MS-Windows, this might happen because Emacs tries to look for the
+shell in a wrong place. The default file name @file{/bin/sh} is
+usually incorrect for non-Unix systems. If you know where your shell
+executable is, set the variable @code{explicit-shell-file-name} in
+your @file{.emacs} file to point to its full file name, like this:
+
+@lisp
+(setq explicit-shell-file-name "d:/shells/bash.exe")
+@end lisp
+
+If you don't know what shell does Emacs use, try the @kbd{M-!}
+command; if that works, put the following line into your
+@file{.emacs}:
+
+@lisp
+(setq explicit-shell-file-name shell-file-name)
+@end lisp
+
+@cindex Antivirus programs, and Shell Mode
+Some people have trouble with Shell Mode because of intrusive
+antivirus software; disabling the resident antivirus program solves
+the problems in those cases.
+
+@node Termcap/Terminfo entries for Emacs, Spontaneous entry into isearch-mode, Problems with Shell Mode on MS-Windows, Bugs and problems
+@section Where is the termcap/terminfo entry for terminal type @samp{emacs}?
+@cindex Termcap
+@cindex Terminfo
+@cindex Emacs entries for termcap/terminfo
+
+The termcap entry for terminal type @samp{emacs} is ordinarily put in
+the @samp{TERMCAP} environment variable of subshells. It may help in
+certain situations (e.g., using rlogin from shell buffer) to add an
+entry for @samp{emacs} to the system-wide termcap file. Here is a
+correct termcap entry for @samp{emacs}:
+
+@example
+emacs:tc=unknown:
+@end example
+
+To make a terminfo entry for @samp{emacs}, use @code{tic} or
+@code{captoinfo}. You need to generate
+@file{/usr/lib/terminfo/e/emacs}. It may work to simply copy
+@file{/usr/lib/terminfo/d/dumb} to @file{/usr/lib/terminfo/e/emacs}.
+
+Having a termcap/terminfo entry will not enable the use of full screen
+programs in shell buffers. Use @kbd{M-x terminal-emulator} for that
+instead.
+
+A workaround to the problem of missing termcap/terminfo entries is to
+change terminal type @samp{emacs} to type @samp{dumb} or @samp{unknown}
+in your shell start up file. @code{csh} users could put this in their
+@file{.cshrc} files:
+
+@example
+if ("$term" == emacs) set term=dumb
+@end example
+
+@node Spontaneous entry into isearch-mode, Problems talking to certain hosts, Termcap/Terminfo entries for Emacs, Bugs and problems
+@section Why does Emacs spontaneously start displaying @samp{I-search:} and beeping?
+@cindex Spontaneous entry into isearch-mode
+@cindex isearch-mode, spontaneous entry into
+@cindex Beeping without obvious reason
+
+Your terminal (or something between your terminal and the computer) is
+sending @kbd{C-s} and @kbd{C-q} for flow control, and Emacs is receiving
+these characters and interpreting them as commands. (The @kbd{C-s}
+character normally invokes the @code{isearch-forward} command.) For
+possible solutions, see @ref{Handling C-s and C-q with flow control}.
+
+@node Problems talking to certain hosts, Errors with init files, Spontaneous entry into isearch-mode, Bugs and problems
+@section Why can't Emacs talk to certain hosts (or certain hostnames)?
+@cindex Hosts, Emacs cannot talk to
+@cindex @code{gethostbyname}, problematic version
+
+The problem may be that Emacs is linked with a wimpier version of
+@code{gethostbyname} than the rest of the programs on the machine. This
+is often manifested as a message on startup of ``X server not responding.
+Check your @samp{DISPLAY} environment variable.'' or a message of
+``Unknown host'' from @code{open-network-stream}.
+
+On a Sun, this may be because Emacs had to be linked with the static C
+library. The version of @code{gethostbyname} in the static C library
+may only look in @file{/etc/hosts} and the NIS (YP) maps, while the
+version in the dynamic C library may be smart enough to check DNS in
+addition to or instead of NIS. On a Motorola Delta running System V
+R3.6, the version of @code{gethostbyname} in the standard library works,
+but the one that works with NIS doesn't (the one you get with -linet).
+Other operating systems have similar problems.
+
+Try these options:
+
+@itemize @bullet
+
+@item
+Explicitly add the host you want to communicate with to @file{/etc/hosts}.
+
+@item
+Relink Emacs with this line in @file{src/config.h}:
+
+@example
+#define LIBS_SYSTEM -lresolv
+@end example
+
+@item
+Replace @code{gethostbyname} and friends in @file{libc.a} with more
+useful versions such as the ones in @file{libresolv.a}. Then relink
+Emacs.
+
+@item
+If you are actually running NIS, make sure that @code{ypbind} is
+properly told to do DNS lookups with the correct command line switch.
+
+@end itemize
+
+@node Errors with init files, Emacs ignores X resources, Problems talking to certain hosts, Bugs and problems
+@section Why does Emacs say @samp{Error in init file}?
+@cindex Error in @file{.emacs}
+@cindex Error in init file
+@cindex Init file, errors in
+@cindex @file{.emacs} file, errors in
+@cindex Debugging @file{.emacs} file
+
+An error occurred while loading either your @file{.emacs} file or the
+system-wide file @file{lisp/default.el}. Emacs 21.1 and later pops the
+@file{*Messages*} buffer, and puts there some additional information
+about the error, to provide some hints for debugging.
+
+For information on how to debug your @file{.emacs} file, see
+@ref{Debugging a customization file}.
+
+It may be the case that you need to load some package first, or use a
+hook that will be evaluated after the package is loaded. A common case
+of this is explained in @ref{Terminal setup code works after Emacs has
+begun}.
+
+@node Emacs ignores X resources, Emacs ignores frame parameters, Errors with init files, Bugs and problems
+@section Why does Emacs ignore my X resources (my .Xdefaults file)?
+@cindex X resources being ignored
+@cindex Ignored X resources
+@cindex @file{.Xdefaults}
+
+As of version 19, Emacs searches for X resources in the files specified
+by the following environment variables:
+
+@itemize @bullet
+
+@item @code{XFILESEARCHPATH}
+@item @code{XUSERFILESEARCHPATH}
+@item @code{XAPPLRESDIR}
+
+@end itemize
+
+This emulates the functionality provided by programs written using the
+Xt toolkit.
+
+@code{XFILESEARCHPATH} and @code{XUSERFILESEARCHPATH} should be a list
+of file names separated by colons. @code{XAPPLRESDIR} should be a list
+of directory names separated by colons.
+
+Emacs searches for X resources:
+
+@enumerate
+
+@item
+specified on the command line, with the @samp{-xrm RESOURCESTRING} option,
+
+@item
+then in the value of the @samp{XENVIRONMENT} environment variable,
+
+@itemize @minus
+
+@item
+or if that is unset, in the file named
+@file{~/.Xdefaults-@var{hostname}} if it exists (where @var{hostname} is
+the name of the machine Emacs is running on),
+
+@end itemize
+
+@item
+then in the screen-specific and server-wide resource properties provided
+by the server,
+
+@itemize @minus
+
+@item
+or if those properties are unset, in the file named @file{~/.Xdefaults}
+if it exists,
+
+@end itemize
+
+@item
+then in the files listed in @samp{XUSERFILESEARCHPATH},
+
+@itemize @minus
+
+@item
+or in files named @file{@var{lang}/Emacs} in directories listed in
+@samp{XAPPLRESDIR} (where @var{lang} is the value of the @code{LANG}
+environment variable), if the @samp{LANG} environment variable is set,
+@item
+or in files named Emacs in the directories listed in @samp{XAPPLRESDIR}
+@item
+or in @file{~/@var{lang}/Emacs} (if the @code{LANG} environment variable
+is set),
+@item
+or in @file{~/Emacs},
+
+@end itemize
+
+@item
+then in the files listed in @code{XFILESEARCHPATH}.
+
+@end enumerate
+
+@node Emacs ignores frame parameters, Emacs takes a long time to visit files, Emacs ignores X resources, Bugs and problems
+@section Why don't my customizations of the frame parameters work?
+@cindex Frame parameters
+
+This probably happens because you have set the frame parameters in the
+variable @code{initial-frame-alist}. That variable holds parameters
+used only for the first frame created when Emacs starts. To customize
+the parameters of all frames, change the variable
+@code{default-frame-alist} instead.
+
+These two variables exist because many users customize the initial frame
+in a special way. For example, you could determine the position and
+size of the initial frame, but would like to control the geometry of the
+other frames by individually positioning each one of them.
+
+
+@node Emacs takes a long time to visit files, Editing files with $ in the name, Emacs ignores frame parameters, Bugs and problems
+@section Why does Emacs take 20 seconds to visit a file?
+@cindex Visiting files takes a long time
+@cindex Delay when visiting files
+@cindex Files, take a long time to visit
+
+Old versions of Emacs (i.e., versions before Emacs 20.x) often
+encountered this when the master lock file, @file{!!!SuperLock!!!}, has
+been left in the lock directory somehow. Delete it.
+
+@email{meuer@@geom.umn.edu, Mark Meuer} says that NeXT NFS has a bug
+where an exclusive create succeeds but returns an error status. This
+can cause the same problem. Since Emacs's file locking doesn't work
+over NFS anyway, the best solution is to recompile Emacs with
+@code{CLASH_DETECTION} undefined.
+
+@node Editing files with $ in the name, Shell mode loses the current directory, Emacs takes a long time to visit files, Bugs and problems
+@section How do I edit a file with a @samp{$} in its name?
+@cindex Editing files with @samp{$} in the name
+@cindex @samp{$} in file names
+@cindex File names containing @samp{$}, editing
+
+When entering a file name in the minibuffer, Emacs will attempt to expand
+a @samp{$} followed by a word as an environment variable. To suppress
+this behavior, type @kbd{$$} instead.
+
+@node Shell mode loses the current directory, Security risks with Emacs, Editing files with $ in the name, Bugs and problems
+@section Why does shell mode lose track of the shell's current directory?
+@cindex Current directory and @code{shell-mode}
+@cindex @code{shell-mode} and current directory
+@cindex Directory, current in @code{shell-mode}
+
+Emacs has no way of knowing when the shell actually changes its
+directory. This is an intrinsic limitation of Unix. So it tries to
+guess by recognizing @samp{cd} commands. If you type @kbd{cd} followed
+by a directory name with a variable reference (@kbd{cd $HOME/bin}) or
+with a shell metacharacter (@kbd{cd ../lib*}), Emacs will fail to
+correctly guess the shell's new current directory. A huge variety of
+fixes and enhancements to shell mode for this problem have been written
+to handle this problem (@pxref{Finding a package with particular
+functionality}).
+
+You can tell Emacs the shell's current directory with the command
+@kbd{M-x dirs}.
+
+@node Security risks with Emacs, Dired claims that no file is on this line, Shell mode loses the current directory, Bugs and problems
+@section Are there any security risks in Emacs?
+@cindex Security with Emacs
+@cindex @samp{movemail} and security
+@cindex @code{file-local-variable} and security
+@cindex Synthetic X events and security
+@cindex X events and security
+
+@itemize @bullet
+
+@item
+The @file{movemail} incident. (No, this is not a risk.)
+
+In his book @cite{The Cuckoo's Egg}, Cliff Stoll describes this in
+chapter 4. The site at LBL had installed the @file{/etc/movemail}
+program setuid root. (As of version 19, @file{movemail} is in your
+architecture-specific directory; type @kbd{C-h v exec-directory
+@key{RET}} to see what it is.) Since @code{movemail} had not been
+designed for this situation, a security hole was created and users could
+get root privileges.
+
+@code{movemail} has since been changed so that this security hole will
+not exist, even if it is installed setuid root. However,
+@code{movemail} no longer needs to be installed setuid root, which
+should eliminate this particular risk.
+
+We have heard unverified reports that the 1988 Internet worm took
+advantage of this configuration problem.
+
+@item
+The @code{file-local-variable} feature. (Yes, a risk, but easy to
+change.)
+
+There is an Emacs feature that allows the setting of local values for
+variables when editing a file by including specially formatted text near
+the end of the file. This feature also includes the ability to have
+arbitrary Emacs Lisp code evaluated when the file is visited.
+Obviously, there is a potential for Trojan horses to exploit this
+feature.
+
+As of Emacs 22, Emacs has a list of local variables that are known to
+be safe to set. If a file tries to set any variable outside this
+list, it asks the user to confirm whether the variables should be set.
+You can also tell Emacs whether to allow the evaluation of Emacs Lisp
+code found at the bottom of files by setting the variable
+@code{enable-local-eval}.
+
+For more information, @inforef{File Variables, File Variables, emacs}.
+
+@item
+Synthetic X events. (Yes, a risk; use @samp{MIT-MAGIC-COOKIE-1} or
+better.)
+
+Emacs accepts synthetic X events generated by the @code{SendEvent}
+request as though they were regular events. As a result, if you are
+using the trivial host-based authentication, other users who can open X
+connections to your X workstation can make your Emacs process do
+anything, including run other processes with your privileges.
+
+The only fix for this is to prevent other users from being able to open
+X connections. The standard way to prevent this is to use a real
+authentication mechanism, such as @samp{MIT-MAGIC-COOKIE-1}. If using
+the @code{xauth} program has any effect, then you are probably using
+@samp{MIT-MAGIC-COOKIE-1}. Your site may be using a superior
+authentication method; ask your system administrator.
+
+If real authentication is not a possibility, you may be satisfied by
+just allowing hosts access for brief intervals while you start your X
+programs, then removing the access. This reduces the risk somewhat by
+narrowing the time window when hostile users would have access, but
+@emph{does not eliminate the risk}.
+
+On most computers running Unix and X, you enable and disable
+access using the @code{xhost} command. To allow all hosts access to
+your X server, use
+
+@example
+xhost +
+@end example
+
+@noindent
+at the shell prompt, which (on an HP machine, at least) produces the
+following message:
+
+@example
+access control disabled, clients can connect from any host
+@end example
+
+To deny all hosts access to your X server (except those explicitly
+allowed by name), use
+
+@example
+xhost -
+@end example
+
+On the test HP computer, this command generated the following message:
+
+@example
+access control enabled, only authorized clients can connect
+@end example
+
+@end itemize
+
+@node Dired claims that no file is on this line, , Security risks with Emacs, Bugs and problems
+@section Dired says, @samp{no file on this line} when I try to do something.
+@cindex Dired does not see a file
+
+@c FIXME: I think this is fixed in Emacs 21, but I didn't have time to
+@c check.
+Chances are you're using a localized version of Unix that doesn't use US
+date format in dired listings. You can check this by looking at dired
+listings or by typing @kbd{ls -l} to a shell and looking at the dates that
+come out.
+
+Dired uses a regular expression to find the beginning of a file name.
+In a long Unix-style directory listing (@samp{ls -l}), the file name
+starts after the date. The regexp has thus been written to look for the
+date, the format of which can vary on non-US systems.
+
+There are two approaches to solving this. The first one involves
+setting things up so that @samp{ls -l} outputs US date format. This can
+be done by setting the locale. See your OS manual for more information.
+
+The second approach involves changing the regular expression used by
+dired, @code{directory-listing-before-filename-regexp}.
+
+@c ------------------------------------------------------------
+@node Compiling and installing Emacs, Finding Emacs and related packages, Bugs and problems, Top
+@chapter Compiling and installing Emacs
+@cindex Compiling and installing Emacs
+
+@menu
+* Installing Emacs::
+* Updating Emacs::
+* Problems building Emacs::
+* Linking with -lX11 fails::
+@end menu
+
+@node Installing Emacs, Updating Emacs, Compiling and installing Emacs, Compiling and installing Emacs
+@section How do I install Emacs?
+@cindex Installing Emacs
+@cindex Unix systems, installing Emacs on
+@cindex Downloading and installing Emacs
+@cindex Retrieving and installing Emacs
+@cindex Building Emacs from source
+@cindex Source code, building Emacs from
+@cindex Unpacking and installing Emacs
+
+This answer is meant for users of Unix and Unix-like systems. Users of
+other operating systems should see the series of questions beginning
+with @ref{Emacs for MS-DOS}, which describe where to get non-Unix source
+and binaries, and how to install Emacs on those systems.
+
+For Unix and Unix-like systems, the easiest way is often to compile it
+from scratch. You will need:
+
+@itemize @bullet
+
+@item
+Emacs sources. @xref{Current GNU distributions}, for a list of ftp sites
+that make them available. On @file{ftp.gnu.org}, the main GNU
+distribution site, sources are available as
+
+@uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-@value{VER}.tar.gz}
+
+The above will obviously change as new versions of Emacs come out. For
+instance, when Emacs 22.42 is released, it will most probably be
+available as
+
+@uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-22.42.tar.gz}
+
+Again, you should use one of the GNU mirror sites (see @ref{Current GNU
+distributions}, and adjust the URL accordingly) so as to reduce load on
+@file{ftp.gnu.org}.
+
+@item
+@code{gzip}, the GNU compression utility. You can get @code{gzip} via
+anonymous ftp at mirrors of @file{ftp.gnu.org} sites; it should compile
+and install without much trouble on most systems. Once you have
+retrieved the Emacs sources, you will probably be able to uncompress
+them with the command
+
+@example
+gunzip --verbose emacs-@value{VER}.tar.gz
+@end example
+
+@noindent
+changing the Emacs version (@value{VER}), as necessary. Once
+@code{gunzip} has finished doing its job, a file by the name of
+@file{emacs-@value{VER}.tar} should be in your build directory.
+
+@item
+@code{tar}, the @dfn{tape archiving} program, which moves multiple files
+into and out of archive files, or @dfn{tarfiles}. All of the files
+comprising the Emacs source come in a single tarfile, and must be
+extracted using @code{tar} before you can build Emacs. Typically, the
+extraction command would look like
+
+@example
+tar -xvvf emacs-@value{VER}.tar
+@end example
+
+@noindent
+The @samp{x} indicates that we want to extract files from this tarfile,
+the two @samp{v}s force verbose output, and the @samp{f} tells
+@code{tar} to use a disk file, rather than one on the tape drive.
+
+If you're using GNU @code{tar} (available at mirrors of
+@file{ftp.gnu.org}), you can combine this step and the previous one by
+using the command
+
+@example
+tar -zxvvf emacs-@value{VER}.tar.gz
+@end example
+
+@noindent
+The additional @samp{z} at the beginning of the options list tells GNU
+@code{tar} to uncompress the file with @code{gunzip} before extracting
+the tarfile's components.
+
+@end itemize
+
+At this point, the Emacs sources (all 70+ megabytes of them) should be
+sitting in a directory called @file{emacs-@value{VER}}. On most common
+Unix and Unix-like systems, you should be able to compile Emacs (with X
+Window system support) with the following commands:
+
+@example
+cd emacs-@value{VER} # change directory to emacs-@value{VER}
+./configure # configure Emacs for your particular system
+make # use Makefile to build components, then Emacs
+@end example
+
+If the @code{make} completes successfully, the odds are fairly good that
+the build has gone well. (@xref{Problems building Emacs}, if you weren't
+successful.)
+
+By default, Emacs is installed in the following directories:
+
+@table @file
+@item /usr/local/bin
+binaries.
+
+@item /usr/local/share/emacs/@value{VER}
+Lisp code and support files.
+
+@item /usr/local/info
+Info documentation.
+@end table
+
+To install files in those default directories, become the superuser and
+type
+
+@example
+make install
+@end example
+
+Note that @samp{make install} will overwrite @file{/usr/local/bin/emacs}
+and any Emacs Info files that might be in @file{/usr/local/info}.
+
+Much more verbose instructions (with many more hints and suggestions)
+come with the Emacs sources, in the file @file{INSTALL}.
+
+@node Updating Emacs, Problems building Emacs, Installing Emacs, Compiling and installing Emacs
+@section How do I update Emacs to the latest version?
+@cindex Updating Emacs
+
+@xref{Installing Emacs}, and follow the instructions there for
+installation.
+
+Most files are placed in version-specific directories. Emacs
+@value{VER}, for instance, places files in
+@file{/usr/local/share/emacs/@value{VER}}.
+
+Upgrading should overwrite only, @file{/usr/local/bin/emacs} (the Emacs
+binary) and documentation in @file{/usr/local/info}. Back up these
+files before you upgrade, and you shouldn't have too much trouble.
+
+@node Problems building Emacs, Linking with -lX11 fails, Updating Emacs, Compiling and installing Emacs
+@section What should I do if I have trouble building Emacs?
+@cindex Problems building Emacs
+@cindex Errors when building Emacs
+
+First look in the file @file{etc/PROBLEMS} (where you unpack the Emacs
+source) to see if there is already a solution for your problem. Next,
+look for other questions in this FAQ that have to do with Emacs
+installation and compilation problems.
+
+If you'd like to have someone look at your problem and help solve it,
+see @ref{Help installing Emacs}.
+
+If you cannot find a solution in the documentation, send a message to
+@email{bug-gnu-emacs@@gnu.org}.
+
+Please don't post it to @uref{news:gnu.emacs.help} or send e-mail to
+@email{help-gnu-emacs@@gnu.org}. For further guidelines, see
+@ref{Guidelines for newsgroup postings} and @ref{Reporting bugs}.
+
+@node Linking with -lX11 fails, , Problems building Emacs, Compiling and installing Emacs
+@section Why does linking Emacs with -lX11 fail?
+@cindex Linking with -lX11 fails
+@cindex lX11, linking fails with
+
+Emacs needs to be linked with the static version of the X11 library,
+@file{libX11.a}. This may be missing.
+
+On OpenWindows, you may need to use @code{add_services} to add the
+``OpenWindows Programmers'' optional software category from the CD-ROM.
+
+On HP-UX 8.0, you may need to run @code{update} again to load the
+X11-PRG ``fileset.'' This may be missing even if you specified ``all
+filesets'' the first time. If @file{libcurses.a} is missing, you may
+need to load the ``Berkeley Development Option.''
+
+@email{zoo@@armadillo.com, David Zuhn} says that MIT X builds shared
+libraries by default, and only shared libraries, on those platforms that
+support them. These shared libraries can't be used when undumping
+@code{temacs} (the last stage of the Emacs build process). To get
+regular libraries in addition to shared libraries, add this to
+@file{site.cf}:
+
+@example
+#define ForceNormalLib YES
+@end example
+
+Other systems may have similar problems. You can always define
+@code{CANNOT_DUMP} and link with the shared libraries instead.
+
+@cindex X Menus don't work
+To get the Xmenu stuff to work, you need to find a copy of MIT's
+@file{liboldX.a}.
+
+@c ------------------------------------------------------------
+@node Finding Emacs and related packages, Major packages and programs, Compiling and installing Emacs, Top
+@chapter Finding Emacs and related packages
+@cindex Finding Emacs and related packages
+
+@menu
+* Finding Emacs on the Internet::
+* Finding a package with particular functionality::
+* Packages that do not come with Emacs::
+* Current GNU distributions::
+* Difference between Emacs and XEmacs::
+* Emacs for MS-DOS::
+* Emacs for Windows::
+* Emacs for OS/2::
+* Emacs for Atari ST::
+* Emacs for the Amiga ::
+* Emacs for NeXTSTEP::
+* Emacs for Apple computers::
+* Emacs for VMS and DECwindows::
+* Modes for various languages::
+@end menu
+
+@node Finding Emacs on the Internet, Finding a package with particular functionality, Finding Emacs and related packages, Finding Emacs and related packages
+@section Where can I get Emacs on the net (or by snail mail)?
+@cindex Finding Emacs on the Internet
+@cindex Snail mail, ordering Emacs via
+@cindex Postal service, ordering Emacs via
+@cindex Distribution, retrieving Emacs
+@cindex Internet, retrieving from
+
+Look in the files @file{etc/DISTRIB} and @file{etc/FTP} for
+information on nearby archive sites. If you don't already have Emacs,
+see @ref{Informational files for Emacs}, for how to get these files.
+
+@xref{Installing Emacs}, for information on how to obtain and build the latest
+version of Emacs, and see @ref{Current GNU distributions}, for a list of
+archive sites that make GNU software available.
+
+@node Finding a package with particular functionality, Packages that do not come with Emacs, Finding Emacs on the Internet, Finding Emacs and related packages
+@section How do I find a Emacs Lisp package that does XXX?
+@cindex Package, finding
+@cindex Finding an Emacs Lisp package
+@cindex Functionality, finding a particular package
+
+First of all, you should check to make sure that the package isn't
+already available. For example, typing @kbd{M-x apropos @key{RET}
+wordstar @key{RET}} lists all functions and variables containing the
+string @samp{wordstar}.
+
+It is also possible that the package is on your system, but has not been
+loaded. To see which packages are available for loading, look through
+your computer's lisp directory (@pxref{File-name conventions}). The Lisp
+source to most packages contains a short description of how they
+should be loaded, invoked, and configured---so before you use or
+modify a Lisp package, see if the author has provided any hints in the
+source code.
+
+The command @kbd{C-h p} (@code{finder-by-keyword}) allows you to browse
+the constituent Emacs packages.
+
+For advice on how to find extra packages that are not part of Emacs,
+see @ref{Packages that do not come with Emacs}.
+
+@node Packages that do not come with Emacs, Current GNU distributions, Finding a package with particular functionality, Finding Emacs and related packages
+@section Where can I get Emacs Lisp packages that don't come with Emacs?
+@cindex Unbundled packages
+@cindex Finding other packages
+@cindex Lisp packages that do not come with Emacs
+@cindex Packages, those that do not come with Emacs
+@cindex Emacs Lisp List
+@cindex Emacs Lisp Archive
+
+@uref{http://www.anc.ed.ac.uk/~stephen/emacs/ell.html, The Emacs Lisp
+List (ELL)}, maintained by @email{stephen@@anc.ed.ac.uk, Stephen Eglen},
+aims to provide one compact list with links to all of the current Emacs
+Lisp files on the Internet. The ELL can be browsed over the web, or
+from Emacs with @uref{http://www.anc.ed.ac.uk/~stephen/emacs/ell.el,
+the @file{ell} package}.
+
+Many authors post their packages to the @uref{news:gnu.emacs.sources,
+Emacs sources newsgroup}. You can search the archives of this
+group with @uref{http://groups.google.com/group/gnu.emacs.sources, Google},
+or @uref{http://dir.gmane.org/gmane.emacs.sources, Gmane}, for example.
+
+Several packages are stored in
+@uref{http://emacswiki.org/elisp/, the Lisp area of the Emacs Wiki}.
+
+For a long time, the Emacs Lisp Archive provided a central repository
+for Emacs packages. Sadly, it has not been active for some time,
+although you can still access the old files at
+
+@uref{http://www.club.cc.cmu.edu/pub/gnu/elisp-archive/}
+
+Read the file @file{etc/MORE.STUFF} for more information about
+external packages.
+
+@node Current GNU distributions, Difference between Emacs and XEmacs, Packages that do not come with Emacs, Finding Emacs and related packages
+@section Where can I get other up-to-date GNU stuff?
+@cindex Current GNU distributions
+@cindex Sources for current GNU distributions
+@cindex Stuff, current GNU
+@cindex Up-to-date GNU stuff
+@cindex Finding current GNU software
+@cindex Official GNU software sites
+
+The most up-to-date official GNU software is normally kept at
+
+@uref{ftp://ftp.gnu.org/pub/gnu}
+
+Read the files @file{etc/DISTRIB} and @file{etc/FTP} for more
+information.
+
+A list of sites mirroring @samp{ftp.gnu.org} can be found at
+
+@uref{http://www.gnu.org/order/ftp.html}
+
+@node Difference between Emacs and XEmacs, Emacs for MS-DOS, Current GNU distributions, Finding Emacs and related packages
+@section What is the difference between Emacs and XEmacs (formerly Lucid Emacs)?
+@cindex XEmacs
+@cindex Difference Emacs and XEmacs
+@cindex Lucid Emacs
+@cindex Epoch
+
+XEmacs is a branch version of Emacs. It was first called Lucid Emacs,
+and was initially derived from a prerelease version of Emacs 19. In
+this FAQ, we use the name ``Emacs'' only for the official version.
+
+Emacs and XEmacs each come with Lisp packages that are lacking in the
+other. The two versions have some significant differences at the Lisp
+programming level. Their current features are roughly comparable,
+though the support for some operating systems, character sets and
+specific packages might be quite different.
+
+Some XEmacs code has been contributed to Emacs, and we would like to
+use other parts, but the earlier XEmacs maintainers did not always
+keep track of the authors of contributed code, which makes it
+impossible for the FSF to get copyright papers signed for that code.
+(The FSF requires these papers for all the code included in the Emacs
+release, aside from generic C support packages that retain their
+separate identity and are not integrated into the code of Emacs
+proper.)
+
+If you want to talk about these two versions and distinguish them,
+please call them ``Emacs'' and ``XEmacs.'' To contrast ``XEmacs''
+with ``GNU Emacs'' would be misleading, since XEmacs too has its
+origin in the work of the GNU Project. Terms such as ``Emacsen'' and
+``(X)Emacs'' are not wrong, but they are not very clear, so it
+is better to write ``Emacs and XEmacs.''
+
+@node Emacs for MS-DOS, Emacs for Windows, Difference between Emacs and XEmacs, Finding Emacs and related packages
+@section Where can I get Emacs for my PC running MS-DOS?
+@cindex MS-DOS, Emacs for
+@cindex DOS, Emacs for
+@cindex Compiling Emacs for DOS
+@cindex Emacs for MS-DOS
+@cindex Tools needed to compile Emacs under DOS
+
+A pre-built binary distribution of Emacs is available from the
+SimTel.NET archives. This version apparently works under MS-DOS and
+Windows (3.X, 9X, ME, NT, and 2000) and supports long file names under
+Windows 9X, Windows ME, and Windows 2000. More information is available
+from
+
+@uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/emacs.README}
+
+The binary itself is available in the files @file{em*.zip} in the
+directory
+
+@uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/}
+
+If you prefer to compile Emacs for yourself, you can do so with the
+current distribution directly. You will need a 386 (or
+better) processor, and to be running MS-DOS 3.0 or later. According to
+@email{eliz@@gnu.org, Eli Zaretskii} and
+@email{hankedr@@dms.auburn.edu, Darrel Hankerson}, you will need the
+following:
+
+@table @emph
+
+@item Compiler
+DJGPP version 1.12 maint 1 or later. Djgpp 2.0 or later is
+recommended, since 1.x is very old an unmaintained. Djgpp 2 supports
+long file names on Windows 9X/ME/2K.
+
+You can get the latest release of DJGPP by retrieving all of
+the files in
+
+@uref{ftp://ftp.delorie.com/pub/djgpp/current/v2*}
+
+@item Unpacking program
+The easiest way is to use @code{djtar} which comes with DJGPP v2.x,
+because it can open gzip'ed tarfiles (i.e., those ending with
+@file{.tar.gz}) in one step. @code{Djtar} comes in
+@file{djdev@var{nnn}.zip} archive (where @var{nnn} is the DJGPP version
+number), from the URL mentioned above.
+
+@strong{Warning!} Do @strong{not} use the popular WinZip program to
+unpack the Emacs distribution! WinZip is known to corrupt some of the
+files by converting them to the DOS CR-LF format, it doesn't always
+preserve the directory structure recorded in the compressed Emacs
+archive, and commits other atrocities. Some of these problems could
+actually prevent Emacs from building successfully!
+
+@item make, mv, sed, and rm
+All of these utilities are available at
+
+@uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu}
+
+16-bit utilities can be found in GNUish, at
+
+@uref{http://www.simtel.net/pub/gnuish/}
+
+@noindent
+(@code{mv} and @code{rm} are in the Fileutils package, @code{sed} and
+@code{make} are each one in a separate package named after them.)
+
+@end table
+
+The files @file{INSTALL} (near its end) and @file{etc/PROBLEMS} in the
+directory of the Emacs sources contains some additional information
+regarding Emacs under MS-DOS.
+
+For a list of other MS-DOS implementations of Emacs (and Emacs
+look-alikes), consult the list of ``Emacs implementations and literature,''
+available at
+
+@uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/}
+
+Note that while many of these programs look similar to Emacs, they often
+lack certain features, such as the Emacs Lisp extension language.
+
+@node Emacs for Windows, Emacs for OS/2, Emacs for MS-DOS, Finding Emacs and related packages
+@section Where can I get Emacs for Microsoft Windows?
+@cindex FAQ for NT Emacs
+@cindex Emacs for MS-Windows
+@cindex Microsoft Windows, Emacs for
+@cindex Windows 9X, ME, NT, 2K, and CE, Emacs for
+
+For information on Emacs for Windows 95 and NT, read the FAQ produced by
+@email{voelker@@cs.washington.edu, Geoff Voelker} and currently maintained
+by @email{ramprasad@@gnu.org, Ramprasad B}, available at
+
+@uref{http://www.gnu.org/software/emacs/windows/ntemacs.html}
+
+@xref{Emacs for MS-DOS}, for Windows 3.1.
+
+A port of Emacs 20.7 for Windows CE, based on NTEmacs, is available at
+
+@uref{http://www.rainer-keuchel.de/software.html}
+
+@noindent
+This port was done by @email{coyxc@@rainer-keuchel.de, Rainer Keuchel},
+and supports all Emacs features except async subprocesses and menus.
+You will need MSVC 6.0 and a Windows CE SDK to build this port.
+
+@node Emacs for OS/2, Emacs for Atari ST, Emacs for Windows, Finding Emacs and related packages
+@section Where can I get Emacs for my PC running OS/2?
+@cindex OS/2, Emacs for
+
+Emacs 20.6 is ported for emx on OS/2 2.0 or 2.1, and is available at
+
+@uref{ftp://hobbes.nmsu.edu/pub/os2/apps/editors/emacs/}
+
+@noindent
+and also at
+
+@uref{http://www.dotemacs.de/os2/emacs.html}
+
+Instructions for installation, basic setup, and other useful information
+for OS/2 users of Emacs can be found at
+
+@uref{http://home.snafu.de/ohei/emacs/emacs206-os2.html}
+
+@node Emacs for Atari ST, Emacs for the Amiga , Emacs for OS/2, Finding Emacs and related packages
+@section Where can I get Emacs for my Atari ST?
+@cindex Atari ST, Emacs for
+@cindex TOS, Emacs for
+
+Roland Sch@"auble reports that Emacs 18.58 running on plain TOS and MiNT
+is available at
+@uref{ftp://atari.archive.umich.edu/Editors/Emacs-18-58/1858b-d3.zoo}.
+
+@node Emacs for the Amiga , Emacs for NeXTSTEP, Emacs for Atari ST, Finding Emacs and related packages
+@section Where can I get Emacs for my Amiga?
+@cindex Amiga, Emacs for
+
+The files you need are available at
+
+@uref{ftp://ftp.wustl.edu/pub/aminet/util/gnu/}
+
+@email{dgilbert@@gamiga.guelphnet.dweomer.org, David Gilbert} has released a
+beta version of Emacs 19.25 for the Amiga. You can get the binary at
+
+@uref{ftp://ftp.wustl.edu/pub/aminet/util/gnu/a2.0bEmacs-bin.lha}
+
+@node Emacs for NeXTSTEP, Emacs for Apple computers, Emacs for the Amiga , Finding Emacs and related packages
+@section Where can I get Emacs for NeXTSTEP?
+@cindex NeXTSTEP, Emacs for
+
+Emacs.app is a NeXTSTEP version of Emacs 19.34 which supports colors,
+menus, and multiple frames. You can get it from
+
+@uref{ftp://next-ftp.peak.org/pub/next-ftp/next/apps/emacs/Emacs_for_NeXTstep.4.20a1.NIHS.b.tar.gz}
+
+@node Emacs for Apple computers, Emacs for VMS and DECwindows, Emacs for NeXTSTEP, Finding Emacs and related packages
+@section Where can I get Emacs for my Apple computer?
+@cindex Apple computers, Emacs for
+@cindex Macintosh, Emacs for
+
+Beginning with version 21.1, the Macintosh is supported in the official
+Emacs distribution; see the files @file{mac/README} and
+@file{mac/INSTALL} in the Emacs distribution for build instructions.
+
+Beginning with version 22.1, Emacs supports Mac OS X natively.
+
+@node Emacs for VMS and DECwindows, Modes for various languages, Emacs for Apple computers, Finding Emacs and related packages
+@section Where do I get Emacs that runs on VMS under DECwindows?
+@cindex DECwindows, Emacs for
+@cindex VMS, Emacs for
+
+Up-to-date information about GNU software (including Emacs) for VMS is
+available at @uref{http://www.lp.se/gnu-vms/}.
+
+@node Modes for various languages, , Emacs for VMS and DECwindows, Finding Emacs and related packages
+@section Where can I get modes for Lex, Yacc/Bison, Bourne shell, csh, C@t{++}, Objective-C, Pascal, Java, and Awk?
+@cindex Awk, mode for
+@cindex @code{awk-mode}
+@cindex Bison, mode for
+@cindex Bourne Shell, mode for
+@cindex C@t{++}, mode for
+@cindex Java, mode for
+@cindex Lex mode
+@cindex Objective-C, mode for
+@cindex @code{pascal-mode}
+@cindex Shell mode
+@cindex Yacc mode
+@cindex @file{csh} mode
+@cindex @code{sh-mode}
+@cindex @code{cc-mode}
+
+Most of these modes are now available in standard Emacs distribution.
+To get additional modes, see @ref{Finding a package with particular
+functionality}.
+
+Barry Warsaw's @code{cc-mode} now works for C, C@t{++}, Objective-C, and
+Java code. It is distributed with Emacs, but has
+@uref{http://cc-mode.sourceforge.net/, its own homepage}.
+
+@c ------------------------------------------------------------
+@node Major packages and programs, Key bindings, Finding Emacs and related packages, Top
+@chapter Major packages and programs
+@cindex Major packages and programs
+
+@menu
+* VM::
+* Supercite::
+* Calc::
+* VIPER::
+* AUCTeX::
+* BBDB::
+* Ispell::
+* Emacs/W3::
+* EDB::
+* Mailcrypt::
+* JDE::
+* Patch::
+@end menu
+
+@node VM, Supercite, Major packages and programs, Major packages and programs
+@section VM (View Mail) --- another mail reader within Emacs, with MIME support
+@cindex VM
+@cindex Alternative mail software
+@cindex View Mail
+@cindex E-mail reader, VM
+
+@table @b
+
+@item Author
+@email{kyle_jones@@wonderworks.com, Kyle Jones}
+
+@item Latest version
+7.19
+
+@item Distribution
+@uref{ftp://ftp.wonderworks.com/pub/vm/vm.tar.gz}
+
+@item Informational newsgroup
+@uref{news:gnu.emacs.vm.info}@*
+
+@item Bug reports newsgroup
+@uref{news:gnu.emacs.vm.bug}@*
+Or send reports to @email{bug-vm@@wonderworks.com}
+@end table
+
+VM 7 works well with Emacs 21 and Emacs 22. Older versions of VM
+suitable for use with older versions of Emacs are available from
+@uref{ftp://ftp.wonderworks.com/pub/vm/, the same FTP site}.
+
+
+@node Supercite, Calc, VM, Major packages and programs
+@section Supercite --- mail and news citation package within Emacs
+@cindex Supercite
+@cindex Superyank
+@cindex Mail and news citations
+@cindex News and mail citations
+@cindex Citations in mail and news
+
+@table @b
+
+@item Author
+@email{barry@@python.org, Barry Warsaw}
+
+@item Latest version
+3.54 (comes bundled with Emacs since version 20)
+
+@item Distribution
+@uref{http://www.python.org/emacs/supercite.tar.gz}
+
+@item Mailing list
+Subscription requests to @email{supercite-request@@python.org}@*
+Submissions @email{supercite@@python.org}
+
+@end table
+
+Superyank is an old version of Supercite.
+
+@node Calc, VIPER, Supercite, Major packages and programs
+@section Calc --- poor man's Mathematica within Emacs
+@cindex Programmable calculator
+@cindex Calc
+@cindex Mathematical package
+
+@table @b
+
+@item Author
+@email{daveg@@csvax.cs.caltech.edu, Dave Gillespie}
+
+@item Latest version
+2.1 (part of Emacs since version 22.1)
+
+@item Distribution
+No separate distribution outside of Emacs. Older versions
+are available at @uref{ftp://ftp.gnu.org/pub/gnu/calc/}.
+
+@end table
+
+Note that Calc 2.02f needs patching to work with Emacs 21 and later.
+
+@cindex @code{calculator}, a package
+Emacs 21.1 and later comes with a package called @file{calculator.el}.
+It doesn't support all the mathematical wizardry offered by Calc, such
+as matrices, special functions, and statistics, but is more than
+adequate as a replacement for @code{xcalc} and similar programs.
+
+@node VIPER, AUCTeX, Calc, Major packages and programs
+@section VIPER --- @code{vi} emulation for Emacs
+@cindex @code{vi} emulation
+@cindex VIPER
+@cindex Emulation of @code{vi}
+
+Since Emacs 19.29, the preferred @code{vi} emulation in Emacs is VIPER
+(@kbd{M-x viper-mode @key{RET}}), which comes with Emacs. It extends
+and supersedes VIP (including VIP 4.3) and provides @code{vi} emulation
+at several levels, from one that closely follows @code{vi} to one that
+departs from @code{vi} in several significant ways.
+
+For Emacs 19.28 and earlier, the following version of VIP is generally
+better than the one distributed with Emacs:
+
+@table @b
+@item Author
+@email{sane@@cs.uiuc.edu, Aamod Sane}
+
+@item Latest version
+4.3
+
+@item Distribution
+@uref{ftp://www.club.cc.cmu.edu/pub/gnu/elisp-archive/modes/vip-mode.tar.Z}
+
+@end table
+
+@node AUCTeX, BBDB, VIPER, Major packages and programs
+@section AUC@TeX{} --- enhanced @TeX{} modes with debugging facilities
+@cindex Mode for @TeX{}
+@cindex @TeX{} mode
+@cindex AUC@TeX{} mode for editing @TeX{}
+@cindex Writing and debugging @TeX{}
+
+AUC@TeX{} is a set of sophisticated major modes for @TeX{}, LaTeX,
+ConTeXt, and Texinfo offering context-sensitive syntax highlighting,
+indentation, formatting and folding, macro completion, @TeX{} shell
+functionality, and debugging. Be also sure to check out
+@ref{Introduction, RefTeX, Introduction, reftex, Ref@TeX{} User Manual}.
+Current versions of AUC@TeX{} include the
+@uref{http://www.gnu.org/software/auctex/preview-latex,preview-latex}
+package for WYSIWYG previews of various LaTeX constructs in the Emacs
+source buffer.
+
+@table @b
+
+@item Authors
+@email{krab@@iesd.auc.dk, Kresten Krab Thorup}, @*
+@email{abraham@@dina.kvl.dk, Per Abrahamsen}, @* and others.
+
+@item Maintainer
+@email{dak@@gnu.org, David Kastrup}
+
+@item Latest version
+11.84
+
+@item Distribution
+@uref{ftp://ftp.gnu.org/pub/gnu/auctex/}
+
+@item Web site
+@uref{http://www.gnu.org/software/auctex/}
+
+@item Mailing list:
+Subscription requests to @email{auctex-request@@gnu.org}@*
+Submissions to @email{auctex@@gnu.org}
+
+@end table
+
+@node BBDB, Ispell, AUCTeX, Major packages and programs
+@section BBDB --- personal Info Rolodex integrated with mail/news readers
+@cindex BBDB
+@cindex Rolodex-like functionality
+@cindex Integrated contact database
+@cindex Contact database
+@cindex Big Brother Database
+@cindex Address book
+
+@table @b
+
+@item Maintainer
+@email{waider@@waider.ie, Ronan Waide}
+
+@item Latest version
+2.34
+
+@item Distribution
+@uref{http://bbdb.sourceforge.net/}
+
+@item Mailing lists
+Subscription requests to @email{bbdb-info-request@@lists.sourceforge.net}@*
+Submissions to @email{bbdb-info@@lists.sourceforge.net}@*
+Release announcements: @email{bbdb-announce-request@@lists.sourceforge.net}
+
+@end table
+
+@node Ispell, Emacs/W3, BBDB, Major packages and programs
+@section Ispell --- spell checker in C with interface for Emacs
+@cindex Spell-checker
+@cindex Checking spelling
+@cindex Ispell
+
+@table @b
+
+@item Author
+@email{geoff@@cs.hmc.edu, Geoff Kuenning}
+
+@item Latest version
+3.3.02
+
+@item Distribution
+@uref{http://fmg-www.cs.ucla.edu/geoff/tars/ispell-3.3.02.tar.gz}@*
+
+@item Web site
+@uref{http://fmg-www.cs.ucla.edu/geoff/ispell.html}
+
+@end table
+
+This Ispell program is distinct from GNU Ispell 4.0. GNU Ispell 4.0 is
+no longer a supported product.
+
+@node Emacs/W3, EDB, Ispell, Major packages and programs
+@section Emacs/W3 --- A World Wide Web browser inside of Emacs
+@cindex WWW browser
+@cindex Web browser
+@cindex HTML browser in Emacs
+@cindex @code{w3-mode}
+
+@table @b
+
+@item Author
+@email{wmperry@@gnu.org, Bill Perry}
+
+@item Maintainer
+Emacs/W3 needs a maintainer. It has lain dormant for several years. If
+you would like to take over the project, please contact
+@email{maintainers@@gnu.org}.
+
+@item Latest version
+4.0pre.47
+
+@item Distribution
+@uref{http://savannah.gnu.org/projects/w3}
+
+@item Mailing lists
+Receive announcements from @email{w3-announce@@gnu.org}@*
+Help to develop Emacs/W3 at @email{w3-dev@@gnu.org}
+
+@end table
+
+@node EDB, Mailcrypt, Emacs/W3, Major packages and programs
+@section EDB --- Database program for Emacs; replaces forms editing modes
+@cindex EDB
+@cindex Database
+@cindex Forms mode
+
+@table @b
+@item Author
+@email{mernst@@theory.lcs.mit.edu, Michael Ernst}
+
+@item Latest version
+1.21
+
+@item Distribution
+@uref{ftp://theory.lcs.mit.edu/pub/emacs/edb}
+
+@end table
+
+@node Mailcrypt, JDE, EDB, Major packages and programs
+@section Mailcrypt --- PGP interface within Emacs mail and news
+@cindex PGP
+@cindex GPG
+@cindex Interface to PGP from Emacs mail and news
+@cindex News, interface to PGP from
+@cindex Mail, interface to PGP from
+@cindex Encryption software, interface to
+
+@table @b
+
+@item Authors
+@email{patl@@lcs.mit.edu, Patrick J. LoPresti} and
+@email{jin@@atype.com, Jin S. Choi}
+
+@item Maintainer
+@email{warner-mailcrypt@@lothar.com, Brian Warner}
+
+@item Latest version
+3.5.8
+
+@item Distribution
+@uref{http://dl.sourceforge.net/sourceforge/mailcrypt/mailcrypt-3.5.8.tar.gz}
+
+@item Web site
+@uref{http://mailcrypt.sourceforge.net/}
+
+@end table
+
+Note that a new package called PGG is bundled with Emacs starting with
+version 22.1. It is a modern interface to various PGP implementations,
+including @uref{http://www.gnupg.org/, The GNU Privacy Guard} and
+supports symmetric encryption.
+
+@node JDE, Patch, Mailcrypt, Major packages and programs
+@section JDE --- Integrated development environment for Java
+@cindex Java development environment
+@cindex Integrated Java development environment
+@cindex JDE
+
+@table @b
+
+@item Author
+@email{paulk@@mathworks.com, Paul Kinnucan}
+
+@item Latest version
+2.3.5
+
+@item Web site
+@uref{http://jdee.sunsite.dk/}
+
+@item Mailing lists
+Subscription requests to @email{jde-subscribe@@sunsite.dk}@*
+Receive announcements from @email{jde-announce-subscribe@@sunsite.dk}
+
+@end table
+
+@node Patch, , JDE, Major packages and programs
+@section Patch --- program to apply ``diffs'' for updating files
+@cindex Updating files with diffs
+@cindex Patching source files with diffs
+@cindex Diffs and patching
+@cindex @file{patch}
+
+@table @b
+
+@item Author
+@email{lwall@@wall.org, Larry Wall} (with GNU modifications)
+
+@item Latest version
+2.5.4
+
+@item Distribution
+@xref{Current GNU distributions}.
+
+@end table
+
+@c ------------------------------------------------------------
+@node Key bindings, Alternate character sets, Major packages and programs, Top
+@chapter Key bindings
+@cindex Key bindings
+
+@menu
+* Binding keys to commands::
+* Invalid prefix characters::
+* Terminal setup code works after Emacs has begun::
+* Using function keys under X::
+* Working with function and arrow keys::
+* X key translations for Emacs::
+* Handling C-s and C-q with flow control::
+* Binding C-s and C-q::
+* Backspace invokes help::
+* stty and Backspace key::
+* Swapping keys::
+* Producing C-XXX with the keyboard::
+* No Meta key::
+* No Escape key::
+* Compose Character::
+* Binding combinations of modifiers and function keys::
+* Meta key does not work in xterm::
+* ExtendChar key does not work as Meta::
+* SPC no longer completes file names::
+@end menu
+
+@node Binding keys to commands, Invalid prefix characters, Key bindings, Key bindings
+@section How do I bind keys (including function keys) to commands?
+@cindex Binding keys to commands
+@cindex Keys, binding to commands
+@cindex Commands, binding keys to
+
+Keys can be bound to commands either interactively or in your
+@file{.emacs} file. To interactively bind keys for all modes, type
+@kbd{M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
+
+To bind a key just in the current major mode, type @kbd{M-x
+local-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
+
+@inforef{Key Bindings, Key Bindings, emacs}, for further details.
+
+To make the process of binding keys interactively easier, use the
+following ``trick'': First bind the key interactively, then immediately
+type @kbd{C-x @key{ESC} @key{ESC} C-a C-k C-g}. Now, the command needed
+to bind the key is in the kill ring, and can be yanked into your
+@file{.emacs} file. If the key binding is global, no changes to the
+command are required. For example,
+
+@lisp
+(global-set-key (quote [f1]) (quote help-for-help))
+@end lisp
+
+@noindent
+can be placed directly into the @file{.emacs} file. If the key binding is
+local, the command is used in conjunction with the @samp{add-hook} function.
+For example, in TeX mode, a local binding might be
+
+@lisp
+(add-hook 'tex-mode-hook
+ (lambda ()
+ (local-set-key (quote [f1]) (quote help-for-help))))
+@end lisp
+
+
+@itemize @bullet
+
+@item
+Control characters in key sequences, in the form yanked from the kill
+ring are given in their graphic form---i.e., @key{CTRL} is shown as
+@samp{^}, @key{TAB} as a set of spaces (usually 8), etc. You may want
+to convert these into their vector or string forms.
+
+@item
+If a prefix key of the character sequence to be bound is already
+bound as a complete key, then you must unbind it before the new
+binding. For example, if @kbd{ESC @{} is previously bound:
+
+@lisp
+(global-unset-key [?\e ?@{]) ;; or
+(local-unset-key [?\e ?@{])
+@end lisp
+
+@item
+Aside from commands and ``lambda lists,'' a vector or string also
+can be bound to a key and thus treated as a macro. For example:
+
+@lisp
+(global-set-key [f10] [?\C-x?\e?\e?\C-a?\C-k?\C-g]) ;; or
+(global-set-key [f10] "\C-x\e\e\C-a\C-k\C-g")
+@end lisp
+
+@end itemize
+
+@node Invalid prefix characters, Terminal setup code works after Emacs has begun, Binding keys to commands, Key bindings
+@section Why does Emacs say @samp{Key sequence XXX uses invalid prefix characters}?
+@cindex Prefix characters, invalid
+@cindex Invalid prefix characters
+@cindex Misspecified key sequences
+
+Usually, one of two things has happened. In one case, the control
+character in the key sequence has been misspecified (e.g. @samp{C-f}
+used instead of @samp{\C-f} within a Lisp expression). In the other
+case, a @dfn{prefix key} in the keystroke sequence you were trying to bind
+was already bound as a @dfn{complete key}. Historically, the @samp{ESC [}
+prefix was usually the problem, in which case you should evaluate either
+of these forms before attempting to bind the key sequence:
+
+@lisp
+(global-unset-key [?\e ?[]) ;; or
+(global-unset-key "\e[")
+@end lisp
+
+@node Terminal setup code works after Emacs has begun, Using function keys under X, Invalid prefix characters, Key bindings
+@section Why doesn't this [terminal or window-system setup] code work in my @file{.emacs} file, but it works just fine after Emacs starts up?
+@cindex Terminal setup code in @file{.emacs}
+
+During startup, Emacs initializes itself according to a given code/file
+order. If some of the code executed in your @file{.emacs} file needs to
+be postponed until the initial terminal or window-system setup code has
+been executed but is not, then you will experience this problem (this
+code/file execution order is not enforced after startup).
+
+To postpone the execution of Emacs Lisp code until after terminal or
+window-system setup, treat the code as a @dfn{lambda list} and set the
+value of either the @code{term-setup-hook} or @code{window-setup-hook}
+variable to this lambda function. For example,
+
+@lisp
+(add-hook 'term-setup-hook
+ (lambda ()
+ (when (string-match "\\`vt220" (or (getenv "TERM") ""))
+ ;; Make vt220's "Do" key behave like M-x:
+ (global-set-key [do] 'execute-extended-command))))
+@end lisp
+
+For information on what Emacs does every time it is started, see the
+@file{lisp/startup.el} file.
+
+@node Using function keys under X, Working with function and arrow keys, Terminal setup code works after Emacs has begun, Key bindings
+@section How do I use function keys under X?
+@cindex Function keys
+@cindex X Window System and function keys
+@cindex Binding function keys
+
+With Emacs 19, functions keys under X are bound like any other key. @xref{Binding keys to commands}, for details.
+
+@node Working with function and arrow keys, X key translations for Emacs, Using function keys under X, Key bindings
+@section How do I tell what characters or symbols my function or arrow keys emit?
+@cindex Working with arrow keys
+@cindex Arrow keys, symbols generated by
+@cindex Working with function keys
+@cindex Function keys, symbols generated by
+@cindex Symbols generated by function keys
+
+Type @kbd{C-h c} then the function or arrow keys. The command will
+return either a function key symbol or character sequence (see the
+Emacs on-line documentation for an explanation). This works for other
+keys as well.
+
+@node X key translations for Emacs, Handling C-s and C-q with flow control, Working with function and arrow keys, Key bindings
+@section How do I set the X key ``translations'' for Emacs?
+@cindex X key translations
+@cindex Key translations under X
+@cindex Translations for keys under X
+
+Emacs is not written using the Xt library by default, so there are no
+``translations'' to be set. (We aren't sure how to set such translations
+if you do build Emacs with Xt; please let us know if you've done this!)
+
+The only way to affect the behavior of keys within Emacs is through
+@code{xmodmap} (outside Emacs) or @code{define-key} (inside Emacs). The
+@code{define-key} command should be used in conjunction with the
+@code{function-key-map} map. For instance,
+
+@lisp
+(define-key function-key-map [M-@key{TAB}] [?\M-\t])
+@end lisp
+
+@noindent
+defines the @kbd{M-@key{TAB}} key sequence.
+
+@node Handling C-s and C-q with flow control, Binding C-s and C-q, X key translations for Emacs, Key bindings
+@section How do I handle @kbd{C-s} and @kbd{C-q} being used for flow control?
+@cindex Flow control, @kbd{C-s} and @kbd{C-q} with
+@cindex @kbd{C-s} and @kbd{C-q} with flow control
+
+@kbd{C-s} and @kbd{C-q} are used in the XON/XOFF flow control protocol.
+This messes things up when you're using Emacs over a serial line,
+because Emacs binds these keys to commands by default. Because Emacs
+won't honor them as flow control characters, too many of these
+characters are not passed on and overwhelm output buffers. Sometimes,
+intermediate software using XON/XOFF flow control will prevent Emacs
+from ever seeing @kbd{C-s} and @kbd{C-q}.
+
+Possible solutions:
+
+@itemize @bullet
+
+@item
+Disable the use of @kbd{C-s} and @kbd{C-q} for flow control.
+
+You need to determine the cause of the flow control.
+
+@itemize @minus
+
+@item
+your terminal
+
+Your terminal may use XON/XOFF flow control to have time to display
+all the characters it receives. For example, VT series terminals do
+this. It may be possible to turn this off from a setup menu. For
+example, on a VT220 you may select ``No XOFF'' in the setup menu. This
+is also true for some terminal emulation programs on PCs.
+
+When you turn off flow control at the terminal, you will also need to
+turn it off at the other end, which might be at the computer you are
+logged in to or at some terminal server in between.
+
+If you turn off flow control, characters may be lost; using a printer
+connected to the terminal may fail. You may be able to get around
+this problem by modifying the @samp{termcap} entry for your terminal to
+include extra NUL padding characters.
+
+@item
+a modem
+
+If you are using a dialup connection, the modems may be using
+XON/XOFF flow control. It's not clear how to get around this.
+
+@item
+a router or terminal server
+
+Some network box between the terminal and your computer may be using
+XON/XOFF flow control. It may be possible to make it use some other
+kind of flow control. You will probably have to ask your local
+network experts for help with this.
+
+@item
+@code{tty} and/or @code{pty} devices
+
+If your connection to Emacs goes through multiple @code{tty} and/or
+@code{pty} devices, they may be using XON/XOFF flow control even when it
+is not necessary.
+
+@email{eirik@@theory.tn.cornell.edu, Eirik Fuller} writes:
+
+@quotation
+Some versions of @code{rlogin} (and possibly @code{telnet}) do not pass
+flow control characters to the remote system to which they connect. On
+such systems, Emacs on the remote system cannot disable flow control on
+the local system. Sometimes @samp{rlogin -8} will avoid this problem.
+
+One way to cure this is to disable flow control on the local host (the
+one running @code{rlogin}, not the one running @code{rlogind}) using the
+@code{stty} command, before starting the @code{rlogin} process. On many
+systems, @samp{stty start u stop u} will do this.
+
+Some versions of @samp{tcsh} will prevent even this from working. One
+way around this is to start another shell before starting rlogin,
+and issue the @samp{stty} command to disable flow control from that shell.
+@end quotation
+
+Use @samp{stty -ixon} instead of @samp{stty start u stop u} on some systems.
+
+@end itemize
+
+@item
+Make Emacs speak the XON/XOFF flow control protocol.
+
+You can make Emacs treat @kbd{C-s} and @kbd{C-q} as flow control characters by
+evaluating the form
+
+@lisp
+(enable-flow-control)
+@end lisp
+
+@noindent
+to unconditionally enable flow control or
+
+@lisp
+(enable-flow-control-on "vt100" "h19")
+@end lisp
+
+@noindent
+(using your terminal names instead of @samp{vt100} or @samp{h19}) to
+enable selectively. These commands will automatically swap @kbd{C-s}
+and @kbd{C-q} to @kbd{C-\} and @kbd{C-^}. Variables can be used to
+change the default swap keys (@code{flow-control-c-s-replacement} and
+@code{flow-control-c-q-replacement}).
+
+If you are fixing this for yourself, simply put the form in your
+@file{.emacs} file. If you are fixing this for your entire site, the
+best place to put it is in the @file{site-lisp/site-start.el} file.
+(Here @file{site-lisp} is actually a subdirectory of your Emacs
+installation directory, typically @file{/usr/local/share/emacs}.)
+Putting this form in @file{site-lisp/default.el} has the problem that
+if the user's @file{.emacs} file has an error, this will prevent
+@file{default.el} from being loaded and Emacs may be unusable for the
+user, even for correcting their @file{.emacs} file (unless they're
+smart enough to move it to another name).
+
+@code{enable-flow-control} can be invoked interactively as well:
+@kbd{M-x enable-flow-control @key{RET}}.
+
+@end itemize
+
+For further discussion of this issue, read the file @file{etc/PROBLEMS}
+(in the Emacs source directory when you unpack the Emacs distribution).
+
+@node Binding C-s and C-q, Backspace invokes help, Handling C-s and C-q with flow control, Key bindings
+@section How do I bind @kbd{C-s} and @kbd{C-q} (or any key) if these keys are filtered out?
+@cindex Binding @kbd{C-s} and @kbd{C-q}
+@cindex @kbd{C-s} and @kbd{C-q}, binding
+
+To bind @kbd{C-s} and @kbd{C-q}, use either @code{enable-flow-control}
+or @code{enable-flow-control-on}. @xref{Handling C-s and C-q with flow
+control}, for usage and implementation details.
+
+To bind other keys, use @code{keyboard-translate}. @xref{Swapping
+keys}, for usage details. To do this for an entire site, you should
+swap the keys in @file{site-lisp/site-start.el}. @xref{Handling C-s
+and C-q with flow control}, for an explanation of why
+@file{site-lisp/default.el} should not be used.
+
+@itemize @bullet
+
+@item
+If you do this for an entire site, the users will be confused by
+the disparity between what the documentation says and how Emacs
+actually behaves.
+
+@end itemize
+
+@node Backspace invokes help, stty and Backspace key, Binding C-s and C-q, Key bindings
+@section Why does the @key{Backspace} key invoke help?
+@cindex Backspace key invokes help
+@cindex Help invoked by Backspace
+@cindex DEL key does not delete
+
+The @key{Backspace} key (on most keyboards) generates @acronym{ASCII} code 8.
+@kbd{C-h} sends the same code. In Emacs by default @kbd{C-h} invokes
+help-command. This is intended to be easy to remember since the first
+letter of @samp{help} is @samp{h}. The easiest solution to this problem
+is to use @kbd{C-h} (and @key{Backspace}) for help and @key{DEL} (the
+@key{Delete} key) for deleting the previous character.
+
+For many people this solution may be problematic:
+
+@itemize @bullet
+
+@item
+They normally use @key{Backspace} outside of Emacs for deleting the
+previous character. This can be solved by making @key{DEL} the command
+for deleting the previous character outside of Emacs. On many Unix
+systems, this command will remap @key{DEL}:
+
+@example
+stty erase `^?'
+@end example
+
+@item
+The user may prefer the @key{Backspace} key for deleting the
+previous character because it is more conveniently located on their
+keyboard or because they don't even have a separate @key{Delete} key.
+In this case, the @key{Backspace} key should be made to behave like
+@key{Delete}. There are several methods.
+
+@itemize @minus
+@item
+Some terminals (e.g., VT3## terminals) and terminal emulators (e.g.,
+TeraTerm) allow the character generated by the @key{Backspace} key to be
+changed from a setup menu.
+
+@item
+You may be able to get a keyboard that is completely programmable, or a
+terminal emulator that supports remapping of any key to any other key.
+
+@item
+With Emacs 21.1 and later, you can control the effect of the
+@key{Backspace} and @key{Delete} keys, on both dumb terminals and a
+windowed displays, by customizing the option
+@code{normal-erase-is-backspace-mode}, or by invoking @kbd{M-x
+normal-erase-is-backspace}. See the documentation of these symbols
+(@pxref{Emacs Lisp documentation}) for more info.
+
+@item
+It is possible to swap the @key{Backspace} and @key{DEL} keys inside
+Emacs:
+
+@lisp
+(keyboard-translate ?\C-h ?\C-?)
+@end lisp
+
+@noindent
+This is the recommended method of forcing @key{Backspace} to act as
+@key{DEL}, because it works even in modes which bind @key{DEL} to
+something other than @code{delete-backward-char}.
+
+Similarly, you could remap @key{DEL} to act as @kbd{C-d}, which by
+default deletes forward:
+
+@lisp
+(keyboard-translate ?\C-? ?\C-d)
+@end lisp
+
+@xref{Swapping keys}, for further details about @code{keyboard-translate}.
+
+@item
+Another approach is to switch key bindings and put help on @kbd{C-x h}
+instead:
+
+@lisp
+(global-set-key "\C-h" 'delete-backward-char)
+
+;; overrides mark-whole-buffer
+(global-set-key "\C-xh" 'help-command)
+@end lisp
+
+@noindent
+This method is not recommended, though: it only solves the problem for
+those modes which bind @key{DEL} to @code{delete-backward-char}. Modes
+which bind @key{DEL} to something else, such as @code{view-mode}, will
+not work as you expect when you press the @key{Backspace} key. For this
+reason, we recommend the @code{keyboard-translate} method, shown
+above.
+
+Other popular key bindings for help are @kbd{M-?} and @kbd{C-x ?}.
+@end itemize
+
+Don't try to bind @key{DEL} to @code{help-command}, because there are
+many modes that have local bindings of @key{DEL} that will interfere.
+
+@end itemize
+
+When Emacs 21 or later runs on a windowed display, it binds the
+@key{Delete} key to a command which deletes the character at point, to
+make Emacs more consistent with keyboard operation on these systems.
+
+For more information about troubleshooting this problem, see @ref{DEL
+Does Not Delete, , If @key{DEL} Fails to Delete, emacs, The GNU Emacs
+Manual}.
+
+@node stty and Backspace key, Swapping keys, Backspace invokes help, Key bindings
+@section Why doesn't Emacs look at the @file{stty} settings for @key{Backspace} vs. @key{Delete}?
+@cindex @file{stty} and Emacs
+@cindex Backspace and @file{stty}
+@cindex Delete and @file{stty}
+
+Good question!
+
+@c FIXME: RMS explained the reasons for this on emacs-hackers. It's
+@c probably worth putting that explanation here.
+
+@node Swapping keys, Producing C-XXX with the keyboard, stty and Backspace key, Key bindings
+@section How do I swap two keys?
+@cindex Swapping keys
+@cindex Keys, swapping
+@cindex @code{keyboard-translate}
+
+You can swap two keys (or key sequences) by using the
+@code{keyboard-translate} function. For example, to turn @kbd{C-h}
+into @key{DEL} and @key{DEL} to @kbd{C-h}, use
+
+@lisp
+(keyboard-translate ?\C-h ?\C-?) ; translate `C-h' to DEL
+(keyboard-translate ?\C-? ?\C-h) ; translate DEL to `C-h'.
+@end lisp
+
+@noindent
+The first key sequence of the pair after the function identifies what is
+produced by the keyboard; the second, what is matched for in the
+keymaps.
+
+However, in the specific case of @kbd{C-h} and @key{DEL}, you should
+toggle @code{normal-erase-is-backspace-mode} instead of calling
+@code{keyboard-translate}. @inforef{DEL Does Not Delete, DEL Does Not Delete,
+emacs}.
+
+Keyboard translations are not the same as key bindings in 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.
+
+@node Producing C-XXX with the keyboard, No Meta key, Swapping keys, Key bindings
+@section How do I produce C-XXX with my keyboard?
+@cindex Producing control characters
+@cindex Generating control characters
+@cindex Control characters, generating
+
+On terminals (but not under X), some common ``aliases'' are:
+
+@table @asis
+
+@item @kbd{C-2} or @kbd{C-@key{SPC}}
+@kbd{C-@@}
+
+@item @kbd{C-6}
+@kbd{C-^}
+
+@item @kbd{C-7} or @kbd{C-S--}
+@kbd{C-_}
+
+@item @kbd{C-4}
+@kbd{C-\}
+
+@item @kbd{C-5}
+@kbd{C-]}
+
+@item @kbd{C-/}
+@kbd{C-?}
+
+@end table
+
+Often other aliases exist; use the @kbd{C-h c} command and try
+@key{CTRL} with all of the digits on your keyboard to see what gets
+generated. You can also try the @kbd{C-h w} command if you know the
+name of the command.
+
+@node No Meta key, No Escape key, Producing C-XXX with the keyboard, Key bindings
+@section What if I don't have a @key{Meta} key?
+@cindex No @key{Meta} key
+@cindex @key{Meta} key, what to do if you lack it
+
+On many keyboards, the @key{Alt} key acts as @key{Meta}, so try it.
+
+Instead of typing @kbd{M-a}, you can type @kbd{@key{ESC} a}. In fact,
+Emacs converts @kbd{M-a} internally into @kbd{@key{ESC} a} anyway
+(depending on the value of @code{meta-prefix-char}). Note that you
+press @key{Meta} and @key{a} together, but with @key{ESC}, you press
+@key{ESC}, release it, and then press @key{a}.
+
+@node No Escape key, Compose Character, No Meta key, Key bindings
+@section What if I don't have an @key{Escape} key?
+@cindex No Escape key
+@cindex Lacking an Escape key
+@cindex Escape key, lacking
+
+Type @kbd{C-[} instead. This should send @acronym{ASCII} code 27 just like an
+Escape key would. @kbd{C-3} may also work on some terminal (but not
+under X). For many terminals (notably DEC terminals) @key{F11}
+generates @key{ESC}. If not, the following form can be used to bind it:
+
+@lisp
+;; F11 is the documented ESC replacement on DEC terminals.
+(define-key function-key-map [f11] [?\e])
+@end lisp
+
+@node Compose Character, Binding combinations of modifiers and function keys, No Escape key, Key bindings
+@section Can I make my @key{Compose Character} key behave like a @key{Meta} key?
+@cindex @key{Compose Character} key, using as @key{Meta}
+@cindex @key{Meta}, using @key{Compose Character} for
+
+On a dumb terminal such as a VT220, no. It is rumored that certain
+VT220 clones could have their @key{Compose} key configured this way. If
+you're using X, you might be able to do this with the @code{xmodmap}
+command.
+
+@node Binding combinations of modifiers and function keys, Meta key does not work in xterm, Compose Character, Key bindings
+@section How do I bind a combination of modifier key and function key?
+@cindex Modifiers and function keys
+@cindex Function keys and modifiers
+@cindex Binding modifiers and function keys
+
+With Emacs 19 and later, you can represent modified function keys in
+vector format by adding prefixes to the function key symbol. For
+example (from the on-line documentation):
+
+@lisp
+(global-set-key [?\C-x right] 'forward-page)
+@end lisp
+
+@noindent
+where @samp{?\C-x} is the Lisp character constant for the character @kbd{C-x}.
+
+You can use the modifier keys @key{Control}, @key{Meta}, @key{Hyper},
+@key{Super}, @key{Alt}, and @key{Shift} with function keys. To
+represent these modifiers, prepend the strings @samp{C-}, @samp{M-},
+@samp{H-}, @samp{s-}, @samp{A-}, and @samp{S-} to the symbol name. Here
+is how to make @kbd{H-M-RIGHT} move forward a word:
+
+@lisp
+(global-set-key [H-M-right] 'forward-word)
+@end lisp
+
+@itemize @bullet
+
+@item
+Not all modifiers are permitted in all situations. @key{Hyper},
+@key{Super}, and @key{Alt} are not available on Unix character
+terminals. Non-@acronym{ASCII} keys and mouse events (e.g. @kbd{C-=} and
+@kbd{Mouse-1}) also fall under this category.
+
+@end itemize
+
+@xref{Binding keys to commands}, for general key binding instructions.
+
+@node Meta key does not work in xterm, ExtendChar key does not work as Meta, Binding combinations of modifiers and function keys, Key bindings
+@section Why doesn't my @key{Meta} key work in an @code{xterm} window?
+@cindex @key{Meta} key and @code{xterm}
+@cindex Xterm and @key{Meta} key
+
+@inforef{Unibyte Mode, Single-Byte Character Set Support, emacs}.
+
+If the advice in the Emacs manual fails, try all of these methods before
+asking for further help:
+
+@itemize @bullet
+
+@item
+You may have big problems using @code{mwm} as your window manager.
+(Does anyone know a good generic solution to allow the use of the
+@key{Meta} key in Emacs with @file{mwm}?)
+
+@item
+For X11: Make sure it really is a @key{Meta} key. Use @code{xev} to
+find out what keysym your @key{Meta} key generates. It should be either
+@code{Meta_L} or @code{Meta_R}. If it isn't, use @file{xmodmap} to fix
+the situation. If @key{Meta} does generate @code{Meta_L} or
+@code{Meta_R}, but @kbd{M-x} produces a non-@acronym{ASCII} character, put this in
+your @file{~/.Xdefaults} file:
+
+@example
+ XTerm*eightBitInput: false
+ XTerm*eightBitOutput: true
+@end example
+
+@item
+Make sure the @code{pty} the @code{xterm} is using is passing 8 bit
+characters. @samp{stty -a} (or @samp{stty everything}) should show
+@samp{cs8} somewhere. If it shows @samp{cs7} instead, use @samp{stty
+cs8 -istrip} (or @samp{stty pass8}) to fix it.
+
+@item
+If there is an @code{rlogin} connection between @code{xterm} and Emacs, the
+@samp{-8} argument may need to be given to rlogin to make it pass all 8 bits
+of every character.
+
+@item
+If Emacs is running on Ultrix, it is reported that evaluating
+@code{(set-input-mode t nil)} helps.
+
+@item
+If all else fails, you can make @code{xterm} generate @kbd{@key{ESC} W} when
+you type @kbd{M-W}, which is the same conversion Emacs would make if it
+got the @kbd{M-W} anyway. In X11R4, the following resource
+specification will do this:
+
+@example
+XTerm.VT100.EightBitInput: false
+@end example
+
+@noindent
+(This changes the behavior of the @code{insert-eight-bit} action.)
+
+With older @code{xterm}s, you can specify this behavior with a translation:
+
+@example
+XTerm.VT100.Translations: #override \
+ Meta<KeyPress>: string(0x1b) insert()
+@end example
+
+@noindent
+You might have to replace @samp{Meta} with @samp{Alt}.
+
+@end itemize
+
+@node ExtendChar key does not work as Meta, SPC no longer completes file names, Meta key does not work in xterm, Key bindings
+@section Why doesn't my @key{ExtendChar} key work as a @key{Meta} key under HP-UX 8.0 and 9.x?
+@cindex @key{ExtendChar} key as @key{Meta}
+@cindex @key{Meta}, using @key{ExtendChar} for
+@cindex HP-UX, the @key{ExtendChar} key
+
+This is a result of an internationalization extension in X11R4 and the
+fact that HP is now using this extension. Emacs assumes that the
+@code{XLookupString} function returns the same result regardless of the
+@key{Meta} key state which is no longer necessarily true. Until Emacs
+is fixed, the temporary kludge is to run this command after each time
+the X server is started but preferably before any xterm clients are:
+
+@example
+xmodmap -e 'remove mod1 = Mode_switch'
+@end example
+
+@c FIXME: Emacs 21 supports I18N in X11; does that mean that this bug is
+@c solved?
+
+This will disable the use of the extra keysyms systemwide, which may be
+undesirable if you actually intend to use them.
+
+@node SPC no longer completes file names, , ExtendChar key does not work as Meta, Key bindings
+@section Why doesn't SPC complete file names anymore?
+@cindex @kbd{SPC} file name completion
+
+Starting with Emacs 22.1, @kbd{SPC} no longer completes file names in
+the minibuffer, so that file names with embedded spaces could be typed
+without the need to quote the spaces.
+
+You can get the old behavior by binding @kbd{SPC} to
+@code{minibuffer-complete-word} in the minibuffer, as follows:
+
+@lisp
+(define-key minibuffer-local-filename-completion-map (kbd "SPC")
+ 'minibuffer-complete-word)
+
+(define-key minibuffer-local-must-match-filename-map (kbd "SPC")
+ 'minibuffer-complete-word)
+@end lisp
+
+@c ------------------------------------------------------------
+@node Alternate character sets, Mail and news, Key bindings, Top
+@chapter Alternate character sets
+@cindex Alternate character sets
+
+@menu
+* Emacs does not display 8-bit characters::
+* Inputting eight-bit characters::
+* Kanji and Chinese characters::
+* Right-to-left alphabets::
+* How to add fonts::
+@end menu
+
+@node Emacs does not display 8-bit characters, Inputting eight-bit characters, Alternate character sets, Alternate character sets
+@section How do I make Emacs display 8-bit characters?
+@cindex Displaying eight-bit characters
+@cindex Eight-bit characters, displaying
+
+@inforef{Unibyte Mode, Single-byte Character Set
+Support, emacs}. On a Unix, when Emacs runs on a text-only terminal
+display or is invoked with @samp{emacs -nw}, you typically need to use
+@code{set-terminal-coding-system} to tell Emacs what the terminal can
+display, even after setting the language environment; otherwise
+non-@acronym{ASCII} characters will display as @samp{?}. On other operating
+systems, such as MS-DOS and MS-Windows, Emacs queries the OS about the
+character set supported by the display, and sets up the required
+terminal coding system automatically.
+
+@node Inputting eight-bit characters, Kanji and Chinese characters, Emacs does not display 8-bit characters, Alternate character sets
+@section How do I input eight-bit characters?
+@cindex Entering eight-bit characters
+@cindex Eight-bit characters, entering
+@cindex Input, 8-bit characters
+
+Various methods are available for input of eight-bit characters. See
+@inforef{Unibyte Mode, Single-byte Character Set
+Support, emacs}. For more sophisticated methods, @inforef{Input
+Methods, Input Methods, emacs}.
+
+@node Kanji and Chinese characters, Right-to-left alphabets, Inputting eight-bit characters, Alternate character sets
+@section Where can I get an Emacs that handles kanji, Chinese, or other Far-Eastern character sets?
+@cindex Kanji, handling with Emacs
+@cindex Chinese, handling with Emacs
+@cindex Japanese, handling with Emacs
+@cindex Korean, handling with Emacs
+
+Emacs 20 and later includes many of the features of MULE, the MULtilingual
+Enhancement to Emacs. @xref{Installing Emacs}, for information on where
+to find and download the latest version of Emacs.
+
+@node Right-to-left alphabets, How to add fonts, Kanji and Chinese characters, Alternate character sets
+@section Where is an Emacs that can handle Semitic (right-to-left) alphabets?
+@cindex Right-to-left alphabets
+@cindex Hebrew, handling with Emacs
+@cindex Semitic alphabets
+@cindex Arabic alphabets
+
+Emacs 20 and later supports Hebrew characters (ISO 8859-8), but does not
+yet support right-to-left character entry and display.
+
+@email{joel@@exc.com, Joel M. Hoffman} has written a Lisp package called
+@file{hebrew.el} that allows right-to-left editing of Hebrew. It
+reportedly works out of the box with Emacs 19, but requires patches for
+Emacs 18. Write to Joel if you want the patches or package.
+
+@c FIXME: Should we mention Ehud Karni's package?
+
+@file{hebrew.el} requires a Hebrew screen font, but no other hardware support.
+Joel has a screen font for PCs running MS-DOS or GNU/Linux.
+
+You might also try querying @code{archie} for files named with
+@file{hebrew}; several ftp sites in Israel may also have the necessary
+files.
+
+@node How to add fonts, , Right-to-left alphabets, Alternate character sets
+@section How do I add fonts for use with Emacs?
+@cindex add fonts for use with Emacs
+@cindex intlfonts
+
+First, download and install the BDF font files and any auxiliary
+packages they need. The GNU Intlfonts distribution can be found on
+@uref{http://directory.fsf.org/localization/intlfonts.html, the GNU
+Software Directory Web site}.
+
+Next, if you are on X Window system, issue the following two commands
+from the shell's prompt:
+
+@example
+ xset +fp /usr/local/share/emacs/fonts
+ xset fp rehash
+@end example
+
+@noindent
+(Modify the first command if you installed the fonts in a directory
+that is not @file{/usr/local/share/emacs/fonts}.) You also need to
+arrange for these two commands to run whenever you log in, e.g., by
+adding them to your window-system startup file, such as
+@file{~/.xsessionrc} or @file{~/.gnomerc}.
+
+Now, add the following line to your @file{~/.emacs} init file:
+
+@lisp
+ (add-to-list 'bdf-directory-list "/usr/share/emacs/fonts/bdf")
+@end lisp
+
+@noindent
+(Again, modify the file name if you installed the fonts elsewhere.)
+
+Finally, if you wish to use the installed fonts with @code{ps-print},
+add the following line to your @file{~/.emacs}:
+
+@lisp
+ (setq ps-multibyte-buffer 'bdf-font-except-latin)
+@end lisp
+
+A few additional steps are necessary for MS-Windows; they are listed
+below.
+
+First, make sure @emph{all} the directories with BDF font files are
+mentioned in @code{bdf-directory-list}. On Unix and GNU/Linux
+systems, one normally runs @kbd{make install} to install the BDF fonts
+in the same directory. By contrast, Windows users typically don't run
+the Intlfonts installation command, but unpack the distribution in
+some directory, which leaves the BDF fonts in its subdirectories. For
+example, assume that you unpacked Intlfonts in @file{C:/Intlfonts};
+then you should set @code{bdf-directory-list} as follows:
+
+@lisp
+ (setq bdf-directory-list
+ '("C:/Intlfonts/Asian"
+ "C:/Intlfonts/Chinese" "C:/Intlfonts/Chinese.X"
+ "C:/Intlfonts/Chinese.BIG" "C:/Intlfonts/Ethiopic"
+ "C:/Intlfonts/European" "C:/Intlfonts/European.BIG"
+ "C:/Intlfonts/Japanese" "C:/Intlfonts/Japanese.X"
+ "C:/Intlfonts/Japanese.BIG" "C:/Intlfonts/Korean.X"
+ "C:/Intlfonts/Misc"))
+@end lisp
+
+@cindex @code{w32-bdf-filename-alist}
+@cindex @code{w32-find-bdf-fonts}
+Next, you need to set up the variable @code{w32-bdf-filename-alist} to
+an alist of the BDF fonts and their corresponding file names.
+Assuming you have set @code{bdf-directory-list} to name all the
+directories with the BDF font files, the following Lisp snippet will
+set up @code{w32-bdf-filename-alist}:
+
+@lisp
+ (setq w32-bdf-filename-alist
+ (w32-find-bdf-fonts bdf-directory-list))
+@end lisp
+
+Now, create fontsets for the BDF fonts:
+
+@lisp
+ (create-fontset-from-fontset-spec
+ "-*-fixed-medium-r-normal-*-16-*-*-*-c-*-fontset-bdf,
+ japanese-jisx0208:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1983-*,
+ katakana-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*,
+ latin-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*,
+ japanese-jisx0208-1978:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1978-*,
+ thai-tis620:-misc-fixed-medium-r-normal--16-160-72-72-m-80-tis620.2529-1,
+ lao:-misc-fixed-medium-r-normal--16-160-72-72-m-80-MuleLao-1,
+ tibetan-1-column:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-80-MuleTibetan-1,
+ ethiopic:-Admas-Ethiomx16f-Medium-R-Normal--16-150-100-100-M-160-Ethiopic-Unicode,
+ tibetan:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-160-MuleTibetan-0")
+@end lisp
+
+Many of the international bdf fonts from Intlfonts are type 0, and
+therefore need to be added to font-encoding-alist:
+
+@lisp
+ (setq font-encoding-alist
+ (append '(("MuleTibetan-0" (tibetan . 0))
+ ("GB2312" (chinese-gb2312 . 0))
+ ("JISX0208" (japanese-jisx0208 . 0))
+ ("JISX0212" (japanese-jisx0212 . 0))
+ ("VISCII" (vietnamese-viscii-lower . 0))
+ ("KSC5601" (korean-ksc5601 . 0))
+ ("MuleArabic-0" (arabic-digit . 0))
+ ("MuleArabic-1" (arabic-1-column . 0))
+ ("MuleArabic-2" (arabic-2-column . 0)))
+ font-encoding-alist))
+@end lisp
+
+You can now use the Emacs font menu to select the @samp{bdf: 16-dot medium}
+fontset, or you can select it by setting the default font in your
+@file{~/.emacs}:
+
+@lisp
+ (set-default-font "fontset-bdf")
+@end lisp
+
+
+@c ------------------------------------------------------------
+@node Mail and news, Concept index, Alternate character sets, Top
+@chapter Mail and news
+@cindex Mail and news
+
+@menu
+* Changing the included text prefix::
+* Saving a copy of outgoing mail::
+* Expanding aliases when sending mail::
+* Rmail thinks all messages are one big one::
+* Sorting the messages in an Rmail folder::
+* Rmail writes to /usr/spool/mail::
+* Recovering mail files when Rmail munges them::
+* Replying to the sender of a message::
+* MIME with Emacs mail packages::
+* Automatically starting a mail or news reader::
+* Reading news with Emacs::
+* Gnus does not work with NNTP::
+* Viewing articles with embedded underlining::
+* Saving a multi-part Gnus posting::
+* Starting Gnus faster::
+* Catching up in all newsgroups::
+* Killing based on nonstandard headers::
+* Removing flashing messages::
+* Catch-up is slow in Gnus::
+* Gnus hangs for a long time::
+* Learning more about Gnus::
+@end menu
+
+@node Changing the included text prefix, Saving a copy of outgoing mail, Mail and news, Mail and news
+@section How do I change the included text prefix in mail/news followups?
+@cindex Prefix in mail/news followups, changing
+@cindex Included text prefix, changing
+@cindex Setting the included text character
+@cindex Quoting in mail messages
+
+If you read mail with Rmail or news with Gnus, set the variable
+@code{mail-yank-prefix}. For VM, set @code{vm-included-text-prefix}.
+For mh-e, set @code{mh-ins-buf-prefix}.
+
+For fancier control of citations, use Supercite. @xref{Supercite}.
+
+To prevent Emacs from including various headers of the replied-to
+message, set the value of @code{mail-yank-ignored-headers} to an
+appropriate regexp.
+
+@node Saving a copy of outgoing mail, Expanding aliases when sending mail, Changing the included text prefix, Mail and news
+@section How do I save a copy of outgoing mail?
+@cindex Saving a copy of outgoing mail
+@cindex Copying outgoing mail to a file
+@cindex Filing outgoing mail
+@cindex Automatic filing of outgoing mail
+@cindex Mail, saving outgoing automatically
+
+You can either mail yourself a copy by including a @samp{BCC} header in the
+mail message, or store a copy of the message directly to a file by
+including an @samp{FCC} header.
+
+If you use standard mail, you can automatically create a @samp{BCC} to
+yourself by putting
+
+@lisp
+(setq mail-self-blind t)
+@end lisp
+
+@noindent
+in your @file{.emacs} file. You can automatically include an @samp{FCC}
+field by putting something like the following in your @file{.emacs}
+file:
+
+@lisp
+(setq mail-archive-file-name (expand-file-name "~/outgoing"))
+@end lisp
+
+The output file will be in Unix mail format, which can be read directly
+by VM, but not always by Rmail. @xref{Learning how to do something}.
+
+If you use @code{mh-e}, add an @samp{FCC} or @samp{BCC} field to your
+components file.
+
+It does not work to put @samp{set record filename} in the @file{.mailrc}
+file.
+
+@node Expanding aliases when sending mail, Rmail thinks all messages are one big one, Saving a copy of outgoing mail, Mail and news
+@section Why doesn't Emacs expand my aliases when sending mail?
+@cindex Expanding aliases when sending mail
+@cindex Mail alias expansion
+@cindex Sending mail with aliases
+
+@itemize @bullet
+
+@item
+You must separate multiple addresses in the headers of the mail buffer
+with commas. This is because Emacs supports RFC822 standard addresses
+like this one:
+
+@example
+To: Willy Smith <wks@@xpnsv.lwyrs.com>
+@end example
+
+However, you do not need to---and probably should not, unless your
+system's version of @file{/usr/ucb/mail} (a.k.a.@: @code{mailx})
+supports RFC822---separate addresses with commas in your
+@file{~/.mailrc} file.
+
+@item
+Emacs normally only reads the @file{.mailrc} file once per session,
+when you start to compose your first mail message. If you edit
+@file{.mailrc}, you can type @kbd{M-x rebuild-mail-abbrevs @key{RET}} to
+make Emacs reread @file{~/.mailrc}.
+
+@item
+If you like, you can expand mail aliases as abbrevs, as soon as you
+type them in. To enable this feature, execute the following:
+
+@lisp
+(add-hook 'mail-mode-hook 'mail-abbrevs-setup)
+@end lisp
+
+Note that the aliases are expanded automatically only after you type
+@key{RET} or a punctuation character (e.g. @kbd{,}). You can force their
+expansion by moving point to the end of the alias and typing @kbd{C-x a e}
+(@kbd{M-x expand-abbrev}).
+@end itemize
+
+@node Rmail thinks all messages are one big one, Sorting the messages in an Rmail folder, Expanding aliases when sending mail, Mail and news
+@section Why does Rmail think all my saved messages are one big message?
+@cindex Rmail thinks all messages are one large message
+
+A file created through the @samp{FCC} field in a message is in Unix mail
+format, not the format that Rmail uses (BABYL format). Rmail will try
+to convert a Unix mail file into BABYL format on input, but sometimes it
+makes errors. For guaranteed safety, you can make the
+@file{saved-messages} file be an inbox for your Rmail file by using the
+function @code{set-rmail-inbox-list}.
+
+@node Sorting the messages in an Rmail folder, Rmail writes to /usr/spool/mail, Rmail thinks all messages are one big one, Mail and news
+@section How can I sort the messages in my Rmail folder?
+@cindex Rmail, sorting messages in
+@cindex Folder, sorting messages in an Rmail
+@cindex Sorting messages in an Rmail folder
+
+In Rmail, type @kbd{C-c C-s C-h} to get a list of sorting functions
+and their key bindings.
+
+@node Rmail writes to /usr/spool/mail, Recovering mail files when Rmail munges them, Sorting the messages in an Rmail folder, Mail and news
+@section Why does Rmail need to write to @file{/usr/spool/mail}?
+@cindex Rmail and @file{/usr/spool/mail}
+@cindex @file{/usr/spool/mail} and Rmail
+
+This is the behavior of the @code{movemail} program which Rmail uses.
+This indicates that @code{movemail} is configured to use lock files.
+
+RMS writes:
+
+@quotation
+Certain systems require lock files to interlock access to mail files.
+On these systems, @code{movemail} must write lock files, or you risk losing
+mail. You simply must arrange to let @code{movemail} write them.
+
+Other systems use the @code{flock} system call to interlock access. On
+these systems, you should configure @code{movemail} to use @code{flock}.
+@end quotation
+
+@node Recovering mail files when Rmail munges them, Replying to the sender of a message, Rmail writes to /usr/spool/mail, Mail and news
+@section How do I recover my mail files after Rmail munges their format?
+@cindex Recovering munged mail files
+@cindex Rmail munged my files
+@cindex Mail files, recovering those munged by Rmail
+
+If you have just done @kbd{M-x rmail-input} on a file and you don't want
+to save it in Rmail's format (called BABYL), just kill the buffer (with
+@kbd{C-x k}).
+
+@cindex Exporting messages as Unix mail files
+If you typed @kbd{M-x rmail} and it read some messages out of your inbox
+and you want to put them in a Unix mail file, use @kbd{C-o} on each
+message.
+
+@cindex Converting from BABYL to Unix mail format
+@cindex @code{unrmail} command
+If you want to convert an existing file from BABYL format to Unix mail
+format, use the command @kbd{M-x unrmail}: it will prompt you for the
+input and output file names.
+
+@pindex b2m
+Alternatively, you could use the @code{b2m} program supplied with
+Emacs. @code{b2m} is a filter, and is used like this:
+
+@example
+ b2m < @var{babyl-file} > @var{mbox-file}
+@end example
+
+@noindent
+where @var{babyl-file} is the name of the BABYL file, and
+@var{mbox-file} is the name of the file where the converted mail will
+be written.
+
+@node Replying to the sender of a message, MIME with Emacs mail packages, Recovering mail files when Rmail munges them, Mail and news
+@section How can I force Rmail to reply to the sender of a message, but not the other recipients?
+@cindex Replying only to the sender of a message
+@cindex Sender, replying only to
+@cindex Rmail, replying to the sender of a message in
+
+@email{isaacson@@seas.upenn.edu, Ron Isaacson} says: When you hit
+@key{r} to reply in Rmail, by default it CCs all of the original
+recipients (everyone on the original @samp{To} and @samp{CC}
+lists). With a prefix argument (i.e., typing @kbd{C-u} before @key{r}),
+it replies only to the sender. However, going through the whole
+@kbd{C-u} business every time you want to reply is a pain. This is the
+best fix I've been able to come up with:
+
+@lisp
+(defun rmail-reply-t ()
+ "Reply only to the sender of the current message. (See rmail-reply.)"
+ (interactive)
+ (rmail-reply t))
+
+(add-hook 'rmail-mode-hook
+ (lambda ()
+ (define-key rmail-mode-map "r" 'rmail-reply-t)
+ (define-key rmail-mode-map "R" 'rmail-reply)))
+@end lisp
+
+@node MIME with Emacs mail packages, Automatically starting a mail or news reader, Replying to the sender of a message, Mail and news
+@section How can I get my favorite Emacs mail package to support MIME?
+@cindex MIME and Emacs mail packages
+@cindex Mail packages and MIME
+@cindex FAQ for MIME and Emacs
+
+Version 6.x of VM supports MIME. @xref{VM}. Gnus supports MIME in mail
+and news messages as of version 5.8.1 (Pterodactyl). Rmail has limited
+support for single-part MIME messages beginning with Emacs 20.3.
+
+@node Automatically starting a mail or news reader, Reading news with Emacs, MIME with Emacs mail packages, Mail and news
+@section How do I make Emacs automatically start my mail/news reader?
+@cindex Mail reader, starting automatically
+@cindex News reader, starting automatically
+@cindex Starting mail/news reader automatically
+
+To start Emacs in Gnus:
+
+@example
+emacs -f gnus
+@end example
+
+@noindent
+in Rmail:
+
+@example
+emacs -f rmail
+@end example
+
+A more convenient way to start with Gnus:
+
+@example
+alias gnus 'emacs -f gnus'
+gnus
+@end example
+
+It is probably unwise to automatically start your mail or news reader
+from your @file{.emacs} file. This would cause problems if you needed to run
+two copies of Emacs at the same time. Also, this would make it difficult for
+you to start Emacs quickly when you needed to.
+
+@node Reading news with Emacs, Gnus does not work with NNTP, Automatically starting a mail or news reader, Mail and news
+@section How do I read news under Emacs?
+@cindex Reading news under Emacs
+@cindex Usenet reader in Emacs
+@cindex Gnus newsreader
+
+Use @kbd{M-x gnus}. It is documented in Info (@pxref{Learning how to do
+something}).
+
+@node Gnus does not work with NNTP, Viewing articles with embedded underlining, Reading news with Emacs, Mail and news
+@section Why doesn't Gnus work via NNTP?
+@cindex Gnus and NNTP
+@cindex NNTP, Gnus fails to work with
+
+There is a bug in NNTP version 1.5.10, such that when multiple requests
+are sent to the NNTP server, the server only handles the first one
+before blocking waiting for more input which never comes. NNTP version
+1.5.11 claims to fix this.
+
+You can work around the bug inside Emacs like this:
+
+@lisp
+(setq nntp-maximum-request 1)
+@end lisp
+
+You can find out what version of NNTP your news server is running by
+telnetting to the NNTP port (usually 119) on the news server machine
+(i.e., @kbd{telnet server-machine 119}). The server should give its
+version number in the welcome message. Type @kbd{quit} to get out.
+
+@xref{Spontaneous entry into isearch-mode}, for some additional ideas.
+
+@node Viewing articles with embedded underlining, Saving a multi-part Gnus posting, Gnus does not work with NNTP, Mail and news
+@section How do I view news articles with embedded underlining (e.g., ClariNews)?
+@cindex Underlining, embedded in news articles
+@cindex News articles with embedded underlining
+@cindex Embedded underlining in news articles
+
+Underlining appears like this:
+
+@example
+_^Hu_^Hn_^Hd_^He_^Hr_^Hl_^Hi_^Hn_^Hi_^Hn_^Hg
+@end example
+
+@email{abraham@@dina.kvl.dk, Per Abrahamsen} suggests using the following
+code, which uses the underline face to turn such text into true
+underlining, inconjunction with Gnus:
+
+@lisp
+(defun gnus-article-prepare-overstrike ()
+ ;; Prepare article for overstrike commands.
+ (save-excursion
+ (set-buffer gnus-article-buffer)
+ (let ((buffer-read-only nil))
+ (goto-char (point-min))
+ (while (search-forward "\b" nil t)
+ (let ((next (following-char))
+ (previous (char-after (- (point) 2))))
+ (cond ((eq next previous)
+ (delete-region (- (point) 2) (point))
+ (put-text-property (point) (1+ (point))
+ 'face 'bold))
+ ((eq next ?_)
+ (delete-region (1- (point)) (1+ (point)))
+ (put-text-property (1- (point)) (point)
+ 'face 'underline))
+ ((eq previous ?_)
+ (delete-region (- (point) 2) (point))
+ (put-text-property (point) (1+ (point))
+ 'face 'underline))))))))
+
+(add-hook 'gnus-article-prepare-hook 'gnus-article-prepare-overstrike)
+@end lisp
+
+Latest versions of Gnus do such a conversion automatically.
+
+If you prefer to do away with underlining altogether, you can
+destructively remove it with @kbd{M-x ununderline-region}; do this
+automatically via
+
+@lisp
+(add-hook 'gnus-article-prepare-hook
+ (lambda () (ununderline-region (point-min) (point-max))))
+@end lisp
+
+@node Saving a multi-part Gnus posting, Starting Gnus faster, Viewing articles with embedded underlining, Mail and news
+@section How do I save all the items of a multi-part posting in Gnus?
+@cindex Multi-part postings in Gnus, saving
+@cindex Saving multi-part postings in Gnus
+@cindex Gnus, saving multi-part postings in
+
+Use @code{gnus-uu}. Type @kbd{C-c C-v C-h} in the Gnus summary buffer
+to see a list of available commands.
+
+@node Starting Gnus faster, Catching up in all newsgroups, Saving a multi-part Gnus posting, Mail and news
+@section How do I make Gnus start up faster?
+@cindex Faster, starting Gnus
+@cindex Starting Gnus faster
+@cindex Gnus, starting faster
+
+From the Gnus FAQ (@pxref{Learning more about Gnus}):
+
+@quotation
+@email{pktiwari@@eos.ncsu.edu, Pranav Kumar Tiwari} writes: I posted
+the same query recently and I got an answer to it. I am going to
+repeat the answer. What you need is a newer version of gnus, version
+5.0.4+. I am using 5.0.12 and it works fine with me with the
+following settings:
+
+@lisp
+(setq gnus-check-new-newsgroups nil
+ gnus-read-active-file 'some
+ gnus-nov-is-evil nil
+ gnus-select-method '(nntp gnus-nntp-server))
+@end lisp
+@end quotation
+
+@node Catching up in all newsgroups, Killing based on nonstandard headers, Starting Gnus faster, Mail and news
+@section How do I catch up all newsgroups in Gnus?
+@cindex Catching up all newsgroups in Gnus
+@cindex Gnus, Catching up all newsgroups in
+
+In the @file{*Newsgroup*} buffer, type @kbd{M-< C-x ( c y C-x ) M-0 C-x e}
+
+Leave off the initial @kbd{M-<} if you only want to catch up from point
+to the end of the @file{*Newsgroup*} buffer.
+
+@node Killing based on nonstandard headers, Removing flashing messages, Catching up in all newsgroups, Mail and news
+@section Why can't I kill in Gnus based on the Newsgroups/Keywords/Control headers?
+@cindex Killing articles based on nonstandard headers
+@cindex Newsgroups header, killing articles based on
+@cindex Keywords header, killing articles based on
+@cindex Control header, killing articles based on
+
+Gnus will complain that the @samp{Newsgroups}, @samp{Keywords}, and
+@samp{Control} headers are ``Unknown header'' fields.
+
+For the @samp{Newsgroups} header, there is an easy workaround: kill on the
+@samp{Xref} header instead, which will be present on any cross-posted article
+(as long as your site carries the cross-post group).
+
+If you really want to kill on one of these headers, you can do it like
+this:
+
+@lisp
+(gnus-kill nil "^Newsgroups: .*\\(bad\\.group\\|worse\\.group\\)")
+@end lisp
+
+@node Removing flashing messages, Catch-up is slow in Gnus, Killing based on nonstandard headers, Mail and news
+@section How do I get rid of flashing messages in Gnus for slow connections?
+@cindex Flashing Gnus messages, removing
+@cindex Removing flashing Gnus messages
+@cindex Slow connections causing flashing messages in Gnus
+@cindex Gnus, flashing messages in
+
+Set @code{nntp-debug-read} to @code{nil}.
+
+@node Catch-up is slow in Gnus, Gnus hangs for a long time, Removing flashing messages, Mail and news
+@section Why is catch up slow in Gnus?
+@cindex Slow catch up in Gnus
+@cindex Gnus is slow when catching up
+@cindex Crosspostings make Gnus catching up slow
+
+Because Gnus is marking crosspostings read. You can control this with
+the variable @code{gnus-use-cross-reference}.
+
+@node Gnus hangs for a long time, Learning more about Gnus, Catch-up is slow in Gnus, Mail and news
+@section Why does Gnus hang for a long time when posting?
+@cindex Hangs in Gnus
+@cindex Gnus hangs while posting
+@cindex Posting, Gnus hangs wile
+
+@email{tale@@uunet.uu.net, David Lawrence} explains:
+
+@quotation
+The problem is almost always interaction between NNTP and C News. NNTP
+POST asks C News's @code{inews} to not background itself but rather hang
+around and give its exit status so it knows whether the post was successful.
+(That wait will on some systems not return the exit status of the
+waited for job is a different sort of problem.) It ends up taking a
+long time because @code{inews} is calling @code{relaynews}, which often
+waits for another @code{relaynews} to free the lock on the news system
+so it can file the article.
+
+My preferred solution is to change @code{inews} to not call
+@code{relaynews}, but rather use @code{newsspool}. This loses some
+error-catching functionality, but is for the most part safe as
+@code{inews} will detect a lot of the errors on its own. The C News
+folks have sped up @code{inews}, too, so speed should look better to
+most folks as that update propagates around.
+@end quotation
+
+@node Learning more about Gnus, , Gnus hangs for a long time, Mail and news
+@section Where can I find out more about Gnus?
+@cindex FAQ for Gnus
+@cindex Gnus FAQ
+@cindex Learning more about Gnus
+
+For more information on Gnus, consult the Gnus manual and FAQ, which are
+part of the Gnus distribution.
+
+@node Concept index, , Mail and news, Top
+@unnumbered Concept Index
+@printindex cp
+
+@contents
+@bye
+
+@ignore
+ arch-tag: fee0d62d-06cf-43d8-ac21-123408eaf10f
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@comment %**start of header
+@setfilename ../info/flymake
+@set VERSION 0.3
+@set UPDATED April 2004
+@settitle GNU Flymake @value{VERSION}
+@syncodeindex pg cp
+@comment %**end of header
+
+@copying
+This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}),
+which is a universal on-the-fly syntax checker for GNU Emacs.
+
+Copyright @copyright{} 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below. A copy of the license
+is included in the section entitled ``GNU Free Documentation License''
+in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Flymake: (flymake). A universal on-the-fly syntax checker.
+@end direntry
+
+@titlepage
+@title GNU Flymake
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author Pavel Kobiakov(@email{pk_at_work@@yahoo.com})
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top GNU Flymake
+@end ifnottex
+
+@menu
+* Overview of Flymake::
+* Installing Flymake::
+* Using Flymake::
+* Configuring Flymake::
+* Flymake Implementation::
+* GNU Free Documentation License::
+* Index::
+@end menu
+
+@node Overview of Flymake
+@chapter Overview
+@cindex Overview of Flymake
+
+Flymake is a universal on-the-fly syntax checker implemented as an
+Emacs minor mode. Flymake runs the pre-configured syntax check tool
+(compiler for C++ files, @code{perl} for perl files, etc.) in the
+background, passing it a temporary copy of the current buffer, and
+parses the output for known error/warning message patterns. Flymake
+then highlights erroneous lines (i.e. lines for which at least one
+error or warning has been reported by the syntax check tool), and
+displays an overall buffer status in the mode line. Status information
+displayed by Flymake contains total number of errors and warnings
+reported for the buffer during the last syntax check.
+
+@code{flymake-goto-next-error} and @code{flymake-goto-prev-error}
+functions allow for easy navigation to the next/previous erroneous
+line, respectively.
+
+Calling @code{flymake-display-err-menu-for-current-line} will popup a
+menu containing error messages reported by the syntax check tool for
+the current line. Errors/warnings belonging to another file, such as a
+@code{.h} header file included by a @code{.c} file, are shown in the
+current buffer as belonging to the first line. Menu items for such
+messages also contain a filename and a line number. Selecting such a
+menu item will automatically open the file and jump to the line with
+error.
+
+Syntax check is done 'on-the-fly'. It is started whenever
+
+@itemize @bullet
+@item buffer is loaded
+@item a newline character is added to the buffer
+@item some changes were made to the buffer more than @code{0.5} seconds ago (the
+delay is configurable).
+@end itemize
+
+Flymake is a universal syntax checker in the sense that it's easily
+extended to support new syntax check tools and error message
+patterns. @xref{Configuring Flymake}.
+
+@node Installing Flymake
+@chapter Installing
+@cindex Installing Flymake
+
+
+Flymake is packaged in a single file, @code{flymake.el}.
+
+To install/update Flymake, place @code{flymake.el} to a directory
+somewhere on Emacs load path. You might also want to byte-compile
+@code{flymake.el} to improve performance.
+
+Also, place the following line in the @code{.emacs} file.
+
+@lisp
+(require 'flymake)
+@end lisp
+
+You might also map the most frequently used Flymake functions, such as
+@code{flymake-goto-next-error}, to some keyboard shortcuts:
+
+@lisp
+(global-set-key [f3] 'flymake-display-err-menu-for-current-line)
+(global-set-key [f4] 'flymake-goto-next-error)
+@end lisp
+
+@node Using Flymake
+@chapter Using Flymake
+@cindex Using Flymake
+
+@menu
+* Flymake mode::
+* Running the syntax check::
+* Navigating to error lines::
+* Viewing error messages::
+* Syntax check statuses::
+* Troubleshooting::
+@end menu
+
+@node Flymake mode
+@section Flymake mode
+@cindex flymake-mode
+
+Flymake is an Emacs minor mode. To use Flymake, you
+must first activate @code{flymake-mode} by using the
+@code{flymake-mode} function.
+
+Instead of manually activating @code{flymake-mode}, you can configure
+Flymake to automatically enable @code{flymake-mode} upon opening any
+file for which syntax check is possible. To do so, place the following
+line in @code{.emacs}:
+
+@lisp
+(add-hook 'find-file-hook 'flymake-find-file-hook)
+@end lisp
+
+@node Running the syntax check
+@section Running the syntax check
+@cindex Manually starting the syntax check
+
+When @code{flymake-mode} is active, syntax check is started
+automatically on any of the three conditions mentioned above. Syntax
+check can also be started manually by using the
+@code{flymake-start-syntax-check-for-current-buffer} function. This
+can be used, for example, when changes were made to some other buffer
+affecting the current buffer.
+
+@node Navigating to error lines
+@section Navigating to error lines
+@cindex Navigating to error lines
+
+After syntax check is completed, lines for which at least one error or
+warning has been reported are highlighted, and total number of errors
+and warning is shown in the mode line. Use the following functions to
+navigate the highlighted lines.
+
+@multitable @columnfractions 0.25 0.75
+
+@item @code{flymake-goto-next-error}
+@tab Moves point to the next erroneous line, if any.
+
+@item @code{flymake-goto-prev-error}
+@tab Moves point to the previous erroneous line.
+
+@end multitable
+
+These functions treat erroneous lines as a linked list. Therefore,
+@code{flymake-goto-next-error} will go to the first erroneous line
+when invoked in the end of the buffer.
+
+@node Viewing error messages
+@section Viewing error messages
+@cindex Viewing error messages
+
+To view error messages belonging to the current line, use the
+@code{flymake-display-err-menu-for-current-line} function. If there's
+at least one error or warning reported for the current line, this
+function will display a popup menu with error/warning texts.
+Selecting the menu item whose error belongs to another file brings
+forward that file with the help of the
+@code{flymake-goto-file-and-line} function.
+
+@node Syntax check statuses
+@section Syntax check statuses
+@cindex Syntax check statuses
+
+After syntax check is finished, its status is displayed in the mode line.
+The following statuses are defined.
+
+@multitable @columnfractions 0.25 0.75
+@item Flymake* or Flymake:E/W*
+@tab Flymake is currently running. For the second case, E/W contains the
+ error and warning count for the previous run.
+
+@item Flymake
+@tab Syntax check is not running. Usually this means syntax check was
+ successfully passed (no errors, no warnings). Other possibilities are:
+ syntax check was killed as a result of executing
+ @code{flymake-compile}, or syntax check cannot start as compilation
+ is currently in progress.
+
+@item Flymake:E/W
+@tab Number of errors/warnings found by the syntax check process.
+
+@item Flymake:!
+@tab Flymake was unable to find master file for the current buffer.
+@end multitable
+
+The following errors cause a warning message and switch flymake mode
+OFF for the buffer.
+
+@multitable @columnfractions 0.25 0.75
+@item CFGERR
+@tab Syntax check process returned nonzero exit code, but no
+ errors/warnings were reported. This indicates a possible configuration
+ error (for example, no suitable error message patterns for the
+ syntax check tool).
+
+@item NOMASTER
+@tab Flymake was unable to find master file for the current buffer.
+
+@item NOMK
+@tab Flymake was unable to find a suitable buildfile for the current buffer.
+
+@item PROCERR
+@tab Flymake was unable to launch a syntax check process.
+@end multitable
+
+
+@node Troubleshooting
+@section Troubleshooting
+@cindex Logging
+@cindex Troubleshooting
+
+Flymake uses a simple logging facility for indicating important points
+in the control flow. The logging facility sends logging messages to
+the @code{*Messages*} buffer. The information logged can be used for
+resolving various problems related to Flymake.
+
+Logging output is controlled by the @code{flymake-log-level}
+variable. @code{3} is the most verbose level, and @code{-1} switches
+logging off.
+
+@node Configuring Flymake
+@chapter Configuring and Extending Flymake
+@cindex Configuring and Extending Flymake
+
+@menu
+* Customizable variables::
+* Adding support for a new syntax check tool::
+@end menu
+
+Flymake was designed to be easily extended for supporting new syntax
+check tools and error message patterns.
+
+@node Customizable variables
+@section Customizable variables
+@cindex Customizable variables
+
+This section summarizes variables used for Flymake
+configuration.
+
+@table @code
+@item flymake-log-level
+Controls logging output, see @ref{Troubleshooting}.
+
+@item flymake-allowed-file-name-masks
+A list of @code{(filename-regexp, init-function, cleanup-function
+getfname-function)} for configuring syntax check tools. @xref{Adding
+support for a new syntax check tool}.
+
+@item flymake-buildfile-dirs
+A list of directories (relative paths) for searching a
+buildfile. @xref{Locating the buildfile}.
+
+@item flymake-master-file-dirs
+A list of directories for searching a master file. @xref{Locating a
+master file}.
+
+@item flymake-get-project-include-dirs-function
+A function used for obtaining a list of project include dirs (C/C++
+specific). @xref{Getting the include directories}.
+
+@item flymake-master-file-count-limit
+@itemx flymake-check-file-limit
+Used when looking for a master file. @xref{Locating a master file}.
+
+@item flymake-err-line-patterns
+Patterns for error/warning messages in the form @code{(regexp file-idx
+line-idx err-text-idx)}. @xref{Parsing the output}.
+
+@item flymake-compilation-prevents-syntax-check
+A flag indicating whether compilation and syntax check of the same
+file cannot be run simultaneously.
+
+@item flymake-no-changes-timeout
+If any changes are made to the buffer, syntax check is automatically
+started after @code{flymake-no-changes-timeout} seconds.
+
+@item flymake-gui-warnings-enabled
+A boolean flag indicating whether Flymake will show message boxes for
+non-recoverable errors. If @code{flymake-gui-warnings-enabled} is
+@code{nil}, these errors will only be logged to the @code{*Messages*}
+buffer.
+
+@item flymake-start-syntax-check-on-newline
+A boolean flag indicating whether to start syntax check after a
+newline character is added to the buffer.
+
+@item flymake-errline-face
+A custom face for highlighting lines for which at least one error has
+been reported.
+
+@item flymake-warnline-face
+A custom face for highlighting lines for which at least one warning
+and no errors have been reported.
+
+@end table
+
+@node Adding support for a new syntax check tool
+@section Adding support for a new syntax check tool
+@cindex Adding support for a new syntax check tool
+
+@menu
+* Example -- Configuring a tool called directly::
+* Example -- Configuring a tool called via make::
+@end menu
+
+Syntax check tools are configured using the
+@code{flymake-allowed-file-name-masks} list. Each item of this list
+has the following format:
+
+@lisp
+(filename-regexp, init-function, cleanup-function, getfname-function)
+@end lisp
+
+@table @code
+@item filename-regexp
+This field is used as a key for locating init/cleanup/getfname
+functions for the buffer. Items in
+@code{flymake-allowed-file-name-masks} are searched sequentially. The
+first item with @code{filename-regexp} matching buffer filename is
+selected. If no match is found, @code{flymake-mode} is switched off.
+
+@item init-function
+@code{init-function} is required to initialize the syntax check,
+usually by creating a temporary copy of the buffer contents. The
+function must return @code{(list cmd-name arg-list)}. If
+@code{init-function} returns null, syntax check is aborted, by
+@code{flymake-mode} is not switched off.
+
+@item cleanup-function
+@code{cleanup-function} is called after the syntax check process is
+complete and should take care of proper deinitialization, which is
+usually deleting a temporary copy created by the @code{init-function}.
+
+@item getfname-function
+This function is used for translating filenames reported by the syntax
+check tool into ``real'' filenames. Filenames reported by the tool
+will be different from the real ones, as actually the tool works with
+the temporary copy. In most cases, the default implementation
+provided by Flymake, @code{flymake-get-real-file-name}, can be used as
+@code{getfname-function}.
+
+@end table
+
+To add support for a new syntax check tool, write corresponding
+@code{init-function}, and, optionally @code{cleanup-function} and
+@code{getfname-function}. If the format of error messages reported by
+the new tool is not yet supported by Flymake, add a new entry to
+the @code{flymake-err-line-patterns} list.
+
+The following sections contain some examples of configuring Flymake
+support for various syntax check tools.
+
+@node Example -- Configuring a tool called directly
+@subsection Example -- Configuring a tool called directly
+@cindex Adding support for perl
+
+In this example, we will add support for @code{perl} as a syntax check
+tool. @code{perl} supports the @code{-c} option which does syntax
+checking.
+
+First, we write the @code{init-function}:
+
+@lisp
+(defun flymake-perl-init (buffer)
+ (let* ((temp-file (flymake-init-create-temp-buffer-copy
+ buffer 'flymake-create-temp-inplace))
+ (local-file (concat (flymake-build-relative-filename
+ (file-name-directory
+ (buffer-file-name
+ (current-buffer)))
+ (file-name-directory temp-file))
+ (file-name-nondirectory temp-file))))
+ (list "perl" (list "-wc " local-file))))
+@end lisp
+
+@code{flymake-perl-init} creates a temporary copy of the buffer
+contents with the help of
+@code{flymake-init-create-temp-buffer-copy}, and builds an appropriate
+command line.
+
+Next, we add a new entry to the
+@code{flymake-allowed-file-name-masks}:
+
+@lisp
+(setq flymake-allowed-file-name-masks
+ (cons '(".+\\.pl$"
+ flymake-perl-init
+ flymake-simple-cleanup
+ flymake-get-real-file-name)
+ flymake-allowed-file-name-masks))
+@end lisp
+
+Note that we use standard @code{cleanup-function} and
+@code{getfname-function}.
+
+Finally, we add an entry to @code{flymake-err-line-patterns}:
+
+@lisp
+(setq flymake-err-line-patterns
+ (cons '("\\(.*\\) at \\([^ \n]+\\) line \\([0-9]+\\)[,.\n]"
+ 2 3 nil 1)
+ flymake-err-line-patterns))
+@end lisp
+
+@node Example -- Configuring a tool called via make
+@subsection Example -- Configuring a tool called via make
+@cindex Adding support for C (gcc+make)
+
+In this example we will add support for C files syntax checked by
+@code{gcc} called via @code{make}.
+
+We're not required to write any new functions, as Flymake already has
+functions for @code{make}. We just add a new entry to the
+@code{flymake-allowed-file-name-masks}:
+
+@lisp
+(setq flymake-allowed-file-name-masks
+ (cons '(".+\\.c$"
+ flymake-simple-make-init
+ flymake-simple-cleanup
+ flymake-get-real-file-name)
+ flymake-allowed-file-name-masks))
+@end lisp
+
+@code{flymake-simple-make-init} builds the following @code{make}
+command line:
+
+@lisp
+(list "make"
+ (list "-s" "-C"
+ base-dir
+ (concat "CHK_SOURCES=" source)
+ "SYNTAX_CHECK_MODE=1"
+ "check-syntax"))
+@end lisp
+
+@code{base-dir} is a directory containing @code{Makefile}, see @ref{Locating the buildfile}.
+
+Thus, @code{Makefile} must contain the @code{check-syntax} target. In
+our case this target might look like this:
+
+@verbatim
+check-syntax:
+ gcc -o nul -S ${CHK_SOURCES}
+@end verbatim
+
+The format of error messages reported by @code{gcc} is already
+supported by Flymake, so we don't have to add a new entry to
+@code{flymake-err-line-patterns}.
+
+@node Flymake Implementation
+@chapter Flymake Implementation
+@cindex Implementation details
+
+@menu
+* Determining whether syntax check is possible::
+* Making a temporary copy::
+* Locating a master file::
+* Getting the include directories::
+* Locating the buildfile::
+* Starting the syntax check process::
+* Parsing the output::
+* Highlighting erroneous lines::
+* Interaction with other modes::
+@end menu
+
+Syntax check is started by calling @code{flymake-start-syntax-check-for-current-buffer}.
+Flymake first determines whether it is able to do syntax
+check. It then saves a copy of the buffer in a temporary file in the
+buffer's directory (or in the system temp directory -- for java
+files), creates a syntax check command and launches a process with
+this command. The output is parsed using a list of error message patterns,
+and error information (file name, line number, type and text) is
+saved. After the process has finished, Flymake highlights erroneous
+lines in the buffer using the accumulated error information.
+
+@node Determining whether syntax check is possible
+@section Determining whether syntax check is possible
+@cindex Syntax check models
+@cindex Master file
+
+Syntax check is considered possible if there's an entry in
+@code{flymake-allowed-file-name-masks} matching buffer's filename and
+its @code{init-function} returns non-@code{nil} value.
+
+Two syntax check modes are distinguished:
+
+@enumerate
+
+@item
+Buffer can be syntax checked in a standalone fashion, that is, the
+file (its temporary copy, in fact) can be passed over to the compiler to
+do the syntax check. Examples are C/C++ (.c, .cpp) and Java (.java)
+sources.
+
+@item
+Buffer can be syntax checked, but additional file, called master file,
+is required to perform this operation. A master file is a file that
+includes the current file, so that running a syntax check tool on it
+will also check syntax in the current file. Examples are C/C++ (.h,
+.hpp) headers.
+
+@end enumerate
+
+These modes are handled inside init/cleanup/getfname functions, see
+@ref{Adding support for a new syntax check tool}.
+
+Flymake contains implementations of all functionality required to
+support different syntax check modes described above (making
+temporary copies, finding master files, etc.), as well as some
+tool-specific (routines for @code{make}, @code{Ant}, etc.) code.
+
+
+@node Making a temporary copy
+@section Making a temporary copy
+@cindex Temporary copy of the buffer
+@cindex Master file
+
+After the possibility of the syntax check has been determined, a
+temporary copy of the current buffer is made so that the most recent
+unsaved changes could be seen by the syntax check tool. Making a copy
+is quite straightforward in a standalone case (mode @code{1}), as it's
+just saving buffer contents to a temporary file.
+
+Things get trickier, however, when master file is involved, as it
+requires to
+
+@itemize @bullet
+@item locate a master file
+@item patch it to include the current file using its new (temporary)
+name.
+@end itemize
+
+Locating a master file is discussed in the following section.
+
+Patching just changes all appropriate lines of the master file so that they
+use the new (temporary) name of the current file. For example, suppose current
+file name is @code{file.h}, the master file is @code{file.cpp}, and
+it includes current file via @code{#include "file.h"}. Current file's copy
+is saved to file @code{file_flymake.h}, so the include line must be
+changed to @code{#include "file_flymake.h"}. Finally, patched master file
+is saved to @code{file_flymake_master.cpp}, and the last one is passed to
+the syntax check tool.
+
+@node Locating a master file
+@section Locating a master file
+@cindex Master file
+
+Master file is located in two steps.
+
+First, a list of possible master files is built. A simple name
+matching is used to find the files. For a C++ header @code{file.h},
+Flymake searches for all @code{.cpp} files in the directories whose relative paths are
+stored in a customizable variable @code{flymake-master-file-dirs}, which
+usually contains something like @code{("." "./src")}. No more than
+@code{flymake-master-file-count-limit} entries is added to the master file
+list. The list is then sorted to move files with names @code{file.cpp} to
+the top.
+
+Next, each master file in a list is checked to contain the appropriate
+include directives. No more than @code{flymake-check-file-limit} of each
+file are parsed.
+
+For @code{file.h}, the include directives to look for are
+@code{#include "file.h"}, @code{#include "../file.h"}, etc. Each
+include is checked against a list of include directories
+(see @ref{Getting the include directories}) to be sure it points to the
+correct @code{file.h}.
+
+First matching master file found stops the search. The master file is then
+patched and saved to disk. In case no master file is found, syntax check is
+aborted, and corresponding status (!) is reported in the mode line.
+
+@node Getting the include directories
+@section Getting the include directories
+@cindex Include directories (C/C++ specific)
+
+Two sets of include directories are distinguished: system include directories
+and project include directories. The former is just the contents of the
+@code{INCLUDE} environment variable. The latter is not so easy to obtain,
+and the way it can be obtained can vary greatly for different projects.
+Therefore, a customizable variable
+@code{flymake-get-project-include-dirs-function} is used to provide the
+way to implement the desired behavior.
+
+The default implementation, @code{flymake-get-project-include-dirs-imp},
+uses a @code{make} call. This requires a correct base directory, that is, a
+directory containing a correct @code{Makefile}, to be determined.
+
+As obtaining the project include directories might be a costly operation, its
+return value is cached in the hash table. The cache is cleared in the beginning
+of every syntax check attempt.
+
+@node Locating the buildfile
+@section Locating the buildfile
+@cindex Locating the buildfile
+@cindex buildfile, locating
+@cindex Makefile, locating
+
+Flymake can be configured to use different tools for performing syntax
+checks. For example, it can use direct compiler call to syntax check a perl
+script or a call to @code{make} for a more complicated case of a
+@code{C/C++} source. The general idea is that simple files, like perl
+scripts and html pages, can be checked by directly invoking a
+corresponding tool. Files that are usually more complex and generally
+used as part of larger projects, might require non-trivial options to
+be passed to the syntax check tool, like include directories for
+C++. The latter files are syntax checked using some build tool, like
+@code{make} or @code{Ant}.
+
+All @code{make} configuration data is usually stored in a file called
+@code{Makefile}. To allow for future extensions, flymake uses a notion of
+buildfile to reference the 'project configuration' file.
+
+Special function, @code{flymake-find-buildfile} is provided for locating buildfiles.
+Searching for a buildfile is done in a manner similar to that of searching
+for possible master files. A customizable variable
+@code{flymake-buildfile-dirs} holds a list of relative paths to the
+buildfile. They are checked sequentially until a buildfile is found. In case
+there's no build file, syntax check is aborted.
+
+Buildfile values are also cached.
+
+@node Starting the syntax check process
+@section Starting the syntax check process
+@cindex Syntax check process
+
+The command line (command name and the list of arguments) for launching a process is returned by the
+initialization function. Flymake then just calls @code{start-process}
+to start an asynchronous process and configures process filter and
+sentinel which is used for processing the output of the syntax check
+tool.
+
+@node Parsing the output
+@section Parsing the output
+@cindex Parsing the output
+
+The output generated by the syntax check tool is parsed in the process
+filter/sentinel using the error message patterns stored in the
+@code{flymake-err-line-patterns} variable. This variable contains a
+list of items of the form @code{(regexp file-idx line-idx
+err-text-idx)}, used to determine whether a particular line is an
+error message and extract file name, line number and error text,
+respectively. Error type (error/warning) is also guessed by matching
+error text with the '@code{^[wW]arning}' pattern. Anything that was not
+classified as a warning is considered an error. Type is then used to
+sort error menu items, which shows error messages first.
+
+Flymake is also able to interpret error message patterns missing err-text-idx
+information. This is done by merely taking the rest of the matched line
+(@code{(substring line (match-end 0))}) as error text. This trick allows
+to make use of a huge collection of error message line patterns from
+@code{compile.el}. All these error patterns are appended to
+the end of @code{flymake-err-line-patterns}.
+
+The error information obtained is saved in a buffer local
+variable. The buffer for which the process output belongs is
+determined from the process-id@w{}->@w{}buffer mapping updated
+after every process launch/exit.
+
+@node Highlighting erroneous lines
+@section Highlighting erroneous lines
+@cindex Erroneous lines, faces
+
+Highlighting is implemented with overlays and happens in the process
+sentinel, after calling the cleanup function. Two customizable faces
+are used: @code{flymake-errline-face} and
+@code{flymake-warnline-face}. Errors belonging outside the current
+buffer are considered to belong to line 1 of the current buffer.
+
+@node Interaction with other modes
+@section Interaction with other modes
+@cindex Interaction with other modes
+@cindex Interaction with compile mode
+
+The only mode flymake currently knows about is @code{compile}.
+
+Flymake can be configured to not start syntax check if it thinks the
+compilation is in progress. The check is made by the
+@code{flymake-compilation-is-running}, which tests the
+@code{compilation-in-progress} variable. The reason why this might be
+useful is saving CPU time in case both syntax check and compilation
+are very CPU intensive. The original reason for adding this feature,
+though, was working around a locking problem with MS Visual C++ compiler.
+
+Flymake also provides an alternative command for starting compilation,
+@code{flymake-compile}:
+
+@lisp
+(defun flymake-compile ()
+ "Kill all flymake syntax checks then start compilation."
+ (interactive)
+ (flymake-stop-all-syntax-checks)
+ (call-interactively 'compile))
+@end lisp
+
+It just kills all the active syntax check processes before calling
+@code{compile}.
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@bye
+
+@ignore
+ arch-tag: 9f0db077-5598-49ab-90b9-8df9248a63ec
+@end ignore
--- /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.)
+
+@copying
+This file documents Forms mode, a form-editing major mode for GNU Emacs.
+
+Copyright @copyright{} 1989, 1997, 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Forms: (forms). Emacs package for editing data bases
+ by filling in forms.
+@end direntry
+
+@titlepage
+@sp 6
+@center @titlefont{Forms Mode User's Manual}
+@sp 4
+@center Forms-Mode version 2
+@sp 1
+@center for GNU Emacs 22.1
+@sp 1
+@center April 2007
+@sp 5
+@center Johan Vromans
+@center @i{jvromans@@squirrel.nl}
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnottex
+@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.
+* GNU Free Documentation License:: The license for this documentation.
+* Credits:: Thanks everyone.
+* Index:: Index to this manual.
+@end menu
+@end ifnottex
+
+@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 favorite 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 GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index
+@unnumbered Index
+@printindex cp
+
+@contents
+@bye
+
+@ignore
+ arch-tag: 2ac9810b-aa49-4ea6-8030-d7f1ecd467ed
+@end ignore
--- /dev/null
+@c \input texinfo @c -*-texinfo-*-
+@c Uncomment 1st line before texing this file alone.
+@c %**start of header
+@c Copyright (C) 1995, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c
+@c Do not modify this file, it was generated from gnus-faq.xml, available from
+@c <URL:http://my.gnus.org/FAQ/>.
+@c
+@setfilename gnus-faq.info
+@settitle Frequently Asked Questions
+@c %**end of header
+@c
+
+@node Frequently Asked Questions
+@section Frequently Asked Questions
+
+@menu
+* FAQ - Changes::
+* FAQ - Introduction:: About Gnus and this FAQ.
+* FAQ 1 - Installation FAQ:: Installation of Gnus.
+* FAQ 2 - Startup / Group buffer:: Start up questions and the
+ first buffer Gnus shows you.
+* FAQ 3 - Getting Messages:: Making Gnus read your mail
+ and news.
+* FAQ 4 - Reading messages:: How to efficiently read
+ messages.
+* FAQ 5 - Composing messages:: Composing mails or Usenet
+ postings.
+* FAQ 6 - Old messages:: Importing, archiving,
+ searching and deleting messages.
+* FAQ 7 - Gnus in a dial-up environment:: Reading mail and news while
+ offline.
+* FAQ 8 - Getting help:: When this FAQ isn't enough.
+* FAQ 9 - Tuning Gnus:: How to make Gnus faster.
+* FAQ - Glossary:: Terms used in the FAQ
+ explained.
+@end menu
+
+@subheading Abstract
+
+This is the new Gnus Frequently Asked Questions list.
+If you have a Web browser, the official hypertext version is at
+@uref{http://my.gnus.org/FAQ/},
+the Docbook source is available from
+@uref{http://sourceforge.net/projects/gnus/, http://sourceforge.net}.
+
+Please submit features and suggestions to the
+@email{faq-discuss@@my.gnus.org, FAQ discussion list}.
+The list is protected against junk mail with
+@uref{http://smarden.org/qconfirm/index.html, qconfirm}. As
+a subscriber, your submissions will automatically pass. You can
+also subscribe to the list by sending a blank email to
+@email{faq-discuss-subscribe@@my.gnus.org, faq-discuss-subscribe@@my.gnus.org}
+and @uref{http://mail1.kens.com/cgi-bin/ezmlm-browse?command=monthbythread%26list=faq-discuss, browse
+the archive (BROKEN)}.
+
+@node FAQ - Changes
+@subheading Changes
+
+
+
+@itemize @bullet
+
+@item
+Updated FAQ to reflect release of Gnus 5.10 and start of
+No Gnus development.
+@end itemize
+
+@node FAQ - Introduction
+@subheading Introduction
+
+This is the Gnus Frequently Asked Questions list.
+
+Gnus is a Usenet Newsreader and Electronic Mail User Agent implemented
+as a part of Emacs. It's been around in some form for almost a decade
+now, and has been distributed as a standard part of Emacs for much of
+that time. Gnus 5 is the latest (and greatest) incarnation. The
+original version was called GNUS, and was written by Masanobu UMEDA.
+When autumn crept up in '94, Lars Magne Ingebrigtsen grew bored and
+decided to rewrite Gnus.
+
+Its biggest strength is the fact that it is extremely
+customizable. It is somewhat intimidating at first glance, but
+most of the complexity can be ignored until you're ready to take
+advantage of it. If you receive a reasonable volume of e-mail
+(you're on various mailing lists), or you would like to read
+high-volume mailing lists but cannot keep up with them, or read
+high volume newsgroups or are just bored, then Gnus is what you
+want.
+
+This FAQ was maintained by Justin Sheehy until March 2002. He
+would like to thank Steve Baur and Per Abrahamsen for doing a wonderful
+job with this FAQ before him. We would like to do the same - thanks,
+Justin!
+
+If you have a Web browser, the official hypertext version is at:
+@uref{http://my.gnus.org/FAQ/}.
+This version is much nicer than the unofficial hypertext
+versions that are archived at Utrecht, Oxford, Smart Pages, Ohio
+State, and other FAQ archives. See the resources question below
+if you want information on obtaining it in another format.
+
+The information contained here was compiled with the assistance
+of the Gnus development mailing list, and any errors or
+misprints are the my.gnus.org team's fault, sorry.
+
+@node FAQ 1 - Installation FAQ
+@subsection Installation FAQ
+
+@menu
+* [1.1]:: What is the latest version of Gnus?
+* [1.2]:: What's new in 5.10?
+* [1.3]:: Where and how to get Gnus?
+* [1.4]:: What to do with the tarball now?
+* [1.5]:: I sometimes read references to No Gnus and Oort Gnus, what
+ are those?
+* [1.6]:: Which version of Emacs do I need?
+* [1.7]:: How do I run Gnus on both Emacs and XEmacs?
+@end menu
+
+@node [1.1]
+@subsubheading Question 1.1
+
+What is the latest version of Gnus?
+
+@subsubheading Answer
+
+Jingle please: Gnus 5.10 is released, get it while it's
+hot! As well as the step in version number is rather
+small, Gnus 5.10 has tons of new features which you
+shouldn't miss. The current release (5.10.8) should be at
+least as stable as the latest release of the 5.8 series.
+
+@node [1.2]
+@subsubheading Question 1.2
+
+What's new in 5.10?
+
+@subsubheading Answer
+
+First of all, you should have a look into the file
+GNUS-NEWS in the toplevel directory of the Gnus tarball,
+there the most important changes are listed. Here's a
+short list of the changes I find especially
+important/interesting:
+
+@itemize @bullet
+
+@item
+Major rewrite of the Gnus agent, Gnus agent is now
+active by default.
+
+@item
+Many new article washing functions for dealing with
+ugly formatted articles.
+
+@item
+Anti Spam features.
+
+@item
+Message-utils now included in Gnus.
+
+@item
+New format specifiers for summary lines, e.g. %B for
+a complex trn-style thread tree.
+@end itemize
+
+@node [1.3]
+@subsubheading Question 1.3
+
+Where and how to get Gnus?
+
+@subsubheading Answer
+
+Gnus is released independent from releases of Emacs and XEmacs.
+Therefore, the version bundled with Emacs or the version in XEmacs'
+package system might not be up to date (e.g. Gnus 5.9 bundled with Emacs
+20 is outdated).
+@c
+You can get the latest released version of Gnus from
+@uref{http://www.gnus.org/dist/gnus.tar.gz} or via anonymous FTP from
+@uref{ftp://ftp.gnus.org/pub/gnus/gnus.tar.gz}.
+
+@node [1.4]
+@subsubheading Question 1.4
+
+What to do with the tarball now?
+
+@subsubheading Answer
+
+Untar it via @samp{tar xvzf gnus.tar.gz} and do the common
+@samp{./configure; make; make install} circle.
+(under MS-Windows either get the Cygwin environment from
+@uref{http://www.cygwin.com}
+which allows you to do what's described above or unpack the
+tarball with some packer (e.g. Winace from
+@uref{http://www.winace.com})
+and use the batch-file make.bat included in the tarball to install
+Gnus.) If you don't want to (or aren't allowed to) install Gnus
+system-wide, you can install it in your home directory and add the
+following lines to your ~/.xemacs/init.el or ~/.emacs:
+
+@example
+(add-to-list 'load-path "/path/to/gnus/lisp")
+(if (featurep 'xemacs)
+ (add-to-list 'Info-directory-list "/path/to/gnus/texi/")
+ (add-to-list 'Info-default-directory-list "/path/to/gnus/texi/"))
+@end example
+@noindent
+
+Make sure that you don't have any Gnus related stuff
+before this line, on MS Windows use something like
+"C:/path/to/lisp" (yes, "/").
+
+@node [1.5]
+@subsubheading Question 1.5
+
+I sometimes read references to No Gnus and Oort Gnus,
+what are those?
+
+@subsubheading Answer
+
+Oort Gnus was the name of the development version of
+Gnus, which became Gnus 5.10 in autumn 2003. No Gnus is
+the name of the current development version which will
+once become Gnus 5.12 or Gnus 6. (If you're wondering why
+not 5.11, the odd version numbers are normally used for
+the Gnus versions bundled with Emacs)
+
+@node [1.6]
+@subsubheading Question 1.6
+
+Which version of Emacs do I need?
+
+@subsubheading Answer
+
+Gnus 5.10 requires an Emacs version that is greater than or equal
+to Emacs 20.7 or XEmacs 21.1.
+The development versions of Gnus (aka No Gnus) requires Emacs 21
+or XEmacs 21.4.
+
+@node [1.7]
+@subsubheading Question 1.7
+
+How do I run Gnus on both Emacs and XEmacs?
+
+@subsubheading Answer
+
+You can't use the same copy of Gnus in both as the Lisp
+files are byte-compiled to a format which is different
+depending on which Emacs did the compilation. Get one copy
+of Gnus for Emacs and one for XEmacs.
+
+@node FAQ 2 - Startup / Group buffer
+@subsection Startup / Group buffer
+
+@menu
+* [2.1]:: Every time I start Gnus I get a message "Gnus auto-save
+ file exists. Do you want to read it?", what does this mean and
+ how to prevent it?
+* [2.2]:: Gnus doesn't remember which groups I'm subscribed to,
+ what's this?
+* [2.3]:: How to change the format of the lines in Group buffer?
+* [2.4]:: My group buffer becomes a bit crowded, is there a way to
+ sort my groups into categories so I can easier browse through
+ them?
+* [2.5]:: How to manually sort the groups in Group buffer? How to
+ sort the groups in a topic?
+@end menu
+
+@node [2.1]
+@subsubheading Question 2.1
+
+Every time I start Gnus I get a message "Gnus auto-save
+file exists. Do you want to read it?", what does this mean
+and how to prevent it?
+
+@subsubheading Answer
+
+This message means that the last time you used Gnus, it
+wasn't properly exited and therefor couldn't write its
+informations to disk (e.g. which messages you read), you
+are now asked if you want to restore those informations
+from the auto-save file.
+
+To prevent this message make sure you exit Gnus
+via @samp{q} in group buffer instead of
+just killing Emacs.
+
+@node [2.2]
+@subsubheading Question 2.2
+
+Gnus doesn't remember which groups I'm subscribed to,
+what's this?
+
+@subsubheading Answer
+
+You get the message described in the q/a pair above while
+starting Gnus, right? It's an other symptom for the same
+problem, so read the answer above.
+
+@node [2.3]
+@subsubheading Question 2.3
+
+How to change the format of the lines in Group buffer?
+
+@subsubheading Answer
+
+You've got to tweak the value of the variable
+gnus-group-line-format. See the manual node "Group Line
+Specification" for information on how to do this. An
+example for this (guess from whose .gnus :-)):
+
+@example
+(setq gnus-group-line-format "%P%M%S[%5t]%5y : %(%g%)\n")
+@end example
+@noindent
+
+@node [2.4]
+@subsubheading Question 2.4
+
+My group buffer becomes a bit crowded, is there a way to
+sort my groups into categories so I can easier browse
+through them?
+
+@subsubheading Answer
+
+Gnus offers the topic mode, it allows you to sort your
+groups in, well, topics, e.g. all groups dealing with
+Linux under the topic linux, all dealing with music under
+the topic music and all dealing with scottish music under
+the topic scottish which is a subtopic of music.
+
+To enter topic mode, just hit t while in Group buffer. Now
+you can use @samp{T n} to create a topic
+at point and @samp{T m} to move a group to
+a specific topic. For more commands see the manual or the
+menu. You might want to include the %P specifier at the
+beginning of your gnus-group-line-format variable to have
+the groups nicely indented.
+
+@node [2.5]
+@subsubheading Question 2.5
+
+How to manually sort the groups in Group buffer? How to
+sort the groups in a topic?
+
+@subsubheading Answer
+
+Move point over the group you want to move and
+hit @samp{C-k}, now move point to the
+place where you want the group to be and
+hit @samp{C-y}.
+
+@node FAQ 3 - Getting Messages
+@subsection Getting Messages
+
+@menu
+* [3.1]:: I just installed Gnus, started it via @samp{M-x gnus}
+ but it only says "nntp (news) open error", what to do?
+* [3.2]:: I'm working under Windows and have no idea what ~/.gnus.el
+ means.
+* [3.3]:: My news server requires authentication, how to store user
+ name and password on disk?
+* [3.4]:: Gnus seems to start up OK, but I can't find out how to
+ subscribe to a group.
+* [3.5]:: Gnus doesn't show all groups / Gnus says I'm not allowed
+ to post on this server as well as I am, what's that?
+* [3.6]:: I want Gnus to fetch news from several servers, is this
+ possible?
+* [3.7]:: And how about local spool files?
+* [3.8]:: OK, reading news works now, but I want to be able to read
+ my mail with Gnus, too. How to do it?
+* [3.9]:: And what about IMAP?
+* [3.10]:: At the office we use one of those MS Exchange servers, can
+ I use Gnus to read my mail from it?
+* [3.11]:: Can I tell Gnus not to delete the mails on the server it
+ retrieves via POP3?
+@end menu
+
+@node [3.1]
+@subsubheading Question 3.1
+
+I just installed Gnus, started it via
+@samp{M-x gnus}
+but it only says "nntp (news) open error", what to do?
+
+@subsubheading Answer
+
+You've got to tell Gnus where to fetch the news from. Read
+the documentation for information on how to do this. As a
+first start, put those lines in ~/.gnus.el:
+
+@example
+(setq gnus-select-method '(nntp "news.yourprovider.net"))
+(setq user-mail-address "you@@yourprovider.net")
+(setq user-full-name "Your Name")
+@end example
+@noindent
+
+@node [3.2]
+@subsubheading Question 3.2
+
+I'm working under Windows and have no idea what ~/.gnus.el means.
+
+@subsubheading Answer
+
+The ~/ means the home directory where Gnus and Emacs look
+for the configuration files. However, you don't really
+need to know what this means, it suffices that Emacs knows
+what it means :-) You can type
+@samp{C-x C-f ~/.gnus.el RET }
+(yes, with the forward slash, even on Windows), and
+Emacs will open the right file for you. (It will most
+likely be new, and thus empty.)
+However, I'd discourage you from doing so, since the
+directory Emacs chooses will most certainly not be what
+you want, so let's do it the correct way.
+The first thing you've got to do is to
+create a suitable directory (no blanks in directory name
+please) e.g. c:\myhome. Then you must set the environment
+variable HOME to this directory. To do this under Win9x
+or Me include the line
+
+@example
+SET HOME=C:\myhome
+@end example
+@noindent
+
+in your autoexec.bat and reboot. Under NT, 2000 and XP, hit
+Winkey+Pause/Break to enter system options (if it doesn't work, go to
+Control Panel -> System -> Advanced). There you'll find the possibility
+to set environment variables. Create a new one with name HOME and value
+C:\myhome. Rebooting is not necessary.
+
+Now to create ~/.gnus.el, say
+@samp{C-x C-f ~/.gnus.el RET C-x C-s}.
+in Emacs.
+
+@node [3.3]
+@subsubheading Question 3.3
+
+My news server requires authentication, how to store
+user name and password on disk?
+
+@subsubheading Answer
+
+Create a file ~/.authinfo which includes for each server a line like this
+
+@example
+machine news.yourprovider.net login YourUserName password YourPassword
+@end example
+@noindent
+.
+Make sure that the file isn't readable to others if you
+work on a OS which is capable of doing so. (Under Unix
+say
+@example
+chmod 600 ~/.authinfo
+@end example
+@noindent
+
+in a shell.)
+
+@node [3.4]
+@subsubheading Question 3.4
+
+Gnus seems to start up OK, but I can't find out how to
+subscribe to a group.
+
+@subsubheading Answer
+
+If you know the name of the group say @samp{U
+name.of.group RET} in group buffer (use the
+tab-completion Luke). Otherwise hit ^ in group buffer,
+this brings you to the server buffer. Now place point (the
+cursor) over the server which carries the group you want,
+hit @samp{RET}, move point to the group
+you want to subscribe to and say @samp{u}
+to subscribe to it.
+
+@node [3.5]
+@subsubheading Question 3.5
+
+Gnus doesn't show all groups / Gnus says I'm not allowed to
+post on this server as well as I am, what's that?
+
+@subsubheading Answer
+
+Some providers allow restricted anonymous access and full
+access only after authorization. To make Gnus send authinfo
+to those servers append
+
+@example
+force yes
+@end example
+@noindent
+
+to the line for those servers in ~/.authinfo.
+
+@node [3.6]
+@subsubheading Question 3.6
+
+I want Gnus to fetch news from several servers, is this possible?
+
+@subsubheading Answer
+
+Of course. You can specify more sources for articles in the
+variable gnus-secondary-select-methods. Add something like
+this in ~/.gnus.el:
+
+@example
+(add-to-list 'gnus-secondary-select-methods
+ '(nntp "news.yourSecondProvider.net"))
+(add-to-list 'gnus-secondary-select-methods
+ '(nntp "news.yourThirdProvider.net"))
+@end example
+@noindent
+
+@node [3.7]
+@subsubheading Question 3.7
+
+And how about local spool files?
+
+@subsubheading Answer
+
+No problem, this is just one more select method called
+nnspool, so you want this:
+
+@example
+(add-to-list 'gnus-secondary-select-methods '(nnspool ""))
+@end example
+@noindent
+
+Or this if you don't want an NNTP Server as primary news source:
+
+@example
+(setq gnus-select-method '(nnspool ""))
+@end example
+@noindent
+
+Gnus will look for the spool file in /usr/spool/news, if you
+want something different, change the line above to something like this:
+
+@example
+(add-to-list 'gnus-secondary-select-methods
+ '(nnspool ""
+ (nnspool-directory "/usr/local/myspoolddir")))
+@end example
+@noindent
+
+This sets the spool directory for this server only.
+You might have to specify more stuff like the program used
+to post articles, see the Gnus manual on how to do this.
+
+@node [3.8]
+@subsubheading Question 3.8
+
+OK, reading news works now, but I want to be able to read my mail
+with Gnus, too. How to do it?
+
+@subsubheading Answer
+
+That's a bit harder since there are many possible sources
+for mail, many possible ways for storing mail and many
+different ways for sending mail. The most common cases are
+these: 1: You want to read your mail from a pop3 server and
+send them directly to a SMTP Server 2: Some program like
+fetchmail retrieves your mail and stores it on disk from
+where Gnus shall read it. Outgoing mail is sent by
+Sendmail, Postfix or some other MTA. Sometimes, you even
+need a combination of the above cases.
+
+However, the first thing to do is to tell Gnus in which way
+it should store the mail, in Gnus terminology which back end
+to use. Gnus supports many different back ends, the most
+commonly used one is nnml. It stores every mail in one file
+and is therefor quite fast. However you might prefer a one
+file per group approach if your file system has problems with
+many small files, the nnfolder back end is then probably the
+choice for you. To use nnml add the following to ~/.gnus.el:
+
+@example
+(add-to-list 'gnus-secondary-select-methods '(nnml ""))
+@end example
+@noindent
+
+As you might have guessed, if you want nnfolder, it's
+
+@example
+(add-to-list 'gnus-secondary-select-methods '(nnfolder ""))
+@end example
+@noindent
+
+Now we need to tell Gnus, where to get it's mail from. If
+it's a POP3 server, then you need something like this:
+
+@example
+(eval-after-load "mail-source"
+ '(add-to-list 'mail-sources '(pop :server "pop.YourProvider.net"
+ :user "yourUserName"
+ :password "yourPassword")))
+@end example
+@noindent
+
+Make sure ~/.gnus.el isn't readable to others if you store
+your password there. If you want to read your mail from a
+traditional spool file on your local machine, it's
+
+@example
+(eval-after-load "mail-source"
+ '(add-to-list 'mail-sources '(file :path "/path/to/spool/file"))
+@end example
+@noindent
+
+If it's a Maildir, with one file per message as used by
+postfix, Qmail and (optionally) fetchmail it's
+
+@example
+(eval-after-load "mail-source"
+ '(add-to-list 'mail-sources '(maildir :path "/path/to/Maildir/"
+ :subdirs ("cur" "new")))
+@end example
+@noindent
+
+And finally if you want to read your mail from several files
+in one directory, for example because procmail already split your
+mail, it's
+
+@example
+(eval-after-load "mail-source"
+ '(add-to-list 'mail-sources
+ '(directory :path "/path/to/procmail-dir/"
+ :suffix ".prcml")))
+@end example
+@noindent
+
+Where :suffix ".prcml" tells Gnus only to use files with the
+suffix .prcml.
+
+OK, now you only need to tell Gnus how to send mail. If you
+want to send mail via sendmail (or whichever MTA is playing
+the role of sendmail on your system), you don't need to do
+anything. However, if you want to send your mail to an
+SMTP Server you need the following in your ~/.gnus.el
+
+@example
+(setq send-mail-function 'smtpmail-send-it)
+(setq message-send-mail-function 'smtpmail-send-it)
+(setq smtpmail-default-smtp-server "smtp.yourProvider.net")
+@end example
+@noindent
+
+@node [3.9]
+@subsubheading Question 3.9
+
+And what about IMAP?
+
+@subsubheading Answer
+
+There are two ways of using IMAP with Gnus. The first one is
+to use IMAP like POP3, that means Gnus fetches the mail from
+the IMAP server and stores it on disk. If you want to do
+this (you don't really want to do this) add the following to
+~/.gnus.el
+
+@example
+(add-to-list 'mail-sources '(imap :server "mail.mycorp.com"
+ :user "username"
+ :pass "password"
+ :stream network
+ :authentication login
+ :mailbox "INBOX"
+ :fetchflag "\\Seen"))
+@end example
+@noindent
+
+You might have to tweak the values for stream and/or
+authentication, see the Gnus manual node "Mail Source
+Specifiers" for possible values.
+
+If you want to use IMAP the way it's intended, you've got to
+follow a different approach. You've got to add the nnimap
+back end to your select method and give the information
+about the server there.
+
+@example
+(add-to-list 'gnus-secondary-select-methods
+ '(nnimap "Give the baby a name"
+ (nnimap-address "imap.yourProvider.net")
+ (nnimap-port 143)
+ (nnimap-list-pattern "archive.*")))
+@end example
+@noindent
+
+Again, you might have to specify how to authenticate to the
+server if Gnus can't guess the correct way, see the Manual
+Node "IMAP" for detailed information.
+
+@node [3.10]
+@subsubheading Question 3.10
+
+At the office we use one of those MS Exchange servers, can I use
+Gnus to read my mail from it?
+
+@subsubheading Answer
+
+Offer your administrator a pair of new running shoes for
+activating IMAP on the server and follow the instructions
+above.
+
+@node [3.11]
+@subsubheading Question 3.11
+
+Can I tell Gnus not to delete the mails on the server it
+retrieves via POP3?
+
+@subsubheading Answer
+
+First of all, that's not the way POP3 is intended to work,
+if you have the possibility, you should use the IMAP
+Protocol if you want your messages to stay on the
+server. Nevertheless there might be situations where you
+need the feature, but sadly Gnus itself has no predefined
+functionality to do so.
+
+However this is Gnus county so there are possibilities to
+achieve what you want. The easiest way is to get an external
+program which retrieves copies of the mail and stores them
+on disk, so Gnus can read it from there. On Unix systems you
+could use e.g. fetchmail for this, on MS Windows you can use
+Hamster, an excellent local news and mail server.
+
+The other solution would be, to replace the method Gnus
+uses to get mail from POP3 servers by one which is capable
+of leaving the mail on the server. If you use XEmacs, get
+the package mail-lib, it includes an enhanced pop3.el,
+look in the file, there's documentation on how to tell
+Gnus to use it and not to delete the retrieved mail. For
+GNU Emacs look for the file epop3.el which can do the same
+(If you know the home of this file, please send me an
+e-mail). You can also tell Gnus to use an external program
+(e.g. fetchmail) to fetch your mail, see the info node
+"Mail Source Specifiers" in the Gnus manual on how to do
+it.
+
+@node FAQ 4 - Reading messages
+@subsection Reading messages
+
+@menu
+* [4.1]:: When I enter a group, all read messages are gone. How to
+ view them again?
+* [4.2]:: How to tell Gnus to show an important message every time I
+ enter a group, even when it's read?
+* [4.3]:: How to view the headers of a message?
+* [4.4]:: How to view the raw unformatted message?
+* [4.5]:: How can I change the headers Gnus displays by default at
+ the top of the article buffer?
+* [4.6]:: I'd like Gnus NOT to render HTML-mails but show me the
+ text part if it's available. How to do it?
+* [4.7]:: Can I use some other browser than w3 to render my
+ HTML-mails?
+* [4.8]:: Is there anything I can do to make poorly formatted mails
+ more readable?
+* [4.9]:: Is there a way to automatically ignore posts by specific
+ authors or with specific words in the subject? And can I highlight
+ more interesting ones in some way?
+* [4.10]:: How can I disable threading in some (e.g. mail-) groups,
+ or set other variables specific for some groups?
+* [4.11]:: Can I highlight messages written by me and follow-ups to
+ those?
+* [4.12]:: The number of total messages in a group which Gnus
+ displays in group buffer is by far to high, especially in mail
+ groups. Is this a bug?
+* [4.13]:: I don't like the layout of summary and article buffer, how
+ to change it? Perhaps even a three pane display?
+* [4.14]:: I don't like the way the Summary buffer looks, how to
+ tweak it?
+* [4.15]:: How to split incoming mails in several groups?
+@end menu
+
+@node [4.1]
+@subsubheading Question 4.1
+
+When I enter a group, all read messages are gone. How to view them again?
+
+@subsubheading Answer
+
+If you enter the group by saying
+@samp{RET}
+in group buffer with point over the group, only unread and ticked messages are loaded. Say
+@samp{C-u RET}
+instead to load all available messages. If you want only the e.g. 300 newest say
+@samp{C-u 300 RET}
+
+Loading only unread messages can be annoying if you have threaded view enabled, say
+
+@example
+(setq gnus-fetch-old-headers 'some)
+@end example
+@noindent
+
+in ~/.gnus.el to load enough old articles to prevent teared threads, replace 'some with t to load
+all articles (Warning: Both settings enlarge the amount of data which is
+fetched when you enter a group and slow down the process of entering a group).
+
+If you already use Gnus 5.10, you can say
+@samp{/o N}
+In summary buffer to load the last N messages, this feature is not available in 5.8.8
+
+If you don't want all old messages, but the parent of the message you're just reading,
+you can say @samp{^}, if you want to retrieve the whole thread
+the message you're just reading belongs to, @samp{A T} is your friend.
+
+@node [4.2]
+@subsubheading Question 4.2
+
+How to tell Gnus to show an important message every time I
+enter a group, even when it's read?
+
+@subsubheading Answer
+
+You can tick important messages. To do this hit
+@samp{u} while point is in summary buffer
+over the message. When you want to remove the mark, hit
+either @samp{d} (this deletes the tick
+mark and set's unread mark) or @samp{M c}
+(which deletes all marks for the message).
+
+@node [4.3]
+@subsubheading Question 4.3
+
+How to view the headers of a message?
+
+@subsubheading Answer
+
+Say @samp{t}
+to show all headers, one more
+@samp{t}
+hides them again.
+
+@node [4.4]
+@subsubheading Question 4.4
+
+How to view the raw unformatted message?
+
+@subsubheading Answer
+
+Say
+@samp{C-u g}
+to show the raw message
+@samp{g}
+returns to normal view.
+
+@node [4.5]
+@subsubheading Question 4.5
+
+How can I change the headers Gnus displays by default at
+the top of the article buffer?
+
+@subsubheading Answer
+
+The variable gnus-visible-headers controls which headers
+are shown, its value is a regular expression, header lines
+which match it are shown. So if you want author, subject,
+date, and if the header exists, Followup-To and MUA / NUA
+say this in ~/.gnus.el:
+
+@example
+(setq gnus-visible-headers
+ '("^From" "^Subject" "^Date" "^Newsgroups" "^Followup-To"
+ "^User-Agent" "^X-Newsreader" "^X-Mailer"))
+@end example
+@noindent
+
+@node [4.6]
+@subsubheading Question 4.6
+
+I'd like Gnus NOT to render HTML-mails but show me the
+text part if it's available. How to do it?
+
+@subsubheading Answer
+
+Say
+
+@example
+(eval-after-load "mm-decode"
+ '(progn
+ (add-to-list 'mm-discouraged-alternatives "text/html")
+ (add-to-list 'mm-discouraged-alternatives "text/richtext")))
+@end example
+@noindent
+
+in ~/.gnus.el. If you don't want HTML rendered, even if there's no text alternative add
+
+@example
+(setq mm-automatic-display (remove "text/html" mm-automatic-display))
+@end example
+@noindent
+
+too.
+
+@node [4.7]
+@subsubheading Question 4.7
+
+Can I use some other browser than w3 to render my HTML-mails?
+
+@subsubheading Answer
+
+Only if you use Gnus 5.10 or younger. In this case you've got the
+choice between w3, w3m, links, lynx and html2text, which
+one is used can be specified in the variable
+mm-text-html-renderer, so if you want links to render your
+mail say
+
+@example
+(setq mm-text-html-renderer 'links)
+@end example
+@noindent
+
+@node [4.8]
+@subsubheading Question 4.8
+
+Is there anything I can do to make poorly formatted mails
+more readable?
+
+@subsubheading Answer
+
+Gnus offers you several functions to "wash" incoming mail, you can
+find them if you browse through the menu, item
+Article->Washing. The most interesting ones are probably "Wrap
+long lines" (@samp{W w}), "Decode ROT13"
+(@samp{W r}) and "Outlook Deuglify" which repairs
+the dumb quoting used by many users of Microsoft products
+(@samp{W Y f} gives you full deuglify.
+See @samp{W Y C-h} or have a look at the menus for
+other deuglifications). Outlook deuglify is only available since
+Gnus 5.10.
+
+@node [4.9]
+@subsubheading Question 4.9
+
+Is there a way to automatically ignore posts by specific
+authors or with specific words in the subject? And can I
+highlight more interesting ones in some way?
+
+@subsubheading Answer
+
+You want Scoring. Scoring means, that you define rules
+which assign each message an integer value. Depending on
+the value the message is highlighted in summary buffer (if
+it's high, say +2000) or automatically marked read (if the
+value is low, say -800) or some other action happens.
+
+There are basically three ways of setting up rules which assign
+the scoring-value to messages. The first and easiest way is to set
+up rules based on the article you are just reading. Say you're
+reading a message by a guy who always writes nonsense and you want
+to ignore his messages in the future. Hit
+@samp{L}, to set up a rule which lowers the score.
+Now Gnus asks you which the criteria for lowering the Score shall
+be. Hit @samp{?} twice to see all possibilities,
+we want @samp{a} which means the author (the from
+header). Now Gnus wants to know which kind of matching we want.
+Hit either @samp{e} for an exact match or
+@samp{s} for substring-match and delete afterwards
+everything but the name to score down all authors with the given
+name no matter which email address is used. Now you need to tell
+Gnus when to apply the rule and how long it should last, hit e.g.
+@samp{p} to apply the rule now and let it last
+forever. If you want to raise the score instead of lowering it say
+@samp{I} instead of @samp{L}.
+
+You can also set up rules by hand. To do this say @samp{V
+f} in summary buffer. Then you are asked for the name
+of the score file, it's name.of.group.SCORE for rules valid in
+only one group or all.Score for rules valid in all groups. See the
+Gnus manual for the exact syntax, basically it's one big list
+whose elements are lists again. the first element of those lists
+is the header to score on, then one more list with what to match,
+which score to assign, when to expire the rule and how to do the
+matching. If you find me very interesting, you could e.g. add the
+following to your all.Score:
+
+@example
+(("references" ("hschmi22.userfqdn.rz-online.de" 500 nil s))
+ ("message-id" ("hschmi22.userfqdn.rz-online.de" 999 nil s)))
+@end example
+@noindent
+
+This would add 999 to the score of messages written by me
+and 500 to the score of messages which are a (possibly
+indirect) answer to a message written by me. Of course
+nobody with a sane mind would do this :-)
+
+The third alternative is adaptive scoring. This means Gnus
+watches you and tries to find out what you find
+interesting and what annoying and sets up rules
+which reflect this. Adaptive scoring can be a huge help
+when reading high traffic groups. If you want to activate
+adaptive scoring say
+
+@example
+(setq gnus-use-adaptive-scoring t)
+@end example
+@noindent
+
+in ~/.gnus.el.
+
+@node [4.10]
+@subsubheading Question 4.10
+
+How can I disable threading in some (e.g. mail-) groups, or
+set other variables specific for some groups?
+
+@subsubheading Answer
+
+While in group buffer move point over the group and hit
+@samp{G c}, this opens a buffer where you
+can set options for the group. At the bottom of the buffer
+you'll find an item that allows you to set variables
+locally for the group. To disable threading enter
+gnus-show-threads as name of variable and nil as
+value. Hit button done at the top of the buffer when
+you're ready.
+
+@node [4.11]
+@subsubheading Question 4.11
+
+Can I highlight messages written by me and follow-ups to
+those?
+
+@subsubheading Answer
+
+Stop those "Can I ..." questions, the answer is always yes
+in Gnus Country :-). It's a three step process: First we
+make faces (specifications of how summary-line shall look
+like) for those postings, then we'll give them some
+special score and finally we'll tell Gnus to use the new
+faces. You can find detailed instructions on how to do it on
+@uref{http://my.gnus.org/node/view/224, my.gnus.org}
+
+@node [4.12]
+@subsubheading Question 4.12
+
+The number of total messages in a group which Gnus
+displays in group buffer is by far to high, especially in
+mail groups. Is this a bug?
+
+@subsubheading Answer
+
+No, that's a matter of design of Gnus, fixing this would
+mean reimplementation of major parts of Gnus'
+back ends. Gnus thinks "highest-article-number -
+lowest-article-number = total-number-of-articles". This
+works OK for Usenet groups, but if you delete and move
+many messages in mail groups, this fails. To cure the
+symptom, enter the group via @samp{C-u RET}
+(this makes Gnus get all messages), then
+hit @samp{M P b} to mark all messages and
+then say @samp{B m name.of.group} to move
+all messages to the group they have been in before, they
+get new message numbers in this process and the count is
+right again (until you delete and move your mail to other
+groups again).
+
+@node [4.13]
+@subsubheading Question 4.13
+
+I don't like the layout of summary and article buffer, how
+to change it? Perhaps even a three pane display?
+
+@subsubheading Answer
+
+You can control the windows configuration by calling the
+function gnus-add-configuration. The syntax is a bit
+complicated but explained very well in the manual node
+"Window Layout". Some popular examples:
+
+Instead 25% summary 75% article buffer 35% summary and 65%
+article (the 1.0 for article means "take the remaining
+space"):
+
+@example
+(gnus-add-configuration
+ '(article (vertical 1.0 (summary .35 point) (article 1.0))))
+@end example
+@noindent
+
+A three pane layout, Group buffer on the left, summary
+buffer top-right, article buffer bottom-right:
+
+@example
+(gnus-add-configuration
+ '(article
+ (horizontal 1.0
+ (vertical 25
+ (group 1.0))
+ (vertical 1.0
+ (summary 0.25 point)
+ (article 1.0)))))
+(gnus-add-configuration
+ '(summary
+ (horizontal 1.0
+ (vertical 25
+ (group 1.0))
+ (vertical 1.0
+ (summary 1.0 point)))))
+@end example
+@noindent
+
+@node [4.14]
+@subsubheading Question 4.14
+
+I don't like the way the Summary buffer looks, how to tweak it?
+
+@subsubheading Answer
+
+You've got to play around with the variable
+gnus-summary-line-format. It's value is a string of
+symbols which stand for things like author, date, subject
+etc. A list of the available specifiers can be found in the
+manual node "Summary Buffer Lines" and the often forgotten
+node "Formatting Variables" and it's sub-nodes. There
+you'll find useful things like positioning the cursor and
+tabulators which allow you a summary in table form, but
+sadly hard tabulators are broken in 5.8.8.
+
+Since 5.10, Gnus offers you some very nice new specifiers,
+e.g. %B which draws a thread-tree and %&user-date which
+gives you a date where the details are dependent of the
+articles age. Here's an example which uses both:
+
+@example
+(setq gnus-summary-line-format ":%U%R %B %s %-60=|%4L |%-20,20f |%&user-date; \n")
+@end example
+@noindent
+
+resulting in:
+
+@example
+:O Re: [Richard Stallman] rfc2047.el | 13 |Lars Magne Ingebrigt |Sat 23:06
+:O Re: Revival of the ding-patches list | 13 |Lars Magne Ingebrigt |Sat 23:12
+:R > Re: Find correct list of articles for a gro| 25 |Lars Magne Ingebrigt |Sat 23:16
+:O \-> ... | 21 |Kai Grossjohann | 0:01
+:R > Re: Cry for help: deuglify.el - moving stuf| 28 |Lars Magne Ingebrigt |Sat 23:34
+:O \-> ... | 115 |Raymond Scholz | 1:24
+:O \-> ... | 19 |Lars Magne Ingebrigt |15:33
+:O Slow mailing list | 13 |Lars Magne Ingebrigt |Sat 23:49
+:O Re: `@@' mark not documented | 13 |Lars Magne Ingebrigt |Sat 23:50
+:R > Re: Gnus still doesn't count messages prope| 23 |Lars Magne Ingebrigt |Sat 23:57
+:O \-> ... | 18 |Kai Grossjohann | 0:35
+:O \-> ... | 13 |Lars Magne Ingebrigt | 0:56
+@end example
+@noindent
+
+@node [4.15]
+@subsubheading Question 4.15
+
+How to split incoming mails in several groups?
+
+@subsubheading Answer
+
+Gnus offers two possibilities for splitting mail, the easy
+nnmail-split-methods and the more powerful Fancy Mail
+Splitting. I'll only talk about the first one, refer to
+the manual, node "Fancy Mail Splitting" for the latter.
+
+The value of nnmail-split-methods is a list, each element
+is a list which stands for a splitting rule. Each rule has
+the form "group where matching articles should go to",
+"regular expression which has to be matched", the first
+rule which matches wins. The last rule must always be a
+general rule (regular expression .*) which denotes where
+articles should go which don't match any other rule. If
+the folder doesn't exist yet, it will be created as soon
+as an article lands there. By default the mail will be
+send to all groups whose rules match. If you
+don't want that (you probably don't want), say
+
+@example
+(setq nnmail-crosspost nil)
+@end example
+@noindent
+
+in ~/.gnus.el.
+
+An example might be better than thousand words, so here's
+my nnmail-split-methods. Note that I send duplicates in a
+special group and that the default group is spam, since I
+filter all mails out which are from some list I'm
+subscribed to or which are addressed directly to me
+before. Those rules kill about 80% of the Spam which
+reaches me (Email addresses are changed to prevent spammers
+from using them):
+
+@example
+(setq nnmail-split-methods
+ '(("duplicates" "^Gnus-Warning:.*duplicate")
+ ("XEmacs-NT" "^\\(To:\\|CC:\\).*localpart@@xemacs.invalid.*")
+ ("Gnus-Tut" "^\\(To:\\|CC:\\).*localpart@@socha.invalid.*")
+ ("tcsh" "^\\(To:\\|CC:\\).*localpart@@mx.gw.invalid.*")
+ ("BAfH" "^\\(To:\\|CC:\\).*localpart@@.*uni-muenchen.invalid.*")
+ ("Hamster-src" "^\\(CC:\\|To:\\).*hamster-sourcen@@yahoogroups.\\(de\\|com\\).*")
+ ("Tagesschau" "^From: tagesschau <localpart@@www.tagesschau.invalid>$")
+ ("Replies" "^\\(CC:\\|To:\\).*localpart@@Frank-Schmitt.invalid.*")
+ ("EK" "^From:.*\\(localpart@@privateprovider.invalid\\|localpart@@workplace.invalid\\).*")
+ ("Spam" "^Content-Type:.*\\(ks_c_5601-1987\\|EUC-KR\\|big5\\|iso-2022-jp\\).*")
+ ("Spam" "^Subject:.*\\(This really work\\|XINGA\\|ADV:\\|XXX\\|adult\\|sex\\).*")
+ ("Spam" "^Subject:.*\\(\=\?ks_c_5601-1987\?\\|\=\?euc-kr\?\\|\=\?big5\?\\).*")
+ ("Spam" "^X-Mailer:\\(.*BulkMailer.*\\|.*MIME::Lite.*\\|\\)")
+ ("Spam" "^X-Mailer:\\(.*CyberCreek Avalanche\\|.*http\:\/\/GetResponse\.com\\)")
+ ("Spam" "^From:.*\\(verizon\.net\\|prontomail\.com\\|money\\|ConsumerDirect\\).*")
+ ("Spam" "^Delivered-To: GMX delivery to spamtrap@@gmx.invalid$")
+ ("Spam" "^Received: from link2buy.com")
+ ("Spam" "^CC: .*azzrael@@t-online.invalid")
+ ("Spam" "^X-Mailer-Version: 1.50 BETA")
+ ("Uni" "^\\(CC:\\|To:\\).*localpart@@uni-koblenz.invalid.*")
+ ("Inbox" "^\\(CC:\\|To:\\).*\\(my\ name\\|address@@one.invalid\\|adress@@two.invalid\\)")
+ ("Spam" "")))
+@end example
+@noindent
+
+@node FAQ 5 - Composing messages
+@subsection Composing messages
+
+@menu
+* [5.1]:: What are the basic commands I need to know for sending
+ mail and postings?
+* [5.2]:: How to enable automatic word-wrap when composing messages?
+* [5.3]:: How to set stuff like From, Organization, Reply-To,
+ signature...?
+* [5.4]:: Can I set things like From, Signature etc group based on
+ the group I post too?
+* [5.5]:: Is there a spell-checker? Perhaps even on-the-fly
+ spell-checking?
+* [5.6]:: Can I set the dictionary based on the group I'm posting
+ to?
+* [5.7]:: Is there some kind of address-book, so I needn't remember
+ all those email addresses?
+* [5.8]:: Sometimes I see little images at the top of article
+ buffer. What's that and how can I send one with my postings, too?
+* [5.9]:: Sometimes I accidentally hit r instead of f in newsgroups.
+ Can Gnus warn me, when I'm replying by mail in newsgroups?
+* [5.10]:: How to tell Gnus not to generate a sender header?
+* [5.11]:: I want Gnus to locally store copies of my send mail and
+ news, how to do it?
+* [5.12]:: People tell me my Message-IDs are not correct, why aren't
+ they and how to fix it?
+@end menu
+
+@node [5.1]
+@subsubheading Question 5.1
+
+What are the basic commands I need to know for sending mail and postings?
+
+@subsubheading Answer
+
+To start composing a new mail hit @samp{m}
+either in Group or Summary buffer, for a posting, it's
+either @samp{a} in Group buffer and
+filling the Newsgroups header manually
+or @samp{a} in the Summary buffer of the
+group where the posting shall be send to. Replying by mail
+is
+@samp{r} if you don't want to cite the
+author, or import the cited text manually and
+@samp{R} to cite the text of the original
+message. For a follow up to a newsgroup, it's
+@samp{f} and @samp{F}
+(analogously to @samp{r} and
+@samp{R}).
+
+Enter new headers above the line saying "--text follows
+this line--", enter the text below the line. When ready
+hit @samp{C-c C-c}, to send the message,
+if you want to finish it later hit @samp{C-c
+C-d} to save it in the drafts group, where you
+can start editing it again by saying @samp{D
+e}.
+
+@node [5.2]
+@subsubheading Question 5.2
+
+How to enable automatic word-wrap when composing messages?
+
+@subsubheading Answer
+
+Say
+
+@example
+(add-hook 'message-mode-hook
+ (lambda ()
+ (setq fill-column 72)
+ (turn-on-auto-fill)))
+@end example
+@noindent
+
+in ~/.gnus.el. You can reformat a paragraph by hitting
+@samp{M-q} (as usual)
+
+@node [5.3]
+@subsubheading Question 5.3
+
+How to set stuff like From, Organization, Reply-To, signature...?
+
+@subsubheading Answer
+
+There are other ways, but you should use posting styles
+for this. (See below why).
+This example should make the syntax clear:
+
+@example
+(setq gnus-posting-styles
+ '((".*"
+ (name "Frank Schmitt")
+ (address "me@@there.invalid")
+ (organization "Hamme net, kren mer och nimmi")
+ (signature-file "~/.signature")
+ ("X-SampleHeader" "foobar")
+ (eval (setq some-variable "Foo bar")))))
+@end example
+@noindent
+
+The ".*" means that this settings are the default ones
+(see below), valid values for the first element of the
+following lists are signature, signature-file,
+organization, address, name or 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; if the value is `nil', the header
+name will be removed. You can also say (eval (foo bar)),
+then the function foo will be evaluated with argument bar
+and the result will be thrown away.
+
+@node [5.4]
+@subsubheading Question 5.4
+
+Can I set things like From, Signature etc group based on the group I post too?
+
+@subsubheading Answer
+
+That's the strength of posting styles. Before, we used ".*"
+to set the default for all groups. You can use a regexp
+like "^gmane" and the following settings are only applied
+to postings you send to the gmane hierarchy, use
+".*binaries" instead and they will be applied to postings
+send to groups containing the string binaries in their
+name etc.
+
+You can instead of specifying a regexp specify a function
+which is evaluated, only if it returns true, the
+corresponding settings take effect. Two interesting
+candidates for this are message-news-p which returns t if
+the current Group is a newsgroup and the corresponding
+message-mail-p.
+
+Note that all forms that match are applied, that means in
+the example below, when I post to
+gmane.mail.spam.spamassassin.general, the settings under
+".*" are applied and the settings under message-news-p and
+those under "^gmane" and those under
+"^gmane\\.mail\\.spam\\.spamassassin\\.general$". Because
+of this put general settings at the top and specific ones
+at the bottom.
+
+@example
+(setq gnus-posting-styles
+ '((".*" ;;default
+ (name "Frank Schmitt")
+ (organization "Hamme net, kren mer och nimmi")
+ (signature-file "~/.signature"))
+ ((message-news-p) ;;Usenet news?
+ (address "mySpamTrap@@Frank-Schmitt.invalid")
+ (reply-to "hereRealRepliesOnlyPlease@@Frank-Schmitt.invalid"))
+ ((message-mail-p) ;;mail?
+ (address "usedForMails@@Frank-Schmitt.invalid"))
+ ("^gmane" ;;this is mail, too in fact
+ (address "usedForMails@@Frank-Schmitt.invalid")
+ (reply-to nil))
+ ("^gmane\\.mail\\.spam\\.spamassassin\\.general$"
+ (eval (set (make-local-variable 'message-sendmail-envelope-from)
+ "Azzrael@@rz-online.de")))))
+@end example
+@noindent
+
+@node [5.5]
+@subsubheading Question 5.5
+
+Is there a spell-checker? Perhaps even on-the-fly spell-checking?
+
+@subsubheading Answer
+
+You can use ispell.el to spell-check stuff in Emacs. So the
+first thing to do is to make sure that you've got either
+@uref{http://fmg-www.cs.ucla.edu/fmg-members/geoff/ispell.html, ispell}
+or @uref{http://aspell.sourceforge.net/, aspell}
+installed and in your Path. Then you need
+@uref{http://www.kdstevens.com/~stevens/ispell-page.html, ispell.el}
+and for on-the-fly spell-checking
+@uref{http://www-sop.inria.fr/mimosa/personnel/Manuel.Serrano/flyspell/flyspell.html, flyspell.el}.
+Ispell.el is shipped with Emacs and available through the XEmacs package system,
+flyspell.el is shipped with Emacs and part of XEmacs text-modes package which is
+available through the package system, so there should be no need to install them
+manually.
+
+Ispell.el assumes you use ispell, if you choose aspell say
+
+@example
+(setq ispell-program-name "aspell")
+@end example
+@noindent
+
+in your Emacs configuration file.
+
+If you want your outgoing messages to be spell-checked, say
+
+@example
+(add-hook 'message-send-hook 'ispell-message)
+@end example
+@noindent
+
+In your ~/.gnus.el, if you prefer on-the-fly spell-checking say
+
+@example
+(add-hook 'message-mode-hook (lambda () (flyspell-mode 1)))
+@end example
+@noindent
+
+@node [5.6]
+@subsubheading Question 5.6
+
+Can I set the dictionary based on the group I'm posting to?
+
+@subsubheading Answer
+
+Yes, say something like
+
+@example
+(add-hook 'gnus-select-group-hook
+ (lambda ()
+ (cond
+ ((string-match
+ "^de\\." (gnus-group-real-name gnus-newsgroup-name))
+ (ispell-change-dictionary "deutsch8"))
+ (t
+ (ispell-change-dictionary "english")))))
+@end example
+@noindent
+
+in ~/.gnus.el. Change "^de\\." and "deutsch8" to something
+that suits your needs.
+
+@node [5.7]
+@subsubheading Question 5.7
+
+Is there some kind of address-book, so I needn't remember
+all those email addresses?
+
+@subsubheading Answer
+
+There's an very basic solution for this, mail aliases.
+You can store your mail addresses in a ~/.mailrc file using a simple
+alias syntax:
+
+@example
+alias al "Al <al@@english-heritage.invalid>"
+@end example
+@noindent
+
+Then typing your alias (followed by a space or punctuation
+character) on a To: or Cc: line in the message buffer will
+cause Gnus to insert the full address for you. See the
+node "Mail Aliases" in Message (not Gnus) manual for
+details.
+
+However, what you really want is the Insidious Big Brother
+Database bbdb. Get it through the XEmacs package system or from
+@uref{http://bbdb.sourceforge.net/, bbdb's homepage}.
+Now place the following in ~/.gnus.el, to activate bbdb for Gnus:
+
+@example
+(require 'bbdb)
+(bbdb-initialize 'gnus 'message)
+@end example
+@noindent
+
+Now you probably want some general bbdb configuration,
+place them in ~/.emacs:
+
+@example
+(require 'bbdb)
+;;If you don't live in Northern America, you should disable the
+;;syntax check for telephone numbers by saying
+(setq bbdb-north-american-phone-numbers-p nil)
+;;Tell bbdb about your email address:
+(setq bbdb-user-mail-names
+ (regexp-opt '("Your.Email@@here.invalid"
+ "Your.other@@mail.there.invalid")))
+;;cycling while completing email addresses
+(setq bbdb-complete-name-allow-cycling t)
+;;No popup-buffers
+(setq bbdb-use-pop-up nil)
+@end example
+@noindent
+
+Now you should be ready to go. Say @samp{M-x bbdb RET
+RET} to open a bbdb buffer showing all
+entries. Say @samp{c} to create a new
+entry, @samp{b} to search your BBDB and
+@samp{C-o} to add a new field to an
+entry. If you want to add a sender to the BBDB you can
+also just hit `:' on the posting in the summary buffer and
+you are done. When you now compose a new mail,
+hit @samp{TAB} to cycle through know
+recipients.
+
+@node [5.8]
+@subsubheading Question 5.8
+
+Sometimes I see little images at the top of article
+buffer. What's that and how can I send one with my
+postings, too?
+
+@subsubheading Answer
+
+Those images are called X-Faces. They are 48*48 pixel b/w
+pictures, encoded in a header line. If you want to include
+one in your posts, you've got to convert some image to a
+X-Face. So fire up some image manipulation program (say
+Gimp), open the image you want to include, cut out the
+relevant part, reduce color depth to 1 bit, resize to
+48*48 and save as bitmap. Now you should get the compface
+package from
+@uref{ftp://ftp.cs.indiana.edu:/pub/faces/, this site}.
+and create the actual X-face by saying
+
+@example
+cat file.xbm | xbm2ikon | compface > file.face
+cat file.face | sed 's/\\/\\\\/g;s/\"/\\\"/g;' > file.face.quoted
+@end example
+@noindent
+
+If you can't use compface, there's an online X-face converter at
+@uref{http://www.dairiki.org/xface/}.
+If you use MS Windows, you could also use the WinFace program from
+@uref{http://www.xs4all.nl/~walterln/winface/}.
+Now you only have to tell Gnus to include the X-face in your postings by saying
+
+@example
+(setq message-default-headers
+ (with-temp-buffer
+ (insert "X-Face: ")
+ (insert-file-contents "~/.xface")
+ (buffer-string)))
+@end example
+@noindent
+
+in ~/.gnus.el. If you use Gnus 5.10, you can simply add an entry
+
+@example
+(x-face-file "~/.xface")
+@end example
+@noindent
+
+to gnus-posting-styles.
+
+@node [5.9]
+@subsubheading Question 5.9
+
+Sometimes I accidentally hit r instead of f in
+newsgroups. Can Gnus warn me, when I'm replying by mail in
+newsgroups?
+
+@subsubheading Answer
+
+Put this in ~/.gnus.el:
+
+@example
+(setq gnus-confirm-mail-reply-to-news t)
+@end example
+@noindent
+
+if you already use Gnus 5.10, if you still use 5.8.8 or
+5.9 try this instead:
+
+@example
+(eval-after-load "gnus-msg"
+ '(unless (boundp 'gnus-confirm-mail-reply-to-news)
+ (defadvice gnus-summary-reply (around reply-in-news activate)
+ "Request confirmation when replying to news."
+ (interactive)
+ (when (or (not (gnus-news-group-p gnus-newsgroup-name))
+ (y-or-n-p "Really reply by mail to article author? "))
+ ad-do-it))))
+@end example
+@noindent
+
+@node [5.10]
+@subsubheading Question 5.10
+
+How to tell Gnus not to generate a sender header?
+
+@subsubheading Answer
+
+Since 5.10 Gnus doesn't generate a sender header by
+default. For older Gnus' try this in ~/.gnus.el:
+
+@example
+(eval-after-load "message"
+ '(add-to-list 'message-syntax-checks '(sender . disabled)))
+@end example
+@noindent
+
+@node [5.11]
+@subsubheading Question 5.11
+
+I want Gnus to locally store copies of my send mail and
+news, how to do it?
+
+@subsubheading Answer
+
+You must set the variable gnus-message-archive-group to do
+this. You can set it to a string giving the name of the
+group where the copies shall go or like in the example
+below use a function which is evaluated and which returns
+the group to use.
+
+@example
+(setq gnus-message-archive-group
+ '((if (message-news-p)
+ "nnml:Send-News"
+ "nnml:Send-Mail")))
+@end example
+@noindent
+
+@node [5.12]
+@subsubheading Question 5.12
+
+People tell me my Message-IDs are not correct, why
+aren't they and how to fix it?
+
+@subsubheading Answer
+
+The message-ID is an unique identifier for messages you
+send. To make it unique, Gnus need to know which machine
+name to put after the "@@". If the name of the machine
+where Gnus is running isn't suitable (it probably isn't
+at most private machines) you can tell Gnus what to use
+by saying:
+
+@example
+(setq message-user-fqdn "yourmachine.yourdomain.tld")
+@end example
+@noindent
+
+in ~/.gnus.el. If you use Gnus 5.9 or earlier, you can use this
+instead (works for newer versions a well):
+
+@example
+(eval-after-load "message"
+ '(let ((fqdn "yourmachine.yourdomain.tld"));; <-- Edit this!
+ (if (boundp 'message-user-fqdn)
+ (setq message-user-fqdn fqdn)
+ (gnus-message 1 "Redefining `message-make-fqdn'.")
+ (defun message-make-fqdn ()
+ "Return user's fully qualified domain name."
+ fqdn))))
+@end example
+@noindent
+
+If you have no idea what to insert for
+"yourmachine.yourdomain.tld", you've got several
+choices. You can either ask your provider if he allows
+you to use something like
+yourUserName.userfqdn.provider.net, or you can use
+somethingUnique.yourdomain.tld if you own the domain
+yourdomain.tld, or you can register at a service which
+gives private users a FQDN for free, e.g.
+@uref{http://www.stura.tu-freiberg.de/~dlx/addfqdn.html}.
+(Sorry but this website is in German, if you know of an
+English one offering the same, drop me a note).
+
+Finally you can tell Gnus not to generate a Message-ID
+for News at all (and letting the server do the job) by saying
+
+@example
+(setq message-required-news-headers
+ (remove' Message-ID message-required-news-headers))
+@end example
+@noindent
+
+you can also tell Gnus not to generate Message-IDs for mail by saying
+
+@example
+(setq message-required-mail-headers
+ (remove' Message-ID message-required-mail-headers))
+@end example
+@noindent
+
+, however some mail servers don't generate proper
+Message-IDs, too, so test if your Mail Server behaves
+correctly by sending yourself a Mail and looking at the Message-ID.
+
+@node FAQ 6 - Old messages
+@subsection Old messages
+
+@menu
+* [6.1]:: How to import my old mail into Gnus?
+* [6.2]:: How to archive interesting messages?
+* [6.3]:: How to search for a specific message?
+* [6.4]:: How to get rid of old unwanted mail?
+* [6.5]:: I want that all read messages are expired (at least in some
+ groups). How to do it?
+* [6.6]:: I don't want expiration to delete my mails but to move them
+ to another group.
+@end menu
+
+@node [6.1]
+@subsubheading Question 6.1
+
+How to import my old mail into Gnus?
+
+@subsubheading Answer
+
+The easiest way is to tell your old mail program to
+export the messages in mbox format. Most Unix mailers
+are able to do this, if you come from the MS Windows
+world, you may find tools at
+@uref{http://mbx2mbox.sourceforge.net/}.
+
+Now you've got to import this mbox file into Gnus. To do
+this, create a nndoc group based on the mbox file by
+saying @samp{G f /path/file.mbox RET} in
+Group buffer. You now have read-only access to your
+mail. If you want to import the messages to your normal
+Gnus mail groups hierarchy, enter the nndoc group you've
+just created by saying @samp{C-u RET}
+(thus making sure all messages are retrieved), mark all
+messages by saying @samp{M P b} and
+either copy them to the desired group by saying
+@samp{B c name.of.group RET} or send them
+through nnmail-split-methods (respool them) by saying
+@samp{B r}.
+
+@node [6.2]
+@subsubheading Question 6.2
+
+How to archive interesting messages?
+
+@subsubheading Answer
+
+If you stumble across an interesting message, say in
+gnu.emacs.gnus and want to archive it there are several
+solutions. The first and easiest is to save it to a file
+by saying @samp{O f}. However, wouldn't
+it be much more convenient to have more direct access to
+the archived message from Gnus? If you say yes, put this
+snippet by Frank Haun <pille3003@@fhaun.de> in
+~/.gnus.el:
+
+@example
+(defun my-archive-article (&optional n)
+ "Copies one or more article(s) to a corresponding `nnml:' group, e.g.
+`gnus.ding' goes to `nnml:1.gnus.ding'. And `nnml:List-gnus.ding' goes
+to `nnml:1.List-gnus-ding'.
+
+Use process marks or mark a region in the summary buffer to archive
+more then one article."
+ (interactive "P")
+ (let ((archive-name
+ (format
+ "nnml:1.%s"
+ (if (featurep 'xemacs)
+ (replace-in-string gnus-newsgroup-name "^.*:" "")
+ (replace-regexp-in-string "^.*:" "" gnus-newsgroup-name)))))
+ (gnus-summary-copy-article n archive-name)))
+@end example
+@noindent
+
+You can now say @samp{M-x
+my-archive-article} in summary buffer to
+archive the article under the cursor in a nnml
+group. (Change nnml to your preferred back end)
+
+Of course you can also make sure the cache is enabled by saying
+
+@example
+(setq gnus-use-cache t)
+@end example
+@noindent
+
+then you only have to set either the tick or the dormant
+mark for articles you want to keep, setting the read
+mark will remove them from cache.
+
+@node [6.3]
+@subsubheading Question 6.3
+
+How to search for a specific message?
+
+@subsubheading Answer
+
+There are several ways for this, too. For a posting from
+a Usenet group the easiest solution is probably to ask
+@uref{http://groups.google.com, groups.google.com},
+if you found the posting there, tell Google to display
+the raw message, look for the message-id, and say
+@samp{M-^ the@@message.id RET} in a
+summary buffer.
+Since Gnus 5.10 there's also a Gnus interface for
+groups.google.com which you can call with
+@samp{G W}) in group buffer.
+
+Another idea which works for both mail and news groups
+is to enter the group where the message you are
+searching is and use the standard Emacs search
+@samp{C-s}, it's smart enough to look at
+articles in collapsed threads, too. If you want to
+search bodies, too try @samp{M-s}
+instead. Further on there are the
+gnus-summary-limit-to-foo functions, which can help you,
+too.
+
+Of course you can also use grep to search through your
+local mail, but this is both slow for big archives and
+inconvenient since you are not displaying the found mail
+in Gnus. Here comes nnir into action. Nnir is a front end
+to search engines like swish-e or swish++ and
+others. You index your mail with one of those search
+engines and with the help of nnir you can search trough
+the indexed mail and generate a temporary group with all
+messages which met your search criteria. If this sound
+cool to you get nnir.el from
+@uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/}
+or @uref{ftp://ftp.is.informatik.uni-duisburg.de/pub/src/emacs/}.
+Instructions on how to use it are at the top of the file.
+
+@node [6.4]
+@subsubheading Question 6.4
+
+How to get rid of old unwanted mail?
+
+@subsubheading Answer
+
+You can of course just mark the mail you don't need
+anymore by saying @samp{#} with point
+over the mail and then say @samp{B DEL}
+to get rid of them forever. You could also instead of
+actually deleting them, send them to a junk-group by
+saying @samp{B m nnml:trash-bin} which
+you clear from time to time, but both are not the intended
+way in Gnus.
+
+In Gnus, we let mail expire like news expires on a news
+server. That means you tell Gnus the message is
+expirable (you tell Gnus "I don't need this mail
+anymore") by saying @samp{E} with point
+over the mail in summary buffer. Now when you leave the
+group, Gnus looks at all messages which you marked as
+expirable before and if they are old enough (default is
+older than a week) they are deleted.
+
+@node [6.5]
+@subsubheading Question 6.5
+
+I want that all read messages are expired (at least in
+some groups). How to do it?
+
+@subsubheading Answer
+
+If you want all read messages to be expired (e.g. in
+mailing lists where there's an online archive), you've
+got two choices: auto-expire and
+total-expire. Auto-expire means, that every article
+which has no marks set and is selected for reading is
+marked as expirable, Gnus hits @samp{E}
+for you every time you read a message. Total-expire
+follows a slightly different approach, here all article
+where the read mark is set are expirable.
+
+To activate auto-expire, include auto-expire in the
+Group parameters for the group. (Hit @samp{G
+c} in summary buffer with point over the
+group to change group parameters). For total-expire add
+total-expire to the group-parameters.
+
+Which method you choose is merely a matter of taste:
+Auto-expire is faster, but it doesn't play together with
+Adaptive Scoring, so if you want to use this feature,
+you should use total-expire.
+
+If you want a message to be excluded from expiration in
+a group where total or auto expire is active, set either
+tick (hit @samp{u}) or dormant mark (hit
+@samp{u}), when you use auto-expire, you
+can also set the read mark (hit
+@samp{d}).
+
+@node [6.6]
+@subsubheading Question 6.6
+
+I don't want expiration to delete my mails but to move them
+to another group.
+
+@subsubheading Answer
+
+Say something like this in ~/.gnus.el:
+
+@example
+(setq nnmail-expiry-target "nnml:expired")
+@end example
+@noindent
+
+(If you want to change the value of nnmail-expiry-target
+on a per group basis see the question "How can I disable
+threading in some (e.g. mail-) groups, or set other
+variables specific for some groups?")
+
+@node FAQ 7 - Gnus in a dial-up environment
+@subsection Gnus in a dial-up environment
+
+@menu
+* [7.1]:: I don't have a permanent connection to the net, how can I
+ minimize the time I've got to be connected?
+* [7.2]:: So what was this thing about the Agent?
+* [7.3]:: I want to store article bodies on disk, too. How to do it?
+* [7.4]:: How to tell Gnus not to try to send mails / postings while
+ I'm offline?
+@end menu
+
+@node [7.1]
+@subsubheading Question 7.1
+
+I don't have a permanent connection to the net, how can
+I minimize the time I've got to be connected?
+
+@subsubheading Answer
+
+You've got basically two options: Either you use the
+Gnus Agent (see below) for this, or you can install
+programs which fetch your news and mail to your local
+disk and Gnus reads the stuff from your local
+machine.
+
+If you want to follow the second approach, you need a
+program which fetches news and offers them to Gnus, a
+program which does the same for mail and a program which
+receives the mail you write from Gnus and sends them
+when you're online.
+
+Let's talk about Unix systems first: For the news part,
+the easiest solution is a small nntp server like
+@uref{http://www.leafnode.org/, Leafnode} or
+@uref{http://infa.abo.fi/~patrik/sn/, sn},
+of course you can also install a full featured news
+server like
+@uref{http://www.isc.org/products/INN/, inn}.
+Then you want to fetch your Mail, popular choices
+are @uref{http://www.catb.org/~esr/fetchmail/, fetchmail}
+and @uref{http://www.qcc.ca/~charlesc/software/getmail-3.0/, getmail}.
+You should tell those to write the mail to your disk and
+Gnus to read it from there. Last but not least the mail
+sending part: This can be done with every MTA like
+@uref{http://www.sendmail.org/, sendmail},
+@uref{http://www.qmail.org/, postfix},
+@uref{http://www.exim.org/, exim} or
+@uref{http://www.qmail.org/, qmail}.
+
+On windows boxes I'd vote for
+@uref{http://www.tglsoft.de/, Hamster},
+it's a small freeware, open-source program which fetches
+your mail and news from remote servers and offers them
+to Gnus (or any other mail and/or news reader) via nntp
+respectively POP3 or IMAP. It also includes a smtp
+server for receiving mails from Gnus.
+
+@node [7.2]
+@subsubheading Question 7.2
+
+So what was this thing about the Agent?
+
+@subsubheading Answer
+
+The Gnus agent is part of Gnus, it allows you to fetch
+mail and news and store them on disk for reading them
+later when you're offline. It kind of mimics offline
+newsreaders like e.g. Forte Agent. If you want to use
+the Agent place the following in ~/.gnus.el if you are
+still using 5.8.8 or 5.9 (it's the default since 5.10):
+
+@example
+(setq gnus-agent t)
+@end example
+@noindent
+
+Now you've got to select the servers whose groups can be
+stored locally. To do this, open the server buffer
+(that is press @samp{^} while in the
+group buffer). Now select a server by moving point to
+the line naming that server. Finally, agentize the
+server by typing @samp{J a}. If you
+make a mistake, or change your mind, you can undo this
+action by typing @samp{J r}. When
+you're done, type 'q' to return to the group buffer.
+Now the next time you enter a group on a agentized
+server, the headers will be stored on disk and read from
+there the next time you enter the group.
+
+@node [7.3]
+@subsubheading Question 7.3
+
+I want to store article bodies on disk, too. How to do it?
+
+@subsubheading Answer
+
+You can tell the agent to automatically fetch the bodies
+of articles which fulfill certain predicates, this is
+done in a special buffer which can be reached by
+saying @samp{J c} in group
+buffer. Please refer to the documentation for
+information which predicates are possible and how
+exactly to do it.
+
+Further on you can tell the agent manually which
+articles to store on disk. There are two ways to do
+this: Number one: In the summary buffer, process mark a
+set of articles that shall be stored in the agent by
+saying @samp{#} with point over the
+article and then type @samp{J s}. The
+other possibility is to set, again in the summary
+buffer, downloadable (%) marks for the articles you
+want by typing @samp{@@} with point over
+the article and then typing @samp{J u}.
+What's the difference? Well, process marks are erased as
+soon as you exit the summary buffer while downloadable
+marks are permanent. You can actually set downloadable
+marks in several groups then use fetch session ('J s' in
+the GROUP buffer) to fetch all of those articles. The
+only downside is that fetch session also fetches all of
+the headers for every selected group on an agentized
+server. Depending on the volume of headers, the initial
+fetch session could take hours.
+
+@node [7.4]
+@subsubheading Question 7.4
+
+How to tell Gnus not to try to send mails / postings
+while I'm offline?
+
+@subsubheading Answer
+
+All you've got to do is to tell Gnus when you are online
+(plugged) and when you are offline (unplugged), the rest
+works automatically. You can toggle plugged/unplugged
+state by saying @samp{J j} in group
+buffer. To start Gnus unplugged say @samp{M-x
+gnus-unplugged} instead of
+@samp{M-x gnus}. Note that for this to
+work, the agent must be active.
+
+@node FAQ 8 - Getting help
+@subsection Getting help
+
+@menu
+* [8.1]:: How to find information and help inside Emacs?
+* [8.2]:: I can't find anything in the Gnus manual about X (e.g.
+ attachments, PGP, MIME...), is it not documented?
+* [8.3]:: Which websites should I know?
+* [8.4]:: Which mailing lists and newsgroups are there?
+* [8.5]:: Where to report bugs?
+* [8.6]:: I need real-time help, where to find it?
+@end menu
+
+@node [8.1]
+@subsubheading Question 8.1
+
+How to find information and help inside Emacs?
+
+@subsubheading Answer
+
+The first stop should be the Gnus manual (Say
+@samp{C-h i d m Gnus RET} to start the
+Gnus manual, then walk through the menus or do a
+full-text search with @samp{s}). Then
+there are the general Emacs help commands starting with
+C-h, type @samp{C-h ? ?} to get a list
+of all available help commands and their meaning. Finally
+@samp{M-x apropos-command} lets you
+search through all available functions and @samp{M-x
+apropos} searches the bound variables.
+
+@node [8.2]
+@subsubheading Question 8.2
+
+I can't find anything in the Gnus manual about X
+(e.g. attachments, PGP, MIME...), is it not documented?
+
+@subsubheading Answer
+
+There's not only the Gnus manual but also the manuals
+for message, emacs-mime, sieve and pgg. Those packages
+are distributed with Gnus and used by Gnus but aren't
+really part of core Gnus, so they are documented in
+different info files, you should have a look in those
+manuals, too.
+
+@node [8.3]
+@subsubheading Question 8.3
+
+Which websites should I know?
+
+@subsubheading Answer
+
+The two most important ones are the
+@uref{http://www.gnus.org, official Gnus website}.
+and it's sister site
+@uref{http://my.gnus.org, my.gnus.org (MGO)},
+hosting an archive of lisp snippets, howtos, a (not
+really finished) tutorial and this FAQ.
+
+Tell me about other sites which are interesting.
+
+@node [8.4]
+@subsubheading Question 8.4
+
+Which mailing lists and newsgroups are there?
+
+@subsubheading Answer
+
+There's the newsgroup gnu.emacs.gnus
+(also available as
+@uref{http://dir.gmane.org/gmane.emacs.gnus.user,
+gmane.emacs.gnus.user})
+which deals with general Gnus questions.
+The ding mailing list (ding@@gnus.org) deals with development of
+Gnus. You can read the ding list via NNTP, too under the name
+@uref{http://dir.gmane.org/gmane.emacs.gnus.general,
+gmane.emacs.gnus.general} from news.gmane.org.
+
+If you want to stay in the big8,
+news.software.newssreaders is also read by some Gnus
+users (but chances for qualified help are much better in
+the above groups) and if you speak German, there's
+de.comm.software.gnus.
+
+@node [8.5]
+@subsubheading Question 8.5
+
+Where to report bugs?
+
+@subsubheading Answer
+
+Say @samp{M-x gnus-bug}, this will start
+a message to the
+@email{bugs@@gnus.org, gnus bug mailing list}
+including information about your environment which make
+it easier to help you.
+
+@node [8.6]
+@subsubheading Question 8.6
+
+I need real-time help, where to find it?
+
+@subsubheading Answer
+
+Point your IRC client to irc.freenode.net, channel #gnus.
+
+@node FAQ 9 - Tuning Gnus
+@subsection Tuning Gnus
+
+@menu
+* [9.1]:: Starting Gnus is really slow, how to speed it up?
+* [9.2]:: How to speed up the process of entering a group?
+* [9.3]:: Sending mail becomes slower and slower, what's up?
+@end menu
+
+@node [9.1]
+@subsubheading Question 9.1
+
+Starting Gnus is really slow, how to speed it up?
+
+@subsubheading Answer
+
+The reason for this could be the way Gnus reads it's
+active file, see the node "The Active File" in the Gnus
+manual for things you might try to speed the process up.
+An other idea would be to byte compile your ~/.gnus.el (say
+@samp{M-x byte-compile-file RET ~/.gnus.el
+RET} to do it). Finally, if you have require
+statements in your .gnus, you could replace them with
+eval-after-load, which loads the stuff not at startup
+time, but when it's needed. Say you've got this in your
+~/.gnus.el:
+
+@example
+(require 'message)
+(add-to-list 'message-syntax-checks '(sender . disabled))
+@end example
+@noindent
+
+then as soon as you start Gnus, message.el is loaded. If
+you replace it with
+
+@example
+(eval-after-load "message"
+ '(add-to-list 'message-syntax-checks '(sender . disabled)))
+@end example
+@noindent
+
+it's loaded when it's needed.
+
+@node [9.2]
+@subsubheading Question 9.2
+
+How to speed up the process of entering a group?
+
+@subsubheading Answer
+
+A speed killer is setting the variable
+gnus-fetch-old-headers to anything different from nil,
+so don't do this if speed is an issue. To speed up
+building of summary say
+
+@example
+(gnus-compile)
+@end example
+@noindent
+
+at the bottom of your ~/.gnus.el, this will make gnus
+byte-compile things like
+gnus-summary-line-format.
+then you could increase the value of gc-cons-threshold
+by saying something like
+
+@example
+(setq gc-cons-threshold 3500000)
+@end example
+@noindent
+
+in ~/.emacs. If you don't care about width of CJK
+characters or use Gnus 5.10 or younger together with a
+recent GNU Emacs, you should say
+
+@example
+(setq gnus-use-correct-string-widths nil)
+@end example
+@noindent
+
+in ~/.gnus.el (thanks to Jesper harder for the last
+two suggestions). Finally if you are still using 5.8.8
+or 5.9 and experience speed problems with summary
+buffer generation, you definitely should update to
+5.10 since there quite some work on improving it has
+been done.
+
+@node [9.3]
+@subsubheading Question 9.3
+
+Sending mail becomes slower and slower, what's up?
+
+@subsubheading Answer
+
+The reason could be that you told Gnus to archive the
+messages you wrote by setting
+gnus-message-archive-group. Try to use a nnml group
+instead of an archive group, this should bring you back
+to normal speed.
+
+@node FAQ - Glossary
+@subsection Glossary
+
+@table @dfn
+
+@item ~/.gnus.el
+When the term ~/.gnus.el is used it just means your Gnus
+configuration file. You might as well call it ~/.gnus or
+specify another name.
+
+@item Back End
+In Gnus terminology a back end is a virtual server, a layer
+between core Gnus and the real NNTP-, POP3-, IMAP- or
+whatever-server which offers Gnus a standardized interface
+to functions like "get message", "get Headers" etc.
+
+@item Emacs
+When the term Emacs is used in this FAQ, it means either GNU
+Emacs or XEmacs.
+
+@item Message
+In this FAQ message means a either a mail or a posting to a
+Usenet Newsgroup or to some other fancy back end, no matter
+of which kind it is.
+
+@item MUA
+MUA is an acronym for Mail User Agent, it's the program you
+use to read and write e-mails.
+
+@item NUA
+NUA is an acronym for News User Agent, it's the program you
+use to read and write Usenet news.
+
+@end table
+
+@ignore
+arch-tag: 64dc5692-edb4-4848-a965-7aa0181acbb8
+@end ignore
--- /dev/null
+\input texinfo
+
+@setfilename ../info/gnus
+@settitle Gnus Manual
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex pg cp
+
+@copying
+Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001,
+2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@iftex
+@iflatex
+\documentclass[twoside,a4paper,openright,11pt]{book}
+\usepackage[latin1]{inputenc}
+\usepackage{pagestyle}
+\usepackage{epsfig}
+\usepackage{pixidx}
+\input{gnusconfig.tex}
+
+\ifx\pdfoutput\undefined
+\else
+\usepackage[pdftex,bookmarks,colorlinks=true]{hyperref}
+\usepackage{thumbpdf}
+\pdfcompresslevel=9
+\fi
+
+\makeindex
+\begin{document}
+
+% Adjust ../Makefile.in if you change the following line:
+\newcommand{\gnusversionname}{Gnus v5.11}
+\newcommand{\gnuschaptername}{}
+\newcommand{\gnussectionname}{}
+
+\newcommand{\gnusbackslash}{/}
+
+\newcommand{\gnusref}[1]{``#1'' on page \pageref{#1}}
+\ifx\pdfoutput\undefined
+\newcommand{\gnusuref}[1]{\gnustt{#1}}
+\else
+\newcommand{\gnusuref}[1]{\href{#1}{\gnustt{#1}}}
+\fi
+\newcommand{\gnusxref}[1]{See ``#1'' on page \pageref{#1}}
+\newcommand{\gnuspxref}[1]{see ``#1'' on page \pageref{#1}}
+
+\newcommand{\gnuskindex}[1]{\index{#1}}
+\newcommand{\gnusindex}[1]{\index{#1}}
+
+\newcommand{\gnustt}[1]{{\gnusselectttfont{}#1}}
+\newcommand{\gnuscode}[1]{\gnustt{#1}}
+\newcommand{\gnusasis}[1]{\gnustt{#1}}
+\newcommand{\gnusurl}[1]{\gnustt{#1}}
+\newcommand{\gnuscommand}[1]{\gnustt{#1}}
+\newcommand{\gnusenv}[1]{\gnustt{#1}}
+\newcommand{\gnussamp}[1]{``{\fontencoding{OT1}\gnusselectttfont{}#1}''}
+\newcommand{\gnuslisp}[1]{\gnustt{#1}}
+\newcommand{\gnuskbd}[1]{`\gnustt{#1}'}
+\newcommand{\gnuskey}[1]{`\gnustt{#1}'}
+\newcommand{\gnusfile}[1]{`\gnustt{#1}'}
+\newcommand{\gnusdfn}[1]{\textit{#1}}
+\newcommand{\gnusi}[1]{\textit{#1}}
+\newcommand{\gnusr}[1]{\textrm{#1}}
+\newcommand{\gnusstrong}[1]{\textbf{#1}}
+\newcommand{\gnusemph}[1]{\textit{#1}}
+\newcommand{\gnusvar}[1]{{\fontsize{10pt}{10}\selectfont\textsl{\textsf{#1}}}}
+\newcommand{\gnussc}[1]{\textsc{#1}}
+\newcommand{\gnustitle}[1]{{\huge\textbf{#1}}}
+\newcommand{\gnusversion}[1]{{\small\textit{#1}}}
+\newcommand{\gnusauthor}[1]{{\large\textbf{#1}}}
+\newcommand{\gnusresult}[1]{\gnustt{=> #1}}
+\newcommand{\gnusacronym}[1]{\textsc{#1}}
+\newcommand{\gnusemail}[1]{\textit{#1}}
+
+\newcommand{\gnusbullet}{{${\bullet}$}}
+\newcommand{\gnusdollar}{\$}
+\newcommand{\gnusampersand}{\&}
+\newcommand{\gnuspercent}{\%}
+\newcommand{\gnushash}{\#}
+\newcommand{\gnushat}{\symbol{"5E}}
+\newcommand{\gnusunderline}{\symbol{"5F}}
+\newcommand{\gnusnot}{$\neg$}
+\newcommand{\gnustilde}{\symbol{"7E}}
+\newcommand{\gnusless}{{$<$}}
+\newcommand{\gnusgreater}{{$>$}}
+\newcommand{\gnusbraceleft}{{$>$}}
+\newcommand{\gnusbraceright}{{$>$}}
+
+\newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=ps/gnus-head,height=1cm}}}
+\newcommand{\gnusinteresting}{
+\marginpar[\mbox{}\hfill\gnushead]{\gnushead}
+}
+
+\newcommand{\gnuscleardoublepage}{\ifodd\count0\mbox{}\clearpage\thispagestyle{empty}\mbox{}\clearpage\else\clearpage\fi}
+
+\newcommand{\gnuspagechapter}[1]{
+{\mbox{}}
+}
+
+\newdimen{\gnusdimen}
+\gnusdimen 0pt
+
+\newcommand{\gnuschapter}[2]{
+\gnuscleardoublepage
+\ifdim \gnusdimen = 0pt\setcounter{page}{1}\pagestyle{gnus}\pagenumbering{arabic} \gnusdimen 1pt\fi
+\chapter{#2}
+\renewcommand{\gnussectionname}{}
+\renewcommand{\gnuschaptername}{#2}
+\thispagestyle{empty}
+\hspace*{-2cm}
+\begin{picture}(500,500)(0,0)
+\put(480,350){\makebox(0,0)[tr]{#1}}
+\put(40,300){\makebox(500,50)[bl]{{\Huge\bf{#2}}}}
+\end{picture}
+\clearpage
+}
+
+\newcommand{\gnusfigure}[3]{
+\begin{figure}
+\mbox{}\ifodd\count0\hspace*{-0.8cm}\else\hspace*{-3cm}\fi\begin{picture}(440,#2)
+#3
+\end{picture}
+\caption{#1}
+\end{figure}
+}
+
+\newcommand{\gnusicon}[1]{
+\marginpar[\mbox{}\hfill\raisebox{-1.5cm}{\epsfig{figure=ps/#1-up,height=1.5cm}}]{\raisebox{-1cm}{\epsfig{figure=ps/#1-up,height=1cm}}}
+}
+
+\newcommand{\gnuspicon}[1]{
+\margindex{\epsfig{figure=#1,width=2cm}}
+}
+
+\newcommand{\gnusxface}[2]{
+\margindex{\epsfig{figure=#1,width=1cm}\epsfig{figure=#2,width=1cm}}
+}
+
+\newcommand{\gnussmiley}[2]{
+\margindex{\makebox[2cm]{\hfill\epsfig{figure=#1,width=0.5cm}\hfill\epsfig{figure=#2,width=0.5cm}\hfill}}
+}
+
+\newcommand{\gnusitemx}[1]{\mbox{}\vspace*{-\itemsep}\vspace*{-\parsep}\item#1}
+
+\newcommand{\gnussection}[1]{
+\renewcommand{\gnussectionname}{#1}
+\section{#1}
+}
+
+\newenvironment{codelist}%
+{\begin{list}{}{
+}
+}{\end{list}}
+
+\newenvironment{asislist}%
+{\begin{list}{}{
+}
+}{\end{list}}
+
+\newenvironment{kbdlist}%
+{\begin{list}{}{
+\labelwidth=0cm
+}
+}{\end{list}}
+
+\newenvironment{dfnlist}%
+{\begin{list}{}{
+}
+}{\end{list}}
+
+\newenvironment{stronglist}%
+{\begin{list}{}{
+}
+}{\end{list}}
+
+\newenvironment{samplist}%
+{\begin{list}{}{
+}
+}{\end{list}}
+
+\newenvironment{varlist}%
+{\begin{list}{}{
+}
+}{\end{list}}
+
+\newenvironment{emphlist}%
+{\begin{list}{}{
+}
+}{\end{list}}
+
+\newlength\gnusheadtextwidth
+\setlength{\gnusheadtextwidth}{\headtextwidth}
+\addtolength{\gnusheadtextwidth}{1cm}
+
+\newpagestyle{gnuspreamble}%
+{
+{
+\ifodd\count0
+{
+\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\mbox{}}\textbf{\hfill\roman{page}}}
+}
+\else
+{
+\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\roman{page}\hfill\mbox{}}}
+}
+}
+\fi
+}
+}
+{
+\ifodd\count0
+\mbox{} \hfill
+\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
+\else
+\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
+\hfill \mbox{}
+\fi
+}
+
+\newpagestyle{gnusindex}%
+{
+{
+\ifodd\count0
+{
+\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\gnuschaptername\hfill\arabic{page}}}}
+}
+\else
+{
+\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}
+}
+\fi
+}
+}
+{
+\ifodd\count0
+\mbox{} \hfill
+\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
+\else
+\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
+\hfill \mbox{}
+\fi
+}
+
+\newpagestyle{gnus}%
+{
+{
+\ifodd\count0
+{
+\makebox[12cm]{\hspace*{3.1cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{chapter}.\arabic{section}} \textbf{\gnussectionname\hfill\arabic{page}}}}}
+}
+\else
+{
+\makebox[12cm]{\hspace*{-2.95cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}}
+}
+\fi
+}
+}
+{
+\ifodd\count0
+\mbox{} \hfill
+\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
+\else
+\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
+\hfill \mbox{}
+\fi
+}
+
+\pagenumbering{roman}
+\pagestyle{gnuspreamble}
+
+@end iflatex
+@end iftex
+
+@iftex
+@iflatex
+
+\begin{titlepage}
+{
+
+%\addtolength{\oddsidemargin}{-5cm}
+%\addtolength{\evensidemargin}{-5cm}
+\parindent=0cm
+\addtolength{\textheight}{2cm}
+
+\gnustitle{\gnustitlename}\hfill\gnusversion{\gnusversionname}\\
+\rule{15cm}{1mm}\\
+\vfill
+\hspace*{0cm}\epsfig{figure=ps/gnus-big-logo,height=15cm}
+\vfill
+\rule{15cm}{1mm}\\
+\gnusauthor{by Lars Magne Ingebrigtsen}
+\newpage
+}
+
+\mbox{}
+\vfill
+
+\thispagestyle{empty}
+
+@c @insertcopying
+\newpage
+\end{titlepage}
+@end iflatex
+@end iftex
+
+@ifnottex
+@insertcopying
+@end ifnottex
+
+@dircategory Emacs
+@direntry
+* Gnus: (gnus). The newsreader Gnus.
+@end direntry
+@iftex
+@finalout
+@end iftex
+@setchapternewpage odd
+
+
+
+@titlepage
+@title Gnus Manual
+
+@author by Lars Magne Ingebrigtsen
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+
+@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---@acronym{NNTP}, local
+spool or your mbox file. All at the same time, if you want to push your
+luck.
+
+@c Adjust ../Makefile.in if you change the following line:
+This manual corresponds to Gnus v5.11.
+
+@end ifinfo
+
+@iftex
+
+@iflatex
+\tableofcontents
+\gnuscleardoublepage
+@end iflatex
+
+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.
+* Group Buffer:: Selecting, subscribing and killing groups.
+* Summary Buffer:: Reading, saving and posting articles.
+* 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, @acronym{FAQ}, History, Internals.
+* GNU Free Documentation License:: The license for this documentation.
+* Index:: Variable, function and concept index.
+* Key Index:: Key Index.
+
+Other related manuals
+
+* Message:(message). Composing messages.
+* Emacs-MIME:(emacs-mime). Composing messages; @acronym{MIME}-specific parts.
+* Sieve:(sieve). Managing Sieve scripts in Emacs.
+* PGG:(pgg). @acronym{PGP/MIME} with Gnus.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Starting Gnus
+
+* 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?
+* Changing Servers:: You may want to move from one server to another.
+* 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.
+* Startup Variables:: Other variables you might change.
+
+New Groups
+
+* 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.
+
+Group Buffer
+
+* 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.
+* Subscription Commands:: Unsubscribing, killing, subscribing.
+* Group Data:: Changing the info for a group.
+* 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.
+
+Group Buffer Format
+
+* Group Line Specification:: Deciding how the group buffer is to look.
+* Group Mode Line Specification:: The group buffer mode line.
+* Group Highlighting:: Having nice colors in the group buffer.
+
+Group Topics
+
+* Topic Commands:: Interactive E-Z commands.
+* Topic Variables:: How to customize the topics the Lisp Way.
+* Topic Sorting:: Sorting each topic individually.
+* Topic Topology:: A map of the world.
+* Topic Parameters:: Parameters that apply to all groups in a topic.
+
+Misc Group Stuff
+
+* 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.
+* Sieve Commands:: Managing Sieve scripts.
+
+Summary Buffer
+
+* 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.
+* Delayed Articles:: Send articles at a later time.
+* Marking Articles:: Marking articles as read, expirable, etc.
+* Limiting:: You can limit the summary buffer.
+* Threading:: How threads are made.
+* Sorting the Summary Buffer:: 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.
+* MIME Commands:: Doing MIMEy things with the articles.
+* Charsets:: Character set issues.
+* 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,
+ or reselecting the current group.
+* Crosspost Handling:: How crossposted articles are dealt with.
+* Duplicate Suppression:: An alternative when crosspost handling fails.
+* Security:: Decrypt and Verify.
+* Mailing List:: Mailing list minor mode.
+
+Summary Buffer Format
+
+* Summary Buffer Lines:: You can specify how summary lines should look.
+* To From Newsgroups:: How to not display your own name.
+* Summary Buffer Mode Line:: You can say how the mode line should look.
+* Summary Highlighting:: Making the summary buffer all pretty and nice.
+
+Choosing Articles
+
+* Choosing Commands:: Commands for choosing articles.
+* Choosing Variables:: Variables that influence these commands.
+
+Reply, Followup and Post
+
+* Summary Mail Commands:: Sending mail.
+* Summary Post Commands:: Sending news.
+* Summary Message Commands:: Other Message-related commands.
+* Canceling and Superseding::
+
+Marking Articles
+
+* Unread Articles:: Marks for unread articles.
+* Read Articles:: Marks for read articles.
+* Other Marks:: Marks that do not affect readedness.
+* Setting Marks:: How to set and remove marks.
+* Generic Marking Commands:: How to customize the marking.
+* Setting Process Marks:: How to mark articles for later processing.
+
+Threading
+
+* Customizing Threading:: Variables you can change to affect the threading.
+* Thread Commands:: Thread based commands in the summary buffer.
+
+Customizing Threading
+
+* 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@dots{} but you were wrong!
+
+Decoding Articles
+
+* 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?
+
+Decoding Variables
+
+* 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.
+
+Article Treatment
+
+* 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 Header:: Doing various header transformations.
+* Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
+* Article Button Levels:: Controlling appearance of buttons.
+* Article Date:: Grumble, UT!
+* Article Display:: Display various stuff---X-Face, Picons, Smileys
+* Article Signature:: What is a signature?
+* Article Miscellanea:: Various other stuff.
+
+Alternative Approaches
+
+* Pick and Read:: First mark articles and then read them.
+* Binary Groups:: Auto-decode all articles.
+
+Various Summary Stuff
+
+* Summary Group Information:: Information oriented commands.
+* Searching for Articles:: Multiple article commands.
+* Summary Generation Commands::
+* Really Various Summary Commands:: Those pesky non-conformant commands.
+
+Article Buffer
+
+* Hiding Headers:: Deciding what headers should be displayed.
+* Using MIME:: Pushing articles through @acronym{MIME} before reading them.
+* Customizing Articles:: Tailoring the look of the articles.
+* Article Keymap:: Keystrokes available in the article buffer.
+* Misc Article:: Other stuff.
+
+Composing Messages
+
+* Mail:: Mailing and replying.
+* Posting Server:: What server should you post and mail via?
+* POP before SMTP:: You cannot send a mail unless you read a mail.
+* 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?
+* Signing and encrypting:: How to compose secure messages.
+
+Select Methods
+
+* Server Buffer:: Making and editing virtual servers.
+* Getting News:: Reading USENET news with Gnus.
+* Getting Mail:: Reading your personal mail with Gnus.
+* Browsing the Web:: Getting messages from a plethora of Web sources.
+* IMAP:: Using Gnus as a @acronym{IMAP} client.
+* Other Sources:: Reading directories, files, SOUP packets.
+* Combined Groups:: Combining groups into one group.
+* Email Based Diary:: Using mails to manage diary events in Gnus.
+* Gnus Unplugged:: Reading news and mail offline.
+
+Server Buffer
+
+* 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.
+
+Getting News
+
+* NNTP:: Reading news from an @acronym{NNTP} server.
+* News Spool:: Reading news from the local spool.
+
+@acronym{NNTP}
+
+* Direct Functions:: Connecting directly to the server.
+* Indirect Functions:: Connecting indirectly to the server.
+* Common Variables:: Understood by several connection functions.
+
+Getting Mail
+
+* Mail in a Newsreader:: Important introductory notes.
+* Getting Started Reading Mail:: A simple cookbook example.
+* Splitting Mail:: How to create mail groups.
+* Mail Sources:: How to tell Gnus where to get mail from.
+* Mail Back End Variables:: Variables for customizing mail handling.
+* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
+* Group Mail Splitting:: Use group customize to drive mail splitting.
+* Incorporating Old Mail:: What about the old mail you have?
+* Expiring Mail:: Getting rid of unwanted mail.
+* Washing Mail:: Removing cruft from the mail you get.
+* Duplicates:: Dealing with duplicated mail.
+* Not Reading Mail:: Using mail back ends for reading other files.
+* Choosing a Mail Back End:: Gnus can read a variety of mail formats.
+
+Mail Sources
+
+* Mail Source Specifiers:: How to specify what a mail source is.
+* Mail Source Customization:: Some variables that influence things.
+* Fetching Mail:: Using the mail source specifiers.
+
+Choosing a Mail Back End
+
+* 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 back end.
+* Maildir:: Another one-file-per-message format.
+* Mail Folders:: Having one file for each group.
+* Comparing Mail Back Ends:: An in-depth looks at pros and cons.
+
+Browsing the Web
+
+* Archiving Mail::
+* Web Searches:: Creating groups from articles that match a string.
+* Slashdot:: Reading the Slashdot comments.
+* Ultimate:: The Ultimate Bulletin Board systems.
+* Web Archive:: Reading mailing list archived on web.
+* RSS:: Reading RDF site summary.
+* Customizing W3:: Doing stuff to Emacs/W3 from Gnus.
+
+@acronym{IMAP}
+
+* Splitting in IMAP:: Splitting mail with nnimap.
+* Expiring in IMAP:: Expiring mail with nnimap.
+* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox.
+* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button.
+* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus.
+* Debugging IMAP:: What to do when things don't work.
+
+Other Sources
+
+* 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''.
+* Mail-To-News Gateways:: Posting articles via mail-to-news gateways.
+
+Document Groups
+
+* Document Server Internals:: How to add your own document types.
+
+SOUP
+
+* SOUP Commands:: Commands for creating and sending @sc{soup} packets
+* SOUP Groups:: A back end for reading @sc{soup} packets.
+* SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
+
+Combined Groups
+
+* Virtual Groups:: Combining articles from many groups.
+* Kibozed Groups:: Looking through parts of the newsfeed for articles.
+
+Email Based Diary
+
+* The NNDiary Back End:: Basic setup and usage.
+* The Gnus Diary Library:: Utility toolkit on top of nndiary.
+* Sending or Not Sending:: A final note on sending diary messages.
+
+The NNDiary Back End
+
+* Diary Messages:: What makes a message valid for nndiary.
+* Running NNDiary:: NNDiary has two modes of operation.
+* Customizing NNDiary:: Bells and whistles.
+
+The Gnus Diary Library
+
+* Diary Summary Line Format:: A nicer summary buffer line format.
+* Diary Articles Sorting:: A nicer way to sort messages.
+* Diary Headers Generation:: Not doing it manually.
+* Diary Group Parameters:: Not handling them manually.
+
+Gnus Unplugged
+
+* 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 Visuals:: Ways that the agent may effect your summary buffer.
+* Agent as Cache:: The Agent is a big cache too.
+* Agent Expiry:: How to make old articles go away.
+* Agent Regeneration:: How to recover from lost connections and other accidents.
+* Agent and IMAP:: How to use the Agent with @acronym{IMAP}.
+* 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.
+* Agent Caveats:: What you think it'll do and what it does.
+
+Agent Categories
+
+* Category Syntax:: What a category looks like.
+* Category Buffer:: A buffer for maintaining categories.
+* Category Variables:: Customize'r'Us.
+
+Agent Commands
+
+* Group Agent Commands:: Configure groups and fetch their contents.
+* Summary Agent Commands:: Manually select then fetch specific articles.
+* Server Agent Commands:: Select the servers that are supported by the agent.
+
+Scoring
+
+* 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 On Other Headers:: Scoring on non-standard headers.
+* 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.
+
+GroupLens
+
+* 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.
+
+Advanced Scoring
+
+* Advanced Scoring Syntax:: A definition.
+* Advanced Scoring Examples:: What they look like.
+* Advanced Scoring Tips:: Getting the most out of it.
+
+Various
+
+* 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.
+* Window Layout:: 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 tendinitis 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.
+* Predicate Specifiers:: Specifying predicates.
+* Moderation:: What to do if you're a moderator.
+* Image Enhancements:: Modern versions of Emacs/XEmacs can display images.
+* Fuzzy Matching:: What's the big fuzz?
+* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email.
+* Spam Package:: A package for filtering and processing spam.
+* Other modes:: Interaction with other modes.
+* Various Various:: Things that are really various.
+
+Formatting Variables
+
+* 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.
+* Positioning Point:: Moving point to a position after an operation.
+* Tabulation:: Tabulating your output.
+* Wide Characters:: Dealing with wide characters.
+
+Image Enhancements
+
+* X-Face:: Display a funky, teensy black-and-white image.
+* Face:: Display a funkier, teensier colored image.
+* Smileys:: Show all those happy faces the way they were
+ meant to be shown.
+* Picons:: How to display pictures of what you're reading.
+* XVarious:: Other XEmacsy Gnusey variables.
+
+Thwarting Email Spam
+
+* The problem of spam:: Some background, and some solutions
+* Anti-Spam Basics:: Simple steps to reduce the amount of spam.
+* SpamAssassin:: How to use external anti-spam tools.
+* Hashcash:: Reduce spam by burning CPU time.
+
+Spam Package
+
+* Spam Package Introduction::
+* Filtering Incoming Mail::
+* Detecting Spam in Groups::
+* Spam and Ham Processors::
+* Spam Package Configuration Examples::
+* Spam Back Ends::
+* Extending the Spam package::
+* Spam Statistics Package::
+
+Spam Statistics Package
+
+* Creating a spam-stat dictionary::
+* Splitting mail using spam-stat::
+* Low-level interface to the spam-stat dictionary::
+
+Appendices
+
+* XEmacs:: Requirements for installing under XEmacs.
+* History:: How Gnus got where it is today.
+* On Writing Manuals:: Why this is not a beginner's guide.
+* Terminology:: We use really difficult, like, words here.
+* Customization:: Tailoring Gnus to your needs.
+* Troubleshooting:: What you might try if things do not work.
+* Gnus Reference Guide:: Rilly, rilly technical stuff.
+* Emacs for Heathens:: A short introduction to Emacsian terms.
+* Frequently Asked Questions:: The Gnus FAQ
+
+History
+
+* Gnus Versions:: What Gnus versions have been released.
+* Other Gnus Versions:: Other Gnus versions that also have been released.
+* 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.
+* Gnus Development:: How Gnus is developed.
+* Contributors:: Oodles of people.
+* New Features:: Pointers to some of the new stuff in Gnus.
+
+New Features
+
+* ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus.
+* September Gnus:: The Thing Formally Known As Gnus 5.2/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.
+* Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9.
+* Oort Gnus:: It's big. It's far out. Gnus 5.10/5.11.
+
+Customization
+
+* 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.
+
+Gnus Reference Guide
+
+* Gnus Utility Functions:: Common functions and variable to use.
+* Back End 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.
+
+Back End Interface
+
+* Required Back End Functions:: Functions that must be implemented.
+* Optional Back End Functions:: Functions that need not be implemented.
+* Error Messaging:: How to get messages and report errors.
+* Writing New Back Ends:: Extending old back ends.
+* Hooking New Back Ends Into Gnus:: What has to be done on the Gnus end.
+* Mail-like Back Ends:: Some tips on mail back ends.
+
+Various File Formats
+
+* Active File Format:: Information on articles and groups available.
+* Newsgroups File Format:: Group descriptions.
+
+Emacs for Heathens
+
+* Keystrokes:: Entering text and executing commands.
+* Emacs Lisp:: The built-in Emacs programming language.
+
+@end detailmenu
+@end menu
+
+@node Starting Up
+@chapter Starting Gnus
+@cindex starting up
+
+If you haven't used Emacs much before using Gnus, read @ref{Emacs for
+Heathens} first.
+
+@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. If not, you should customize the variable
+@code{gnus-select-method} as described in @ref{Finding the News}. For a
+minimal setup for posting should also customize the variables
+@code{user-full-name} and @code{user-mail-address}.
+
+@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.el} 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.
+* New Groups:: What is Gnus supposed to do with new groups?
+* Changing Servers:: You may want to move from one server to another.
+* 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.
+* 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} @acronym{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. But do not use the local spool if your
+server is running Leafnode (which is a simple, standalone private news
+server); in this case, use @code{(nntp "localhost")}.
+
+@vindex gnus-nntpserver-file
+@cindex NNTPSERVER
+@cindex @acronym{NNTP} server
+If this variable is not set, Gnus will take a look at the
+@env{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 @acronym{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
+@vindex gnus-nntp-server
+You can also make Gnus prompt you interactively for the name of an
+@acronym{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. (Note that this
+will set @code{gnus-nntp-server}, which means that if you then @kbd{M-x
+gnus} later in the same Emacs session, Gnus will contact the same
+server.)
+
+@findex gnus-group-browse-foreign-server
+@kindex B (Group)
+However, if you use one @acronym{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} back end 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 (@pxref{Startup Files}), 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.) Also @pxref{Group 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
+@file{.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.)
+
+@findex gnus-slave
+Anyway, 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) @file{.newsrc} file.
+
+If the @file{.newsrc*} files have not been saved in the master when the
+slave starts, you may be prompted as to whether to read an auto-save
+file. If you answer ``yes'', the unsaved changes to the master will be
+incorporated into the slave. If you answer ``no'', the slave may see some
+messages as unread that have been read in the master.
+
+
+
+@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 back ends 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 its
+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.
+
+@item gnus-subscribe-topics
+@vindex gnus-subscribe-topics
+Put the groups into the topic that has a matching @code{subscribe} topic
+parameter (@pxref{Topic Parameters}). For instance, a @code{subscribe}
+topic parameter that looks like
+
+@example
+"nnslashdot"
+@end example
+
+will mean that all groups that match that regex will be subscribed under
+that topic.
+
+If no topics match the groups, the groups will be subscribed in the
+top-level topic.
+
+@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 back ends (@code{nnml}, @code{nnbabyl},
+@code{nnfolder}, @code{nnmbox}, @code{nnmh}, and @code{nnmaildir})
+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 @acronym{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
+@acronym{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.
+
+@kindex M-x gnus-group-clear-data
+@findex gnus-group-clear-data
+Clear the data from the current group only---nix out marks and the
+list of read articles (@code{gnus-group-clear-data}).
+
+After changing servers, you @strong{must} move the cache hierarchy away,
+since the cached articles will have wrong article numbers, which will
+affect which articles Gnus thinks are read.
+@code{gnus-group-clear-data-on-native-groups} will ask you if you want
+to have it done automatically; for @code{gnus-group-clear-data}, you
+can use @kbd{M-x gnus-cache-move-cache} (but beware, it will move the
+cache for all groups).
+
+
+@node Startup Files
+@section Startup Files
+@cindex startup files
+@cindex .newsrc
+@cindex .newsrc.el
+@cindex .newsrc.eld
+
+Most common Unix news readers use a shared startup file called
+@file{.newsrc}. This file contains all the information about what
+groups are subscribed, and which articles in these groups have been
+read.
+
+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
+@vindex gnus-read-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? Similarly, setting
+@code{gnus-read-newsrc-file} to @code{nil} makes Gnus ignore the
+@file{.newsrc} file and any @file{.newsrc-SERVER} files, which can be
+convenient if you use a different news reader occasionally, and you
+want to read a different subset of the available groups with that
+news reader.
+
+@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
+@vindex gnus-backup-startup-file
+@vindex version-control
+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.
+If you want version control for this file, set
+@code{gnus-backup-startup-file}. It respects the same values as the
+@code{version-control} variable.
+
+@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
+@vindex gnus-site-init-file
+When Gnus starts, it will read the @code{gnus-site-init-file}
+(@file{.../site-lisp/gnus-init} 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). If Emacs was invoked with
+the @option{-q} or @option{--no-init-file} options (@pxref{Initial
+Options, ,Initial Options, emacs, The Emacs Manual}), Gnus doesn't read
+@code{gnus-init-file}.
+
+
+@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 @file{.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.
+
+Some news servers (old versions of Leafnode and old versions of INN, for
+instance) do not support the @code{LIST ACTIVE group}. For these
+servers, @code{nil} is probably the most efficient value for this
+variable.
+
+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
+@acronym{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.
+
+If you think that starting up Gnus takes too long, try all the three
+different values for this variable and see what works best for you.
+
+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-setup-news-hook
+@vindex gnus-setup-news-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 @file{.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 Group Buffer
+@chapter Group Buffer
+@cindex group buffer
+
+@c Alex Schroeder suggests to rearrange this as follows:
+@c
+@c <kensanata> ok, just save it for reference. I'll go to bed in a minute.
+@c 1. Selecting a Group, 2. (new) Finding a Group, 3. Group Levels,
+@c 4. Subscription Commands, 5. Group Maneuvering, 6. Group Data,
+@c 7. Group Score, 8. Group Buffer Format
+@c <kensanata> Group Levels should have more information on levels 5 to 9. I
+@c suggest to split the 4th paragraph ("Gnus considers groups...") as follows:
+@c <kensanata> First, "Gnus considers groups... (default 9)."
+@c <kensanata> New, a table summarizing what levels 1 to 9 mean.
+@c <kensanata> Third, "Gnus treats subscribed ... reasons of efficiency"
+@c <kensanata> Then expand the next paragraph or add some more to it.
+@c This short one sentence explains levels 1 and 2, therefore I understand
+@c that I should keep important news at 3 and boring news at 4.
+@c Say so! Then go on to explain why I should bother with levels 6 to 9.
+@c Maybe keep those that you don't want to read temporarily at 6,
+@c those that you never want to read at 8, those that offend your
+@c human rights at 9...
+
+
+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.
+
+@iftex
+@iflatex
+\gnusfigure{The Group Buffer}{320}{
+\put(75,50){\epsfig{figure=ps/group,height=9cm}}
+\put(120,37){\makebox(0,0)[t]{Buffer name}}
+\put(120,38){\vector(1,2){10}}
+\put(40,60){\makebox(0,0)[r]{Mode line}}
+\put(40,58){\vector(1,0){30}}
+\put(200,28){\makebox(0,0)[t]{Native select method}}
+\put(200,26){\vector(-1,2){15}}
+}
+@end iflatex
+@end iftex
+
+@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.
+* Subscription Commands:: Unsubscribing, killing, subscribing.
+* Group Data:: Changing the info for a group.
+* 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 Mode Line Specification:: The group buffer mode line.
+* Group Highlighting:: Having nice colors in the group buffer.
+@end menu
+
+You can customize the Group Mode tool bar, see @kbd{M-x
+customize-apropos RET gnus-group-tool-bar}. This feature is only
+available in Emacs.
+
+The tool bar icons are now (de)activated correctly depending on the
+cursor position. Therefore, moving around in the Group Buffer is
+slower. You can disable this via the variable
+@code{gnus-group-update-tool-bar}. Its default value depends on your
+Emacs version.
+
+@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:%B%(%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. @xref{Positioning
+Point}. 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 U
+Number of unseen articles.
+
+@item t
+Estimated total number of articles. (This is really @var{max-number}
+minus @var{min-number} plus 1.)
+
+Gnus uses this estimation because the @acronym{NNTP} protocol provides
+efficient access to @var{max-number} and @var{min-number} but getting
+the true unread message count is not possible efficiently. For
+hysterical raisins, even the mail back ends, where the true number of
+unread messages might be available efficiently, use the same limited
+interface. To remove this restriction from Gnus means that the back
+end interface has to be changed, which is not an easy job. If you
+want to work on this, please contact the Gnus mailing list.
+
+@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 C
+Group comment (@pxref{Group Parameters}) or group name if there is no
+comment element in the group parameters.
+
+@item D
+Newsgroup description. You need to read the group descriptions
+before these will appear, and to do that, you either have to set
+@code{gnus-read-active-file} or use the group buffer @kbd{M-d}
+command.
+
+@item o
+@samp{m} if moderated.
+
+@item O
+@samp{(m)} if moderated.
+
+@item s
+Select method.
+
+@item B
+If the summary buffer for the group is open or not.
+
+@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.e.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 p
+@samp{#} (@code{gnus-process-mark}) if the group is process marked.
+
+@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 Mode Line Specification
+@subsection Group Mode Line Specification
+@cindex group mode line
+
+@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 @code{(@var{form} . @var{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
+(cond (window-system
+ (setq custom-background-mode 'light)
+ (defface my-group-face-1
+ '((t (:foreground "Red" :bold t))) "First group face")
+ (defface my-group-face-2
+ '((t (:foreground "DarkSeaGreen4" :bold t)))
+ "Second group face")
+ (defface my-group-face-3
+ '((t (:foreground "Green4" :bold t))) "Third group face")
+ (defface my-group-face-4
+ '((t (:foreground "SteelBlue" :bold t))) "Fourth group face")
+ (defface my-group-face-5
+ '((t (:foreground "Blue" :bold t))) "Fifth group face")))
+
+(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,
+@var{max-number} minus @var{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 @code{abs(@var{n})} oldest articles.
+
+Thus, @kbd{SPC} enters the group normally, @kbd{C-u SPC} offers old
+articles, @kbd{C-u 4 2 SPC} fetches the 42 newest articles, and @kbd{C-u
+- 4 2 SPC} fetches the 42 oldest ones.
+
+When you are in the group (in the Summary buffer), you can type
+@kbd{M-g} to fetch new articles, or @kbd{C-u M-g} to also show the old
+ones.
+
+@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 C-M-RET
+@kindex C-M-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. If it is @code{nil}, no groups are
+considered big. The default value is 200. 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 (@var{-n}), the @var{n} oldest articles will be
+fetched. If it is positive, the @var{n} articles that have arrived
+most recently will be fetched.
+
+@vindex gnus-large-ephemeral-newsgroup
+@code{gnus-large-ephemeral-newsgroup} is the same as
+@code{gnus-large-newsgroup}, but is only used for ephemeral
+newsgroups.
+
+@vindex gnus-maximum-newsgroup
+In groups in some news servers, there might be a big gap between a few
+very old articles that will never be expired and the recent ones. In
+such a case, the server will return the data like @code{(1 . 30000000)}
+for the @code{LIST ACTIVE group} command, for example. Even if there
+are actually only the articles 1-10 and 29999900-30000000, Gnus doesn't
+know it at first and prepares for getting 30000000 articles. However,
+it will consume hundreds megabytes of memories and might make Emacs get
+stuck as the case may be. If you use such news servers, set the
+variable @code{gnus-maximum-newsgroup} to a positive number. The value
+means that Gnus ignores articles other than this number of the latest
+ones in every group. For instance, the value 10000 makes Gnus get only
+the articles 29990001-30000000 (if the latest article number is 30000000
+in a group). Note that setting this variable to a number might prevent
+you from reading very old articles. The default value of the variable
+@code{gnus-maximum-newsgroup} is @code{nil}, which means Gnus never
+ignores old articles.
+
+@vindex gnus-select-group-hook
+@vindex gnus-auto-select-first
+@vindex gnus-auto-select-subject
+If @code{gnus-auto-select-first} is non-@code{nil}, select an article
+automatically when entering a group with the @kbd{SPACE} command.
+Which article this is is controlled by the
+@code{gnus-auto-select-subject} variable. Valid values for this
+variable are:
+
+@table @code
+
+@item unread
+Place point on the subject line of the first unread article.
+
+@item first
+Place point on the subject line of the first article.
+
+@item unseen
+Place point on the subject line of the first unseen article.
+
+@item unseen-or-unread
+Place point on the subject line of the first unseen article, and if
+there is no such article, place point on the subject line of the first
+unread article.
+
+@item best
+Place point on the subject line of the highest-scored unread article.
+
+@end table
+
+This variable can also be a function. In that case, that function
+will be called to place point on a subject line.
+
+If you want to prevent automatic selection in some group (say, in a
+binary group with Huge articles) you can set the
+@code{gnus-auto-select-first} 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 @acronym{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).
+
+Maybe the following description of the default behavior of Gnus helps to
+understand what these levels are all about. By default, Gnus shows you
+subscribed nonempty groups, but by hitting @kbd{L} you can have it show
+empty subscribed groups and unsubscribed groups, too. Type @kbd{l} to
+go back to showing nonempty subscribed groups again. Thus, unsubscribed
+groups are hidden, in a way.
+
+Zombie and killed groups are similar to unsubscribed groups in that they
+are hidden by default. But they are different from subscribed and
+unsubscribed groups in that Gnus doesn't ask the news server for
+information (number of messages, number of unread messages) on zombie
+and killed groups. Normally, you use @kbd{C-k} to kill the groups you
+aren't interested in. If most groups are killed, Gnus is faster.
+
+Why does Gnus distinguish between zombie and killed groups? Well, when
+a new group arrives on the server, Gnus by default makes it a zombie
+group. This means that you are normally not bothered with new groups,
+but you can type @kbd{A z} to get a list of all new groups. Subscribe
+the ones you like and kill the ones you don't want. (@kbd{A k} shows a
+list of killed groups.)
+
+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.
+
+If this variable is @code{best}, Gnus will make the next newsgroup the
+one with the best level.
+
+@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 have Gnus assign a score
+to each group through the mechanism described below. 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.
+
+Changes from the group editing commands are stored in
+@file{~/.newsrc.eld} (@code{gnus-startup-file}). An alternative is the
+variable @code{gnus-parameters}, @xref{Group Parameters}.
+
+@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 @acronym{NNTP} groups (@pxref{Browse Foreign Server}).
+
+@item G M
+@kindex G M (Group)
+@findex gnus-group-read-ephemeral-group
+Make an ephemeral group (@code{gnus-group-read-ephemeral-group}). Gnus
+will prompt you for a name, a method and an @dfn{address}.
+
+@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 back ends.
+
+@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} back end (@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{mbox}, @code{babyl},
+@code{digest}, @code{news}, @code{rnews}, @code{mmdf}, @code{forward},
+@code{rfc934}, @code{rfc822-forward}, @code{mime-parts},
+@code{standard-digest}, @code{slack-digest}, @code{clari-briefs},
+@code{nsmail}, @code{outlook}, @code{oe-dbx}, and @code{mailman}. 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 Google
+@cindex nnweb
+@cindex gmane
+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{google}, @code{dejanews}, and @code{gmane}.
+@xref{Web Searches}.
+
+If you use the @code{google} search engine, you can limit the search
+to a particular group by using a match string like
+@samp{shaving group:alt.sysadmin.recovery}.
+
+@item G R
+@kindex G R (Group)
+@findex gnus-group-make-rss-group
+Make a group based on an @acronym{RSS} feed
+(@code{gnus-group-make-rss-group}). You will be prompted for an URL.
+@xref{RSS}.
+
+@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} groups), 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 @acronym{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.
+
+Some parameters have correspondent customizable variables, each of which
+is an alist of regexps and values.
+
+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.
+
+See also @code{gnus-parameter-to-address-alist}.
+
+@item to-list
+@cindex to-list
+Address used when doing @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
+
+@findex gnus-mailing-list-mode
+@cindex mail list groups
+If this variable is set, @code{gnus-mailing-list-mode} is turned on when
+entering summary buffer.
+
+See also @code{gnus-parameter-to-list-alist}.
+
+@anchor{subscribed}
+@item subscribed
+@cindex subscribed
+@cindex Mail-Followup-To
+@findex gnus-find-subscribed-addresses
+If this parameter is set to @code{t}, Gnus will consider the
+to-address and to-list parameters for this group as addresses of
+mailing lists you are subscribed to. Giving Gnus this information is
+(only) a first step in getting it to generate correct Mail-Followup-To
+headers for your posts to these lists. The second step is to put the
+following in your @file{.gnus.el}
+
+@lisp
+(setq message-subscribed-address-functions
+ '(gnus-find-subscribed-addresses))
+@end lisp
+
+@xref{Mailing Lists, ,Mailing Lists, message, The Message Manual}, for
+a complete treatment of available MFT support.
+
+@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.
+
+This parameter cannot be set via @code{gnus-parameters}. See
+@code{gnus-permanently-visible-groups} as an alternative.
+
+@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, and for the header to be hidden
+if @code{reply-to} is part of @code{gnus-boring-article-headers}. 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. That 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}).
+
+@strong{Caveat}: Adding @code{(gcc-self . t)} to the parameter list of
+@code{nntp} groups (or the like) isn't valid. An @code{nntp} server
+doesn't accept articles.
+
+@item auto-expire
+@cindex auto-expire
+@cindex expiring mail
+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}.
+
+See also @code{gnus-auto-expirable-newsgroups}.
+
+@item total-expire
+@cindex total-expire
+@cindex expiring mail
+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.
+
+See also @code{gnus-total-expirable-newsgroups}.
+
+@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}
+(@pxref{Expiring Mail}) 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 expiry-target
+@cindex expiry-target
+Where expired messages end up. This parameter overrides
+@code{nnmail-expiry-target}.
+
+@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
+@cindex 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
+@cindex 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 an integer
+Display the last @var{integer} articles in the group. This is the same as
+entering the group with @kbd{C-u @var{integer}}.
+
+@item default
+Display the default visible articles, which normally includes unread and
+ticked articles.
+
+@item an array
+Display articles that satisfy a predicate.
+
+Here are some examples:
+
+@table @code
+@item [unread]
+Display only unread articles.
+
+@item [not expire]
+Display everything except expirable articles.
+
+@item [and (not reply) (not expire)]
+Display everything except expirable and articles you've already
+responded to.
+@end table
+
+The available operators are @code{not}, @code{and} and @code{or}.
+Predicates include @code{tick}, @code{unsend}, @code{undownload},
+@code{unread}, @code{dormant}, @code{expire}, @code{reply},
+@code{killed}, @code{bookmark}, @code{score}, @code{save},
+@code{cache}, @code{forward}, @code{unseen} and @code{recent}.
+
+@end table
+
+The @code{display} parameter works by limiting the summary buffer to
+the subset specified. You can pop the limit by using the @kbd{/ w}
+command (@pxref{Limiting}).
+
+@item comment
+@cindex comment
+Elements that look like @code{(comment . "This is a comment")} are
+arbitrary comments on the group. You can display comments in the
+group line (@pxref{Group Line Specification}).
+
+@item charset
+@cindex charset
+Elements that look like @code{(charset . iso-8859-1)} will make
+@code{iso-8859-1} the default charset; that is, the charset that will be
+used for all articles that do not specify a charset.
+
+See also @code{gnus-group-charset-alist}.
+
+@item ignored-charsets
+@cindex ignored-charset
+Elements that look like @code{(ignored-charsets x-unknown iso-8859-1)}
+will make @code{iso-8859-1} and @code{x-unknown} ignored; that is, the
+default charset will be used for decoding articles.
+
+See also @code{gnus-group-ignored-charsets-alist}.
+
+@item posting-style
+@cindex posting-style
+You can store additional posting style information for this group
+here (@pxref{Posting Styles}). The format is that of an entry in the
+@code{gnus-posting-styles} alist, except that there's no regexp matching
+the group name (of course). Style elements in this group parameter will
+take precedence over the ones found in @code{gnus-posting-styles}.
+
+For instance, if you want a funky name and signature in this group only,
+instead of hacking @code{gnus-posting-styles}, you could put something
+like this in the group parameters:
+
+@example
+(posting-style
+ (name "Funky Name")
+ ("X-My-Header" "Funky Value")
+ (signature "Funky Signature"))
+@end example
+
+@item post-method
+@cindex post-method
+If it is set, the value is used as the method for posting message
+instead of @code{gnus-post-method}.
+
+@item banner
+@cindex banner
+An item like @code{(banner . @var{regexp})} causes any part of an article
+that matches the regular expression @var{regexp} to be stripped. Instead of
+@var{regexp}, you can also use the symbol @code{signature} which strips the
+last signature or any of the elements of the alist
+@code{gnus-article-banner-alist}.
+
+@item sieve
+@cindex sieve
+This parameter contains a Sieve test that should match incoming mail
+that should be placed in this group. From this group parameter, a
+Sieve @samp{IF} control structure is generated, having the test as the
+condition and @samp{fileinto "group.name";} as the body.
+
+For example, if the @samp{INBOX.list.sieve} group has the @code{(sieve
+address "sender" "sieve-admin@@extundo.com")} group parameter, when
+translating the group parameter into a Sieve script (@pxref{Sieve
+Commands}) the following Sieve code is generated:
+
+@example
+if address \"sender\" \"sieve-admin@@extundo.com\" @{
+ fileinto \"INBOX.list.sieve\";
+@}
+@end example
+
+The Sieve language is described in RFC 3028. @xref{Top, Emacs Sieve,
+Top, sieve, Emacs Sieve}.
+
+@item (agent parameters)
+If the agent has been enabled, you can set any of the its parameters
+to control the behavior of the agent in individual groups. See Agent
+Parameters in @ref{Category Syntax}. Most users will choose to set
+agent parameters in either an agent category or group topic to
+minimize the configuration effort.
+
+@item (@var{variable} @var{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.
+
+Note that this feature sets the variable locally to the summary buffer.
+But some variables are evaluated in the article buffer, or in the
+message buffer (of a reply or followup or otherwise newly created
+message). As a workaround, it might help to add the variable in
+question to @code{gnus-newsgroup-variables}. @xref{Various Summary
+Stuff}. So if you want to set @code{message-from-style} via the group
+parameters, then you may need the following statement elsewhere in your
+@file{~/.gnus} file:
+
+@lisp
+(add-to-list 'gnus-newsgroup-variables 'message-from-style)
+@end lisp
+
+@vindex gnus-list-identifiers
+A use for this feature is to remove a mailing list identifier tag in
+the subject fields of articles. E.g. if the news group
+
+@example
+nntp+news.gnus.org:gmane.text.docbook.apps
+@end example
+
+has the tag @samp{DOC-BOOK-APPS:} in the subject of all articles, this
+tag can be removed from the article subjects in the summary buffer for
+the group by putting @code{(gnus-list-identifiers "DOCBOOK-APPS:")}
+into the group parameters for the group.
+
+This can also be used as a group-specific hook function. 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 (meaningless) result of the
+@code{(ding)} form.
+
+Alternatively, since the VARIABLE becomes local to the group, this
+pattern can be used to temporarily change a hook. For example, if the
+following is added to a group parameter
+
+@lisp
+(gnus-summary-prepared-hook
+ '(lambda nil (local-set-key "d" (local-key-binding "n"))))
+@end lisp
+
+when the group is entered, the 'd' key will not mark the article as
+expired.
+
+@end table
+
+Use the @kbd{G p} or the @kbd{G c} command to edit group parameters of a
+group. (@kbd{G p} presents you with a Lisp-based interface, @kbd{G c}
+presents you with a Customize-like interface. The latter helps avoid
+silly Lisp errors.) You might also be interested in reading about topic
+parameters (@pxref{Topic Parameters}).
+
+@vindex gnus-parameters
+Group parameters can be set via the @code{gnus-parameters} variable too.
+But some variables, such as @code{visible}, have no effect (For this
+case see @code{gnus-permanently-visible-groups} as an alternative.).
+For example:
+
+@lisp
+(setq gnus-parameters
+ '(("mail\\..*"
+ (gnus-show-threads nil)
+ (gnus-use-scoring nil)
+ (gnus-summary-line-format
+ "%U%R%z%I%(%[%d:%ub%-23,23f%]%) %s\n")
+ (gcc-self . t)
+ (display . all))
+
+ ("^nnimap:\\(foo.bar\\)$"
+ (to-group . "\\1"))
+
+ ("mail\\.me"
+ (gnus-use-scoring t))
+
+ ("list\\..*"
+ (total-expire . t)
+ (broken-reply-to . t))))
+@end lisp
+
+String value of parameters will be subjected to regexp substitution, as
+the @code{to-group} example shows.
+
+@vindex gnus-parameters-case-fold-search
+By default, whether comparing the group name and one of those regexps
+specified in @code{gnus-parameters} is done in a case-sensitive manner
+or a case-insensitive manner depends on the value of
+@code{case-fold-search} at the time when the comparison is done. The
+value of @code{case-fold-search} is typically @code{t}; it means, for
+example, the element @code{("INBOX\\.FOO" (total-expire . t))} might be
+applied to both the @samp{INBOX.FOO} group and the @samp{INBOX.foo}
+group. If you want to make those regexps always case-sensitive, set the
+value of the @code{gnus-parameters-case-fold-search} variable to
+@code{nil}. Otherwise, set it to @code{t} if you want to compare them
+always in a case-insensitive manner.
+
+
+@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}).
+
+@item A c
+@kindex A c (Group)
+@findex gnus-group-list-cached
+List all groups with cached articles (@code{gnus-group-list-cached}).
+
+@item A ?
+@kindex A ? (Group)
+@findex gnus-group-list-dormant
+List all groups with dormant articles (@code{gnus-group-list-dormant}).
+
+@item A /
+@kindex A / (Group)
+@findex gnus-group-list-limit
+List groups limited within the current selection
+(@code{gnus-group-list-limit}).
+
+@item A f
+@kindex A f (Group)
+@findex gnus-group-list-flush
+Flush groups from the current selection (@code{gnus-group-list-flush}).
+
+@item A p
+@kindex A p (Group)
+@findex gnus-group-list-plus
+List groups plus the current selection (@code{gnus-group-list-plus}).
+
+@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.
+
+@item gnus-group-sort-by-server
+@findex gnus-group-sort-by-server
+Sort alphabetically on the Gnus server name.
+
+
+@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 back end name@*
+(@code{gnus-group-sort-groups-by-method}).
+
+@item G S n
+@kindex G S n (Group)
+@findex gnus-group-sort-groups-by-real-name
+Sort the group buffer alphabetically by real (unprefixed) group name
+(@code{gnus-group-sort-groups-by-real-name}).
+
+@end table
+
+All the commands below obey the process/prefix convention
+(@pxref{Process/Prefix}).
+
+When given a symbolic prefix (@pxref{Symbolic Prefixes}), 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 groups 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 groups 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 groups 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 groups 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 groups 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 groups alphabetically by back end name@*
+(@code{gnus-group-sort-selected-groups-by-method}).
+
+@item G P n
+@kindex G P n (Group)
+@findex gnus-group-sort-selected-groups-by-real-name
+Sort the groups alphabetically by real (unprefixed) group name
+(@code{gnus-group-sort-selected-groups-by-real-name}).
+
+@item G P s
+@kindex G P s (Group)
+@findex gnus-group-sort-selected-groups
+Sort the groups according to @code{gnus-group-sort-function}.
+
+@end table
+
+And finally, note that you can use @kbd{C-k} and @kbd{C-y} to manually
+move groups around.
+
+
+@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
+@cindex expiring mail
+Run all expirable articles in the current group through the expiry
+process (if any) (@code{gnus-group-expire-articles}). That is, delete
+all expirable articles in the group that have been around for a while.
+(@pxref{Expiring Mail}).
+
+@item C-c C-M-x
+@kindex C-c C-M-x (Group)
+@findex gnus-group-expire-all-groups
+@cindex expiring mail
+Run all expirable 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 d
+@kindex d (Browse)
+@findex gnus-browse-describe-group
+Describe the current group (@code{gnus-browse-describe-group}).
+
+@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
+@vindex gnus-after-exiting-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.
+
+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!
+
+@iftex
+@iflatex
+\gnusfigure{Group Topics}{400}{
+\put(75,50){\epsfig{figure=ps/group-topic,height=9cm}}
+}
+@end iflatex
+@end iftex
+
+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@dots{} Nice tune, that@dots{} la la la@dots{} 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. Put the following line in your
+@file{~/.gnus.el} file:
+
+@lisp
+(add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
+@end lisp
+
+@menu
+* Topic Commands:: Interactive E-Z commands.
+* Topic Variables:: How to customize the topics the Lisp Way.
+* 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 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.
+
+In general, the following kinds of operations are possible on topics.
+First of all, you want to create topics. Secondly, you want to put
+groups in topics and to move them around until you have an order you
+like. The third kind of operation is to show/hide parts of the whole
+shebang. You might want to hide a topic including its subtopics and
+groups, to get a better overview of the other groups.
+
+Here is a list of the basic keys that you might need to set up topics
+the way you like.
+
+@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 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}).
+
+@end table
+
+The following two keys can be used to move groups and topics around.
+They work like the well-known cut and paste. @kbd{C-k} is like cut and
+@kbd{C-y} is like paste. Of course, this being Emacs, we use the terms
+kill and yank rather than cut and paste.
+
+@table @kbd
+
+@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.
+
+So, to move a topic to the beginning of the list of topics, just hit
+@kbd{C-k} on it. This is like the ``cut'' part of cut and paste. Then,
+move the cursor to the beginning of the buffer (just below the ``Gnus''
+topic) and hit @kbd{C-y}. This is like the ``paste'' part of cut and
+paste. Like I said -- E-Z.
+
+You can use @kbd{C-k} and @kbd{C-y} on groups as well as on topics. So
+you can move topics around as well as groups.
+
+@end table
+
+After setting up the topics the way you like them, you might wish to
+hide a topic, or to show it again. That's why we have the following
+key.
+
+@table @kbd
+
+@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.
+
+@end table
+
+Now for a list of other commands, in no particular order.
+
+@table @kbd
+
+@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 j
+@kindex T j (Topic)
+@findex gnus-topic-jump-to-topic
+Go to a topic (@code{gnus-topic-jump-to-topic}).
+
+@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 h
+@kindex T h (Topic)
+@findex gnus-topic-hide-topic
+Hide the current topic (@code{gnus-topic-hide-topic}). If given
+a prefix, hide the topic permanently.
+
+@item T s
+@kindex T s (Topic)
+@findex gnus-topic-show-topic
+Show the current topic (@code{gnus-topic-show-topic}). If given
+a prefix, show the topic permanently.
+
+@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}). This command works recursively on
+sub-topics unless given a prefix.
+
+@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}). This command works recursively on
+sub-topics unless given a prefix.
+
+@item C-c C-x
+@kindex C-c C-x (Topic)
+@findex gnus-topic-expire-articles
+@cindex expiring mail
+Run all expirable articles in the current group or topic through the
+expiry process (if any)
+(@code{gnus-topic-expire-articles}). (@pxref{Expiring Mail}).
+
+@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 T M-n
+@kindex T M-n (Topic)
+@findex gnus-topic-goto-next-topic
+Go to the next topic (@code{gnus-topic-goto-next-topic}).
+
+@item T M-p
+@kindex T M-p (Topic)
+@findex gnus-topic-goto-previous-topic
+Go to the next topic (@code{gnus-topic-goto-previous-topic}).
+
+@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 Variables
+@subsection Topic Variables
+@cindex topic variables
+
+The previous section told you how to tell Gnus which topics to display.
+This section explains how to tell Gnus what to display about each topic.
+
+@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 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 back end name
+(@code{gnus-topic-sort-groups-by-method}).
+
+@item T S e
+@kindex T S e (Topic)
+@findex gnus-topic-sort-groups-by-server
+Sort the current topic alphabetically by server name
+(@code{gnus-topic-sort-groups-by-server}).
+
+@item T S s
+@kindex T S s (Topic)
+@findex gnus-topic-sort-groups
+Sort the current topic according to the function(s) given by the
+@code{gnus-group-sort-function} variable
+(@code{gnus-topic-sort-groups}).
+
+@end table
+
+When given a prefix argument, all these commands will sort in reverse
+order. @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
+@group
+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 group
+@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}). When the agent is
+enabled, all agent parameters (See Agent Parameters in @ref{Category
+Syntax}) are also valid topic parameters.
+
+In addition, the following parameters are only valid as topic
+parameters:
+
+@table @code
+@item subscribe
+When subscribing new groups by topic (@pxref{Subscription Methods}), the
+@code{subscribe} topic parameter says what groups go in what topic. Its
+value should be a regexp to match the groups that should go in that
+topic.
+
+@item subscribe-level
+When subscribing new groups by topic (see the @code{subscribe} parameter),
+the group will be subscribed with the level specified in the
+@code{subscribe-level} instead of @code{gnus-level-default-subscribed}.
+
+@end table
+
+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
+@group
+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 group
+@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.
+* Sieve Commands:: Managing Sieve scripts.
+@end menu
+
+@table @kbd
+
+@item v
+@kindex v (Group)
+@cindex keys, reserved for users (Group)
+The key @kbd{v} is reserved for users. You can bind it to some
+command or better use it as a prefix key. For example:
+
+@lisp
+(define-key gnus-group-mode-map (kbd "v j d")
+ (lambda ()
+ (interactive)
+ (gnus-group-jump-to-group "nndraft:drafts")))
+@end lisp
+
+On keys reserved for users in Emacs and on keybindings in general
+@xref{Keymaps, Keymaps, , emacs, The Emacs Editor}.
+
+@item ^
+@kindex ^ (Group)
+@findex gnus-group-enter-server-mode
+Enter the server buffer (@code{gnus-group-enter-server-mode}).
+@xref{Server Buffer}.
+
+@item a
+@kindex a (Group)
+@findex gnus-group-post-news
+Start composing a message (a news by default)
+(@code{gnus-group-post-news}). If given a prefix, post to the group
+under the point. If the prefix is 1, prompt for a group to post to.
+Contrary to what the name of this function suggests, the prepared
+article might be a mail instead of a news, if a mail group is specified
+with the prefix argument. @xref{Composing Messages}.
+
+@item m
+@kindex m (Group)
+@findex gnus-group-mail
+Mail a message somewhere (@code{gnus-group-mail}). If given a prefix,
+use the posting style of the group under the point. If the prefix is 1,
+prompt for a group name to find the posting style.
+@xref{Composing Messages}.
+
+@item i
+@kindex i (Group)
+@findex gnus-group-news
+Start composing a news (@code{gnus-group-news}). If given a prefix,
+post to the group under the point. If the prefix is 1, prompt
+for group to post to. @xref{Composing Messages}.
+
+This function actually prepares a news even when using mail groups.
+This is useful for ``posting'' messages to mail groups without actually
+sending them over the network: they're just saved directly to the group
+in question. The corresponding back end must have a request-post method
+for this to work though.
+
+@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.
+
+@item gnus-group-name-charset-method-alist
+@vindex gnus-group-name-charset-method-alist
+An alist of method and the charset for group names. It is used to show
+non-@acronym{ASCII} group names.
+
+For example:
+@lisp
+(setq gnus-group-name-charset-method-alist
+ '(((nntp "news.com.cn") . cn-gb-2312)))
+@end lisp
+
+@item gnus-group-name-charset-group-alist
+@cindex UTF-8 group names
+@vindex gnus-group-name-charset-group-alist
+An alist of regexp of group name and the charset for group names. It
+is used to show non-@acronym{ASCII} group names. @code{((".*"
+utf-8))} is the default value if UTF-8 is supported, otherwise the
+default is @code{nil}.
+
+For example:
+@lisp
+(setq gnus-group-name-charset-group-alist
+ '(("\\.com\\.cn:" . cn-gb-2312)))
+@end lisp
+
+@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
+back end(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 @acronym{FAQ} for the current group
+(@code{gnus-group-fetch-faq}). Gnus will try to get the @acronym{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 c
+@kindex H c (Group)
+@findex gnus-group-fetch-charter
+@vindex gnus-group-charter-alist
+@cindex charter
+Try to open the charter for the current group in a web browser
+(@code{gnus-group-fetch-charter}). Query for a group if given a
+prefix argument.
+
+Gnus will use @code{gnus-group-charter-alist} to find the location of
+the charter. If no location is known, Gnus will fetch the control
+messages for the group, which in some cases includes the charter.
+
+@item H C
+@kindex H C (Group)
+@findex gnus-group-fetch-control
+@vindex gnus-group-fetch-control-use-browse-url
+@cindex control message
+Fetch the control messages for the group from the archive at
+@code{ftp.isc.org} (@code{gnus-group-fetch-control}). Query for a
+group if given a prefix argument.
+
+If @code{gnus-group-fetch-control-use-browse-url} is non-@code{nil},
+Gnus will open the control messages in a browser using
+@code{browse-url}. Otherwise they are fetched using @code{ange-ftp}
+and displayed in an ephemeral group.
+
+Note that the control messages are compressed. To use this command
+you need to turn on @code{auto-compression-mode} (@pxref{Compressed
+Files, ,Compressed Files, emacs, The Emacs Manual}).
+
+@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
+
+If you would like greater control of the time format, you can use a
+user-defined format spec. Something like the following should do the
+trick:
+
+@lisp
+(setq gnus-group-line-format
+ "%M\%S\%p\%P\%5y: %(%-40,40g%) %ud\n")
+(defun gnus-user-format-function-d (headers)
+ (let ((time (gnus-group-timestamp gnus-tmp-group)))
+ (if time
+ (format-time-string "%b %d %H:%M" time)
+ "")))
+@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.el}) (@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 Sieve Commands
+@subsection Sieve Commands
+@cindex group sieve commands
+
+Sieve is a server-side mail filtering language. In Gnus you can use
+the @code{sieve} group parameter (@pxref{Group Parameters}) to specify
+sieve rules that should apply to each group. Gnus provides two
+commands to translate all these group parameters into a proper Sieve
+script that can be transfered to the server somehow.
+
+@vindex gnus-sieve-file
+@vindex gnus-sieve-region-start
+@vindex gnus-sieve-region-end
+The generated Sieve script is placed in @code{gnus-sieve-file} (by
+default @file{~/.sieve}). The Sieve code that Gnus generate is placed
+between two delimiters, @code{gnus-sieve-region-start} and
+@code{gnus-sieve-region-end}, so you may write additional Sieve code
+outside these delimiters that will not be removed the next time you
+regenerate the Sieve script.
+
+@vindex gnus-sieve-crosspost
+The variable @code{gnus-sieve-crosspost} controls how the Sieve script
+is generated. If it is non-@code{nil} (the default) articles is
+placed in all groups that have matching rules, otherwise the article
+is only placed in the group with the first matching rule. For
+example, the group parameter @samp{(sieve address "sender"
+"owner-ding@@hpc.uh.edu")} will generate the following piece of Sieve
+code if @code{gnus-sieve-crosspost} is @code{nil}. (When
+@code{gnus-sieve-crosspost} is non-@code{nil}, it looks the same
+except that the line containing the call to @code{stop} is removed.)
+
+@example
+if address "sender" "owner-ding@@hpc.uh.edu" @{
+ fileinto "INBOX.ding";
+ stop;
+@}
+@end example
+
+@xref{Top, Emacs Sieve, Top, sieve, Emacs Sieve}.
+
+@table @kbd
+
+@item D g
+@kindex D g (Group)
+@findex gnus-sieve-generate
+@vindex gnus-sieve-file
+@cindex generating sieve script
+Regenerate a Sieve script from the @code{sieve} group parameters and
+put you into the @code{gnus-sieve-file} without saving it.
+
+@item D u
+@kindex D u (Group)
+@findex gnus-sieve-update
+@vindex gnus-sieve-file
+@cindex updating sieve script
+Regenerates the Gnus managed part of @code{gnus-sieve-file} using the
+@code{sieve} group parameters, save the file and upload it to the
+server using the @code{sieveshell} program.
+
+@end table
+
+
+@node Summary Buffer
+@chapter 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.
+
+You can customize the Summary Mode tool bar, see @kbd{M-x
+customize-apropos RET gnus-summary-tool-bar}. This feature is only
+available in Emacs.
+
+@kindex v (Summary)
+@cindex keys, reserved for users (Summary)
+The key @kbd{v} is reserved for users. You can bind it to some
+command or better use it as a prefix key. For example:
+@lisp
+(define-key gnus-summary-mode-map (kbd "v -") "LrS") ;; lower subthread
+@end lisp
+
+@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.
+* Delayed Articles:: Send articles at a later time.
+* Marking Articles:: Marking articles as read, expirable, etc.
+* Limiting:: You can limit the summary buffer.
+* Threading:: How threads are made.
+* Sorting the Summary Buffer:: 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.
+* MIME Commands:: Doing MIMEy things with the articles.
+* Charsets:: Character set issues.
+* 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,
+ or reselecting the current group.
+* Crosspost Handling:: How crossposted articles are dealt with.
+* Duplicate Suppression:: An alternative when crosspost handling fails.
+* Security:: Decrypt and Verify.
+* Mailing List:: Mailing list minor mode.
+@end menu
+
+
+@node Summary Buffer Format
+@section Summary Buffer Format
+@cindex summary buffer format
+
+@iftex
+@iflatex
+\gnusfigure{The Summary Buffer}{180}{
+\put(0,0){\epsfig{figure=ps/summary,width=7.5cm}}
+\put(445,0){\makebox(0,0)[br]{\epsfig{figure=ps/summary-article,width=7.5cm}}}
+}
+@end iflatex
+@end iftex
+
+@menu
+* Summary Buffer Lines:: You can specify how summary lines should look.
+* To From Newsgroups:: How to not display your own name.
+* 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:
+
+@lisp
+(setq gnus-extract-address-components
+ 'mail-extract-address-components)
+@end lisp
+
+@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}).
+
+There should always be a colon or a point position marker on the line;
+the cursor always moves to the point position marker or the colon after
+performing an operation. (Of course, Gnus wouldn't be Gnus if it wasn't
+possible to change this. Just write a new function
+@code{gnus-goto-colon} which does whatever you like with the cursor.)
+@xref{Positioning Point}.
+
+The default string is @samp{%U%R%z%I%(%[%4L: %-23,23f%]%) %s\n}.
+
+The following format specification characters and extended format
+specification(s) are understood:
+
+@table @samp
+@item N
+Article number.
+@item S
+Subject string. List identifiers stripped,
+@code{gnus-list-identifiers}. @xref{Article Hiding}.
+@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 f
+The name, @code{To} header or the @code{Newsgroups} header (@pxref{To
+From Newsgroups}).
+@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. This specifier is not supported
+in some methods (like nnfolder).
+@item k
+Pretty-printed version of the number of characters in the article;
+for example, @samp{1.2k} or @samp{0.4M}.
+@item I
+Indentation based on thread level (@pxref{Customizing Threading}).
+@item B
+A complex trn-style thread tree, showing response-connecting trace
+lines. A thread could be drawn like this:
+
+@example
+>
++->
+| +->
+| | \->
+| | \->
+| \->
++->
+\->
+@end example
+
+You can customize the appearance with the following options. Note
+that it is possible to make the thread display look really neat by
+replacing the default @acronym{ASCII} characters with graphic
+line-drawing glyphs.
+@table @code
+@item gnus-sum-thread-tree-root
+@vindex gnus-sum-thread-tree-root
+Used for the root of a thread. If @code{nil}, use subject
+instead. The default is @samp{> }.
+
+@item gnus-sum-thread-tree-false-root
+@vindex gnus-sum-thread-tree-false-root
+Used for the false root of a thread (@pxref{Loose Threads}). If
+@code{nil}, use subject instead. The default is @samp{> }.
+
+@item gnus-sum-thread-tree-single-indent
+@vindex gnus-sum-thread-tree-single-indent
+Used for a thread with just one message. If @code{nil}, use subject
+instead. The default is @samp{}.
+
+@item gnus-sum-thread-tree-vertical
+@vindex gnus-sum-thread-tree-vertical
+Used for drawing a vertical line. The default is @samp{| }.
+
+@item gnus-sum-thread-tree-indent
+@vindex gnus-sum-thread-tree-indent
+Used for indenting. The default is @samp{ }.
+
+@item gnus-sum-thread-tree-leaf-with-other
+@vindex gnus-sum-thread-tree-leaf-with-other
+Used for a leaf with brothers. The default is @samp{+-> }.
+
+@item gnus-sum-thread-tree-single-leaf
+@vindex gnus-sum-thread-tree-single-leaf
+Used for a leaf without brothers. The default is @samp{\-> }
+
+@end table
+
+@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. @xref{Read Articles}.
+
+@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. @xref{Other Marks}.
+
+@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 *
+Desired cursor position (instead of after first colon).
+@item &user-date;
+Age sensitive date format. Various date format is defined in
+@code{gnus-user-date-format-alist}.
+@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-@var{x}}, where @var{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
+
+Text between @samp{%(} and @samp{%)} will be highlighted with
+@code{gnus-mouse-face} when the mouse point is placed inside the area.
+There can only be one such area.
+
+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 To From Newsgroups
+@subsection To From Newsgroups
+@cindex To
+@cindex Newsgroups
+
+In some groups (particularly in archive groups), the @code{From} header
+isn't very interesting, since all the articles there are written by
+you. To display the information in the @code{To} or @code{Newsgroups}
+headers instead, you need to decide three things: What information to
+gather; where to display it; and when to display it.
+
+@enumerate
+@item
+@vindex gnus-extra-headers
+The reading of extra header information is controlled by the
+@code{gnus-extra-headers}. This is a list of header symbols. For
+instance:
+
+@lisp
+(setq gnus-extra-headers
+ '(To Newsgroups X-Newsreader))
+@end lisp
+
+This will result in Gnus trying to obtain these three headers, and
+storing it in header structures for later easy retrieval.
+
+@item
+@findex gnus-extra-header
+The value of these extra headers can be accessed via the
+@code{gnus-extra-header} function. Here's a format line spec that will
+access the @code{X-Newsreader} header:
+
+@example
+"%~(form (gnus-extra-header 'X-Newsreader))@@"
+@end example
+
+@item
+@vindex gnus-ignored-from-addresses
+The @code{gnus-ignored-from-addresses} variable says when the @samp{%f}
+summary line spec returns the @code{To}, @code{Newsreader} or
+@code{From} header. If this regexp matches the contents of the
+@code{From} header, the value of the @code{To} or @code{Newsreader}
+headers are used instead.
+
+@end enumerate
+
+@vindex nnmail-extra-headers
+A related variable is @code{nnmail-extra-headers}, which controls when
+to include extra headers when generating overview (@acronym{NOV}) files.
+If you have old overview files, you should regenerate them after
+changing this variable, by entering the server buffer using @kbd{^},
+and then @kbd{g} on the appropriate mail server (e.g. nnml) to cause
+regeneration.
+
+@vindex gnus-summary-line-format
+You also have to instruct Gnus to display the data by changing the
+@code{%n} spec to the @code{%f} spec in the
+@code{gnus-summary-line-format} variable.
+
+In summary, you'd typically put something like the following in
+@file{~/.gnus.el}:
+
+@lisp
+(setq gnus-extra-headers
+ '(To Newsgroups))
+(setq nnmail-extra-headers gnus-extra-headers)
+(setq gnus-summary-line-format
+ "%U%R%z%I%(%[%4L: %-23,23f%]%) %s\n")
+(setq gnus-ignored-from-addresses
+ "Your Name Here")
+@end lisp
+
+(The values listed above are the default values in Gnus. Alter them
+to fit your needs.)
+
+A note for news server administrators, or for users who wish to try to
+convince their news server administrator to provide some additional
+support:
+
+The above is mostly useful for mail groups, where you have control over
+the @acronym{NOV} files that are created. However, if you can persuade your
+nntp admin to add (in the usual implementation, notably INN):
+
+@example
+Newsgroups:full
+@end example
+
+to the end of her @file{overview.fmt} file, then you can use that just
+as you would the extra headers from the mail groups.
+
+
+@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 @code{(@var{form}
+. @var{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 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 with unread articles. 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.
+
+This variable can also be a number. In that case, center the window at
+the given number of lines from the top.
+
+@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.
+
+If you want to fetch new articles or redisplay the group, see
+@ref{Exiting the Summary Buffer}.
+
+@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}).
+
+If you have an article window open already and you press @kbd{SPACE}
+again, the article will be scrolled. This lets you conveniently
+@kbd{SPACE} through an entire newsgroup. @xref{Paging the Article}.
+
+@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 unread article with the highest score
+(@code{gnus-summary-best-unread-article}). If given a prefix argument,
+go to the first unread article that has a score over the default score.
+
+@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}.
+
+@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}).
+
+@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. The default is
+@code{nil}. If you would like each article to be saved in the Agent as
+you read it, putting @code{gnus-agent-fetch-selected-article} on this
+hook will do so.
+
+@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-read-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}).
+
+@vindex gnus-article-boring-faces
+@vindex gnus-article-skip-boring
+If @code{gnus-article-skip-boring} is non-@code{nil} and the rest of
+the article consists only of citations and signature, then it will be
+skipped; the next article will be shown instead. You can customize
+what is considered uninteresting with
+@code{gnus-article-boring-faces}. You can manually view the article's
+pages, no matter how boring, using @kbd{C-M-v}.
+
+@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
+@vindex gnus-summary-show-article-charset-alist
+(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.
+
+If given a numerical prefix, you can do semi-manual charset stuff.
+@kbd{C-u 0 g cn-gb-2312 RET} will decode the message as if it were
+encoded in the @code{cn-gb-2312} charset. If you have
+
+@lisp
+(setq gnus-summary-show-article-charset-alist
+ '((1 . cn-gb-2312)
+ (2 . big5)))
+@end lisp
+
+then you can say @kbd{C-u 1 g} to get the same effect.
+
+@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.
+* Summary Message Commands:: Other Message-related commands.
+* Canceling and Superseding::
+@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. If @code{Mail-Followup-To} is
+present, that's used instead.
+
+@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-wide-reply-with-original}). This command uses
+the process/prefix convention.
+
+@item S v
+@kindex S v (Summary)
+@findex gnus-summary-very-wide-reply
+Mail a very wide reply to the author of the current article
+(@code{gnus-summary-wide-reply}). A @dfn{very 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 in all the process/prefixed
+articles. This command uses the process/prefix convention.
+
+@item S V
+@kindex S V (Summary)
+@findex gnus-summary-very-wide-reply-with-original
+Mail a very wide reply to the author of the current article and include the
+original message (@code{gnus-summary-very-wide-reply-with-original}). This
+command uses the process/prefix convention.
+
+@item S B r
+@kindex S B r (Summary)
+@findex gnus-summary-reply-broken-reply-to
+Mail a reply to the author of the current article but ignore the
+@code{Reply-To} field (@code{gnus-summary-reply-broken-reply-to}).
+If you need this because a mailing list incorrectly sets a
+@code{Reply-To} header pointing to the list, you probably want to set
+the @code{broken-reply-to} group parameter instead, so things will work
+correctly. @xref{Group Parameters}.
+
+@item S B R
+@kindex S B R (Summary)
+@findex gnus-summary-reply-broken-reply-to-with-original
+Mail a reply to the author of the current article and include the
+original message but ignore the @code{Reply-To} field
+(@code{gnus-summary-reply-broken-reply-to-with-original}).
+
+@item S o m
+@itemx C-c C-f
+@kindex S o m (Summary)
+@kindex C-c C-f (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 no prefix is given, the message
+is forwarded according to the value of (@code{message-forward-as-mime})
+and (@code{message-forward-show-mml}); if the prefix is 1, decode the
+message and forward directly inline; if the prefix is 2, forward message
+as an rfc822 @acronym{MIME} section; if the prefix is 3, decode message and
+forward as an rfc822 @acronym{MIME} section; if the prefix is 4, forward message
+directly inline; otherwise, the message is forwarded as no prefix given
+but use the flipped value of (@code{message-forward-as-mime}). By
+default, the message is decoded and forwarded as an rfc822 @acronym{MIME}
+section.
+
+@item S m
+@itemx m
+@kindex m (Summary)
+@kindex S m (Summary)
+@findex gnus-summary-mail-other-window
+@c @icon{gnus-summary-mail-originate}
+Prepare a mail (@code{gnus-summary-mail-other-window}). By default, use
+the posting style of the current group. If given a prefix, disable that.
+If the prefix is 1, prompt for a group name to find the posting style.
+
+@item S i
+@itemx i
+@kindex i (Summary)
+@kindex S i (Summary)
+@findex gnus-summary-news-other-window
+Prepare a news (@code{gnus-summary-news-other-window}). By default,
+post to the current group. If given a prefix, disable that. If the
+prefix is 1, prompt for a group to post to.
+
+This function actually prepares a news even when using mail groups.
+This is useful for ``posting'' messages to mail groups without actually
+sending them over the network: they're just saved directly to the group
+in question. The corresponding back end must have a request-post method
+for this to work though.
+
+@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 muss sein!
+
+This command understands the process/prefix convention
+(@pxref{Process/Prefix}).
+
+@item S D e
+@kindex S D e (Summary)
+@findex gnus-summary-resend-message-edit
+
+Like the previous command, but will allow you to edit the message as
+if it were a new message before resending.
+
+@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 @xref{Header Commands, ,Header Commands, message, The Message
+Manual}, 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}
+Prepare for posting an article (@code{gnus-summary-post-news}). By
+default, post to the current group. If given a prefix, disable that.
+If the prefix is 1, prompt for another group instead.
+
+@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 no prefix is given, the message is forwarded according to the value
+of (@code{message-forward-as-mime}) and
+(@code{message-forward-show-mml}); if the prefix is 1, decode the
+message and forward directly inline; if the prefix is 2, forward message
+as an rfc822 @acronym{MIME} section; if the prefix is 3, decode message and
+forward as an rfc822 @acronym{MIME} section; if the prefix is 4, forward message
+directly inline; otherwise, the message is forwarded as no prefix given
+but use the flipped value of (@code{message-forward-as-mime}). By
+default, the message is decoded and forwarded as an rfc822 @acronym{MIME} section.
+
+@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-post-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 @xref{Header Commands, ,Header Commands, message, The Message
+Manual}, for more information.
+
+
+@node Summary Message Commands
+@subsection Summary Message Commands
+
+@table @kbd
+@item S y
+@kindex S y (Summary)
+@findex gnus-summary-yank-message
+Yank the current article into an already existing Message composition
+buffer (@code{gnus-summary-yank-message}). This command prompts for
+what message buffer you want to yank into, and understands the
+process/prefix convention (@pxref{Process/Prefix}).
+
+@end table
+
+
+@node Canceling and Superseding
+@subsection 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}).
+
+Gnus ensures that only you can cancel your own messages using a
+@code{Cancel-Lock} header (@pxref{Canceling News, Canceling News, ,
+message, Message Manual}).
+
+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 Delayed Articles
+@section Delayed Articles
+@cindex delayed sending
+@cindex send delayed
+
+Sometimes, you might wish to delay the sending of a message. For
+example, you might wish to arrange for a message to turn up just in time
+to remind your about the birthday of your Significant Other. For this,
+there is the @code{gnus-delay} package. Setup is simple:
+
+@lisp
+(gnus-delay-initialize)
+@end lisp
+
+@findex gnus-delay-article
+Normally, to send a message you use the @kbd{C-c C-c} command from
+Message mode. To delay a message, use @kbd{C-c C-j}
+(@code{gnus-delay-article}) instead. This will ask you for how long the
+message should be delayed. Possible answers are:
+
+@itemize @bullet
+@item
+A time span. Consists of an integer and a letter. For example,
+@code{42d} means to delay for 42 days. Available letters are @code{m}
+(minutes), @code{h} (hours), @code{d} (days), @code{w} (weeks), @code{M}
+(months) and @code{Y} (years).
+
+@item
+A specific date. Looks like @code{YYYY-MM-DD}. The message will be
+delayed until that day, at a specific time (eight o'clock by default).
+See also @code{gnus-delay-default-hour}.
+
+@item
+A specific time of day. Given in @code{hh:mm} format, 24h, no am/pm
+stuff. The deadline will be at that time today, except if that time has
+already passed, then it's at the given time tomorrow. So if it's ten
+o'clock in the morning and you specify @code{11:15}, then the deadline
+is one hour and fifteen minutes hence. But if you specify @code{9:20},
+that means a time tomorrow.
+@end itemize
+
+The action of the @code{gnus-delay-article} command is influenced by a
+couple of variables:
+
+@table @code
+@item gnus-delay-default-hour
+@vindex gnus-delay-default-hour
+When you specify a specific date, the message will be due on that hour
+on the given date. Possible values are integers 0 through 23.
+
+@item gnus-delay-default-delay
+@vindex gnus-delay-default-delay
+This is a string and gives the default delay. It can be of any of the
+formats described above.
+
+@item gnus-delay-group
+@vindex gnus-delay-group
+Delayed articles will be kept in this group on the drafts server until
+they are due. You probably don't need to change this. The default
+value is @code{"delayed"}.
+
+@item gnus-delay-header
+@vindex gnus-delay-header
+The deadline for each article will be stored in a header. This variable
+is a string and gives the header name. You probably don't need to
+change this. The default value is @code{"X-Gnus-Delayed"}.
+@end table
+
+The way delaying works is like this: when you use the
+@code{gnus-delay-article} command, you give a certain delay. Gnus
+calculates the deadline of the message and stores it in the
+@code{X-Gnus-Delayed} header and puts the message in the
+@code{nndraft:delayed} group.
+
+@findex gnus-delay-send-queue
+And whenever you get new news, Gnus looks through the group for articles
+which are due and sends them. It uses the @code{gnus-delay-send-queue}
+function for this. By default, this function is added to the hook
+@code{gnus-get-new-news-hook}. But of course, you can change this.
+Maybe you want to use the demon to send drafts? Just tell the demon to
+execute the @code{gnus-delay-send-queue} function.
+
+@table @code
+@item gnus-delay-initialize
+@findex gnus-delay-initialize
+By default, this function installs @code{gnus-delay-send-queue} in
+@code{gnus-get-new-news-hook}. But it accepts the optional second
+argument @code{no-check}. If it is non-@code{nil},
+@code{gnus-get-new-news-hook} is not changed. The optional first
+argument is ignored.
+
+For example, @code{(gnus-delay-initialize nil t)} means to do nothing.
+Presumably, you want to use the demon for sending due delayed articles.
+Just don't forget to set that up :-)
+@end table
+
+
+@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.
+
+@ifinfo
+There's a plethora of commands for manipulating these marks.
+@end ifinfo
+
+@menu
+* Unread Articles:: Marks for unread articles.
+* Read Articles:: Marks for read articles.
+* Other Marks:: Marks that do not affect readedness.
+* Setting Marks:: How to set and remove marks.
+* Generic Marking Commands:: How to customize the marking.
+* 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 (from news servers by the
+news server software, Gnus itself never expires ticked messages), 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}).
+Otherwise (except for the visibility issue), they are just like ticked
+messages.
+
+@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-duplicate-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-forwarded-mark
+All articles that you have forwarded will be marked with an @samp{F} in
+the second column (@code{gnus-forwarded-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-recent-mark
+Articles that according to the server haven't been shown to the user
+before are marked with a @samp{N} in the second column
+(@code{gnus-recent-mark}). Note that not all servers support this
+mark, in which case it simply never appears. Compare with
+@code{gnus-unseen-mark}.
+
+@item
+@vindex gnus-unseen-mark
+Articles that haven't been seen before in Gnus by the user are marked
+with a @samp{.} in the second column (@code{gnus-unseen-mark}).
+Compare with @code{gnus-recent-mark}.
+
+@item
+@vindex gnus-downloaded-mark
+When using the Gnus agent (@pxref{Agent Basics}), articles may be
+downloaded for unplugged (offline) viewing. If you are using the
+@samp{%O} spec, these articles get the @samp{+} mark in that spec.
+(The variable @code{gnus-downloaded-mark} controls which character to
+use.)
+
+@item
+@vindex gnus-undownloaded-mark
+When using the Gnus agent (@pxref{Agent Basics}), some articles might
+not have been downloaded. Such articles cannot be viewed while you
+are unplugged (offline). If you are using the @samp{%O} spec, these
+articles get the @samp{-} mark in that spec. (The variable
+@code{gnus-undownloaded-mark} controls which character to use.)
+
+@item
+@vindex gnus-downloadable-mark
+The Gnus agent (@pxref{Agent Basics}) downloads some articles
+automatically, but it is also possible to explicitly mark articles for
+download, even if they would not be downloaded automatically. Such
+explicitly-marked articles get the @samp{%} mark in the first column.
+(The variable @code{gnus-downloadable-mark} controls which character to
+use.)
+
+@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 (before the point)
+(@code{gnus-summary-catchup-to-here}).
+
+@item M h
+@kindex M h (Summary)
+@findex gnus-summary-catchup-from-here
+Catchup the current group from point (after the point)
+(@code{gnus-summary-catchup-from-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 Generic Marking Commands
+@subsection Generic Marking Commands
+
+Some people would like the command that ticks an article (@kbd{!}) go to
+the next article. Others would like it to go to the next unread
+article. Yet others would like it to stay on the current article. And
+even though I haven't heard of anybody wanting it to go to the
+previous (unread) article, I'm sure there are people that want that as
+well.
+
+Multiply these five behaviors with five different marking commands, and
+you get a potentially complex set of variable to control what each
+command should do.
+
+To sidestep that mess, Gnus provides commands that do all these
+different things. They can be found on the @kbd{M M} map in the summary
+buffer. Type @kbd{M M C-h} to see them all---there are too many of them
+to list in this manual.
+
+While you can use these commands directly, most users would prefer
+altering the summary mode keymap. For instance, if you would like the
+@kbd{!} command to go to the next article instead of the next unread
+article, you could say something like:
+
+@lisp
+@group
+(add-hook 'gnus-summary-mode-hook 'my-alter-summary-map)
+(defun my-alter-summary-map ()
+ (local-set-key "!" 'gnus-summary-put-mark-as-ticked-next))
+@end group
+@end lisp
+
+@noindent
+or
+
+@lisp
+(defun my-alter-summary-map ()
+ (local-set-key "!" "MM!n"))
+@end lisp
+
+
+@node Setting Process Marks
+@subsection Setting Process Marks
+@cindex setting process marks
+
+Process marks are displayed as @code{#} in the summary buffer, and are
+used for marking articles in such a way that other commands will
+process these articles. For instance, if you process mark four
+articles and then use the @kbd{*} command, Gnus will enter these four
+articles into the cache. For more information,
+@pxref{Process/Prefix}.
+
+@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 G
+@kindex M P G (Summary)
+@findex gnus-uu-unmark-by-regexp
+Unmark articles that have a @code{Subject} header that matches a regular
+expression (@code{gnus-uu-unmark-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 g
+@kindex M P g (Summary)
+@findex gnus-uu-unmark-region
+Unmark articles in region (@code{gnus-uu-unmark-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-all}).
+
+@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
+
+Also see the @kbd{&} command in @ref{Searching for Articles}, for how to
+set process marks based on article body contents.
+
+
+@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}). If given a prefix, exclude
+matching articles.
+
+@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}). If given a prefix, exclude
+matching articles.
+
+@item / x
+@kindex / x (Summary)
+@findex gnus-summary-limit-to-extra
+Limit the summary buffer to articles that match one of the ``extra''
+headers (@pxref{To From Newsgroups})
+(@code{gnus-summary-limit-to-extra}). If given a prefix, exclude
+matching articles.
+
+@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-age}). If given a prefix, limit to
+articles younger than that number of days.
+
+@item / n
+@kindex / n (Summary)
+@findex gnus-summary-limit-to-articles
+With prefix @samp{n}, limit the summary buffer to the next @samp{n}
+articles. If not given a prefix, use the process marked articles
+instead. (@code{gnus-summary-limit-to-articles}).
+
+@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 / .
+@kindex / . (Summary)
+@findex gnus-summary-limit-to-unseen
+Limit the summary buffer to the unseen articles
+(@code{gnus-summary-limit-to-unseen}).
+
+@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 / p
+@kindex / p (Summary)
+@findex gnus-summary-limit-to-display-predicate
+Limit the summary buffer to articles that satisfy the @code{display}
+group parameter predicate
+(@code{gnus-summary-limit-to-display-predicate}). @xref{Group
+Parameters}, for more on this predicate.
+
+@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 / M
+@kindex / M (Summary)
+@findex gnus-summary-limit-exclude-marks
+Exclude all marked articles (@code{gnus-summary-limit-exclude-marks}).
+
+@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.
+
+@item / N
+@kindex / N (Summary)
+@findex gnus-summary-insert-new-articles
+Insert all new articles in the summary buffer. It scans for new emails
+if @var{back-end}@code{-get-new-mail} is non-@code{nil}.
+
+@item / o
+@kindex / o (Summary)
+@findex gnus-summary-insert-old-articles
+Insert all old articles in the summary buffer. If given a numbered
+prefix, fetch this number of articles.
+
+@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 exacerbates the problem,
+so one has to employ other heuristics to get pleasing results. A
+plethora of approaches exists, as detailed in horrible detail in
+@ref{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@dots{} 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:
+
+@iftex
+@iflatex
+\gnusfigure{The Summary Buffer}{390}{
+\put(0,0){\epsfig{figure=ps/summary-adopt,width=7.5cm}}
+\put(445,0){\makebox(0,0)[br]{\epsfig{figure=ps/summary-empty,width=7.5cm}}}
+\put(0,400){\makebox(0,0)[tl]{\epsfig{figure=ps/summary-none,width=7.5cm}}}
+\put(445,400){\makebox(0,0)[tr]{\epsfig{figure=ps/summary-dummy,width=7.5cm}}}
+}
+@end iflatex
+@end iftex
+
+@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
+@vindex gnus-summary-make-false-root-always
+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}.
+If you want all threads to have a dummy root, even the non-gathered
+ones, set @code{gnus-summary-make-false-root-always} to @code{t}.
+
+@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.
+
+@item gnus-simplify-all-whitespace
+@findex gnus-simplify-all-whitespace
+Remove all 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 back end you are using carries overview
+files---this would normally be @code{nntp}, @code{nnspool},
+@code{nnml}, and @code{nnmaildir}. 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-fetch-old-ephemeral-headers
+@vindex gnus-fetch-old-ephemeral-headers
+Same as @code{gnus-fetch-old-headers}, but only used for ephemeral
+newsgroups.
+
+@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.
+
+@item gnus-read-all-available-headers
+@vindex gnus-read-all-available-headers
+This is a rather obscure variable that few will find useful. It's
+intended for those non-news newsgroups where the back end has to fetch
+quite a lot to present the summary buffer, and where it's impossible to
+go back to parents of articles. This is mostly the case in the
+web-based groups, like the @code{nnultimate} groups.
+
+If you don't use those, then it's safe to leave this as the default
+@code{nil}. If you want to use this variable, it should be a regexp
+that matches the group name, or @code{t} for all groups.
+
+@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.
+
+This can also be a predicate specifier (@pxref{Predicate Specifiers}).
+Available predicates are @code{gnus-article-unread-p} and
+@code{gnus-article-unseen-p}.
+
+Here's an example:
+
+@lisp
+(setq gnus-thread-hide-subtree
+ '(or gnus-article-unread-p
+ gnus-article-unseen-p))
+@end lisp
+
+(It's a pretty nonsensical example, since all unseen articles are also
+unread, but you get my drift.)
+
+
+@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}, which is the default, the subject
+change is ignored. If it is @code{nil}, 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.
+
+@item gnus-sort-gathered-threads-function
+@vindex gnus-sort-gathered-threads-function
+Sometimes, particularly with mailing lists, the order in which mails
+arrive locally is not necessarily the same as the order in which they
+arrived on the mailing list. Consequently, when sorting sub-threads
+using the default @code{gnus-thread-sort-by-number}, responses can end
+up appearing before the article to which they are responding to.
+Setting this variable to an alternate value
+(e.g. @code{gnus-thread-sort-by-date}), in a group's parameters or in an
+appropriate hook (e.g. @code{gnus-summary-generate-hook}) can produce a
+more logical sub-thread ordering in such instances.
+
+@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.
+
+@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 C-M-k
+@kindex T k (Summary)
+@kindex C-M-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 C-M-l
+@kindex T l (Summary)
+@kindex C-M-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)
+@itemx C-M-f
+@kindex C-M-n (Summary)
+@itemx M-down
+@kindex M-down (Summary)
+@findex gnus-summary-next-thread
+Go to the next thread (@code{gnus-summary-next-thread}).
+
+@item T p
+@kindex T p (Summary)
+@itemx C-M-b
+@kindex C-M-p (Summary)
+@itemx M-up
+@kindex M-up (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 @kbd{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 the Summary Buffer
+@section Sorting the Summary Buffer
+
+@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
+@findex gnus-thread-sort-by-random
+@vindex gnus-thread-sort-functions
+@findex gnus-thread-sort-by-most-recent-number
+@findex gnus-thread-sort-by-most-recent-date
+If you are using a threaded summary display, you can sort the threads by
+setting @code{gnus-thread-sort-functions}, which can be either a single
+function, a list of functions, or a list containing functions and
+@code{(not some-function)} elements.
+
+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},
+@code{gnus-thread-sort-by-most-recent-number},
+@code{gnus-thread-sort-by-most-recent-date},
+@code{gnus-thread-sort-by-random} 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 reverse 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
+ (not 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-random
+@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},
+@code{gnus-article-sort-by-random}, 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 @acronym{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 @acronym{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@dots{} 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 back end will pre-fetch
+the next 30 articles. If this variable is @code{t}, the back end 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-unread-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-unread-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 @acronym{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 hierarchical 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 @acronym{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 @acronym{NOV}
+files, and @kbd{gnus-cache-generate-active} will (re)generate the active
+file.
+
+@findex gnus-cache-move-cache
+@code{gnus-cache-move-cache} will move your whole
+@code{gnus-cache-directory} to some other location. You get asked to
+where, isn't that cool?
+
+@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.
+
+The default value is 20.
+
+
+@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}).
+
+For the commands listed here, the target is a file. If you want to
+save to a group, see the @kbd{B c} (@code{gnus-summary-copy-article})
+command (@pxref{Mail Group Commands}).
+
+@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 a Unix mail box (mbox) file
+(@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
+@itemx |
+@kindex O p (Summary)
+@kindex | (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}).
+If given a symbolic prefix (@pxref{Symbolic Prefixes}), include the
+complete headers in the piped output.
+
+@item O P
+@kindex O P (Summary)
+@findex gnus-summary-muttprint
+@vindex gnus-summary-muttprint-program
+Save the current article into muttprint. That is, print it using the
+external program @uref{http://muttprint.sourceforge.net/,
+Muttprint}. The program name and options to use is controlled by the
+variable @code{gnus-summary-muttprint-program}.
+(@code{gnus-summary-muttprint}).
+
+@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 eight 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-write-to-file
+@findex gnus-summary-write-to-file
+Write the article straight to an ordinary file. The file is
+overwritten if it exists. 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-write-body-to-file
+@findex gnus-summary-write-body-to-file
+Write the article body straight to an ordinary file. The file is
+overwritten if it exists. 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
+
+The symbol of each function may have the following properties:
+
+@table @code
+@item :decode
+The value non-@code{nil} means save decoded articles. This is
+meaningful only with @code{gnus-summary-save-in-file},
+@code{gnus-summary-save-body-in-file},
+@code{gnus-summary-write-to-file}, and
+@code{gnus-summary-write-body-to-file}.
+
+@item :function
+The value specifies an alternative function which appends, not
+overwrites, articles to a file. This implies that when saving many
+articles at a time, @code{gnus-prompt-before-saving} is bound to
+@code{t} and all articles are saved in a single file. This is
+meaningful only with @code{gnus-summary-write-to-file} and
+@code{gnus-summary-write-body-to-file}.
+
+@item :headers
+The value specifies the symbol of a variable of which the value
+specifies headers to be saved. If it is omitted,
+@code{gnus-save-all-headers} and @code{gnus-saved-headers} control what
+headers should be saved.
+@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
+@env{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}.
+
+@item gnus-sender-save-name
+@findex gnus-sender-save-name
+File names like @file{~/News/larsi}.
+@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 @file{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)) ; @r{to get a hierarchy}
+(setq gnus-default-article-saver
+ 'gnus-summary-save-in-file) ; @r{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 @file{.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 @acronym{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 @acronym{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 @acronym{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 RFC 1153---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@dots{}) 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 Header:: Doing various header transformations.
+* Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
+* Article Button Levels:: Controlling appearance of buttons.
+* Article Date:: Grumble, UT!
+* Article Display:: Display various stuff---X-Face, Picons, Smileys
+* Article Signature:: What is a signature?
+* Article Miscellanea:: Various other stuff.
+@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.
+
+@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
+@code{(@var{regexp} @var{name} @var{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 in bytes is bigger than this variable (which is
+25000 by default), no citation highlighting will be performed.
+
+@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.
+
+@item gnus-cite-ignore-quoted-from
+@vindex gnus-cite-ignore-quoted-from
+If non-@code{nil}, no citation highlighting will be performed on lines
+beginning with @samp{>From }. Those lines may have been quoted by MTAs
+in order not to mix up with the envelope From line. The default value
+is @code{t}.
+
+@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*} 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-emphasis-alist
+ '(("_\\(\\w+\\)_" 0 1 gnus-emphasis-underline)
+ ("\\*\\(\\w+\\)\\*" 0 1 gnus-emphasis-bold)))
+@end lisp
+
+@cindex slash
+@cindex asterisk
+@cindex underline
+@cindex /
+@cindex *
+
+@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
+
+@vindex gnus-group-highlight-words-alist
+
+If you want to highlight arbitrary words, you can use the
+@code{gnus-group-highlight-words-alist} variable, which uses the same
+syntax as @code{gnus-emphasis-alist}. The @code{highlight-words} group
+parameter (@pxref{Group Parameters}) can also be used.
+
+@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, @acronym{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 l
+@kindex W W l (Summary)
+@findex gnus-article-hide-list-identifiers
+@vindex gnus-list-identifiers
+Strip list identifiers specified in @code{gnus-list-identifiers}. These
+are strings some mailing list servers add to the beginning of all
+@code{Subject} headers---for example, @samp{[zebra 4711]}. Any leading
+@samp{Re: } is skipped before stripping. @code{gnus-list-identifiers}
+may not contain @code{\\(..\\)}.
+
+@table @code
+
+@item gnus-list-identifiers
+@vindex gnus-list-identifiers
+A regular expression that matches list identifiers to be removed from
+subject. This can also be a list of regular expressions.
+
+@end table
+
+@item W W P
+@kindex W W P (Summary)
+@findex gnus-article-hide-pem
+Hide @acronym{PEM} (privacy enhanced messages) cruft
+(@code{gnus-article-hide-pem}).
+
+@item W W B
+@kindex W W B (Summary)
+@findex gnus-article-strip-banner
+@vindex gnus-article-banner-alist
+@vindex gnus-article-address-banner-alist
+@cindex banner
+@cindex OneList
+@cindex stripping advertisements
+@cindex advertisements
+Strip the banner specified by the @code{banner} group parameter
+(@code{gnus-article-strip-banner}). This is mainly used to hide those
+annoying banners and/or signatures that some mailing lists and moderated
+groups adds to all the messages. The way to use this function is to add
+the @code{banner} group parameter (@pxref{Group Parameters}) to the
+group you want banners stripped from. The parameter either be a string,
+which will be interpreted as a regular expression matching text to be
+removed, or the symbol @code{signature}, meaning that the (last)
+signature should be removed, or other symbol, meaning that the
+corresponding regular expression in @code{gnus-article-banner-alist} is
+used.
+
+Regardless of a group, you can hide things like advertisements only when
+the sender of an article has a certain mail address specified in
+@code{gnus-article-address-banner-alist}.
+
+@table @code
+
+@item gnus-article-address-banner-alist
+@vindex gnus-article-address-banner-alist
+Alist of mail addresses and banners. Each element has the form
+@code{(@var{address} . @var{banner})}, where @var{address} is a regexp
+matching a mail address in the From header, @var{banner} is one of a
+symbol @code{signature}, an item in @code{gnus-article-banner-alist},
+a regexp and @code{nil}. If @var{address} matches author's mail
+address, it will remove things like advertisements. For example, if a
+sender has the mail address @samp{hail@@yoo-hoo.co.jp} and there is a
+banner something like @samp{Do You Yoo-hoo!?} in all articles he
+sends, you can use the following element to remove them:
+
+@lisp
+("@@yoo-hoo\\.co\\.jp\\'" .
+ "\n_+\nDo You Yoo-hoo!\\?\n.*\n.*\n")
+@end lisp
+
+@end table
+
+@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. This can also be a cons cell with the number of lines at the top
+and bottom of the text, respectively, to remain visible.
+
+@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
+have happen automatically (@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.
+
+@xref{Customizing Articles}, if you want to change how Gnus displays
+articles by default.
+
+@table @kbd
+
+@item C-u g
+This is not really washing, it's sort of the opposite of washing. If
+you type this, you see the article exactly as it exists on disk or on
+the server.
+
+@item g
+Force redisplaying of the current article
+(@code{gnus-summary-show-article}). This is also not really washing.
+If you type this, you see the article without any previously applied
+interactive Washing functions but with all default treatments
+(@pxref{Customizing Articles}).
+
+@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 m
+@kindex W m (Summary)
+@findex gnus-summary-morse-message
+Morse decode the article buffer (@code{gnus-summary-morse-message}).
+
+@item W t
+@item t
+@kindex W t (Summary)
+@kindex 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-headers
+Toggle whether to display all headers in the article buffer permanently
+(@code{gnus-summary-verbose-headers}).
+
+@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
+@vindex gnus-article-dumbquotes-map
+@cindex Smartquotes
+@cindex M****s*** sm*rtq**t*s
+@cindex Latin 1
+Treat M****s*** sm*rtq**t*s according to
+@code{gnus-article-dumbquotes-map}
+(@code{gnus-article-treat-dumbquotes}). Note that this function guesses
+whether a character is a sm*rtq**t* or not, so it should only be used
+interactively.
+
+Sm*rtq**t*s are M****s***'s unilateral extension to the character map in
+an attempt to provide more quoting characters. If you see something
+like @code{\222} or @code{\264} where you're expecting some kind of
+apostrophe or quotation mark, then try this wash.
+
+@item W Y f
+@kindex W Y f (Summary)
+@findex gnus-article-outlook-deuglify-article
+@cindex Outlook Express
+Full deuglify of broken Outlook (Express) articles: Treat dumbquotes,
+unwrap lines, repair attribution and rearrange citation.
+(@code{gnus-article-outlook-deuglify-article}).
+
+@item W Y u
+@kindex W Y u (Summary)
+@findex gnus-article-outlook-unwrap-lines
+@vindex gnus-outlook-deuglify-unwrap-min
+@vindex gnus-outlook-deuglify-unwrap-max
+Unwrap lines that appear to be wrapped citation lines. You can control
+what lines will be unwrapped by frobbing
+@code{gnus-outlook-deuglify-unwrap-min} and
+@code{gnus-outlook-deuglify-unwrap-max}, indicating the minimum and
+maximum length of an unwrapped citation line.
+(@code{gnus-article-outlook-unwrap-lines}).
+
+@item W Y a
+@kindex W Y a (Summary)
+@findex gnus-article-outlook-repair-attribution
+Repair a broken attribution line.@*
+(@code{gnus-article-outlook-repair-attribution}).
+
+@item W Y c
+@kindex W Y c (Summary)
+@findex gnus-article-outlook-rearrange-citation
+Repair broken citations by rearranging the text.
+(@code{gnus-article-outlook-rearrange-citation}).
+
+@item W w
+@kindex W w (Summary)
+@findex gnus-article-fill-cited-article
+Do word wrap (@code{gnus-article-fill-cited-article}).
+
+You can give the command a numerical prefix to specify the width to use
+when filling.
+
+@item W Q
+@kindex W Q (Summary)
+@findex gnus-article-fill-long-lines
+Fill long lines (@code{gnus-article-fill-long-lines}).
+
+@item W C
+@kindex W C (Summary)
+@findex gnus-article-capitalize-sentences
+Capitalize the first word in each sentence
+(@code{gnus-article-capitalize-sentences}).
+
+@item W c
+@kindex W c (Summary)
+@findex gnus-article-remove-cr
+Translate CRLF pairs (i. e., @samp{^M}s on the end of the lines) into LF
+(this takes care of DOS line endings), and then translate any remaining
+CRs into LF (this takes care of Mac line endings)
+(@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 @acronym{MIME} encoding employed when
+sending non-@acronym{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. Note that this is usually done
+automatically by Gnus if the message in question has a
+@code{Content-Transfer-Encoding} header that says that this encoding
+has been done. If a prefix is given, a charset will be asked for.
+
+@item W 6
+@kindex W 6 (Summary)
+@findex gnus-article-de-base64-unreadable
+Treat base64 (@code{gnus-article-de-base64-unreadable}). Base64 is
+one common @acronym{MIME} encoding employed when sending
+non-@acronym{ASCII} (i.e., 8-bit) articles. Note that this is
+usually done automatically by Gnus if the message in question has a
+@code{Content-Transfer-Encoding} header that says that this encoding
+has been done. If a prefix is given, a charset will be asked for.
+
+@item W Z
+@kindex W Z (Summary)
+@findex gnus-article-decode-HZ
+Treat HZ or HZP (@code{gnus-article-decode-HZ}). HZ (or HZP) is one
+common encoding employed when sending Chinese articles. It typically
+makes strings look like @samp{~@{<:Ky2;S@{#,NpJ)l6HK!#~@}}.
+
+@item W u
+@kindex W u (Summary)
+@findex gnus-article-unsplit-urls
+Remove newlines from within URLs. Some mailers insert newlines into
+outgoing email messages to keep lines short. This reformatting can
+split long URLs onto multiple lines. Repair those URLs by removing
+the newlines (@code{gnus-article-unsplit-urls}).
+
+@item W h
+@kindex W h (Summary)
+@findex gnus-article-wash-html
+Treat @acronym{HTML} (@code{gnus-article-wash-html}). Note that this is
+usually done automatically by Gnus if the message in question has a
+@code{Content-Type} header that says that the message is @acronym{HTML}.
+
+If a prefix is given, a charset will be asked for. If it is a number,
+the charset defined in @code{gnus-summary-show-article-charset-alist}
+(@pxref{Paging the Article}) will be used.
+
+@vindex gnus-article-wash-function
+The default is to use the function specified by
+@code{mm-text-html-renderer} (@pxref{Display Customization, ,Display
+Customization, emacs-mime, The Emacs MIME Manual}) to convert the
+@acronym{HTML}, but this is controlled by the
+@code{gnus-article-wash-function} variable. Pre-defined functions you
+can use include:
+
+@table @code
+@item w3
+Use Emacs/W3.
+
+@item w3m
+Use @uref{http://emacs-w3m.namazu.org/, emacs-w3m}.
+
+@item w3m-standalone
+Use @uref{http://w3m.sourceforge.net/, w3m}.
+
+@item links
+Use @uref{http://links.sf.net/, Links}.
+
+@item lynx
+Use @uref{http://lynx.isc.org/, Lynx}.
+
+@item html2text
+Use html2text---a simple @acronym{HTML} converter included with Gnus.
+
+@end table
+
+@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 p
+@kindex W p (Summary)
+@findex gnus-article-verify-x-pgp-sig
+Verify a signed control message
+(@code{gnus-article-verify-x-pgp-sig}). Control messages such as
+@code{newgroup} and @code{checkgroups} are usually signed by the
+hierarchy maintainer. You need to add the @acronym{PGP} public key of
+the maintainer to your keyring to verify the
+message.@footnote{@acronym{PGP} keys for many hierarchies are
+available at @uref{ftp://ftp.isc.org/pub/pgpcontrol/README.html}}
+
+@item W s
+@kindex W s (Summary)
+@findex gnus-summary-force-verify-and-decrypt
+Verify a signed (@acronym{PGP}, @acronym{PGP/MIME} or
+@acronym{S/MIME}) message
+(@code{gnus-summary-force-verify-and-decrypt}). @xref{Security}.
+
+@item W a
+@kindex W a (Summary)
+@findex gnus-article-strip-headers-in-body
+Strip headers like the @code{X-No-Archive} header from the beginning of
+article bodies (@code{gnus-article-strip-headers-in-body}).
+
+@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}).
+
+@item W E e
+@kindex W E e (Summary)
+@findex gnus-article-strip-trailing-space
+Remove all white space from the end of all lines of the article
+body (@code{gnus-article-strip-trailing-space}).
+
+@end table
+
+@xref{Customizing Articles}, for how to wash articles automatically.
+
+
+@node Article Header
+@subsection Article Header
+
+These commands perform various transformations of article header.
+
+@table @kbd
+
+@item W G u
+@kindex W G u (Summary)
+@findex gnus-article-treat-unfold-headers
+Unfold folded header lines (@code{gnus-article-treat-unfold-headers}).
+
+@item W G n
+@kindex W G n (Summary)
+@findex gnus-article-treat-fold-newsgroups
+Fold the @code{Newsgroups} and @code{Followup-To} headers
+(@code{gnus-article-treat-fold-newsgroups}).
+
+@item W G f
+@kindex W G f (Summary)
+@findex gnus-article-treat-fold-headers
+Fold all the message headers
+(@code{gnus-article-treat-fold-headers}).
+
+@item W E w
+@kindex W E w (Summary)
+@findex gnus-article-remove-leading-whitespace
+Remove excessive whitespace from all headers
+(@code{gnus-article-remove-leading-whitespace}).
+
+@end table
+
+
+@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.
+
+@vindex gnus-button-man-handler
+Gnus adds @dfn{buttons} to certain standard references by default:
+Well-formed URLs, mail addresses, Message-IDs, Info links, man pages and
+Emacs or Gnus related references. 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
+(@var{regexp} @var{button-par} @var{use-p} @var{function} @var{data-par})
+@end lisp
+
+@table @var
+
+@item regexp
+All text that match this regular expression (case insensitive) will be
+considered an external reference. Here's a typical regexp that matches
+embedded URLs: @samp{<URL:\\([^\n\r>]*\\)>}. This can also be a
+variable containing a regexp, useful variables to use include
+@code{gnus-button-url-regexp} and @code{gnus-button-mid-or-mail-regexp}.
+
+@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. Often variables named
+@code{gnus-button-@var{*}-level} are used here, @xref{Article Button
+Levels}, but any other form may be used too.
+
+@c @code{use-p} is @code{eval}ed only if @code{regexp} 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
+(@var{header} @var{regexp} @var{button-par} @var{use-p} @var{function} @var{data-par})
+@end lisp
+
+@var{header} is a regular expression.
+@end table
+
+@subsubsection Related variables and functions
+
+@table @code
+@item gnus-button-@var{*}-level
+@xref{Article Button Levels}.
+
+@c Stuff related to gnus-button-browse-level
+
+@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.
+
+@c Stuff related to gnus-button-man-level
+
+@item gnus-button-man-handler
+@vindex gnus-button-man-handler
+The function to use for displaying man pages. It must take at least one
+argument with a string naming the man page.
+
+@c Stuff related to gnus-button-message-level
+
+@item gnus-button-mid-or-mail-regexp
+@vindex gnus-button-mid-or-mail-regexp
+Regular expression that matches a message ID or a mail address.
+
+@item gnus-button-prefer-mid-or-mail
+@vindex gnus-button-prefer-mid-or-mail
+This variable determines what to do when the button on a string as
+@samp{foo123@@bar.invalid} is pushed. Strings like this can be either a
+message ID or a mail address. If it is one of the symbols @code{mid} or
+@code{mail}, Gnus will always assume that the string is a message ID or
+a mail address, respectively. If this variable is set to the symbol
+@code{ask}, always query the user what to do. If it is a function, this
+function will be called with the string as its only argument. The
+function must return @code{mid}, @code{mail}, @code{invalid} or
+@code{ask}. The default value is the function
+@code{gnus-button-mid-or-mail-heuristic}.
+
+@item gnus-button-mid-or-mail-heuristic
+@findex gnus-button-mid-or-mail-heuristic
+Function that guesses whether its argument is a message ID or a mail
+address. Returns @code{mid} if it's a message IDs, @code{mail} if
+it's a mail address, @code{ask} if unsure and @code{invalid} if the
+string is invalid.
+
+@item gnus-button-mid-or-mail-heuristic-alist
+@vindex gnus-button-mid-or-mail-heuristic-alist
+An alist of @code{(RATE . REGEXP)} pairs used by the function
+@code{gnus-button-mid-or-mail-heuristic}.
+
+@c Stuff related to gnus-button-tex-level
+
+@item gnus-button-ctan-handler
+@findex gnus-button-ctan-handler
+The function to use for displaying CTAN links. It must take one
+argument, the string naming the URL.
+
+@item gnus-ctan-url
+@vindex gnus-ctan-url
+Top directory of a CTAN (Comprehensive TeX Archive Network) archive used
+by @code{gnus-button-ctan-handler}.
+
+@c Misc stuff
+
+@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 Button Levels
+@subsection Article button levels
+@cindex button levels
+The higher the value of the variables @code{gnus-button-@var{*}-level},
+the more buttons will appear. If the level is zero, no corresponding
+buttons are displayed. With the default value (which is 5) you should
+already see quite a lot of buttons. With higher levels, you will see
+more buttons, but you may also get more false positives. To avoid them,
+you can set the variables @code{gnus-button-@var{*}-level} local to
+specific groups (@pxref{Group Parameters}). Here's an example for the
+variable @code{gnus-parameters}:
+
+@lisp
+;; @r{increase @code{gnus-button-*-level} in some groups:}
+(setq gnus-parameters
+ '(("\\<\\(emacs\\|gnus\\)\\>" (gnus-button-emacs-level 10))
+ ("\\<unix\\>" (gnus-button-man-level 10))
+ ("\\<tex\\>" (gnus-button-tex-level 10))))
+@end lisp
+
+@table @code
+
+@item gnus-button-browse-level
+@vindex gnus-button-browse-level
+Controls the display of references to message IDs, mail addresses and
+news URLs. Related variables and functions include
+@code{gnus-button-url-regexp}, @code{browse-url}, and
+@code{browse-url-browser-function}.
+
+@item gnus-button-emacs-level
+@vindex gnus-button-emacs-level
+Controls the display of Emacs or Gnus references. Related functions are
+@code{gnus-button-handle-custom},
+@code{gnus-button-handle-describe-function},
+@code{gnus-button-handle-describe-variable},
+@code{gnus-button-handle-symbol},
+@code{gnus-button-handle-describe-key},
+@code{gnus-button-handle-apropos},
+@code{gnus-button-handle-apropos-command},
+@code{gnus-button-handle-apropos-variable},
+@code{gnus-button-handle-apropos-documentation}, and
+@code{gnus-button-handle-library}.
+
+@item gnus-button-man-level
+@vindex gnus-button-man-level
+Controls the display of references to (Unix) man pages.
+See @code{gnus-button-man-handler}.
+
+@item gnus-button-message-level
+@vindex gnus-button-message-level
+Controls the display of message IDs, mail addresses and news URLs.
+Related variables and functions include
+@code{gnus-button-mid-or-mail-regexp},
+@code{gnus-button-prefer-mid-or-mail},
+@code{gnus-button-mid-or-mail-heuristic}, and
+@code{gnus-button-mid-or-mail-heuristic-alist}.
+
+@item gnus-button-tex-level
+@vindex gnus-button-tex-level
+Controls the display of references to @TeX{} or LaTeX stuff, e.g. for CTAN
+URLs. See the variables @code{gnus-ctan-url},
+@code{gnus-button-ctan-handler},
+@code{gnus-button-ctan-directory-regexp}, and
+@code{gnus-button-handle-ctan-bogus-regexp}.
+
+@end table
+
+
+@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 p
+@kindex W T p (Summary)
+@findex gnus-article-date-english
+Display the date in a format that's easily pronounceable in English
+(@code{gnus-article-date-english}).
+
+@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}). It looks something like:
+
+@example
+X-Sent: 6 weeks, 4 days, 1 hour, 3 minutes, 8 seconds ago
+@end example
+
+@vindex gnus-article-date-lapsed-new-header
+The value of @code{gnus-article-date-lapsed-new-header} determines
+whether this header will just be added below the old Date one, or will
+replace it.
+
+An advantage of using Gnus to read mail is that it converts simple bugs
+into wonderful absurdities.
+
+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 Display
+@subsection Article Display
+@cindex picons
+@cindex x-face
+@cindex smileys
+
+These commands add various frivolous display gimmicks to the article
+buffer in Emacs versions that support them.
+
+@code{X-Face} headers are small black-and-white images supplied by the
+message headers (@pxref{X-Face}).
+
+@code{Face} headers are small colored images supplied by the message
+headers (@pxref{Face}).
+
+Smileys are those little @samp{:-)} symbols that people like to litter
+their messages with (@pxref{Smileys}).
+
+Picons, on the other hand, reside on your own system, and Gnus will
+try to match the headers to what you have (@pxref{Picons}).
+
+All these functions are toggles---if the elements already exist,
+they'll be removed.
+
+@table @kbd
+@item W D x
+@kindex W D x (Summary)
+@findex gnus-article-display-x-face
+Display an @code{X-Face} in the @code{From} header.
+(@code{gnus-article-display-x-face}).
+
+@item W D d
+@kindex W D d (Summary)
+@findex gnus-article-display-face
+Display a @code{Face} in the @code{From} header.
+(@code{gnus-article-display-face}).
+
+@item W D s
+@kindex W D s (Summary)
+@findex gnus-treat-smiley
+Display smileys (@code{gnus-treat-smiley}).
+
+@item W D f
+@kindex W D f (Summary)
+@findex gnus-treat-from-picon
+Piconify the @code{From} header (@code{gnus-treat-from-picon}).
+
+@item W D m
+@kindex W D m (Summary)
+@findex gnus-treat-mail-picon
+Piconify all mail headers (i. e., @code{Cc}, @code{To})
+(@code{gnus-treat-mail-picon}).
+
+@item W D n
+@kindex W D n (Summary)
+@findex gnus-treat-newsgroups-picon
+Piconify all news headers (i. e., @code{Newsgroups} and
+@code{Followup-To}) (@code{gnus-treat-newsgroups-picon}).
+
+@item W D D
+@kindex W D D (Summary)
+@findex gnus-article-remove-images
+Remove all images from the article buffer
+(@code{gnus-article-remove-images}).
+
+@end table
+
+
+
+@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
+ '("^-- $" ; @r{The standard}
+ "^-- *$" ; @r{A common mangling}
+ "^-------*$" ; @r{Many people just use a looong}
+ ; @r{line of dashes. Shame!}
+ "^ *--------*$" ; @r{Double-shame!}
+ "^________*$" ; @r{Underscores are also popular}
+ "^========*$")) ; @r{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 when displaying articles.
+
+@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 Miscellanea
+@subsection Article Miscellanea
+
+@table @kbd
+@item A t
+@kindex A t (Summary)
+@findex gnus-article-babel
+Translate the article from one language to another
+(@code{gnus-article-babel}).
+
+@end table
+
+
+@node MIME Commands
+@section MIME Commands
+@cindex MIME decoding
+@cindex attachments
+@cindex viewing attachments
+
+The following commands all understand the numerical prefix. For
+instance, @kbd{3 b} means ``view the third @acronym{MIME} part''.
+
+@table @kbd
+@item b
+@itemx K v
+@kindex b (Summary)
+@kindex K v (Summary)
+View the @acronym{MIME} part.
+
+@item K o
+@kindex K o (Summary)
+Save the @acronym{MIME} part.
+
+@item K c
+@kindex K c (Summary)
+Copy the @acronym{MIME} part.
+
+@item K e
+@kindex K e (Summary)
+View the @acronym{MIME} part externally.
+
+@item K i
+@kindex K i (Summary)
+View the @acronym{MIME} part internally.
+
+@item K |
+@kindex K | (Summary)
+Pipe the @acronym{MIME} part to an external command.
+@end table
+
+The rest of these @acronym{MIME} commands do not use the numerical prefix in
+the same manner:
+
+@table @kbd
+@item K b
+@kindex K b (Summary)
+Make all the @acronym{MIME} parts have buttons in front of them. This is
+mostly useful if you wish to save (or perform other actions) on inlined
+parts.
+
+@item K m
+@kindex K m (Summary)
+@findex gnus-summary-repair-multipart
+Some multipart messages are transmitted with missing or faulty headers.
+This command will attempt to ``repair'' these messages so that they can
+be viewed in a more pleasant manner
+(@code{gnus-summary-repair-multipart}).
+
+@item X m
+@kindex X m (Summary)
+@findex gnus-summary-save-parts
+Save all parts matching a @acronym{MIME} type to a directory
+(@code{gnus-summary-save-parts}). Understands the process/prefix
+convention (@pxref{Process/Prefix}).
+
+@item M-t
+@kindex M-t (Summary)
+@findex gnus-summary-toggle-display-buttonized
+Toggle the buttonized display of the article buffer
+(@code{gnus-summary-toggle-display-buttonized}).
+
+@item W M w
+@kindex W M w (Summary)
+@findex gnus-article-decode-mime-words
+Decode RFC 2047-encoded words in the article headers
+(@code{gnus-article-decode-mime-words}).
+
+@item W M c
+@kindex W M c (Summary)
+@findex gnus-article-decode-charset
+Decode encoded article bodies as well as charsets
+(@code{gnus-article-decode-charset}).
+
+This command looks in the @code{Content-Type} header to determine the
+charset. If there is no such header in the article, you can give it a
+prefix, which will prompt for the charset to decode as. In regional
+groups where people post using some common encoding (but do not
+include @acronym{MIME} headers), you can set the @code{charset} group/topic
+parameter to the required charset (@pxref{Group Parameters}).
+
+@item W M v
+@kindex W M v (Summary)
+@findex gnus-mime-view-all-parts
+View all the @acronym{MIME} parts in the current article
+(@code{gnus-mime-view-all-parts}).
+
+@end table
+
+Relevant variables:
+
+@table @code
+@item gnus-ignored-mime-types
+@vindex gnus-ignored-mime-types
+This is a list of regexps. @acronym{MIME} types that match a regexp from
+this list will be completely ignored by Gnus. The default value is
+@code{nil}.
+
+To have all Vcards be ignored, you'd say something like this:
+
+@lisp
+(setq gnus-ignored-mime-types
+ '("text/x-vcard"))
+@end lisp
+
+@item gnus-article-loose-mime
+@vindex gnus-article-loose-mime
+If non-@code{nil}, Gnus won't require the @samp{MIME-Version} header
+before interpreting the message as a @acronym{MIME} message. This helps
+when reading messages from certain broken mail user agents. The
+default is @code{nil}.
+
+@item gnus-article-emulate-mime
+@vindex gnus-article-emulate-mime
+@cindex uuencode
+@cindex yEnc
+There are other, non-@acronym{MIME} encoding methods used. The most common
+is @samp{uuencode}, but yEncode is also getting to be popular. If
+this variable is non-@code{nil}, Gnus will look in message bodies to
+see if it finds these encodings, and if so, it'll run them through the
+Gnus @acronym{MIME} machinery. The default is @code{t}. Only
+single-part yEnc encoded attachments can be decoded. There's no support
+for encoding in Gnus.
+
+@item gnus-unbuttonized-mime-types
+@vindex gnus-unbuttonized-mime-types
+This is a list of regexps. @acronym{MIME} types that match a regexp from
+this list won't have @acronym{MIME} buttons inserted unless they aren't
+displayed or this variable is overridden by
+@code{gnus-buttonized-mime-types}. The default value is
+@code{(".*/.*")}. This variable is only used when
+@code{gnus-inhibit-mime-unbuttonizing} is @code{nil}.
+
+@item gnus-buttonized-mime-types
+@vindex gnus-buttonized-mime-types
+This is a list of regexps. @acronym{MIME} types that match a regexp from
+this list will have @acronym{MIME} buttons inserted unless they aren't
+displayed. This variable overrides
+@code{gnus-unbuttonized-mime-types}. The default value is @code{nil}.
+This variable is only used when @code{gnus-inhibit-mime-unbuttonizing}
+is @code{nil}.
+
+To see e.g. security buttons but no other buttons, you could set this
+variable to @code{("multipart/signed")} and leave
+@code{gnus-unbuttonized-mime-types} at the default value.
+
+You could also add @code{"multipart/alternative"} to this list to
+display radio buttons that allow you to choose one of two media types
+those mails include. See also @code{mm-discouraged-alternatives}
+(@pxref{Display Customization, ,Display Customization, emacs-mime, The
+Emacs MIME Manual}).
+
+@item gnus-inhibit-mime-unbuttonizing
+@vindex gnus-inhibit-mime-unbuttonizing
+If this is non-@code{nil}, then all @acronym{MIME} parts get buttons. The
+default value is @code{nil}.
+
+@item gnus-article-mime-part-function
+@vindex gnus-article-mime-part-function
+For each @acronym{MIME} part, this function will be called with the @acronym{MIME}
+handle as the parameter. The function is meant to be used to allow
+users to gather information from the article (e. g., add Vcard info to
+the bbdb database) or to do actions based on parts (e. g., automatically
+save all jpegs into some directory).
+
+Here's an example function the does the latter:
+
+@lisp
+(defun my-save-all-jpeg-parts (handle)
+ (when (equal (car (mm-handle-type handle)) "image/jpeg")
+ (with-temp-buffer
+ (insert (mm-get-part handle))
+ (write-region (point-min) (point-max)
+ (read-file-name "Save jpeg to: ")))))
+(setq gnus-article-mime-part-function
+ 'my-save-all-jpeg-parts)
+@end lisp
+
+@vindex gnus-mime-multipart-functions
+@item gnus-mime-multipart-functions
+Alist of @acronym{MIME} multipart types and functions to handle them.
+
+@vindex gnus-mime-display-multipart-alternative-as-mixed
+@item gnus-mime-display-multipart-alternative-as-mixed
+Display "multipart/alternative" parts as "multipart/mixed".
+
+@vindex gnus-mime-display-multipart-related-as-mixed
+@item gnus-mime-display-multipart-related-as-mixed
+Display "multipart/related" parts as "multipart/mixed".
+
+If displaying "text/html" is discouraged, see
+@code{mm-discouraged-alternatives}, images or other material inside a
+"multipart/related" part might be overlooked when this variable is
+@code{nil}. @ref{Display Customization, Display Customization, ,
+emacs-mime, Emacs-Mime Manual}.
+
+@vindex gnus-mime-display-multipart-as-mixed
+@item gnus-mime-display-multipart-as-mixed
+Display "multipart" parts as "multipart/mixed". If @code{t}, it
+overrides @code{nil} values of
+@code{gnus-mime-display-multipart-alternative-as-mixed} and
+@code{gnus-mime-display-multipart-related-as-mixed}.
+
+@vindex mm-file-name-rewrite-functions
+@item mm-file-name-rewrite-functions
+List of functions used for rewriting file names of @acronym{MIME} parts.
+Each function takes a file name as input and returns a file name.
+
+Ready-made functions include@*
+@code{mm-file-name-delete-whitespace},
+@code{mm-file-name-trim-whitespace},
+@code{mm-file-name-collapse-whitespace}, and
+@code{mm-file-name-replace-whitespace}. The later uses the value of
+the variable @code{mm-file-name-replace-whitespace} to replace each
+whitespace character in a file name with that string; default value
+is @code{"_"} (a single underscore).
+@findex mm-file-name-delete-whitespace
+@findex mm-file-name-trim-whitespace
+@findex mm-file-name-collapse-whitespace
+@findex mm-file-name-replace-whitespace
+@vindex mm-file-name-replace-whitespace
+
+The standard functions @code{capitalize}, @code{downcase},
+@code{upcase}, and @code{upcase-initials} may be useful, too.
+
+Everybody knows that whitespace characters in file names are evil,
+except those who don't know. If you receive lots of attachments from
+such unenlightened users, you can make live easier by adding
+
+@lisp
+(setq mm-file-name-rewrite-functions
+ '(mm-file-name-trim-whitespace
+ mm-file-name-collapse-whitespace
+ mm-file-name-replace-whitespace))
+@end lisp
+
+@noindent
+to your @file{~/.gnus.el} file.
+
+@end table
+
+
+@node Charsets
+@section Charsets
+@cindex charsets
+
+People use different charsets, and we have @acronym{MIME} to let us know what
+charsets they use. Or rather, we wish we had. Many people use
+newsreaders and mailers that do not understand or use @acronym{MIME}, and
+just send out messages without saying what character sets they use. To
+help a bit with this, some local news hierarchies have policies that say
+what character set is the default. For instance, the @samp{fj}
+hierarchy uses @code{iso-2022-jp}.
+
+@vindex gnus-group-charset-alist
+This knowledge is encoded in the @code{gnus-group-charset-alist}
+variable, which is an alist of regexps (use the first item to match full
+group names) and default charsets to be used when reading these groups.
+
+@vindex gnus-newsgroup-ignored-charsets
+In addition, some people do use soi-disant @acronym{MIME}-aware agents that
+aren't. These blithely mark messages as being in @code{iso-8859-1}
+even if they really are in @code{koi-8}. To help here, the
+@code{gnus-newsgroup-ignored-charsets} variable can be used. The
+charsets that are listed here will be ignored. The variable can be
+set on a group-by-group basis using the group parameters (@pxref{Group
+Parameters}). The default value is @code{(unknown-8bit x-unknown)},
+which includes values some agents insist on having in there.
+
+@vindex gnus-group-posting-charset-alist
+When posting, @code{gnus-group-posting-charset-alist} is used to
+determine which charsets should not be encoded using the @acronym{MIME}
+encodings. For instance, some hierarchies discourage using
+quoted-printable header encoding.
+
+This variable is an alist of regexps and permitted unencoded charsets
+for posting. Each element of the alist has the form @code{(}@var{test
+header body-list}@code{)}, where:
+
+@table @var
+@item test
+is either a regular expression matching the newsgroup header or a
+variable to query,
+@item header
+is the charset which may be left unencoded in the header (@code{nil}
+means encode all charsets),
+@item body-list
+is a list of charsets which may be encoded using 8bit content-transfer
+encoding in the body, or one of the special values @code{nil} (always
+encode using quoted-printable) or @code{t} (always use 8bit).
+@end table
+
+@cindex Russian
+@cindex koi8-r
+@cindex koi8-u
+@cindex iso-8859-5
+@cindex coding system aliases
+@cindex preferred charset
+
+@xref{Encoding Customization, , Encoding Customization, emacs-mime,
+The Emacs MIME Manual}, for additional variables that control which
+MIME charsets are used when sending messages.
+
+Other charset tricks that may be useful, although not Gnus-specific:
+
+If there are several @acronym{MIME} charsets that encode the same Emacs
+charset, you can choose what charset to use by saying the following:
+
+@lisp
+(put-charset-property 'cyrillic-iso8859-5
+ 'preferred-coding-system 'koi8-r)
+@end lisp
+
+This means that Russian will be encoded using @code{koi8-r} instead of
+the default @code{iso-8859-5} @acronym{MIME} charset.
+
+If you want to read messages in @code{koi8-u}, you can cheat and say
+
+@lisp
+(define-coding-system-alias 'koi8-u 'koi8-r)
+@end lisp
+
+This will almost do the right thing.
+
+And finally, to read charsets like @code{windows-1251}, you can say
+something like
+
+@lisp
+(codepage-setup 1251)
+(define-coding-system-alias 'windows-1251 'cp1251)
+@end lisp
+
+
+@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. An alternative way to print
+article is to use Muttprint (@pxref{Saving Articles}).
+
+@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-c
+@kindex C-c C-s C-c (Summary)
+@findex gnus-summary-sort-by-chars
+Sort by article length (@code{gnus-summary-sort-by-chars}).
+
+@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}).
+
+@item C-c C-s C-r
+@kindex C-c C-s C-r (Summary)
+@findex gnus-summary-sort-by-random
+Randomize (@code{gnus-summary-sort-by-random}).
+
+@item C-c C-s C-o
+@kindex C-c C-s C-o (Summary)
+@findex gnus-summary-sort-by-original
+Sort using the default sorting method
+(@code{gnus-summary-sort-by-original}).
+@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 @acronym{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 Gnus 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.
+
+Gnus looks for the @code{Message-ID} in the headers that have already
+been fetched, but also tries all the select methods specified by
+@code{gnus-refer-article-method} if it is not found.
+@end table
+
+@vindex gnus-refer-article-method
+If the group you are reading is located on a back end that does not
+support fetching by @code{Message-ID} very well (like @code{nnspool}),
+you can set @code{gnus-refer-article-method} to an @acronym{NNTP} method. It
+would, perhaps, be best if the @acronym{NNTP} server you consult is the one
+updating the spool you are reading from, but that's not really
+necessary.
+
+It can also be a list of select methods, as well as the special symbol
+@code{current}, which means to use the current select method. If it
+is a list, Gnus will try all the methods in the list until it finds a
+match.
+
+Here's an example setting that will first try the current method, and
+then ask Google if that fails:
+
+@lisp
+(setq gnus-refer-article-method
+ '(current
+ (nnweb "google" (nnweb-type google))))
+@end lisp
+
+Most of the mail back ends support fetching by @code{Message-ID}, but
+do not do a particularly excellent job at it. That is, @code{nnmbox},
+@code{nnbabyl}, @code{nnmaildir}, @code{nnml}, are able to locate
+articles from any groups, while @code{nnfolder}, and @code{nnimap} 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
+@example
+((@var{real-open} . @var{real-close})
+ (@var{sparse-open} . @var{sparse-close})
+ (@var{dummy-open} . @var{dummy-close}))
+@end example
+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.
+
+You may also wish to add the following hook to keep the window minimized
+at all times:
+
+@lisp
+(add-hook 'gnus-configure-windows-hook
+ 'gnus-tree-perhaps-minimize)
+@end lisp
+
+@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
+@group
+@{***@}
+ |--------------------------\-----\-----\
+(***) [Bjo] [Gun] [Gun]
+ |--\-----\-----\ |
+[odd] [Jan] [odd] (***) [Jor]
+ | | |--\
+[Gun] [Eri] [Eri] [odd]
+ |
+ [Paa]
+@end group
+@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{Window Layout}.
+
+
+@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
+@cindex expiring mail
+Run all expirable articles in the current group through the expiry
+process (@code{gnus-summary-expire-articles}). That is, delete all
+expirable articles in the group that have been around for a while.
+(@pxref{Expiring Mail}).
+
+@item B C-M-e
+@kindex B C-M-e (Summary)
+@findex gnus-summary-expire-articles-now
+@cindex expiring mail
+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
+@vindex gnus-preserve-marks
+Move the article from one mail group to another
+(@code{gnus-summary-move-article}). Marks will be preserved if
+@code{gnus-preserve-marks} is non-@code{nil} (which is the default).
+
+@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}). Marks will be preserved if
+@code{gnus-preserve-marks} is non-@code{nil} (which is the default).
+
+@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 I
+@kindex B I (Summary)
+@findex gnus-summary-create-article
+Create an empty article in the current mail newsgroups
+(@code{gnus-summary-create-article}). You will be prompted for a
+@code{From} header and a @code{Subject} header.
+
+@item B r
+@kindex B r (Summary)
+@findex gnus-summary-respool-article
+@vindex gnus-summary-respool-default-method
+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.
+Marks will be preserved if @code{gnus-preserve-marks} is non-@code{nil}
+(which is the default).
+
+@item B w
+@itemx e
+@kindex B w (Summary)
+@kindex e (Summary)
+@findex gnus-summary-edit-article
+@kindex C-c C-c (Article)
+@findex gnus-summary-edit-article-done
+Edit the current article (@code{gnus-summary-edit-article}). To finish
+editing and make the changes permanent, type @kbd{C-c C-c}
+(@code{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 respooling, 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.
+
+@item K E
+@kindex K E (Summary)
+@findex gnus-article-encrypt-body
+@vindex gnus-article-encrypt-protocol
+Encrypt the body of an article (@code{gnus-article-encrypt-body}).
+The body is encrypted with the encryption protocol specified by the
+variable @code{gnus-article-encrypt-protocol}.
+
+@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. (Note that
+@code{gnus-move-split-methods} uses group names where
+@code{gnus-split-methods} uses file names.)
+
+@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::
+* Really Various Summary Commands:: Those pesky non-conformant commands.
+@end menu
+
+@table @code
+@vindex gnus-summary-display-while-building
+@item gnus-summary-display-while-building
+If non-@code{nil}, show and update the summary buffer as it's being
+built. If @code{t}, update the buffer after every line is inserted.
+If the value is an integer, @var{n}, update the display every @var{n}
+lines. The default is @code{nil}.
+
+@vindex gnus-summary-display-arrow
+@item gnus-summary-display-arrow
+If non-@code{nil}, display an arrow in the fringe to indicate the
+current article.
+
+@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-prepared-hook
+@item gnus-summary-prepared-hook
+A hook called as the very last thing after the summary buffer has been
+generated.
+
+@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.
+
+@vindex gnus-alter-articles-to-read-function
+@item gnus-alter-articles-to-read-function
+This function, which takes two parameters (the group name and the list
+of articles to be selected), is called to allow the user to alter the
+list of articles to be selected.
+
+For instance, the following function adds the list of cached articles to
+the list in one particular group:
+
+@lisp
+(defun my-add-cached-articles (group articles)
+ (if (string= group "some.group")
+ (append gnus-newsgroup-cached articles)
+ articles))
+@end lisp
+
+@vindex gnus-newsgroup-variables
+@item gnus-newsgroup-variables
+A list of newsgroup (summary buffer) local variables, or cons of
+variables and their default expressions to be evalled (when the default
+values are not @code{nil}), that should be made global while the summary
+buffer is active.
+
+Note: The default expressions will be evaluated (using function
+@code{eval}) before assignment to the local variable rather than just
+assigned to it. If the default expression is the symbol @code{global},
+that symbol will not be evaluated but the global value of the local
+variable will be used instead.
+
+These variables can be used to set variables in the group parameters
+while still allowing them to affect operations done in other
+buffers. For example:
+
+@lisp
+(setq gnus-newsgroup-variables
+ '(message-use-followup-to
+ (gnus-visible-headers .
+ "^From:\\|^Newsgroups:\\|^Subject:\\|^Date:\\|^To:")))
+@end lisp
+
+Also @pxref{Group Parameters}.
+@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 @acronym{FAQ} (list of frequently asked questions)
+for the current group (@code{gnus-summary-fetch-faq}). Gnus will try
+to get the @acronym{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 (raw) 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 (raw) 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, 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 the header is an empty
+string, the match is done on the entire article. If given a prefix,
+search backward instead.
+
+For instance, @kbd{& RET some.*string RET #} will put the process mark on
+all articles that have heads or bodies that match @samp{some.*string}.
+
+@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}).
+
+@item Y d
+@kindex Y d (Summary)
+@findex gnus-summary-insert-dormant-articles
+Pull all dormant articles (for the current group) into the summary buffer
+(@code{gnus-summary-insert-dormant-articles}).
+
+@end table
+
+
+@node Really Various Summary Commands
+@subsection Really Various Summary Commands
+
+@table @kbd
+
+@item A D
+@itemx C-d
+@kindex C-d (Summary)
+@kindex A 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 C-M-d
+@kindex C-M-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 C-M-e
+@kindex C-M-e (Summary)
+@findex gnus-summary-edit-parameters
+Edit the group parameters (@pxref{Group Parameters}) of the current
+group (@code{gnus-summary-edit-parameters}).
+
+@item C-M-a
+@kindex C-M-a (Summary)
+@findex gnus-summary-customize-parameters
+Customize the group parameters (@pxref{Group Parameters}) of the current
+group (@code{gnus-summary-customize-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 Z Q
+@itemx q
+@kindex Z Z (Summary)
+@kindex Z Q (Summary)
+@kindex q (Summary)
+@findex gnus-summary-exit
+@vindex gnus-summary-exit-hook
+@vindex gnus-summary-prepare-exit-hook
+@vindex gnus-group-no-more-groups-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
+@itemx C-x C-s
+@kindex Z R (Summary)
+@kindex C-x C-s (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
+with an ``updating'' exit. For instance @kbd{Q}
+(@code{gnus-summary-exit-no-update}) does not call this hook.
+
+@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 @acronym{NOV}
+One thing that may cause Gnus to not do the cross-posting thing
+correctly is if you use an @acronym{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 @acronym{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 @acronym{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 @acronym{NNTP} server may fail to generate the @code{Xref} header. This
+is evil and not very common.
+
+@item
+The @acronym{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 @acronym{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 Security
+@section Security
+
+Gnus is able to verify signed messages or decrypt encrypted messages.
+The formats that are supported are @acronym{PGP}, @acronym{PGP/MIME}
+and @acronym{S/MIME}, however you need some external programs to get
+things to work:
+
+@enumerate
+@item
+To handle @acronym{PGP} and @acronym{PGP/MIME} messages, you have to
+install an OpenPGP implementation such as GnuPG. The Lisp interface
+to GnuPG included with Gnus is called PGG (@pxref{Top, ,PGG, pgg, PGG
+Manual}), but Mailcrypt and gpg.el are also supported.
+
+@item
+To handle @acronym{S/MIME} message, you need to install OpenSSL. OpenSSL 0.9.6
+or newer is recommended.
+
+@end enumerate
+
+The variables that control security functionality on reading messages
+include:
+
+@table @code
+@item mm-verify-option
+@vindex mm-verify-option
+Option of verifying signed parts. @code{never}, not verify;
+@code{always}, always verify; @code{known}, only verify known
+protocols. Otherwise, ask user.
+
+@item mm-decrypt-option
+@vindex mm-decrypt-option
+Option of decrypting encrypted parts. @code{never}, no decryption;
+@code{always}, always decrypt; @code{known}, only decrypt known
+protocols. Otherwise, ask user.
+
+@item mml1991-use
+@vindex mml1991-use
+Symbol indicating elisp interface to OpenPGP implementation for
+@acronym{PGP} messages. The default is @code{pgg}, but
+@code{mailcrypt} and @code{gpg} are also supported although
+deprecated.
+
+@item mml2015-use
+@vindex mml2015-use
+Symbol indicating elisp interface to OpenPGP implementation for
+@acronym{PGP/MIME} messages. The default is @code{pgg}, but
+@code{mailcrypt} and @code{gpg} are also supported although
+deprecated.
+
+@end table
+
+By default the buttons that display security information are not
+shown, because they clutter reading the actual e-mail. You can type
+@kbd{K b} manually to display the information. Use the
+@code{gnus-buttonized-mime-types} and
+@code{gnus-unbuttonized-mime-types} variables to control this
+permanently. @ref{MIME Commands} for further details, and hints on
+how to customize these variables to always display security
+information.
+
+@cindex snarfing keys
+@cindex importing PGP keys
+@cindex PGP key ring import
+Snarfing OpenPGP keys (i.e., importing keys from articles into your
+key ring) is not supported explicitly through a menu item or command,
+rather Gnus do detect and label keys as @samp{application/pgp-keys},
+allowing you to specify whatever action you think is appropriate
+through the usual @acronym{MIME} infrastructure. You can use a
+@file{~/.mailcap} entry (@pxref{mailcap, , mailcap, emacs-mime, The
+Emacs MIME Manual}) such as the following to import keys using GNU
+Privacy Guard when you click on the @acronym{MIME} button
+(@pxref{Using MIME}).
+
+@example
+application/pgp-keys; gpg --import --interactive --verbose; needsterminal
+@end example
+@noindent
+This happens to also be the default action defined in
+@code{mailcap-mime-data}.
+
+More information on how to set things for sending outgoing signed and
+encrypted messages up can be found in the message manual
+(@pxref{Security, ,Security, message, Message Manual}).
+
+@node Mailing List
+@section Mailing List
+@cindex mailing list
+@cindex RFC 2396
+
+@kindex A M (summary)
+@findex gnus-mailing-list-insinuate
+Gnus understands some mailing list fields of RFC 2369. To enable it,
+add a @code{to-list} group parameter (@pxref{Group Parameters}),
+possibly using @kbd{A M} (@code{gnus-mailing-list-insinuate}) in the
+summary buffer.
+
+That enables the following commands to the summary buffer:
+
+@table @kbd
+
+@item C-c C-n h
+@kindex C-c C-n h (Summary)
+@findex gnus-mailing-list-help
+Send a message to fetch mailing list help, if List-Help field exists.
+
+@item C-c C-n s
+@kindex C-c C-n s (Summary)
+@findex gnus-mailing-list-subscribe
+Send a message to subscribe the mailing list, if List-Subscribe field exists.
+
+@item C-c C-n u
+@kindex C-c C-n u (Summary)
+@findex gnus-mailing-list-unsubscribe
+Send a message to unsubscribe the mailing list, if List-Unsubscribe
+field exists.
+
+@item C-c C-n p
+@kindex C-c C-n p (Summary)
+@findex gnus-mailing-list-post
+Post to the mailing list, if List-Post field exists.
+
+@item C-c C-n o
+@kindex C-c C-n o (Summary)
+@findex gnus-mailing-list-owner
+Send a message to the mailing list owner, if List-Owner field exists.
+
+@item C-c C-n a
+@kindex C-c C-n a (Summary)
+@findex gnus-mailing-list-owner
+Browse the mailing list archive, if List-Archive field exists.
+
+@end table
+
+
+@node Article Buffer
+@chapter 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 @acronym{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 nauseam---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-boring-article-headers
+You can hide further boring headers by setting
+@code{gnus-treat-hide-boring-headers} to @code{head}. 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 it
+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 addresses as
+the @code{From} header, or if the @code{broken-reply-to} group
+parameter is set.
+@item newsgroups
+Remove the @code{Newsgroups} header if it only contains the current group
+name.
+@item to-address
+Remove the @code{To} header if it only contains the address identical to
+the current group's @code{to-address} parameter.
+@item to-list
+Remove the @code{To} header if it only contains the address identical to
+the current group's @code{to-list} parameter.
+@item cc-list
+Remove the @code{Cc} header if it only contains the address identical to
+the current group's @code{to-list} parameter.
+@item date
+Remove the @code{Date} header if the article is less than three days
+old.
+@item long-to
+Remove the @code{To} and/or @code{Cc} header if it is very long.
+@item many-to
+Remove all @code{To} and/or @code{Cc} headers if there are more than one.
+@end table
+
+To include these 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 MIME
+@cindex @acronym{MIME}
+
+Mime is a standard for waving your hands through the air, aimlessly,
+while people stand around yawning.
+
+@acronym{MIME}, however, is a standard for encoding your articles, aimlessly,
+while all newsreaders die of fear.
+
+@acronym{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-display-mime-function
+@findex gnus-display-mime
+Gnus pushes @acronym{MIME} articles through @code{gnus-display-mime-function}
+to display the @acronym{MIME} parts. This is @code{gnus-display-mime} by
+default, which creates a bundle of clickable buttons that can be used to
+display, save and manipulate the @acronym{MIME} objects.
+
+The following commands are available when you have placed point over a
+@acronym{MIME} button:
+
+@table @kbd
+@findex gnus-article-press-button
+@item RET (Article)
+@kindex RET (Article)
+@itemx BUTTON-2 (Article)
+Toggle displaying of the @acronym{MIME} object
+(@code{gnus-article-press-button}). If built-in viewers can not display
+the object, Gnus resorts to external viewers in the @file{mailcap}
+files. If a viewer has the @samp{copiousoutput} specification, the
+object is displayed inline.
+
+@findex gnus-mime-view-part
+@item M-RET (Article)
+@kindex M-RET (Article)
+@itemx v (Article)
+Prompt for a method, and then view the @acronym{MIME} object using this
+method (@code{gnus-mime-view-part}).
+
+@findex gnus-mime-view-part-as-type
+@item t (Article)
+@kindex t (Article)
+View the @acronym{MIME} object as if it were a different @acronym{MIME} media type
+(@code{gnus-mime-view-part-as-type}).
+
+@findex gnus-mime-view-part-as-charset
+@item C (Article)
+@kindex C (Article)
+Prompt for a charset, and then view the @acronym{MIME} object using this
+charset (@code{gnus-mime-view-part-as-charset}).
+
+@findex gnus-mime-save-part
+@item o (Article)
+@kindex o (Article)
+Prompt for a file name, and then save the @acronym{MIME} object
+(@code{gnus-mime-save-part}).
+
+@findex gnus-mime-save-part-and-strip
+@item C-o (Article)
+@kindex C-o (Article)
+Prompt for a file name, then save the @acronym{MIME} object and strip it from
+the article. Then proceed to article editing, where a reasonable
+suggestion is being made on how the altered article should look
+like. The stripped @acronym{MIME} object will be referred via the
+message/external-body @acronym{MIME} type.
+(@code{gnus-mime-save-part-and-strip}).
+
+@findex gnus-mime-delete-part
+@item d (Article)
+@kindex d (Article)
+Delete the @acronym{MIME} object from the article and replace it with some
+information about the removed @acronym{MIME} object
+(@code{gnus-mime-delete-part}).
+
+@findex gnus-mime-copy-part
+@item c (Article)
+@kindex c (Article)
+Copy the @acronym{MIME} object to a fresh buffer and display this buffer
+(@code{gnus-mime-copy-part}). Compressed files like @file{.gz} and
+@file{.bz2} are automatically decompressed if
+@code{auto-compression-mode} is enabled (@pxref{Compressed Files,,
+Accessing Compressed Files, emacs, The Emacs Editor}).
+
+@findex gnus-mime-print-part
+@item p (Article)
+@kindex p (Article)
+Print the @acronym{MIME} object (@code{gnus-mime-print-part}). This
+command respects the @samp{print=} specifications in the
+@file{.mailcap} file.
+
+@findex gnus-mime-inline-part
+@item i (Article)
+@kindex i (Article)
+Insert the contents of the @acronym{MIME} object into the buffer
+(@code{gnus-mime-inline-part}) as text/plain. If given a prefix, insert
+the raw contents without decoding. If given a numerical prefix, you can
+do semi-manual charset stuff (see
+@code{gnus-summary-show-article-charset-alist} in @ref{Paging the
+Article}).
+
+@findex gnus-mime-view-part-internally
+@item E (Article)
+@kindex E (Article)
+View the @acronym{MIME} object with an internal viewer. If no internal
+viewer is available, use an external viewer
+(@code{gnus-mime-view-part-internally}).
+
+@findex gnus-mime-view-part-externally
+@item e (Article)
+@kindex e (Article)
+View the @acronym{MIME} object with an external viewer.
+(@code{gnus-mime-view-part-externally}).
+
+@findex gnus-mime-pipe-part
+@item | (Article)
+@kindex | (Article)
+Output the @acronym{MIME} object to a process (@code{gnus-mime-pipe-part}).
+
+@findex gnus-mime-action-on-part
+@item . (Article)
+@kindex . (Article)
+Interactively run an action on the @acronym{MIME} object
+(@code{gnus-mime-action-on-part}).
+
+@end table
+
+Gnus will display some @acronym{MIME} objects automatically. The way Gnus
+determines which parts to do this with is described in the Emacs
+@acronym{MIME} manual.
+
+It might be best to just use the toggling functions from the article
+buffer to avoid getting nasty surprises. (For instance, you enter the
+group @samp{alt.sing-a-long} and, before you know it, @acronym{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.
+
+Also @pxref{MIME Commands}.
+
+
+@node Customizing Articles
+@section Customizing Articles
+@cindex article customization
+
+A slew of functions for customizing how the articles are to look like
+exist. You can call these functions interactively
+(@pxref{Article Washing}), or you can have them
+called automatically when you select the articles.
+
+To have them called automatically, you should set the corresponding
+``treatment'' variable. For instance, to have headers hidden, you'd set
+@code{gnus-treat-hide-headers}. Below is a list of variables that can
+be set, but first we discuss the values these variables can have.
+
+Note: Some values, while valid, make little sense. Check the list below
+for sensible values.
+
+@enumerate
+@item
+@code{nil}: Don't do this treatment.
+
+@item
+@code{t}: Do this treatment on all body parts.
+
+@item
+@code{head}: Do the treatment on the headers.
+
+@item
+@code{last}: Do this treatment on the last part.
+
+@item
+An integer: Do this treatment on all body parts that have a length less
+than this number.
+
+@item
+A list of strings: Do this treatment on all body parts that are in
+articles that are read in groups that have names that match one of the
+regexps in the list.
+
+@item
+A list where the first element is not a string:
+
+The list is evaluated recursively. The first element of the list is a
+predicate. The following predicates are recognized: @code{or},
+@code{and}, @code{not} and @code{typep}. Here's an example:
+
+@lisp
+(or last
+ (typep "text/x-vcard"))
+@end lisp
+
+@end enumerate
+
+You may have noticed that the word @dfn{part} is used here. This refers
+to the fact that some messages are @acronym{MIME} multipart articles that may
+be divided into several parts. Articles that are not multiparts are
+considered to contain just a single part.
+
+@vindex gnus-article-treat-types
+Are the treatments applied to all sorts of multipart parts? Yes, if you
+want to, but by default, only @samp{text/plain} parts are given the
+treatment. This is controlled by the @code{gnus-article-treat-types}
+variable, which is a list of regular expressions that are matched to the
+type of the part. This variable is ignored if the value of the
+controlling variable is a predicate list, as described above.
+
+@ifinfo
+@c Avoid sort of redundant entries in the same section for the printed
+@c manual, but add them in info to allow `i gnus-treat-foo-bar RET' or
+@c `i foo-bar'.
+@vindex gnus-treat-buttonize
+@vindex gnus-treat-buttonize-head
+@vindex gnus-treat-capitalize-sentences
+@vindex gnus-treat-overstrike
+@vindex gnus-treat-strip-cr
+@vindex gnus-treat-strip-headers-in-body
+@vindex gnus-treat-strip-leading-blank-lines
+@vindex gnus-treat-strip-multiple-blank-lines
+@vindex gnus-treat-strip-pem
+@vindex gnus-treat-strip-trailing-blank-lines
+@vindex gnus-treat-unsplit-urls
+@vindex gnus-treat-wash-html
+@vindex gnus-treat-date-english
+@vindex gnus-treat-date-iso8601
+@vindex gnus-treat-date-lapsed
+@vindex gnus-treat-date-local
+@vindex gnus-treat-date-original
+@vindex gnus-treat-date-user-defined
+@vindex gnus-treat-date-ut
+@vindex gnus-treat-from-picon
+@vindex gnus-treat-mail-picon
+@vindex gnus-treat-newsgroups-picon
+@vindex gnus-treat-display-smileys
+@vindex gnus-treat-body-boundary
+@vindex gnus-treat-display-x-face
+@vindex gnus-treat-display-face
+@vindex gnus-treat-emphasize
+@vindex gnus-treat-fill-article
+@vindex gnus-treat-fill-long-lines
+@vindex gnus-treat-hide-boring-headers
+@vindex gnus-treat-hide-citation
+@vindex gnus-treat-hide-citation-maybe
+@vindex gnus-treat-hide-headers
+@vindex gnus-treat-hide-signature
+@vindex gnus-treat-strip-banner
+@vindex gnus-treat-strip-list-identifiers
+@vindex gnus-treat-highlight-citation
+@vindex gnus-treat-highlight-headers
+@vindex gnus-treat-highlight-signature
+@vindex gnus-treat-play-sounds
+@vindex gnus-treat-translate
+@vindex gnus-treat-x-pgp-sig
+@vindex gnus-treat-unfold-headers
+@vindex gnus-treat-fold-headers
+@vindex gnus-treat-fold-newsgroups
+@vindex gnus-treat-leading-whitespace
+@end ifinfo
+
+The following treatment options are available. The easiest way to
+customize this is to examine the @code{gnus-article-treat} customization
+group. Values in parenthesis are suggested sensible values. Others are
+possible but those listed are probably sufficient for most people.
+
+@table @code
+@item gnus-treat-buttonize (t, integer)
+@item gnus-treat-buttonize-head (head)
+
+@xref{Article Buttons}.
+
+@item gnus-treat-capitalize-sentences (t, integer)
+@item gnus-treat-overstrike (t, integer)
+@item gnus-treat-strip-cr (t, integer)
+@item gnus-treat-strip-headers-in-body (t, integer)
+@item gnus-treat-strip-leading-blank-lines (t, integer)
+@item gnus-treat-strip-multiple-blank-lines (t, integer)
+@item gnus-treat-strip-pem (t, last, integer)
+@item gnus-treat-strip-trailing-blank-lines (t, last, integer)
+@item gnus-treat-unsplit-urls (t, integer)
+@item gnus-treat-wash-html (t, integer)
+
+@xref{Article Washing}.
+
+@item gnus-treat-date-english (head)
+@item gnus-treat-date-iso8601 (head)
+@item gnus-treat-date-lapsed (head)
+@item gnus-treat-date-local (head)
+@item gnus-treat-date-original (head)
+@item gnus-treat-date-user-defined (head)
+@item gnus-treat-date-ut (head)
+
+@xref{Article Date}.
+
+@item gnus-treat-from-picon (head)
+@item gnus-treat-mail-picon (head)
+@item gnus-treat-newsgroups-picon (head)
+
+@xref{Picons}.
+
+@item gnus-treat-display-smileys (t, integer)
+
+@item gnus-treat-body-boundary (head)
+
+@vindex gnus-body-boundary-delimiter
+Adds a delimiter between header and body, the string used as delimiter
+is controlled by @code{gnus-body-boundary-delimiter}.
+
+@xref{Smileys}.
+
+@vindex gnus-treat-display-x-face
+@item gnus-treat-display-x-face (head)
+
+@xref{X-Face}.
+
+@vindex gnus-treat-display-face
+@item gnus-treat-display-face (head)
+
+@xref{Face}.
+
+@vindex gnus-treat-emphasize
+@item gnus-treat-emphasize (t, head, integer)
+@vindex gnus-treat-fill-article
+@item gnus-treat-fill-article (t, integer)
+@vindex gnus-treat-fill-long-lines
+@item gnus-treat-fill-long-lines (t, integer)
+@vindex gnus-treat-hide-boring-headers
+@item gnus-treat-hide-boring-headers (head)
+@vindex gnus-treat-hide-citation
+@item gnus-treat-hide-citation (t, integer)
+@vindex gnus-treat-hide-citation-maybe
+@item gnus-treat-hide-citation-maybe (t, integer)
+@vindex gnus-treat-hide-headers
+@item gnus-treat-hide-headers (head)
+@vindex gnus-treat-hide-signature
+@item gnus-treat-hide-signature (t, last)
+@vindex gnus-treat-strip-banner
+@item gnus-treat-strip-banner (t, last)
+@vindex gnus-treat-strip-list-identifiers
+@item gnus-treat-strip-list-identifiers (head)
+
+@xref{Article Hiding}.
+
+@vindex gnus-treat-highlight-citation
+@item gnus-treat-highlight-citation (t, integer)
+@vindex gnus-treat-highlight-headers
+@item gnus-treat-highlight-headers (head)
+@vindex gnus-treat-highlight-signature
+@item gnus-treat-highlight-signature (t, last, integer)
+
+@xref{Article Highlighting}.
+
+@vindex gnus-treat-play-sounds
+@item gnus-treat-play-sounds
+@vindex gnus-treat-translate
+@item gnus-treat-translate
+@vindex gnus-treat-x-pgp-sig
+@item gnus-treat-x-pgp-sig (head)
+
+@vindex gnus-treat-unfold-headers
+@item gnus-treat-unfold-headers (head)
+@vindex gnus-treat-fold-headers
+@item gnus-treat-fold-headers (head)
+@vindex gnus-treat-fold-newsgroups
+@item gnus-treat-fold-newsgroups (head)
+@vindex gnus-treat-leading-whitespace
+@item gnus-treat-leading-whitespace (head)
+
+@xref{Article Header}.
+
+
+@end table
+
+@vindex gnus-part-display-hook
+You can, of course, write your own functions to be called from
+@code{gnus-part-display-hook}. The functions are called narrowed to the
+part, 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.
+
+
+@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.
+
+@kindex v (Article)
+@cindex keys, reserved for users (Article)
+The key @kbd{v} is reserved for users. You can bind it to some
+command or better use it as a prefix key.
+
+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}).
+This is exactly the same as @kbd{h SPACE h}.
+
+@item DEL
+@kindex DEL (Article)
+@findex gnus-article-prev-page
+Scroll backwards one page (@code{gnus-article-prev-page}).
+This is exactly the same as @kbd{h DEL h}.
+
+@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}).
+
+@item R
+@kindex R (Article)
+@findex gnus-article-reply-with-original
+Send a reply to the current article and yank the current article
+(@code{gnus-article-reply-with-original}). If given a prefix, make a
+wide reply. If the region is active, only yank the text in the
+region.
+
+@item F
+@kindex F (Article)
+@findex gnus-article-followup-with-original
+Send a followup to the current article and yank the current article
+(@code{gnus-article-followup-with-original}). If given a prefix, make
+a wide reply. If the region is active, only yank the text in the
+region.
+
+
+@end table
+
+
+@node Misc Article
+@section Misc Article
+
+@table @code
+
+@item gnus-single-article-buffer
+@vindex gnus-single-article-buffer
+@cindex article buffers, several
+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-decode-hook
+@item gnus-article-decode-hook
+@cindex @acronym{MIME}
+Hook used to decode @acronym{MIME} articles. The default value is
+@code{(article-decode-charset article-decode-encoded-words)}
+
+@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.
+
+@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-over-scroll
+@item gnus-article-over-scroll
+If non-@code{nil}, allow scrolling the article buffer even when there
+no more new text to scroll in. The default is @code{nil}.
+
+@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{Summary Buffer Mode
+Line}). It accepts the same format specifications as that variable,
+with two extensions:
+
+@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. The characters and their meaning:
+
+@table @samp
+
+@item c
+Displayed when cited text may be hidden in the article buffer.
+
+@item h
+Displayed when headers are hidden in the article buffer.
+
+@item p
+Displayed when article is digitally signed or encrypted, and Gnus has
+hidden the security headers. (N.B. does not tell anything about
+security status, i.e. good or bad signature.)
+
+@item s
+Displayed when the signature has been hidden in the Article buffer.
+
+@item o
+Displayed when Gnus has treated overstrike characters in the article buffer.
+
+@item e
+Displayed when Gnus has treated emphasised strings in the article buffer.
+
+@end table
+
+@item m
+The number of @acronym{MIME} parts in the article.
+
+@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).
+
+@cindex IDNA
+@cindex internationalized domain names
+@vindex gnus-use-idna
+@item gnus-use-idna
+This variable controls whether Gnus performs IDNA decoding of
+internationalized domain names inside @samp{From}, @samp{To} and
+@samp{Cc} headers. This requires
+@uref{http://www.gnu.org/software/libidn/, GNU Libidn}, and this
+variable is only enabled if you have installed it.
+
+@end table
+
+
+@node Composing Messages
+@chapter Composing Messages
+@cindex composing messages
+@cindex messages
+@cindex mail
+@cindex sending mail
+@cindex reply
+@cindex followup
+@cindex post
+@cindex using gpg
+@cindex using s/mime
+@cindex using smime
+
+@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, , Overview, message,
+Message Manual}. Where the message will be posted/mailed to depends
+on your setup (@pxref{Posting Server}).
+
+@menu
+* Mail:: Mailing and replying.
+* Posting Server:: What server should you post and mail via?
+* POP before SMTP:: You cannot send a mail unless you read a mail.
+* 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?
+* Signing and encrypting:: How to compose secure messages.
+@end menu
+
+Also @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. If
+@code{nil} include all headers.
+
+@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}.
+
+@item gnus-confirm-mail-reply-to-news
+@vindex gnus-confirm-mail-reply-to-news
+If non-@code{nil}, Gnus will ask you for a confirmation when you are
+about to reply to news articles by mail. If it is @code{nil}, nothing
+interferes in what you want to do. This can also be a function
+receiving the group name as the only parameter which should return
+non-@code{nil} if a confirmation is needed, or a regular expression
+matching group names, where confirmation should be asked for.
+
+If you find yourself never wanting to reply to mail, but occasionally
+press @kbd{R} anyway, this variable might be for you.
+
+@item gnus-confirm-treat-mail-like-news
+@vindex gnus-confirm-treat-mail-like-news
+If non-@code{nil}, Gnus also requests confirmation according to
+@code{gnus-confirm-mail-reply-to-news} when replying to mail. This is
+useful for treating mailing lists like newsgroups.
+
+@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.
+
+It can be quite complicated.
+
+@vindex gnus-post-method
+When posting news, Message usually invokes @code{message-send-news}
+(@pxref{News Variables, , News Variables, message, Message Manual}).
+Normally, Gnus will 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). However. If the server
+you're reading from 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, to get back the default behavior, 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 native select method,
+you can set this variable to @code{native}.
+
+When sending mail, Message invokes @code{message-send-mail-function}.
+The default function, @code{message-send-mail-with-sendmail}, pipes
+your article to the @code{sendmail} binary for further queuing and
+sending. When your local system is not configured for sending mail
+using @code{sendmail}, and you have access to a remote @acronym{SMTP}
+server, you can set @code{message-send-mail-function} to
+@code{smtpmail-send-it} and make sure to setup the @code{smtpmail}
+package correctly. An example:
+
+@lisp
+(setq message-send-mail-function 'smtpmail-send-it
+ smtpmail-default-smtp-server "YOUR SMTP HOST")
+@end lisp
+
+To the thing similar to this, there is
+@code{message-smtpmail-send-it}. It is useful if your @acronym{ISP}
+requires the @acronym{POP}-before-@acronym{SMTP} authentication.
+@xref{POP before SMTP}.
+
+Other possible choices for @code{message-send-mail-function} includes
+@code{message-send-mail-with-mh}, @code{message-send-mail-with-qmail},
+and @code{feedmail-send-it}.
+
+@node POP before SMTP
+@section POP before SMTP
+@cindex pop before smtp
+@findex message-smtpmail-send-it
+@findex mail-source-touch-pop
+
+Does your @acronym{ISP} require the @acronym{POP}-before-@acronym{SMTP}
+authentication? It is whether you need to connect to the @acronym{POP}
+mail server within a certain time before sending mails. If so, there is
+a convenient way. To do that, put the following lines in your
+@file{~/.gnus.el} file:
+
+@lisp
+(setq message-send-mail-function 'message-smtpmail-send-it)
+(add-hook 'message-send-mail-hook 'mail-source-touch-pop)
+@end lisp
+
+@noindent
+It means to let Gnus connect to the @acronym{POP} mail server in advance
+whenever you send a mail. The @code{mail-source-touch-pop} function
+does only a @acronym{POP} authentication according to the value of
+@code{mail-sources} without fetching mails, just before sending a mail.
+Note that you have to use @code{message-smtpmail-send-it} which runs
+@code{message-send-mail-hook} rather than @code{smtpmail-send-it} and
+set the value of @code{mail-sources} for a @acronym{POP} connection
+correctly. @xref{Mail Sources}.
+
+If you have two or more @acronym{POP} mail servers set in
+@code{mail-sources}, you may want to specify one of them to
+@code{mail-source-primary-source} as the @acronym{POP} mail server to be
+used for the @acronym{POP}-before-@acronym{SMTP} authentication. If it
+is your primary @acronym{POP} mail server (i.e., you are fetching mails
+mainly from that server), you can set it permanently as follows:
+
+@lisp
+(setq mail-source-primary-source
+ '(pop :server "pop3.mail.server"
+ :password "secret"))
+@end lisp
+
+@noindent
+Otherwise, bind it dynamically only when performing the
+@acronym{POP}-before-@acronym{SMTP} authentication as follows:
+
+@lisp
+(add-hook 'message-send-mail-hook
+ (lambda ()
+ (let ((mail-source-primary-source
+ '(pop :server "pop3.mail.server"
+ :password "secret")))
+ (mail-source-touch-pop))))
+@end lisp
+
+@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 @acronym{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.
+
+@item gnus-user-agent
+@vindex gnus-user-agent
+@cindex User-Agent
+
+This variable controls which information should be exposed in the
+User-Agent header. It can be a list of symbols or a string. Valid
+symbols are @code{gnus} (show Gnus version) and @code{emacs} (show Emacs
+version). In addition to the Emacs version, you can add @code{codename}
+(show (S)XEmacs codename) or either @code{config} (show system
+configuration) or @code{type} (show system type). If you set it to a
+string, be sure to use a valid format, see RFC 2616.
+
+@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
+
+If you want to change the @code{ispell} dictionary based on what group
+you're in, you could say something like the following:
+
+@lisp
+(add-hook 'gnus-select-group-hook
+ (lambda ()
+ (cond
+ ((string-match
+ "^de\\." (gnus-group-real-name gnus-newsgroup-name))
+ (ispell-change-dictionary "deutsch"))
+ (t
+ (ispell-change-dictionary "english")))))
+@end lisp
+
+Modify to suit your needs.
+
+
+@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.
+
+For archiving interesting messages in a group you read, see the
+@kbd{B c} (@code{gnus-summary-copy-article}) command (@pxref{Mail
+Group Commands}).
+
+@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 likable 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:
+
+@table @asis
+@item a string
+Messages will be saved in that group.
+
+Note that you can include a select method in the group name, then the
+message will not be stored in the select method given by
+@code{gnus-message-archive-method}, but in the select method specified
+by the group name, instead. Suppose @code{gnus-message-archive-method}
+has the default value shown above. Then setting
+@code{gnus-message-archive-group} to @code{"foo"} means that outgoing
+messages are stored in @samp{nnfolder+archive:foo}, but if you use the
+value @code{"nnml:foo"}, then outgoing messages will be stored in
+@samp{nnml:foo}.
+
+@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 table
+
+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")))))
+@end lisp
+
+@c (XEmacs 19.13 doesn't have @code{format-time-string}, so you'll have to
+@c 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.
+
+@item gnus-gcc-mark-as-read
+@vindex gnus-gcc-mark-as-read
+If non-@code{nil}, automatically mark @code{Gcc} articles as read.
+
+@item gnus-gcc-externalize-attachments
+@vindex gnus-gcc-externalize-attachments
+If @code{nil}, attach files as normal parts in Gcc copies; if a regexp
+and matches the Gcc group name, attach files as external parts; if it is
+@code{all}, attach local files as external parts; if it is other
+non-@code{nil}, the behavior is the same as @code{all}, but it may be
+changed in the future.
+
+@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 is the form @code{(header @var{match} @var{regexp})}, then Gnus
+will look in the original article for a header whose name is
+@var{match} and compare that @var{regexp}. @var{match} and
+@var{regexp} are strings. (The original article is the one you are
+replying or following up to. If you are not composing a reply or a
+followup, then there is nothing to match against.) If the
+@code{match} is 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 an arbitrary amount of @dfn{attributes}. Each
+attribute consists of a @code{(@var{name} @var{value})} pair. In
+addition, you can also use the @code{(@var{name} :file @var{value})}
+form or the @code{(@var{name} :value @var{value})} form. Where
+@code{:file} signifies @var{value} represents a file name and its
+contents should be used as the attribute value, @code{:value} signifies
+@var{value} does not represent a file name explicitly. The attribute
+name can be one of:
+
+@itemize @bullet
+@item @code{signature}
+@item @code{signature-file}
+@item @code{x-face-file}
+@item @code{address}, overriding @code{user-mail-address}
+@item @code{name}, overriding @code{(user-full-name)}
+@item @code{body}
+@end itemize
+
+The attribute name can also be a string or a symbol. In that case,
+this will be used as a header name, and the value will be inserted in
+the headers of the article; if the value is @code{nil}, the header
+name will be removed. If the attribute name is @code{eval}, the form
+is evaluated, and the result is thrown away.
+
+The attribute value can be a string (used verbatim), a function with
+zero arguments (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). The functions and sexps are called/@code{eval}ed in the
+message buffer that is being set up. The headers of the current article
+are available through the @code{message-reply-headers} variable, which
+is a vector of the following headers: number subject from date id
+references chars lines xref extra.
+
+@vindex message-reply-headers
+
+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 @code{message-news-p} and @code{message-mail-p} functions.
+
+@findex message-mail-p
+@findex message-news-p
+
+So here's a new example:
+
+@lisp
+(setq gnus-posting-styles
+ '((".*"
+ (signature-file "~/.signature")
+ (name "User Name")
+ (x-face-file "~/.xface")
+ (x-url (getenv "WWW_HOME"))
+ (organization "People's Front Against MWM"))
+ ("^rec.humor"
+ (signature my-funny-signature-randomizer))
+ ((equal (system-name) "gnarly") ;; @r{A form}
+ (signature my-quote-randomizer))
+ (message-news-p ;; @r{A function symbol}
+ (signature my-news-signature))
+ (window-system ;; @r{A value symbol}
+ ("X-Window-System" (format "%s" window-system)))
+ ;; @r{If I'm replying to Larsi, set the Organization header.}
+ ((header "from" "larsi.*org")
+ (Organization "Somewhere, Inc."))
+ ((posting-from-work-p) ;; @r{A user defined function}
+ (signature-file "~/.work-signature")
+ (address "user@@bar.foo")
+ (body "You are fired.\n\nSincerely, your boss.")
+ (organization "Important Work, Inc"))
+ ("nnml:.*"
+ (From (save-excursion
+ (set-buffer gnus-article-buffer)
+ (message-fetch-field "to"))))
+ ("^nn.+:"
+ (signature-file "~/.mail-signature"))))
+@end lisp
+
+The @samp{nnml:.*} rule means that you use the @code{To} address as the
+@code{From} address in all your outgoing replies, which might be handy
+if you fill many roles.
+You may also use @code{message-alternative-emails} instead.
+@xref{Message Headers, ,Message Headers, message, Message Manual}.
+
+@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. The special properties of the draft group comes from
+a group property (@pxref{Group Parameters}), and if lost the group
+behaves like any other group. This means the commands below will not
+be available. To restore the special properties of the group, the
+simplest way is to kill the group, using @kbd{C-k}, and restart
+Gnus. The group is automatically created again with the
+correct parameters. The content of the group is not lost.
+
+@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
+@kindex D s (Draft)
+@findex gnus-draft-send-message
+@kindex D S (Draft)
+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.
+
+@findex gnus-draft-toggle-sending
+@kindex D t (Draft)
+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 Signing and encrypting
+@section Signing and encrypting
+@cindex using gpg
+@cindex using s/mime
+@cindex using smime
+
+Gnus can digitally sign and encrypt your messages, using vanilla
+@acronym{PGP} format or @acronym{PGP/MIME} or @acronym{S/MIME}. For
+decoding such messages, see the @code{mm-verify-option} and
+@code{mm-decrypt-option} options (@pxref{Security}).
+
+@vindex gnus-message-replysign
+@vindex gnus-message-replyencrypt
+@vindex gnus-message-replysignencrypted
+Often, you would like to sign replies to people who send you signed
+messages. Even more often, you might want to encrypt messages which
+are in reply to encrypted messages. Gnus offers
+@code{gnus-message-replysign} to enable the former, and
+@code{gnus-message-replyencrypt} for the latter. In addition, setting
+@code{gnus-message-replysignencrypted} (on by default) will sign
+automatically encrypted messages.
+
+Instructing @acronym{MML} to perform security operations on a
+@acronym{MIME} part is done using the @kbd{C-c C-m s} key map for
+signing and the @kbd{C-c C-m c} key map for encryption, as follows.
+
+@table @kbd
+
+@item C-c C-m s s
+@kindex C-c C-m s s (Message)
+@findex mml-secure-message-sign-smime
+
+Digitally sign current message using @acronym{S/MIME}.
+
+@item C-c C-m s o
+@kindex C-c C-m s o (Message)
+@findex mml-secure-message-sign-pgp
+
+Digitally sign current message using @acronym{PGP}.
+
+@item C-c C-m s p
+@kindex C-c C-m s p (Message)
+@findex mml-secure-message-sign-pgp
+
+Digitally sign current message using @acronym{PGP/MIME}.
+
+@item C-c C-m c s
+@kindex C-c C-m c s (Message)
+@findex mml-secure-message-encrypt-smime
+
+Digitally encrypt current message using @acronym{S/MIME}.
+
+@item C-c C-m c o
+@kindex C-c C-m c o (Message)
+@findex mml-secure-message-encrypt-pgp
+
+Digitally encrypt current message using @acronym{PGP}.
+
+@item C-c C-m c p
+@kindex C-c C-m c p (Message)
+@findex mml-secure-message-encrypt-pgpmime
+
+Digitally encrypt current message using @acronym{PGP/MIME}.
+
+@item C-c C-m C-n
+@kindex C-c C-m C-n (Message)
+@findex mml-unsecure-message
+Remove security related @acronym{MML} tags from message.
+
+@end table
+
+@xref{Security, ,Security, message, Message Manual}, for more information.
+
+@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
+@acronym{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 back end 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 back end in question.
+
+One could say that a select method defines a @dfn{virtual server}---so
+we do just that (@pxref{Server Buffer}).
+
+The @dfn{name} of the group is the name the back end will recognize the
+group as.
+
+For instance, the group @samp{soc.motss} on the @acronym{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}
+back end just knows this group as @samp{soc.motss}.
+
+The different methods all have their peculiarities, of course.
+
+@menu
+* Server Buffer:: Making and editing virtual servers.
+* Getting News:: Reading USENET news with Gnus.
+* Getting Mail:: Reading your personal mail with Gnus.
+* Browsing the Web:: Getting messages from a plethora of Web sources.
+* IMAP:: Using Gnus as a @acronym{IMAP} client.
+* Other Sources:: Reading directories, files, SOUP packets.
+* Combined Groups:: Combining groups into one group.
+* Email Based Diary:: Using mails to manage diary events in Gnus.
+* Gnus Unplugged:: Reading news and mail offline.
+@end menu
+
+
+@node Server Buffer
+@section 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 back end 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
+back end represents a virtual server.
+
+For instance, the @code{nntp} back end may be used to connect to several
+different actual @acronym{NNTP} servers, or, perhaps, to many different ports
+on the same actual @acronym{NNTP} server. You tell Gnus which back end 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
+@acronym{NNTP} server @samp{news.funet.fi} on port number 13, which
+hangs if queried for @acronym{NOV} headers and has a buggy select. Ahem.
+Anyway, 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 back end 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.
+
+@item a
+Whether this server is agentized.
+@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 v
+@kindex v (Server)
+@cindex keys, reserved for users (Server)
+The key @kbd{v} is reserved for users. You can bind it to some
+command or better use it as a prefix key.
+
+@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 back end that has gotten out of sync.
+
+@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
+back end, and the second is the @dfn{address}, or @dfn{name}, if you
+will.
+
+After these two elements, there may be an arbitrary number of
+@code{(@var{variable} @var{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 back end to find out what
+variables are relevant, but here's an @code{nnmh} example:
+
+@code{nnmh} is a mail back end 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
+
+@cindex proxy
+@cindex firewall
+
+If you are behind a firewall and only have access to the @acronym{NNTP}
+server from the firewall machine, you can instruct Gnus to @code{rlogin}
+on the firewall machine and telnet from there to the @acronym{NNTP} server.
+Doing this can be rather fiddly, but your virtual server definition
+should probably look something like this:
+
+@lisp
+(nntp "firewall"
+ (nntp-open-connection-function nntp-open-via-rlogin-and-telnet)
+ (nntp-via-address "the.firewall.machine")
+ (nntp-address "the.real.nntp.host")
+ (nntp-end-of-line "\n"))
+@end lisp
+
+If you want to use the wonderful @code{ssh} program to provide a
+compressed connection over the modem line, you could add the following
+configuration to the example above:
+
+@lisp
+ (nntp-via-rlogin-command "ssh")
+@end lisp
+
+See also @code{nntp-via-rlogin-command-switches}.
+
+If you're behind a firewall, but have direct access to the outside world
+through a wrapper command like "runsocks", you could open a socksified
+telnet connection to the news server as follows:
+
+@lisp
+(nntp "outside"
+ (nntp-pre-command "runsocks")
+ (nntp-open-connection-function nntp-open-via-telnet)
+ (nntp-address "the.news.server")
+ (nntp-end-of-line "\n"))
+@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{nnml} to read the cache. You
+could also use @code{nnspool} or @code{nnmh}, though.
+
+Type @kbd{a nnml RET cache RET}.
+
+You should now have a brand new @code{nnml} 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
+(nnml "cache")
+@end lisp
+
+Change that to:
+
+@lisp
+(nnml "cache"
+ (nnml-directory "~/News/cache/")
+ (nnml-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
+@cindex server variables
+@cindex server parameters
+
+One sticky point when defining variables (both on back ends 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 back end, see each back end'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
+
+Server variables are often called @dfn{server parameters}.
+
+@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{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}).
+
+@item L
+@kindex L (Server)
+@findex gnus-server-offline-server
+Set server status to offline (@code{gnus-server-offline-server}).
+
+@end table
+
+
+@node Getting News
+@section Getting News
+@cindex reading news
+@cindex news back ends
+
+A newsreader is normally used for reading news. Gnus currently provides
+only two methods of getting news---it can read from an @acronym{NNTP} server,
+or it can read from a local spool.
+
+@menu
+* NNTP:: Reading news from an @acronym{NNTP} server.
+* News Spool:: Reading news from the local spool.
+@end menu
+
+
+@node NNTP
+@subsection NNTP
+@cindex nntp
+
+Subscribing to a foreign group from an @acronym{NNTP} server is rather easy.
+You just specify @code{nntp} as method and the address of the @acronym{NNTP}
+server as the, uhm, address.
+
+If the @acronym{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 authentication
+@cindex nntp authentication
+@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 @acronym{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 @acronym{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}. In addition Gnus introduces two new tokens, not present
+in the original @file{.netrc}/@code{ftp} syntax, namely @samp{port} and
+@samp{force}. (This is the only way the @file{.authinfo} file format
+deviates from the @file{.netrc} file format.) @samp{port} is used to
+indicate what port on the server the credentials apply to and
+@samp{force} is explained below.
+
+@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 @acronym{NNTP} server doesn't support @acronym{NOV} headers, this back end
+will collect headers by sending a series of @code{head} commands. To
+speed things up, the back end 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 @acronym{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} back end should wait for a
+connection before giving up. If it is @code{nil}, which is the default,
+no timeouts are done.
+
+@item nntp-nov-is-evil
+@vindex nntp-nov-is-evil
+If the @acronym{NNTP} server does not support @acronym{NOV}, you could set this
+variable to @code{t}, but @code{nntp} usually checks automatically whether @acronym{NOV}
+can be used.
+
+@item nntp-xover-commands
+@vindex nntp-xover-commands
+@cindex @acronym{NOV}
+@cindex XOVER
+List of strings used as commands to fetch @acronym{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 @acronym{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 @acronym{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-xref-number-is-evil
+@vindex nntp-xref-number-is-evil
+When Gnus refers to an article having the @code{Message-ID} that a user
+specifies or having the @code{Message-ID} of the parent article of the
+current one (@pxref{Finding the Parent}), Gnus sends a @code{HEAD}
+command to the @acronym{NNTP} server to know where it is, and the server
+returns the data containing the pairs of a group and an article number
+in the @code{Xref} header. Gnus normally uses the article number to
+refer to the article if the data shows that that article is in the
+current group, while it uses the @code{Message-ID} otherwise. However,
+some news servers, e.g., ones running Diablo, run multiple engines
+having the same articles but article numbers are not kept synchronized
+between them. In that case, the article number that appears in the
+@code{Xref} header varies by which engine is chosen, so you cannot refer
+to the parent article that is in the current group, for instance. If
+you connect to such a server, set this variable to a non-@code{nil}
+value, and Gnus never uses article numbers. For example:
+
+@lisp
+(setq gnus-select-method
+ '(nntp "newszilla"
+ (nntp-address "newszilla.example.com")
+ (nntp-xref-number-is-evil t)
+ @dots{}))
+@end lisp
+
+The default value of this server variable is @code{nil}.
+
+@item nntp-prepare-server-hook
+@vindex nntp-prepare-server-hook
+A hook run before attempting to connect to an @acronym{NNTP} server.
+
+@item nntp-record-commands
+@vindex nntp-record-commands
+If non-@code{nil}, @code{nntp} will log all commands it sends to the
+@acronym{NNTP} server (along with a timestamp) in the @samp{*nntp-log*}
+buffer. This is useful if you are debugging a Gnus/@acronym{NNTP} connection
+that doesn't seem to work.
+
+@item nntp-open-connection-function
+@vindex nntp-open-connection-function
+It is possible to customize how the connection to the nntp server will
+be opened. If you specify an @code{nntp-open-connection-function}
+parameter, Gnus will use that function to establish the connection.
+Six pre-made functions are supplied. These functions can be grouped in
+two categories: direct connection functions (four pre-made), and
+indirect ones (two pre-made).
+
+@item nntp-never-echoes-commands
+@vindex nntp-never-echoes-commands
+Non-@code{nil} means the nntp server never echoes commands. It is
+reported that some nntps server doesn't echo commands. So, you may want
+to set this to non-@code{nil} in the method for such a server setting
+@code{nntp-open-connection-function} to @code{nntp-open-ssl-stream} for
+example. The default value is @code{nil}. Note that the
+@code{nntp-open-connection-functions-never-echo-commands} variable
+overrides the @code{nil} value of this variable.
+
+@item nntp-open-connection-functions-never-echo-commands
+@vindex nntp-open-connection-functions-never-echo-commands
+List of functions that never echo commands. Add or set a function which
+you set to @code{nntp-open-connection-function} to this list if it does
+not echo commands. Note that a non-@code{nil} value of the
+@code{nntp-never-echoes-commands} variable overrides this variable. The
+default value is @code{(nntp-open-network-stream)}.
+
+@item nntp-prepare-post-hook
+@vindex nntp-prepare-post-hook
+A hook run just before posting an article. If there is no
+@code{Message-ID} header in the article and the news server provides the
+recommended ID, it will be added to the article before running this
+hook. It is useful to make @code{Cancel-Lock} headers even if you
+inhibit Gnus to add a @code{Message-ID} header, you could say:
+
+@lisp
+(add-hook 'nntp-prepare-post-hook 'canlock-insert-header)
+@end lisp
+
+Note that not all servers support the recommended ID. This works for
+INN versions 2.3.0 and later, for instance.
+
+@end table
+
+@menu
+* Direct Functions:: Connecting directly to the server.
+* Indirect Functions:: Connecting indirectly to the server.
+* Common Variables:: Understood by several connection functions.
+@end menu
+
+
+@node Direct Functions
+@subsubsection Direct Functions
+@cindex direct connection functions
+
+These functions are called direct because they open a direct connection
+between your machine and the @acronym{NNTP} server. The behavior of these
+functions is also affected by commonly understood variables
+(@pxref{Common Variables}).
+
+@table @code
+@findex nntp-open-network-stream
+@item nntp-open-network-stream
+This is the default, and simply connects to some port or other on the
+remote system.
+
+@findex nntp-open-tls-stream
+@item nntp-open-tls-stream
+Opens a connection to a server over a @dfn{secure} channel. To use
+this you must have @uref{http://www.gnu.org/software/gnutls/, GNUTLS}
+installed. You then define a server as follows:
+
+@lisp
+;; @r{"nntps" is port 563 and is predefined in our @file{/etc/services}}
+;; @r{however, @samp{gnutls-cli -p} doesn't like named ports.}
+;;
+(nntp "snews.bar.com"
+ (nntp-open-connection-function nntp-open-tls-stream)
+ (nntp-port-number )
+ (nntp-address "snews.bar.com"))
+@end lisp
+
+@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 @uref{http://www.openssl.org, OpenSSL} or
+@uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL, SSLeay} installed. You
+then define a server as follows:
+
+@lisp
+;; @r{"snews" is port 563 and is predefined in our @file{/etc/services}}
+;; @r{however, @samp{openssl s_client -port} doesn't like named ports.}
+;;
+(nntp "snews.bar.com"
+ (nntp-open-connection-function nntp-open-ssl-stream)
+ (nntp-port-number 563)
+ (nntp-address "snews.bar.com"))
+@end lisp
+
+@findex nntp-open-telnet-stream
+@item nntp-open-telnet-stream
+Opens a connection to an @acronym{NNTP} server by simply @samp{telnet}'ing
+it. You might wonder why this function exists, since we have the
+default @code{nntp-open-network-stream} which would do the job. (One
+of) the reason(s) is that if you are behind a firewall but have direct
+connections to the outside world thanks to a command wrapper like
+@code{runsocks}, you can use it like this:
+
+@lisp
+(nntp "socksified"
+ (nntp-pre-command "runsocks")
+ (nntp-open-connection-function nntp-open-telnet-stream)
+ (nntp-address "the.news.server"))
+@end lisp
+
+With the default method, you would need to wrap your whole Emacs
+session, which is not a good idea.
+@end table
+
+
+@node Indirect Functions
+@subsubsection Indirect Functions
+@cindex indirect connection functions
+
+These functions are called indirect because they connect to an
+intermediate host before actually connecting to the @acronym{NNTP} server.
+All of these functions and related variables are also said to belong to
+the ``via'' family of connection: they're all prefixed with ``via'' to make
+things cleaner. The behavior of these functions is also affected by
+commonly understood variables (@pxref{Common Variables}).
+
+@table @code
+@item nntp-open-via-rlogin-and-telnet
+@findex nntp-open-via-rlogin-and-telnet
+Does an @samp{rlogin} on a remote system, and then does a @samp{telnet}
+to the real @acronym{NNTP} server from there. This is useful for instance if
+you need to connect to a firewall machine first.
+
+@code{nntp-open-via-rlogin-and-telnet}-specific variables:
+
+@table @code
+@item nntp-via-rlogin-command
+@vindex nntp-via-rlogin-command
+Command used to log in on the intermediate host. The default is
+@samp{rsh}, but @samp{ssh} is a popular alternative.
+
+@item nntp-via-rlogin-command-switches
+@vindex nntp-via-rlogin-command-switches
+List of strings to be used as the switches to
+@code{nntp-via-rlogin-command}. The default is @code{nil}. If you use
+@samp{ssh} for @code{nntp-via-rlogin-command}, you may set this to
+@samp{("-C")} in order to compress all data connections, otherwise set
+this to @samp{("-t" "-e" "none")} or @samp{("-C" "-t" "-e" "none")} if
+the telnet command requires a pseudo-tty allocation on an intermediate
+host.
+@end table
+
+@item nntp-open-via-telnet-and-telnet
+@findex nntp-open-via-telnet-and-telnet
+Does essentially the same, but uses @samp{telnet} instead of
+@samp{rlogin} to connect to the intermediate host.
+
+@code{nntp-open-via-telnet-and-telnet}-specific variables:
+
+@table @code
+@item nntp-via-telnet-command
+@vindex nntp-via-telnet-command
+Command used to @code{telnet} the intermediate host. The default is
+@samp{telnet}.
+
+@item nntp-via-telnet-switches
+@vindex nntp-via-telnet-switches
+List of strings to be used as the switches to the
+@code{nntp-via-telnet-command} command. The default is @samp{("-8")}.
+
+@item nntp-via-user-password
+@vindex nntp-via-user-password
+Password to use when logging in on the intermediate host.
+
+@item nntp-via-envuser
+@vindex nntp-via-envuser
+If non-@code{nil}, the intermediate @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.
+
+@item nntp-via-shell-prompt
+@vindex nntp-via-shell-prompt
+Regexp matching the shell prompt on the intermediate host. The default
+is @samp{bash\\|\$ *\r?$\\|> *\r?}.
+
+@end table
+
+@end table
+
+
+Here are some additional variables that are understood by all the above
+functions:
+
+@table @code
+
+@item nntp-via-user-name
+@vindex nntp-via-user-name
+User name to use when connecting to the intermediate host.
+
+@item nntp-via-address
+@vindex nntp-via-address
+Address of the intermediate host to connect to.
+
+@end table
+
+
+@node Common Variables
+@subsubsection Common Variables
+
+The following variables affect the behavior of all, or several of the
+pre-made connection functions. When not specified, all functions are
+affected (the values of the following variables will be used as the
+default if each virtual @code{nntp} server doesn't specify those server
+variables individually).
+
+@table @code
+
+@item nntp-pre-command
+@vindex nntp-pre-command
+A command wrapper to use when connecting through a non native
+connection function (all except @code{nntp-open-network-stream},
+@code{nntp-open-tls-stream}, and @code{nntp-open-ssl-stream}). This is
+where you would put a @samp{SOCKS} wrapper for instance.
+
+@item nntp-address
+@vindex nntp-address
+The address of the @acronym{NNTP} server.
+
+@item nntp-port-number
+@vindex nntp-port-number
+Port number to connect to the @acronym{NNTP} server. The default is
+@samp{nntp}. If you use @acronym{NNTP} over
+@acronym{TLS}/@acronym{SSL}, you may want to use integer ports rather
+than named ports (i.e, use @samp{563} instead of @samp{snews} or
+@samp{nntps}), because external @acronym{TLS}/@acronym{SSL} tools may
+not work with named ports.
+
+@item nntp-end-of-line
+@vindex nntp-end-of-line
+String to use as end-of-line marker when talking to the @acronym{NNTP}
+server. This is @samp{\r\n} by default, but should be @samp{\n} when
+using a non native connection function.
+
+@item nntp-telnet-command
+@vindex nntp-telnet-command
+Command to use when connecting to the @acronym{NNTP} server through
+@samp{telnet}. This is @emph{not} for an intermediate host. This is
+just for the real @acronym{NNTP} server. The default is
+@samp{telnet}.
+
+@item nntp-telnet-switches
+@vindex nntp-telnet-switches
+A list of switches to pass to @code{nntp-telnet-command}. The default
+is @samp{("-8")}.
+
+@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.
+
+Anyway, 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 @acronym{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 name of the active file.
+
+@item nnspool-newsgroups-file
+@vindex nnspool-newsgroups-file
+The name of the group descriptions file.
+
+@item nnspool-history-file
+@vindex nnspool-history-file
+The name of the news history file.
+
+@item nnspool-active-times-file
+@vindex nnspool-active-times-file
+The name of 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 @acronym{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 @code{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
+* Mail in a Newsreader:: Important introductory notes.
+* Getting Started Reading Mail:: A simple cookbook example.
+* Splitting Mail:: How to create mail groups.
+* Mail Sources:: How to tell Gnus where to get mail from.
+* Mail Back End Variables:: Variables for customizing mail handling.
+* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
+* Group Mail Splitting:: Use group customize to drive mail splitting.
+* Incorporating Old Mail:: What about the old mail you have?
+* Expiring Mail:: Getting rid of unwanted mail.
+* Washing Mail:: Removing cruft from the mail you get.
+* Duplicates:: Dealing with duplicated mail.
+* Not Reading Mail:: Using mail back ends for reading other files.
+* Choosing a Mail Back End:: Gnus can read a variety of mail formats.
+@end menu
+
+
+@node Mail in a Newsreader
+@subsection Mail in a Newsreader
+
+If you are used to traditional mail readers, but have decided to switch
+to reading mail with Gnus, you may find yourself experiencing something
+of a culture shock.
+
+Gnus does not behave like traditional mail readers. If you want to make
+it behave that way, you can, but it's an uphill battle.
+
+Gnus, by default, handles all its groups using the same approach. This
+approach is very newsreaderly---you enter a group, see the new/unread
+messages, and when you read the messages, they get marked as read, and
+you don't see them any more. (Unless you explicitly ask for them.)
+
+In particular, you do not do anything explicitly to delete messages.
+
+Does this mean that all the messages that have been marked as read are
+deleted? How awful!
+
+But, no, it means that old messages are @dfn{expired} according to some
+scheme or other. For news messages, the expire process is controlled by
+the news administrator; for mail, the expire process is controlled by
+you. The expire process for mail is covered in depth in @ref{Expiring
+Mail}.
+
+What many Gnus users find, after using it a while for both news and
+mail, is that the transport mechanism has very little to do with how
+they want to treat a message.
+
+Many people subscribe to several mailing lists. These are transported
+via @acronym{SMTP}, and are therefore mail. But we might go for weeks without
+answering, or even reading these messages very carefully. We may not
+need to save them because if we should need to read one again, they are
+archived somewhere else.
+
+Some people have local news groups which have only a handful of readers.
+These are transported via @acronym{NNTP}, and are therefore news. But we may need
+to read and answer a large fraction of the messages very carefully in
+order to do our work. And there may not be an archive, so we may need
+to save the interesting messages the same way we would personal mail.
+
+The important distinction turns out to be not the transport mechanism,
+but other factors such as how interested we are in the subject matter,
+or how easy it is to retrieve the message if we need to read it again.
+
+Gnus provides many options for sorting mail into ``groups'' which behave
+like newsgroups, and for treating each group (whether mail or news)
+differently.
+
+Some users never get comfortable using the Gnus (ahem) paradigm and wish
+that Gnus should grow up and be a male, er, mail reader. It is possible
+to whip Gnus into a more mailreaderly being, but, as said before, it's
+not easy. People who prefer proper mail readers should try @sc{vm}
+instead, which is an excellent, and proper, mail reader.
+
+I don't mean to scare anybody off, but I want to make it clear that you
+may be required to learn a new way of thinking about messages. After
+you've been subjected to The Gnus Way, you will come to love it. I can
+guarantee it. (At least the guy who sold me the Emacs Subliminal
+Brain-Washing Functions that I've put into Gnus did guarantee it. You
+Will Be Assimilated. You Love Gnus. You Love The Gnus Mail Way.
+You Do.)
+
+
+@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 back end 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'' back end), you could put the following in your @file{~/.gnus.el} file:
+
+@lisp
+(setq gnus-secondary-select-methods '((nnml "")))
+@end lisp
+
+Now, the next time you start Gnus, this back end will be queried for new
+articles, and it will move all the messages in your spool file to its
+directory, which is @file{~/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 Back End} and @pxref{Expiring Mail}.
+
+
+@node Splitting Mail
+@subsection Splitting Mail
+@cindex splitting mail
+@cindex mail splitting
+@cindex mail filtering (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
+
+@noindent
+In that case, @code{nnmail-split-lowercase-expanded} controls whether
+the inserted text should be made lowercase. @xref{Fancy Mail Splitting}.
+
+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.
+
+@cindex @samp{bogus} 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 no rule matched, the mail
+will end up in the @samp{bogus} group. When new groups are created by
+splitting mail, you may want to run @code{gnus-group-find-new-groups} to
+see the new groups. This also applies to the @samp{bogus} group.
+
+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 back ends 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 back ends 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
+@findex 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. If you wish to see
+where re-spooling messages would put the messages, you can use
+@code{gnus-summary-respool-trace} and related commands (@pxref{Mail
+Group Commands}).
+
+@vindex nnmail-split-header-length-limit
+Header lines longer than the value of
+@code{nnmail-split-header-length-limit} are excluded from the split
+function.
+
+@vindex nnmail-mail-splitting-decodes
+@vindex nnmail-mail-splitting-charset
+By default, splitting does not decode headers, so you can not match on
+non-@acronym{ASCII} strings. But it is useful if you want to match
+articles based on the raw header data. To enable it, set the
+@code{nnmail-mail-splitting-decodes} variable to a non-@code{nil} value.
+In addition, the value of the @code{nnmail-mail-splitting-charset}
+variable is used for decoding non-@acronym{MIME} encoded string when
+@code{nnmail-mail-splitting-decodes} is non-@code{nil}. The default
+value is @code{nil} which means not to decode non-@acronym{MIME} encoded
+string. A suitable value for you will be @code{undecided} or be the
+charset used normally in mails you are interested in.
+
+@vindex nnmail-resplit-incoming
+By default, splitting is performed on all incoming messages. If you
+specify a @code{directory} entry for the variable @code{mail-sources}
+(@pxref{Mail Source Specifiers}), however, then splitting does
+@emph{not} happen by default. You can set the variable
+@code{nnmail-resplit-incoming} to a non-@code{nil} value to make
+splitting happen even in this case. (This variable has no effect on
+other kinds of entries.)
+
+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 Sources
+@subsection Mail Sources
+
+Mail can be gotten from many different sources---the mail spool, from
+a @acronym{POP} mail server, from a procmail directory, or from a
+maildir, for instance.
+
+@menu
+* Mail Source Specifiers:: How to specify what a mail source is.
+* Mail Source Customization:: Some variables that influence things.
+* Fetching Mail:: Using the mail source specifiers.
+@end menu
+
+
+@node Mail Source Specifiers
+@subsubsection Mail Source Specifiers
+@cindex POP
+@cindex mail server
+@cindex procmail
+@cindex mail spool
+@cindex mail source
+
+You tell Gnus how to fetch mail by setting @code{mail-sources}
+(@pxref{Fetching Mail}) to a @dfn{mail source specifier}.
+
+Here's an example:
+
+@lisp
+(pop :server "pop3.mailserver.com" :user "myname")
+@end lisp
+
+As can be observed, a mail source specifier is a list where the first
+element is a @dfn{mail source type}, followed by an arbitrary number of
+@dfn{keywords}. Keywords that are not explicitly specified are given
+default values.
+
+The following mail source types are available:
+
+@table @code
+@item file
+Get mail from a single file; typically from the mail spool.
+
+Keywords:
+
+@table @code
+@item :path
+The file name. Defaults to the value of the @env{MAIL}
+environment variable or the value of @code{rmail-spool-directory}
+(usually something like @file{/usr/mail/spool/user-name}).
+
+@item :prescript
+@itemx :postscript
+Script run before/after fetching mail.
+@end table
+
+An example file mail source:
+
+@lisp
+(file :path "/usr/spool/mail/user-name")
+@end lisp
+
+Or using the default file name:
+
+@lisp
+(file)
+@end lisp
+
+If the mail spool file is not located on the local machine, it's best
+to use @acronym{POP} or @acronym{IMAP} or the like to fetch the mail.
+You can not use ange-ftp file names here---it has no way to lock the
+mail spool while moving the mail.
+
+If it's impossible to set up a proper server, you can use ssh instead.
+
+@lisp
+(setq mail-sources
+ '((file :prescript "ssh host bin/getmail >%t")))
+@end lisp
+
+The @samp{getmail} script would look something like the following:
+
+@example
+#!/bin/sh
+# getmail - move mail from spool to stdout
+# flu@@iki.fi
+
+MOVEMAIL=/usr/lib/emacs/20.3/i386-redhat-linux/movemail
+TMP=$HOME/Mail/tmp
+rm -f $TMP; $MOVEMAIL $MAIL $TMP >/dev/null && cat $TMP
+@end example
+
+Alter this script to fit the @samp{movemail} and temporary
+file you want to use.
+
+
+@item directory
+@vindex nnmail-scan-directory-mail-source-once
+Get mail from several files in a directory. This is typically used
+when you have procmail split the incoming mail into several files.
+That is, there is a one-to-one correspondence between files in that
+directory and groups, so that mail from the file @file{foo.bar.spool}
+will be put in the group @code{foo.bar}. (You can change the suffix
+to be used instead of @code{.spool}.) Setting
+@code{nnmail-scan-directory-mail-source-once} to non-@code{nil} forces
+Gnus to scan the mail source only once. This is particularly useful
+if you want to scan mail groups at a specified level.
+
+@vindex nnmail-resplit-incoming
+There is also the variable @code{nnmail-resplit-incoming}, if you set
+that to a non-@code{nil} value, then the normal splitting process is
+applied to all the files from the directory, @ref{Splitting Mail}.
+
+Keywords:
+
+@table @code
+@item :path
+The name of the directory where the files are. There is no default
+value.
+
+@item :suffix
+Only files ending with this suffix are used. The default is
+@samp{.spool}.
+
+@item :predicate
+Only files that have this predicate return non-@code{nil} are returned.
+The default is @code{identity}. This is used as an additional
+filter---only files that have the right suffix @emph{and} satisfy this
+predicate are considered.
+
+@item :prescript
+@itemx :postscript
+Script run before/after fetching mail.
+
+@end table
+
+An example directory mail source:
+
+@lisp
+(directory :path "/home/user-name/procmail-dir/"
+ :suffix ".prcml")
+@end lisp
+
+@item pop
+Get mail from a @acronym{POP} server.
+
+Keywords:
+
+@table @code
+@item :server
+The name of the @acronym{POP} server. The default is taken from the
+@env{MAILHOST} environment variable.
+
+@item :port
+The port number of the @acronym{POP} server. This can be a number (eg,
+@samp{:port 1234}) or a string (eg, @samp{:port "pop3"}). If it is a
+string, it should be a service name as listed in @file{/etc/services} on
+Unix systems. The default is @samp{"pop3"}. On some systems you might
+need to specify it as @samp{"pop-3"} instead.
+
+@item :user
+The user name to give to the @acronym{POP} server. The default is the login
+name.
+
+@item :password
+The password to give to the @acronym{POP} server. If not specified,
+the user is prompted.
+
+@item :program
+The program to use to fetch mail from the @acronym{POP} server. This
+should be a @code{format}-like string. Here's an example:
+
+@example
+fetchmail %u@@%s -P %p %t
+@end example
+
+The valid format specifier characters are:
+
+@table @samp
+@item t
+The name of the file the mail is to be moved to. This must always be
+included in this string.
+
+@item s
+The name of the server.
+
+@item P
+The port number of the server.
+
+@item u
+The user name to use.
+
+@item p
+The password to use.
+@end table
+
+The values used for these specs are taken from the values you give the
+corresponding keywords.
+
+@item :prescript
+A script to be run before fetching the mail. The syntax is the same as
+the @code{:program} keyword. This can also be a function to be run.
+
+@item :postscript
+A script to be run after fetching the mail. The syntax is the same as
+the @code{:program} keyword. This can also be a function to be run.
+
+@item :function
+The function to use to fetch mail from the @acronym{POP} server. The
+function is called with one parameter---the name of the file where the
+mail should be moved to.
+
+@item :authentication
+This can be either the symbol @code{password} or the symbol @code{apop}
+and says what authentication scheme to use. The default is
+@code{password}.
+
+@end table
+
+@vindex pop3-movemail
+@vindex pop3-leave-mail-on-server
+If the @code{:program} and @code{:function} keywords aren't specified,
+@code{pop3-movemail} will be used. If @code{pop3-leave-mail-on-server}
+is non-@code{nil} the mail is to be left on the @acronym{POP} server
+after fetching when using @code{pop3-movemail}. Note that POP servers
+maintain no state information between sessions, so what the client
+believes is there and what is actually there may not match up. If they
+do not, then you may get duplicate mails or the whole thing can fall
+apart and leave you with a corrupt mailbox.
+
+Here are some examples for getting mail from a @acronym{POP} server.
+Fetch from the default @acronym{POP} server, using the default user
+name, and default fetcher:
+
+@lisp
+(pop)
+@end lisp
+
+Fetch from a named server with a named user and password:
+
+@lisp
+(pop :server "my.pop.server"
+ :user "user-name" :password "secret")
+@end lisp
+
+Use @samp{movemail} to move the mail:
+
+@lisp
+(pop :program "movemail po:%u %t %p")
+@end lisp
+
+@item maildir
+Get mail from a maildir. This is a type of mailbox that is supported by
+at least qmail and postfix, where each file in a special directory
+contains exactly one mail.
+
+Keywords:
+
+@table @code
+@item :path
+The name of the directory where the mails are stored. The default is
+taken from the @env{MAILDIR} environment variable or
+@file{~/Maildir/}.
+@item :subdirs
+The subdirectories of the Maildir. The default is
+@samp{("new" "cur")}.
+
+@c If you sometimes look at your mail through a pop3 daemon before fetching
+@c them with Gnus, you may also have to fetch your mails from the
+@c @code{cur} directory inside the maildir, like in the first example
+@c below.
+
+You can also get mails from remote hosts (because maildirs don't suffer
+from locking problems).
+
+@end table
+
+Two example maildir mail sources:
+
+@lisp
+(maildir :path "/home/user-name/Maildir/"
+ :subdirs ("cur" "new"))
+@end lisp
+
+@lisp
+(maildir :path "/user@@remotehost.org:~/Maildir/"
+ :subdirs ("new"))
+@end lisp
+
+@item imap
+Get mail from a @acronym{IMAP} server. If you don't want to use
+@acronym{IMAP} as intended, as a network mail reading protocol (ie
+with nnimap), for some reason or other, Gnus let you treat it similar
+to a @acronym{POP} server and fetches articles from a given
+@acronym{IMAP} mailbox. @xref{IMAP}, for more information.
+
+Note that for the Kerberos, GSSAPI, @acronym{TLS}/@acronym{SSL} and STARTTLS support you
+may need external programs and libraries, @xref{IMAP}.
+
+Keywords:
+
+@table @code
+@item :server
+The name of the @acronym{IMAP} server. The default is taken from the
+@env{MAILHOST} environment variable.
+
+@item :port
+The port number of the @acronym{IMAP} server. The default is @samp{143}, or
+@samp{993} for @acronym{TLS}/@acronym{SSL} connections.
+
+@item :user
+The user name to give to the @acronym{IMAP} server. The default is the login
+name.
+
+@item :password
+The password to give to the @acronym{IMAP} server. If not specified, the user is
+prompted.
+
+@item :stream
+What stream to use for connecting to the server, this is one of the
+symbols in @code{imap-stream-alist}. Right now, this means
+@samp{gssapi}, @samp{kerberos4}, @samp{starttls}, @samp{tls},
+@samp{ssl}, @samp{shell} or the default @samp{network}.
+
+@item :authentication
+Which authenticator to use for authenticating to the server, this is
+one of the symbols in @code{imap-authenticator-alist}. Right now,
+this means @samp{gssapi}, @samp{kerberos4}, @samp{digest-md5},
+@samp{cram-md5}, @samp{anonymous} or the default @samp{login}.
+
+@item :program
+When using the `shell' :stream, the contents of this variable is
+mapped into the @code{imap-shell-program} variable. This should be a
+@code{format}-like string (or list of strings). Here's an example:
+
+@example
+ssh %s imapd
+@end example
+
+The valid format specifier characters are:
+
+@table @samp
+@item s
+The name of the server.
+
+@item l
+User name from @code{imap-default-user}.
+
+@item p
+The port number of the server.
+@end table
+
+The values used for these specs are taken from the values you give the
+corresponding keywords.
+
+@item :mailbox
+The name of the mailbox to get mail from. The default is @samp{INBOX}
+which normally is the mailbox which receive incoming mail.
+
+@item :predicate
+The predicate used to find articles to fetch. The default, @samp{UNSEEN
+UNDELETED}, is probably the best choice for most people, but if you
+sometimes peek in your mailbox with a @acronym{IMAP} client and mark some
+articles as read (or; SEEN) you might want to set this to @samp{1:*}.
+Then all articles in the mailbox is fetched, no matter what. For a
+complete list of predicates, see RFC 2060 section 6.4.4.
+
+@item :fetchflag
+How to flag fetched articles on the server, the default @samp{\Deleted}
+will mark them as deleted, an alternative would be @samp{\Seen} which
+would simply mark them as read. These are the two most likely choices,
+but more flags are defined in RFC 2060 section 2.3.2.
+
+@item :dontexpunge
+If non-@code{nil}, don't remove all articles marked as deleted in the
+mailbox after finishing the fetch.
+
+@end table
+
+An example @acronym{IMAP} mail source:
+
+@lisp
+(imap :server "mail.mycorp.com"
+ :stream kerberos4
+ :fetchflag "\\Seen")
+@end lisp
+
+@item webmail
+Get mail from a webmail server, such as @uref{http://www.hotmail.com/},
+@uref{http://webmail.netscape.com/}, @uref{http://www.netaddress.com/},
+@uref{http://mail.yahoo.com/}.
+
+NOTE: Webmail largely depends on cookies. A "one-line-cookie" patch is
+required for url "4.0pre.46".
+
+WARNING: Mails may be lost. NO WARRANTY.
+
+Keywords:
+
+@table @code
+@item :subtype
+The type of the webmail server. The default is @code{hotmail}. The
+alternatives are @code{netscape}, @code{netaddress}, @code{my-deja}.
+
+@item :user
+The user name to give to the webmail server. The default is the login
+name.
+
+@item :password
+The password to give to the webmail server. If not specified, the user is
+prompted.
+
+@item :dontexpunge
+If non-@code{nil}, only fetch unread articles and don't move them to
+trash folder after finishing the fetch.
+
+@end table
+
+An example webmail source:
+
+@lisp
+(webmail :subtype 'hotmail
+ :user "user-name"
+ :password "secret")
+@end lisp
+@end table
+
+@table @dfn
+@item Common Keywords
+Common keywords can be used in any type of mail source.
+
+Keywords:
+
+@table @code
+@item :plugged
+If non-@code{nil}, fetch the mail even when Gnus is unplugged. If you
+use directory source to get mail, you can specify it as in this
+example:
+
+@lisp
+(setq mail-sources
+ '((directory :path "/home/pavel/.Spool/"
+ :suffix ""
+ :plugged t)))
+@end lisp
+
+Gnus will then fetch your mail even when you are unplugged. This is
+useful when you use local mail and news.
+
+@end table
+@end table
+
+@subsubsection Function Interface
+
+Some of the above keywords specify a Lisp function to be executed.
+For each keyword @code{:foo}, the Lisp variable @code{foo} is bound to
+the value of the keyword while the function is executing. For example,
+consider the following mail-source setting:
+
+@lisp
+(setq mail-sources '((pop :user "jrl"
+ :server "pophost" :function fetchfunc)))
+@end lisp
+
+While the function @code{fetchfunc} is executing, the symbol @code{user}
+is bound to @code{"jrl"}, and the symbol @code{server} is bound to
+@code{"pophost"}. The symbols @code{port}, @code{password},
+@code{program}, @code{prescript}, @code{postscript}, @code{function},
+and @code{authentication} are also bound (to their default values).
+
+See above for a list of keywords for each type of mail source.
+
+
+@node Mail Source Customization
+@subsubsection Mail Source Customization
+
+The following is a list of variables that influence how the mail is
+fetched. You would normally not need to set or change any of these
+variables.
+
+@table @code
+@item mail-source-crash-box
+@vindex mail-source-crash-box
+File where mail will be stored while processing it. The default is@*
+@file{~/.emacs-mail-crash-box}.
+
+@item mail-source-delete-incoming
+@vindex mail-source-delete-incoming
+If non-@code{nil}, delete incoming files after handling them. If
+@code{t}, delete the files immediately, if @code{nil}, never delete any
+files. If a positive number, delete files older than number of days
+(This will only happen, when receiving new mail). You may also set
+@code{mail-source-delete-incoming} to @code{nil} and call
+@code{mail-source-delete-old-incoming} from a hook or interactively.
+
+@item mail-source-delete-old-incoming-confirm
+@vindex mail-source-delete-old-incoming-confirm
+If non-@code{nil}, ask for confirmation before deleting old incoming
+files. This variable only applies when
+@code{mail-source-delete-incoming} is a positive number.
+
+@item mail-source-ignore-errors
+@vindex mail-source-ignore-errors
+If non-@code{nil}, ignore errors when reading mail from a mail source.
+
+@item mail-source-directory
+@vindex mail-source-directory
+Directory where incoming mail source files (if any) will be stored. The
+default is @file{~/Mail/}. At present, the only thing this is used for
+is to say where the incoming files will be stored if the variable
+@code{mail-source-delete-incoming} is @code{nil} or a number.
+
+@item mail-source-incoming-file-prefix
+@vindex mail-source-incoming-file-prefix
+Prefix for file name for storing incoming mail. The default is
+@file{Incoming}, in which case files will end up with names like
+@file{Incoming30630D_} or @file{Incoming298602ZD}. This is really only
+relevant if @code{mail-source-delete-incoming} is @code{nil} or a
+number.
+
+@item mail-source-default-file-modes
+@vindex mail-source-default-file-modes
+All new mail files will get this file mode. The default is 384.
+
+@item mail-source-movemail-program
+@vindex mail-source-movemail-program
+If non-@code{nil}, name of program for fetching new mail. If
+@code{nil}, @code{movemail} in @var{exec-directory}.
+
+@end table
+
+
+@node Fetching Mail
+@subsubsection Fetching Mail
+
+@vindex mail-sources
+@vindex nnmail-spool-file
+The way to actually tell Gnus where to get new mail from is to set
+@code{mail-sources} to a list of mail source specifiers
+(@pxref{Mail Source Specifiers}).
+
+If this variable (and the obsolescent @code{nnmail-spool-file}) is
+@code{nil}, the mail back ends will never attempt to fetch mail by
+themselves.
+
+If you want to fetch mail both from your local spool as well as a
+@acronym{POP} mail server, you'd say something like:
+
+@lisp
+(setq mail-sources
+ '((file)
+ (pop :server "pop3.mail.server"
+ :password "secret")))
+@end lisp
+
+Or, if you don't want to use any of the keyword defaults:
+
+@lisp
+(setq mail-sources
+ '((file :path "/var/spool/mail/user-name")
+ (pop :server "pop3.mail.server"
+ :user "user-name"
+ :port "pop3"
+ :password "secret")))
+@end lisp
+
+
+When you use a mail back end, 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 back end---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.
+
+
+
+@node Mail Back End Variables
+@subsection Mail Back End Variables
+
+These variables are (for the most part) pertinent to all the various
+mail back ends.
+
+@table @code
+@vindex nnmail-read-incoming-hook
+@item nnmail-read-incoming-hook
+The mail back ends 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-split-hook
+@item nnmail-split-hook
+@findex gnus-article-decode-encoded-words
+@cindex RFC 1522 decoding
+@cindex RFC 2047 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-encoded-words} 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 'nnmail-pre-get-new-mail-hook
+ (lambda () (set-default-file-modes 511)))
+
+(add-hook 'nnmail-post-get-new-mail-hook
+ (lambda () (set-default-file-modes 551)))
+@end lisp
+
+@item nnmail-use-long-file-names
+@vindex nnmail-use-long-file-names
+If non-@code{nil}, the mail back ends will use long file and directory
+names. Groups like @samp{mail.misc} will end up in directories
+(assuming use of @code{nnml} back end) or files (assuming use of
+@code{nnfolder} back end) 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 back end (via @code{Gcc}, for instance) into the mail duplication
+discovery cache. The default is @code{nil}.
+
+@item nnmail-cache-ignore-groups
+@vindex nnmail-cache-ignore-groups
+This can be a regular expression or a list of regular expressions.
+Group names that match any of the regular expressions will never be
+recorded in the @code{Message-ID} cache.
+
+This can be useful, for example, when using Fancy Splitting
+(@pxref{Fancy Mail Splitting}) together with the function
+@code{nnmail-split-fancy-with-parent}.
+
+@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
+;; @r{Messages from the mailer daemon are not crossposted to any of}
+;; @r{the ordinary groups. Warnings are put in a separate group}
+;; @r{from real errors.}
+(| ("from" mail (| ("subject" "warn.*" "mail.warning")
+ "mail.misc"))
+ ;; @r{Non-error messages are crossposted to all relevant}
+ ;; @r{groups, but we don't crosspost between the group for the}
+ ;; @r{(ding) list and the group for other (ding) related mail.}
+ (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
+ ("subject" "ding" "ding.misc"))
+ ;; @r{Other mailing lists@dots{}}
+ (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
+ (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
+ ;; @r{Both lists below have the same suffix, so prevent}
+ ;; @r{cross-posting to mkpkg.list of messages posted only to}
+ ;; @r{the bugs- list, but allow cross-posting when the}
+ ;; @r{message was really cross-posted.}
+ (any "bugs-mypackage@@somewhere" "mypkg.bugs")
+ (any "mypackage@@somewhere" - "bugs-mypackage" "mypkg.list")
+ ;; @r{People@dots{}}
+ (any "larsi@@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen"))
+ ;; @r{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 possible split syntaxes:
+
+@table @code
+
+@item 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.
+
+@c Don't fold this line.
+@item (@var{field} @var{value} [- @var{restrict} [@dots{}] ] @var{split} [@var{invert-partial}])
+The split can be a list containing at least three elements. If the
+first element @var{field} (a regexp matching a header) contains
+@var{value} (also a regexp) then store the message as specified by
+@var{split}.
+
+If @var{restrict} (yet another regexp) matches some string after
+@var{field} and before the end of the matched @var{value}, the
+@var{split} is ignored. If none of the @var{restrict} clauses match,
+@var{split} is processed.
+
+The last element @var{invert-partial} is optional. If it is
+non-@code{nil}, the match-partial-words behavior controlled by the
+variable @code{nnmail-split-fancy-match-partial-words} (see below) is
+be inverted. (New in Gnus 5.10.7)
+
+@item (| @var{split} @dots{})
+If the split is a list, and the first element is @code{|} (vertical
+bar), then process each @var{split} until one of them matches. A
+@var{split} is said to match if it will cause the mail message to be
+stored in one or more groups.
+
+@item (& @var{split} @dots{})
+If the split is a list, and the first element is @code{&}, then
+process all @var{split}s in the list.
+
+@item junk
+If the split is the symbol @code{junk}, then don't save (i.e., delete)
+this message. Use with extreme caution.
+
+@item (: @var{function} @var{arg1} @var{arg2} @dots{})
+If the split is a list, and the first element is @samp{:}, then the
+second element will be called as a function with @var{args} given as
+arguments. The function should return a @var{split}.
+
+@cindex body split
+For instance, the following function could be used to split based on the
+body of the messages:
+
+@lisp
+(defun split-on-body ()
+ (save-excursion
+ (save-restriction
+ (widen)
+ (goto-char (point-min))
+ (when (re-search-forward "Some.*string" nil t)
+ "string.group"))))
+@end lisp
+
+The buffer is narrowed to the message in question when @var{function}
+is run. That's why @code{(widen)} needs to be called after
+@code{save-excursion} and @code{save-restriction} in the example
+above. Also note that with the nnimap backend, message bodies will
+not be downloaded by default. You need to set
+@code{nnimap-split-download-body} to @code{t} to do that
+(@pxref{Splitting in IMAP}).
+
+@item (! @var{func} @var{split})
+If the split is a list, and the first element is @code{!}, then
+@var{split} will be processed, and @var{func} will be called as a
+function with the result of @var{split} as argument. @var{func}
+should return a split.
+
+@item nil
+If the split is @code{nil}, it is ignored.
+
+@end table
+
+In these splits, @var{field} must match a complete field name.
+
+Normally, @var{value} in these splits must match a complete @emph{word}
+according to the fundamental mode syntax table. In other words, all
+@var{value}'s will be implicitly surrounded by @code{\<...\>} markers,
+which are word delimiters. Therefore, if you use the following split,
+for example,
+
+@example
+(any "joe" "joemail")
+@end example
+
+@noindent
+messages sent from @samp{joedavis@@foo.org} will normally not be filed
+in @samp{joemail}. If you want to alter this behavior, you can use any
+of the following three ways:
+
+@enumerate
+@item
+@vindex nnmail-split-fancy-match-partial-words
+You can set the @code{nnmail-split-fancy-match-partial-words} variable
+to non-@code{nil} in order to ignore word boundaries and instead the
+match becomes more like a grep. This variable controls whether partial
+words are matched during fancy splitting. The default value is
+@code{nil}.
+
+Note that it influences all @var{value}'s in your split rules.
+
+@item
+@var{value} beginning with @code{.*} ignores word boundaries in front of
+a word. Similarly, if @var{value} ends with @code{.*}, word boundaries
+in the rear of a word will be ignored. For example, the @var{value}
+@code{"@@example\\.com"} does not match @samp{foo@@example.com} but
+@code{".*@@example\\.com"} does.
+
+@item
+You can set the @var{invert-partial} flag in your split rules of the
+@samp{(@var{field} @var{value} @dots{})} types, aforementioned in this
+section. If the flag is set, word boundaries on both sides of a word
+are ignored even if @code{nnmail-split-fancy-match-partial-words} is
+@code{nil}. Contrarily, if the flag is set, word boundaries are not
+ignored even if @code{nnmail-split-fancy-match-partial-words} is
+non-@code{nil}. (New in Gnus 5.10.7)
+@end enumerate
+
+@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 @sc{car} of a cell contains the key, and the @sc{cdr}
+contains the associated value. Predefined entries in
+@code{nnmail-split-abbrev-alist} include:
+
+@table @code
+@item from
+Matches the @samp{From}, @samp{Sender} and @samp{Resent-From} fields.
+@item to
+Matches the @samp{To}, @samp{Cc}, @samp{Apparently-To},
+@samp{Resent-To} and @samp{Resent-Cc} fields.
+@item any
+Is the union of the @code{from} and @code{to} entries.
+@end table
+
+@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
+
+In this example, messages sent to @samp{debian-foo@@lists.debian.org}
+will be filed in @samp{mail.debian.foo}.
+
+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.
+
+@vindex nnmail-split-lowercase-expanded
+Where @code{nnmail-split-lowercase-expanded} controls whether the
+lowercase of the matched string should be used for the substitution.
+Setting it as non-@code{nil} is useful to avoid the creation of multiple
+groups when users send to an address using different case
+(i.e. mailing-list@@domain vs Mailing-List@@Domain). The default value
+is @code{t}.
+
+@findex nnmail-split-fancy-with-parent
+@code{nnmail-split-fancy-with-parent} is a function which allows you to
+split followups into the same groups their parents are in. Sometimes
+you can't make splitting rules for all your mail. For example, your
+boss might send you personal mail regarding different projects you are
+working on, and as you can't tell your boss to put a distinguishing
+string into the subject line, you have to resort to manually moving the
+messages into the right group. With this function, you only have to do
+it once per thread.
+
+To use this feature, you have to set @code{nnmail-treat-duplicates}
+and @code{nnmail-cache-accepted-message-ids} to a non-@code{nil}
+value. And then you can include @code{nnmail-split-fancy-with-parent}
+using the colon feature, like so:
+@lisp
+(setq nnmail-treat-duplicates 'warn ; @r{or @code{delete}}
+ nnmail-cache-accepted-message-ids t
+ nnmail-split-fancy
+ '(| (: nnmail-split-fancy-with-parent)
+ ;; @r{other splits go here}
+ ))
+@end lisp
+
+This feature works as follows: when @code{nnmail-treat-duplicates} is
+non-@code{nil}, Gnus records the message id of every message it sees
+in the file specified by the variable
+@code{nnmail-message-id-cache-file}, together with the group it is in
+(the group is omitted for non-mail messages). When mail splitting is
+invoked, the function @code{nnmail-split-fancy-with-parent} then looks
+at the References (and In-Reply-To) header of each message to split
+and searches the file specified by @code{nnmail-message-id-cache-file}
+for the message ids. When it has found a parent, it returns the
+corresponding group name unless the group name matches the regexp
+@code{nnmail-split-fancy-with-parent-ignore-groups}. It is
+recommended that you set @code{nnmail-message-id-cache-length} to a
+somewhat higher number than the default so that the message ids are
+still in the cache. (A value of 5000 appears to create a file some
+300 kBytes in size.)
+@vindex nnmail-cache-accepted-message-ids
+When @code{nnmail-cache-accepted-message-ids} is non-@code{nil}, Gnus
+also records the message ids of moved articles, so that the followup
+messages goes into the new group.
+
+Also see the variable @code{nnmail-cache-ignore-groups} if you don't
+want certain groups to be recorded in the cache. For example, if all
+outgoing messages are written to an ``outgoing'' group, you could set
+@code{nnmail-cache-ignore-groups} to match that group name.
+Otherwise, answers to all your messages would end up in the
+``outgoing'' group.
+
+
+@node Group Mail Splitting
+@subsection Group Mail Splitting
+@cindex mail splitting
+@cindex group mail splitting
+
+@findex gnus-group-split
+If you subscribe to dozens of mailing lists but you don't want to
+maintain mail splitting rules manually, group mail splitting is for you.
+You just have to set @code{to-list} and/or @code{to-address} in group
+parameters or group customization and set @code{nnmail-split-methods} to
+@code{gnus-group-split}. This splitting function will scan all groups
+for those parameters and split mail accordingly, i.e., messages posted
+from or to the addresses specified in the parameters @code{to-list} or
+@code{to-address} of a mail group will be stored in that group.
+
+Sometimes, mailing lists have multiple addresses, and you may want mail
+splitting to recognize them all: just set the @code{extra-aliases} group
+parameter to the list of additional addresses and it's done. If you'd
+rather use a regular expression, set @code{split-regexp}.
+
+All these parameters in a group will be used to create an
+@code{nnmail-split-fancy} split, in which the @var{field} is @samp{any},
+the @var{value} is a single regular expression that matches
+@code{to-list}, @code{to-address}, all of @code{extra-aliases} and all
+matches of @code{split-regexp}, and the @var{split} is the name of the
+group. @var{restrict}s are also supported: just set the
+@code{split-exclude} parameter to a list of regular expressions.
+
+If you can't get the right split to be generated using all these
+parameters, or you just need something fancier, you can set the
+parameter @code{split-spec} to an @code{nnmail-split-fancy} split. In
+this case, all other aforementioned parameters will be ignored by
+@code{gnus-group-split}. In particular, @code{split-spec} may be set to
+@code{nil}, in which case the group will be ignored by
+@code{gnus-group-split}.
+
+@vindex gnus-group-split-default-catch-all-group
+@code{gnus-group-split} will do cross-posting on all groups that match,
+by defining a single @code{&} fancy split containing one split for each
+group. If a message doesn't match any split, it will be stored in the
+group named in @code{gnus-group-split-default-catch-all-group}, unless
+some group has @code{split-spec} set to @code{catch-all}, in which case
+that group is used as the catch-all group. Even though this variable is
+often used just to name a group, it may also be set to an arbitrarily
+complex fancy split (after all, a group name is a fancy split), and this
+may be useful to split mail that doesn't go to any mailing list to
+personal mail folders. Note that this fancy split is added as the last
+element of a @code{|} split list that also contains a @code{&} split
+with the rules extracted from group parameters.
+
+It's time for an example. Assume the following group parameters have
+been defined:
+
+@example
+nnml:mail.bar:
+((to-address . "bar@@femail.com")
+ (split-regexp . ".*@@femail\\.com"))
+nnml:mail.foo:
+((to-list . "foo@@nowhere.gov")
+ (extra-aliases "foo@@localhost" "foo-redist@@home")
+ (split-exclude "bugs-foo" "rambling-foo")
+ (admin-address . "foo-request@@nowhere.gov"))
+nnml:mail.others:
+((split-spec . catch-all))
+@end example
+
+Setting @code{nnmail-split-methods} to @code{gnus-group-split} will
+behave as if @code{nnmail-split-fancy} had been selected and variable
+@code{nnmail-split-fancy} had been set as follows:
+
+@lisp
+(| (& (any "\\(bar@@femail\\.com\\|.*@@femail\\.com\\)" "mail.bar")
+ (any "\\(foo@@nowhere\\.gov\\|foo@@localhost\\|foo-redist@@home\\)"
+ - "bugs-foo" - "rambling-foo" "mail.foo"))
+ "mail.others")
+@end lisp
+
+@findex gnus-group-split-fancy
+If you'd rather not use group splitting for all your mail groups, you
+may use it for only some of them, by using @code{nnmail-split-fancy}
+splits like this:
+
+@lisp
+(: gnus-group-split-fancy @var{groups} @var{no-crosspost} @var{catch-all})
+@end lisp
+
+@var{groups} may be a regular expression or a list of group names whose
+parameters will be scanned to generate the output split.
+@var{no-crosspost} can be used to disable cross-posting; in this case, a
+single @code{|} split will be output. @var{catch-all} is the fall back
+fancy split, used like @code{gnus-group-split-default-catch-all-group}.
+If @var{catch-all} is @code{nil}, or if @code{split-regexp} matches the
+empty string in any selected group, no catch-all split will be issued.
+Otherwise, if some group has @code{split-spec} set to @code{catch-all},
+this group will override the value of the @var{catch-all} argument.
+
+@findex gnus-group-split-setup
+Unfortunately, scanning all groups and their parameters can be quite
+slow, especially considering that it has to be done for every message.
+But don't despair! The function @code{gnus-group-split-setup} can be
+used to enable @code{gnus-group-split} in a much more efficient way. It
+sets @code{nnmail-split-methods} to @code{nnmail-split-fancy} and sets
+@code{nnmail-split-fancy} to the split produced by
+@code{gnus-group-split-fancy}. Thus, the group parameters are only
+scanned once, no matter how many messages are split.
+
+@findex gnus-group-split-update
+However, if you change group parameters, you'd have to update
+@code{nnmail-split-fancy} manually. You can do it by running
+@code{gnus-group-split-update}. If you'd rather have it updated
+automatically, just tell @code{gnus-group-split-setup} to do it for
+you. For example, add to your @file{~/.gnus.el}:
+
+@lisp
+(gnus-group-split-setup @var{auto-update} @var{catch-all})
+@end lisp
+
+If @var{auto-update} is non-@code{nil}, @code{gnus-group-split-update}
+will be added to @code{nnmail-pre-get-new-mail-hook}, so you won't ever
+have to worry about updating @code{nnmail-split-fancy} again. If you
+don't omit @var{catch-all} (it's optional, equivalent to @code{nil}),
+@code{gnus-group-split-default-catch-all-group} will be set to its
+value.
+
+@vindex gnus-group-split-updated-hook
+Because you may want to change @code{nnmail-split-fancy} after it is set
+by @code{gnus-group-split-update}, this function will run
+@code{gnus-group-split-updated-hook} just before finishing.
+
+@node Incorporating Old Mail
+@subsection Incorporating Old Mail
+@cindex incorporating old mail
+@cindex import 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
+back ends, 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 @kbd{G f} and give the file name to the mbox file when prompted to create an
+@code{nndoc} group from the mbox file (@pxref{Foreign Groups}).
+
+@item
+Type @kbd{SPACE} to enter the newly created group.
+
+@item
+Type @kbd{M P b} to process-mark all articles in this group's buffer
+(@pxref{Setting Process Marks}).
+
+@item
+Type @kbd{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
+back end to another. Just respool all the mail in the old mail groups
+using the new mail back end.
+
+
+@node Expiring Mail
+@subsection Expiring Mail
+@cindex article expiry
+@cindex expiring mail
+
+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}. (With the default key bindings, this means
+that you have to type @kbd{E}.) 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.
+
+You do not have to mark articles as expirable by hand. Gnus provides
+two features, called ``auto-expire'' and ``total-expire'', that can help you
+with this. In a nutshell, ``auto-expire'' means that Gnus hits @kbd{E}
+for you when you select an article. And ``total-expire'' means that Gnus
+considers all articles as expirable that are read. So, in addition to
+the articles marked @samp{E}, also the articles marked @samp{r},
+@samp{R}, @samp{O}, @samp{K}, @samp{Y} and so on are considered
+expirable.
+
+When should either auto-expire or total-expire be used? Most people
+who are subscribed to mailing lists split each list into its own group
+and then turn on auto-expire or total-expire for those groups.
+(@xref{Splitting Mail}, for more information on splitting each list
+into its own group.)
+
+Which one is better, auto-expire or total-expire? It's not easy to
+answer. Generally speaking, auto-expire is probably faster. Another
+advantage of auto-expire is that you get more marks to work with: for
+the articles that are supposed to stick around, you can still choose
+between tick and dormant and read marks. But with total-expire, you
+only have dormant and ticked to choose from. The advantage of
+total-expire is that it works well with adaptive scoring (@pxref{Adaptive
+Scoring}). Auto-expire works with normal scoring but not with adaptive
+scoring.
+
+@vindex gnus-auto-expirable-newsgroups
+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.el} 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
+articles 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-expiry-target
+The normal action taken when expiring articles is to delete them.
+However, in some circumstances it might make more sense to move them
+to other groups instead of deleting them. The variable
+@code{nnmail-expiry-target} (and the @code{expiry-target} group
+parameter) controls this. The variable supplies a default value for
+all groups, which can be overridden for specific groups by the group
+parameter. default value is @code{delete}, but this can also be a
+string (which should be the name of the group the message should be
+moved to), or a function (which will be called in a buffer narrowed to
+the message in question, and with the name of the group being moved
+from as its parameter) which should return a target---either a group
+name or @code{delete}.
+
+Here's an example for specifying a group name:
+@lisp
+(setq nnmail-expiry-target "nnml:expired")
+@end lisp
+
+@findex nnmail-fancy-expiry-target
+@vindex nnmail-fancy-expiry-targets
+Gnus provides a function @code{nnmail-fancy-expiry-target} which will
+expire mail to groups according to the variable
+@code{nnmail-fancy-expiry-targets}. Here's an example:
+
+@lisp
+ (setq nnmail-expiry-target 'nnmail-fancy-expiry-target
+ nnmail-fancy-expiry-targets
+ '((to-from "boss" "nnfolder:Work")
+ ("subject" "IMPORTANT" "nnfolder:IMPORTANT.%Y.%b")
+ ("from" ".*" "nnfolder:Archive-%Y")))
+@end lisp
+
+With this setup, any mail that has @code{IMPORTANT} in its Subject
+header and was sent in the year @code{YYYY} and month @code{MMM}, will
+get expired to the group @code{nnfolder:IMPORTANT.YYYY.MMM}. If its
+From or To header contains the string @code{boss}, it will get expired
+to @code{nnfolder:Work}. All other mail will get expired to
+@code{nnfolder:Archive-YYYY}.
+
+@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.
+
+@vindex gnus-inhibit-user-auto-expire
+If @code{gnus-inhibit-user-auto-expire} is non-@code{nil}, user marking
+commands will not mark an article as expirable, even if the group has
+auto-expire turned on.
+
+
+@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, RFC 822 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 RFC 822 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 disk. 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. It is called in a buffer that contains all
+the new, incoming mail. 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.
+
+(Note that this function works on both the header on the body of all
+messages, so it is a potentially dangerous function to use (if a body
+of a message contains something that looks like a header line). So
+rather than fix the bug, it is of course the right solution to make it
+into a feature by documenting it.)
+
+@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. @code{nnmail-list-identifiers} may not contain
+@code{\\(..\\)}.
+
+For instance, if you want to remove the @samp{(idm)} and the
+@samp{nagnagnag} identifiers:
+
+@lisp
+(setq nnmail-list-identifiers
+ '("(idm)" "nagnagnag"))
+@end lisp
+
+This can also be done non-destructively with
+@code{gnus-list-identifiers}, @xref{Article Hiding}.
+
+@item nnmail-remove-tabs
+@findex nnmail-remove-tabs
+Translate all @samp{TAB} characters into @samp{SPACE} characters.
+
+@item nnmail-fix-eudora-headers
+@findex nnmail-fix-eudora-headers
+@cindex Eudora
+Eudora produces broken @code{References} headers, but OK
+@code{In-Reply-To} headers. This function will get rid of the
+@code{References} headers.
+
+@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
+ '(| ;; @r{Messages duplicates go to a separate group.}
+ ("gnus-warning" "duplicat\\(e\\|ion\\) of message" "duplicate")
+ ;; @r{Message from daemons, postmaster, and the like to another.}
+ (any mail "mail.misc")
+ ;; @r{Other rules.}
+ [...] ))
+@end lisp
+@noindent
+Or something like:
+@lisp
+(setq nnmail-split-methods
+ '(("duplicates" "^Gnus-Warning:.*duplicate")
+ ;; @r{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 back ends, 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{mail-sources} and @code{nnmail-spool-file} to
+@code{nil}, none of the back ends 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 Rmail
+file you have stashed away with @code{nnbabyl}. All back ends have
+variables called back-end-@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 back ends 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 Back End
+@subsection Choosing a Mail Back End
+
+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.
+
+There are six different mail back ends in the standard Gnus, and more
+back ends are available separately. The mail back end most people use
+(because it is possibly the fastest) is @code{nnml} (@pxref{Mail
+Spool}).
+
+@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 back end.
+* Maildir:: Another one-file-per-message format.
+* Mail Folders:: Having one file for each group.
+* Comparing Mail Back Ends:: An in-depth looks at pros and cons.
+@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} back end 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. Default is
+@file{~/mbox}.
+
+@item nnmbox-active-file
+@vindex nnmbox-active-file
+The name of the active file for the mail box. Default is
+@file{~/.mbox-active}.
+
+@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. Default is @code{t}.
+@end table
+
+
+@node Rmail Babyl
+@subsubsection Rmail Babyl
+@cindex nnbabyl
+@cindex Rmail mbox
+
+@vindex nnbabyl-active-file
+@vindex nnbabyl-mbox-file
+The @dfn{nnbabyl} back end 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. The default is @file{~/RMAIL}
+
+@item nnbabyl-active-file
+@vindex nnbabyl-active-file
+The name of the active file for the rmail box. The default is
+@file{~/.rmail-active}
+
+@item nnbabyl-get-new-mail
+@vindex nnbabyl-get-new-mail
+If non-@code{nil}, @code{nnbabyl} will read incoming mail. Default is
+@code{t}
+@end table
+
+
+@node Mail Spool
+@subsubsection Mail Spool
+@cindex nnml
+@cindex mail @acronym{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 back end, 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 back end. 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 back end when it comes to article
+splitting. It has to create lots of files, and it also generates
+@acronym{NOV} databases for the incoming mails. This makes it possibly the
+fastest back end when it comes to reading mail.
+
+@cindex self contained nnml servers
+@cindex marks
+When the marks file is used (which it is by default), @code{nnml}
+servers have the property that you may backup them using @code{tar} or
+similar, and later be able to restore them into Gnus (by adding the
+proper @code{nnml} server) and have all your marks be preserved. Marks
+for a group is usually stored in the @code{.marks} file (but see
+@code{nnml-marks-file-name}) within each @code{nnml} group's directory.
+Individual @code{nnml} groups are also possible to backup, use @kbd{G m}
+to restore the group (after restoring the backup into the nnml
+directory).
+
+If for some reason you believe your @file{.marks} files are screwed
+up, you can just delete them all. Gnus will then correctly regenerate
+them next time it starts.
+
+Virtual server settings:
+
+@table @code
+@item nnml-directory
+@vindex nnml-directory
+All @code{nnml} directories will be placed under this directory. The
+default is the value of @code{message-directory} (whose default value
+is @file{~/Mail}).
+
+@item nnml-active-file
+@vindex nnml-active-file
+The active file for the @code{nnml} server. The default is
+@file{~/Mail/active}.
+
+@item nnml-newsgroups-file
+@vindex nnml-newsgroups-file
+The @code{nnml} group descriptions file. @xref{Newsgroups File
+Format}. The default is @file{~/Mail/newsgroups}.
+
+@item nnml-get-new-mail
+@vindex nnml-get-new-mail
+If non-@code{nil}, @code{nnml} will read incoming mail. The default is
+@code{t}.
+
+@item nnml-nov-is-evil
+@vindex nnml-nov-is-evil
+If non-@code{nil}, this back end will ignore any @acronym{NOV} files. The
+default is @code{nil}.
+
+@item nnml-nov-file-name
+@vindex nnml-nov-file-name
+The name of the @acronym{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.
+
+@item nnml-marks-is-evil
+@vindex nnml-marks-is-evil
+If non-@code{nil}, this back end will ignore any @sc{marks} files. The
+default is @code{nil}.
+
+@item nnml-marks-file-name
+@vindex nnml-marks-file-name
+The name of the @dfn{marks} files. The default is @file{.marks}.
+
+@item nnml-use-compressed-files
+@vindex nnml-use-compressed-files
+If non-@code{nil}, @code{nnml} will allow using compressed message
+files.
+
+@end table
+
+@findex nnml-generate-nov-databases
+If your @code{nnml} groups and @acronym{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
+@acronym{NOV} databases and it doesn't keep an active file or marks
+file. This makes @code{nnmh} a @emph{much} slower back end 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. The
+default is the value of @code{message-directory} (whose default is
+@file{~/Mail})
+
+@item nnmh-get-new-mail
+@vindex nnmh-get-new-mail
+If non-@code{nil}, @code{nnmh} will read incoming mail. The default is
+@code{t}.
+
+@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}. The default is @code{nil}.
+@end table
+
+
+@node Maildir
+@subsubsection Maildir
+@cindex nnmaildir
+@cindex maildir
+
+@code{nnmaildir} stores mail in the maildir format, with each maildir
+corresponding to a group in Gnus. This format is documented here:
+@uref{http://cr.yp.to/proto/maildir.html} and here:
+@uref{http://www.qmail.org/man/man5/maildir.html}. @code{nnmaildir}
+also stores extra information in the @file{.nnmaildir/} directory
+within a maildir.
+
+Maildir format was designed to allow concurrent deliveries and
+reading, without needing locks. With other back ends, you would have
+your mail delivered to a spool of some kind, and then you would
+configure Gnus to split mail from that spool into your groups. You
+can still do that with @code{nnmaildir}, but the more common
+configuration is to have your mail delivered directly to the maildirs
+that appear as group in Gnus.
+
+@code{nnmaildir} is designed to be perfectly reliable: @kbd{C-g} will
+never corrupt its data in memory, and @code{SIGKILL} will never
+corrupt its data in the filesystem.
+
+@code{nnmaildir} stores article marks and @acronym{NOV} data in each
+maildir. So you can copy a whole maildir from one Gnus setup to
+another, and you will keep your marks.
+
+Virtual server settings:
+
+@table @code
+@item directory
+For each of your @code{nnmaildir} servers (it's very unlikely that
+you'd need more than one), you need to create a directory and populate
+it with maildirs or symlinks to maildirs (and nothing else; do not
+choose a directory already used for other purposes). Each maildir
+will be represented in Gnus as a newsgroup on that server; the
+filename of the symlink will be the name of the group. Any filenames
+in the directory starting with @samp{.} are ignored. The directory is
+scanned when you first start Gnus, and each time you type @kbd{g} in
+the group buffer; if any maildirs have been removed or added,
+@code{nnmaildir} notices at these times.
+
+The value of the @code{directory} parameter should be a Lisp form
+which is processed by @code{eval} and @code{expand-file-name} to get
+the path of the directory for this server. The form is @code{eval}ed
+only when the server is opened; the resulting string is used until the
+server is closed. (If you don't know about forms and @code{eval},
+don't worry---a simple string will work.) This parameter is not
+optional; you must specify it. I don't recommend using
+@code{"~/Mail"} or a subdirectory of it; several other parts of Gnus
+use that directory by default for various things, and may get confused
+if @code{nnmaildir} uses it too. @code{"~/.nnmaildir"} is a typical
+value.
+
+@item target-prefix
+This should be a Lisp form which is processed by @code{eval} and
+@code{expand-file-name}. The form is @code{eval}ed only when the
+server is opened; the resulting string is used until the server is
+closed.
+
+When you create a group on an @code{nnmaildir} server, the maildir is
+created with @code{target-prefix} prepended to its name, and a symlink
+pointing to that maildir is created, named with the plain group name.
+So if @code{directory} is @code{"~/.nnmaildir"} and
+@code{target-prefix} is @code{"../maildirs/"}, then when you create
+the group @code{foo}, @code{nnmaildir} will create
+@file{~/.nnmaildir/../maildirs/foo} as a maildir, and will create
+@file{~/.nnmaildir/foo} as a symlink pointing to
+@file{../maildirs/foo}.
+
+You can set @code{target-prefix} to a string without any slashes to
+create both maildirs and symlinks in the same @code{directory}; in
+this case, any maildirs found in @code{directory} whose names start
+with @code{target-prefix} will not be listed as groups (but the
+symlinks pointing to them will be).
+
+As a special case, if @code{target-prefix} is @code{""} (the default),
+then when you create a group, the maildir will be created in
+@code{directory} without a corresponding symlink. Beware that you
+cannot use @code{gnus-group-delete-group} on such groups without the
+@code{force} argument.
+
+@item directory-files
+This should be a function with the same interface as
+@code{directory-files} (such as @code{directory-files} itself). It is
+used to scan the server's @code{directory} for maildirs. This
+parameter is optional; the default is
+@code{nnheader-directory-files-safe} if
+@code{nnheader-directory-files-is-safe} is @code{nil}, and
+@code{directory-files} otherwise.
+(@code{nnheader-directory-files-is-safe} is checked only once when the
+server is opened; if you want to check it each time the directory is
+scanned, you'll have to provide your own function that does that.)
+
+@item get-new-mail
+If non-@code{nil}, then after scanning for new mail in the group
+maildirs themselves as usual, this server will also incorporate mail
+the conventional Gnus way, from @code{mail-sources} according to
+@code{nnmail-split-methods} or @code{nnmail-split-fancy}. The default
+value is @code{nil}.
+
+Do @emph{not} use the same maildir both in @code{mail-sources} and as
+an @code{nnmaildir} group. The results might happen to be useful, but
+that would be by chance, not by design, and the results might be
+different in the future. If your split rules create new groups,
+remember to supply a @code{create-directory} server parameter.
+@end table
+
+@subsubsection Group parameters
+
+@code{nnmaildir} uses several group parameters. It's safe to ignore
+all this; the default behavior for @code{nnmaildir} is the same as the
+default behavior for other mail back ends: articles are deleted after
+one week, etc. Except for the expiry parameters, all this
+functionality is unique to @code{nnmaildir}, so you can ignore it if
+you're just trying to duplicate the behavior you already have with
+another back end.
+
+If the value of any of these parameters is a vector, the first element
+is evaluated as a Lisp form and the result is used, rather than the
+original value. If the value is not a vector, the value itself is
+evaluated as a Lisp form. (This is why these parameters use names
+different from those of other, similar parameters supported by other
+back ends: they have different, though similar, meanings.) (For
+numbers, strings, @code{nil}, and @code{t}, you can ignore the
+@code{eval} business again; for other values, remember to use an extra
+quote and wrap the value in a vector when appropriate.)
+
+@table @code
+@item expire-age
+An integer specifying the minimum age, in seconds, of an article
+before it will be expired, or the symbol @code{never} to specify that
+articles should never be expired. If this parameter is not set,
+@code{nnmaildir} falls back to the usual
+@code{nnmail-expiry-wait}(@code{-function}) variables (the
+@code{expiry-wait} group parameter overrides @code{nnmail-expiry-wait}
+and makes @code{nnmail-expiry-wait-function} ineffective). If you
+wanted a value of 3 days, you could use something like @code{[(* 3 24
+60 60)]}; @code{nnmaildir} will evaluate the form and use the result.
+An article's age is measured starting from the article file's
+modification time. Normally, this is the same as the article's
+delivery time, but editing an article makes it younger. Moving an
+article (other than via expiry) may also make an article younger.
+
+@item expire-group
+If this is set to a string such as a full Gnus group name, like
+@example
+"backend+server.address.string:group.name"
+@end example
+and if it is not the name of the same group that the parameter belongs
+to, then articles will be moved to the specified group during expiry
+before being deleted. @emph{If this is set to an @code{nnmaildir}
+group, the article will be just as old in the destination group as it
+was in the source group.} So be careful with @code{expire-age} in the
+destination group. If this is set to the name of the same group that
+the parameter belongs to, then the article is not expired at all. If
+you use the vector form, the first element is evaluated once for each
+article. So that form can refer to
+@code{nnmaildir-article-file-name}, etc., to decide where to put the
+article. @emph{Even if this parameter is not set, @code{nnmaildir}
+does not fall back to the @code{expiry-target} group parameter or the
+@code{nnmail-expiry-target} variable.}
+
+@item read-only
+If this is set to @code{t}, @code{nnmaildir} will treat the articles
+in this maildir as read-only. This means: articles are not renamed
+from @file{new/} into @file{cur/}; articles are only found in
+@file{new/}, not @file{cur/}; articles are never deleted; articles
+cannot be edited. @file{new/} is expected to be a symlink to the
+@file{new/} directory of another maildir---e.g., a system-wide mailbox
+containing a mailing list of common interest. Everything in the
+maildir outside @file{new/} is @emph{not} treated as read-only, so for
+a shared mailbox, you do still need to set up your own maildir (or
+have write permission to the shared mailbox); your maildir just won't
+contain extra copies of the articles.
+
+@item directory-files
+A function with the same interface as @code{directory-files}. It is
+used to scan the directories in the maildir corresponding to this
+group to find articles. The default is the function specified by the
+server's @code{directory-files} parameter.
+
+@item distrust-Lines:
+If non-@code{nil}, @code{nnmaildir} will always count the lines of an
+article, rather than use the @code{Lines:} header field. If
+@code{nil}, the header field will be used if present.
+
+@item always-marks
+A list of mark symbols, such as @code{['(read expire)]}. Whenever
+Gnus asks @code{nnmaildir} for article marks, @code{nnmaildir} will
+say that all articles have these marks, regardless of whether the
+marks stored in the filesystem say so. This is a proof-of-concept
+feature that will probably be removed eventually; it ought to be done
+in Gnus proper, or abandoned if it's not worthwhile.
+
+@item never-marks
+A list of mark symbols, such as @code{['(tick expire)]}. Whenever
+Gnus asks @code{nnmaildir} for article marks, @code{nnmaildir} will
+say that no articles have these marks, regardless of whether the marks
+stored in the filesystem say so. @code{never-marks} overrides
+@code{always-marks}. This is a proof-of-concept feature that will
+probably be removed eventually; it ought to be done in Gnus proper, or
+abandoned if it's not worthwhile.
+
+@item nov-cache-size
+An integer specifying the size of the @acronym{NOV} memory cache. To
+speed things up, @code{nnmaildir} keeps @acronym{NOV} data in memory
+for a limited number of articles in each group. (This is probably not
+worthwhile, and will probably be removed in the future.) This
+parameter's value is noticed only the first time a group is seen after
+the server is opened---i.e., when you first start Gnus, typically.
+The @acronym{NOV} cache is never resized until the server is closed
+and reopened. The default is an estimate of the number of articles
+that would be displayed in the summary buffer: a count of articles
+that are either marked with @code{tick} or not marked with
+@code{read}, plus a little extra.
+@end table
+
+@subsubsection Article identification
+Articles are stored in the @file{cur/} subdirectory of each maildir.
+Each article file is named like @code{uniq:info}, where @code{uniq}
+contains no colons. @code{nnmaildir} ignores, but preserves, the
+@code{:info} part. (Other maildir readers typically use this part of
+the filename to store marks.) The @code{uniq} part uniquely
+identifies the article, and is used in various places in the
+@file{.nnmaildir/} subdirectory of the maildir to store information
+about the corresponding article. The full pathname of an article is
+available in the variable @code{nnmaildir-article-file-name} after you
+request the article in the summary buffer.
+
+@subsubsection NOV data
+An article identified by @code{uniq} has its @acronym{NOV} data (used
+to generate lines in the summary buffer) stored in
+@code{.nnmaildir/nov/uniq}. There is no
+@code{nnmaildir-generate-nov-databases} function. (There isn't much
+need for it---an article's @acronym{NOV} data is updated automatically
+when the article or @code{nnmail-extra-headers} has changed.) You can
+force @code{nnmaildir} to regenerate the @acronym{NOV} data for a
+single article simply by deleting the corresponding @acronym{NOV}
+file, but @emph{beware}: this will also cause @code{nnmaildir} to
+assign a new article number for this article, which may cause trouble
+with @code{seen} marks, the Agent, and the cache.
+
+@subsubsection Article marks
+An article identified by @code{uniq} is considered to have the mark
+@code{flag} when the file @file{.nnmaildir/marks/flag/uniq} exists.
+When Gnus asks @code{nnmaildir} for a group's marks, @code{nnmaildir}
+looks for such files and reports the set of marks it finds. When Gnus
+asks @code{nnmaildir} to store a new set of marks, @code{nnmaildir}
+creates and deletes the corresponding files as needed. (Actually,
+rather than create a new file for each mark, it just creates hard
+links to @file{.nnmaildir/markfile}, to save inodes.)
+
+You can invent new marks by creating a new directory in
+@file{.nnmaildir/marks/}. You can tar up a maildir and remove it from
+your server, untar it later, and keep your marks. You can add and
+remove marks yourself by creating and deleting mark files. If you do
+this while Gnus is running and your @code{nnmaildir} server is open,
+it's best to exit all summary buffers for @code{nnmaildir} groups and
+type @kbd{s} in the group buffer first, and to type @kbd{g} or
+@kbd{M-g} in the group buffer afterwards. Otherwise, Gnus might not
+pick up the changes, and might undo them.
+
+
+@node Mail Folders
+@subsubsection Mail Folders
+@cindex nnfolder
+@cindex mbox folders
+@cindex mail folders
+
+@code{nnfolder} is a back end 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.
+
+@cindex self contained nnfolder servers
+@cindex marks
+When the marks file is used (which it is by default), @code{nnfolder}
+servers have the property that you may backup them using @code{tar} or
+similar, and later be able to restore them into Gnus (by adding the
+proper @code{nnfolder} server) and have all your marks be preserved.
+Marks for a group are usually stored in a file named as the mbox file
+with @code{.mrk} concatenated to it (but see
+@code{nnfolder-marks-file-suffix}) within the @code{nnfolder}
+directory. Individual @code{nnfolder} groups are also possible to
+backup, use @kbd{G m} to restore the group (after restoring the backup
+into the @code{nnfolder} directory).
+
+Virtual server settings:
+
+@table @code
+@item nnfolder-directory
+@vindex nnfolder-directory
+All the @code{nnfolder} mail boxes will be stored under this
+directory. The default is the value of @code{message-directory}
+(whose default is @file{~/Mail})
+
+@item nnfolder-active-file
+@vindex nnfolder-active-file
+The name of the active file. The default is @file{~/Mail/active}.
+
+@item nnfolder-newsgroups-file
+@vindex nnfolder-newsgroups-file
+The name of the group descriptions file. @xref{Newsgroups File
+Format}. The default is @file{~/Mail/newsgroups}
+
+@item nnfolder-get-new-mail
+@vindex nnfolder-get-new-mail
+If non-@code{nil}, @code{nnfolder} will read incoming mail. The
+default is @code{t}
+
+@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
+
+@item nnfolder-delete-mail-hook
+@vindex nnfolder-delete-mail-hook
+Hook run in a buffer narrowed to the message that is to be deleted.
+This function can be used to copy the message to somewhere else, or to
+extract some information from it before removing it.
+
+@item nnfolder-nov-is-evil
+@vindex nnfolder-nov-is-evil
+If non-@code{nil}, this back end will ignore any @acronym{NOV} files. The
+default is @code{nil}.
+
+@item nnfolder-nov-file-suffix
+@vindex nnfolder-nov-file-suffix
+The extension for @acronym{NOV} files. The default is @file{.nov}.
+
+@item nnfolder-nov-directory
+@vindex nnfolder-nov-directory
+The directory where the @acronym{NOV} files should be stored. If
+@code{nil}, @code{nnfolder-directory} is used.
+
+@item nnfolder-marks-is-evil
+@vindex nnfolder-marks-is-evil
+If non-@code{nil}, this back end will ignore any @sc{marks} files. The
+default is @code{nil}.
+
+@item nnfolder-marks-file-suffix
+@vindex nnfolder-marks-file-suffix
+The extension for @sc{marks} files. The default is @file{.mrk}.
+
+@item nnfolder-marks-directory
+@vindex nnfolder-marks-directory
+The directory where the @sc{marks} files should be stored. If
+@code{nil}, @code{nnfolder-directory} is used.
+
+@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}. This only works if you use long file names,
+though.
+
+@node Comparing Mail Back Ends
+@subsubsection Comparing Mail Back Ends
+
+First, just for terminology, the @dfn{back end} is the common word for a
+low-level access method---a transport, if you will, by which something
+is acquired. The sense is that one's mail has to come from somewhere,
+and so selection of a suitable back end is required in order to get that
+mail within spitting distance of Gnus.
+
+The same concept exists for Usenet itself: Though access to articles is
+typically done by @acronym{NNTP} these days, once upon a midnight dreary, everyone
+in the world got at Usenet by running a reader on the machine where the
+articles lay (the machine which today we call an @acronym{NNTP} server), and
+access was by the reader stepping into the articles' directory spool
+area directly. One can still select between either the @code{nntp} or
+@code{nnspool} back ends, to select between these methods, if one happens
+actually to live on the server (or can see its spool directly, anyway,
+via NFS).
+
+The goal in selecting a mail back end is to pick one which
+simultaneously represents a suitable way of dealing with the original
+format plus leaving mail in a form that is convenient to use in the
+future. Here are some high and low points on each:
+
+@table @code
+@item nnmbox
+
+UNIX systems have historically had a single, very common, and well-
+defined format. All messages arrive in a single @dfn{spool file}, and
+they are delineated by a line whose regular expression matches
+@samp{^From_}. (My notational use of @samp{_} is to indicate a space,
+to make it clear in this instance that this is not the RFC-specified
+@samp{From:} header.) Because Emacs and therefore Gnus emanate
+historically from the Unix environment, it is simplest if one does not
+mess a great deal with the original mailbox format, so if one chooses
+this back end, Gnus' primary activity in getting mail from the real spool
+area to Gnus' preferred directory is simply to copy it, with no
+(appreciable) format change in the process. It is the ``dumbest'' way
+to move mail into availability in the Gnus environment. This makes it
+fast to move into place, but slow to parse, when Gnus has to look at
+what's where.
+
+@item nnbabyl
+
+Once upon a time, there was the DEC-10 and DEC-20, running operating
+systems called TOPS and related things, and the usual (only?) mail
+reading environment was a thing called Babyl. I don't know what format
+was used for mail landing on the system, but Babyl had its own internal
+format to which mail was converted, primarily involving creating a
+spool-file-like entity with a scheme for inserting Babyl-specific
+headers and status bits above the top of each message in the file.
+Rmail was Emacs' first mail reader, it was written by Richard Stallman,
+and Stallman came out of that TOPS/Babyl environment, so he wrote Rmail
+to understand the mail files folks already had in existence. Gnus (and
+VM, for that matter) continue to support this format because it's
+perceived as having some good qualities in those mailer-specific
+headers/status bits stuff. Rmail itself still exists as well, of
+course, and is still maintained by Stallman.
+
+Both of the above forms leave your mail in a single file on your
+file system, and they must parse that entire file each time you take a
+look at your mail.
+
+@item nnml
+
+@code{nnml} is the back end which smells the most as though you were
+actually operating with an @code{nnspool}-accessed Usenet system. (In
+fact, I believe @code{nnml} actually derived from @code{nnspool} code,
+lo these years ago.) One's mail is taken from the original spool file,
+and is then cut up into individual message files, 1:1. It maintains a
+Usenet-style active file (analogous to what one finds in an INN- or
+CNews-based news system in (for instance) @file{/var/lib/news/active},
+or what is returned via the @samp{NNTP LIST} verb) and also creates
+@dfn{overview} files for efficient group entry, as has been defined for
+@acronym{NNTP} servers for some years now. It is slower in mail-splitting,
+due to the creation of lots of files, updates to the @code{nnml} active
+file, and additions to overview files on a per-message basis, but it is
+extremely fast on access because of what amounts to the indexing support
+provided by the active file and overviews.
+
+@code{nnml} costs @dfn{inodes} in a big way; that is, it soaks up the
+resource which defines available places in the file system to put new
+files. Sysadmins take a dim view of heavy inode occupation within
+tight, shared file systems. But if you live on a personal machine where
+the file system is your own and space is not at a premium, @code{nnml}
+wins big.
+
+It is also problematic using this back end if you are living in a
+FAT16-based Windows world, since much space will be wasted on all these
+tiny files.
+
+@item nnmh
+
+The Rand MH mail-reading system has been around UNIX systems for a very
+long time; it operates by splitting one's spool file of messages into
+individual files, but with little or no indexing support---@code{nnmh}
+is considered to be semantically equivalent to ``@code{nnml} without
+active file or overviews''. This is arguably the worst choice, because
+one gets the slowness of individual file creation married to the
+slowness of access parsing when learning what's new in one's groups.
+
+@item nnfolder
+
+Basically the effect of @code{nnfolder} is @code{nnmbox} (the first
+method described above) on a per-group basis. That is, @code{nnmbox}
+itself puts @emph{all} one's mail in one file; @code{nnfolder} provides a
+little bit of optimization to this so that each of one's mail groups has
+a Unix mail box file. It's faster than @code{nnmbox} because each group
+can be parsed separately, and still provides the simple Unix mail box
+format requiring minimal effort in moving the mail around. In addition,
+it maintains an ``active'' file making it much faster for Gnus to figure
+out how many messages there are in each separate group.
+
+If you have groups that are expected to have a massive amount of
+messages, @code{nnfolder} is not the best choice, but if you receive
+only a moderate amount of mail, @code{nnfolder} is probably the most
+friendly mail back end all over.
+
+@item nnmaildir
+
+For configuring expiry and other things, @code{nnmaildir} uses
+incompatible group parameters, slightly different from those of other
+mail back ends.
+
+@code{nnmaildir} is largely similar to @code{nnml}, with some notable
+differences. Each message is stored in a separate file, but the
+filename is unrelated to the article number in Gnus. @code{nnmaildir}
+also stores the equivalent of @code{nnml}'s overview files in one file
+per article, so it uses about twice as many inodes as @code{nnml}. (Use
+@code{df -i} to see how plentiful your inode supply is.) If this slows
+you down or takes up very much space, consider switching to
+@uref{http://www.namesys.com/, ReiserFS} or another non-block-structured
+file system.
+
+Since maildirs don't require locking for delivery, the maildirs you use
+as groups can also be the maildirs your mail is directly delivered to.
+This means you can skip Gnus' mail splitting if your mail is already
+organized into different mailboxes during delivery. A @code{directory}
+entry in @code{mail-sources} would have a similar effect, but would
+require one set of mailboxes for spooling deliveries (in mbox format,
+thus damaging message bodies), and another set to be used as groups (in
+whatever format you like). A maildir has a built-in spool, in the
+@code{new/} subdirectory. Beware that currently, mail moved from
+@code{new/} to @code{cur/} instead of via mail splitting will not
+undergo treatment such as duplicate checking.
+
+@code{nnmaildir} stores article marks for a given group in the
+corresponding maildir, in a way designed so that it's easy to manipulate
+them from outside Gnus. You can tar up a maildir, unpack it somewhere
+else, and still have your marks. @code{nnml} also stores marks, but
+it's not as easy to work with them from outside Gnus as with
+@code{nnmaildir}.
+
+@code{nnmaildir} uses a significant amount of memory to speed things up.
+(It keeps in memory some of the things that @code{nnml} stores in files
+and that @code{nnmh} repeatedly parses out of message files.) If this
+is a problem for you, you can set the @code{nov-cache-size} group
+parameter to something small (0 would probably not work, but 1 probably
+would) to make it use less memory. This caching will probably be
+removed in the future.
+
+Startup is likely to be slower with @code{nnmaildir} than with other
+back ends. Everything else is likely to be faster, depending in part
+on your file system.
+
+@code{nnmaildir} does not use @code{nnoo}, so you cannot use @code{nnoo}
+to write an @code{nnmaildir}-derived back end.
+
+@end table
+
+
+@node Browsing the Web
+@section Browsing the Web
+@cindex web
+@cindex browsing the web
+@cindex www
+@cindex http
+
+Web-based discussion forums are getting more and more popular. On many
+subjects, the web-based forums have become the most important forums,
+eclipsing the importance of mailing lists and news groups. The reason
+is easy to understand---they are friendly to new users; you just point
+and click, and there's the discussion. With mailing lists, you have to
+go through a cumbersome subscription procedure, and most people don't
+even know what a news group is.
+
+The problem with this scenario is that web browsers are not very good at
+being newsreaders. They do not keep track of what articles you've read;
+they do not allow you to score on subjects you're interested in; they do
+not allow off-line browsing; they require you to click around and drive
+you mad in the end.
+
+So---if web browsers suck at reading discussion forums, why not use Gnus
+to do it instead?
+
+Gnus has been getting a bit of a collection of back ends for providing
+interfaces to these sources.
+
+@menu
+* Archiving Mail::
+* Web Searches:: Creating groups from articles that match a string.
+* Slashdot:: Reading the Slashdot comments.
+* Ultimate:: The Ultimate Bulletin Board systems.
+* Web Archive:: Reading mailing list archived on web.
+* RSS:: Reading RDF site summary.
+* Customizing W3:: Doing stuff to Emacs/W3 from Gnus.
+@end menu
+
+All the web sources require Emacs/W3 and the url library or those
+alternatives to work.
+
+The main caveat with all these web sources is that they probably won't
+work for a very long time. Gleaning information from the @acronym{HTML} data
+is guesswork at best, and when the layout is altered, the Gnus back end
+will fail. If you have reasonably new versions of these back ends,
+though, you should be ok.
+
+One thing all these Web methods have in common is that the Web sources
+are often down, unavailable or just plain too slow to be fun. In those
+cases, it makes a lot of sense to let the Gnus Agent (@pxref{Gnus
+Unplugged}) handle downloading articles, and then you can read them at
+leisure from your local disk. No more World Wide Wait for you.
+
+@node Archiving Mail
+@subsection Archiving Mail
+@cindex archiving mail
+@cindex backup of mail
+
+Some of the back ends, notably @code{nnml}, @code{nnfolder}, and
+@code{nnmaildir}, now actually store the article marks with each group.
+For these servers, archiving and restoring a group while preserving
+marks is fairly simple.
+
+(Preserving the group level and group parameters as well still
+requires ritual dancing and sacrifices to the @file{.newsrc.eld} deity
+though.)
+
+To archive an entire @code{nnml}, @code{nnfolder}, or @code{nnmaildir}
+server, take a recursive copy of the server directory. There is no need
+to shut down Gnus, so archiving may be invoked by @code{cron} or
+similar. You restore the data by restoring the directory tree, and
+adding a server definition pointing to that directory in Gnus. The
+@ref{Article Backlog}, @ref{Asynchronous Fetching} and other things
+might interfere with overwriting data, so you may want to shut down Gnus
+before you restore the data.
+
+It is also possible to archive individual @code{nnml},
+@code{nnfolder}, or @code{nnmaildir} groups, while preserving marks.
+For @code{nnml} or @code{nnmaildir}, you copy all files in the group's
+directory. For @code{nnfolder} you need to copy both the base folder
+file itself (@file{FOO}, say), and the marks file (@file{FOO.mrk} in
+this example). Restoring the group is done with @kbd{G m} from the Group
+buffer. The last step makes Gnus notice the new directory.
+@code{nnmaildir} notices the new directory automatically, so @kbd{G m}
+is unnecessary in that case.
+
+@node Web Searches
+@subsection Web Searches
+@cindex nnweb
+@cindex Google
+@cindex dejanews
+@cindex gmane
+@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} back end 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 (Google, 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 or those alternatives
+(try @code{customize-group} on the @samp{mm-url} variable group)
+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{google}, @code{dejanews}, and @code{gmane}. Note that
+@code{dejanews} is an alias to @code{google}.
+
+@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
+999.
+
+@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 Slashdot
+@subsection Slashdot
+@cindex Slashdot
+@cindex nnslashdot
+
+@uref{http://slashdot.org/, Slashdot} is a popular news site, with
+lively discussion following the news articles. @code{nnslashdot} will
+let you read this forum in a convenient manner.
+
+The easiest way to read this source is to put something like the
+following in your @file{~/.gnus.el} file:
+
+@lisp
+(setq gnus-secondary-select-methods
+ '((nnslashdot "")))
+@end lisp
+
+This will make Gnus query the @code{nnslashdot} back end for new comments
+and groups. The @kbd{F} command will subscribe each new news article as
+a new Gnus group, and you can read the comments by entering these
+groups. (Note that the default subscription method is to subscribe new
+groups as zombies. Other methods are available (@pxref{Subscription
+Methods}).
+
+If you want to remove an old @code{nnslashdot} group, the @kbd{G DEL}
+command is the most handy tool (@pxref{Foreign Groups}).
+
+When following up to @code{nnslashdot} comments (or posting new
+comments), some light @acronym{HTML}izations will be performed. In
+particular, text quoted with @samp{> } will be quoted with
+@samp{blockquote} instead, and signatures will have @samp{br} added to
+the end of each line. Other than that, you can just write @acronym{HTML}
+directly into the message buffer. Note that Slashdot filters out some
+@acronym{HTML} forms.
+
+The following variables can be altered to change its behavior:
+
+@table @code
+@item nnslashdot-threaded
+Whether @code{nnslashdot} should display threaded groups or not. The
+default is @code{t}. To be able to display threads, @code{nnslashdot}
+has to retrieve absolutely all comments in a group upon entry. If a
+threaded display is not required, @code{nnslashdot} will only retrieve
+the comments that are actually wanted by the user. Threading is nicer,
+but much, much slower than unthreaded.
+
+@item nnslashdot-login-name
+@vindex nnslashdot-login-name
+The login name to use when posting.
+
+@item nnslashdot-password
+@vindex nnslashdot-password
+The password to use when posting.
+
+@item nnslashdot-directory
+@vindex nnslashdot-directory
+Where @code{nnslashdot} will store its files. The default is
+@file{~/News/slashdot/}.
+
+@item nnslashdot-active-url
+@vindex nnslashdot-active-url
+The @acronym{URL} format string that will be used to fetch the
+information on news articles and comments. The default is@*
+@samp{http://slashdot.org/search.pl?section=&min=%d}.
+
+@item nnslashdot-comments-url
+@vindex nnslashdot-comments-url
+The @acronym{URL} format string that will be used to fetch comments.
+
+@item nnslashdot-article-url
+@vindex nnslashdot-article-url
+The @acronym{URL} format string that will be used to fetch the news
+article. The default is
+@samp{http://slashdot.org/article.pl?sid=%s&mode=nocomment}.
+
+@item nnslashdot-threshold
+@vindex nnslashdot-threshold
+The score threshold. The default is -1.
+
+@item nnslashdot-group-number
+@vindex nnslashdot-group-number
+The number of old groups, in addition to the ten latest, to keep
+updated. The default is 0.
+
+@end table
+
+
+
+@node Ultimate
+@subsection Ultimate
+@cindex nnultimate
+@cindex Ultimate Bulletin Board
+
+@uref{http://www.ultimatebb.com/, The Ultimate Bulletin Board} is
+probably the most popular Web bulletin board system used. It has a
+quite regular and nice interface, and it's possible to get the
+information Gnus needs to keep groups updated.
+
+The easiest way to get started with @code{nnultimate} is to say
+something like the following in the group buffer: @kbd{B nnultimate RET
+http://www.tcj.com/messboard/ubbcgi/ RET}. (Substitute the @acronym{URL}
+(not including @samp{Ultimate.cgi} or the like at the end) for a forum
+you're interested in; there's quite a list of them on the Ultimate web
+site.) Then subscribe to the groups you're interested in from the
+server buffer, and read them from the group buffer.
+
+The following @code{nnultimate} variables can be altered:
+
+@table @code
+@item nnultimate-directory
+@vindex nnultimate-directory
+The directory where @code{nnultimate} stores its files. The default is@*
+@file{~/News/ultimate/}.
+@end table
+
+
+@node Web Archive
+@subsection Web Archive
+@cindex nnwarchive
+@cindex Web Archive
+
+Some mailing lists only have archives on Web servers, such as
+@uref{http://www.egroups.com/} and
+@uref{http://www.mail-archive.com/}. It has a quite regular and nice
+interface, and it's possible to get the information Gnus needs to keep
+groups updated.
+
+@findex gnus-group-make-warchive-group
+The easiest way to get started with @code{nnwarchive} is to say
+something like the following in the group buffer: @kbd{M-x
+gnus-group-make-warchive-group RET @var{an_egroup} RET egroups RET
+www.egroups.com RET @var{your@@email.address} RET}. (Substitute the
+@var{an_egroup} with the mailing list you subscribed, the
+@var{your@@email.address} with your email address.), or to browse the
+back end by @kbd{B nnwarchive RET mail-archive RET}.
+
+The following @code{nnwarchive} variables can be altered:
+
+@table @code
+@item nnwarchive-directory
+@vindex nnwarchive-directory
+The directory where @code{nnwarchive} stores its files. The default is@*
+@file{~/News/warchive/}.
+
+@item nnwarchive-login
+@vindex nnwarchive-login
+The account name on the web server.
+
+@item nnwarchive-passwd
+@vindex nnwarchive-passwd
+The password for your account on the web server.
+@end table
+
+@node RSS
+@subsection RSS
+@cindex nnrss
+@cindex RSS
+
+Some web sites have an RDF Site Summary (@acronym{RSS}).
+@acronym{RSS} is a format for summarizing headlines from news related
+sites (such as BBC or CNN). But basically anything list-like can be
+presented as an @acronym{RSS} feed: weblogs, changelogs or recent
+changes to a wiki (e.g. @url{http://cliki.net/recent-changes.rdf}).
+
+@acronym{RSS} has a quite regular and nice interface, and it's
+possible to get the information Gnus needs to keep groups updated.
+
+Note: you had better use Emacs which supports the @code{utf-8} coding
+system because @acronym{RSS} uses UTF-8 for encoding non-@acronym{ASCII}
+text by default. It is also used by default for non-@acronym{ASCII}
+group names.
+
+@kindex G R (Group)
+Use @kbd{G R} from the group buffer to subscribe to a feed---you will be
+prompted for the location, the title and the description of the feed.
+The title, which allows any characters, will be used for the group name
+and the name of the group data file. The description can be omitted.
+
+An easy way to get started with @code{nnrss} is to say something like
+the following in the group buffer: @kbd{B nnrss RET RET y}, then
+subscribe to groups.
+
+The @code{nnrss} back end saves the group data file in
+@code{nnrss-directory} (see below) for each @code{nnrss} group. File
+names containing non-@acronym{ASCII} characters will be encoded by the
+coding system specified with the @code{nnmail-pathname-coding-system}
+variable. If it is @code{nil}, in Emacs the coding system defaults to
+the value of @code{default-file-name-coding-system}. If you are using
+XEmacs and want to use non-@acronym{ASCII} group names, you should set
+the value for the @code{nnmail-pathname-coding-system} variable properly.
+
+The @code{nnrss} back end generates @samp{multipart/alternative}
+@acronym{MIME} articles in which each contains a @samp{text/plain} part
+and a @samp{text/html} part.
+
+@cindex OPML
+You can also use the following commands to import and export your
+subscriptions from a file in @acronym{OPML} format (Outline Processor
+Markup Language).
+
+@defun nnrss-opml-import file
+Prompt for an @acronym{OPML} file, and subscribe to each feed in the
+file.
+@end defun
+
+@defun nnrss-opml-export
+Write your current @acronym{RSS} subscriptions to a buffer in
+@acronym{OPML} format.
+@end defun
+
+The following @code{nnrss} variables can be altered:
+
+@table @code
+@item nnrss-directory
+@vindex nnrss-directory
+The directory where @code{nnrss} stores its files. The default is
+@file{~/News/rss/}.
+
+@item nnrss-file-coding-system
+@vindex nnrss-file-coding-system
+The coding system used when reading and writing the @code{nnrss} groups
+data files. The default is the value of
+@code{mm-universal-coding-system} (which defaults to @code{emacs-mule}
+in Emacs or @code{escape-quoted} in XEmacs).
+
+@item nnrss-use-local
+@vindex nnrss-use-local
+@findex nnrss-generate-download-script
+If you set @code{nnrss-use-local} to @code{t}, @code{nnrss} will read
+the feeds from local files in @code{nnrss-directory}. You can use
+the command @code{nnrss-generate-download-script} to generate a
+download script using @command{wget}.
+
+@item nnrss-wash-html-in-text-plain-parts
+Non-@code{nil} means that @code{nnrss} renders text in @samp{text/plain}
+parts as @acronym{HTML}. The function specified by the
+@code{mm-text-html-renderer} variable (@pxref{Display Customization,
+,Display Customization, emacs-mime, The Emacs MIME Manual}) will be used
+to render text. If it is @code{nil}, which is the default, text will
+simply be folded. Leave it @code{nil} if you prefer to see
+@samp{text/html} parts.
+@end table
+
+The following code may be helpful, if you want to show the description in
+the summary buffer.
+
+@lisp
+(add-to-list 'nnmail-extra-headers nnrss-description-field)
+(setq gnus-summary-line-format "%U%R%z%I%(%[%4L: %-15,15f%]%) %s%uX\n")
+
+(defun gnus-user-format-function-X (header)
+ (let ((descr
+ (assq nnrss-description-field (mail-header-extra header))))
+ (if descr (concat "\n\t" (cdr descr)) "")))
+@end lisp
+
+The following code may be useful to open an nnrss url directly from the
+summary buffer.
+
+@lisp
+(require 'browse-url)
+
+(defun browse-nnrss-url( arg )
+ (interactive "p")
+ (let ((url (assq nnrss-url-field
+ (mail-header-extra
+ (gnus-data-header
+ (assq (gnus-summary-article-number)
+ gnus-newsgroup-data))))))
+ (if url
+ (progn
+ (browse-url (cdr url))
+ (gnus-summary-mark-as-read-forward 1))
+ (gnus-summary-scroll-up arg))))
+
+(eval-after-load "gnus"
+ #'(define-key gnus-summary-mode-map
+ (kbd "<RET>") 'browse-nnrss-url))
+(add-to-list 'nnmail-extra-headers nnrss-url-field)
+@end lisp
+
+Even if you have added @code{"text/html"} to the
+@code{mm-discouraged-alternatives} variable (@pxref{Display
+Customization, ,Display Customization, emacs-mime, The Emacs MIME
+Manual}) since you don't want to see @acronym{HTML} parts, it might be
+more useful especially in @code{nnrss} groups to display
+@samp{text/html} parts. Here's an example of setting
+@code{mm-discouraged-alternatives} as a group parameter (@pxref{Group
+Parameters}) in order to display @samp{text/html} parts only in
+@code{nnrss} groups:
+
+@lisp
+;; @r{Set the default value of @code{mm-discouraged-alternatives}.}
+(eval-after-load "gnus-sum"
+ '(add-to-list
+ 'gnus-newsgroup-variables
+ '(mm-discouraged-alternatives
+ . '("text/html" "image/.*"))))
+
+;; @r{Display @samp{text/html} parts in @code{nnrss} groups.}
+(add-to-list
+ 'gnus-parameters
+ '("\\`nnrss:" (mm-discouraged-alternatives nil)))
+@end lisp
+
+
+@node Customizing W3
+@subsection Customizing W3
+@cindex W3
+@cindex html
+@cindex url
+@cindex Netscape
+
+Gnus uses the url library to fetch web pages and Emacs/W3 (or those
+alternatives) to display web pages. Emacs/W3 is documented in its own
+manual, but there are some things that may be more relevant for Gnus
+users.
+
+For instance, a common question is how to make Emacs/W3 follow links
+using the @code{browse-url} functions (which will call some external web
+browser like Netscape). Here's one way:
+
+@lisp
+(eval-after-load "w3"
+ '(progn
+ (fset 'w3-fetch-orig (symbol-function 'w3-fetch))
+ (defun w3-fetch (&optional url target)
+ (interactive (list (w3-read-url-with-default)))
+ (if (eq major-mode 'gnus-article-mode)
+ (browse-url url)
+ (w3-fetch-orig url target)))))
+@end lisp
+
+Put that in your @file{.emacs} file, and hitting links in W3-rendered
+@acronym{HTML} in the Gnus article buffers will use @code{browse-url} to
+follow the link.
+
+
+@node IMAP
+@section IMAP
+@cindex nnimap
+@cindex @acronym{IMAP}
+
+@acronym{IMAP} is a network protocol for reading mail (or news, or @dots{}),
+think of it as a modernized @acronym{NNTP}. Connecting to a @acronym{IMAP}
+server is much similar to connecting to a news server, you just
+specify the network address of the server.
+
+@acronym{IMAP} has two properties. First, @acronym{IMAP} can do
+everything that @acronym{POP} can, it can hence be viewed as a
+@acronym{POP++}. Secondly, @acronym{IMAP} is a mail storage protocol,
+similar to @acronym{NNTP} being a news storage protocol---however,
+@acronym{IMAP} offers more features than @acronym{NNTP} because news
+is more or less read-only whereas mail is read-write.
+
+If you want to use @acronym{IMAP} as a @acronym{POP++}, use an imap
+entry in @code{mail-sources}. With this, Gnus will fetch mails from
+the @acronym{IMAP} server and store them on the local disk. This is
+not the usage described in this section---@xref{Mail Sources}.
+
+If you want to use @acronym{IMAP} as a mail storage protocol, use an nnimap
+entry in @code{gnus-secondary-select-methods}. With this, Gnus will
+manipulate mails stored on the @acronym{IMAP} server. This is the kind of
+usage explained in this section.
+
+A server configuration in @file{~/.gnus.el} with a few @acronym{IMAP}
+servers might look something like the following. (Note that for
+@acronym{TLS}/@acronym{SSL}, you need external programs and libraries,
+see below.)
+
+@lisp
+(setq gnus-secondary-select-methods
+ '((nnimap "simpleserver") ; @r{no special configuration}
+ ; @r{perhaps a ssh port forwarded server:}
+ (nnimap "dolk"
+ (nnimap-address "localhost")
+ (nnimap-server-port 1430))
+ ; @r{a UW server running on localhost}
+ (nnimap "barbar"
+ (nnimap-server-port 143)
+ (nnimap-address "localhost")
+ (nnimap-list-pattern ("INBOX" "mail/*")))
+ ; @r{anonymous public cyrus server:}
+ (nnimap "cyrus.andrew.cmu.edu"
+ (nnimap-authenticator anonymous)
+ (nnimap-list-pattern "archive.*")
+ (nnimap-stream network))
+ ; @r{a ssl server on a non-standard port:}
+ (nnimap "vic20"
+ (nnimap-address "vic20.somewhere.com")
+ (nnimap-server-port 9930)
+ (nnimap-stream ssl))))
+@end lisp
+
+After defining the new server, you can subscribe to groups on the
+server using normal Gnus commands such as @kbd{U} in the Group Buffer
+(@pxref{Subscription Commands}) or via the Server Buffer
+(@pxref{Server Buffer}).
+
+The following variables can be used to create a virtual @code{nnimap}
+server:
+
+@table @code
+
+@item nnimap-address
+@vindex nnimap-address
+
+The address of the remote @acronym{IMAP} server. Defaults to the virtual
+server name if not specified.
+
+@item nnimap-server-port
+@vindex nnimap-server-port
+Port on server to contact. Defaults to port 143, or 993 for @acronym{TLS}/@acronym{SSL}.
+
+Note that this should be an integer, example server specification:
+
+@lisp
+(nnimap "mail.server.com"
+ (nnimap-server-port 4711))
+@end lisp
+
+@item nnimap-list-pattern
+@vindex nnimap-list-pattern
+String or list of strings of mailboxes to limit available groups to.
+This is used when the server has very many mailboxes and you're only
+interested in a few---some servers export your home directory via
+@acronym{IMAP}, you'll probably want to limit the mailboxes to those in
+@file{~/Mail/*} then.
+
+The string can also be a cons of REFERENCE and the string as above, what
+REFERENCE is used for is server specific, but on the University of
+Washington server it's a directory that will be concatenated with the
+mailbox.
+
+Example server specification:
+
+@lisp
+(nnimap "mail.server.com"
+ (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*"
+ ("~friend/Mail/" . "list/*"))))
+@end lisp
+
+@item nnimap-stream
+@vindex nnimap-stream
+The type of stream used to connect to your server. By default, nnimap
+will detect and automatically use all of the below, with the exception
+of @acronym{TLS}/@acronym{SSL}. (@acronym{IMAP} over
+@acronym{TLS}/@acronym{SSL} is being replaced by STARTTLS, which can
+be automatically detected, but it's not widely deployed yet.)
+
+Example server specification:
+
+@lisp
+(nnimap "mail.server.com"
+ (nnimap-stream ssl))
+@end lisp
+
+Please note that the value of @code{nnimap-stream} is a symbol!
+
+@itemize @bullet
+@item
+@dfn{gssapi:} Connect with GSSAPI (usually Kerberos 5). Requires the
+@samp{gsasl} or @samp{imtest} program.
+@item
+@dfn{kerberos4:} Connect with Kerberos 4. Requires the @samp{imtest} program.
+@item
+@dfn{starttls:} Connect via the STARTTLS extension (similar to
+@acronym{TLS}/@acronym{SSL}). Requires the external library @samp{starttls.el} and program
+@samp{starttls}.
+@item
+@dfn{tls:} Connect through @acronym{TLS}. Requires GNUTLS (the program
+@samp{gnutls-cli}).
+@item
+@dfn{ssl:} Connect through @acronym{SSL}. Requires OpenSSL (the program
+@samp{openssl}) or SSLeay (@samp{s_client}).
+@item
+@dfn{shell:} Use a shell command to start @acronym{IMAP} connection.
+@item
+@dfn{network:} Plain, TCP/IP network connection.
+@end itemize
+
+@vindex imap-kerberos4-program
+The @samp{imtest} program is shipped with Cyrus IMAPD. If you're
+using @samp{imtest} from Cyrus IMAPD < 2.0.14 (which includes version
+1.5.x and 1.6.x) you need to frob @code{imap-process-connection-type}
+to make @code{imap.el} use a pty instead of a pipe when communicating
+with @samp{imtest}. You will then suffer from a line length
+restrictions on @acronym{IMAP} commands, which might make Gnus seem to hang
+indefinitely if you have many articles in a mailbox. The variable
+@code{imap-kerberos4-program} contain parameters to pass to the imtest
+program.
+
+For @acronym{TLS} connection, the @code{gnutls-cli} program from GNUTLS is
+needed. It is available from
+@uref{http://www.gnu.org/software/gnutls/}.
+
+@vindex imap-gssapi-program
+This parameter specifies a list of command lines that invoke a GSSAPI
+authenticated @acronym{IMAP} stream in a subshell. They are tried
+sequentially until a connection is made, or the list has been
+exhausted. By default, @samp{gsasl} from GNU SASL, available from
+@uref{http://www.gnu.org/software/gsasl/}, and the @samp{imtest}
+program from Cyrus IMAPD (see @code{imap-kerberos4-program}), are
+tried.
+
+@vindex imap-ssl-program
+For @acronym{SSL} connections, the OpenSSL program is available from
+@uref{http://www.openssl.org/}. OpenSSL was formerly known as SSLeay,
+and nnimap support it too---although the most recent versions of
+SSLeay, 0.9.x, are known to have serious bugs making it
+useless. Earlier versions, especially 0.8.x, of SSLeay are known to
+work. The variable @code{imap-ssl-program} contain parameters to pass
+to OpenSSL/SSLeay.
+
+@vindex imap-shell-program
+@vindex imap-shell-host
+For @acronym{IMAP} connections using the @code{shell} stream, the variable
+@code{imap-shell-program} specify what program to call.
+
+@item nnimap-authenticator
+@vindex nnimap-authenticator
+
+The authenticator used to connect to the server. By default, nnimap
+will use the most secure authenticator your server is capable of.
+
+Example server specification:
+
+@lisp
+(nnimap "mail.server.com"
+ (nnimap-authenticator anonymous))
+@end lisp
+
+Please note that the value of @code{nnimap-authenticator} is a symbol!
+
+@itemize @bullet
+@item
+@dfn{gssapi:} GSSAPI (usually kerberos 5) authentication. Requires
+external program @code{gsasl} or @code{imtest}.
+@item
+@dfn{kerberos4:} Kerberos 4 authentication. Requires external program
+@code{imtest}.
+@item
+@dfn{digest-md5:} Encrypted username/password via DIGEST-MD5. Requires
+external library @code{digest-md5.el}.
+@item
+@dfn{cram-md5:} Encrypted username/password via CRAM-MD5.
+@item
+@dfn{login:} Plain-text username/password via LOGIN.
+@item
+@dfn{anonymous:} Login as ``anonymous'', supplying your email address as password.
+@end itemize
+
+@item nnimap-expunge-on-close
+@cindex expunging
+@vindex nnimap-expunge-on-close
+Unlike Parmenides the @acronym{IMAP} designers have decided things that
+don't exist actually do exist. More specifically, @acronym{IMAP} has
+this concept of marking articles @code{Deleted} which doesn't actually
+delete them, and this (marking them @code{Deleted}, that is) is what
+nnimap does when you delete an article in Gnus (with @kbd{B DEL} or
+similar).
+
+Since the articles aren't really removed when we mark them with the
+@code{Deleted} flag we'll need a way to actually delete them. Feel like
+running in circles yet?
+
+Traditionally, nnimap has removed all articles marked as @code{Deleted}
+when closing a mailbox but this is now configurable by this server
+variable.
+
+The possible options are:
+
+@table @code
+
+@item always
+The default behavior, delete all articles marked as ``Deleted'' when
+closing a mailbox.
+@item never
+Never actually delete articles. Currently there is no way of showing
+the articles marked for deletion in nnimap, but other @acronym{IMAP} clients
+may allow you to do this. If you ever want to run the EXPUNGE command
+manually, @xref{Expunging mailboxes}.
+@item ask
+When closing mailboxes, nnimap will ask if you wish to expunge deleted
+articles or not.
+
+@end table
+
+@item nnimap-importantize-dormant
+@vindex nnimap-importantize-dormant
+
+If non-@code{nil} (the default), marks dormant articles as ticked (as
+well), for other @acronym{IMAP} clients. Within Gnus, dormant articles will
+naturally still (only) be marked as dormant. This is to make dormant
+articles stand out, just like ticked articles, in other @acronym{IMAP}
+clients. (In other words, Gnus has two ``Tick'' marks and @acronym{IMAP}
+has only one.)
+
+Probably the only reason for frobbing this would be if you're trying
+enable per-user persistent dormant flags, using something like:
+
+@lisp
+(setcdr (assq 'dormant nnimap-mark-to-flag-alist)
+ (format "gnus-dormant-%s" (user-login-name)))
+(setcdr (assq 'dormant nnimap-mark-to-predicate-alist)
+ (format "KEYWORD gnus-dormant-%s" (user-login-name)))
+@end lisp
+
+In this case, you would not want the per-user dormant flag showing up
+as ticked for other users.
+
+@item nnimap-expunge-search-string
+@cindex expunging
+@vindex nnimap-expunge-search-string
+@cindex expiring @acronym{IMAP} mail
+
+This variable contain the @acronym{IMAP} search command sent to server when
+searching for articles eligible for expiring. The default is
+@code{"UID %s NOT SINCE %s"}, where the first @code{%s} is replaced by
+UID set and the second @code{%s} is replaced by a date.
+
+Probably the only useful value to change this to is
+@code{"UID %s NOT SENTSINCE %s"}, which makes nnimap use the Date: in
+messages instead of the internal article date. See section 6.4.4 of
+RFC 2060 for more information on valid strings.
+
+However, if @code{nnimap-search-uids-not-since-is-evil}
+is true, this variable has no effect since the search logic
+is reversed, as described below.
+
+@item nnimap-authinfo-file
+@vindex nnimap-authinfo-file
+
+A file containing credentials used to log in on servers. The format is
+(almost) the same as the @code{ftp} @file{~/.netrc} file. See the
+variable @code{nntp-authinfo-file} for exact syntax; also see
+@ref{NNTP}. An example of an .authinfo line for an IMAP server, is:
+
+@example
+machine students.uio.no login larsi password geheimnis port imap
+@end example
+
+Note that it should be @code{port imap}, or @code{port 143}, if you
+use a @code{nnimap-stream} of @code{tls} or @code{ssl}, even if the
+actual port number used is port 993 for secured IMAP. For
+convenience, Gnus will accept @code{port imaps} as a synonym of
+@code{port imap}.
+
+@item nnimap-need-unselect-to-notice-new-mail
+@vindex nnimap-need-unselect-to-notice-new-mail
+
+Unselect mailboxes before looking for new mail in them. Some servers
+seem to need this under some circumstances; it was reported that
+Courier 1.7.1 did.
+
+@item nnimap-nov-is-evil
+@vindex nnimap-nov-is-evil
+@cindex Courier @acronym{IMAP} server
+@cindex @acronym{NOV}
+
+Never generate or use a local @acronym{NOV} database. Defaults to the
+value of @code{gnus-agent}.
+
+Using a @acronym{NOV} database usually makes header fetching much
+faster, but it uses the @code{UID SEARCH UID} command, which is very
+slow on some servers (notably some versions of Courier). Since the Gnus
+Agent caches the information in the @acronym{NOV} database without using
+the slow command, this variable defaults to true if the Agent is in use,
+and false otherwise.
+
+@item nnimap-search-uids-not-since-is-evil
+@vindex nnimap-search-uids-not-since-is-evil
+@cindex Courier @acronym{IMAP} server
+@cindex expiring @acronym{IMAP} mail
+
+Avoid the @code{UID SEARCH UID @var{message numbers} NOT SINCE
+@var{date}} command, which is slow on some @acronym{IMAP} servers
+(notably, some versions of Courier). Instead, use @code{UID SEARCH SINCE
+@var{date}} and prune the list of expirable articles within Gnus.
+
+When Gnus expires your mail (@pxref{Expiring Mail}), it starts with a
+list of expirable articles and asks the IMAP server questions like ``Of
+these articles, which ones are older than a week?'' While this seems
+like a perfectly reasonable question, some IMAP servers take a long time
+to answer it, since they seemingly go looking into every old article to
+see if it is one of the expirable ones. Curiously, the question ``Of
+@emph{all} articles, which ones are newer than a week?'' seems to be
+much faster to answer, so setting this variable causes Gnus to ask this
+question and figure out the answer to the real question itself.
+
+This problem can really sneak up on you: when you first configure Gnus,
+everything works fine, but once you accumulate a couple thousand
+messages, you start cursing Gnus for being so slow. On the other hand,
+if you get a lot of email within a week, setting this variable will
+cause a lot of network traffic between Gnus and the IMAP server.
+
+@end table
+
+@menu
+* Splitting in IMAP:: Splitting mail with nnimap.
+* Expiring in IMAP:: Expiring mail with nnimap.
+* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox.
+* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button.
+* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus.
+* Debugging IMAP:: What to do when things don't work.
+@end menu
+
+
+
+@node Splitting in IMAP
+@subsection Splitting in IMAP
+@cindex splitting imap mail
+
+Splitting is something Gnus users have loved and used for years, and now
+the rest of the world is catching up. Yeah, dream on, not many
+@acronym{IMAP} servers have server side splitting and those that have
+splitting seem to use some non-standard protocol. This means that
+@acronym{IMAP} support for Gnus has to do its own splitting.
+
+And it does.
+
+(Incidentally, people seem to have been dreaming on, and Sieve has
+gaining a market share and is supported by several IMAP servers.
+Fortunately, Gnus support it too, @xref{Sieve Commands}.)
+
+Here are the variables of interest:
+
+@table @code
+
+@item nnimap-split-crosspost
+@cindex splitting, crosspost
+@cindex crosspost
+@vindex nnimap-split-crosspost
+
+If non-@code{nil}, do crossposting if several split methods match the
+mail. If @code{nil}, the first match in @code{nnimap-split-rule}
+found will be used.
+
+Nnmail equivalent: @code{nnmail-crosspost}.
+
+@item nnimap-split-inbox
+@cindex splitting, inbox
+@cindex inbox
+@vindex nnimap-split-inbox
+
+A string or a list of strings that gives the name(s) of @acronym{IMAP}
+mailboxes to split from. Defaults to @code{nil}, which means that
+splitting is disabled!
+
+@lisp
+(setq nnimap-split-inbox
+ '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap"))
+@end lisp
+
+No nnmail equivalent.
+
+@item nnimap-split-rule
+@cindex splitting, rules
+@vindex nnimap-split-rule
+
+New mail found in @code{nnimap-split-inbox} will be split according to
+this variable.
+
+This variable contains a list of lists, where the first element in the
+sublist gives the name of the @acronym{IMAP} mailbox to move articles
+matching the regexp in the second element in the sublist. Got that?
+Neither did I, we need examples.
+
+@lisp
+(setq nnimap-split-rule
+ '(("INBOX.nnimap"
+ "^Sender: owner-nnimap@@vic20.globalcom.se")
+ ("INBOX.junk" "^Subject:.*MAKE MONEY")
+ ("INBOX.private" "")))
+@end lisp
+
+This will put all articles from the nnimap mailing list into mailbox
+INBOX.nnimap, all articles containing MAKE MONEY in the Subject: line
+into INBOX.junk and everything else in INBOX.private.
+
+The first string may contain @samp{\\1} forms, like the ones used by
+replace-match to insert sub-expressions from the matched text. For
+instance:
+
+@lisp
+("INBOX.lists.\\1" "^Sender: owner-\\([a-z-]+\\)@@")
+@end lisp
+
+The first element can also be the symbol @code{junk} to indicate that
+matching messages should simply be deleted. Use with care.
+
+The second element can also be a function. In that case, it will be
+called with the first element of the rule as the argument, in a buffer
+containing the headers of the article. It should return a
+non-@code{nil} value if it thinks that the mail belongs in that group.
+
+Nnmail users might recollect that the last regexp had to be empty to
+match all articles (like in the example above). This is not required in
+nnimap. Articles not matching any of the regexps will not be moved out
+of your inbox. (This might affect performance if you keep lots of
+unread articles in your inbox, since the splitting code would go over
+them every time you fetch new mail.)
+
+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''.
+
+This variable can also have a function as its value, the function will
+be called with the headers narrowed and should return a group where it
+thinks the article should be split to. See @code{nnimap-split-fancy}.
+
+The splitting code tries to create mailboxes if it needs to.
+
+To allow for different split rules on different virtual servers, and
+even different split rules in different inboxes on the same server,
+the syntax of this variable have been extended along the lines of:
+
+@lisp
+(setq nnimap-split-rule
+ '(("my1server" (".*" (("ding" "ding@@gnus.org")
+ ("junk" "From:.*Simon"))))
+ ("my2server" ("INBOX" nnimap-split-fancy))
+ ("my[34]server" (".*" (("private" "To:.*Simon")
+ ("junk" my-junk-func))))))
+@end lisp
+
+The virtual server name is in fact a regexp, so that the same rules
+may apply to several servers. In the example, the servers
+@code{my3server} and @code{my4server} both use the same rules.
+Similarly, the inbox string is also a regexp. The actual splitting
+rules are as before, either a function, or a list with group/regexp or
+group/function elements.
+
+Nnmail equivalent: @code{nnmail-split-methods}.
+
+@item nnimap-split-predicate
+@cindex splitting
+@vindex nnimap-split-predicate
+
+Mail matching this predicate in @code{nnimap-split-inbox} will be
+split, it is a string and the default is @samp{UNSEEN UNDELETED}.
+
+This might be useful if you use another @acronym{IMAP} client to read mail in
+your inbox but would like Gnus to split all articles in the inbox
+regardless of readedness. Then you might change this to
+@samp{UNDELETED}.
+
+@item nnimap-split-fancy
+@cindex splitting, fancy
+@findex nnimap-split-fancy
+@vindex nnimap-split-fancy
+
+It's possible to set @code{nnimap-split-rule} to
+@code{nnmail-split-fancy} if you want to use fancy
+splitting. @xref{Fancy Mail Splitting}.
+
+However, to be able to have different fancy split rules for nnmail and
+nnimap back ends you can set @code{nnimap-split-rule} to
+@code{nnimap-split-fancy} and define the nnimap specific fancy split
+rule in @code{nnimap-split-fancy}.
+
+Example:
+
+@lisp
+(setq nnimap-split-rule 'nnimap-split-fancy
+ nnimap-split-fancy ...)
+@end lisp
+
+Nnmail equivalent: @code{nnmail-split-fancy}.
+
+@item nnimap-split-download-body
+@findex nnimap-split-download-body
+@vindex nnimap-split-download-body
+
+Set to non-@code{nil} to download entire articles during splitting.
+This is generally not required, and will slow things down
+considerably. You may need it if you want to use an advanced
+splitting function that analyzes the body to split the article.
+
+@end table
+
+@node Expiring in IMAP
+@subsection Expiring in IMAP
+@cindex expiring @acronym{IMAP} mail
+
+Even though @code{nnimap} is not a proper @code{nnmail} derived back
+end, it supports most features in regular expiring (@pxref{Expiring
+Mail}). Unlike splitting in @acronym{IMAP} (@pxref{Splitting in
+IMAP}) it does not clone the @code{nnmail} variables (i.e., creating
+@var{nnimap-expiry-wait}) but reuse the @code{nnmail} variables. What
+follows below are the variables used by the @code{nnimap} expiry
+process.
+
+A note on how the expire mark is stored on the @acronym{IMAP} server is
+appropriate here as well. The expire mark is translated into a
+@code{imap} client specific mark, @code{gnus-expire}, and stored on the
+message. This means that likely only Gnus will understand and treat
+the @code{gnus-expire} mark properly, although other clients may allow
+you to view client specific flags on the message. It also means that
+your server must support permanent storage of client specific flags on
+messages. Most do, fortunately.
+
+If expiring @acronym{IMAP} mail seems very slow, try setting the server
+variable @code{nnimap-search-uids-not-since-is-evil}.
+
+@table @code
+
+@item nnmail-expiry-wait
+@item nnmail-expiry-wait-function
+
+These variables are fully supported. The expire value can be a
+number, the symbol @code{immediate} or @code{never}.
+
+@item nnmail-expiry-target
+
+This variable is supported, and internally implemented by calling the
+@code{nnmail} functions that handle this. It contains an optimization
+that if the destination is a @acronym{IMAP} group on the same server, the
+article is copied instead of appended (that is, uploaded again).
+
+@end table
+
+@node Editing IMAP ACLs
+@subsection Editing IMAP ACLs
+@cindex editing imap acls
+@cindex Access Control Lists
+@cindex Editing @acronym{IMAP} ACLs
+@kindex G l (Group)
+@findex gnus-group-nnimap-edit-acl
+
+ACL stands for Access Control List. ACLs are used in @acronym{IMAP} for
+limiting (or enabling) other users access to your mail boxes. Not all
+@acronym{IMAP} servers support this, this function will give an error if it
+doesn't.
+
+To edit an ACL for a mailbox, type @kbd{G l}
+(@code{gnus-group-edit-nnimap-acl}) and you'll be presented with an ACL
+editing window with detailed instructions.
+
+Some possible uses:
+
+@itemize @bullet
+@item
+Giving ``anyone'' the ``lrs'' rights (lookup, read, keep seen/unseen flags)
+on your mailing list mailboxes enables other users on the same server to
+follow the list without subscribing to it.
+@item
+At least with the Cyrus server, you are required to give the user
+``anyone'' posting ("p") capabilities to have ``plussing'' work (that is,
+mail sent to user+mailbox@@domain ending up in the @acronym{IMAP} mailbox
+INBOX.mailbox).
+@end itemize
+
+@node Expunging mailboxes
+@subsection Expunging mailboxes
+@cindex expunging
+
+@cindex expunge
+@cindex manual expunging
+@kindex G x (Group)
+@findex gnus-group-nnimap-expunge
+
+If you're using the @code{never} setting of @code{nnimap-expunge-on-close},
+you may want the option of expunging all deleted articles in a mailbox
+manually. This is exactly what @kbd{G x} does.
+
+Currently there is no way of showing deleted articles, you can just
+delete them.
+
+@node A note on namespaces
+@subsection A note on namespaces
+@cindex IMAP namespace
+@cindex namespaces
+
+The @acronym{IMAP} protocol has a concept called namespaces, described
+by the following text in the RFC2060:
+
+@display
+5.1.2. Mailbox Namespace Naming Convention
+
+ By convention, the first hierarchical element of any mailbox name
+ which begins with "#" identifies the "namespace" of the remainder of
+ the name. This makes it possible to disambiguate between different
+ types of mailbox stores, each of which have their own namespaces.
+
+ For example, implementations which offer access to USENET
+ newsgroups MAY use the "#news" namespace to partition the USENET
+ newsgroup namespace from that of other mailboxes. Thus, the
+ comp.mail.misc newsgroup would have an mailbox name of
+ "#news.comp.mail.misc", and the name "comp.mail.misc" could refer
+ to a different object (e.g. a user's private mailbox).
+@end display
+
+While there is nothing in this text that warrants concern for the
+@acronym{IMAP} implementation in Gnus, some servers use namespace
+prefixes in a way that does not work with how Gnus uses mailbox names.
+
+Specifically, University of Washington's @acronym{IMAP} server uses
+mailbox names like @code{#driver.mbx/read-mail} which are valid only
+in the @sc{create} and @sc{append} commands. After the mailbox is
+created (or a messages is appended to a mailbox), it must be accessed
+without the namespace prefix, i.e. @code{read-mail}. Since Gnus do
+not make it possible for the user to guarantee that user entered
+mailbox names will only be used with the CREATE and APPEND commands,
+you should simply not use the namespace prefixed mailbox names in
+Gnus.
+
+See the UoW IMAPD documentation for the @code{#driver.*/} prefix
+for more information on how to use the prefixes. They are a power
+tool and should be used only if you are sure what the effects are.
+
+@node Debugging IMAP
+@subsection Debugging IMAP
+@cindex IMAP debugging
+@cindex protocol dump (IMAP)
+
+@acronym{IMAP} is a complex protocol, more so than @acronym{NNTP} or
+@acronym{POP3}. Implementation bugs are not unlikely, and we do our
+best to fix them right away. If you encounter odd behavior, chances
+are that either the server or Gnus is buggy.
+
+If you are familiar with network protocols in general, you will
+probably be able to extract some clues from the protocol dump of the
+exchanges between Gnus and the server. Even if you are not familiar
+with network protocols, when you include the protocol dump in
+@acronym{IMAP}-related bug reports you are helping us with data
+critical to solving the problem. Therefore, we strongly encourage you
+to include the protocol dump when reporting IMAP bugs in Gnus.
+
+
+@vindex imap-log
+Because the protocol dump, when enabled, generates lots of data, it is
+disabled by default. You can enable it by setting @code{imap-log} as
+follows:
+
+@lisp
+(setq imap-log t)
+@end lisp
+
+This instructs the @code{imap.el} package to log any exchanges with
+the server. The log is stored in the buffer @samp{*imap-log*}. Look
+for error messages, which sometimes are tagged with the keyword
+@code{BAD}---but when submitting a bug, make sure to include all the
+data.
+
+@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''.
+* 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
+back end 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 @acronym{NOV} files if they are present.
+
+@code{nndir} is a ``read-only'' back end---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} back end (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-include-files
+@vindex nneething-include-files
+Regexp saying what files to include in the group. If this variable is
+non-@code{nil}, only files matching this regexp will be included.
+
+@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.
+
+@cindex rnews batch files
+@item rnews
+The rnews batch transport format.
+
+@item nsmail
+Netscape mail boxes.
+
+@item mime-parts
+@acronym{MIME} multipart messages.
+
+@item standard-digest
+The standard (RFC 1153) digest format.
+
+@item mime-digest
+A @acronym{MIME} digest of messages.
+
+@item lanl-gov-announce
+Announcement messages from LANL Gov Announce.
+
+@cindex forwarded messages
+@item rfc822-forward
+A message forwarded according to RFC822.
+
+@item outlook
+The Outlook mail box.
+
+@item oe-dbx
+The Outlook Express dbx mail box.
+
+@item exim-bounce
+A bounce message from the Exim MTA.
+
+@item forward
+A message forwarded according to informal rules.
+
+@item rfc934
+An RFC934-forwarded message.
+
+@item mailman
+A mailman digest.
+
+@item clari-briefs
+A digest of Clarinet brief news items.
+
+@item slack-digest
+Non-standard digest format---matches most things, but does it badly.
+
+@item mail-in-mail
+The last resort.
+@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 back end, @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{standard-digest},
+@code{slack-digest}, @code{clari-briefs}, @code{nsmail}, @code{outlook},
+@code{oe-dbx}, @code{mailman}, and @code{mail-in-mail} 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. To do more
+complicated things that cannot be dealt with a simple regexp, you can
+use @code{article-begin-function} instead of this.
+
+@item article-begin-function
+If present, this should be a function that moves point to the beginning
+of each article. This setting overrides @code{article-begin}.
+
+@item head-begin
+If present, this should be a regexp that matches the head of the
+article. To do more complicated things that cannot be dealt with a
+simple regexp, you can use @code{head-begin-function} instead of this.
+
+@item head-begin-function
+If present, this should be a function that moves point to the head of
+the article. This setting overrides @code{head-begin}.
+
+@item head-end
+This should match the end of the head of the article. It defaults to
+@samp{^$}---the empty line.
+
+@item body-begin
+This should match the beginning of the body of the article. It defaults
+to @samp{^\n}. To do more complicated things that cannot be dealt with
+a simple regexp, you can use @code{body-begin-function} instead of this.
+
+@item body-begin-function
+If present, this function should move point to the beginning of the body
+of the article. This setting overrides @code{body-begin}.
+
+@item body-end
+If present, this should match the end of the body of the article. To do
+more complicated things that cannot be dealt with a simple regexp, you
+can use @code{body-end-function} instead of this.
+
+@item body-end-function
+If present, this function should move point to the end of the body of
+the article. This setting overrides @code{body-end}.
+
+@item file-begin
+If present, this should match the beginning of the file. All text
+before this regexp will be totally ignored.
+
+@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.
+
+@item generate-article-function
+If present, this function is called to generate an entire article that
+Gnus can understand. It is called with the article number as a
+parameter when requesting all articles.
+
+@item dissection-function
+If present, this function is called to dissect a document by itself,
+overriding @code{first-article}, @code{article-begin},
+@code{article-begin-function}, @code{head-begin},
+@code{head-begin-function}, @code{head-end}, @code{body-begin},
+@code{body-begin-function}, @code{body-end}, @code{body-end-function},
+@code{file-begin}, and @code{file-end}.
+
+@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-@var{type}-type-p} is called for a given type @var{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 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} back end 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 back end 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 SOUP Groups
+@cindex nnsoup
+
+@code{nnsoup} is the back end 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 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} back end provides the interface.
+
+Note that you can't read anything from this back end---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{To} 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}.
+@end table
+
+@end table
+
+Here's an example:
+
+@lisp
+(setq gnus-post-method
+ '(nngateway
+ "mail2news@@replay.com"
+ (nngateway-header-transformation
+ nngateway-mail2news-header-transformation)))
+@end lisp
+
+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.). To create an empty virtual group, run
+@kbd{G V} (@code{gnus-group-make-empty-virtual}) in the group buffer
+and edit the method regexp with @kbd{M-e}
+(@code{gnus-group-edit-group-method})
+
+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} variable is non-@code{nil} (which
+is the default), @code{nnvirtual} will always scan groups for unread
+articles when entering a virtual group. If this variable is @code{nil}
+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 back end of the component group the article comes from
+whether it is a news or mail back end. However, when you do a @kbd{^},
+there is typically no sure way for the component back end to know this,
+and in that case @code{nnvirtual} tells Gnus that the article came from a
+not-news back end. (Just to be on the safe side.)
+
+@kbd{C-c C-n} in the message buffer will insert the @code{Newsgroups}
+line from the article you respond to in these cases.
+
+@code{nnvirtual} groups do not inherit anything but articles and marks
+from component groups---group parameters, for instance, are not
+inherited.
+
+
+@node Kibozed Groups
+@subsection Kibozed Groups
+@cindex nnkiboze
+@cindex kibozing
+
+@dfn{Kibozing} is defined by the @acronym{OED} as ``grepping through
+(parts of) the news feed''. @code{nnkiboze} is a back end that will
+do this for you. Oh joy! Now you can grind any @acronym{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
+@acronym{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/kiboze/} by default.
+One contains the @acronym{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 @acronym{NOV} lines removed from the @acronym{NOV} file.
+
+
+@node Email Based Diary
+@section Email Based Diary
+@cindex diary
+@cindex email based diary
+@cindex calendar
+
+This section describes a special mail back end called @code{nndiary},
+and its companion library @code{gnus-diary}. It is ``special'' in the
+sense that it is not meant to be one of the standard alternatives for
+reading mail with Gnus. See @ref{Choosing a Mail Back End} for that.
+Instead, it is used to treat @emph{some} of your mails in a special way,
+namely, as event reminders.
+
+Here is a typical scenario:
+
+@itemize @bullet
+@item
+You've got a date with Andy Mc Dowell or Bruce Willis (select according
+to your sexual preference) in one month. You don't want to forget it.
+@item
+So you send a ``reminder'' message (actually, a diary one) to yourself.
+@item
+You forget all about it and keep on getting and reading new mail, as usual.
+@item
+From time to time, as you type `g' in the group buffer and as the date
+is getting closer, the message will pop up again to remind you of your
+appointment, just as if it were new and unread.
+@item
+Read your ``new'' messages, this one included, and start dreaming again
+of the night you're gonna have.
+@item
+Once the date is over (you actually fell asleep just after dinner), the
+message will be automatically deleted if it is marked as expirable.
+@end itemize
+
+The Gnus Diary back end has the ability to handle regular appointments
+(that wouldn't ever be deleted) as well as punctual ones, operates as a
+real mail back end and is configurable in many ways. All of this is
+explained in the sections below.
+
+@menu
+* The NNDiary Back End:: Basic setup and usage.
+* The Gnus Diary Library:: Utility toolkit on top of nndiary.
+* Sending or Not Sending:: A final note on sending diary messages.
+@end menu
+
+
+@node The NNDiary Back End
+@subsection The NNDiary Back End
+@cindex nndiary
+@cindex the nndiary back end
+
+@code{nndiary} is a back end very similar to @code{nnml} (@pxref{Mail
+Spool}). Actually, it could appear as a mix of @code{nnml} and
+@code{nndraft}. If you know @code{nnml}, you're already familiar with
+the message storing scheme of @code{nndiary}: one file per message, one
+directory per group.
+
+ Before anything, there is one requirement to be able to run
+@code{nndiary} properly: you @emph{must} use the group timestamp feature
+of Gnus. This adds a timestamp to each group's parameters. @ref{Group
+Timestamp} to see how it's done.
+
+@menu
+* Diary Messages:: What makes a message valid for nndiary.
+* Running NNDiary:: NNDiary has two modes of operation.
+* Customizing NNDiary:: Bells and whistles.
+@end menu
+
+@node Diary Messages
+@subsubsection Diary Messages
+@cindex nndiary messages
+@cindex nndiary mails
+
+@code{nndiary} messages are just normal ones, except for the mandatory
+presence of 7 special headers. These headers are of the form
+@code{X-Diary-<something>}, @code{<something>} being one of
+@code{Minute}, @code{Hour}, @code{Dom}, @code{Month}, @code{Year},
+@code{Time-Zone} and @code{Dow}. @code{Dom} means ``Day of Month'', and
+@code{dow} means ``Day of Week''. These headers actually behave like
+crontab specifications and define the event date(s):
+
+@itemize @bullet
+@item
+For all headers except the @code{Time-Zone} one, a header value is
+either a star (meaning all possible values), or a list of fields
+(separated by a comma).
+@item
+A field is either an integer, or a range.
+@item
+A range is two integers separated by a dash.
+@item
+Possible integer values are 0--59 for @code{Minute}, 0--23 for
+@code{Hour}, 1--31 for @code{Dom}, 1--12 for @code{Month}, above 1971
+for @code{Year} and 0--6 for @code{Dow} (0 meaning Sunday).
+@item
+As a special case, a star in either @code{Dom} or @code{Dow} doesn't
+mean ``all possible values'', but ``use only the other field''. Note
+that if both are star'ed, the use of either one gives the same result.
+@item
+The @code{Time-Zone} header is special in that it can only have one
+value (@code{GMT}, for instance). A star doesn't mean ``all possible
+values'' (because it makes no sense), but ``the current local time
+zone''. Most of the time, you'll be using a star here. However, for a
+list of available time zone values, see the variable
+@code{nndiary-headers}.
+@end itemize
+
+As a concrete example, here are the diary headers to add to your message
+for specifying ``Each Monday and each 1st of month, at 12:00, 20:00,
+21:00, 22:00, 23:00 and 24:00, from 1999 to 2010'' (I'll let you find
+what to do then):
+
+@example
+X-Diary-Minute: 0
+X-Diary-Hour: 12, 20-24
+X-Diary-Dom: 1
+X-Diary-Month: *
+X-Diary-Year: 1999-2010
+X-Diary-Dow: 1
+X-Diary-Time-Zone: *
+@end example
+
+@node Running NNDiary
+@subsubsection Running NNDiary
+@cindex running nndiary
+@cindex nndiary operation modes
+
+@code{nndiary} has two modes of operation: ``traditional'' (the default)
+and ``autonomous''. In traditional mode, @code{nndiary} does not get new
+mail by itself. You have to move (@kbd{B m}) or copy (@kbd{B c}) mails
+from your primary mail back end to nndiary groups in order to handle them
+as diary messages. In autonomous mode, @code{nndiary} retrieves its own
+mail and handles it independently from your primary mail back end.
+
+One should note that Gnus is not inherently designed to allow several
+``master'' mail back ends at the same time. However, this does make
+sense with @code{nndiary}: you really want to send and receive diary
+messages to your diary groups directly. So, @code{nndiary} supports
+being sort of a ``second primary mail back end'' (to my knowledge, it is
+the only back end offering this feature). However, there is a limitation
+(which I hope to fix some day): respooling doesn't work in autonomous
+mode.
+
+In order to use @code{nndiary} in autonomous mode, you have several
+things to do:
+
+@itemize @bullet
+@item
+Allow @code{nndiary} to retrieve new mail by itself. Put the following
+line in your @file{~/.gnus.el} file:
+
+@lisp
+(setq nndiary-get-new-mail t)
+@end lisp
+@item
+You must arrange for diary messages (those containing @code{X-Diary-*}
+headers) to be split in a private folder @emph{before} Gnus treat them.
+Again, this is needed because Gnus cannot (yet ?) properly handle
+multiple primary mail back ends. Getting those messages from a separate
+source will compensate this misfeature to some extent.
+
+As an example, here's my procmailrc entry to store diary files in
+@file{~/.nndiary} (the default @code{nndiary} mail source file):
+
+@example
+:0 HD :
+* ^X-Diary
+.nndiary
+@end example
+@end itemize
+
+Once this is done, you might want to customize the following two options
+that affect the diary mail retrieval and splitting processes:
+
+@defvar nndiary-mail-sources
+This is the diary-specific replacement for the standard
+@code{mail-sources} variable. It obeys the same syntax, and defaults to
+@code{(file :path "~/.nndiary")}.
+@end defvar
+
+@defvar nndiary-split-methods
+This is the diary-specific replacement for the standard
+@code{nnmail-split-methods} variable. It obeys the same syntax.
+@end defvar
+
+ Finally, you may add a permanent @code{nndiary} virtual server
+(something like @code{(nndiary "diary")} should do) to your
+@code{gnus-secondary-select-methods}.
+
+ Hopefully, almost everything (see the TODO section in
+@file{nndiary.el}) will work as expected when you restart Gnus: in
+autonomous mode, typing @kbd{g} and @kbd{M-g} in the group buffer, will
+also get your new diary mails and split them according to your
+diary-specific rules, @kbd{F} will find your new diary groups etc.
+
+@node Customizing NNDiary
+@subsubsection Customizing NNDiary
+@cindex customizing nndiary
+@cindex nndiary customization
+
+Now that @code{nndiary} is up and running, it's time to customize it.
+The custom group is called @code{nndiary} (no, really ?!). You should
+browse it to figure out which options you'd like to tweak. The following
+two variables are probably the only ones you will want to change:
+
+@defvar nndiary-reminders
+This is the list of times when you want to be reminded of your
+appointments (e.g. 3 weeks before, then 2 days before, then 1 hour
+before and that's it). Remember that ``being reminded'' means that the
+diary message will pop up as brand new and unread again when you get new
+mail.
+@end defvar
+
+@defvar nndiary-week-starts-on-monday
+Rather self-explanatory. Otherwise, Sunday is assumed (this is the
+default).
+@end defvar
+
+
+@node The Gnus Diary Library
+@subsection The Gnus Diary Library
+@cindex gnus-diary
+@cindex the gnus diary library
+
+Using @code{nndiary} manually (I mean, writing the headers by hand and
+so on) would be rather boring. Fortunately, there is a library called
+@code{gnus-diary} written on top of @code{nndiary}, that does many
+useful things for you.
+
+ In order to use it, add the following line to your @file{~/.gnus.el} file:
+
+@lisp
+(require 'gnus-diary)
+@end lisp
+
+ Also, you shouldn't use any @code{gnus-user-format-function-[d|D]}
+(@pxref{Summary Buffer Lines}). @code{gnus-diary} provides both of these
+(sorry if you used them before).
+
+
+@menu
+* Diary Summary Line Format:: A nicer summary buffer line format.
+* Diary Articles Sorting:: A nicer way to sort messages.
+* Diary Headers Generation:: Not doing it manually.
+* Diary Group Parameters:: Not handling them manually.
+@end menu
+
+@node Diary Summary Line Format
+@subsubsection Diary Summary Line Format
+@cindex diary summary buffer line
+@cindex diary summary line format
+
+Displaying diary messages in standard summary line format (usually
+something like @samp{From Joe: Subject}) is pretty useless. Most of
+the time, you're the one who wrote the message, and you mostly want to
+see the event's date.
+
+ @code{gnus-diary} provides two supplemental user formats to be used in
+summary line formats. @code{D} corresponds to a formatted time string
+for the next occurrence of the event (e.g. ``Sat, Sep 22 01, 12:00''),
+while @code{d} corresponds to an approximative remaining time until the
+next occurrence of the event (e.g. ``in 6 months, 1 week'').
+
+ For example, here's how Joe's birthday is displayed in my
+@code{nndiary+diary:birthdays} summary buffer (note that the message is
+expirable, but will never be deleted, as it specifies a periodic event):
+
+@example
+ E Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week)
+@end example
+
+In order to get something like the above, you would normally add the
+following line to your diary groups'parameters:
+
+@lisp
+(gnus-summary-line-format "%U%R%z %uD: %(%s%) (%ud)\n")
+@end lisp
+
+However, @code{gnus-diary} does it automatically (@pxref{Diary Group
+Parameters}). You can however customize the provided summary line format
+with the following user options:
+
+@defvar gnus-diary-summary-line-format
+Defines the summary line format used for diary groups (@pxref{Summary
+Buffer Lines}). @code{gnus-diary} uses it to automatically update the
+diary groups'parameters.
+@end defvar
+
+@defvar gnus-diary-time-format
+Defines the format to display dates in diary summary buffers. This is
+used by the @code{D} user format. See the docstring for details.
+@end defvar
+
+@defvar gnus-diary-delay-format-function
+Defines the format function to use for displaying delays (remaining
+times) in diary summary buffers. This is used by the @code{d} user
+format. There are currently built-in functions for English and French;
+you can also define your own. See the docstring for details.
+@end defvar
+
+@node Diary Articles Sorting
+@subsubsection Diary Articles Sorting
+@cindex diary articles sorting
+@cindex diary summary lines sorting
+@findex gnus-summary-sort-by-schedule
+@findex gnus-thread-sort-by-schedule
+@findex gnus-article-sort-by-schedule
+
+@code{gnus-diary} provides new sorting functions (@pxref{Sorting the
+Summary Buffer} ) called @code{gnus-summary-sort-by-schedule},
+@code{gnus-thread-sort-by-schedule} and
+@code{gnus-article-sort-by-schedule}. These functions let you organize
+your diary summary buffers from the closest event to the farthest one.
+
+@code{gnus-diary} automatically installs
+@code{gnus-summary-sort-by-schedule} as a menu item in the summary
+buffer's ``sort'' menu, and the two others as the primary (hence
+default) sorting functions in the group parameters (@pxref{Diary Group
+Parameters}).
+
+@node Diary Headers Generation
+@subsubsection Diary Headers Generation
+@cindex diary headers generation
+@findex gnus-diary-check-message
+
+@code{gnus-diary} provides a function called
+@code{gnus-diary-check-message} to help you handle the @code{X-Diary-*}
+headers. This function ensures that the current message contains all the
+required diary headers, and prompts you for values or corrections if
+needed.
+
+ This function is hooked into the @code{nndiary} back end, so that
+moving or copying an article to a diary group will trigger it
+automatically. It is also bound to @kbd{C-c D c} in @code{message-mode}
+and @code{article-edit-mode} in order to ease the process of converting
+a usual mail to a diary one.
+
+ This function takes a prefix argument which will force prompting of
+all diary headers, regardless of their presence or validity. That way,
+you can very easily reschedule an already valid diary message, for
+instance.
+
+@node Diary Group Parameters
+@subsubsection Diary Group Parameters
+@cindex diary group parameters
+
+When you create a new diary group, or visit one, @code{gnus-diary}
+automatically checks your group parameters and if needed, sets the
+summary line format to the diary-specific value, installs the
+diary-specific sorting functions, and also adds the different
+@code{X-Diary-*} headers to the group's posting-style. It is then easier
+to send a diary message, because if you use @kbd{C-u a} or @kbd{C-u m}
+on a diary group to prepare a message, these headers will be inserted
+automatically (although not filled with proper values yet).
+
+@node Sending or Not Sending
+@subsection Sending or Not Sending
+
+Well, assuming you've read all of the above, here are two final notes on
+mail sending with @code{nndiary}:
+
+@itemize @bullet
+@item
+@code{nndiary} is a @emph{real} mail back end. You really send real diary
+messsages for real. This means for instance that you can give
+appointments to anybody (provided they use Gnus and @code{nndiary}) by
+sending the diary message to them as well.
+@item
+However, since @code{nndiary} also has a @code{request-post} method, you
+can also use @kbd{C-u a} instead of @kbd{C-u m} on a diary group and the
+message won't actually be sent; just stored locally in the group. This
+comes in very handy for private appointments.
+@end itemize
+
+@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.
+
+Setting up Gnus as an ``offline'' newsreader is quite simple. In
+fact, you don't even have to configure anything.
+
+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 Visuals:: Ways that the agent may effect your summary buffer.
+* Agent as Cache:: The Agent is a big cache too.
+* Agent Expiry:: How to make old articles go away.
+* Agent Regeneration:: How to recover from lost connections and other accidents.
+* Agent and IMAP:: How to use the Agent with @acronym{IMAP}.
+* 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.
+* Agent Caveats:: What you think it'll do and what it does.
+@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.
+
+You know that Gnus gives you all the opportunity you'd ever want for
+shooting yourself in the foot. Some people call it flexibility. Gnus
+is also customizable to a great extent, which means that the user has a
+say on how Gnus behaves. Other newsreaders might unconditionally shoot
+you in your foot, but with Gnus, you have a choice!
+
+Gnus is never really in plugged or unplugged state. Rather, it applies
+that state to each server individually. This means that some servers
+can be plugged while others can be unplugged. Additionally, some
+servers can be ignored by the Agent altogether (which means that
+they're kinda like plugged always).
+
+So when you unplug the Agent and then wonder why is Gnus opening a
+connection to the Net, the next step to do is to look whether all
+servers are agentized. If there is an unagentized server, you found
+the culprit.
+
+Another thing is the @dfn{offline} state. Sometimes, servers aren't
+reachable. When Gnus notices this, it asks you whether you want the
+server to be switched to offline state. If you say yes, then the
+server will behave somewhat as if it was unplugged, except that Gnus
+will ask you whether you want to switch it back online again.
+
+Let's take a typical Gnus session using the Agent.
+
+@itemize @bullet
+
+@item
+@findex gnus-unplugged
+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} and use @kbd{g} to check for new mail
+as usual. To check for new mail in unplugged mode (@pxref{Mail
+Source Specifiers}).
+
+@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{g} to check if there are any new news and then @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
+back end, 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} on the server (or servers) that you wish to have covered by the
+Agent (@pxref{Server Agent Commands}), or @kbd{J r} on automatically
+added servers you do not wish to have covered by the Agent. By default,
+all @code{nntp} and @code{nnimap} servers in @code{gnus-select-method} and
+@code{gnus-secondary-select-methods} are agentized.
+
+@item
+Decide on download policy. It's fairly simple once you decide whether
+you are going to use agent categories, topic parameters, and/or group
+parameters to implement your policy. If you're new to gnus, it
+is probably best to start with a category, @xref{Agent Categories}.
+
+Both topic parameters (@pxref{Topic Parameters}) and agent categories
+(@pxref{Agent Categories}) provide for setting a policy that applies
+to multiple groups. Which you use is entirely up to you. Topic
+parameters do override categories so, if you mix the two, you'll have
+to take that into account. If you have a few groups that deviate from
+your policy, you can use group parameters (@pxref{Group Parameters}) to
+configure them.
+
+@item
+Uhm@dots{} 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.
+
+One of the more effective methods for controlling what is to be
+downloaded is to create a @dfn{category} and then assign some (or all)
+groups to this category. Groups that do not belong in any other
+category belong to the @code{default} category. Gnus has its own
+buffer for creating and managing categories.
+
+If you prefer, you can also use group parameters (@pxref{Group
+Parameters}) and topic parameters (@pxref{Topic Parameters}) for an
+alternative approach to controlling the agent. The only real
+difference is that categories are specific to the agent (so there is
+less to learn) while group and topic parameters include the kitchen
+sink.
+
+Since you can set agent parameters in several different places we have
+a rule to decide which source to believe. This rule specifies that
+the parameter sources are checked in the following order: group
+parameters, topic parameters, agent category, and finally customizable
+variables. So you can mix all of these sources to produce a wide range
+of behavior, just don't blame me if you don't remember where you put
+your settings.
+
+@menu
+* Category Syntax:: What a category looks like.
+* Category Buffer:: A buffer for maintaining categories.
+* Category Variables:: Customize'r'Us.
+@end menu
+
+
+@node Category Syntax
+@subsubsection Category Syntax
+
+A category consists of a name, the list of groups belonging to the
+category, and a number of optional parameters that override the
+customizable variables. The complete list of agent parameters are
+listed below.
+
+@cindex Agent Parameters
+@table @code
+@item gnus-agent-cat-name
+The name of the category.
+
+@item gnus-agent-cat-groups
+The list of groups that are in this category.
+
+@item gnus-agent-cat-predicate
+A predicate which (generally) gives a rough outline of which articles
+are eligible for downloading; and
+
+@item gnus-agent-cat-score-file
+a score rule which (generally) gives you a finer granularity when
+deciding what articles to download. (Note that this @dfn{download
+score} is not necessarily related to normal scores.)
+
+@item gnus-agent-cat-enable-expiration
+a boolean indicating whether the agent should expire old articles in
+this group. Most groups should be expired to conserve disk space. In
+fact, its probably safe to say that the gnus.* hierarchy contains the
+only groups that should not be expired.
+
+@item gnus-agent-cat-days-until-old
+an integer indicating the number of days that the agent should wait
+before deciding that a read article is safe to expire.
+
+@item gnus-agent-cat-low-score
+an integer that overrides the value of @code{gnus-agent-low-score}.
+
+@item gnus-agent-cat-high-score
+an integer that overrides the value of @code{gnus-agent-high-score}.
+
+@item gnus-agent-cat-length-when-short
+an integer that overrides the value of
+@code{gnus-agent-short-article}.
+
+@item gnus-agent-cat-length-when-long
+an integer that overrides the value of @code{gnus-agent-long-article}.
+
+@c @item gnus-agent-cat-disable-undownloaded-faces
+@c a symbol indicating whether the summary buffer should @emph{not} display
+@c undownloaded articles using the gnus-summary-*-undownloaded-face
+@c faces. The symbol nil will enable the use of undownloaded faces while
+@c all other symbols disable them.
+
+@item gnus-agent-cat-enable-undownloaded-faces
+a symbol indicating whether the summary buffer should display
+undownloaded articles using the gnus-summary-*-undownloaded-face
+faces. The symbol nil will disable the use of undownloaded faces while
+all other symbols enable them.
+@end table
+
+The name of a category can not be changed once the category has been
+created.
+
+Each category maintains a list of groups that are exclusive members of
+that category. The exclusivity rule is automatically enforced, add a
+group to a new category and it is automatically removed from its old
+category.
+
+A predicate in its simplest form can be a single predicate such as
+@code{true} or @code{false}. These two will download every available
+article or nothing respectively. In the case of these two special
+predicates an additional score rule is superfluous.
+
+Predicates of @code{high} or @code{low} download articles in respect of
+their scores in relationship to @code{gnus-agent-high-score} and
+@code{gnus-agent-low-score} as described below.
+
+To gain even finer control of what is to be regarded eligible for
+download a predicate can consist of a number 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.
+
+When evaluating each of these predicates, the named constant will be
+bound to the value determined by calling
+@code{gnus-agent-find-parameter} on the appropriate parameter. For
+example, gnus-agent-short-article will be bound to
+@code{(gnus-agent-find-parameter group 'agent-short-article)}. This
+means that you can specify a predicate in your category then tune that
+predicate to individual groups.
+
+@table @code
+@item short
+True if the article is shorter than @code{gnus-agent-short-article}
+lines; default 100.
+
+@item long
+True if the article is longer than @code{gnus-agent-long-article}
+lines; default 200.
+
+@item low
+True if the article has a download score less than
+@code{gnus-agent-low-score}; default 0.
+
+@item high
+True if the article has a download score greater than
+@code{gnus-agent-high-score}; default 0.
+
+@item spam
+True if 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.
+
+For example, you could decide that you don't want to download articles
+that were posted more than a certain number of days ago (e.g. posted
+more than @code{gnus-agent-expire-days} ago) you might write a function
+something along the lines of the following:
+
+@lisp
+(defun my-article-old-p ()
+ "Say whether an article is old."
+ (< (time-to-days (date-to-time (mail-header-date gnus-headers)))
+ (- (time-to-days (current-time)) gnus-agent-expire-days)))
+@end lisp
+
+with the predicate then defined as:
+
+@lisp
+(not my-article-old-p)
+@end lisp
+
+or you could append your predicate to the predefined
+@code{gnus-category-predicate-alist} in your @file{~/.gnus.el} or
+wherever.
+
+@lisp
+(require 'gnus-agent)
+(setq gnus-category-predicate-alist
+ (append gnus-category-predicate-alist
+ '((old . my-article-old-p))))
+@end lisp
+
+and simply specify your predicate as:
+
+@lisp
+(not old)
+@end lisp
+
+If/when using something like the above, be aware that there are many
+misconfigured systems/mailers out there and so an article's date is not
+always a reliable indication of when it was posted. Hell, some people
+just don't give a damn.
+
+The above predicates apply to @emph{all} the groups which belong to the
+category. However, if you wish to have a specific predicate for an
+individual group within a category, or you're just too lazy to set up a
+new category, you can enter a group's individual predicate in its group
+parameters like so:
+
+@lisp
+(agent-predicate . short)
+@end lisp
+
+This is the group/topic parameter equivalent of the agent category default.
+Note that when specifying a single word predicate like this, the
+@code{agent-predicate} specification must be in dotted pair notation.
+
+The equivalent of the longer example from above would be:
+
+@lisp
+(agent-predicate or high (and (not low) (not long)))
+@end lisp
+
+The outer parenthesis required in the category specification are not
+entered here as, not being in dotted pair notation, the value of the
+predicate is assumed to be a list.
+
+
+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{Subject}, @code{From},
+@code{Date}, @code{Message-ID}, @code{References}, @code{Chars},
+@code{Lines}, and @code{Xref}.
+
+As with predicates, the specification of the @code{download score rule}
+to use in respect of a group can be in either the category definition if
+it's to be applicable to all groups in therein, or a group's parameters
+if it's to be specific to that group.
+
+In both of these places the @code{download score rule} can take one of
+three forms:
+
+@enumerate
+@item
+Score rule
+
+This has the same syntax as a normal Gnus score file except only a
+subset of scoring keywords are available as mentioned above.
+
+example:
+
+@itemize @bullet
+@item
+Category specification
+
+@lisp
+(("from"
+ ("Lars Ingebrigtsen" 1000000 nil s))
+("lines"
+ (500 -100 nil <)))
+@end lisp
+
+@item
+Group/Topic Parameter specification
+
+@lisp
+(agent-score ("from"
+ ("Lars Ingebrigtsen" 1000000 nil s))
+ ("lines"
+ (500 -100 nil <)))
+@end lisp
+
+Again, note the omission of the outermost parenthesis here.
+@end itemize
+
+@item
+Agent score file
+
+These score files must @emph{only} contain the permitted scoring
+keywords stated above.
+
+example:
+
+@itemize @bullet
+@item
+Category specification
+
+@lisp
+("~/News/agent.SCORE")
+@end lisp
+
+or perhaps
+
+@lisp
+("~/News/agent.SCORE" "~/News/agent.group.SCORE")
+@end lisp
+
+@item
+Group Parameter specification
+
+@lisp
+(agent-score "~/News/agent.SCORE")
+@end lisp
+
+Additional score files can be specified as above. Need I say anything
+about parenthesis?
+@end itemize
+
+@item
+Use @code{normal} score files
+
+If you don't want to maintain two sets of scoring rules for a group, and
+your desired @code{downloading} criteria for a group are the same as your
+@code{reading} criteria then you can tell the agent to refer to your
+@code{normal} score files when deciding what to download.
+
+These directives in either the category definition or a group's
+parameters will cause the agent to read in all the applicable score
+files for a group, @emph{filtering out} those sections that do not
+relate to one of the permitted subset of scoring keywords.
+
+@itemize @bullet
+@item
+Category Specification
+
+@lisp
+file
+@end lisp
+
+@item
+Group Parameter specification
+
+@lisp
+(agent-score . file)
+@end lisp
+@end itemize
+@end enumerate
+
+@node Category Buffer
+@subsubsection 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 e
+@kindex e (Category)
+@findex gnus-category-customize-category
+Use a customization buffer to set all of the selected category's
+parameters at one time (@code{gnus-category-customize-category}).
+
+@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.
+
+@item gnus-agent-expire-days
+@vindex gnus-agent-expire-days
+The number of days that a @samp{read} article must stay in the agent's
+local disk before becoming eligible for expiration (While the name is
+the same, this doesn't mean expiring the article on the server. It
+just means deleting the local copy of the article). What is also
+important to understand is that the counter starts with the time the
+article was written to the local disk and not the time the article was
+read.
+Default 7.
+
+@item gnus-agent-enable-expiration
+@vindex gnus-agent-enable-expiration
+Determines whether articles in a group are, by default, expired or
+retained indefinitely. The default is @code{ENABLE} which means that
+you'll have to disable expiration when desired. On the other hand,
+you could set this to @code{DISABLE}. In that case, you would then
+have to enable expiration in selected groups.
+
+@end table
+
+
+@node Agent Commands
+@subsection Agent Commands
+@findex gnus-agent-toggle-plugged
+@kindex J j (Agent)
+
+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:: Configure groups and fetch their contents.
+* Summary Agent Commands:: Manually select then fetch specific articles.
+* Server Agent Commands:: Select the servers that are supported by the agent.
+@end menu
+
+
+
+
+@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-queue
+Send all sendable messages in the queue group
+(@code{gnus-group-send-queue}). @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}). This command understands the
+process/prefix convention (@pxref{Process/Prefix}).
+
+@item J r
+@kindex J r (Agent Group)
+@findex gnus-agent-remove-group
+Remove the current group from its category, if any
+(@code{gnus-agent-remove-group}). This command understands the
+process/prefix convention (@pxref{Process/Prefix}).
+
+@item J Y
+@kindex J Y (Agent Group)
+@findex gnus-agent-synchronize-flags
+Synchronize flags changed while unplugged with remote server, if any.
+
+
+@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}).
+
+@cindex %
+@item @@
+@kindex @@ (Agent Summary)
+@findex gnus-agent-toggle-mark
+Toggle whether to download the article
+(@code{gnus-agent-toggle-mark}). The download mark is @samp{%} by
+default.
+
+@item J c
+@kindex J c (Agent Summary)
+@findex gnus-agent-catchup
+Mark all articles as read (@code{gnus-agent-catchup}) that are neither cached, downloaded, nor downloadable.
+
+@item J S
+@kindex J S (Agent Summary)
+@findex gnus-agent-fetch-group
+Download all eligible (@pxref{Agent Categories}) articles in this group.
+(@code{gnus-agent-fetch-group}).
+
+@item J s
+@kindex J s (Agent Summary)
+@findex gnus-agent-fetch-series
+Download all processable articles in this group.
+(@code{gnus-agent-fetch-series}).
+
+@item J u
+@kindex J u (Agent Summary)
+@findex gnus-agent-summary-fetch-group
+Download all downloadable articles in the current group
+(@code{gnus-agent-summary-fetch-group}).
+
+@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 Visuals
+@subsection Agent Visuals
+
+If you open a summary while unplugged and, Gnus knows from the group's
+active range that there are more articles than the headers currently
+stored in the Agent, you may see some articles whose subject looks
+something like @samp{[Undownloaded article #####]}. These are
+placeholders for the missing headers. Aside from setting a mark,
+there is not much that can be done with one of these placeholders.
+When Gnus finally gets a chance to fetch the group's headers, the
+placeholders will automatically be replaced by the actual headers.
+You can configure the summary buffer's maneuvering to skip over the
+placeholders if you care (See @code{gnus-auto-goto-ignores}).
+
+While it may be obvious to all, the only headers and articles
+available while unplugged are those headers and articles that were
+fetched into the Agent while previously plugged. To put it another
+way, ``If you forget to fetch something while plugged, you might have a
+less than satisfying unplugged session''. For this reason, the Agent
+adds two visual effects to your summary buffer. These effects display
+the download status of each article so that you always know which
+articles will be available when unplugged.
+
+The first visual effect is the @samp{%O} spec. If you customize
+@code{gnus-summary-line-format} to include this specifier, you will add
+a single character field that indicates an article's download status.
+Articles that have been fetched into either the Agent or the Cache,
+will display @code{gnus-downloaded-mark} (defaults to @samp{+}). All
+other articles will display @code{gnus-undownloaded-mark} (defaults to
+@samp{-}). If you open a group that has not been agentized, a space
+(@samp{ }) will be displayed.
+
+The second visual effect are the undownloaded faces. The faces, there
+are three indicating the article's score (low, normal, high), seem to
+result in a love/hate response from many Gnus users. The problem is
+that the face selection is controlled by a list of condition tests and
+face names (See @code{gnus-summary-highlight}). Each condition is
+tested in the order in which it appears in the list so early
+conditions have precedence over later conditions. All of this means
+that, if you tick an undownloaded article, the article will continue
+to be displayed in the undownloaded face rather than the ticked face.
+
+If you use the Agent as a cache (to avoid downloading the same article
+each time you visit it or to minimize your connection time), the
+undownloaded face will probably seem like a good idea. The reason
+being that you do all of our work (marking, reading, deleting) with
+downloaded articles so the normal faces always appear.
+
+For occasional Agent users, the undownloaded faces may appear to be an
+absolutely horrible idea. The issue being that, since most of their
+articles have not been fetched into the Agent, most of the normal
+faces will be obscured by the undownloaded faces. If this is your
+situation, you have two choices available. First, you can completely
+disable the undownload faces by customizing
+@code{gnus-summary-highlight} to delete the three cons-cells that
+refer to the @code{gnus-summary-*-undownloaded-face} faces. Second,
+if you prefer to take a more fine-grained approach, you may set the
+@code{agent-disable-undownloaded-faces} group parameter to @code{t}.
+This parameter, like all other agent parameters, may be set on an
+Agent Category (@pxref{Agent Categories}), a Group Topic (@pxref{Topic
+Parameters}), or an individual group (@pxref{Group Parameters}).
+
+@node Agent as Cache
+@subsection Agent as Cache
+
+When Gnus is plugged, it is not efficient to download headers or
+articles from the server again, if they are already stored in the
+Agent. So, Gnus normally only downloads headers once, and stores them
+in the Agent. These headers are later used when generating the summary
+buffer, regardless of whether you are plugged or unplugged. Articles
+are not cached in the Agent by default though (that would potentially
+consume lots of disk space), but if you have already downloaded an
+article into the Agent, Gnus will not download the article from the
+server again but use the locally stored copy instead.
+
+If you so desire, you can configure the agent (see @code{gnus-agent-cache}
+@pxref{Agent Variables}) to always download headers and articles while
+plugged. Gnus will almost certainly be slower, but it will be kept
+synchronized with the server. That last point probably won't make any
+sense if you are using a nntp or nnimap back end.
+
+@node Agent Expiry
+@subsection Agent Expiry
+
+@vindex gnus-agent-expire-days
+@findex gnus-agent-expire
+@kindex M-x gnus-agent-expire
+@kindex M-x gnus-agent-expire-group
+@findex gnus-agent-expire-group
+@cindex agent expiry
+@cindex Gnus agent expiry
+@cindex expiry, in Gnus agent
+
+The Agent back end, @code{nnagent}, doesn't handle expiry. Well, at
+least it doesn't handle it like other back ends. Instead, there are
+special @code{gnus-agent-expire} and @code{gnus-agent-expire-group}
+commands that will expire all read articles that are older than
+@code{gnus-agent-expire-days} days. They can be run whenever you feel
+that you're running out of space. Neither are particularly fast or
+efficient, and it's not a particularly good idea to interrupt them (with
+@kbd{C-g} or anything else) once you've started one of them.
+
+Note that other functions, e.g. @code{gnus-request-expire-articles},
+might run @code{gnus-agent-expire} for you to keep the agent
+synchronized with the group.
+
+The agent parameter @code{agent-enable-expiration} may be used to
+prevent expiration in selected groups.
+
+@vindex gnus-agent-expire-all
+If @code{gnus-agent-expire-all} is non-@code{nil}, the agent
+expiration commands 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.
+
+If you find that some articles eligible for expiry are never expired,
+perhaps some Gnus Agent files are corrupted. There's are special
+commands, @code{gnus-agent-regenerate} and
+@code{gnus-agent-regenerate-group}, to fix possible problems.
+
+@node Agent Regeneration
+@subsection Agent Regeneration
+
+@cindex agent regeneration
+@cindex Gnus agent regeneration
+@cindex regeneration
+
+The local data structures used by @code{nnagent} may become corrupted
+due to certain exceptional conditions. When this happens,
+@code{nnagent} functionality may degrade or even fail. The solution
+to this problem is to repair the local data structures by removing all
+internal inconsistencies.
+
+For example, if your connection to your server is lost while
+downloaded articles into the agent, the local data structures will not
+know about articles successfully downloaded prior to the connection
+failure. Running @code{gnus-agent-regenerate} or
+@code{gnus-agent-regenerate-group} will update the data structures
+such that you don't need to download these articles a second time.
+
+@findex gnus-agent-regenerate
+@kindex M-x gnus-agent-regenerate
+The command @code{gnus-agent-regenerate} will perform
+@code{gnus-agent-regenerate-group} on every agentized group. While
+you can run @code{gnus-agent-regenerate} in any buffer, it is strongly
+recommended that you first close all summary buffers.
+
+@findex gnus-agent-regenerate-group
+@kindex M-x gnus-agent-regenerate-group
+The command @code{gnus-agent-regenerate-group} uses the local copies
+of individual articles to repair the local @acronym{NOV}(header) database. It
+then updates the internal data structures that document which articles
+are stored locally. An optional argument will mark articles in the
+agent as unread.
+
+@node Agent and IMAP
+@subsection Agent and IMAP
+
+The Agent works with any Gnus back end, including nnimap. However,
+since there are some conceptual differences between @acronym{NNTP} and
+@acronym{IMAP}, this section (should) provide you with some information to
+make Gnus Agent work smoother as a @acronym{IMAP} Disconnected Mode client.
+
+The first thing to keep in mind is that all flags (read, ticked, etc)
+are kept on the @acronym{IMAP} server, rather than in @file{.newsrc} as is the
+case for nntp. Thus Gnus need to remember flag changes when
+disconnected, and synchronize these flags when you plug back in.
+
+Gnus keeps track of flag changes when reading nnimap groups under the
+Agent. When you plug back in, Gnus will check if you have any changed
+any flags and ask if you wish to synchronize these with the server.
+The behavior is customizable by @code{gnus-agent-synchronize-flags}.
+
+@vindex gnus-agent-synchronize-flags
+If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will
+never automatically synchronize flags. If it is @code{ask}, which is
+the default, the Agent will check if you made any changes and if so
+ask if you wish to synchronize these when you re-connect. If it has
+any other value, all flags will be synchronized automatically.
+
+If you do not wish to synchronize flags automatically when you
+re-connect, you can do it manually with the
+@code{gnus-agent-synchronize-flags} command that is bound to @kbd{J Y}
+in the group buffer.
+
+Some things are currently not implemented in the Agent that you'd might
+expect from a disconnected @acronym{IMAP} client, including:
+
+@itemize @bullet
+
+@item
+Copying/moving articles into nnimap groups when unplugged.
+
+@item
+Creating/deleting nnimap groups when unplugged.
+
+@end itemize
+
+Technical note: the synchronization algorithm does not work by ``pushing''
+all local flags to the server, but rather incrementally update the
+server view of flags by changing only those flags that were changed by
+the user. Thus, if you set one flag on an article, quit the group and
+re-select the group and remove the flag; the flag will be set and
+removed from the server when you ``synchronize''. The queued flag
+operations can be found in the per-server @code{flags} file in the Agent
+directory. It's emptied when you synchronize flags.
+
+
+@node Outgoing Messages
+@subsection Outgoing Messages
+
+When Gnus is unplugged, all outgoing messages (both mail and news) are
+stored in the draft group ``queue'' (@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.
+
+@item gnus-agent-fetched-hook
+@vindex gnus-agent-fetched-hook
+Hook run when finished fetching articles.
+
+@item gnus-agent-cache
+@vindex gnus-agent-cache
+Variable to control whether use the locally stored @acronym{NOV} and
+articles when plugged, e.g. essentially using the Agent as a cache.
+The default is non-@code{nil}, which means to use the Agent as a cache.
+
+@item gnus-agent-go-online
+@vindex gnus-agent-go-online
+If @code{gnus-agent-go-online} is @code{nil}, the Agent will never
+automatically switch offline servers into online status. If it is
+@code{ask}, the default, the Agent will ask if you wish to switch
+offline servers into online status when you re-connect. If it has any
+other value, all offline servers will be automatically switched into
+online status.
+
+@item gnus-agent-mark-unread-after-downloaded
+@vindex gnus-agent-mark-unread-after-downloaded
+If @code{gnus-agent-mark-unread-after-downloaded} is non-@code{nil},
+mark articles as unread after downloading. This is usually a safe
+thing to do as the newly downloaded article has obviously not been
+read. The default is @code{t}.
+
+@item gnus-agent-consider-all-articles
+@vindex gnus-agent-consider-all-articles
+If @code{gnus-agent-consider-all-articles} is non-@code{nil}, the
+agent will let the agent predicate decide whether articles need to be
+downloaded or not, for all articles. When @code{nil}, the default,
+the agent will only let the predicate decide whether unread articles
+are downloaded or not. If you enable this, you may also want to look
+into the agent expiry settings (@pxref{Category Variables}), so that
+the agent doesn't download articles which the agent will later expire,
+over and over again.
+
+@item gnus-agent-max-fetch-size
+@vindex gnus-agent-max-fetch-size
+The agent fetches articles into a temporary buffer prior to parsing
+them into individual files. To avoid exceeding the max. buffer size,
+the agent alternates between fetching and parsing until all articles
+have been fetched. @code{gnus-agent-max-fetch-size} provides a size
+limit to control how often the cycling occurs. A large value improves
+performance. A small value minimizes the time lost should the
+connection be lost while fetching (You may need to run
+@code{gnus-agent-regenerate-group} to update the group's state.
+However, all articles parsed prior to loosing the connection will be
+available while unplugged). The default is 10M so it is unusual to
+see any cycling.
+
+@item gnus-server-unopen-status
+@vindex gnus-server-unopen-status
+Perhaps not an Agent variable, but closely related to the Agent, this
+variable says what will happen if Gnus cannot open a server. If the
+Agent is enabled, the default, @code{nil}, makes Gnus ask the user
+whether to deny the server or whether to unplug the agent. If the
+Agent is disabled, Gnus always simply deny the server. Other choices
+for this variable include @code{denied} and @code{offline} the latter
+is only valid if the Agent is used.
+
+@item gnus-auto-goto-ignores
+@vindex gnus-auto-goto-ignores
+Another variable that isn't an Agent variable, yet so closely related
+that most will look for it here, this variable tells the summary
+buffer how to maneuver around undownloaded (only headers stored in the
+agent) and unfetched (neither article nor headers stored) articles.
+
+The valid values are @code{nil} (maneuver to any article),
+@code{undownloaded} (maneuvering while unplugged ignores articles that
+have not been fetched), @code{always-undownloaded} (maneuvering always
+ignores articles that have not been fetched), @code{unfetched}
+(maneuvering ignores articles whose headers have not been fetched).
+
+@item gnus-agent-auto-agentize-methods
+@vindex gnus-agent-auto-agentize-methods
+If you have never used the Agent before (or more technically, if
+@file{~/News/agent/lib/servers} does not exist), Gnus will
+automatically agentize a few servers for you. This variable control
+which backends should be auto-agentized. It is typically only useful
+to agentize remote backends. The auto-agentizing has the same effect
+as running @kbd{J a} on the servers (@pxref{Server Agent Commands}).
+If the file exist, you must manage the servers manually by adding or
+removing them, this variable is only applicable the first time you
+start Gnus. The default is @samp{(nntp nnimap)}.
+
+@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
+;; @r{Define how Gnus is to fetch news. We do this over @acronym{NNTP}}
+;; @r{from your ISP's server.}
+(setq gnus-select-method '(nntp "news.your-isp.com"))
+
+;; @r{Define how Gnus is to read your mail. We read mail from}
+;; @r{your ISP's @acronym{POP} server.}
+(setq mail-sources '((pop :server "pop.your-isp.com")))
+
+;; @r{Say how Gnus is to store the mail. We use nnml groups.}
+(setq gnus-secondary-select-methods '((nnml "")))
+
+;; @r{Make Gnus into an offline newsreader.}
+;; (gnus-agentize) ; @r{The obsolete setting.}
+;; (setq gnus-agent t) ; @r{Now the default.}
+@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
+@acronym{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
+@findex gnus-agent-batch
+
+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:
+
+You can run a complete batch command from the command line with the
+following incantation:
+
+@example
+#!/bin/sh
+emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-agent-batch >/dev/null 2>&1
+@end example
+
+
+@node Agent Caveats
+@subsection Agent Caveats
+
+The Gnus Agent doesn't seem to work like most other offline
+newsreaders. Here are some common questions that some imaginary people
+may ask:
+
+@table @dfn
+@item If I read an article while plugged, do they get entered into the Agent?
+
+@strong{No}. If you want this behavior, add
+@code{gnus-agent-fetch-selected-article} to
+@code{gnus-select-article-hook}.
+
+@item If I read an article while plugged, and the article already exists in
+the Agent, will it get downloaded once more?
+
+@strong{No}, unless @code{gnus-agent-cache} is @code{nil}.
+
+@end table
+
+In short, when Gnus is unplugged, it only looks into the locally stored
+articles; when it's plugged, it talks to your ISP and may also use the
+locally stored articles.
+
+
+@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 On Other Headers:: Scoring on non-standard headers.
+* 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}). In the @code{*Score Trace*} buffer, you
+may type @kbd{e} to edit score file corresponding to the score rule on
+current line and @kbd{f} to format (@code{gnus-score-pretty-print}) the
+score file and edit it.
+
+@item V w
+@kindex V w (Summary)
+@findex gnus-score-find-favourite-words
+List words used in scoring (@code{gnus-score-find-favourite-words}).
+
+@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 @code{Xref} line---i.e., the cross-posting line.
+
+@item r
+Score on the @code{References} line.
+
+@item d
+Score on the date.
+
+@item l
+Score on the number of lines.
+
+@item i
+Score on the @code{Message-ID} header.
+
+@item e
+Score on an ``extra'' header, that is, one of those in gnus-extra-headers,
+if your @acronym{NNTP} server tracks additional header data in overviews.
+
+@item f
+Score on followups---this matches the author name, and adds scores to
+the followups to this author. (Using this key leads to the creation of
+@file{ADAPT} files.)
+
+@item b
+Score on the body.
+
+@item h
+Score on the head.
+
+@item t
+Score on thread. (Using this key leads to the creation of @file{ADAPT}
+files.)
+
+@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 usually 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
+
+@item
+If you are scoring on `e' (extra) headers, you will then be prompted for
+the header name on which you wish to score. This must be a header named
+in gnus-extra-headers, and @samp{TAB} completion is available.
+
+@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.el -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 @env{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
+(@file{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 your 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.
+
+If you do not set this to @code{t}, then manual scores (like those set
+with @kbd{V s} (@code{gnus-summary-set-score})) will not be preserved
+across group visits.
+
+@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} for each
+server.
+
+@end table
+This variable can also be a list of functions. In that case, all
+these functions will be called with the group name as argument, and
+all the returned lists of score files will be applied. These
+functions can also return lists of 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.
+
+For example, to do hierarchical scoring but use a non-server-specific
+overall score file, you could use the value
+@example
+(list (lambda (group) ("all.SCORE"))
+ 'gnus-score-find-hierarchical)
+@end example
+
+@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}, temporary score entries that have
+been triggered (matched) will have their dates updated. (This is how Gnus
+controls expiry---all non-matched-entries will become too old while
+matched entries will stay fresh and young.) However, if you set this
+variable to @code{nil}, even matched 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
+@code{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. @xref{Advanced
+Scoring}, for a different approach.
+
+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 an 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 Extra
+Just as for the standard string overview headers, if you are using
+gnus-extra-headers, you can score on these headers' values. In this
+case, there is a 5th element in the score entry, being the name of the
+header to be scored. The following entry is useful in your
+@file{all.SCORE} file in case of spam attacks from a single origin
+host, if your @acronym{NNTP} server tracks @samp{NNTP-Posting-Host} in
+overviews:
+
+@lisp
+("111.222.333.444" -1000 nil s
+ "NNTP-Posting-Host")
+@end lisp
+
+@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 back ends (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 a few
+interesting threads which can't be found automatically by ordinary
+scoring rules exist.
+
+@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{var}
+@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}, @kbd{V e} and
+@kbd{V t} 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
+(setq 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{e}) 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.
+
+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 @file{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-length-limit
+Some may feel that short words shouldn't count when doing adaptive
+scoring. If so, you may set @code{gnus-adaptive-word-length-limit} to
+an integer. Words shorter than this number will be ignored. This
+variable defaults to @code{nil}.
+
+@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}.
+
+@vindex gnus-adaptive-word-no-group-words
+If @code{gnus-adaptive-word-no-group-words} is set to @code{t}, gnus
+won't adaptively word score any of the words in the group name. Useful
+for groups like @samp{comp.editors.emacs}, where most of the subject
+lines contain the word @samp{emacs}.
+
+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
+@code{(@var{regexp} @var{file-name})}. If the @var{regexp} matches the
+group name, the @var{file-name} will be used as the home score file.
+
+@item
+A function. If the function returns non-@code{nil}, the result will
+be used as the home score file. The function will be called with the
+name of the group as the parameter.
+
+@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
+ ;; @r{All groups that match the regexp @code{"\\.emacs"}}
+ '(("\\.emacs" "emacs.SCORE")
+ ;; @r{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}, like this:
+@lisp
+(add-hook 'message-sent-hook 'gnus-score-followup-thread)
+@end lisp
+
+
+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 On Other Headers
+@section Scoring On Other Headers
+@cindex scoring on other headers
+
+Gnus is quite fast when scoring the ``traditional''
+headers---@samp{From}, @samp{Subject} and so on. However, scoring
+other headers requires writing a @code{head} scoring rule, which means
+that Gnus has to request every single article from the back end to find
+matches. This takes a long time in big groups.
+
+Now, there's not much you can do about this for news groups, but for
+mail groups, you have greater control. In @ref{To From Newsgroups},
+it's explained in greater detail what this mechanism does, but here's
+a cookbook example for @code{nnml} on how to allow scoring on the
+@samp{To} and @samp{Cc} headers.
+
+Put the following in your @file{~/.gnus.el} file.
+
+@lisp
+(setq gnus-extra-headers '(To Cc Newsgroups Keywords)
+ nnmail-extra-headers gnus-extra-headers)
+@end lisp
+
+Restart Gnus and rebuild your @code{nnml} overview files with the
+@kbd{M-x nnml-generate-nov-databases} command. This will take a long
+time if you have much mail.
+
+Now you can score on @samp{To} and @samp{Cc} as ``extra headers'' like
+so: @kbd{I e s p To RET <your name> RET}.
+
+See? Simple.
+
+
+@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 have scores 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.
+
+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,
+say this:
+
+@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
+@noindent
+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
+
+@dots{} 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 @sc{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
+@uref{http://www.stud.ifi.uio.no/~larsi/ding-various/gnus-kill-to-score.el}.
+
+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
+
+@sc{Note:} Unfortunately the GroupLens system seems to have shut down,
+so this section is mostly of historical interest.
+
+@uref{http://www.cs.umn.edu/Research/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
+@uref{http://www.cs.umn.edu/Research/GroupLens/bbb.html, Better Bit
+Bureau (BBB)} 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: %-23,23n%]%)
+%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
+
+Please note that the following examples are score file rules. To
+make a complete score file from them, surround them with another pair
+of parentheses.
+
+Let's say you want to increase the score of articles written by Lars
+when he's talking about Gnus:
+
+@example
+@group
+((&
+ ("from" "Lars Ingebrigtsen")
+ ("subject" "Gnus"))
+ 1000)
+@end group
+@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 Eigil 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
+
+Suppose you're reading a high volume group and you're only interested
+in replies. The plan is to score down all articles that don't have
+subject that begin with "Re:", "Fw:" or "Fwd:" and then score up all
+parents of articles that have subjects that begin with reply marks.
+
+@example
+((! ("subject" "re:\\|fwd?:" r))
+ -200)
+((1- ("subject" "re:\\|fwd?:" r))
+ 200)
+@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 according to `gnus-score-decay-constant'
+and `gnus-score-decay-scale'."
+ (let ((n (- score
+ (* (if (< score 0) -1 1)
+ (min (abs score)
+ (max gnus-score-decay-constant
+ (* (abs score)
+ gnus-score-decay-scale)))))))
+ (if (and (featurep 'xemacs)
+ ;; XEmacs' floor can handle only the floating point
+ ;; number below the half of the maximum integer.
+ (> (abs n) (lsh -1 -2)))
+ (string-to-number
+ (car (split-string (number-to-string n) "\\.")))
+ (floor n))))
+@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.
+
+@iftex
+@iflatex
+@chapter Message
+@include message.texi
+@chapter Emacs MIME
+@include emacs-mime.texi
+@chapter Sieve
+@include sieve.texi
+@chapter PGG
+@include pgg.texi
+@end iflatex
+@end iftex
+
+@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.
+* Window Layout:: 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 tendinitis 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.
+* Predicate Specifiers:: Specifying predicates.
+* Moderation:: What to do if you're a moderator.
+* Fetching a Group:: Starting Gnus just to read a group.
+* Image Enhancements:: Modern versions of Emacs/XEmacs can display images.
+* Fuzzy Matching:: What's the big fuzz?
+* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email.
+* Spam Package:: A package for filtering and processing spam.
+* Other modes:: Interaction with other modes.
+* 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.
+
+Many commands do not use the process/prefix convention. All commands
+that do explicitly say so in this manual. To apply the process/prefix
+convention to commands that do not use it, you can use the @kbd{M-&}
+command. For instance, to mark all the articles in the group as
+expirable, you could say @kbd{M P b M-& E}.
+
+
+@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 C-M-u} means ``feed the @kbd{C-M-u}
+command the symbolic prefix @code{a}''. @kbd{M-i a M-i b C-M-u} means
+``feed the @kbd{C-M-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.
+* Positioning Point:: Moving point to a position after an operation.
+* Tabulation:: Tabulating your output.
+* Wide Characters:: Dealing with wide characters.
+@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.
+
+Also Gnus supports some extended format specifications, such as
+@samp{%&user-date;}.
+
+
+@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.
+
+Here's an example:
+
+@lisp
+"~(form (current-time-string))@@"
+@end lisp
+
+@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.
+
+Also Gnus supports extended user-defined specs, such as @samp{%u&foo;}.
+Gnus will call the function @code{gnus-user-format-function-}@samp{foo}.
+
+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}.
+
+Text inside the @samp{%<<} and @samp{%>>} specifiers will get the
+special @code{balloon-help} property set to
+@code{gnus-balloon-face-0}. If you say @samp{%1<<}, you'll get
+@code{gnus-balloon-face-1} and so on. The @code{gnus-balloon-face-*}
+variables should be either strings or symbols naming functions that
+return a string. When the mouse passes over text with this property
+set, a balloon window will appear and display the string. Please
+refer to @ref{Tooltips, ,Tooltips, emacs, The Emacs Manual},
+(in GNU Emacs) or the doc string of @code{balloon-help-mode} (in
+XEmacs) for more information on this. (For technical reasons, the
+guillemets have been approximated as @samp{<<} and @samp{>>} in this
+paragraph.)
+
+Here's an alternative recipe for the group buffer:
+
+@lisp
+;; @r{Create three face types.}
+(setq gnus-face-1 'bold)
+(setq gnus-face-3 'italic)
+
+;; @r{We want the article count to be in}
+;; @r{a bold and green face. So we create}
+;; @r{a new face called @code{my-green-bold}.}
+(copy-face 'bold 'my-green-bold)
+;; @r{Set the color.}
+(set-face-foreground 'my-green-bold "ForestGreen")
+(setq gnus-face-2 'my-green-bold)
+
+;; @r{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 Positioning Point
+@subsection Positioning Point
+
+Gnus usually moves point to a pre-defined place on each line in most
+buffers. By default, point move to the first colon character on the
+line. You can customize this behavior in three different ways.
+
+You can move the colon character to somewhere else on the line.
+
+@findex gnus-goto-colon
+You can redefine the function that moves the point to the colon. The
+function is called @code{gnus-goto-colon}.
+
+But perhaps the most convenient way to deal with this, if you don't want
+to have a colon in your line, is to use the @samp{%*} specifier. If you
+put a @samp{%*} somewhere in your format line definition, Gnus will
+place point there.
+
+
+@node Tabulation
+@subsection Tabulation
+
+You can usually line up your displays by padding and cutting your
+strings. However, when combining various strings of different size, it
+can often be more convenient to just output the strings, and then worry
+about lining up the following text afterwards.
+
+To do that, Gnus supplies tabulator specs---@samp{%=}. There are two
+different types---@dfn{hard tabulators} and @dfn{soft tabulators}.
+
+@samp{%50=} will insert space characters to pad the line up to column
+50. If the text is already past column 50, nothing will be inserted.
+This is the soft tabulator.
+
+@samp{%-50=} will insert space characters to pad the line up to column
+50. If the text is already past column 50, the excess text past column
+50 will be removed. This is the hard tabulator.
+
+
+@node Wide Characters
+@subsection Wide Characters
+
+Fixed width fonts in most countries have characters of the same width.
+Some countries, however, use Latin characters mixed with wider
+characters---most notable East Asian countries.
+
+The problem is that when formatting, Gnus assumes that if a string is 10
+characters wide, it'll be 10 Latin characters wide on the screen. In
+these countries, that's not true.
+
+@vindex gnus-use-correct-string-widths
+To help fix this, you can set @code{gnus-use-correct-string-widths} to
+@code{t}. This makes buffer generation slower, but the results will be
+prettier. The default value under XEmacs is @code{t} but @code{nil}
+for Emacs.
+
+
+@node Window Layout
+@section Window Layout
+@cindex window layout
+
+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.
+
+Setting this variable to @code{nil} kinda works, but there are
+glitches. Use at your own peril.
+
+@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
+@group
+split = frame | horizontal | vertical | buffer | form
+frame = "(frame " size *split ")"
+horizontal = "(horizontal " size *split ")"
+vertical = "(vertical " size *split ")"
+buffer = "(" buf-name " " size *[ "point" ] *[ "frame-focus"] ")"
+size = number | frame-params
+buf-name = group | article | summary ...
+@end group
+@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.
+The list of all possible keys for @code{gnus-buffer-configuration} can
+be found in its default value.
+
+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
+
+One common desire for a multiple frame split is to have a separate frame
+for composing mail and news while leaving the original frame intact. To
+accomplish that, something like the following can be done:
+
+@lisp
+(message
+ (frame 1.0
+ (if (not (buffer-live-p gnus-summary-buffer))
+ (car (cdr (assoc 'group gnus-buffer-configuration)))
+ (car (cdr (assoc 'summary gnus-buffer-configuration))))
+ (vertical ((user-position . t) (top . 1) (left . 1)
+ (name . "Message"))
+ (message 1.0 point))))
+@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}.
+
+If you're using tree displays (@pxref{Tree Display}), and the tree
+window is displayed vertically next to another window, you may also want
+to fiddle with @code{gnus-tree-minimize-window} to avoid having the
+windows resized.
+
+@subsection Example Window Configurations
+
+@itemize @bullet
+@item
+Narrow left hand side occupied by group buffer. Right hand side split
+between summary buffer (top one-sixth) and article buffer (bottom).
+
+@ifinfo
+@example
++---+---------+
+| G | Summary |
+| r +---------+
+| o | |
+| u | Article |
+| p | |
++---+---------+
+@end example
+@end ifinfo
+
+@lisp
+(gnus-add-configuration
+ '(article
+ (horizontal 1.0
+ (vertical 25 (group 1.0))
+ (vertical 1.0
+ (summary 0.16 point)
+ (article 1.0)))))
+
+(gnus-add-configuration
+ '(summary
+ (horizontal 1.0
+ (vertical 25 (group 1.0))
+ (vertical 1.0 (summary 1.0 point)))))
+@end lisp
+
+@end itemize
+
+
+@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 @file{~/.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 @acronym{PGP} headers every hour when
+Emacs is idle:
+
+@lisp
+(gnus-demon-scan-pgp 60 t)
+@end lisp
+
+This @var{time} parameter and that @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.)
+
+So, if you want to add a handler, you could put something like this in
+your @file{~/.gnus.el} 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.el} 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.
+
+You can also set this variable to a positive number as a group level.
+In that case, Gnus scans NoCeM messages when checking new news if this
+value is not exceeding a group level that you specify as the prefix
+argument to some commands, e.g. @code{gnus},
+@code{gnus-group-get-new-news}, etc. Otherwise, Gnus does not scan
+NoCeM messages if you specify a group level to those commands. For
+example, if you use 1 or 2 on the mail groups and the levels on the news
+groups remain the default, 3 is the best choice.
+
+@item gnus-nocem-groups
+@vindex gnus-nocem-groups
+Gnus will look for NoCeM messages in the groups in this list. The
+default is
+@lisp
+("news.lists.filters" "news.admin.net-abuse.bulletins"
+ "alt.nocem.misc" "news.admin.net-abuse.announce")
+@end lisp
+
+@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
+@lisp
+("Automoose-1" "clewis@@ferret.ocunix.on.ca"
+ "cosmo.roadkill" "SpamHippo" "hweede@@snafu.de")
+@end lisp
+fine, upstanding citizens all of them.
+
+Known despammers that you can put in this list are listed at@*
+@uref{http://www.xs4all.nl/~rosalind/nocemreg/nocemreg.html}.
+
+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
+@code{(@var{issuer} @var{conditions} @dots{})} 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 @var{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 pgg-verify
+This should be a function for verifying that the NoCeM issuer is who she
+says she is. The default is @code{pgg-verify}, which returns
+non-@code{nil} if the verification is successful, otherwise (including
+the case the NoCeM message was not signed) returns @code{nil}. If this
+is too slow and you don't care for verification (which may be dangerous),
+you can set this variable to @code{nil}.
+
+Formerly the default was @code{mc-verify}, which is a Mailcrypt
+function. While you can still use it, you can change it into
+@code{pgg-verify} running with GnuPG if you are willing to add the
+@acronym{PGP} public keys to GnuPG's keyring.
+
+@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.
+
+@item gnus-nocem-check-from
+@vindex gnus-nocem-check-from
+Non-@code{nil} means check for valid issuers in message bodies.
+Otherwise don't bother fetching articles unless their author matches a
+valid issuer; that is much faster if you are selective about the
+issuers.
+
+@item gnus-nocem-check-article-limit
+@vindex gnus-nocem-check-article-limit
+If non-@code{nil}, the maximum number of articles to check in any NoCeM
+group. NoCeM groups can be huge and very slow to process.
+
+@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{C-M-_} key performs the @code{gnus-undo}
+command, which should feel kinda like the normal Emacs @code{undo}
+command.
+
+
+@node Predicate Specifiers
+@section Predicate Specifiers
+@cindex predicate specifiers
+
+Some Gnus variables are @dfn{predicate specifiers}. This is a special
+form that allows flexible specification of predicates without having
+to type all that much.
+
+These specifiers are lists consisting of functions, symbols and lists.
+
+Here's an example:
+
+@lisp
+(or gnus-article-unseen-p
+ gnus-article-unread-p)
+@end lisp
+
+The available symbols are @code{or}, @code{and} and @code{not}. The
+functions all take one parameter.
+
+@findex gnus-make-predicate
+Internally, Gnus calls @code{gnus-make-predicate} on these specifiers
+to create a function that can be called. This input parameter to this
+function will be passed along to all the functions in the predicate
+specifier.
+
+
+@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 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 Image Enhancements
+@section Image Enhancements
+
+XEmacs, as well as Emacs 21@footnote{Emacs 21 on MS Windows doesn't
+support images, Emacs 22 does.} and up, are able to display pictures and
+stuff, so Gnus has taken advantage of that.
+
+@menu
+* X-Face:: Display a funky, teensy black-and-white image.
+* Face:: Display a funkier, teensier colored image.
+* Smileys:: Show all those happy faces the way they were meant to be shown.
+* Picons:: How to display pictures of what you're reading.
+* XVarious:: Other XEmacsy Gnusey variables.
+@end menu
+
+
+@node X-Face
+@subsection X-Face
+@cindex x-face
+
+@code{X-Face} headers describe a 48x48 pixel black-and-white (1 bit
+depth) image that's supposed to represent the author of the message.
+It seems to be supported by an ever-growing number of mail and news
+readers.
+
+@cindex x-face
+@findex gnus-article-display-x-face
+@vindex gnus-article-x-face-command
+@vindex gnus-article-x-face-too-ugly
+@iftex
+@iflatex
+\include{xface}
+@end iflatex
+@end iftex
+@c @anchor{X-Face}
+
+Viewing an @code{X-Face} header either requires an Emacs that has
+@samp{compface} support (which most XEmacs versions has), or that you
+have suitable conversion or display programs installed. If your Emacs
+has image support the default action is to display the face before the
+@code{From} header. If there's no native @code{X-Face} support, Gnus
+will try to convert the @code{X-Face} header using external programs
+from the @code{pbmplus} package and friends, see below. For XEmacs it's
+faster if XEmacs has been compiled with @code{X-Face} support. The
+default action under Emacs without image support is to fork off the
+@code{display} program.
+
+On a GNU/Linux system, the @code{display} program is included in the
+ImageMagick package. For external conversion programs look for packages
+with names like @code{netpbm}, @code{libgr-progs} and @code{compface}.
+On Windows, you may use the packages @code{netpbm} and @code{compface}
+from @url{http://gnuwin32.sourceforge.net}. You need to add the
+@code{bin} directory to your @code{PATH} environment variable.
+@c In fact only the following DLLs and binaries seem to be required:
+@c compface1.dll uncompface.exe libnetpbm10.dll icontopbm.exe
+
+The variable @code{gnus-article-x-face-command} controls which programs
+are used to display the @code{X-Face} header. 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 @code{gnus-article-x-face-too-ugly} (which is a regexp) matches the
+@code{From} header, the face will not be shown.
+
+(Note: @code{x-face} is used in the variable/function names, not
+@code{xface}).
+
+@noindent
+Face and variable:
+
+@table @code
+@item gnus-x-face
+@vindex gnus-x-face
+Face to show X-Face. The colors from this face are used as the
+foreground and background colors of the displayed X-Faces. The
+default colors are black and white.
+@end table
+
+If you use posting styles, you can use an @code{x-face-file} entry in
+@code{gnus-posting-styles}, @xref{Posting Styles}. If you don't, Gnus
+provides a few convenience functions and variables to allow easier
+insertion of X-Face headers in outgoing messages. You also need the
+above mentioned ImageMagick, netpbm or other image conversion packages
+(depending the values of the variables below) for these functions.
+
+@findex gnus-random-x-face
+@vindex gnus-convert-pbm-to-x-face-command
+@vindex gnus-x-face-directory
+@code{gnus-random-x-face} goes through all the @samp{pbm} files in
+@code{gnus-x-face-directory} and picks one at random, and then
+converts it to the X-Face format by using the
+@code{gnus-convert-pbm-to-x-face-command} shell command. The
+@samp{pbm} files should be 48x48 pixels big. It returns the X-Face
+header data as a string.
+
+@findex gnus-insert-random-x-face-header
+@code{gnus-insert-random-x-face-header} calls
+@code{gnus-random-x-face} and inserts a @samp{X-Face} header with the
+randomly generated data.
+
+@findex gnus-x-face-from-file
+@vindex gnus-convert-image-to-x-face-command
+@code{gnus-x-face-from-file} takes a GIF file as the parameter, and then
+converts the file to X-Face format by using the
+@code{gnus-convert-image-to-x-face-command} shell command.
+
+Here's how you would typically use the first function. Put something
+like the following in your @file{~/.gnus.el} file:
+
+@lisp
+(setq message-required-news-headers
+ (nconc message-required-news-headers
+ (list '(X-Face . gnus-random-x-face))))
+@end lisp
+
+Using the last function would be something like this:
+
+@lisp
+(setq message-required-news-headers
+ (nconc message-required-news-headers
+ (list '(X-Face . (lambda ()
+ (gnus-x-face-from-file
+ "~/My-face.gif"))))))
+@end lisp
+
+
+@node Face
+@subsection Face
+@cindex face
+
+@c #### FIXME: faces and x-faces' implementations should really be harmonized.
+
+@code{Face} headers are essentially a funkier version of @code{X-Face}
+ones. They describe a 48x48 pixel colored image that's supposed to
+represent the author of the message.
+
+@cindex face
+@findex gnus-article-display-face
+The contents of a @code{Face} header must be a base64 encoded PNG image.
+See @uref{http://quimby.gnus.org/circus/face/} for the precise
+specifications.
+
+Viewing an @code{Face} header requires an Emacs that is able to display
+PNG images.
+@c Maybe add this:
+@c (if (featurep 'xemacs)
+@c (featurep 'png)
+@c (image-type-available-p 'png))
+
+Gnus provides a few convenience functions and variables to allow
+easier insertion of Face headers in outgoing messages.
+
+@findex gnus-convert-png-to-face
+@code{gnus-convert-png-to-face} takes a 48x48 PNG image, no longer than
+726 bytes long, and converts it to a face.
+
+@findex gnus-face-from-file
+@vindex gnus-convert-image-to-face-command
+@code{gnus-face-from-file} takes a JPEG file as the parameter, and then
+converts the file to Face format by using the
+@code{gnus-convert-image-to-face-command} shell command.
+
+Here's how you would typically use this function. Put something like the
+following in your @file{~/.gnus.el} file:
+
+@lisp
+(setq message-required-news-headers
+ (nconc message-required-news-headers
+ (list '(Face . (lambda ()
+ (gnus-face-from-file "~/face.jpg"))))))
+@end lisp
+
+
+@node Smileys
+@subsection Smileys
+@cindex smileys
+
+@iftex
+@iflatex
+\gnusfig{-3cm}{0.5cm}{\epsfig{figure=ps/BigFace,height=20cm}}
+\input{smiley}
+@end iflatex
+@end iftex
+
+@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
+(setq gnus-treat-display-smileys t)
+@end lisp
+
+Smiley maps text smiley faces---@samp{:-)}, @samp{8-)}, @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-regexp-alist
+The alist used is specified by the @code{smiley-regexp-alist}
+variable. 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:
+
+@table @code
+
+@item smiley-data-directory
+@vindex smiley-data-directory
+Where Smiley will look for smiley faces files.
+
+@item gnus-smiley-file-types
+@vindex gnus-smiley-file-types
+List of suffixes on smiley file names to try.
+
+@end table
+
+
+@node Picons
+@subsection Picons
+
+@iftex
+@iflatex
+\include{picons}
+@end iflatex
+@end iftex
+
+So@dots{} You want to slow down your news reader even more! This is a
+good way to do so. It's also a great way to impress people staring
+over your shoulder as you read news.
+
+What are Picons? To quote directly from the Picons Web site:
+
+@iftex
+@iflatex
+\margindex{}
+@end iflatex
+@end iftex
+
+@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-picon-databases
+For instructions on obtaining and installing the picons databases,
+point your Web browser at
+@uref{http://www.cs.indiana.edu/picons/ftp/index.html}.
+
+If you are using Debian GNU/Linux, saying @samp{apt-get install
+picons.*} will install the picons where Gnus can find them.
+
+To enable displaying picons, simply make sure that
+@code{gnus-picon-databases} points to the directory containing the
+Picons databases.
+
+The following variables offer control over where things are located.
+
+@table @code
+
+@item gnus-picon-databases
+@vindex gnus-picon-databases
+The location of the picons database. This is a list of directories
+containing the @file{news}, @file{domains}, @file{users} (and so on)
+subdirectories. Defaults to @code{("/usr/lib/picon"
+"/usr/local/faces")}.
+
+@item gnus-picon-news-directories
+@vindex gnus-picon-news-directories
+List of subdirectories to search in @code{gnus-picon-databases} for
+newsgroups faces. @code{("news")} is the default.
+
+@item gnus-picon-user-directories
+@vindex gnus-picon-user-directories
+List of subdirectories to search in @code{gnus-picon-databases} for user
+faces. @code{("users" "usenix" "local" "misc")} is the default.
+
+@item gnus-picon-domain-directories
+@vindex gnus-picon-domain-directories
+List of subdirectories to search in @code{gnus-picon-databases} for
+domain name faces. Defaults to @code{("domains")}. Some people may
+want to add @samp{"unknown"} to this list.
+
+@item gnus-picon-file-types
+@vindex gnus-picon-file-types
+Ordered list of suffixes on picon file names to try. Defaults to
+@code{("xpm" "gif" "xbm")} minus those not built-in your Emacs.
+
+@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-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
+
+@subsubsection Toolbar
+
+@table @code
+
+@item gnus-use-toolbar
+@vindex gnus-use-toolbar
+This variable specifies the position to display the toolbar. If
+@code{nil}, don't display toolbars. If it is non-@code{nil}, it should
+be one of the symbols @code{default}, @code{top}, @code{bottom},
+@code{right}, and @code{left}. @code{default} means to use the default
+toolbar, the rest mean to display the toolbar on the place which those
+names show. The default is @code{default}.
+
+@item gnus-toolbar-thickness
+@vindex gnus-toolbar-thickness
+Cons of the height and the width specifying the thickness of a toolbar.
+The height is used for the toolbar displayed on the top or the bottom,
+the width is used for the toolbar displayed on the right or the left.
+The default is that of the default 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
+
+@iftex
+@iflatex
+\margindex{}
+@end iflatex
+@end iftex
+
+
+@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. Here's what you can do about it.
+
+@menu
+* The problem of spam:: Some background, and some solutions
+* Anti-Spam Basics:: Simple steps to reduce the amount of spam.
+* SpamAssassin:: How to use external anti-spam tools.
+* Hashcash:: Reduce spam by burning CPU time.
+@end menu
+
+@node The problem of spam
+@subsection The problem of spam
+@cindex email spam
+@cindex spam filtering approaches
+@cindex filtering approaches, spam
+@cindex UCE
+@cindex unsolicited commercial email
+
+First, some background on spam.
+
+If you have access to e-mail, you are familiar with spam (technically
+termed @acronym{UCE}, Unsolicited Commercial E-mail). Simply put, it
+exists because e-mail delivery is very cheap compared to paper mail,
+so only a very small percentage of people need to respond to an UCE to
+make it worthwhile to the advertiser. Ironically, one of the most
+common spams is the one offering a database of e-mail addresses for
+further spamming. Senders of spam are usually called @emph{spammers},
+but terms like @emph{vermin}, @emph{scum}, @emph{sociopaths}, and
+@emph{morons} are in common use as well.
+
+Spam comes from a wide variety of sources. It is simply impossible to
+dispose of all spam without discarding useful messages. A good
+example is the TMDA system, which requires senders
+unknown to you to confirm themselves as legitimate senders before
+their e-mail can reach you. Without getting into the technical side
+of TMDA, a downside is clearly that e-mail from legitimate sources may
+be discarded if those sources can't or won't confirm themselves
+through the TMDA system. Another problem with TMDA is that it
+requires its users to have a basic understanding of e-mail delivery
+and processing.
+
+The simplest approach to filtering spam is filtering, at the mail
+server or when you sort through incoming mail. If you get 200 spam
+messages per day from @samp{random-address@@vmadmin.com}, you block
+@samp{vmadmin.com}. If you get 200 messages about @samp{VIAGRA}, you
+discard all messages with @samp{VIAGRA} in the message. If you get
+lots of spam from Bulgaria, for example, you try to filter all mail
+from Bulgarian IPs.
+
+This, unfortunately, is a great way to discard legitimate e-mail. The
+risks of blocking a whole country (Bulgaria, Norway, Nigeria, China,
+etc.) or even a continent (Asia, Africa, Europe, etc.) from contacting
+you should be obvious, so don't do it if you have the choice.
+
+In another instance, the very informative and useful RISKS digest has
+been blocked by overzealous mail filters because it @strong{contained}
+words that were common in spam messages. Nevertheless, in isolated
+cases, with great care, direct filtering of mail can be useful.
+
+Another approach to filtering e-mail is the distributed spam
+processing, for instance DCC implements such a system. In essence,
+@var{N} systems around the world agree that a machine @var{X} in
+Ghana, Estonia, or California is sending out spam e-mail, and these
+@var{N} systems enter @var{X} or the spam e-mail from @var{X} into a
+database. The criteria for spam detection vary---it may be the number
+of messages sent, the content of the messages, and so on. When a user
+of the distributed processing system wants to find out if a message is
+spam, he consults one of those @var{N} systems.
+
+Distributed spam processing works very well against spammers that send
+a large number of messages at once, but it requires the user to set up
+fairly complicated checks. There are commercial and free distributed
+spam processing systems. Distributed spam processing has its risks as
+well. For instance legitimate e-mail senders have been accused of
+sending spam, and their web sites and mailing lists have been shut
+down for some time because of the incident.
+
+The statistical approach to spam filtering is also popular. It is
+based on a statistical analysis of previous spam messages. Usually
+the analysis is a simple word frequency count, with perhaps pairs of
+words or 3-word combinations thrown into the mix. Statistical
+analysis of spam works very well in most of the cases, but it can
+classify legitimate e-mail as spam in some cases. It takes time to
+run the analysis, the full message must be analyzed, and the user has
+to store the database of spam analysis. Statistical analysis on the
+server is gaining popularity. This has the advantage of letting the
+user Just Read Mail, but has the disadvantage that it's harder to tell
+the server that it has misclassified mail.
+
+Fighting spam is not easy, no matter what anyone says. There is no
+magic switch that will distinguish Viagra ads from Mom's e-mails.
+Even people are having a hard time telling spam apart from non-spam,
+because spammers are actively looking to fool us into thinking they
+are Mom, essentially. Spamming is irritating, irresponsible, and
+idiotic behavior from a bunch of people who think the world owes them
+a favor. We hope the following sections will help you in fighting the
+spam plague.
+
+@node Anti-Spam Basics
+@subsection Anti-Spam Basics
+@cindex email spam
+@cindex spam
+@cindex UCE
+@cindex unsolicited commercial email
+
+One way of dealing with spam 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
+sysadmin 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 @acronym{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.
+
+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.
+
+Be careful with this approach. Spammers are wise to it.
+
+
+@node SpamAssassin
+@subsection SpamAssassin, Vipul's Razor, DCC, etc
+@cindex SpamAssassin
+@cindex Vipul's Razor
+@cindex DCC
+
+The days where the hints in the previous section were sufficient in
+avoiding spam are coming to an end. There are many tools out there
+that claim to reduce the amount of spam you get. This section could
+easily become outdated fast, as new products replace old, but
+fortunately most of these tools seem to have similar interfaces. Even
+though this section will use SpamAssassin as an example, it should be
+easy to adapt it to most other tools.
+
+Note that this section does not involve the @code{spam.el} package,
+which is discussed in the next section. If you don't care for all
+the features of @code{spam.el}, you can make do with these simple
+recipes.
+
+If the tool you are using is not installed on the mail server, you
+need to invoke it yourself. Ideas on how to use the
+@code{:postscript} mail source parameter (@pxref{Mail Source
+Specifiers}) follow.
+
+@lisp
+(setq mail-sources
+ '((file :prescript "formail -bs spamassassin < /var/mail/%u")
+ (pop :user "jrl"
+ :server "pophost"
+ :postscript
+ "mv %t /tmp/foo; formail -bs spamc < /tmp/foo > %t")))
+@end lisp
+
+Once you manage to process your incoming spool somehow, thus making
+the mail contain e.g.@: a header indicating it is spam, you are ready to
+filter it out. Using normal split methods (@pxref{Splitting Mail}):
+
+@lisp
+(setq nnmail-split-methods '(("spam" "^X-Spam-Flag: YES")
+ ...))
+@end lisp
+
+Or using fancy split methods (@pxref{Fancy Mail Splitting}):
+
+@lisp
+(setq nnmail-split-methods 'nnmail-split-fancy
+ nnmail-split-fancy '(| ("X-Spam-Flag" "YES" "spam")
+ ...))
+@end lisp
+
+Some people might not like the idea of piping the mail through various
+programs using a @code{:prescript} (if some program is buggy, you
+might lose all mail). If you are one of them, another solution is to
+call the external tools during splitting. Example fancy split method:
+
+@lisp
+(setq nnmail-split-fancy '(| (: kevin-spamassassin)
+ ...))
+(defun kevin-spamassassin ()
+ (save-excursion
+ (save-restriction
+ (widen)
+ (if (eq 1 (call-process-region (point-min) (point-max)
+ "spamc" nil nil nil "-c"))
+ "spam"))))
+@end lisp
+
+Note that with the nnimap backend, message bodies will not be
+downloaded by default. You need to set
+@code{nnimap-split-download-body} to @code{t} to do that
+(@pxref{Splitting in IMAP}).
+
+That is about it. As some spam is likely to get through anyway, you
+might want to have a nifty function to call when you happen to read
+spam. And here is the nifty function:
+
+@lisp
+ (defun my-gnus-raze-spam ()
+ "Submit SPAM to Vipul's Razor, then mark it as expirable."
+ (interactive)
+ (gnus-summary-show-raw-article)
+ (gnus-summary-save-in-pipe "razor-report -f -d")
+ (gnus-summary-mark-as-expirable 1))
+@end lisp
+
+@node Hashcash
+@subsection Hashcash
+@cindex hashcash
+
+A novel technique to fight spam is to require senders to do something
+costly for each message they send. This has the obvious drawback that
+you cannot rely on everyone in the world using this technique,
+since it is not part of the Internet standards, but it may be useful
+in smaller communities.
+
+While the tools in the previous section work well in practice, they
+work only because the tools are constantly maintained and updated as
+new form of spam appears. This means that a small percentage of spam
+will always get through. It also means that somewhere, someone needs
+to read lots of spam to update these tools. Hashcash avoids that, but
+instead prefers that everyone you contact through e-mail supports the
+scheme. You can view the two approaches as pragmatic vs dogmatic.
+The approaches have their own advantages and disadvantages, but as
+often in the real world, a combination of them is stronger than either
+one of them separately.
+
+@cindex X-Hashcash
+The ``something costly'' is to burn CPU time, more specifically to
+compute a hash collision up to a certain number of bits. The
+resulting hashcash cookie is inserted in a @samp{X-Hashcash:}
+header. For more details, and for the external application
+@code{hashcash} you need to install to use this feature, see
+@uref{http://www.cypherspace.org/~adam/hashcash/}. Even more
+information can be found at @uref{http://www.camram.org/}.
+
+If you wish to call hashcash for each message you send, say something
+like:
+
+@lisp
+(require 'hashcash)
+(add-hook 'message-send-hook 'mail-add-payment)
+@end lisp
+
+The @file{hashcash.el} library can be found in the Gnus development
+contrib directory or at
+@uref{http://users.actrix.gen.nz/mycroft/hashcash.el}.
+
+You will need to set up some additional variables as well:
+
+@table @code
+
+@item hashcash-default-payment
+@vindex hashcash-default-payment
+This variable indicates the default number of bits the hash collision
+should consist of. By default this is 0, meaning nothing will be
+done. Suggested useful values include 17 to 29.
+
+@item hashcash-payment-alist
+@vindex hashcash-payment-alist
+Some receivers may require you to spend burn more CPU time than the
+default. This variable contains a list of @samp{(@var{addr}
+@var{amount})} cells, where @var{addr} is the receiver (email address
+or newsgroup) and @var{amount} is the number of bits in the collision
+that is needed. It can also contain @samp{(@var{addr} @var{string}
+@var{amount})} cells, where the @var{string} is the string to use
+(normally the email address or newsgroup name is used).
+
+@item hashcash
+@vindex hashcash
+Where the @code{hashcash} binary is installed.
+
+@end table
+
+Currently there is no built in functionality in Gnus to verify
+hashcash cookies, it is expected that this is performed by your hand
+customized mail filtering scripts. Improvements in this area would be
+a useful contribution, however.
+
+@node Spam Package
+@section Spam Package
+@cindex spam filtering
+@cindex spam
+
+The Spam package provides Gnus with a centralized mechanism for
+detecting and filtering spam. It filters new mail, and processes
+messages according to whether they are spam or ham. (@dfn{Ham} is the
+name used throughout this manual to indicate non-spam messages.)
+
+@menu
+* Spam Package Introduction::
+* Filtering Incoming Mail::
+* Detecting Spam in Groups::
+* Spam and Ham Processors::
+* Spam Package Configuration Examples::
+* Spam Back Ends::
+* Extending the Spam package::
+* Spam Statistics Package::
+@end menu
+
+@node Spam Package Introduction
+@subsection Spam Package Introduction
+@cindex spam filtering
+@cindex spam filtering sequence of events
+@cindex spam
+
+You must read this section to understand how the Spam package works.
+Do not skip, speed-read, or glance through this section.
+
+@cindex spam-initialize
+@vindex spam-use-stat
+To use the Spam package, you @strong{must} first run the function
+@code{spam-initialize}:
+
+@example
+(spam-initialize)
+@end example
+
+This autoloads @code{spam.el} and installs the various hooks necessary
+to let the Spam package do its job. In order to make use of the Spam
+package, you have to set up certain group parameters and variables,
+which we will describe below. All of the variables controlling the
+Spam package can be found in the @samp{spam} customization group.
+
+There are two ``contact points'' between the Spam package and the rest
+of Gnus: checking new mail for spam, and leaving a group.
+
+Checking new mail for spam is done in one of two ways: while splitting
+incoming mail, or when you enter a group.
+
+The first way, checking for spam while splitting incoming mail, is
+suited to mail back ends such as @code{nnml} or @code{nnimap}, where
+new mail appears in a single spool file. The Spam package processes
+incoming mail, and sends mail considered to be spam to a designated
+``spam'' group. @xref{Filtering Incoming Mail}.
+
+The second way is suited to back ends such as @code{nntp}, which have
+no incoming mail spool, or back ends where the server is in charge of
+splitting incoming mail. In this case, when you enter a Gnus group,
+the unseen or unread messages in that group are checked for spam.
+Detected spam messages are marked as spam. @xref{Detecting Spam in
+Groups}.
+
+@cindex spam back ends
+In either case, you have to tell the Spam package what method to use
+to detect spam messages. There are several methods, or @dfn{spam back
+ends} (not to be confused with Gnus back ends!) to choose from: spam
+``blacklists'' and ``whitelists'', dictionary-based filters, and so
+forth. @xref{Spam Back Ends}.
+
+In the Gnus summary buffer, messages that have been identified as spam
+always appear with a @samp{$} symbol.
+
+The Spam package divides Gnus groups into three categories: ham
+groups, spam groups, and unclassified groups. You should mark each of
+the groups you subscribe to as either a ham group or a spam group,
+using the @code{spam-contents} group parameter (@pxref{Group
+Parameters}). Spam groups have a special property: when you enter a
+spam group, all unseen articles are marked as spam. Thus, mail split
+into a spam group is automatically marked as spam.
+
+Identifying spam messages is only half of the Spam package's job. The
+second half comes into play whenever you exit a group buffer. At this
+point, the Spam package does several things:
+
+First, it calls @dfn{spam and ham processors} to process the articles
+according to whether they are spam or ham. There is a pair of spam
+and ham processors associated with each spam back end, and what the
+processors do depends on the back end. At present, the main role of
+spam and ham processors is for dictionary-based spam filters: they add
+the contents of the messages in the group to the filter's dictionary,
+to improve its ability to detect future spam. The @code{spam-process}
+group parameter specifies what spam processors to use. @xref{Spam and
+Ham Processors}.
+
+If the spam filter failed to mark a spam message, you can mark it
+yourself, so that the message is processed as spam when you exit the
+group:
+
+@table @kbd
+@item M-d
+@itemx M s x
+@itemx S x
+@kindex M-d
+@kindex S x
+@kindex M s x
+@findex gnus-summary-mark-as-spam
+@findex gnus-summary-mark-as-spam
+Mark current article as spam, showing it with the @samp{$} mark
+(@code{gnus-summary-mark-as-spam}).
+@end table
+
+@noindent
+Similarly, you can unmark an article if it has been erroneously marked
+as spam. @xref{Setting Marks}.
+
+Normally, a ham message found in a non-ham group is not processed as
+ham---the rationale is that it should be moved into a ham group for
+further processing (see below). However, you can force these articles
+to be processed as ham by setting
+@code{spam-process-ham-in-spam-groups} and
+@code{spam-process-ham-in-nonham-groups}.
+
+@vindex gnus-ham-process-destinations
+@vindex gnus-spam-process-destinations
+The second thing that the Spam package does when you exit a group is
+to move ham articles out of spam groups, and spam articles out of ham
+groups. Ham in a spam group is moved to the group specified by the
+variable @code{gnus-ham-process-destinations}, or the group parameter
+@code{ham-process-destination}. Spam in a ham group is moved to the
+group specified by the variable @code{gnus-spam-process-destinations},
+or the group parameter @code{spam-process-destination}. If these
+variables are not set, the articles are left in their current group.
+If an article cannot be moved (e.g., with a read-only backend such
+as @acronym{NNTP}), it is copied.
+
+If an article is moved to another group, it is processed again when
+you visit the new group. Normally, this is not a problem, but if you
+want each article to be processed only once, load the
+@code{gnus-registry.el} package and set the variable
+@code{spam-log-to-registry} to @code{t}. @xref{Spam Package
+Configuration Examples}.
+
+Normally, spam groups ignore @code{gnus-spam-process-destinations}.
+However, if you set @code{spam-move-spam-nonspam-groups-only} to
+@code{nil}, spam will also be moved out of spam groups, depending on
+the @code{spam-process-destination} parameter.
+
+The final thing the Spam package does is to mark spam articles as
+expired, which is usually the right thing to do.
+
+If all this seems confusing, don't worry. Soon it will be as natural
+as typing Lisp one-liners on a neural interface@dots{} err, sorry, that's
+50 years in the future yet. Just trust us, it's not so bad.
+
+@node Filtering Incoming Mail
+@subsection Filtering Incoming Mail
+@cindex spam filtering
+@cindex spam filtering incoming mail
+@cindex spam
+
+To use the Spam package to filter incoming mail, you must first set up
+fancy mail splitting. @xref{Fancy Mail Splitting}. The Spam package
+defines a special splitting function that you can add to your fancy
+split variable (either @code{nnmail-split-fancy} or
+@code{nnimap-split-fancy}, depending on your mail back end):
+
+@example
+(: spam-split)
+@end example
+
+@vindex spam-split-group
+@noindent
+The @code{spam-split} function scans incoming mail according to your
+chosen spam back end(s), and sends messages identified as spam to a
+spam group. By default, the spam group is a group named @samp{spam},
+but you can change this by customizing @code{spam-split-group}. Make
+sure the contents of @code{spam-split-group} are an unqualified group
+name. For instance, in an @code{nnimap} server @samp{your-server},
+the value @samp{spam} means @samp{nnimap+your-server:spam}. The value
+@samp{nnimap+server:spam} is therefore wrong---it gives the group
+@samp{nnimap+your-server:nnimap+server:spam}.
+
+@code{spam-split} does not modify the contents of messages in any way.
+
+@vindex nnimap-split-download-body
+Note for IMAP users: if you use the @code{spam-check-bogofilter},
+@code{spam-check-ifile}, and @code{spam-check-stat} spam back ends,
+you should also set set the variable @code{nnimap-split-download-body}
+to @code{t}. These spam back ends are most useful when they can
+``scan'' the full message body. By default, the nnimap back end only
+retrieves the message headers; @code{nnimap-split-download-body} tells
+it to retrieve the message bodies as well. We don't set this by
+default because it will slow @acronym{IMAP} down, and that is not an
+appropriate decision to make on behalf of the user. @xref{Splitting
+in IMAP}.
+
+You have to specify one or more spam back ends for @code{spam-split}
+to use, by setting the @code{spam-use-*} variables. @xref{Spam Back
+Ends}. Normally, @code{spam-split} simply uses all the spam back ends
+you enabled in this way. However, you can tell @code{spam-split} to
+use only some of them. Why this is useful? Suppose you are using the
+@code{spam-use-regex-headers} and @code{spam-use-blackholes} spam back
+ends, and the following split rule:
+
+@example
+ nnimap-split-fancy '(|
+ (any "ding" "ding")
+ (: spam-split)
+ ;; @r{default mailbox}
+ "mail")
+@end example
+
+@noindent
+The problem is that you want all ding messages to make it to the ding
+folder. But that will let obvious spam (for example, spam detected by
+SpamAssassin, and @code{spam-use-regex-headers}) through, when it's
+sent to the ding list. On the other hand, some messages to the ding
+list are from a mail server in the blackhole list, so the invocation
+of @code{spam-split} can't be before the ding rule.
+
+The solution is to let SpamAssassin headers supersede ding rules, and
+perform the other @code{spam-split} rules (including a second
+invocation of the regex-headers check) after the ding rule. This is
+done by passing a parameter to @code{spam-split}:
+
+@example
+nnimap-split-fancy
+ '(|
+ ;; @r{spam detected by @code{spam-use-regex-headers} goes to @samp{regex-spam}}
+ (: spam-split "regex-spam" 'spam-use-regex-headers)
+ (any "ding" "ding")
+ ;; @r{all other spam detected by spam-split goes to @code{spam-split-group}}
+ (: spam-split)
+ ;; @r{default mailbox}
+ "mail")
+@end example
+
+@noindent
+This lets you invoke specific @code{spam-split} checks depending on
+your particular needs, and target the results of those checks to a
+particular spam group. You don't have to throw all mail into all the
+spam tests. Another reason why this is nice is that messages to
+mailing lists you have rules for don't have to have resource-intensive
+blackhole checks performed on them. You could also specify different
+spam checks for your nnmail split vs. your nnimap split. Go crazy.
+
+You should set the @code{spam-use-*} variables for whatever spam back
+ends you intend to use. The reason is that when loading
+@file{spam.el}, some conditional loading is done depending on what
+@code{spam-use-xyz} variables you have set. @xref{Spam Back Ends}.
+
+@c @emph{TODO: spam.el needs to provide a uniform way of training all the
+@c statistical databases. Some have that functionality built-in, others
+@c don't.}
+
+@node Detecting Spam in Groups
+@subsection Detecting Spam in Groups
+
+To detect spam when visiting a group, set the group's
+@code{spam-autodetect} and @code{spam-autodetect-methods} group
+parameters. These are accessible with @kbd{G c} or @kbd{G p}, as
+usual (@pxref{Group Parameters}).
+
+You should set the @code{spam-use-*} variables for whatever spam back
+ends you intend to use. The reason is that when loading
+@file{spam.el}, some conditional loading is done depending on what
+@code{spam-use-xyz} variables you have set.
+
+By default, only unseen articles are processed for spam. You can
+force Gnus to recheck all messages in the group by setting the
+variable @code{spam-autodetect-recheck-messages} to @code{t}.
+
+If you use the @code{spam-autodetect} method of checking for spam, you
+can specify different spam detection methods for different groups.
+For instance, the @samp{ding} group may have @code{spam-use-BBDB} as
+the autodetection method, while the @samp{suspect} group may have the
+@code{spam-use-blacklist} and @code{spam-use-bogofilter} methods
+enabled. Unlike with @code{spam-split}, you don't have any control
+over the @emph{sequence} of checks, but this is probably unimportant.
+
+@node Spam and Ham Processors
+@subsection Spam and Ham Processors
+@cindex spam filtering
+@cindex spam filtering variables
+@cindex spam variables
+@cindex spam
+
+@vindex gnus-spam-process-newsgroups
+Spam and ham processors specify special actions to take when you exit
+a group buffer. Spam processors act on spam messages, and ham
+processors on ham messages. At present, the main role of these
+processors is to update the dictionaries of dictionary-based spam back
+ends such as Bogofilter (@pxref{Bogofilter}) and the Spam Statistics
+package (@pxref{Spam Statistics Filtering}).
+
+The spam and ham processors that apply to each group are determined by
+the group's@code{spam-process} group parameter. If this group
+parameter is not defined, they are determined by the variable
+@code{gnus-spam-process-newsgroups}.
+
+@vindex gnus-spam-newsgroup-contents
+Gnus learns from the spam you get. You have to collect your spam in
+one or more spam groups, and set or customize the variable
+@code{spam-junk-mailgroups} as appropriate. You can also declare
+groups to contain spam by setting their group parameter
+@code{spam-contents} to @code{gnus-group-spam-classification-spam}, or
+by customizing the corresponding variable
+@code{gnus-spam-newsgroup-contents}. The @code{spam-contents} group
+parameter and the @code{gnus-spam-newsgroup-contents} variable can
+also be used to declare groups as @emph{ham} groups if you set their
+classification to @code{gnus-group-spam-classification-ham}. If
+groups are not classified by means of @code{spam-junk-mailgroups},
+@code{spam-contents}, or @code{gnus-spam-newsgroup-contents}, they are
+considered @emph{unclassified}. All groups are unclassified by
+default.
+
+@vindex gnus-spam-mark
+@cindex $
+In spam groups, all messages are considered to be spam by default:
+they get the @samp{$} mark (@code{gnus-spam-mark}) when you enter the
+group. If you have seen a message, had it marked as spam, then
+unmarked it, it won't be marked as spam when you enter the group
+thereafter. You can disable that behavior, so all unread messages
+will get the @samp{$} mark, if you set the
+@code{spam-mark-only-unseen-as-spam} parameter to @code{nil}. You
+should remove the @samp{$} mark when you are in the group summary
+buffer for every message that is not spam after all. To remove the
+@samp{$} mark, you can use @kbd{M-u} to ``unread'' the article, or
+@kbd{d} for declaring it read the non-spam way. When you leave a
+group, all spam-marked (@samp{$}) articles are sent to a spam
+processor which will study them as spam samples.
+
+Messages may also be deleted in various other ways, and unless
+@code{ham-marks} group parameter gets overridden below, marks @samp{R}
+and @samp{r} for default read or explicit delete, marks @samp{X} and
+@samp{K} for automatic or explicit kills, as well as mark @samp{Y} for
+low scores, are all considered to be associated with articles which
+are not spam. This assumption might be false, in particular if you
+use kill files or score files as means for detecting genuine spam, you
+should then adjust the @code{ham-marks} group parameter.
+
+@defvar ham-marks
+You can customize this group or topic parameter to be the list of
+marks you want to consider ham. By default, the list contains the
+deleted, read, killed, kill-filed, and low-score marks (the idea is
+that these articles have been read, but are not spam). It can be
+useful to also include the tick mark in the ham marks. It is not
+recommended to make the unread mark a ham mark, because it normally
+indicates a lack of classification. But you can do it, and we'll be
+happy for you.
+@end defvar
+
+@defvar spam-marks
+You can customize this group or topic parameter to be the list of
+marks you want to consider spam. By default, the list contains only
+the spam mark. It is not recommended to change that, but you can if
+you really want to.
+@end defvar
+
+When you leave @emph{any} group, regardless of its
+@code{spam-contents} classification, all spam-marked articles are sent
+to a spam processor, which will study these as spam samples. If you
+explicit kill a lot, you might sometimes end up with articles marked
+@samp{K} which you never saw, and which might accidentally contain
+spam. Best is to make sure that real spam is marked with @samp{$},
+and nothing else.
+
+@vindex gnus-ham-process-destinations
+When you leave a @emph{spam} group, all spam-marked articles are
+marked as expired after processing with the spam processor. This is
+not done for @emph{unclassified} or @emph{ham} groups. Also, any
+@strong{ham} articles in a spam group will be moved to a location
+determined by either the @code{ham-process-destination} group
+parameter or a match in the @code{gnus-ham-process-destinations}
+variable, which is a list of regular expressions matched with group
+names (it's easiest to customize this variable with @kbd{M-x
+customize-variable @key{RET} gnus-ham-process-destinations}). Each
+group name list is a standard Lisp list, if you prefer to customize
+the variable manually. If the @code{ham-process-destination}
+parameter is not set, ham articles are left in place. If the
+@code{spam-mark-ham-unread-before-move-from-spam-group} parameter is
+set, the ham articles are marked as unread before being moved.
+
+If ham can not be moved---because of a read-only backend such as
+@acronym{NNTP}, for example, it will be copied.
+
+Note that you can use multiples destinations per group or regular
+expression! This enables you to send your ham to a regular mail
+group and to a @emph{ham training} group.
+
+When you leave a @emph{ham} group, all ham-marked articles are sent to
+a ham processor, which will study these as non-spam samples.
+
+@vindex spam-process-ham-in-spam-groups
+By default the variable @code{spam-process-ham-in-spam-groups} is
+@code{nil}. Set it to @code{t} if you want ham found in spam groups
+to be processed. Normally this is not done, you are expected instead
+to send your ham to a ham group and process it there.
+
+@vindex spam-process-ham-in-nonham-groups
+By default the variable @code{spam-process-ham-in-nonham-groups} is
+@code{nil}. Set it to @code{t} if you want ham found in non-ham (spam
+or unclassified) groups to be processed. Normally this is not done,
+you are expected instead to send your ham to a ham group and process
+it there.
+
+@vindex gnus-spam-process-destinations
+When you leave a @emph{ham} or @emph{unclassified} group, all
+@strong{spam} articles are moved to a location determined by either
+the @code{spam-process-destination} group parameter or a match in the
+@code{gnus-spam-process-destinations} variable, which is a list of
+regular expressions matched with group names (it's easiest to
+customize this variable with @kbd{M-x customize-variable @key{RET}
+gnus-spam-process-destinations}). Each group name list is a standard
+Lisp list, if you prefer to customize the variable manually. If the
+@code{spam-process-destination} parameter is not set, the spam
+articles are only expired. The group name is fully qualified, meaning
+that if you see @samp{nntp:servername} before the group name in the
+group buffer then you need it here as well.
+
+If spam can not be moved---because of a read-only backend such as
+@acronym{NNTP}, for example, it will be copied.
+
+Note that you can use multiples destinations per group or regular
+expression! This enables you to send your spam to multiple @emph{spam
+training} groups.
+
+@vindex spam-log-to-registry
+The problem with processing ham and spam is that Gnus doesn't track
+this processing by default. Enable the @code{spam-log-to-registry}
+variable so @code{spam.el} will use @code{gnus-registry.el} to track
+what articles have been processed, and avoid processing articles
+multiple times. Keep in mind that if you limit the number of registry
+entries, this won't work as well as it does without a limit.
+
+@vindex spam-mark-only-unseen-as-spam
+Set this variable if you want only unseen articles in spam groups to
+be marked as spam. By default, it is set. If you set it to
+@code{nil}, unread articles will also be marked as spam.
+
+@vindex spam-mark-ham-unread-before-move-from-spam-group
+Set this variable if you want ham to be unmarked before it is moved
+out of the spam group. This is very useful when you use something
+like the tick mark @samp{!} to mark ham---the article will be placed
+in your @code{ham-process-destination}, unmarked as if it came fresh
+from the mail server.
+
+@vindex spam-autodetect-recheck-messages
+When autodetecting spam, this variable tells @code{spam.el} whether
+only unseen articles or all unread articles should be checked for
+spam. It is recommended that you leave it off.
+
+@node Spam Package Configuration Examples
+@subsection Spam Package Configuration Examples
+@cindex spam filtering
+@cindex spam filtering configuration examples
+@cindex spam configuration examples
+@cindex spam
+
+@subsubheading Ted's setup
+
+From Ted Zlatanov <tzz@@lifelogs.com>.
+@example
+;; @r{for @code{gnus-registry-split-fancy-with-parent} and spam autodetection}
+;; @r{see @file{gnus-registry.el} for more information}
+(gnus-registry-initialize)
+(spam-initialize)
+
+(setq
+ spam-log-to-registry t ; @r{for spam autodetection}
+ spam-use-BBDB t
+ spam-use-regex-headers t ; @r{catch X-Spam-Flag (SpamAssassin)}
+ ;; @r{all groups with @samp{spam} in the name contain spam}
+ gnus-spam-newsgroup-contents
+ '(("spam" gnus-group-spam-classification-spam))
+ ;; @r{see documentation for these}
+ spam-move-spam-nonspam-groups-only nil
+ spam-mark-only-unseen-as-spam t
+ spam-mark-ham-unread-before-move-from-spam-group t
+ nnimap-split-rule 'nnimap-split-fancy
+ ;; @r{understand what this does before you copy it to your own setup!}
+ nnimap-split-fancy '(|
+ ;; @r{trace references to parents and put in their group}
+ (: gnus-registry-split-fancy-with-parent)
+ ;; @r{this will catch server-side SpamAssassin tags}
+ (: spam-split 'spam-use-regex-headers)
+ (any "ding" "ding")
+ ;; @r{note that spam by default will go to @samp{spam}}
+ (: spam-split)
+ ;; @r{default mailbox}
+ "mail"))
+
+;; @r{my parameters, set with @kbd{G p}}
+
+;; @r{all nnml groups, and all nnimap groups except}
+;; @r{@samp{nnimap+mail.lifelogs.com:train} and}
+;; @r{@samp{nnimap+mail.lifelogs.com:spam}: any spam goes to nnimap training,}
+;; @r{because it must have been detected manually}
+
+((spam-process-destination . "nnimap+mail.lifelogs.com:train"))
+
+;; @r{all @acronym{NNTP} groups}
+;; @r{autodetect spam with the blacklist and ham with the BBDB}
+((spam-autodetect-methods spam-use-blacklist spam-use-BBDB)
+;; @r{send all spam to the training group}
+ (spam-process-destination . "nnimap+mail.lifelogs.com:train"))
+
+;; @r{only some @acronym{NNTP} groups, where I want to autodetect spam}
+((spam-autodetect . t))
+
+;; @r{my nnimap @samp{nnimap+mail.lifelogs.com:spam} group}
+
+;; @r{this is a spam group}
+((spam-contents gnus-group-spam-classification-spam)
+
+ ;; @r{any spam (which happens when I enter for all unseen messages,}
+ ;; @r{because of the @code{gnus-spam-newsgroup-contents} setting above), goes to}
+ ;; @r{@samp{nnimap+mail.lifelogs.com:train} unless I mark it as ham}
+
+ (spam-process-destination "nnimap+mail.lifelogs.com:train")
+
+ ;; @r{any ham goes to my @samp{nnimap+mail.lifelogs.com:mail} folder, but}
+ ;; @r{also to my @samp{nnimap+mail.lifelogs.com:trainham} folder for training}
+
+ (ham-process-destination "nnimap+mail.lifelogs.com:mail"
+ "nnimap+mail.lifelogs.com:trainham")
+ ;; @r{in this group, only @samp{!} marks are ham}
+ (ham-marks
+ (gnus-ticked-mark))
+ ;; @r{remembers senders in the blacklist on the way out---this is}
+ ;; @r{definitely not needed, it just makes me feel better}
+ (spam-process (gnus-group-spam-exit-processor-blacklist)))
+
+;; @r{Later, on the @acronym{IMAP} server I use the @samp{train} group for training}
+;; @r{SpamAssassin to recognize spam, and the @samp{trainham} group fora}
+;; @r{recognizing ham---but Gnus has nothing to do with it.}
+
+@end example
+
+@subsubheading Using @file{spam.el} on an IMAP server with a statistical filter on the server
+From Reiner Steib <reiner.steib@@gmx.de>.
+
+My provider has set up bogofilter (in combination with @acronym{DCC}) on
+the mail server (@acronym{IMAP}). Recognized spam goes to
+@samp{spam.detected}, the rest goes through the normal filter rules,
+i.e. to @samp{some.folder} or to @samp{INBOX}. Training on false
+positives or negatives is done by copying or moving the article to
+@samp{training.ham} or @samp{training.spam} respectively. A cron job on
+the server feeds those to bogofilter with the suitable ham or spam
+options and deletes them from the @samp{training.ham} and
+@samp{training.spam} folders.
+
+With the following entries in @code{gnus-parameters}, @code{spam.el}
+does most of the job for me:
+
+@lisp
+ ("nnimap:spam\\.detected"
+ (gnus-article-sort-functions '(gnus-article-sort-by-chars))
+ (ham-process-destination "nnimap:INBOX" "nnimap:training.ham")
+ (spam-contents gnus-group-spam-classification-spam))
+ ("nnimap:\\(INBOX\\|other-folders\\)"
+ (spam-process-destination . "nnimap:training.spam")
+ (spam-contents gnus-group-spam-classification-ham))
+@end lisp
+
+@itemize
+
+@item @b{The Spam folder:}
+
+In the folder @samp{spam.detected}, I have to check for false positives
+(i.e. legitimate mails, that were wrongly judged as spam by
+bogofilter or DCC).
+
+Because of the @code{gnus-group-spam-classification-spam} entry, all
+messages are marked as spam (with @code{$}). When I find a false
+positive, I mark the message with some other ham mark
+(@code{ham-marks}, @ref{Spam and Ham Processors}). On group exit,
+those messages are copied to both groups, @samp{INBOX} (where I want
+to have the article) and @samp{training.ham} (for training bogofilter)
+and deleted from the @samp{spam.detected} folder.
+
+The @code{gnus-article-sort-by-chars} entry simplifies detection of
+false positives for me. I receive lots of worms (sweN, @dots{}), that all
+have a similar size. Grouping them by size (i.e. chars) makes finding
+other false positives easier. (Of course worms aren't @i{spam}
+(@acronym{UCE}, @acronym{UBE}) strictly speaking. Anyhow, bogofilter is
+an excellent tool for filtering those unwanted mails for me.)
+
+@item @b{Ham folders:}
+
+In my ham folders, I just hit @kbd{S x}
+(@code{gnus-summary-mark-as-spam}) whenever I see an unrecognized spam
+mail (false negative). On group exit, those messages are moved to
+@samp{training.ham}.
+@end itemize
+
+@subsubheading Reporting spam articles in Gmane groups with @code{spam-report.el}
+
+From Reiner Steib <reiner.steib@@gmx.de>.
+
+With following entry in @code{gnus-parameters}, @kbd{S x}
+(@code{gnus-summary-mark-as-spam}) marks articles in @code{gmane.*}
+groups as spam and reports the to Gmane at group exit:
+
+@lisp
+ ("^gmane\\."
+ (spam-process (gnus-group-spam-exit-processor-report-gmane)))
+@end lisp
+
+Additionally, I use @code{(setq spam-report-gmane-use-article-number nil)}
+because I don't read the groups directly from news.gmane.org, but
+through my local news server (leafnode). I.e. the article numbers are
+not the same as on news.gmane.org, thus @code{spam-report.el} has to check
+the @code{X-Report-Spam} header to find the correct number.
+
+@node Spam Back Ends
+@subsection Spam Back Ends
+@cindex spam back ends
+
+The spam package offers a variety of back ends for detecting spam.
+Each back end defines a set of methods for detecting spam
+(@pxref{Filtering Incoming Mail}, @pxref{Detecting Spam in Groups}),
+and a pair of spam and ham processors (@pxref{Spam and Ham
+Processors}).
+
+@menu
+* Blacklists and Whitelists::
+* BBDB Whitelists::
+* Gmane Spam Reporting::
+* Anti-spam Hashcash Payments::
+* Blackholes::
+* Regular Expressions Header Matching::
+* Bogofilter::
+* ifile spam filtering::
+* Spam Statistics Filtering::
+* SpamOracle::
+@end menu
+
+@node Blacklists and Whitelists
+@subsubsection Blacklists and Whitelists
+@cindex spam filtering
+@cindex whitelists, spam filtering
+@cindex blacklists, spam filtering
+@cindex spam
+
+@defvar spam-use-blacklist
+
+Set this variable to @code{t} if you want to use blacklists when
+splitting incoming mail. Messages whose senders are in the blacklist
+will be sent to the @code{spam-split-group}. This is an explicit
+filter, meaning that it acts only on mail senders @emph{declared} to
+be spammers.
+
+@end defvar
+
+@defvar spam-use-whitelist
+
+Set this variable to @code{t} if you want to use whitelists when
+splitting incoming mail. Messages whose senders are not in the
+whitelist will be sent to the next spam-split rule. This is an
+explicit filter, meaning that unless someone is in the whitelist, their
+messages are not assumed to be spam or ham.
+
+@end defvar
+
+@defvar spam-use-whitelist-exclusive
+
+Set this variable to @code{t} if you want to use whitelists as an
+implicit filter, meaning that every message will be considered spam
+unless the sender is in the whitelist. Use with care.
+
+@end defvar
+
+@defvar gnus-group-spam-exit-processor-blacklist
+
+Add this symbol to a group's @code{spam-process} parameter by
+customizing the group parameters or the
+@code{gnus-spam-process-newsgroups} variable. When this symbol is
+added to a group's @code{spam-process} parameter, the senders of
+spam-marked articles will be added to the blacklist.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-spam-exit-processor-blacklist}, it is recommended
+that you use @code{'(spam spam-use-blacklist)}. Everything will work
+the same way, we promise.
+
+@end defvar
+
+@defvar gnus-group-ham-exit-processor-whitelist
+
+Add this symbol to a group's @code{spam-process} parameter by
+customizing the group parameters or the
+@code{gnus-spam-process-newsgroups} variable. When this symbol is
+added to a group's @code{spam-process} parameter, the senders of
+ham-marked articles in @emph{ham} groups will be added to the
+whitelist. Note that this ham processor has no effect in @emph{spam}
+or @emph{unclassified} groups.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-ham-exit-processor-whitelist}, it is recommended
+that you use @code{'(ham spam-use-whitelist)}. Everything will work
+the same way, we promise.
+
+@end defvar
+
+Blacklists are lists of regular expressions matching addresses you
+consider to be spam senders. For instance, to block mail from any
+sender at @samp{vmadmin.com}, you can put @samp{vmadmin.com} in your
+blacklist. You start out with an empty blacklist. Blacklist entries
+use the Emacs regular expression syntax.
+
+Conversely, whitelists tell Gnus what addresses are considered
+legitimate. All messages from whitelisted addresses are considered
+non-spam. Also see @ref{BBDB Whitelists}. Whitelist entries use the
+Emacs regular expression syntax.
+
+The blacklist and whitelist file locations can be customized with the
+@code{spam-directory} variable (@file{~/News/spam} by default), or
+the @code{spam-whitelist} and @code{spam-blacklist} variables
+directly. The whitelist and blacklist files will by default be in the
+@code{spam-directory} directory, named @file{whitelist} and
+@file{blacklist} respectively.
+
+@node BBDB Whitelists
+@subsubsection BBDB Whitelists
+@cindex spam filtering
+@cindex BBDB whitelists, spam filtering
+@cindex BBDB, spam filtering
+@cindex spam
+
+@defvar spam-use-BBDB
+
+Analogous to @code{spam-use-whitelist} (@pxref{Blacklists and
+Whitelists}), but uses the BBDB as the source of whitelisted
+addresses, without regular expressions. You must have the BBDB loaded
+for @code{spam-use-BBDB} to work properly. Messages whose senders are
+not in the BBDB will be sent to the next spam-split rule. This is an
+explicit filter, meaning that unless someone is in the BBDB, their
+messages are not assumed to be spam or ham.
+
+@end defvar
+
+@defvar spam-use-BBDB-exclusive
+
+Set this variable to @code{t} if you want to use the BBDB as an
+implicit filter, meaning that every message will be considered spam
+unless the sender is in the BBDB. Use with care. Only sender
+addresses in the BBDB will be allowed through; all others will be
+classified as spammers.
+
+@end defvar
+
+@defvar gnus-group-ham-exit-processor-BBDB
+
+Add this symbol to a group's @code{spam-process} parameter by
+customizing the group parameters or the
+@code{gnus-spam-process-newsgroups} variable. When this symbol is
+added to a group's @code{spam-process} parameter, the senders of
+ham-marked articles in @emph{ham} groups will be added to the
+BBDB. Note that this ham processor has no effect in @emph{spam}
+or @emph{unclassified} groups.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-ham-exit-processor-BBDB}, it is recommended
+that you use @code{'(ham spam-use-BBDB)}. Everything will work
+the same way, we promise.
+
+@end defvar
+
+@node Gmane Spam Reporting
+@subsubsection Gmane Spam Reporting
+@cindex spam reporting
+@cindex Gmane, spam reporting
+@cindex Gmane, spam reporting
+@cindex spam
+
+@defvar gnus-group-spam-exit-processor-report-gmane
+
+Add this symbol to a group's @code{spam-process} parameter by
+customizing the group parameters or the
+@code{gnus-spam-process-newsgroups} variable. When this symbol is
+added to a group's @code{spam-process} parameter, the spam-marked
+articles groups will be reported to the Gmane administrators via a
+HTTP request.
+
+Gmane can be found at @uref{http://gmane.org}.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-spam-exit-processor-report-gmane}, it is recommended
+that you use @code{'(spam spam-use-gmane)}. Everything will work the
+same way, we promise.
+
+@end defvar
+
+@defvar spam-report-gmane-use-article-number
+
+This variable is @code{t} by default. Set it to @code{nil} if you are
+running your own news server, for instance, and the local article
+numbers don't correspond to the Gmane article numbers. When
+@code{spam-report-gmane-use-article-number} is @code{nil},
+@code{spam-report.el} will use the @code{X-Report-Spam} header that
+Gmane provides.
+
+@end defvar
+
+@node Anti-spam Hashcash Payments
+@subsubsection Anti-spam Hashcash Payments
+@cindex spam filtering
+@cindex hashcash, spam filtering
+@cindex spam
+
+@defvar spam-use-hashcash
+
+Similar to @code{spam-use-whitelist} (@pxref{Blacklists and
+Whitelists}), but uses hashcash tokens for whitelisting messages
+instead of the sender address. You must have the @code{hashcash.el}
+package loaded for @code{spam-use-hashcash} to work properly.
+Messages without a hashcash payment token will be sent to the next
+spam-split rule. This is an explicit filter, meaning that unless a
+hashcash token is found, the messages are not assumed to be spam or
+ham.
+
+@end defvar
+
+@node Blackholes
+@subsubsection Blackholes
+@cindex spam filtering
+@cindex blackholes, spam filtering
+@cindex spam
+
+@defvar spam-use-blackholes
+
+This option is disabled by default. You can let Gnus consult the
+blackhole-type distributed spam processing systems (DCC, for instance)
+when you set this option. The variable @code{spam-blackhole-servers}
+holds the list of blackhole servers Gnus will consult. The current
+list is fairly comprehensive, but make sure to let us know if it
+contains outdated servers.
+
+The blackhole check uses the @code{dig.el} package, but you can tell
+@file{spam.el} to use @code{dns.el} instead for better performance if
+you set @code{spam-use-dig} to @code{nil}. It is not recommended at
+this time to set @code{spam-use-dig} to @code{nil} despite the
+possible performance improvements, because some users may be unable to
+use it, but you can try it and see if it works for you.
+
+@end defvar
+
+@defvar spam-blackhole-servers
+
+The list of servers to consult for blackhole checks.
+
+@end defvar
+
+@defvar spam-blackhole-good-server-regex
+
+A regular expression for IPs that should not be checked against the
+blackhole server list. When set to @code{nil}, it has no effect.
+
+@end defvar
+
+@defvar spam-use-dig
+
+Use the @code{dig.el} package instead of the @code{dns.el} package.
+The default setting of @code{t} is recommended.
+
+@end defvar
+
+Blackhole checks are done only on incoming mail. There is no spam or
+ham processor for blackholes.
+
+@node Regular Expressions Header Matching
+@subsubsection Regular Expressions Header Matching
+@cindex spam filtering
+@cindex regular expressions header matching, spam filtering
+@cindex spam
+
+@defvar spam-use-regex-headers
+
+This option is disabled by default. You can let Gnus check the
+message headers against lists of regular expressions when you set this
+option. The variables @code{spam-regex-headers-spam} and
+@code{spam-regex-headers-ham} hold the list of regular expressions.
+Gnus will check against the message headers to determine if the
+message is spam or ham, respectively.
+
+@end defvar
+
+@defvar spam-regex-headers-spam
+
+The list of regular expressions that, when matched in the headers of
+the message, positively identify it as spam.
+
+@end defvar
+
+@defvar spam-regex-headers-ham
+
+The list of regular expressions that, when matched in the headers of
+the message, positively identify it as ham.
+
+@end defvar
+
+Regular expression header checks are done only on incoming mail.
+There is no specific spam or ham processor for regular expressions.
+
+@node Bogofilter
+@subsubsection Bogofilter
+@cindex spam filtering
+@cindex bogofilter, spam filtering
+@cindex spam
+
+@defvar spam-use-bogofilter
+
+Set this variable if you want @code{spam-split} to use Eric Raymond's
+speedy Bogofilter.
+
+With a minimum of care for associating the @samp{$} mark for spam
+articles only, Bogofilter training all gets fairly automatic. You
+should do this until you get a few hundreds of articles in each
+category, spam or not. The command @kbd{S t} in summary mode, either
+for debugging or for curiosity, shows the @emph{spamicity} score of
+the current article (between 0.0 and 1.0).
+
+Bogofilter determines if a message is spam based on a specific
+threshold. That threshold can be customized, consult the Bogofilter
+documentation.
+
+If the @code{bogofilter} executable is not in your path, Bogofilter
+processing will be turned off.
+
+You should not enable this if you use @code{spam-use-bogofilter-headers}.
+
+@end defvar
+
+@table @kbd
+@item M s t
+@itemx S t
+@kindex M s t
+@kindex S t
+@findex spam-bogofilter-score
+Get the Bogofilter spamicity score (@code{spam-bogofilter-score}).
+@end table
+
+@defvar spam-use-bogofilter-headers
+
+Set this variable if you want @code{spam-split} to use Eric Raymond's
+speedy Bogofilter, looking only at the message headers. It works
+similarly to @code{spam-use-bogofilter}, but the @code{X-Bogosity} header
+must be in the message already. Normally you would do this with a
+procmail recipe or something similar; consult the Bogofilter
+installation documents for details.
+
+You should not enable this if you use @code{spam-use-bogofilter}.
+
+@end defvar
+
+@defvar gnus-group-spam-exit-processor-bogofilter
+Add this symbol to a group's @code{spam-process} parameter by
+customizing the group parameters or the
+@code{gnus-spam-process-newsgroups} variable. When this symbol is
+added to a group's @code{spam-process} parameter, spam-marked articles
+will be added to the Bogofilter spam database.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-spam-exit-processor-bogofilter}, it is recommended
+that you use @code{'(spam spam-use-bogofilter)}. Everything will work
+the same way, we promise.
+@end defvar
+
+@defvar gnus-group-ham-exit-processor-bogofilter
+Add this symbol to a group's @code{spam-process} parameter by
+customizing the group parameters or the
+@code{gnus-spam-process-newsgroups} variable. When this symbol is
+added to a group's @code{spam-process} parameter, the ham-marked
+articles in @emph{ham} groups will be added to the Bogofilter database
+of non-spam messages. Note that this ham processor has no effect in
+@emph{spam} or @emph{unclassified} groups.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-ham-exit-processor-bogofilter}, it is recommended
+that you use @code{'(ham spam-use-bogofilter)}. Everything will work
+the same way, we promise.
+@end defvar
+
+@defvar spam-bogofilter-database-directory
+
+This is the directory where Bogofilter will store its databases. It
+is not specified by default, so Bogofilter will use its own default
+database directory.
+
+@end defvar
+
+The Bogofilter mail classifier is similar to @command{ifile} in intent and
+purpose. A ham and a spam processor are provided, plus the
+@code{spam-use-bogofilter} and @code{spam-use-bogofilter-headers}
+variables to indicate to spam-split that Bogofilter should either be
+used, or has already been used on the article. The 0.9.2.1 version of
+Bogofilter was used to test this functionality.
+
+@node ifile spam filtering
+@subsubsection ifile spam filtering
+@cindex spam filtering
+@cindex ifile, spam filtering
+@cindex spam
+
+@defvar spam-use-ifile
+
+Enable this variable if you want @code{spam-split} to use @command{ifile}, a
+statistical analyzer similar to Bogofilter.
+
+@end defvar
+
+@defvar spam-ifile-all-categories
+
+Enable this variable if you want @code{spam-use-ifile} to give you all
+the ifile categories, not just spam/non-spam. If you use this, make
+sure you train ifile as described in its documentation.
+
+@end defvar
+
+@defvar spam-ifile-spam-category
+
+This is the category of spam messages as far as ifile is concerned.
+The actual string used is irrelevant, but you probably want to leave
+the default value of @samp{spam}.
+@end defvar
+
+@defvar spam-ifile-database
+
+This is the filename for the ifile database. It is not specified by
+default, so ifile will use its own default database name.
+
+@end defvar
+
+The ifile mail classifier is similar to Bogofilter in intent and
+purpose. A ham and a spam processor are provided, plus the
+@code{spam-use-ifile} variable to indicate to spam-split that ifile
+should be used. The 1.2.1 version of ifile was used to test this
+functionality.
+
+@node Spam Statistics Filtering
+@subsubsection Spam Statistics Filtering
+@cindex spam filtering
+@cindex spam-stat, spam filtering
+@cindex spam-stat
+@cindex spam
+
+This back end uses the Spam Statistics Emacs Lisp package to perform
+statistics-based filtering (@pxref{Spam Statistics Package}). Before
+using this, you may want to perform some additional steps to
+initialize your Spam Statistics dictionary. @xref{Creating a
+spam-stat dictionary}.
+
+@defvar spam-use-stat
+
+@end defvar
+
+@defvar gnus-group-spam-exit-processor-stat
+Add this symbol to a group's @code{spam-process} parameter by
+customizing the group parameters or the
+@code{gnus-spam-process-newsgroups} variable. When this symbol is
+added to a group's @code{spam-process} parameter, the spam-marked
+articles will be added to the spam-stat database of spam messages.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-spam-exit-processor-stat}, it is recommended
+that you use @code{'(spam spam-use-stat)}. Everything will work
+the same way, we promise.
+@end defvar
+
+@defvar gnus-group-ham-exit-processor-stat
+Add this symbol to a group's @code{spam-process} parameter by
+customizing the group parameters or the
+@code{gnus-spam-process-newsgroups} variable. When this symbol is
+added to a group's @code{spam-process} parameter, the ham-marked
+articles in @emph{ham} groups will be added to the spam-stat database
+of non-spam messages. Note that this ham processor has no effect in
+@emph{spam} or @emph{unclassified} groups.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-ham-exit-processor-stat}, it is recommended
+that you use @code{'(ham spam-use-stat)}. Everything will work
+the same way, we promise.
+@end defvar
+
+This enables @file{spam.el} to cooperate with @file{spam-stat.el}.
+@file{spam-stat.el} provides an internal (Lisp-only) spam database,
+which unlike ifile or Bogofilter does not require external programs.
+A spam and a ham processor, and the @code{spam-use-stat} variable for
+@code{spam-split} are provided.
+
+@node SpamOracle
+@subsubsection Using SpamOracle with Gnus
+@cindex spam filtering
+@cindex SpamOracle
+@cindex spam
+
+An easy way to filter out spam is to use SpamOracle. SpamOracle is an
+statistical mail filtering tool written by Xavier Leroy and needs to be
+installed separately.
+
+There are several ways to use SpamOracle with Gnus. In all cases, your
+mail is piped through SpamOracle in its @emph{mark} mode. SpamOracle will
+then enter an @samp{X-Spam} header indicating whether it regards the
+mail as a spam mail or not.
+
+One possibility is to run SpamOracle as a @code{:prescript} from the
+@xref{Mail Source Specifiers}, (@pxref{SpamAssassin}). This method has
+the advantage that the user can see the @emph{X-Spam} headers.
+
+The easiest method is to make @file{spam.el} (@pxref{Spam Package})
+call SpamOracle.
+
+@vindex spam-use-spamoracle
+To enable SpamOracle usage by @file{spam.el}, set the variable
+@code{spam-use-spamoracle} to @code{t} and configure the
+@code{nnmail-split-fancy} or @code{nnimap-split-fancy}. @xref{Spam
+Package}. In this example the @samp{INBOX} of an nnimap server is
+filtered using SpamOracle. Mails recognized as spam mails will be
+moved to @code{spam-split-group}, @samp{Junk} in this case. Ham
+messages stay in @samp{INBOX}:
+
+@example
+(setq spam-use-spamoracle t
+ spam-split-group "Junk"
+ nnimap-split-inbox '("INBOX")
+ nnimap-split-rule 'nnimap-split-fancy
+ nnimap-split-fancy '(| (: spam-split) "INBOX"))
+@end example
+
+@defvar spam-use-spamoracle
+Set to @code{t} if you want Gnus to enable spam filtering using
+SpamOracle.
+@end defvar
+
+@defvar spam-spamoracle-binary
+Gnus uses the SpamOracle binary called @file{spamoracle} found in the
+user's PATH. Using the variable @code{spam-spamoracle-binary}, this
+can be customized.
+@end defvar
+
+@defvar spam-spamoracle-database
+By default, SpamOracle uses the file @file{~/.spamoracle.db} as a database to
+store its analysis. This is controlled by the variable
+@code{spam-spamoracle-database} which defaults to @code{nil}. That means
+the default SpamOracle database will be used. In case you want your
+database to live somewhere special, set
+@code{spam-spamoracle-database} to this path.
+@end defvar
+
+SpamOracle employs a statistical algorithm to determine whether a
+message is spam or ham. In order to get good results, meaning few
+false hits or misses, SpamOracle needs training. SpamOracle learns
+the characteristics of your spam mails. Using the @emph{add} mode
+(training mode) one has to feed good (ham) and spam mails to
+SpamOracle. This can be done by pressing @kbd{|} in the Summary
+buffer and pipe the mail to a SpamOracle process or using
+@file{spam.el}'s spam- and ham-processors, which is much more
+convenient. For a detailed description of spam- and ham-processors,
+@xref{Spam Package}.
+
+@defvar gnus-group-spam-exit-processor-spamoracle
+Add this symbol to a group's @code{spam-process} parameter by
+customizing the group parameter or the
+@code{gnus-spam-process-newsgroups} variable. When this symbol is added
+to a group's @code{spam-process} parameter, spam-marked articles will be
+sent to SpamOracle as spam samples.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-spam-exit-processor-spamoracle}, it is recommended
+that you use @code{'(spam spam-use-spamoracle)}. Everything will work
+the same way, we promise.
+@end defvar
+
+@defvar gnus-group-ham-exit-processor-spamoracle
+Add this symbol to a group's @code{spam-process} parameter by
+customizing the group parameter or the
+@code{gnus-spam-process-newsgroups} variable. When this symbol is added
+to a group's @code{spam-process} parameter, the ham-marked articles in
+@emph{ham} groups will be sent to the SpamOracle as samples of ham
+messages. Note that this ham processor has no effect in @emph{spam} or
+@emph{unclassified} groups.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-ham-exit-processor-spamoracle}, it is recommended
+that you use @code{'(ham spam-use-spamoracle)}. Everything will work
+the same way, we promise.
+@end defvar
+
+@emph{Example:} These are the Group Parameters of a group that has been
+classified as a ham group, meaning that it should only contain ham
+messages.
+@example
+ ((spam-contents gnus-group-spam-classification-ham)
+ (spam-process ((ham spam-use-spamoracle)
+ (spam spam-use-spamoracle))))
+@end example
+For this group the @code{spam-use-spamoracle} is installed for both
+ham and spam processing. If the group contains spam message
+(e.g. because SpamOracle has not had enough sample messages yet) and
+the user marks some messages as spam messages, these messages will be
+processed by SpamOracle. The processor sends the messages to
+SpamOracle as new samples for spam.
+
+@node Extending the Spam package
+@subsection Extending the Spam package
+@cindex spam filtering
+@cindex spam elisp package, extending
+@cindex extending the spam elisp package
+
+Say you want to add a new back end called blackbox. For filtering
+incoming mail, provide the following:
+
+@enumerate
+
+@item
+Code
+
+@lisp
+(defvar spam-use-blackbox nil
+ "True if blackbox should be used.")
+@end lisp
+
+Add
+@lisp
+(spam-use-blackbox . spam-check-blackbox)
+@end lisp
+to @code{spam-list-of-checks}.
+
+Add
+@lisp
+(gnus-group-ham-exit-processor-blackbox ham spam-use-blackbox)
+(gnus-group-spam-exit-processor-blackbox spam spam-use-blackbox)
+@end lisp
+
+to @code{spam-list-of-processors}.
+
+Add
+@lisp
+(spam-use-blackbox spam-blackbox-register-routine
+ nil
+ spam-blackbox-unregister-routine
+ nil)
+@end lisp
+
+to @code{spam-registration-functions}. Write the register/unregister
+routines using the bogofilter register/unregister routines as a
+start, or other register/unregister routines more appropriate to
+Blackbox.
+
+@item
+Functionality
+
+Write the @code{spam-check-blackbox} function. It should return
+@samp{nil} or @code{spam-split-group}, observing the other
+conventions. See the existing @code{spam-check-*} functions for
+examples of what you can do, and stick to the template unless you
+fully understand the reasons why you aren't.
+
+Make sure to add @code{spam-use-blackbox} to
+@code{spam-list-of-statistical-checks} if Blackbox is a statistical
+mail analyzer that needs the full message body to operate.
+
+@end enumerate
+
+For processing spam and ham messages, provide the following:
+
+@enumerate
+
+@item
+Code
+
+Note you don't have to provide a spam or a ham processor. Only
+provide them if Blackbox supports spam or ham processing.
+
+Also, ham and spam processors are being phased out as single
+variables. Instead the form @code{'(spam spam-use-blackbox)} or
+@code{'(ham spam-use-blackbox)} is favored. For now, spam/ham
+processor variables are still around but they won't be for long.
+
+@lisp
+(defvar gnus-group-spam-exit-processor-blackbox "blackbox-spam"
+ "The Blackbox summary exit spam processor.
+Only applicable to spam groups.")
+
+(defvar gnus-group-ham-exit-processor-blackbox "blackbox-ham"
+ "The whitelist summary exit ham processor.
+Only applicable to non-spam (unclassified and ham) groups.")
+
+@end lisp
+
+@item
+Gnus parameters
+
+Add
+@lisp
+(const :tag "Spam: Blackbox" (spam spam-use-blackbox))
+(const :tag "Ham: Blackbox" (ham spam-use-blackbox))
+@end lisp
+to the @code{spam-process} group parameter in @code{gnus.el}. Make
+sure you do it twice, once for the parameter and once for the
+variable customization.
+
+Add
+@lisp
+(variable-item spam-use-blackbox)
+@end lisp
+to the @code{spam-autodetect-methods} group parameter in
+@code{gnus.el}.
+
+@end enumerate
+
+@node Spam Statistics Package
+@subsection Spam Statistics Package
+@cindex Paul Graham
+@cindex Graham, Paul
+@cindex naive Bayesian spam filtering
+@cindex Bayesian spam filtering, naive
+@cindex spam filtering, naive Bayesian
+
+Paul Graham has written an excellent essay about spam filtering using
+statistics: @uref{http://www.paulgraham.com/spam.html,A Plan for
+Spam}. In it he describes the inherent deficiency of rule-based
+filtering as used by SpamAssassin, for example: Somebody has to write
+the rules, and everybody else has to install these rules. You are
+always late. It would be much better, he argues, to filter mail based
+on whether it somehow resembles spam or non-spam. One way to measure
+this is word distribution. He then goes on to describe a solution
+that checks whether a new mail resembles any of your other spam mails
+or not.
+
+The basic idea is this: Create a two collections of your mail, one
+with spam, one with non-spam. Count how often each word appears in
+either collection, weight this by the total number of mails in the
+collections, and store this information in a dictionary. For every
+word in a new mail, determine its probability to belong to a spam or a
+non-spam mail. Use the 15 most conspicuous words, compute the total
+probability of the mail being spam. If this probability is higher
+than a certain threshold, the mail is considered to be spam.
+
+The Spam Statistics package adds support to Gnus for this kind of
+filtering. It can be used as one of the back ends of the Spam package
+(@pxref{Spam Package}), or by itself.
+
+Before using the Spam Statistics package, you need to set it up.
+First, you need two collections of your mail, one with spam, one with
+non-spam. Then you need to create a dictionary using these two
+collections, and save it. And last but not least, you need to use
+this dictionary in your fancy mail splitting rules.
+
+@menu
+* Creating a spam-stat dictionary::
+* Splitting mail using spam-stat::
+* Low-level interface to the spam-stat dictionary::
+@end menu
+
+@node Creating a spam-stat dictionary
+@subsubsection Creating a spam-stat dictionary
+
+Before you can begin to filter spam based on statistics, you must
+create these statistics based on two mail collections, one with spam,
+one with non-spam. These statistics are then stored in a dictionary
+for later use. In order for these statistics to be meaningful, you
+need several hundred emails in both collections.
+
+Gnus currently supports only the nnml back end for automated dictionary
+creation. The nnml back end stores all mails in a directory, one file
+per mail. Use the following:
+
+@defun spam-stat-process-spam-directory
+Create spam statistics for every file in this directory. Every file
+is treated as one spam mail.
+@end defun
+
+@defun spam-stat-process-non-spam-directory
+Create non-spam statistics for every file in this directory. Every
+file is treated as one non-spam mail.
+@end defun
+
+Usually you would call @code{spam-stat-process-spam-directory} on a
+directory such as @file{~/Mail/mail/spam} (this usually corresponds to
+the group @samp{nnml:mail.spam}), and you would call
+@code{spam-stat-process-non-spam-directory} on a directory such as
+@file{~/Mail/mail/misc} (this usually corresponds to the group
+@samp{nnml:mail.misc}).
+
+When you are using @acronym{IMAP}, you won't have the mails available
+locally, so that will not work. One solution is to use the Gnus Agent
+to cache the articles. Then you can use directories such as
+@file{"~/News/agent/nnimap/mail.yourisp.com/personal_spam"} for
+@code{spam-stat-process-spam-directory}. @xref{Agent as Cache}.
+
+@defvar spam-stat
+This variable holds the hash-table with all the statistics---the
+dictionary we have been talking about. For every word in either
+collection, this hash-table stores a vector describing how often the
+word appeared in spam and often it appeared in non-spam mails.
+@end defvar
+
+If you want to regenerate the statistics from scratch, you need to
+reset the dictionary.
+
+@defun spam-stat-reset
+Reset the @code{spam-stat} hash-table, deleting all the statistics.
+@end defun
+
+When you are done, you must save the dictionary. The dictionary may
+be rather large. If you will not update the dictionary incrementally
+(instead, you will recreate it once a month, for example), then you
+can reduce the size of the dictionary by deleting all words that did
+not appear often enough or that do not clearly belong to only spam or
+only non-spam mails.
+
+@defun spam-stat-reduce-size
+Reduce the size of the dictionary. Use this only if you do not want
+to update the dictionary incrementally.
+@end defun
+
+@defun spam-stat-save
+Save the dictionary.
+@end defun
+
+@defvar spam-stat-file
+The filename used to store the dictionary. This defaults to
+@file{~/.spam-stat.el}.
+@end defvar
+
+@node Splitting mail using spam-stat
+@subsubsection Splitting mail using spam-stat
+
+This section describes how to use the Spam statistics
+@emph{independently} of the @xref{Spam Package}.
+
+First, add the following to your @file{~/.gnus.el} file:
+
+@lisp
+(require 'spam-stat)
+(spam-stat-load)
+@end lisp
+
+This will load the necessary Gnus code, and the dictionary you
+created.
+
+Next, you need to adapt your fancy splitting rules: You need to
+determine how to use @code{spam-stat}. The following examples are for
+the nnml back end. Using the nnimap back end works just as well. Just
+use @code{nnimap-split-fancy} instead of @code{nnmail-split-fancy}.
+
+In the simplest case, you only have two groups, @samp{mail.misc} and
+@samp{mail.spam}. The following expression says that mail is either
+spam or it should go into @samp{mail.misc}. If it is spam, then
+@code{spam-stat-split-fancy} will return @samp{mail.spam}.
+
+@lisp
+(setq nnmail-split-fancy
+ `(| (: spam-stat-split-fancy)
+ "mail.misc"))
+@end lisp
+
+@defvar spam-stat-split-fancy-spam-group
+The group to use for spam. Default is @samp{mail.spam}.
+@end defvar
+
+If you also filter mail with specific subjects into other groups, use
+the following expression. Only mails not matching the regular
+expression are considered potential spam.
+
+@lisp
+(setq nnmail-split-fancy
+ `(| ("Subject" "\\bspam-stat\\b" "mail.emacs")
+ (: spam-stat-split-fancy)
+ "mail.misc"))
+@end lisp
+
+If you want to filter for spam first, then you must be careful when
+creating the dictionary. Note that @code{spam-stat-split-fancy} must
+consider both mails in @samp{mail.emacs} and in @samp{mail.misc} as
+non-spam, therefore both should be in your collection of non-spam
+mails, when creating the dictionary!
+
+@lisp
+(setq nnmail-split-fancy
+ `(| (: spam-stat-split-fancy)
+ ("Subject" "\\bspam-stat\\b" "mail.emacs")
+ "mail.misc"))
+@end lisp
+
+You can combine this with traditional filtering. Here, we move all
+HTML-only mails into the @samp{mail.spam.filtered} group. Note that since
+@code{spam-stat-split-fancy} will never see them, the mails in
+@samp{mail.spam.filtered} should be neither in your collection of spam mails,
+nor in your collection of non-spam mails, when creating the
+dictionary!
+
+@lisp
+(setq nnmail-split-fancy
+ `(| ("Content-Type" "text/html" "mail.spam.filtered")
+ (: spam-stat-split-fancy)
+ ("Subject" "\\bspam-stat\\b" "mail.emacs")
+ "mail.misc"))
+@end lisp
+
+
+@node Low-level interface to the spam-stat dictionary
+@subsubsection Low-level interface to the spam-stat dictionary
+
+The main interface to using @code{spam-stat}, are the following functions:
+
+@defun spam-stat-buffer-is-spam
+Called in a buffer, that buffer is considered to be a new spam mail.
+Use this for new mail that has not been processed before.
+@end defun
+
+@defun spam-stat-buffer-is-no-spam
+Called in a buffer, that buffer is considered to be a new non-spam
+mail. Use this for new mail that has not been processed before.
+@end defun
+
+@defun spam-stat-buffer-change-to-spam
+Called in a buffer, that buffer is no longer considered to be normal
+mail but spam. Use this to change the status of a mail that has
+already been processed as non-spam.
+@end defun
+
+@defun spam-stat-buffer-change-to-non-spam
+Called in a buffer, that buffer is no longer considered to be spam but
+normal mail. Use this to change the status of a mail that has already
+been processed as spam.
+@end defun
+
+@defun spam-stat-save
+Save the hash table to the file. The filename used is stored in the
+variable @code{spam-stat-file}.
+@end defun
+
+@defun spam-stat-load
+Load the hash table from a file. The filename used is stored in the
+variable @code{spam-stat-file}.
+@end defun
+
+@defun spam-stat-score-word
+Return the spam score for a word.
+@end defun
+
+@defun spam-stat-score-buffer
+Return the spam score for a buffer.
+@end defun
+
+@defun spam-stat-split-fancy
+Use this function for fancy mail splitting. Add the rule @samp{(:
+spam-stat-split-fancy)} to @code{nnmail-split-fancy}
+@end defun
+
+Make sure you load the dictionary before using it. This requires the
+following in your @file{~/.gnus.el} file:
+
+@lisp
+(require 'spam-stat)
+(spam-stat-load)
+@end lisp
+
+Typical test will involve calls to the following functions:
+
+@smallexample
+Reset: (setq spam-stat (make-hash-table :test 'equal))
+Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam")
+Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc")
+Save table: (spam-stat-save)
+File size: (nth 7 (file-attributes spam-stat-file))
+Number of words: (hash-table-count spam-stat)
+Test spam: (spam-stat-test-directory "~/Mail/mail/spam")
+Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc")
+Reduce table size: (spam-stat-reduce-size)
+Save table: (spam-stat-save)
+File size: (nth 7 (file-attributes spam-stat-file))
+Number of words: (hash-table-count spam-stat)
+Test spam: (spam-stat-test-directory "~/Mail/mail/spam")
+Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc")
+@end smallexample
+
+Here is how you would create your dictionary:
+
+@smallexample
+Reset: (setq spam-stat (make-hash-table :test 'equal))
+Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam")
+Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc")
+Repeat for any other non-spam group you need...
+Reduce table size: (spam-stat-reduce-size)
+Save table: (spam-stat-save)
+@end smallexample
+
+@node Other modes
+@section Interaction with other modes
+
+@subsection Dired
+@cindex dired
+
+@code{gnus-dired-minor-mode} provides some useful functions for dired
+buffers. It is enabled with
+@lisp
+(add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode)
+@end lisp
+
+@table @kbd
+@item C-c C-m C-a
+@findex gnus-dired-attach
+@cindex attachments, selection via dired
+Send dired's marked files as an attachment (@code{gnus-dired-attach}).
+You will be prompted for a message buffer.
+
+@item C-c C-m C-l
+@findex gnus-dired-find-file-mailcap
+Visit a file according to the appropriate mailcap entry
+(@code{gnus-dired-find-file-mailcap}). With prefix, open file in a new
+buffer.
+
+@item C-c C-m C-p
+@findex gnus-dired-print
+Print file according to the mailcap entry (@code{gnus-dired-print}). If
+there is no print command, print in a PostScript image.
+@end table
+
+@node Various Various
+@section Various Various
+@cindex mode lines
+@cindex highlights
+
+@table @code
+
+@item gnus-home-directory
+@vindex gnus-home-directory
+All Gnus file and directory variables will be initialized from this
+variable, which defaults to @file{~/}.
+
+@item gnus-directory
+@vindex gnus-directory
+Most Gnus storage file and directory variables will be initialized from
+this variable, which defaults to the @env{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 back ends instead of Gnus proper.
+
+@item nnheader-max-head-length
+@vindex nnheader-max-head-length
+When the back ends read straight heads of articles, they all try to read
+as little as possible. This variable (default 8192) specifies
+the absolute max length the back ends 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 back ends 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
+@group
+(setq nnheader-file-name-translation-alist
+ '((?: . ?_)))
+@end group
+@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{;}.
+
+@item gnus-invalid-group-regexp
+@vindex gnus-invalid-group-regexp
+
+Regexp to match ``invalid'' group names when querying user for a group
+name. The default value catches some @strong{really} invalid group
+names who could possibly mess up Gnus internally (like allowing
+@samp{:} in a group name, which is normally used to delimit method and
+group).
+
+@acronym{IMAP} users might want to allow @samp{/} in group names though.
+
+
+@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
+* XEmacs:: Requirements for installing under XEmacs.
+* History:: How Gnus got where it is today.
+* On Writing Manuals:: Why this is not a beginner's guide.
+* Terminology:: We use really difficult, like, words here.
+* Customization:: Tailoring Gnus to your needs.
+* Troubleshooting:: What you might try if things do not work.
+* Gnus Reference Guide:: Rilly, rilly technical stuff.
+* Emacs for Heathens:: A short introduction to Emacsian terms.
+* Frequently Asked Questions:: The Gnus FAQ
+@end menu
+
+
+@node XEmacs
+@section XEmacs
+@cindex XEmacs
+@cindex installing under XEmacs
+
+XEmacs is distributed as a collection of packages. You should install
+whatever packages the Gnus XEmacs package requires. The current
+requirements are @samp{gnus}, @samp{mail-lib}, @samp{xemacs-base},
+@samp{eterm}, @samp{sh-script}, @samp{net-utils}, @samp{os-utils},
+@samp{dired}, @samp{mh-e}, @samp{sieve}, @samp{ps-print}, @samp{W3},
+@samp{pgg}, @samp{mailcrypt}, @samp{ecrypto}, and @samp{sasl}.
+
+
+@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
+@uref{http://quimby.gnus.org/}. 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.
+
+@menu
+* Gnus Versions:: What Gnus versions have been released.
+* Other Gnus Versions:: Other Gnus versions that also have been released.
+* 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.
+* Gnus Development:: How Gnus is developed.
+* Contributors:: Oodles of people.
+* New Features:: Pointers to some of the new stuff in Gnus.
+@end menu
+
+
+@node Gnus Versions
+@subsection Gnus Versions
+@cindex ding Gnus
+@cindex September Gnus
+@cindex Red Gnus
+@cindex Quassia Gnus
+@cindex Pterodactyl Gnus
+@cindex Oort Gnus
+@cindex No Gnus
+@cindex Gnus versions
+
+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.
+It was released as ``Gnus 5.6'' on March 8th 1998 (46 releases).
+
+Gnus 5.6 begat Pterodactyl Gnus on August 29th 1998 and was released as
+``Gnus 5.8'' (after 99 releases and a CVS repository) on December 3rd
+1999.
+
+On the 26th of October 2000, Oort Gnus was begun and was released as
+Gnus 5.10 on May 1st 2003 (24 releases).
+
+On the January 4th 2004, No Gnus was begun.
+
+If you happen upon a version of Gnus that has a prefixed name --
+``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'',
+``Pterodactyl Gnus'', ``Oort Gnus'', ``No 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.
+
+
+@node Other Gnus Versions
+@subsection Other Gnus Versions
+@cindex Semi-gnus
+
+In addition to the versions of Gnus which have had their releases
+coordinated by Lars, one major development has been Semi-gnus from
+Japan. It's based on a library called @acronym{SEMI}, which provides
+@acronym{MIME} capabilities.
+
+These Gnusae are based mainly on Gnus 5.6 and Pterodactyl Gnus.
+Collectively, they are called ``Semi-gnus'', and different strains are
+called T-gnus, ET-gnus, Nana-gnus and Chaos. These provide powerful
+@acronym{MIME} and multilingualization things, especially important for
+Japanese users.
+
+
+@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 back ends, Gnus now offers a simple
+interface for anybody who wants to write new back ends 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 (2)822
+@cindex RFC 822
+@cindex RFC 2822
+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 X-Newsreader
+@itemx User-Agent
+These are considered to be ``vanity headers'', while I consider them
+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
+
+@item USEFOR
+@cindex USEFOR
+USEFOR is an IETF working group writing a successor to RFC 1036, based
+on Son-of-RFC 1036. They have produced a number of drafts proposing
+various changes to the format of news articles. The Gnus towers will
+look into implementing the changes when the draft is accepted as an RFC.
+
+@item MIME - RFC 2045-2049 etc
+@cindex @acronym{MIME}
+All the various @acronym{MIME} RFCs are supported.
+
+@item Disposition Notifications - RFC 2298
+Message Mode is able to request notifications from the receiver.
+
+@item PGP - RFC 1991 and RFC 2440
+@cindex RFC 1991
+@cindex RFC 2440
+RFC 1991 is the original @acronym{PGP} message specification,
+published as an informational RFC. RFC 2440 was the follow-up, now
+called Open PGP, and put on the Standards Track. Both document a
+non-@acronym{MIME} aware @acronym{PGP} format. Gnus supports both
+encoding (signing and encryption) and decoding (verification and
+decryption).
+
+@item PGP/MIME - RFC 2015/3156
+RFC 2015 (superseded by 3156 which references RFC 2440 instead of RFC
+1991) describes the @acronym{MIME}-wrapping around the RFC 1991/2440 format.
+Gnus supports both encoding and decoding.
+
+@item S/MIME - RFC 2633
+RFC 2633 describes the @acronym{S/MIME} format.
+
+@item IMAP - RFC 1730/2060, RFC 2195, RFC 2086, RFC 2359, RFC 2595, RFC 1731
+RFC 1730 is @acronym{IMAP} version 4, updated somewhat by RFC 2060
+(@acronym{IMAP} 4 revision 1). RFC 2195 describes CRAM-MD5
+authentication for @acronym{IMAP}. RFC 2086 describes access control
+lists (ACLs) for @acronym{IMAP}. RFC 2359 describes a @acronym{IMAP}
+protocol enhancement. RFC 2595 describes the proper @acronym{TLS}
+integration (STARTTLS) with @acronym{IMAP}. RFC 1731 describes the
+GSSAPI/Kerberos4 mechanisms for @acronym{IMAP}.
+
+@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 21.1 and up.
+
+@item
+XEmacs 21.4 and up.
+
+@end itemize
+
+This Gnus version will absolutely not work on any Emacsen older than
+that. Not reliably, at least. Older versions of Gnus may work on older
+Emacs versions. Particularly, Gnus 5.10.8 should also work on Emacs
+20.7 and XEmacs 21.1.
+
+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 Gnus Development
+@subsection Gnus Development
+
+Gnus is developed in a two-phased cycle. The first phase involves much
+discussion on the @samp{ding@@gnus.org} mailing list, where people
+propose changes and new features, post patches and new back ends. This
+phase is called the @dfn{alpha} phase, since the Gnusae released in this
+phase are @dfn{alpha releases}, or (perhaps more commonly in other
+circles) @dfn{snapshots}. During this phase, Gnus is assumed to be
+unstable and should not be used by casual users. Gnus alpha releases
+have names like ``Red Gnus'' and ``Quassia Gnus''.
+
+After futzing around for 50-100 alpha releases, Gnus is declared
+@dfn{frozen}, and only bug fixes are applied. Gnus loses the prefix,
+and is called things like ``Gnus 5.6.32'' instead. Normal people are
+supposed to be able to use these, and these are mostly discussed on the
+@samp{gnu.emacs.gnus} newsgroup.
+
+@cindex Incoming*
+@vindex mail-source-delete-incoming
+Some variable defaults differ between alpha Gnusae and released Gnusae.
+In particular, @code{mail-source-delete-incoming} defaults to @code{nil} in
+alpha Gnusae and @code{t} in released Gnusae. This is to prevent
+lossage of mail if an alpha release hiccups while handling the mail.
+
+The division of discussion between the ding mailing list and the Gnus
+newsgroup is not purely based on publicity concerns. It's true that
+having people write about the horrible things that an alpha Gnus release
+can do (sometimes) in a public forum may scare people off, but more
+importantly, talking about new experimental features that have been
+introduced may confuse casual users. New features are frequently
+introduced, fiddled with, and judged to be found wanting, and then
+either discarded or totally rewritten. People reading the mailing list
+usually keep up with these rapid changes, while people on the newsgroup
+can't be assumed to do so.
+
+
+
+@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@dots{} oops,
+wrong show.
+
+@itemize @bullet
+
+@item
+Masanobu @sc{Umeda}---the writer of the original @sc{gnus}.
+
+@item
+Shenghuo Zhu---uudecode.el, mm-uu.el, rfc1843.el, webmail.el,
+nnwarchive and many, many other things connected with @acronym{MIME} and
+other types of en/decoding, as well as general bug fixing, new
+functionality and stuff.
+
+@item
+Per Abrahamsen---custom, scoring, highlighting and @sc{soup} code (as
+well as numerous other things).
+
+@item
+Luis Fernandes---design and graphics.
+
+@item
+Joe Reiss---creator of the smiley faces.
+
+@item
+Justin Sheehy---the @acronym{FAQ} maintainer.
+
+@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,
+Kevin Greiner,
+Jesper Harder,
+Paul Jarc,
+Simon Josefsson,
+David Kågedal,
+Richard Pieri,
+Fabrice Popineau,
+Daniel Quinlan,
+Michael Shields,
+Reiner Steib,
+Jason L. Tibbitts, III,
+Jack Vinson,
+Katsumi Yamaoka, @c Yamaoka
+and
+Teodor Zlatanov.
+
+Also thanks to the following for patches and stuff:
+
+Jari Aalto,
+Adrian Aichner,
+Vladimir Alexiev,
+Russ Allbery,
+Peter Arius,
+Matt Armstrong,
+Marc Auslander,
+Miles Bader,
+Alexei V. Barantsev,
+Frank Bennett,
+Robert Bihlmeyer,
+Chris Bone,
+Mark Borges,
+Mark Boyns,
+Lance A. Brown,
+Rob Browning,
+Kees de Bruin,
+Martin Buchholz,
+Joe Buehler,
+Kevin Buhr,
+Alastair Burt,
+Joao Cachopo,
+Zlatko Calusic,
+Massimo Campostrini,
+Castor,
+David Charlap,
+Dan Christensen,
+Kevin Christian,
+Jae-you Chung, @c ?
+James H. Cloos, Jr.,
+Laura Conrad,
+Michael R. Cook,
+Glenn Coombs,
+Andrew J. Cosgriff,
+Neil Crellin,
+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,
+Mark W. Eichin,
+Karl Eichwalder,
+Enami Tsugutomo, @c Enami
+Michael Ernst,
+Luc Van Eycken,
+Sam Falkner,
+Nelson Jose dos Santos Ferreira,
+Sigbjorn Finne,
+Sven Fischer,
+Paul Fisher,
+Decklin Foster,
+Gary D. Foster,
+Paul Franklin,
+Guy Geens,
+Arne Georg Gleditsch,
+David S. Goldberg,
+Michelangelo Grigni,
+Dale Hagglund,
+D. Hall,
+Magnus Hammerin,
+Kenichi Handa, @c Handa
+Raja R. Harinath,
+Yoshiki Hayashi, @c Hayashi
+P. E. Jareth Hein,
+Hisashige Kenji, @c Hisashige
+Scott Hofmann,
+Marc Horowitz,
+Gunnar Horrigmo,
+Richard Hoskins,
+Brad Howes,
+Miguel de Icaza,
+François Felix Ingrand,
+Tatsuya Ichikawa, @c Ichikawa
+Ishikawa Ichiro, @c Ishikawa
+Lee Iverson,
+Iwamuro Motonori, @c Iwamuro
+Rajappa Iyer,
+Andreas Jaeger,
+Adam P. Jenkins,
+Randell Jesup,
+Fred Johansen,
+Gareth Jones,
+Greg Klanderman,
+Karl Kleinpaste,
+Michael Klingbeil,
+Peter Skov Knudsen,
+Shuhei Kobayashi, @c Kobayashi
+Petr Konecny,
+Koseki Yoshinori, @c Koseki
+Thor Kristoffersen,
+Jens Lautenbacher,
+Martin Larose,
+Seokchan Lee, @c Lee
+Joerg Lenneis,
+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
+Ettore Perazzoli,
+William Perry,
+Stephen Peters,
+Jens-Ulrik Holger Petersen,
+Ulrich Pfeifer,
+Matt Pharr,
+Andy Piper,
+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,
+Markus Rost,
+Jason Rumney,
+Wolfgang Rupprecht,
+Jay Sachs,
+Dewey M. Sasser,
+Conrad Sauerwald,
+Loren Schall,
+Dan Schmidt,
+Ralph Schleicher,
+Philippe Schnoebelen,
+Andreas Schwab,
+Randal L. Schwartz,
+Danny Siu,
+Matt Simmons,
+Paul D. Smith,
+Jeff Sparkes,
+Toby Speight,
+Michael Sperber,
+Darren Stalder,
+Richard Stallman,
+Greg Stark,
+Sam Steingold,
+Paul Stevenson,
+Jonas Steverud,
+Paul Stodghill,
+Kiyokazu Suto, @c Suto
+Kurt Swanson,
+Samuel Tardieu,
+Teddy,
+Chuck Thompson,
+Tozawa Akihiko, @c Tozawa
+Philippe Troin,
+James Troup,
+Trung Tran-Duc,
+Jack Twilley,
+Aaron M. Ucko,
+Aki Vehtari,
+Didier Verna,
+Vladimir Volovich,
+Jan Vroonhof,
+Stefan Waldherr,
+Pete Ware,
+Barry A. Warsaw,
+Christoph Wedler,
+Joe Wells,
+Lee Willis,
+and
+Lloyd Zusman.
+
+
+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.2/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.
+* Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9.
+* Oort Gnus:: It's big. It's far out. Gnus 5.10/5.11.
+@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 @acronym{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 back ends 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.el}) 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 @acronym{FAQ}s 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{Window Layout}).
+
+@item
+You can click on buttons instead of using the keyboard
+(@pxref{Buttons}).
+
+@end itemize
+
+
+@node September Gnus
+@subsubsection September Gnus
+
+@iftex
+@iflatex
+\gnusfig{-28cm}{0cm}{\epsfig{figure=ps/september,height=20cm}}
+@end iflatex
+@end iftex
+
+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 back end (@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}).
+
+@item
+All mail back ends 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{Window
+Layout}).
+
+@item
+Mail can be re-scanned by a daemonic process (@pxref{Daemons}).
+@iftex
+@iflatex
+\marginpar[\mbox{}\hfill\epsfig{figure=ps/fseptember,height=5cm}]{\epsfig{figure=ps/fseptember,height=5cm}}
+@end iflatex
+@end iftex
+
+@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}).
+
+@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:
+
+@iftex
+@iflatex
+\gnusfig{-5.5cm}{-4cm}{\epsfig{figure=ps/red,height=20cm}}
+@end iflatex
+@end iftex
+
+@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{C-M-_}
+(@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{C-M-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 back end makes it possible to post even when the @acronym{NNTP}
+server doesn't allow posting (@pxref{Mail-To-News Gateways}).
+
+@item
+A new back end 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}).
+@iftex
+@iflatex
+\marginpar[\mbox{}\hfill\epsfig{figure=ps/fred,width=3cm}]{\epsfig{figure=ps/fred,width=3cm}}
+@end iflatex
+@end iftex
+
+@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:
+
+@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.
+@xref{Gnus Unplugged}, for the full story.
+
+@item
+The @code{nndraft} back end 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. @xref{Symbolic Prefixes}, 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 @file{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 @acronym{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} back end.
+
+@item
+Old dejanews archives can now be read by @code{nnweb}.
+
+@end itemize
+
+@node Pterodactyl Gnus
+@subsubsection Pterodactyl Gnus
+
+New features in Gnus 5.8:
+
+@itemize @bullet
+
+@item
+The mail-fetching functions have changed. See the manual for the
+many details. In particular, all procmail fetching variables are gone.
+
+If you used procmail like in
+
+@lisp
+(setq nnmail-use-procmail t)
+(setq nnmail-spool-file 'procmail)
+(setq nnmail-procmail-directory "~/mail/incoming/")
+(setq nnmail-procmail-suffix "\\.in")
+@end lisp
+
+this now has changed to
+
+@lisp
+(setq mail-sources
+ '((directory :path "~/mail/incoming/"
+ :suffix ".in")))
+@end lisp
+
+@xref{Mail Source Specifiers}.
+
+@item
+Gnus is now a @acronym{MIME}-capable reader. This affects many parts of
+Gnus, and adds a slew of new commands. See the manual for details.
+
+@item
+Gnus has also been multilingualized. This also affects too
+many parts of Gnus to summarize here, and adds many new variables.
+
+@item
+@code{gnus-auto-select-first} can now be a function to be
+called to position point.
+
+@item
+The user can now decide which extra headers should be included in
+summary buffers and @acronym{NOV} files.
+
+@item
+@code{gnus-article-display-hook} has been removed. Instead, a number
+of variables starting with @code{gnus-treat-} have been added.
+
+@item
+The Gnus posting styles have been redone again and now works in a
+subtly different manner.
+
+@item
+New web-based back ends have been added: @code{nnslashdot},
+@code{nnwarchive} and @code{nnultimate}. nnweb has been revamped,
+again, to keep up with ever-changing layouts.
+
+@item
+Gnus can now read @acronym{IMAP} mail via @code{nnimap}.
+
+@end itemize
+
+@node Oort Gnus
+@subsubsection Oort Gnus
+@cindex Oort Gnus
+
+New features in Gnus 5.10:
+
+@itemize @bullet
+
+@item Installation changes
+@c ***********************
+
+@itemize @bullet
+@item
+Upgrading from previous (stable) version if you have used Oort.
+
+If you have tried Oort (the unstable Gnus branch leading to this
+release) but went back to a stable version, be careful when upgrading to
+this version. In particular, you will probably want to remove all
+@file{.marks} (nnml) and @file{.mrk} (nnfolder) files, so that flags are
+read from your @file{.newsrc.eld} instead of from the
+@file{.marks}/@file{.mrk} file where this release store flags. See a
+later entry for more information about marks. Note that downgrading
+isn't save in general.
+
+@item
+Lisp files are now installed in @file{.../site-lisp/gnus/} by default.
+It defaulted to @file{.../site-lisp/} formerly. In addition to this,
+the new installer issues a warning if other Gnus installations which
+will shadow the latest one are detected. You can then remove those
+shadows manually or remove them using @code{make
+remove-installed-shadows}.
+
+@item
+New @file{make.bat} for compiling and installing Gnus under MS Windows
+
+Use @file{make.bat} if you want to install Gnus under MS Windows, the
+first argument to the batch-program should be the directory where
+@file{xemacs.exe} respectively @file{emacs.exe} is located, if you want
+to install Gnus after compiling it, give @file{make.bat} @code{/copy} as
+the second parameter.
+
+@file{make.bat} has been rewritten from scratch, it now features
+automatic recognition of XEmacs and GNU Emacs, generates
+@file{gnus-load.el}, checks if errors occur while compilation and
+generation of info files and reports them at the end of the build
+process. It now uses @code{makeinfo} if it is available and falls
+back to @file{infohack.el} otherwise. @file{make.bat} should now
+install all files which are necessary to run Gnus and be generally a
+complete replacement for the @code{configure; make; make install}
+cycle used under Unix systems.
+
+The new @file{make.bat} makes @file{make-x.bat} and @file{xemacs.mak}
+superfluous, so they have been removed.
+
+@item
+@file{~/News/overview/} not used.
+
+As a result of the following change, the @file{~/News/overview/}
+directory is not used any more. You can safely delete the entire
+hierarchy.
+
+@c FIXME: `gnus-load' is mentioned in README, which is not included in
+@c CVS. We should find a better place for this item.
+@item
+@code{(require 'gnus-load)}
+
+If you use a stand-alone Gnus distribution, you'd better add
+@code{(require 'gnus-load)} into your @file{~/.emacs} after adding the Gnus
+lisp directory into load-path.
+
+File @file{gnus-load.el} contains autoload commands, functions and variables,
+some of which may not be included in distributions of Emacsen.
+
+@end itemize
+
+@item New packages and libraries within Gnus
+@c *****************************************
+
+@itemize @bullet
+
+@item
+The revised Gnus @acronym{FAQ} is included in the manual,
+@xref{Frequently Asked Questions}.
+
+@item
+@acronym{TLS} wrapper shipped with Gnus
+
+@acronym{TLS}/@acronym{SSL} is now supported in @acronym{IMAP} and
+@acronym{NNTP} via @file{tls.el} and GNUTLS. The old
+@acronym{TLS}/@acronym{SSL} support via (external third party)
+@file{ssl.el} and OpenSSL still works.
+
+@item
+Improved anti-spam features.
+
+Gnus is now able to take out spam from your mail and news streams
+using a wide variety of programs and filter rules. Among the supported
+methods are RBL blocklists, bogofilter and white/blacklists. Hooks
+for easy use of external packages such as SpamAssassin and Hashcash
+are also new. @xref{Thwarting Email Spam}.
+@c FIXME: @xref{Spam Package}?. Should this be under Misc?
+
+@item
+Gnus supports server-side mail filtering using Sieve.
+
+Sieve rules can be added as Group Parameters for groups, and the
+complete Sieve script is generated using @kbd{D g} from the Group
+buffer, and then uploaded to the server using @kbd{C-c C-l} in the
+generated Sieve buffer. @xref{Sieve Commands}, and the new Sieve
+manual @ref{Top, , Top, sieve, Emacs Sieve}.
+
+@end itemize
+
+@item Changes in group mode
+@c ************************
+
+@itemize @bullet
+
+@item
+@code{gnus-group-read-ephemeral-group} can be called interactively,
+using @kbd{G M}.
+
+@item
+Retrieval of charters and control messages
+
+There are new commands for fetching newsgroup charters (@kbd{H c}) and
+control messages (@kbd{H C}).
+
+@item
+The new variable @code{gnus-parameters} can be used to set group parameters.
+
+Earlier this was done only via @kbd{G p} (or @kbd{G c}), which stored
+the parameters in @file{~/.newsrc.eld}, but via this variable you can
+enjoy the powers of customize, and simplified backups since you set the
+variable in @file{~/.gnus.el} instead of @file{~/.newsrc.eld}. The
+variable maps regular expressions matching group names to group
+parameters, a'la:
+@lisp
+(setq gnus-parameters
+ '(("mail\\..*"
+ (gnus-show-threads nil)
+ (gnus-use-scoring nil))
+ ("^nnimap:\\(foo.bar\\)$"
+ (to-group . "\\1"))))
+@end lisp
+
+@item
+Unread count correct in nnimap groups.
+
+The estimated number of unread articles in the group buffer should now
+be correct for nnimap groups. This is achieved by calling
+@code{nnimap-fixup-unread-after-getting-new-news} from the
+@code{gnus-setup-news-hook} (called on startup) and
+@code{gnus-after-getting-new-news-hook}. (called after getting new
+mail). If you have modified those variables from the default, you may
+want to add @code{nnimap-fixup-unread-after-getting-new-news} again. If
+you were happy with the estimate and want to save some (minimal) time
+when getting new mail, remove the function.
+
+@item
+Group names are treated as UTF-8 by default.
+
+This is supposedly what USEFOR wanted to migrate to. See
+@code{gnus-group-name-charset-group-alist} and
+@code{gnus-group-name-charset-method-alist} for customization.
+
+@item
+@code{gnus-group-charset-alist} and
+@code{gnus-group-ignored-charsets-alist}.
+
+The regexps in these variables are compared with full group names
+instead of real group names in 5.8. Users who customize these
+variables should change those regexps accordingly. For example:
+@lisp
+("^han\\>" euc-kr) -> ("\\(^\\|:\\)han\\>" euc-kr)
+@end lisp
+
+@end itemize
+
+@item Changes in summary and article mode
+@c **************************************
+
+@itemize @bullet
+
+@item
+@kbd{F} (@code{gnus-article-followup-with-original}) and @kbd{R}
+(@code{gnus-article-reply-with-original}) only yank the text in the
+region if the region is active.
+
+@item
+In draft groups, @kbd{e} is now bound to @code{gnus-draft-edit-message}.
+Use @kbd{B w} for @code{gnus-summary-edit-article} instead.
+
+@item
+Article Buttons
+
+More buttons for URLs, mail addresses, Message-IDs, Info links, man
+pages and Emacs or Gnus related references. @xref{Article Buttons}. The
+variables @code{gnus-button-@var{*}-level} can be used to control the
+appearance of all article buttons. @xref{Article Button Levels}.
+
+@item
+Single-part yenc encoded attachments can be decoded.
+
+@item
+Picons
+
+The picons code has been reimplemented to work in GNU Emacs---some of
+the previous options have been removed or renamed.
+
+Picons are small ``personal icons'' representing users, domain and
+newsgroups, which can be displayed in the Article buffer.
+@xref{Picons}.
+
+@item
+If the new option @code{gnus-treat-body-boundary} is non-@code{nil}, a
+boundary line is drawn at the end of the headers.
+
+@item
+Signed article headers (X-PGP-Sig) can be verified with @kbd{W p}.
+
+@item
+The Summary Buffer uses an arrow in the fringe to indicate the current
+article. Use @code{(setq gnus-summary-display-arrow nil)} to disable it.
+
+@item
+Warn about email replies to news
+
+Do you often find yourself replying to news by email by mistake? Then
+the new option @code{gnus-confirm-mail-reply-to-news} is just the thing for
+you.
+
+@item
+If the new option @code{gnus-summary-display-while-building} is
+non-@code{nil}, the summary buffer is shown and updated as it's being
+built.
+
+@item
+The new @code{recent} mark @samp{.} indicates newly arrived messages (as
+opposed to old but unread messages).
+
+@item
+Gnus supports RFC 2369 mailing list headers, and adds a number of
+related commands in mailing list groups. @xref{Mailing List}.
+
+@item
+The Date header can be displayed in a format that can be read aloud
+in English. @xref{Article Date}.
+
+@item
+diffs are automatically highlighted in groups matching
+@code{mm-uu-diff-groups-regexp}
+
+@item
+Better handling of Microsoft citation styles
+
+Gnus now tries to recognize the mangled header block that some Microsoft
+mailers use to indicate that the rest of the message is a citation, even
+though it is not quoted in any way. The variable
+@code{gnus-cite-unsightly-citation-regexp} matches the start of these
+citations.
+
+The new command @kbd{W Y f}
+(@code{gnus-article-outlook-deuglify-article}) allows deuglifying broken
+Outlook (Express) articles.
+
+@item
+@code{gnus-article-skip-boring}
+
+If you set @code{gnus-article-skip-boring} to @code{t}, then Gnus will
+not scroll down to show you a page that contains only boring text,
+which by default means cited text and signature. You can customize
+what is skippable using @code{gnus-article-boring-faces}.
+
+This feature is especially useful if you read many articles that
+consist of a little new content at the top with a long, untrimmed
+message cited below.
+
+@item
+Smileys (@samp{:-)}, @samp{;-)} etc) are now displayed graphically in
+Emacs too.
+
+Put @code{(setq gnus-treat-display-smileys nil)} in @file{~/.gnus.el} to
+disable it.
+
+@item
+Face headers handling. @xref{Face}.
+
+@item
+In the summary buffer, the new command @kbd{/ N} inserts new messages
+and @kbd{/ o} inserts old messages.
+
+@item
+Gnus decodes morse encoded messages if you press @kbd{W m}.
+
+@item
+@code{gnus-summary-line-format}
+
+The default value changed to @samp{%U%R%z%I%(%[%4L: %-23,23f%]%)
+%s\n}. Moreover @code{gnus-extra-headers},
+@code{nnmail-extra-headers} and @code{gnus-ignored-from-addresses}
+changed their default so that the users name will be replaced by the
+recipient's name or the group name posting to for @acronym{NNTP}
+groups.
+
+@item
+Deleting of attachments.
+
+The command @code{gnus-mime-save-part-and-strip} (bound to @kbd{C-o}
+on @acronym{MIME} buttons) saves a part and replaces the part with an
+external one. @code{gnus-mime-delete-part} (bound to @kbd{d} on
+@acronym{MIME} buttons) removes a part. It works only on back ends
+that support editing.
+
+@item
+@code{gnus-default-charset}
+
+The default value is determined from the
+@code{current-language-environment} variable, instead of
+@code{iso-8859-1}. Also the @samp{.*} item in
+@code{gnus-group-charset-alist} is removed.
+
+@item
+Printing capabilities are enhanced.
+
+Gnus supports Muttprint natively with @kbd{O P} from the Summary and
+Article buffers. Also, each individual @acronym{MIME} part can be
+printed using @kbd{p} on the @acronym{MIME} button.
+
+@item
+Extended format specs.
+
+Format spec @samp{%&user-date;} is added into
+@code{gnus-summary-line-format-alist}. Also, user defined extended
+format specs are supported. The extended format specs look like
+@samp{%u&foo;}, which invokes function
+@code{gnus-user-format-function-@var{foo}}. Because @samp{&} is used as the
+escape character, old user defined format @samp{%u&} is no longer supported.
+
+@item
+@kbd{/ *} (@code{gnus-summary-limit-include-cached}) is rewritten.
+@c FIXME: Was this a user-visible change?
+
+It was aliased to @kbd{Y c}
+(@code{gnus-summary-insert-cached-articles}). The new function filters
+out other articles.
+
+@item
+Some limiting commands accept a @kbd{C-u} prefix to negate the match.
+
+If @kbd{C-u} is used on subject, author or extra headers, i.e., @kbd{/
+s}, @kbd{/ a}, and @kbd{/ x}
+(@code{gnus-summary-limit-to-@{subject,author,extra@}}) respectively, the
+result will be to display all articles that do not match the expression.
+
+@item
+Gnus inlines external parts (message/external).
+
+@end itemize
+
+@item Changes in Message mode and related Gnus features
+@c ****************************************************
+
+@itemize @bullet
+
+@item
+Delayed articles
+
+You can delay the sending of a message with @kbd{C-c C-j} in the Message
+buffer. The messages are delivered at specified time. This is useful
+for sending yourself reminders. @xref{Delayed Articles}.
+
+@item
+If the new option @code{nnml-use-compressed-files} is non-@code{nil},
+the nnml back end allows compressed message files.
+
+@item
+The new option @code{gnus-gcc-mark-as-read} automatically marks
+Gcc articles as read.
+
+@item
+Externalizing of attachments
+
+If @code{gnus-gcc-externalize-attachments} or
+@code{message-fcc-externalize-attachments} is non-@code{nil}, attach
+local files as external parts.
+
+@item
+The envelope sender address can be customized when using Sendmail.
+@xref{Mail Variables, Mail Variables,, message, Message Manual}.
+
+@item
+Gnus no longer generate the Sender: header automatically.
+
+Earlier it was generated when the user configurable email address was
+different from the Gnus guessed default user address. As the guessing
+algorithm is rarely correct these days, and (more controversially) the
+only use of the Sender: header was to check if you are entitled to
+cancel/supersede news (which is now solved by Cancel Locks instead,
+see another entry), generation of the header has been disabled by
+default. See the variables @code{message-required-headers},
+@code{message-required-news-headers}, and
+@code{message-required-mail-headers}.
+
+@item
+Features from third party @file{message-utils.el} added to @file{message.el}.
+
+Message now asks if you wish to remove @samp{(was: <old subject>)} from
+subject lines (see @code{message-subject-trailing-was-query}). @kbd{C-c
+M-m} and @kbd{C-c M-f} inserts markers indicating included text.
+@kbd{C-c C-f a} adds a X-No-Archive: header. @kbd{C-c C-f x} inserts
+appropriate headers and a note in the body for cross-postings and
+followups (see the variables @code{message-cross-post-@var{*}}).
+
+@item
+References and X-Draft-From headers are no longer generated when you
+start composing messages and @code{message-generate-headers-first} is
+@code{nil}.
+
+@item
+Easy inclusion of X-Faces headers. @xref{X-Face}.
+
+@item
+Group Carbon Copy (GCC) quoting
+
+To support groups that contains SPC and other weird characters, groups
+are quoted before they are placed in the Gcc: header. This means
+variables such as @code{gnus-message-archive-group} should no longer
+contain quote characters to make groups containing SPC work. Also, if
+you are using the string @samp{nnml:foo, nnml:bar} (indicating Gcc
+into two groups) you must change it to return the list
+@code{("nnml:foo" "nnml:bar")}, otherwise the Gcc: line will be quoted
+incorrectly. Note that returning the string @samp{nnml:foo, nnml:bar}
+was incorrect earlier, it just didn't generate any problems since it
+was inserted directly.
+
+@item
+@code{message-insinuate-rmail}
+
+Adding @code{(message-insinuate-rmail)} and @code{(setq
+mail-user-agent 'gnus-user-agent)} in @file{.emacs} convinces Rmail to
+compose, reply and forward messages in message-mode, where you can
+enjoy the power of @acronym{MML}.
+
+@item
+@code{message-minibuffer-local-map}
+
+The line below enables BBDB in resending a message:
+@lisp
+(define-key message-minibuffer-local-map [(tab)]
+ 'bbdb-complete-name)
+@end lisp
+
+@item
+@code{gnus-posting-styles}
+
+Add a new format of match like
+@lisp
+((header "to" "larsi.*org")
+ (Organization "Somewhere, Inc."))
+@end lisp
+The old format like the lines below is obsolete, but still accepted.
+@lisp
+(header "to" "larsi.*org"
+ (Organization "Somewhere, Inc."))
+@end lisp
+
+@item
+@code{message-ignored-news-headers} and @code{message-ignored-mail-headers}
+
+@samp{X-Draft-From} and @samp{X-Gnus-Agent-Meta-Information} have been
+added into these two variables. If you customized those, perhaps you
+need add those two headers too.
+
+@item
+Gnus supports the ``format=flowed'' (RFC 2646) parameter. On
+composing messages, it is enabled by @code{use-hard-newlines}.
+Decoding format=flowed was present but not documented in earlier
+versions.
+
+@item
+The option @code{mm-fill-flowed} can be used to disable treatment of
+``format=flowed'' messages. Also, flowed text is disabled when sending
+inline PGP signed messages. @xref{Flowed text, , Flowed text,
+emacs-mime, The Emacs MIME Manual}. (New in Gnus 5.10.7)
+@c This entry is also present in the node "No Gnus".
+
+@item
+Gnus supports the generation of RFC 2298 Disposition Notification requests.
+
+This is invoked with the @kbd{C-c M-n} key binding from message mode.
+
+@item
+Message supports the Importance: (RFC 2156) header.
+
+In the message buffer, @kbd{C-c C-f C-i} or @kbd{C-c C-u} cycles through
+the valid values.
+
+@item
+Gnus supports Cancel Locks in News.
+
+This means a header @samp{Cancel-Lock} is inserted in news posting. It is
+used to determine if you wrote an article or not (for canceling and
+superseding). Gnus generates a random password string the first time
+you post a message, and saves it in your @file{~/.emacs} using the Custom
+system. While the variable is called @code{canlock-password}, it is not
+security sensitive data. Publishing your canlock string on the web
+will not allow anyone to be able to anything she could not already do.
+The behavior can be changed by customizing @code{message-insert-canlock}.
+
+@item
+Gnus supports @acronym{PGP} (RFC 1991/2440), @acronym{PGP/MIME} (RFC
+2015/3156) and @acronym{S/MIME} (RFC 2630-2633).
+
+It needs an external @acronym{S/MIME} and OpenPGP implementation, but no
+additional Lisp libraries. This add several menu items to the
+Attachments menu, and @kbd{C-c RET} key bindings, when composing
+messages. This also obsoletes @code{gnus-article-hide-pgp-hook}.
+
+@item
+@acronym{MML} (Mime compose) prefix changed from @kbd{M-m} to @kbd{C-c
+C-m}.
+
+This change was made to avoid conflict with the standard binding of
+@code{back-to-indentation}, which is also useful in message mode.
+
+@item
+The default for @code{message-forward-show-mml} changed to the symbol
+@code{best}.
+
+The behavior for the @code{best} value is to show @acronym{MML} (i.e.,
+convert to @acronym{MIME}) when appropriate. @acronym{MML} will not be
+used when forwarding signed or encrypted messages, as the conversion
+invalidate the digital signature.
+
+@item
+If @code{auto-compression-mode} is enabled, attachments are automatically
+decompressed when activated.
+@c FIXME: Does this affect article or message mode?
+
+@item
+Support for non-@acronym{ASCII} domain names
+
+Message supports non-@acronym{ASCII} domain names in From:, To: and
+Cc: and will query you whether to perform encoding when you try to
+send a message. The variable @code{message-use-idna} controls this.
+Gnus will also decode non-@acronym{ASCII} domain names in From:, To:
+and Cc: when you view a message. The variable @code{gnus-use-idna}
+controls this.
+
+@item You can now drag and drop attachments to the Message buffer.
+See @code{mml-dnd-protocol-alist} and @code{mml-dnd-attach-options}.
+@xref{MIME, ,MIME, message, Message Manual}.
+@c New in 5.10.9 / 5.11
+
+@end itemize
+
+@item Changes in back ends
+@c ***********************
+
+@itemize @bullet
+@item
+Gnus can display RSS newsfeeds as a newsgroup. @xref{RSS}.
+
+@item
+The nndoc back end now supports mailman digests and exim bounces.
+
+@item
+Gnus supports Maildir groups.
+
+Gnus includes a new back end @file{nnmaildir.el}. @xref{Maildir}.
+
+@item
+The nnml and nnfolder back ends store marks for each groups.
+
+This makes it possible to take backup of nnml/nnfolder servers/groups
+separately of @file{~/.newsrc.eld}, while preserving marks. It also
+makes it possible to share articles and marks between users (without
+sharing the @file{~/.newsrc.eld} file) within e.g. a department. It
+works by storing the marks stored in @file{~/.newsrc.eld} in a per-group
+file @file{.marks} (for nnml) and @file{@var{groupname}.mrk} (for
+nnfolder, named @var{groupname}). If the nnml/nnfolder is moved to
+another machine, Gnus will automatically use the @file{.marks} or
+@file{.mrk} file instead of the information in @file{~/.newsrc.eld}.
+The new server variables @code{nnml-marks-is-evil} and
+@code{nnfolder-marks-is-evil} can be used to disable this feature.
+
+@end itemize
+
+@item Appearance
+@c *************
+
+@itemize @bullet
+
+@item
+The menu bar item (in Group and Summary buffer) named ``Misc'' has
+been renamed to ``Gnus''.
+
+@item
+The menu bar item (in Message mode) named ``@acronym{MML}'' has been
+renamed to ``Attachments''. Note that this menu also contains security
+related stuff, like signing and encryption (@pxref{Security, Security,,
+message, Message Manual}).
+
+@item
+The tool bars have been updated to use GNOME icons in Group, Summary and
+Message mode. You can also customize the tool bars. This is a new
+feature in Gnus 5.10.9. (Only for Emacs, not in XEmacs.)
+
+@item The tool bar icons are now (de)activated correctly
+in the group buffer, see the variable @code{gnus-group-update-tool-bar}.
+Its default value depends on your Emacs version. This is a new feature
+in Gnus 5.10.9.
+@end itemize
+
+
+@item Miscellaneous changes
+@c ************************
+
+@itemize @bullet
+
+@item
+@code{gnus-agent}
+
+The Gnus Agent has seen a major updated and is now enabled by default,
+and all nntp and nnimap servers from @code{gnus-select-method} and
+@code{gnus-secondary-select-method} are agentized by default. Earlier
+only the server in @code{gnus-select-method} was agentized by the
+default, and the agent was disabled by default. When the agent is
+enabled, headers are now also retrieved from the Agent cache instead
+of the back ends when possible. Earlier this only happened in the
+unplugged state. You can enroll or remove servers with @kbd{J a} and
+@kbd{J r} in the server buffer. Gnus will not download articles into
+the Agent cache, unless you instruct it to do so, though, by using
+@kbd{J u} or @kbd{J s} from the Group buffer. You revert to the old
+behavior of having the Agent disabled with @code{(setq gnus-agent
+nil)}. Note that putting @code{(gnus-agentize)} in @file{~/.gnus.el}
+is not needed any more.
+
+@item
+Gnus reads the @acronym{NOV} and articles in the Agent if plugged.
+
+If one reads an article while plugged, and the article already exists
+in the Agent, it won't get downloaded once more. @code{(setq
+gnus-agent-cache nil)} reverts to the old behavior.
+
+@item
+Dired integration
+
+@code{gnus-dired-minor-mode} (see @ref{Other modes}) installs key
+bindings in dired buffers to send a file as an attachment, open a file
+using the appropriate mailcap entry, and print a file using the mailcap
+entry.
+
+@item
+The format spec @code{%C} for positioning point has changed to @code{%*}.
+
+@item
+@code{gnus-slave-unplugged}
+
+A new command which starts Gnus offline in slave mode.
+
+@end itemize
+
+@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}
+@iflatex
+or my own home-brewed TeXinfo to \LaTeX\ transformer,
+and then run through @code{latex} and @code{dvips}
+@end iflatex
+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.
+
+@iflatex
+@c @head
+Of course, everything in this manual is of vital interest, so you should
+read it all. Several times. However, if you feel like skimming the
+manual, look for that gnu head you should see in the margin over
+there---it means that what's being discussed is of more importance than
+the rest of the stuff. (On the other hand, if everything is infinitely
+important, how can anything be more important than that? Just one more
+of the mysteries of this world, I guess.)
+@end iflatex
+
+@end iftex
+
+
+@node On Writing Manuals
+@section On Writing Manuals
+
+I guess most manuals are written after-the-fact; documenting a program
+that's already there. This is not how this manual is written. When
+implementing something, I write the manual entry for that something
+straight away. I then see that it's difficult to explain the
+functionality, so I write how it's supposed to be, and then I change the
+implementation. Writing the documentation and writing the code goes
+hand in hand.
+
+This, of course, means that this manual has no, or little, flow. It
+documents absolutely everything in Gnus, but often not where you're
+looking for it. It is a reference manual, and not a guide to how to get
+started with Gnus.
+
+That would be a totally different book, that should be written using the
+reference manual as source material. It would look quite differently.
+
+
+@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 @acronym{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 back end
+@cindex back end
+Gnus considers mail and news to be mostly the same, really. The only
+difference is how to access the actual articles. News articles are
+commonly fetched via the protocol @acronym{NNTP}, whereas mail
+messages could be read from a file on the local disk. The internal
+architecture of Gnus thus comprises a ``front end'' and a number of
+``back ends''. Internally, when you enter a group (by hitting
+@key{RET}, say), you thereby invoke a function in the front end in
+Gnus. The front end then ``talks'' to a back end and says things like
+``Give me the list of articles in the foo group'' or ``Show me article
+number 4711''.
+
+So a back end mainly defines either a protocol (the @code{nntp} back
+end accesses news via @acronym{NNTP}, the @code{nnimap} back end
+accesses mail via @acronym{IMAP}) or a file format and directory
+layout (the @code{nnspool} back end accesses news via the common
+``spool directory'' format, the @code{nnml} back end access mail via a
+file format and directory layout that's quite similar).
+
+Gnus does not handle the underlying media, so to speak---this is all
+done by the back ends. A back end is a collection of functions to
+access the articles.
+
+However, sometimes the term ``back end'' is also used where ``server''
+would have been more appropriate. And then there is the term ``select
+method'' which can mean either. The Gnus terminology can be quite
+confusing.
+
+@item native
+@cindex native
+Gnus will always use one method (and back end) 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 back ends for getting
+news.
+
+@item secondary
+@cindex secondary
+Secondary back ends 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 @acronym{NOV} lines.
+
+@item @acronym{NOV}
+@cindex @acronym{NOV}
+When Gnus enters a group, it asks the back end 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 spool
+@cindex spool
+News servers store their articles locally in one fashion or other.
+One old-fashioned storage method is to have just one file per
+article. That's called a ``traditional spool''.
+
+@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 back end, 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
+@cindex temporary 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 RFC 1153.
+
+@item splitting
+@cindex splitting, terminology
+@cindex mail sorting
+@cindex mail filtering (splitting)
+The action of sorting your emails according to certain rules. Sometimes
+incorrectly called mail filtering.
+
+@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 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 @acronym{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 very 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 @acronym{NNTP} server will not be very fast. Not all @acronym{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.
+
+Use the following to enable all the available hiding features:
+@lisp
+(setq gnus-treat-hide-headers 'head
+ gnus-treat-hide-signature t
+ gnus-treat-hide-citation t)
+@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-read-newsrc-file
+If this is @code{nil}, Gnus will never read @file{.newsrc}---it will
+only read @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.
+
+
+@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.10.6} you have the right files loaded. Otherwise
+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
+@acronym{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.
+
+@cindex patches
+If you would like to contribute a patch to fix bugs or make
+improvements, please produce the patch using @samp{diff -u}.
+
+@cindex edebug
+If you want to debug your problem further before reporting, possibly
+in order to solve the problem yourself and send a patch, you can use
+edebug. Debugging Lisp code is documented in the Elisp manual
+(@pxref{Debugging, , Debugging Lisp Programs, elisp, The GNU Emacs
+Lisp Reference Manual}). To get you started with edebug, consider if
+you discover some weird behavior when pressing @kbd{c}, the first
+step is to do @kbd{C-h k c} and click on the hyperlink (Emacs only) in
+the documentation buffer that leads you to the function definition,
+then press @kbd{M-x edebug-defun RET} with point inside that function,
+return to Gnus and press @kbd{c} to invoke the code. You will be
+placed in the lisp buffer and can single step using @kbd{SPC} and
+evaluate expressions using @kbd{M-:} or inspect variables using
+@kbd{C-h v}, abort execution with @kbd{q}, and resume execution with
+@kbd{c} or @kbd{g}.
+
+@cindex elp
+@cindex profile
+@cindex slow
+Sometimes, a problem do not directly generate an elisp error but
+manifests itself by causing Gnus to be very slow. In these cases, you
+can use @kbd{M-x toggle-debug-on-quit} and press @kbd{C-g} when things are
+slow, and then try to analyze the backtrace (repeating the procedure
+helps isolating the real problem areas).
+
+A fancier approach is to use the elisp profiler, ELP. The profiler is
+(or should be) fully documented elsewhere, but to get you started
+there are a few steps that need to be followed. First, instrument the
+part of Gnus you are interested in for profiling, e.g. @kbd{M-x
+elp-instrument-package RET gnus} or @kbd{M-x elp-instrument-package
+RET message}. Then perform the operation that is slow and press
+@kbd{M-x elp-results}. You will then see which operations that takes
+time, and can debug them further. If the entire operation takes much
+longer than the time spent in the slowest function in the profiler
+output, you probably profiled the wrong part of Gnus. To reset
+profiling statistics, use @kbd{M-x elp-reset-all}. @kbd{M-x
+elp-restore-all} is supposed to remove profiling, but given the
+complexities and dynamic code generation in Gnus, it might not always
+work perfectly.
+
+@cindex gnu.emacs.gnus
+@cindex ding mailing list
+If you just need help, you are better off asking on
+@samp{gnu.emacs.gnus}. I'm not very helpful. You can also ask on
+@email{ding@@gnus.org, the ding mailing list}. Write to
+@email{ding-request@@gnus.org} to subscribe.
+
+
+@page
+@node Gnus Reference Guide
+@section Gnus Reference Guide
+
+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
+back ends (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.
+* Back End 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 back end.
+
+@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 gnus-group-find-parameter
+@findex gnus-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 back end
+@var{group} comes from supports @var{function}, return non-@code{nil}.
+
+@lisp
+(gnus-check-backend-function "request-scan" "nnml:misc")
+@result{} t
+@end lisp
+
+@item gnus-read-method
+@findex gnus-read-method
+Prompts the user for a select method.
+
+@end table
+
+
+@node Back End Interface
+@subsection Back End Interface
+
+Gnus doesn't know anything about @acronym{NNTP}, spools, mail or virtual
+groups. It only knows how to talk to @dfn{virtual servers}. A virtual
+server is a @dfn{back end} and some @dfn{back end 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 back end---say @code{nntp}---on
+something, it will normally include a virtual server name in the
+function parameters. (If not, the back end 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 back ends should be able to switch between several virtual servers.
+The standard back ends 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 back ends could be said to be @dfn{server-forming} back ends, and
+some might be said not to be. The latter are back ends 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.
+
+Gnus identifies each message by way of group name and article number. A
+few remarks about these article numbers might be useful. First of all,
+the numbers are positive integers. Secondly, it is normally not
+possible for later articles to ``re-use'' older article numbers without
+confusing Gnus. That is, if a group has ever contained a message
+numbered 42, then no other message may get that number, or Gnus will get
+mightily confused.@footnote{See the function
+@code{nnchoke-request-update-info}, @ref{Optional Back End Functions}.}
+Third, article numbers must be assigned in order of arrival in the
+group; this is not necessarily the same as the date of the message.
+
+The previous paragraph already mentions all the ``hard'' restrictions that
+article numbers must fulfill. But it seems that it might be useful to
+assign @emph{consecutive} article numbers, for Gnus gets quite confused
+if there are holes in the article numbering sequence. However, due to
+the ``no-reuse'' restriction, holes cannot be avoided altogether. It's
+also useful for the article numbers to start at 1 to avoid running out
+of numbers as long as possible.
+
+Note that by convention, back ends are named @code{nnsomething}, but
+Gnus also comes with some @code{nnnotbackends}, such as
+@file{nnheader.el}, @file{nnmail.el} and @file{nnoo.el}.
+
+In the examples and definitions I will refer to the imaginary back end
+@code{nnchoke}.
+
+@cindex @code{nnchoke}
+
+@menu
+* Required Back End Functions:: Functions that must be implemented.
+* Optional Back End Functions:: Functions that need not be implemented.
+* Error Messaging:: How to get messages and report errors.
+* Writing New Back Ends:: Extending old back ends.
+* Hooking New Back Ends Into Gnus:: What has to be done on the Gnus end.
+* Mail-like Back Ends:: Some tips on mail back ends.
+@end menu
+
+
+@node Required Back End Functions
+@subsubsection Required Back End 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 back ends do not fully support either---only
+sequences (lists) of article numbers, and most back ends do not support
+retrieval of @code{Message-ID}s. But they should try for both.
+
+The result data should either be HEADs or @acronym{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 @acronym{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 back end 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
+
+@cindex BNF
+(The version of BNF used here is the one used in RFC822.)
+
+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 = field 7*8[ <TAB> field ] 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 back end
+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 back end
+have reserved. All buffers that have been created by that back end
+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} value. 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. If the group contains no
+articles, the lowest article number should be reported as 1 and the
+highest as 0.
+
+@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 back ends.
+
+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. If the group
+contains no articles, the lowest article number should be reported as 1
+and the highest as 0.
+
+@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 Back End Functions
+@subsubsection Optional Back End 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 back end for
+alterations. This comes in handy if the back end 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 a non-@code{nil} value.
+
+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-set-mark GROUP ACTION &optional SERVER)
+
+Set/remove/add marks on articles. Normally Gnus handles the article
+marks (such as read, ticked, expired etc) internally, and store them in
+@file{~/.newsrc.eld}. Some back ends (such as @acronym{IMAP}) however carry
+all information about the articles on the server, so Gnus need to
+propagate the mark information to the server.
+
+@var{action} is a list of mark setting requests, having this format:
+
+@example
+(RANGE ACTION MARK)
+@end example
+
+@var{range} is a range of articles you wish to update marks on.
+@var{action} is @code{add} or @code{del}, used to add marks or remove
+marks (preserving all marks not mentioned). @var{mark} is a list of
+marks; where each mark is a symbol. Currently used marks are
+@code{read}, @code{tick}, @code{reply}, @code{expire}, @code{killed},
+@code{dormant}, @code{save}, @code{download}, @code{unsend},
+@code{forward} and @code{recent}, but your back end should, if
+possible, not limit itself to these.
+
+Given contradictory actions, the last action in the list should be the
+effective one. That is, if your action contains a request to add the
+@code{tick} mark on article 1 and, later in the list, a request to
+remove the mark on the same article, the mark should in fact be removed.
+
+An example action list:
+
+@example
+(((5 12 30) 'del '(tick))
+ ((10 . 90) 'add '(read expire))
+ ((92 94) 'del '(read)))
+@end example
+
+The function should return a range of articles it wasn't able to set the
+mark on (currently not used for anything).
+
+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 back end 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 back end 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 back end check for incoming articles, in one way or
+another. A mail back end will typically read the spool file or query
+the @acronym{POP} server when this function is invoked. The
+@var{group} doesn't have to be heeded---if the back end 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
+(i.e., the date format used in mail and news headers, and returned by
+the function @code{message-make-date} by default). The data should be
+in the active buffer format.
+
+It is okay for this function to return ``too many'' groups; some back ends
+might find it cheaper to return the full list of groups, rather than
+just the new groups. But don't do this for back ends with many groups.
+Normally, if the user creates the groups herself, there won't be too
+many groups, so @code{nnml} and the like are probably safe. But for
+back ends like @code{nntp}, where the groups have been created by the
+server, it is quite likely that there can be many groups.
+
+
+@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 back end 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.
+
+The group should exist before the back end is asked to accept the
+article for that group.
+
+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 back ends 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 back end
+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 back end in question. This function
+takes one argument---the server symbol.
+
+Internally, these functions access @var{back-end}@code{-status-string},
+so the @code{nnchoke} back end will have its error message stored in
+@code{nnchoke-status-string}.
+
+
+@node Writing New Back Ends
+@subsubsection Writing New Back Ends
+
+Many back ends 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
+back ends when writing new back ends. 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 back ends declare their public variables and functions by using a
+package called @code{nnoo}.
+
+To inherit functions from other back ends (and allow other back ends to
+inherit functions from the current back end), 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 back ends to map the variable to when executing
+a function in those back ends.
+
+@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 back ends should
+have.
+
+@lisp
+(nnoo-define-basics nndir)
+@end lisp
+
+@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 back ends can inherit it.
+
+@item nnoo-map-functions
+This macro allows mapping of functions from the current back end to
+functions from the parent back ends.
+
+@lisp
+(nnoo-map-functions nndir
+ (nnml-retrieve-headers 0 nndir-current-group 0 0)
+ (nnmh-request-article 0 nndir-current-group 0 0))
+@end lisp
+
+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 back ends. It should be the
+last thing in the source file, since it will only define functions that
+haven't already been defined.
+
+@lisp
+(nnoo-import nndir
+ (nnmh
+ nnmh-request-list
+ nnmh-request-newgroups)
+ (nnml))
+@end lisp
+
+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} back end.
+
+@lisp
+;;; @r{nndir.el --- single directory newsgroup access for Gnus}
+;; @r{Copyright (C) 1995,96 Free Software Foundation, Inc.}
+
+;;; @r{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")
+
+;;; @r{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 Back Ends Into Gnus
+@subsubsection Hooking New Back Ends Into Gnus
+
+@vindex gnus-valid-select-methods
+@findex gnus-declare-backend
+Having Gnus start using your new back end is rather easy---you just
+declare it with the @code{gnus-declare-backend} functions. This will
+enter the back end into the @code{gnus-valid-select-methods} variable.
+
+@code{gnus-declare-backend} takes two parameters---the back end name and
+an arbitrary number of @dfn{abilities}.
+
+Here's an example:
+
+@lisp
+(gnus-declare-backend "nnchoke" 'mail 'respool 'address)
+@end lisp
+
+The above line would then go in the @file{nnchoke.el} file.
+
+The abilities can be:
+
+@table @code
+@item mail
+This is a mailish back end---followups should (probably) go via mail.
+@item post
+This is a newsish back end---followups should (probably) go via news.
+@item post-mail
+This back end supports both mail and news.
+@item none
+This is neither a post nor mail back end---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 back ends.
+@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 back ends like
+@code{nntp}, but not @code{nnmbox}, for instance.
+@end table
+
+
+@node Mail-like Back Ends
+@subsubsection Mail-like Back Ends
+
+One of the things that separate the mail back ends from the rest of the
+back ends is the heavy dependence by most of the mail back ends 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 back end 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{back-end}@code{-save-mail} to
+save each article. @var{back-end}@code{-active-number} will be called to
+find the article number assigned to this article.
+
+The function also uses the following variables:
+@var{back-end}@code{-get-new-mail} (to see whether to get new mail for
+this back end); and @var{back-end}@code{-group-alist} and
+@var{back-end}@code{-active-file} to generate the new active file.
+@var{back-end}@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 @acronym{NOV} format in a mysterious fashion. One could
+almost suspect that the author looked at the @acronym{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
+RFC 1036 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}, and @code{extra}. 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.
+
+All these slots contain strings, except the @code{extra} slot, which
+contains an alist of header/value pairs (@pxref{To From Newsgroups}).
+
+
+@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 spc high-number spc low-number spc flag <NEWLINE>
+group = <non-white-space string>
+spc = " "
+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{C-M-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{C-M-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{C-M-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{~/.gnus.el}
+file to customize Gnus. (You can also use the @file{~/.emacs} file, but
+in order to set things of Gnus up, it is much better to use the
+@file{~/.gnus.el} file, @xref{Startup Files}.)
+
+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 @file{~/.gnus.el} file with lots of these to
+change how Gnus works.
+
+If you have put that thing in your @file{~/.gnus.el} file, it will be
+read and @code{eval}ed (which is Lisp-ese for ``run'') the next time you
+start Gnus. 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 GNU Free Documentation License
+@chapter GNU Free Documentation License
+@include doclicense.texi
+
+@node Index
+@chapter Index
+@printindex cp
+
+@node Key Index
+@chapter Key Index
+@printindex ky
+
+@summarycontents
+@contents
+@bye
+
+@iftex
+@iflatex
+\end{document}
+@end iflatex
+@end iftex
+
+@c Local Variables:
+@c mode: texinfo
+@c coding: iso-8859-1
+@c End:
+
+@ignore
+ arch-tag: c9fa47e7-78ca-4681-bda9-9fef45d1c819
+@end ignore
--- /dev/null
+@c The GNU General Public License.
+@center Version 3, 29 June 2007
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+@end display
+
+@heading Preamble
+
+The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works. By contrast,
+the GNU General Public License is intended to guarantee your freedom
+to share and change all versions of a program---to make sure it remains
+free software for all its users. We, the Free Software Foundation,
+use the GNU General Public License for most of our software; it
+applies also to any other work released this way by its authors. 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
+them 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 prevent others from denying you
+these rights or asking you to surrender the rights. Therefore, you
+have certain responsibilities if you distribute copies of the
+software, or if you modify it: responsibilities to respect the freedom
+of others.
+
+For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received. 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.
+
+Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software. For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the
+manufacturer can do so. This is fundamentally incompatible with the
+aim of protecting users' freedom to change the software. The
+systematic pattern of such abuse occurs in the area of products for
+individuals to use, which is precisely where it is most unacceptable.
+Therefore, we have designed this version of the GPL to prohibit the
+practice for those products. If such problems arise substantially in
+other domains, we stand ready to extend this provision to those
+domains in future versions of the GPL, as needed to protect the
+freedom of users.
+
+Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish
+to avoid the special danger that patents applied to a free program
+could make it effectively proprietary. To prevent this, the GPL
+assures that patents cannot be used to render the program non-free.
+
+The precise terms and conditions for copying, distribution and
+modification follow.
+
+@heading TERMS AND CONDITIONS
+
+@enumerate 0
+@item Definitions.
+
+``This License'' refers to version 3 of the GNU General Public License.
+
+``Copyright'' also means copyright-like laws that apply to other kinds
+of works, such as semiconductor masks.
+
+``The Program'' refers to any copyrightable work licensed under this
+License. Each licensee is addressed as ``you''. ``Licensees'' and
+``recipients'' may be individuals or organizations.
+
+To ``modify'' a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of
+an exact copy. The resulting work is called a ``modified version'' of
+the earlier work or a work ``based on'' the earlier work.
+
+A ``covered work'' means either the unmodified Program or a work based
+on the Program.
+
+To ``propagate'' a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy. Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+To ``convey'' a work means any kind of propagation that enables other
+parties to make or receive copies. Mere interaction with a user
+through a computer network, with no transfer of a copy, is not
+conveying.
+
+An interactive user interface displays ``Appropriate Legal Notices'' to
+the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License. If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+@item Source Code.
+
+The ``source code'' for a work means the preferred form of the work for
+making modifications to it. ``Object code'' means any non-source form
+of a work.
+
+A ``Standard Interface'' means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+The ``System Libraries'' of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form. A
+``Major Component'', in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+The ``Corresponding Source'' for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities. However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work. For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can
+regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same
+work.
+
+@item Basic Permissions.
+
+All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met. This License explicitly affirms your unlimited
+permission to run the unmodified Program. The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work. This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey,
+without conditions so long as your license otherwise remains in force.
+You may convey covered works to others for the sole purpose of having
+them make modifications exclusively for you, or provide you with
+facilities for running those works, provided that you comply with the
+terms of this License in conveying all material for which you do not
+control copyright. Those thus making or running the covered works for
+you must do so exclusively on your behalf, under your direction and
+control, on terms that prohibit them from making any copies of your
+copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the
+conditions stated below. Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+@item Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such
+circumvention is effected by exercising rights under this License with
+respect to the covered work, and you disclaim any intention to limit
+operation or modification of the work as a means of enforcing, against
+the work's users, your or third parties' legal rights to forbid
+circumvention of technological measures.
+
+@item Conveying Verbatim Copies.
+
+You may convey 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;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+@item Conveying Modified Source Versions.
+
+You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these
+conditions:
+
+@enumerate a
+@item
+The work must carry prominent notices stating that you modified it,
+and giving a relevant date.
+
+@item
+The work must carry prominent notices stating that it is released
+under this License and any conditions added under section 7. This
+requirement modifies the requirement in section 4 to ``keep intact all
+notices''.
+
+@item
+You must license the entire work, as a whole, under this License to
+anyone who comes into possession of a copy. This License will
+therefore apply, along with any applicable section 7 additional terms,
+to the whole of the work, and all its parts, regardless of how they
+are packaged. This License gives no permission to license the work in
+any other way, but it does not invalidate such permission if you have
+separately received it.
+
+@item
+If the work has interactive user interfaces, each must display
+Appropriate Legal Notices; however, if the Program has interactive
+interfaces that do not display Appropriate Legal Notices, your work
+need not make them do so.
+@end enumerate
+
+A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+``aggregate'' if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit. Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+@item Conveying Non-Source Forms.
+
+You may convey a covered work in object code form under the terms of
+sections 4 and 5, provided that you also convey the machine-readable
+Corresponding Source under the terms of this License, in one of these
+ways:
+
+@enumerate a
+@item
+Convey the object code in, or embodied in, a physical product
+(including a physical distribution medium), accompanied by the
+Corresponding Source fixed on a durable physical medium customarily
+used for software interchange.
+
+@item
+Convey the object code in, or embodied in, a physical product
+(including a physical distribution medium), accompanied by a written
+offer, valid for at least three years and valid for as long as you
+offer spare parts or customer support for that product model, to give
+anyone who possesses the object code either (1) a copy of the
+Corresponding Source for all the software in the product that is
+covered by this License, on a durable physical medium customarily used
+for software interchange, for a price no more than your reasonable
+cost of physically performing this conveying of source, or (2) access
+to copy the Corresponding Source from a network server at no charge.
+
+@item
+Convey individual copies of the object code with a copy of the written
+offer to provide the Corresponding Source. This alternative is
+allowed only occasionally and noncommercially, and only if you
+received the object code with such an offer, in accord with subsection
+6b.
+
+@item
+Convey the object code by offering access from a designated place
+(gratis or for a charge), and offer equivalent access to the
+Corresponding Source in the same way through the same place at no
+further charge. You need not require recipients to copy the
+Corresponding Source along with the object code. If the place to copy
+the object code is a network server, the Corresponding Source may be
+on a different server (operated by you or a third party) that supports
+equivalent copying facilities, provided you maintain clear directions
+next to the object code saying where to find the Corresponding Source.
+Regardless of what server hosts the Corresponding Source, you remain
+obligated to ensure that it is available for as long as needed to
+satisfy these requirements.
+
+@item
+Convey the object code using peer-to-peer transmission, provided you
+inform other peers where the object code and Corresponding Source of
+the work are being offered to the general public at no charge under
+subsection 6d.
+
+@end enumerate
+
+A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+A ``User Product'' is either (1) a ``consumer product'', which means any
+tangible personal property which is normally used for personal,
+family, or household purposes, or (2) anything designed or sold for
+incorporation into a dwelling. In determining whether a product is a
+consumer product, doubtful cases shall be resolved in favor of
+coverage. For a particular product received by a particular user,
+``normally used'' refers to a typical or common use of that class of
+product, regardless of the status of the particular user or of the way
+in which the particular user actually uses, or expects or is expected
+to use, the product. A product is a consumer product regardless of
+whether the product has substantial commercial, industrial or
+non-consumer uses, unless such uses represent the only significant
+mode of use of the product.
+
+``Installation Information'' for a User Product means any methods,
+procedures, authorization keys, or other information required to
+install and execute modified versions of a covered work in that User
+Product from a modified version of its Corresponding Source. The
+information must suffice to ensure that the continued functioning of
+the modified object code is in no case prevented or interfered with
+solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information. But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or
+updates for a work that has been modified or installed by the
+recipient, or for the User Product in which it has been modified or
+installed. Access to a network may be denied when the modification
+itself materially and adversely affects the operation of the network
+or violates the rules and protocols for communication across the
+network.
+
+Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+@item Additional Terms.
+
+``Additional permissions'' are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law. If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it. (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.) You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders
+of that material) supplement the terms of this License with terms:
+
+@enumerate a
+@item
+Disclaiming warranty or limiting liability differently from the terms
+of sections 15 and 16 of this License; or
+
+@item
+Requiring preservation of specified reasonable legal notices or author
+attributions in that material or in the Appropriate Legal Notices
+displayed by works containing it; or
+
+@item
+Prohibiting misrepresentation of the origin of that material, or
+requiring that modified versions of such material be marked in
+reasonable ways as different from the original version; or
+
+@item
+Limiting the use for publicity purposes of names of licensors or
+authors of the material; or
+
+@item
+Declining to grant rights under trademark law for use of some trade
+names, trademarks, or service marks; or
+
+@item
+Requiring indemnification of licensors and authors of that material by
+anyone who conveys the material (or modified versions of it) with
+contractual assumptions of liability to the recipient, for any
+liability that these contractual assumptions directly impose on those
+licensors and authors.
+@end enumerate
+
+All other non-permissive additional terms are considered ``further
+restrictions'' within the meaning of section 10. If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term. If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions; the
+above requirements apply either way.
+
+@item Termination.
+
+You may not propagate or modify a covered work except as expressly
+provided under this License. Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+@item Acceptance Not Required for Having Copies.
+
+You are not required to accept this License in order to receive or run
+a copy of the Program. Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance. However,
+nothing other than this License grants you permission to propagate or
+modify any covered work. These actions infringe copyright if you do
+not accept this License. Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+@item Automatic Licensing of Downstream Recipients.
+
+Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License. You are not responsible
+for enforcing compliance by third parties with this License.
+
+An ``entity transaction'' is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations. If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License. For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+@item Patents.
+
+A ``contributor'' is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based. The
+work thus licensed is called the contributor's ``contributor version''.
+
+A contributor's ``essential patent claims'' are all patent claims owned
+or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version. For
+purposes of this definition, ``control'' includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+In the following three paragraphs, a ``patent license'' is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement). To ``grant'' such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients. ``Knowingly relying'' means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+A patent license is ``discriminatory'' if it does not include within the
+scope of its coverage, prohibits the exercise of, or is conditioned on
+the non-exercise of one or more of the rights that are specifically
+granted under this License. You may not convey a covered work if you
+are a party to an arrangement with a third party that is in the
+business of distributing software, under which you make payment to the
+third party based on the extent of your activity of conveying the
+work, and under which the third party grants, to any of the parties
+who would receive the covered work from you, a discriminatory patent
+license (a) in connection with copies of the covered work conveyed by
+you (or copies made from those copies), or (b) primarily for and in
+connection with specific products or compilations that contain the
+covered work, unless you entered into that arrangement, or that patent
+license was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+@item No Surrender of Others' Freedom.
+
+If 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 convey
+a covered work so as to satisfy simultaneously your obligations under
+this License and any other pertinent obligations, then as a
+consequence you may not convey it at all. For example, if you agree
+to terms that obligate you to collect a royalty for further conveying
+from those to whom you convey the Program, the only way you could
+satisfy both those terms and this License would be to refrain entirely
+from conveying the Program.
+
+@item Use with the GNU Affero General Public License.
+
+Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work. The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+@item Revised Versions of this License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU 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 that a certain numbered version of the GNU General Public
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that numbered version or
+of any later version published by the Free Software Foundation. If
+the Program does not specify a version number of the GNU General
+Public License, you may choose any version ever published by the Free
+Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions
+of the GNU General Public License can be used, that proxy's public
+statement of acceptance of a version permanently authorizes you to
+choose that version for the Program.
+
+Later license versions may give you additional or different
+permissions. However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+@item Disclaimer of Warranty.
+
+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 Limitation of Liability.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
+CONVEYS 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.
+
+@item Interpretation of Sections 15 and 16.
+
+If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+@end enumerate
+
+@heading END OF TERMS AND CONDITIONS
+
+@heading 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
+state 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 a brief idea of what it does.}
+Copyright (C) @var{year} @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 3 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, see @url{http://www.gnu.org/licenses/}.
+@end smallexample
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+@smallexample
+@var{program} Copyright (C) @var{year} @var{name of author}
+This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}.
+This is free software, and you are welcome to redistribute it
+under certain conditions; type @samp{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, your
+program's commands might be different; for a GUI interface, you would
+use an ``about box''.
+
+You should also get your employer (if you work as a programmer) or school,
+if any, to sign a ``copyright disclaimer'' for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+@url{http://www.gnu.org/licenses/}.
+
+The GNU 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 Lesser General Public License instead of this License. But
+first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}.
+
+@ignore
+ arch-tag: 0c4a2556-f87e-464f-9b1d-efd920fcaf67
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename ../info/idlwave
+@settitle IDLWAVE User Manual
+@dircategory Emacs
+@direntry
+* IDLWAVE: (idlwave). Major mode and shell for IDL files.
+@end direntry
+@synindex ky cp
+@syncodeindex vr cp
+@syncodeindex fn cp
+@set VERSION 6.1
+@set EDITION 6.1
+@set IDLVERSION 6.3
+@set NSYSROUTINES 4346
+@set DATE April, 2007
+@set AUTHOR J.D. Smith & Carsten Dominik
+@set MAINTAINER J.D. Smith
+@c %**end of header
+@finalout
+
+@ifinfo
+This file documents IDLWAVE, a major mode for editing IDL files with
+Emacs, and interacting with an IDL shell run as a subprocess.
+
+This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE
+@value{VERSION}
+
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
+ 2006, 2007 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end ifinfo
+
+@titlepage
+@title IDLWAVE User Manual
+@subtitle Emacs major mode and shell for IDL
+@subtitle Edition @value{EDITION}, @value{DATE}
+
+@author by J.D. Smith & Carsten Dominik
+@page
+This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for
+IDLWAVE version @value{VERSION}, @value{DATE}.
+@sp 2
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
+ 2006, 2007 Free Software Foundation, Inc.
+@sp 2
+@cindex Copyright, of IDLWAVE
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end titlepage
+@contents
+
+@page
+
+@ifnottex
+
+@node Top, Introduction, (dir), (dir)
+
+IDLWAVE is a package which supports editing source code written in the
+Interactive Data Language (IDL), and running IDL as an inferior shell.
+
+@end ifnottex
+
+@menu
+* Introduction:: What IDLWAVE is, and what it is not
+* IDLWAVE in a Nutshell:: One page quick-start guide
+* Getting Started:: Tutorial
+* The IDLWAVE Major Mode:: The mode for editing IDL programs
+* The IDLWAVE Shell:: The mode for running IDL as an inferior program
+* Acknowledgements:: Who did what
+* Sources of Routine Info:: How does IDLWAVE know about routine XYZ
+* HTML Help Browser Tips::
+* Configuration Examples:: The user is king
+* Windows and MacOS:: What still works, and how
+* Troubleshooting:: When good computers turn bad
+* GNU Free Documentation License:: The license for this documentation.
+* Index:: Fast access
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Getting Started (Tutorial)
+
+* Lesson I -- Development Cycle::
+* Lesson II -- Customization::
+* Lesson III -- User Catalog::
+
+The IDLWAVE Major Mode
+
+* Code Formatting:: Making code look nice
+* Routine Info:: Calling Sequence and Keyword List
+* Online Help:: One key press from source to help
+* Completion:: Completing routine names and Keywords
+* Routine Source:: Finding routines, the easy way
+* Resolving Routines:: Force the Shell to compile a routine
+* Code Templates:: Frequent code constructs
+* Abbreviations:: Abbreviations for common commands
+* Actions:: Changing case, Padding, End checking
+* Doc Header:: Inserting a standard header
+* Motion Commands:: Moving through the structure of a program
+* Misc Options:: Things that fit nowhere else
+
+Code Formatting
+
+* Code Indentation:: Reflecting the logical structure
+* Continued Statement Indentation::
+* Comment Indentation:: Special indentation for comment lines
+* Continuation Lines:: Splitting statements over lines
+* Syntax Highlighting:: Font-lock support
+* Octals and Highlighting:: Why "123 causes problems
+
+Online Help
+
+* Help with HTML Documentation::
+* Help with Source::
+
+Completion
+
+* Case of Completed Words:: CaseOFcomPletedWords
+* Object Method Completion and Class Ambiguity:: obj->Method, what?
+* Object Method Completion in the Shell::
+* Class and Keyword Inheritance:: obj->Method, _EXTRA=e
+* Structure Tag Completion:: Completing state.Tag
+
+Actions
+
+* Block Boundary Check:: Is the END statement correct?
+* Padding Operators:: Enforcing space around `=' etc
+* Case Changes:: Enforcing upper case keywords
+
+The IDLWAVE Shell
+
+* Starting the Shell:: How to launch IDL as a subprocess
+* Using the Shell:: Interactively working with the Shell
+* Commands Sent to the Shell::
+* Debugging IDL Programs::
+* Examining Variables::
+* Custom Expression Examination::
+
+Debugging IDL Programs
+
+* A Tale of Two Modes::
+* Debug Key Bindings::
+* Breakpoints and Stepping::
+* Compiling Programs::
+* Walking the Calling Stack::
+* Electric Debug Mode::
+
+Sources of Routine Info
+
+* Routine Definitions:: Where IDL Routines are defined.
+* Routine Information Sources:: So how does IDLWAVE know about...
+* Catalogs::
+* Load-Path Shadows:: Routines defined in several places
+* Documentation Scan:: Scanning the IDL Manuals
+
+Catalogs
+
+* Library Catalogs::
+* User Catalog::
+
+@end detailmenu
+@end menu
+
+@node Introduction, IDLWAVE in a Nutshell, Top, Top
+@chapter Introduction
+@cindex Introduction
+@cindex CORBA (Common Object Request Broker Architecture)
+@cindex Interface Definition Language
+@cindex Interactive Data Language
+@cindex cc-mode.el
+@cindex @file{idl.el}
+@cindex @file{idl-shell.el}
+@cindex Feature overview
+
+IDLWAVE is a package which supports editing source files written in
+the Interactive Data Language (IDL), and running IDL as an inferior shell@footnote{IDLWAVE can also be used
+for editing source files for the related WAVE/CL language, but with only
+limited support.}. It is a feature-rich replacement for the IDLDE
+development environment included with IDL, and uses the full power of
+Emacs to make editing and running IDL programs easier, quicker, and more
+structured.
+
+IDLWAVE consists of two main parts: a major mode for editing IDL
+source files (@code{idlwave-mode}) and a mode for running the IDL
+program as an inferior shell (@code{idlwave-shell-mode}). Although
+one mode can be used without the other, both work together closely to
+form a complete development environment. Here is a brief summary of
+what IDLWAVE does:
+
+@itemize @bullet
+@item
+Smart code indentation and automatic-formatting.
+@item
+Three level syntax highlighting support.
+@item
+Context-sensitive display of calling sequences and keywords for more
+than 1000 native IDL routines, extendible to any additional number of
+local routines, and already available with many pre-scanned libraries.
+@item
+Fast, context-sensitive online HTML help, or source-header help for
+undocumented routines.
+@item
+Context sensitive completion of routine names, keywords, system
+variables, class names and much more.
+@item
+Easy insertion of code templates and abbreviations of common constructs.
+@item
+Automatic corrections to enforce a variety of customizable coding
+standards.
+@item
+Integrity checks and auto-termination of logical blocks.
+@item
+Routine name space conflict search with likelihood-of-use ranking.
+@item
+Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs).
+@item
+Documentation support.
+@item
+Running IDL as an inferior Shell with history search, command line
+editing and all the completion and routine info capabilities present in
+IDL source buffers.
+@item
+Full handling of debugging with breakpoints, with interactive setting
+of break conditions, and easy stepping through code.
+@item
+Compilation, execution and interactive single-keystroke debugging of
+programs directly from the source buffer.
+@item
+Quick, source-guided navigation of the calling stack, with variable
+inspection, etc.
+@item
+Examining variables and expressions with a mouse click.
+@item
+And much, much more...
+@end itemize
+
+@ifnottex
+@cindex Screenshots
+Here are a number of screenshots showing IDLWAVE in action:
+
+@itemize @bullet
+@item
+@uref{http://idlwave.org/screenshots/emacs_21_nav.gif,An IDLWAVE buffer}
+@item
+@uref{http://idlwave.org/screenshots/emacs_21_keys.gif,A keyword being completed}
+@item
+@uref{http://idlwave.org/screenshots/emacs_21_help.gif,Online help text.}
+@item
+@uref{http://idlwave.org/screenshots/emacs_21_ri.gif,Routine information displayed}
+@item
+@uref{http://idlwave.org/screenshots/emacs_21_bp.gif,Debugging code
+stopped at a breakpoint}
+@end itemize
+@end ifnottex
+
+IDLWAVE is the distant successor to the @file{idl.el} and
+@file{idl-shell.el} files written by Chris Chase. The modes and files
+had to be renamed because of a name space conflict with CORBA's
+@code{idl-mode}, defined in Emacs in the file @file{cc-mode.el}.
+
+In this manual, each section ends with a list of related user options.
+Don't be confused by the sheer number of options available --- in most
+cases the default settings are just fine. The variables are listed here
+to make sure you know where to look if you want to change anything. For
+a full description of what a particular variable does and how to
+configure it, see the documentation string of that variable (available
+with @kbd{C-h v}). Some configuration examples are also given in the
+appendix.
+
+@node IDLWAVE in a Nutshell, Getting Started, Introduction, Top
+@chapter IDLWAVE in a Nutshell
+@cindex Summary of important commands
+@cindex IDLWAVE in a Nutshell
+@cindex Nutshell, IDLWAVE in a
+
+@subheading Editing IDL Programs
+
+@multitable @columnfractions .15 .85
+@item @key{TAB}
+@tab Indent the current line relative to context.
+@item @kbd{C-M-\}
+@tab Re-indent all lines in the current region.
+@item @kbd{C-M-q}
+@tab Re-indent all lines in the current routine.
+@item @kbd{C-u @key{TAB}}
+@tab Re-indent all lines in the current statement.
+@item @kbd{M-@key{RET}}
+@tab Start a continuation line, splitting the current line at point.
+@item @kbd{M-;}
+@tab Start new comment at line beginning or after code, or (un)comment
+highlighted region.
+@item @kbd{M-q}
+@tab Fill the current comment paragraph.
+@item @kbd{C-c ?}
+@tab Display calling sequence and keywords for the procedure or function call
+at point.
+@item @kbd{M-?}
+@tab Load context sensitive online help for nearby routine, keyword, etc.
+@item @kbd{M-@key{TAB}}
+@tab Complete a procedure name, function name or keyword in the buffer.
+@item @kbd{C-c C-i}
+@tab Update IDLWAVE's knowledge about functions and procedures.
+@item @kbd{C-c C-v}
+@tab Visit the source code of a procedure/function.
+@item @kbd{C-u C-c C-v}
+@tab Visit the source code of a procedure/function in this buffer.
+@item @kbd{C-c C-h}
+@tab Insert a standard documentation header.
+@item @kbd{C-c @key{RET}}
+@tab Insert a new timestamp and history item in the documentation header.
+@end multitable
+
+@subheading Running the IDLWAVE Shell, Debugging Programs
+
+@multitable @columnfractions .15 .85
+@item @kbd{C-c C-s}
+@tab Start IDL as a subprocess and/or switch to the shell buffer.
+@item @key{Up}, @kbd{M-p}
+@tab Cycle back through IDL command history.
+@item @key{Down},@kbd{M-n}
+@tab Cycle forward.
+@item @kbd{@key{TAB}}
+@tab Complete a procedure name, function name or keyword in the shell buffer.
+@item @kbd{C-c C-d C-c}
+@tab Save and compile the source file in the current buffer.
+@item @kbd{C-c C-d C-e}
+@tab Compile and run the current region.
+@item @kbd{C-c C-d C-x}
+@tab Go to next syntax error.
+@item @kbd{C-c C-d C-v}
+@tab Switch to electric debug mode.
+@item @kbd{C-c C-d C-b}
+@tab Set a breakpoint at the nearest viable source line.
+@item @kbd{C-c C-d C-d}
+@tab Clear the nearest breakpoint.
+@item @kbd{C-c C-d [}
+@tab Go to the previous breakpoint.
+@item @kbd{C-c C-d ]}
+@tab Go to the next breakpoint.
+@item @kbd{C-c C-d C-p}
+@tab Print the value of the expression near point in IDL.
+@end multitable
+
+@subheading Commonly used Settings in @file{.emacs}
+@lisp
+;; Change the indentation preferences
+;; Start autoloading routine info after 2 idle seconds
+(setq idlwave-init-rinfo-when-idle-after 2)
+;; Pad operators with spaces
+(setq idlwave-do-actions t
+ idlwave-surround-by-blank t)
+;; Syntax Highlighting
+(add-hook 'idlwave-mode-hook 'turn-on-font-lock)
+;; Automatically start the shell when needed
+(setq idlwave-shell-automatic-start t)
+;; Bind debugging commands with CONTROL and SHIFT modifiers
+(setq idlwave-shell-debug-modifiers '(control shift))
+@end lisp
+
+@html
+<A NAME="TUTORIAL"></A>
+@end html
+
+@node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top
+@chapter Getting Started (Tutorial)
+@cindex Quick-Start
+@cindex Tutorial
+@cindex Getting Started
+
+@menu
+* Lesson I -- Development Cycle::
+* Lesson II -- Customization::
+* Lesson III -- User Catalog::
+@end menu
+
+@node Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started
+@section Lesson I: Development Cycle
+
+The purpose of this tutorial is to guide you through a very basic
+development cycle using IDLWAVE. We will paste a simple program into
+a buffer and use the shell to compile, debug and run it. On the way
+we will use many of the important IDLWAVE commands. Note, however,
+that IDLWAVE has many more capabilities than covered here, which can
+be discovered by reading the entire manual, or hovering over the
+shoulder of your nearest IDLWAVE guru for a few days.
+
+It is assumed that you have access to Emacs or XEmacs with the full
+IDLWAVE package including online help. We also assume that you are
+familiar with Emacs and can read the nomenclature of key presses in
+Emacs (in particular, @kbd{C} stands for @key{CONTROL} and @kbd{M} for
+@key{META} (often the @key{ALT} key carries this functionality)).
+
+Open a new source file by typing:
+
+@example
+@kbd{C-x C-f tutorial.pro @key{RET}}
+@end example
+
+A buffer for this file will pop up, and it should be in IDLWAVE mode,
+indicated in the mode line just below the editing window. Also, the
+menu bar should contain @samp{IDLWAVE}.
+
+Now cut-and-paste the following code, also available as
+@file{tutorial.pro} in the IDLWAVE distribution.
+
+@example
+function daynr,d,m,y
+ ;; compute a sequence number for a date
+ ;; works 1901-2099.
+ if y lt 100 then y = y+1900
+ if m le 2 then delta = 1 else delta = 0
+ m1 = m + delta*12 + 1
+ y1 = y * delta
+ return, d + floor(m1*30.6)+floor(y1*365.25)+5
+end
+
+function weekday,day,month,year
+ ;; compute weekday number for date
+ nr = daynr(day,month,year)
+ return, nr mod 7
+end
+
+pro plot_wday,day,month
+ ;; Plot the weekday of a date in the first 10 years of this century.
+ years = 2000,+indgen(10)
+ wdays = intarr(10)
+ for i=0,n_elements(wdays)-1 do begin
+ wdays[i] = weekday(day,month,years[i])
+ end
+ plot,years,wdays,YS=2,YT="Wday (0=Sunday)"
+end
+@end example
+
+The indentation probably looks funny, since it's different from the
+settings you use, so use the @key{TAB} key in each line to
+automatically line it up (or, more quickly, @emph{select} the entire
+buffer with @kbd{C-x h}, and indent the whole region with
+@kbd{C-M-\}). Notice how different syntactical elements are
+highlighted in different colors, if you have set up support for
+font-lock.
+
+Let's check out two particular editing features of IDLWAVE. Place the
+cursor after the @code{end} statement of the @code{for} loop and press
+@key{SPC}. IDLWAVE blinks back to the beginning of the block and
+changes the generic @code{end} to the specific @code{endfor}
+automatically (as long as the variable @code{idlwave-expand-generic-end}
+is turned on --- @pxref{Lesson II -- Customization}). Now place the
+cursor in any line you would like to split and press @kbd{M-@key{RET}}.
+The line is split at the cursor position, with the continuation @samp{$}
+and indentation all taken care of. Use @kbd{C-/} to undo the last
+change.
+
+The procedure @code{plot_wday} is supposed to plot the day of the week
+of a given date for the first 10 years of the 21st century. As in
+most code, there are a few bugs, which we are going to use IDLWAVE to
+help us fix.
+
+First, let's launch the IDLWAVE shell. You do this with the command
+@kbd{C-c C-s}. The Emacs window will split or another window will popup
+to display IDL running in a shell interaction buffer. Type a few
+commands like @code{print,!PI} to convince yourself that you can work
+there just as well as in a terminal, or the IDLDE. Use the arrow keys
+to cycle through your command history. Are we having fun now?
+
+Now go back to the source window and type @kbd{C-c C-d C-c} to compile
+the program. If you watch the shell buffer, you see that IDLWAVE types
+@samp{.run "tutorial.pro"} for you. But the compilation fails because
+there is a comma in the line @samp{years=...}. The line with the error
+is highlighted and the cursor positioned at the error, so remove the
+comma (you should only need to hit @kbd{Delete}!). Compile again, using
+the same keystrokes as before. Notice that the file is automatically
+saved for you. This time everything should work fine, and you should
+see the three routines compile.
+
+Now we want to use the command to plot the day of the week on January
+1st. We could type the full command ourselves, but why do that? Go
+back to the shell window, type @samp{plot_} and hit @key{TAB}. After
+a bit of a delay (while IDLWAVE initializes its routine info database,
+if necessary), the window will split to show all procedures it knows
+starting with that string, and @w{@code{plot_wday}} should be one of
+them. Saving the buffer alerted IDLWAVE about this new routine.
+Click with the middle mouse button on @code{plot_wday} and it will be
+copied to the shell buffer, or if you prefer, add @samp{w} to
+@samp{plot_} to make it unambiguous (depending on what other routines
+starting with @samp{plot_} you have installed on your system), hit
+@key{TAB} again, and the full routine name will be completed. Now
+provide the two arguments:
+
+@example
+plot_wday,1,1
+@end example
+
+@noindent and press @key{RET}. This fails with an error message telling
+you the @code{YT} keyword to plot is ambiguous. What are the allowed
+keywords again? Go back to the source window and put the cursor into
+the `plot' line and press @kbd{C-c ?}. This shows the routine info
+window for the plot routine, which contains a list of keywords, along
+with the argument list. Oh, we wanted @code{YTITLE}. Fix that up.
+Recompile with @kbd{C-c C-d C-c}. Jump back into the shell with
+@kbd{C-c C-s}, press the @key{UP} arrow to recall the previous command
+and execute again.
+
+This time we get a plot, but it is pretty ugly --- the points are all
+connected with a line. Hmm, isn't there a way for @code{plot} to use
+symbols instead? What was that keyword? Position the cursor on the
+plot line after a comma (where you'd normally type a keyword), and hit
+@kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha,
+there it is, @code{PSYM}. Middle click to insert it. An @samp{=}
+sign is included for you too. Now what were the values of @code{PSYM}
+supposed to be? With the cursor on or after the keyword, press
+@kbd{M-?} for online help (alternatively, you could have right clicked
+on the colored keyword itself in the completion list). A browser will
+pop up showing the HTML documentation for the @code{PYSM} keyword.
+OK, let's use diamonds=4. Fix this, recompile (you know the command
+by now: @kbd{C-c C-d C-c}), go back to the shell (if it's vanished,
+you know what to do: @kbd{C-c C-s}) and execute again. Now things
+look pretty good.
+
+Let's try a different day --- how about April fool's day?
+
+@example
+plot_wday,1,4
+@end example
+
+Oops, this looks very wrong. All April Fool's days cannot be Fridays!
+We've got a bug in the program, perhaps in the @code{daynr} function.
+Let's put a breakpoint on the last line there. Position the cursor on
+the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. IDL sets a
+breakpoint (as you see in the shell window), and the break line is
+indicated. Back to the shell buffer, re-execute the previous command.
+IDL stops at the line with the breakpoint. Now hold down the SHIFT
+key and click with the middle mouse button on a few variables there:
+@samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe @code{d} isn't
+the correct type. CONTROL-SHIFT middle-click on it for help. Well,
+it's an integer, so that's not the problem. Aha, @samp{y1} is zero,
+but it should be the year, depending on delta. Shift click
+@samp{delta} to see that it's 0. Below, we see the offending line:
+@samp{y1=y*delta...} the multiplication should have been a minus sign!
+Hit @kbd{q} to exit the debugging mode, and fix the line to read:
+
+@example
+y1 = y - delta
+@end example
+
+Now remove all breakpoints: @kbd{C-c C-d C-a}. Recompile and rerun the
+command. Everything should now work fine. How about those leap years?
+Change the code to plot 100 years and see that every 28 years, the
+sequence of weekdays repeats.
+
+@node Lesson II -- Customization, Lesson III -- User Catalog, Lesson I -- Development Cycle, Getting Started
+@section Lesson II: Customization
+
+Emacs is probably the most customizable piece of software ever written,
+and it would be a shame if you did not make use of this to adapt IDLWAVE
+to your own preferences. Customizing Emacs or IDLWAVE is accomplished
+by setting Lisp variables in the @file{.emacs} file in your home
+directory --- but do not be dismayed; for the most part, you can just
+copy and work from the examples given here.
+
+Let's first use a boolean variable. These are variables which you turn
+on or off, much like a checkbox. A value of @samp{t} means on, a value
+of @samp{nil} means off. Copy the following line into your
+@file{.emacs} file, exit and restart Emacs.
+
+@lisp
+(setq idlwave-reserved-word-upcase t)
+@end lisp
+
+When this option is turned on, each reserved word you type into an IDL
+source buffer will be converted to upper case when you press @key{SPC}
+or @key{RET} right after the word. Try it out! @samp{if} changes to
+@samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this
+behavior, remove the option again from your @file{.emacs} file and
+restart Emacs.
+
+You likely have your own indentation preferences for IDL code. For
+example, some may prefer to indent the main block of an IDL program
+slightly from the margin and use only 3 spaces as indentation between
+@code{BEGIN} and @code{END}. Try the following lines in @file{.emacs}:
+
+@lisp
+(setq idlwave-main-block-indent 1)
+(setq idlwave-block-indent 3)
+(setq idlwave-end-offset -3)
+@end lisp
+
+Restart Emacs, and re-indent the program we developed in the first part
+of this tutorial with @kbd{C-c h} and @kbd{C-M-\}. You may want to keep
+these lines in @file{.emacs}, with values adjusted to your likings. If
+you want to get more information about any of these variables, type,
+e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}. To find which
+variables can be customized, look for items marked @samp{User Option:}
+throughout this manual.
+
+If you cannot seem to master this Lisp customization in @file{.emacs},
+there is another, more user-friendly way to customize all the IDLWAVE
+variables. You can access it through the IDLWAVE menu in one of the
+@file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE
+Group}. Here you'll be presented with all the various variables grouped
+into categories. You can navigate the hierarchy (e.g. @samp{IDLWAVE
+Code Formatting->Idlwave Abbrev And Indent Action->Idlwave Expand
+Generic End} to turn on @code{END} expansion), read about the variables,
+change them, and `Save for Future Sessions'. Few of these variables
+need customization, but you can exercise considerable control over
+IDLWAVE's functionality with them.
+
+You may also find the key bindings used for the debugging commands too
+long and complicated. Often we have heard complaints along the lines
+of, ``Do I really have to go through the finger gymnastics of @kbd{C-c
+C-d C-c} to run a simple command?'' Due to Emacs rules and
+conventions, shorter bindings cannot be set by default, but you can
+easily enable them. First, there is a way to assign all debugging
+commands in a single sweep to another simpler combination. The only
+problem is that we have to use something which Emacs does not need for
+other important commands. One good option is to execute debugging
+commands by holding down @key{CONTROL} and @key{SHIFT} while pressing
+a single character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c}
+for compiling the current source file, @kbd{C-S-a} for deleting all
+breakpoints (try it, it's easier). You can enable this with:
+
+@lisp
+(setq idlwave-shell-debug-modifiers '(shift control))
+@end lisp
+
+@noindent If you have a special keyboard with, for example, a
+@key{SUPER} key, you could even shorten that:
+
+@lisp
+(setq idlwave-shell-debug-modifiers '(super))
+@end lisp
+
+@noindent to get compilation on @kbd{S-c}. Often, a modifier key like
+@key{SUPER} or @key{HYPER} is bound or can be bound to an otherwise
+unused key on your keyboard --- consult your system documentation.
+
+You can also assign specific commands to keys. This you must do in the
+@emph{mode-hook}, a special function which is run when a new IDLWAVE
+buffer gets set up. The possibilities for key customization are
+endless. Here we set function keys f4-f8 to common debugging commands.
+
+@lisp
+;; First for the source buffer
+(add-hook 'idlwave-mode-hook
+ (lambda ()
+ (local-set-key [f4] 'idlwave-shell-retall)
+ (local-set-key [f5] 'idlwave-shell-break-here)
+ (local-set-key [f6] 'idlwave-shell-clear-current-bp)
+ (local-set-key [f7] 'idlwave-shell-cont)
+ (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
+;; Then for the shell buffer
+(add-hook 'idlwave-shell-mode-hook
+ (lambda ()
+ (local-set-key [f4] 'idlwave-shell-retall)
+ (local-set-key [f5] 'idlwave-shell-break-here)
+ (local-set-key [f6] 'idlwave-shell-clear-current-bp)
+ (local-set-key [f7] 'idlwave-shell-cont)
+ (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
+@end lisp
+
+@node Lesson III -- User Catalog, , Lesson II -- Customization, Getting Started
+@section Lesson III: User and Library Catalogs
+
+We have already used the routine info display in the first part of this
+tutorial. This was the invoked using @kbd{C-c ?}, and displays
+information about the IDL routine near the cursor position. Wouldn't it
+be nice to have the same kind of information available for your own
+routines and for the huge amount of code in major libraries like JHUPL
+or the IDL-Astro library? In many cases, you may already have this
+information. Files named @file{.idlwave_catalog} in library directories
+contain scanned information on the routines in that directory; many
+popular libraries ship with these ``library catalogs'' pre-scanned.
+Users can scan their own routines in one of two ways: either using the
+supplied tool to scan directories and build their own
+@file{.idlwave_catalog} files, or using the built-in method to create a
+single ``user catalog'', which we'll show here. @xref{Catalogs}, for
+more information on choosing which method to use.
+
+To build a user catalog, select @code{Routine Info/Select Catalog
+Directories} from the IDLWAVE entry in the menu bar. If necessary,
+start the shell first with @kbd{C-c C-s} (@pxref{Starting the Shell}).
+IDLWAVE will find out about the IDL @code{!PATH} variable and offer a
+list of directories on the path. Simply select them all (or whichever
+you want --- directories with existing library catalogs will not be
+selected by default) and click on the @samp{Scan&Save} button. Then
+go for a cup of coffee while IDLWAVE collects information for each and
+every IDL routine on your search path. All this information is
+written to the file @file{.idlwave/idlusercat.el} in your home
+directory and will from now on automatically load whenever you use
+IDLWAVE. You may find it necessary to rebuild the catalog on occasion
+as your local libraries change, or build a library catalog for those
+directories instead. Invoke routine info (@kbd{C-c ?}) or completion
+(@kbd{M-@key{TAB}}) on any routine or partial routine name you know to
+be located in the library. E.g., if you have scanned the IDL-Astro
+library:
+
+@example
+ a=readf@key{M-@key{TAB}}
+@end example
+
+expands to `readfits('. Then try
+
+@example
+ a=readfits(@key{C-c ?}
+@end example
+
+and you get:
+
+@example
+Usage: Result = READFITS(filename, header, heap)
+...
+@end example
+
+I hope you made it until here. Now you are set to work with IDLWAVE.
+On the way you will want to change other things, and to learn more
+about the possibilities not discussed in this short tutorial. Read
+the manual, look at the documentation strings of interesting variables
+(with @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the
+remaining questions on the newsgroup @code{comp.lang.idl-pvwave}.
+
+@node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top
+@chapter The IDLWAVE Major Mode
+@cindex IDLWAVE major mode
+@cindex Major mode, @code{idlwave-mode}
+
+The IDLWAVE major mode supports editing IDL source files. In this
+chapter we describe the main features of the mode and how to customize
+them.
+
+@menu
+* Code Formatting:: Making code look nice
+* Routine Info:: Calling Sequence and Keyword List
+* Online Help:: One key press from source to help
+* Completion:: Completing routine names and Keywords
+* Routine Source:: Finding routines, the easy way
+* Resolving Routines:: Force the Shell to compile a routine
+* Code Templates:: Frequent code constructs
+* Abbreviations:: Abbreviations for common commands
+* Actions:: Changing case, Padding, End checking
+* Doc Header:: Inserting a standard header
+* Motion Commands:: Moving through the structure of a program
+* Misc Options:: Things that fit nowhere else
+@end menu
+
+@node Code Formatting, Routine Info, The IDLWAVE Major Mode, The IDLWAVE Major Mode
+@section Code Formatting
+@cindex Code formatting
+@cindex Formatting, of code
+
+@menu
+* Code Indentation:: Reflecting the logical structure
+* Continued Statement Indentation::
+* Comment Indentation:: Special indentation for comment lines
+* Continuation Lines:: Splitting statements over lines
+* Syntax Highlighting:: Font-lock support
+* Octals and Highlighting:: Why "123 causes problems
+@end menu
+
+The IDL language, with its early roots in FORTRAN, modern
+implementation in C, and liberal borrowing of features of many vector
+and other languages along its 25+ year history, has inherited an
+unusual mix of syntax elements. Left to his or her own devices, a
+novice IDL programmer will often conjure code which is very difficult
+to read and impossible to adapt. Much can be gleaned from studying
+available IDL code libraries for coding style pointers, but, due to
+the variety of IDL syntax elements, replicating this style can be
+challenging at best. Luckily, IDLWAVE understands the structure of
+IDL code very well, and takes care of almost all formatting issues for
+you. After configuring it to match your coding standards, you can
+rely on it to help keep your code neat and organized.
+
+
+@node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting
+@subsection Code Indentation
+@cindex Code indentation
+@cindex Indentation
+
+Like all Emacs programming modes, IDLWAVE performs code indentation.
+The @key{TAB} key indents the current line relative to context.
+@key{LFD} insert a newline and indents the new line. The indentation is
+governed by a number of variables. IDLWAVE indents blocks (between
+@code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and
+continuation lines.
+
+@cindex Foreign code, adapting
+@cindex Indentation, of foreign code
+@kindex C-M-\
+To re-indent a larger portion of code (e.g. when working with foreign
+code written with different conventions), use @kbd{C-M-\}
+(@code{indent-region}) after marking the relevant code. Useful marking
+commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current
+subprogram). The command @kbd{C-M-q} reindents the entire current
+routine. @xref{Actions}, for information how to impose additional
+formatting conventions on foreign code.
+
+@defopt idlwave-main-block-indent (@code{2})
+Extra indentation for the main block of code. That is the block between
+the FUNCTION/PRO statement and the END statement for that program
+unit.
+@end defopt
+
+@defopt idlwave-block-indent (@code{3})
+Extra indentation applied to block lines. If you change this, you
+probably also want to change @code{idlwave-end-offset}.
+@end defopt
+
+@defopt idlwave-end-offset (@code{-3})
+Extra indentation applied to block END lines. A value equal to negative
+@code{idlwave-block-indent} will make END lines line up with the block
+BEGIN lines.
+@end defopt
+
+@node Continued Statement Indentation, Comment Indentation, Code Indentation, Code Formatting
+@subsection Continued Statement Indentation
+@cindex Indentation, continued statement
+@cindex Continued statement indentation
+Continuation lines (following a line ending with @code{$}) can receive a
+fixed indentation offset from the main level, but in several situations
+IDLWAVE can use a special form of indentation which aligns continued
+statements more naturally. Special indentation is calculated for
+continued routine definition statements and calls, enclosing parentheses
+(like function calls, structure/class definitions, explicit structures
+or lists, etc.), and continued assignments. An attempt is made to line
+up with the first non-whitespace character after the relevant opening
+punctuation mark (@code{,},@code{(},@code{@{},@code{[},@code{=}). For
+lines without any non-comment characters on the line with the opening
+punctuation, the continued line(s) are aligned just past the
+punctuation. An example:
+
+@example
+function foo, a, b, $
+ c, d
+ bar = sin( a + b + $
+ c + d)
+end
+@end example
+@noindent
+
+The only drawback to this special continued statement indentation is
+that it consumes more space, e.g., for long function names or left hand
+sides of an assignment:
+
+@example
+function thisfunctionnameisverylongsoitwillleavelittleroom, a, b, $
+ c, d
+@end example
+
+You can instruct IDLWAVE when to avoid using this special continuation
+indentation by setting the variable
+@code{idlwave-max-extra-continuation-indent}, which specifies the
+maximum additional indentation beyond the basic indent to be
+tolerated, otherwise defaulting to a fixed-offset from the enclosing
+indent (the size of which offset is set in
+@code{idlwave-continuation-indent}). As a special case, continuations
+of routine calls without any arguments or keywords will @emph{not}
+align the continued line, under the assumption that you continued
+because you needed the space.
+
+Also, since the indentation level can be somewhat dynamic in continued
+statements with special continuation indentation, especially if
+@code{idlwave-max-extra-continuation-indent} is small, the key
+@kbd{C-u @key{TAB}} will re-indent all lines in the current statement.
+Note that @code{idlwave-indent-to-open-paren}, if non-@code{nil},
+overrides the @code{idlwave-max-extra-continuation-indent} limit, for
+parentheses only, forcing them always to line up.
+
+
+@defopt idlwave-continuation-indent (@code{2})
+Extra indentation applied to normal continuation lines.
+@end defopt
+
+@defopt idlwave-max-extra-continuation-indent (@code{20})
+The maximum additional indentation (over the basic continuation-indent)
+that will be permitted for special continues. To effectively disable
+special continuation indentation, set to @code{0}. To enable it
+constantly, set to a large number (like @code{100}). Note that the
+indentation in a long continued statement never decreases from line to
+line, outside of nested parentheses statements.
+@end defopt
+
+@defopt idlwave-indent-to-open-paren (@code{t})
+Non-@code{nil} means indent continuation lines to innermost open
+parenthesis, regardless of whether the
+@code{idlwave-max-extra-continuation-indent} limit is satisfied.
+@end defopt
+
+@node Comment Indentation, Continuation Lines, Continued Statement Indentation, Code Formatting
+@subsection Comment Indentation
+@cindex Comment indentation
+@cindex Hanging paragraphs
+@cindex Paragraphs, filling
+@cindex Paragraphs, hanging
+
+In IDL, lines starting with a @samp{;} are called @emph{comment lines}.
+Comment lines are indented as follows:
+
+@multitable @columnfractions .1 .90
+@item @code{;;;}
+@tab The indentation of lines starting with three semicolons remains
+unchanged.
+@item @code{;;}
+@tab Lines starting with two semicolons are indented like the surrounding code.
+@item @code{;}
+@tab Lines starting with a single semicolon are indented to a minimum column.
+@end multitable
+
+@noindent
+The indentation of comments starting in column 0 is never changed.
+
+@defopt idlwave-no-change-comment
+The indentation of a comment starting with this regexp will not be
+changed.
+@end defopt
+
+@defopt idlwave-begin-line-comment
+A comment anchored at the beginning of line.
+@end defopt
+
+@defopt idlwave-code-comment
+A comment that starts with this regexp is indented as if it is a part of
+IDL code.
+@end defopt
+
+@node Continuation Lines, Syntax Highlighting, Comment Indentation, Code Formatting
+@subsection Continuation Lines and Filling
+@cindex Continuation lines
+@cindex Line splitting
+@cindex String splitting
+@cindex Splitting, of lines
+
+@kindex M-@key{RET}
+In IDL, a newline character terminates a statement unless preceded by a
+@samp{$}. If you would like to start a continuation line, use
+@kbd{M-@key{RET}}, which calls the command @code{idlwave-split-line}.
+It inserts the continuation character @samp{$}, terminates the line and
+indents the new line. The command @kbd{M-@key{RET}} can also be invoked
+inside a string to split it at that point, in which case the @samp{+}
+concatenation operator is used.
+
+@cindex Filling
+@cindex @code{auto-fill-mode}
+@cindex Hanging paragraphs
+When filling comment paragraphs, IDLWAVE overloads the normal filling
+functions and uses a function which creates the hanging paragraphs
+customary in IDL routine headers. When @code{auto-fill-mode} is turned
+on (toggle with @kbd{C-c C-a}), comments will be auto-filled. If the
+first line of a paragraph contains a match for
+@code{idlwave-hang-indent-regexp} (a dash-space by default), subsequent
+lines are positioned to line up after it, as in the following example.
+
+@example
+@group
+;=================================
+; x - an array containing
+; lots of interesting numbers.
+;
+; y - another variable where
+; a hanging paragraph is used
+; to describe it.
+;=================================
+@end group
+@end example
+
+@kindex M-q
+You can also refill a comment at any time paragraph with @kbd{M-q}.
+Comment delimiting lines as in the above example, consisting of one or
+more @samp{;} followed by one or more of the characters @samp{+=-_*},
+are kept in place, as is.
+
+@defopt idlwave-fill-comment-line-only (@code{t})
+Non-@code{nil} means auto fill will only operate on comment lines.
+@end defopt
+
+@defopt idlwave-auto-fill-split-string (@code{t})
+Non-@code{nil} means auto fill will split strings with the IDL @samp{+}
+operator.
+@end defopt
+
+@defopt idlwave-split-line-string (@code{t})
+Non-@code{nil} means @code{idlwave-split-line} will split strings with
+@samp{+}.
+@end defopt
+
+@defopt idlwave-hanging-indent (@code{t})
+Non-@code{nil} means comment paragraphs are indented under the hanging
+indent given by @code{idlwave-hang-indent-regexp} match in the first
+line of the paragraph.
+@end defopt
+
+@defopt idlwave-hang-indent-regexp (@code{"- "})
+Regular expression matching the position of the hanging indent
+in the first line of a comment paragraph.
+@end defopt
+
+@defopt idlwave-use-last-hang-indent (@code{nil})
+Non-@code{nil} means use last match on line for
+@code{idlwave-indent-regexp}.
+@end defopt
+
+@node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting
+@subsection Syntax Highlighting
+@cindex Syntax highlighting
+@cindex Highlighting of syntax
+@cindex Font lock
+
+Highlighting of keywords, comments, strings etc. can be accomplished
+with @code{font-lock}. If you are using @code{global-font-lock-mode}
+(in Emacs), or have @code{font-lock} turned on in any other buffer in
+XEmacs, it should also automatically work in IDLWAVE buffers. If you'd
+prefer invoking font-lock individually by mode, you can enforce it in
+@code{idlwave-mode} with the following line in your @file{.emacs}:
+
+@lisp
+(add-hook 'idlwave-mode-hook 'turn-on-font-lock)
+@end lisp
+
+@noindent IDLWAVE supports 3 increasing levels of syntax highlighting.
+The variable @code{font-lock-maximum-decoration} determines which level
+is selected. Individual categories of special tokens can be selected
+for highlighting using the variable
+@code{idlwave-default-font-lock-items}.
+
+@defopt idlwave-default-font-lock-items
+Items which should be fontified on the default fontification level
+2.
+@end defopt
+
+@node Octals and Highlighting, , Syntax Highlighting, Code Formatting
+@subsection Octals and Highlighting
+@cindex Syntax highlighting, Octals
+@cindex Highlighting of syntax, Octals
+
+A rare syntax highlighting problem results from an extremely unfortunate
+notation for octal numbers in IDL: @code{"123}. This unpaired quotation
+mark is very difficult to parse, given that it can be mixed on a single
+line with any number of strings. Emacs will incorrectly identify this
+as a string, and the highlighting of following lines of code can be
+distorted, since the string is never terminated.
+
+One solution to this involves terminating the mistakenly identified
+string yourself by providing a closing quotation mark in a comment:
+
+@example
+ string("305B) + $ ;" <--- for font-lock
+ ' is an Angstrom.'
+@end example
+
+@noindent A far better solution is to abandon this notation for octals
+altogether, and use the more sensible alternative IDL provides:
+
+@example
+ string('305'OB) + ' is an Angstrom.'
+@end example
+
+@noindent This simultaneously solves the font-lock problem and is more
+consistent with the notation for hexadecimal numbers, e.g. @code{'C5'XB}.
+
+@node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode
+@section Routine Info
+@cindex Routine info
+@cindex Updating routine info
+@cindex Scanning buffers for routine info
+@cindex Buffers, scanning for routine info
+@cindex Shell, querying for routine info
+
+@kindex C-c C-i
+IDL comes bundled with more than one thousand procedures, functions
+and object methods, and large libraries typically contain hundreds or
+even thousands more (each with a few to tens of keywords and
+arguments). This large command set can make it difficult to remember
+the calling sequence and keywords for the routines you use, but
+IDLWAVE can help. It builds up routine information from a wide
+variety of sources; IDLWAVE in fact knows far more about the
+@samp{.pro} routines on your system than IDL itself! It maintains a
+list of all built-in routines, with calling sequences and
+keywords@footnote{This list is created by scanning the IDL manuals and
+might contain (very few) errors. Please report any errors to the
+maintainer, so that they can be fixed.}. It also scans Emacs buffers
+for routine definitions, queries the IDLWAVE-Shell for information
+about routines currently compiled there, and automatically locates
+library and user-created catalogs. This information is updated
+automatically, and so should usually be current. To force a global
+update and refresh the routine information, use @kbd{C-c C-i}
+(@code{idlwave-update-routine-info}).
+
+@kindex C-c ?
+To display the information about a routine, press @kbd{C-c ?}, which
+calls the command @code{idlwave-routine-info}. When the current cursor
+position is on the name or in the argument list of a procedure or
+function, information will be displayed about the routine. For example,
+consider the indicated cursor positions in the following line:
+
+@example
+plot,x,alog(x+5*sin(x) + 2),
+ | | | | | | | |
+ 1 2 3 4 5 6 7 8
+@end example
+
+@cindex Default routine, for info and help
+On positions 1,2 and 8, information about the @samp{plot} procedure will
+be shown. On positions 3,4, and 7, the @samp{alog} function will be
+described, while positions 5 and 6 will investigate the @samp{sin}
+function.
+
+When you ask for routine information about an object method, and the
+method exists in several classes, IDLWAVE queries for the class of the
+object, unless the class is already known through a text property on the
+@samp{->} operator (@pxref{Object Method Completion and Class
+Ambiguity}), or by having been explicitly included in the call
+(e.g. @code{a->myclass::Foo}).
+
+@cindex Calling sequences
+@cindex Keywords of a routine
+@cindex Routine source information
+The description displayed contains the calling sequence, the list of
+keywords and the source location of this routine. It looks like this:
+
+@example
+Usage: XMANAGER, NAME, ID
+Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER
+ JUST_REG MODAL NO_BLOCK
+Source: SystemLib [LCSB] /soft1/idl53/lib/xmanager.pro
+@end example
+
+@cindex Categories, of routines
+@cindex Load-path shadows
+@cindex Shadows, load-path
+@cindex IDL variable @code{!PATH}
+@cindex @code{!PATH}, IDL variable
+@cindex IDL variable @code{!DIR}
+@cindex @code{!DIR}, IDL variable
+
+If a definition of this routine exists in several files accessible to
+IDLWAVE, several @samp{Source} lines will point to the different
+files. This may indicate that your routine is shadowing a system
+library routine, which may or may not be what you want
+(@pxref{Load-Path Shadows}). The information about the calling
+sequence and keywords is derived from the first source listed.
+Library routines are available only if you have scanned your local IDL
+directories or are using pre-scanned libraries (@pxref{Catalogs}).
+The source entry consists of a @emph{source category}, a set of
+@emph{flags} and the path to the @emph{source file}. The following
+default categories exist:
+
+@multitable @columnfractions .15 .85
+@item @i{System}
+@tab A system routine of unknown origin. When the system library has
+been scanned as part of a catalog (@pxref{Catalogs}), this category
+will automatically split into the next two.
+@item @i{Builtin}
+@tab A builtin system routine with no source code available.
+@item @i{SystemLib}
+@tab A library system routine in the official lib directory @file{!DIR/lib}.
+@item @i{Obsolete}
+@tab A library routine in the official lib directory @file{!DIR/lib/obsolete}.
+@item @i{Library}
+@tab A routine in a file on IDL's search path @code{!PATH}.
+@item @i{Other}
+@tab Any other routine with a file not known to be on the search path.
+@item @i{Unresolved}
+@tab An otherwise unknown routine the shell lists as unresolved
+(referenced, but not compiled).
+@end multitable
+
+Any routines discovered in library catalogs (@pxref{Library
+Catalogs}), will display the category assigned during creation,
+e.g. @samp{NasaLib}. For routines not discovered in this way, you can
+create additional categories based on the routine's filename using the
+variable @code{idlwave-special-lib-alist}.
+
+@cindex Flags, in routine info
+@cindex Duplicate routines
+@cindex Multiply defined routines
+@cindex Routine definitions, multiple
+The flags @code{[LCSB]} indicate the source of the information IDLWAVE
+has regarding the file: from a library catalog (@w{@code{[L---]}}),
+from a user catalog (@w{@code{[-C--]}}, from the IDL Shell
+(@w{@code{[--S-]}}) or from an Emacs buffer (@w{@code{[---B]}}).
+Combinations are possible (a compiled library routine visited in a
+buffer might read @w{@code{[L-SB]}}). If a file contains multiple
+definitions of the same routine, the file name will be prefixed with
+@samp{(Nx)} where @samp{N} is the number of definitions.
+
+@cindex Online Help from the routine info buffer
+@cindex Active text, in routine info
+@cindex Inserting keywords, from routine info
+@cindex Source file, access from routine info
+Some of the text in the @file{*Help*} routine info buffer will be active
+(it is highlighted when the mouse moves over it). Typically, clicking
+with the right mouse button invokes online help lookup, and clicking
+with the middle mouse button inserts keywords or visits files:
+
+@multitable @columnfractions 0.15 0.85
+@item @i{Usage}
+@tab If online help is installed, a click with the @emph{right} mouse
+button on the @i{Usage:} line will access the help for the
+routine (@pxref{Online Help}).
+@item @i{Keyword}
+@tab Online help about keywords is also available with the
+@emph{right} mouse button. Clicking on a keyword with the @emph{middle}
+mouse button will insert this keyword in the buffer from where
+@code{idlwave-routine-info} was called. Holding down @key{SHIFT} while
+clicking also adds the initial @samp{/}.
+@item @i{Source}
+@tab Clicking with the @emph{middle} mouse button on a @samp{Source} line
+finds the source file of the routine and visits it in another window.
+Another click on the same line switches back to the buffer from which
+@kbd{C-c ?} was called. If you use the @emph{right} mouse button, the
+source will not be visited by a buffer, but displayed in the online help
+window.
+@item @i{Classes}
+@tab The @i{Classes} line is only included in the routine info window if
+the current class inherits from other classes. You can click with the
+@emph{middle} mouse button to display routine info about the current
+method in other classes on the inheritance chain, if such a method
+exists there.
+@end multitable
+
+@defopt idlwave-resize-routine-help-window (@code{t})
+Non-@code{nil} means resize the Routine-info @file{*Help*} window to
+fit the content.
+@end defopt
+
+@defopt idlwave-special-lib-alist
+Alist of regular expressions matching special library directories.
+@end defopt
+
+@defopt idlwave-rinfo-max-source-lines (@code{5})
+Maximum number of source files displayed in the Routine Info window.
+@end defopt
+
+
+@html
+<A NAME="ONLINE_HELP"></A>
+@end html
+@node Online Help, Completion, Routine Info, The IDLWAVE Major Mode
+@section Online Help
+
+@cindex Online Help
+@cindex @file{idlw-help.txt}
+@cindex @file{idlw-help.el}
+@cindex Installing online help
+@cindex Online Help, Installation
+@cindex Speed, of online help
+@cindex XML Help Catalog
+
+For IDL system routines, extensive documentation is supplied with IDL.
+IDLWAVE can access the HTML version of this documentation very quickly
+and accurately, based on the local context. This can be @emph{much}
+faster than using the IDL online help application, because IDLWAVE
+usually gets you to the right place in the documentation directly ---
+e.g. a specific keyword of a routine --- without any additional browsing
+and scrolling.
+
+For this online help to work, an HTML version of the IDL documentation
+is required. Beginning with IDL 6.2, HTML documentation is distributed
+directly with IDL, along with an XML-based catalog of routine
+information. By default, IDLWAVE automatically attempts to convert this
+XML catalog into a format Emacs can more easily understand, and caches
+this information in your @code{idlwave_config_directory}
+(@file{~/.idlwave/}, by default). It also re-scans the XML catalog if
+it is newer than the current cached version. You can force rescan with
+the menu entry @code{IDLWAVE->Routine Info->Rescan XML Help Catalog}.
+
+Before IDL 6.2, the HTML help was not distributed with IDL, and was not
+part of the standalone IDLWAVE distribution, but had to be downloaded
+separately. This is no longer necessary: all help and routine
+information is supplied with IDL versions 6.2 and later.
+
+There are a variety of options for displaying the HTML help: see below.
+Help for routines without HTML documentation is also available, by using
+the routine documentation header and/or routine source.
+
+@kindex M-?
+In any IDL program (or, as with most IDLWAVE commands, in the IDL
+Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with
+@kbd{S-Mouse-3} to access context sensitive online help. The following
+locations are recognized context for help:
+
+@cindex Context, for online help
+@multitable @columnfractions .25 .75
+@item @i{Routine names}
+@tab The name of a routine (function, procedure, method).
+@item @i{Keyword Parameters}
+@tab A keyword parameter of a routine.
+@item @i{System Variables}
+@tab System variables like @code{!DPI}.
+@item @i{System Variable Tags}
+@tab System variables tags like @code{!D.X_SIZE}.
+@item @i{IDL Statements}
+@tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc.
+@item @i{IDL Controls}
+@tab Control structures like @code{FOR}, @code{SWITCH}, etc.
+@item @i{Class names}
+@tab A class name in an @code{OBJ_NEW} call.
+@item @i{Class Init Keywords}
+@tab Beyond the class name in an @code{OBJ_NEW} call.
+@item @i{Executive Command}
+@tab An executive command like @code{.RUN}. Mostly useful in the shell.
+@item @i{Structure Tags}
+@tab Structure tags like @code{state.xsize}
+@item @i{Class Tags}
+@tab Class tags like @code{self.value}.
+@item @i{Default}
+@tab The routine that would be selected for routine info display.
+@end multitable
+
+@cindex @code{OBJ_NEW}, special online help
+Note that the @code{OBJ_NEW} function is special in that the help
+displayed depends on the cursor position. If the cursor is on the
+@samp{OBJ_NEW}, this function is described. If it is on the class
+name inside the quotes, the documentation for the class is pulled up.
+If the cursor is @emph{after} the class name, anywhere in the argument
+list, the documentation for the corresponding @code{Init} method and
+its keywords is targeted.
+
+Apart from an IDLWAVE buffer or shell, there are two more places from
+which online help can be accessed.
+
+@itemize @bullet
+@item
+Online help for routines and keywords can be accessed through the
+Routine Info display. Click with @kbd{Mouse-3} on an item to see the
+corresponding help (@pxref{Routine Info}).
+@item
+When using completion and Emacs pops up a @file{*Completions*} buffer
+with possible completions, clicking with @kbd{Mouse-3} on a completion
+item invokes help on that item (@pxref{Completion}). Items for which
+help is available in the online system documentation (vs. just the
+program source itself) will be emphasized (e.g. colored blue).
+@end itemize
+@noindent
+In both cases, a blue face indicates that the item is documented in
+the IDL manual, but an attempt will be made to visit non-blue items
+directly in the originating source file.
+
+
+@menu
+* Help with HTML Documentation::
+* Help with Source::
+@end menu
+
+@node Help with HTML Documentation, Help with Source, Online Help, Online Help
+@subsection Help with HTML Documentation
+@cindex HTML Help
+@cindex Help using HTML manuals
+@cindex IDL manual, HTML version
+@cindex IDL Assistant
+
+Help using the HTML documentation is invoked with the built-in Emacs
+command @code{browse-url}, which displays the relevant help topic in a
+browser of your choosing. Beginning with version 6.2, IDL comes with
+the help browser @emph{IDL Assistant}, which it uses by default for
+displaying online help on all supported platforms. This browser
+offers topical searches, an index, and is also now the default and
+recommended IDLWAVE help browser. The variable
+@code{idlwave-help-use-assistant} controls whether this browser is
+used. Note that, due to limitations in the Assistant, invoking help
+within IDLWAVE and @code{? topic} within IDL will result in two
+running copies of Assistant.
+
+Aside from the IDL Assistant, there are many possible browsers to choose
+among, with differing advantages and disadvantages. The variable
+@code{idlwave-help-browser-function} controls which browser help is sent
+to (as long as @code{idlwave-help-use-assistant} is not set). This
+function is used to set the variable @code{browse-url-browser-function}
+locally for IDLWAVE help only. Customize the latter variable to see
+what choices of browsers your system offers. Certain browsers like
+@code{w3} (bundled with many versions of Emacs) and @code{w3m}
+(@uref{http://emacs-w3m.namazu.org/}) are run within Emacs, and use
+Emacs buffers to display the HTML help. This can be convenient,
+especially on small displays, and images can even be displayed in-line
+on newer Emacs versions. However, better formatting results are often
+achieved with external browsers, like Mozilla. IDLWAVE assumes any
+browser function containing "w3" is displayed in a local buffer. If you
+are using another Emacs-local browser for which this is not true, set
+the variable @code{idlwave-help-browser-is-local}.
+
+With IDL 6.2 or later, it is important to ensure that the variable
+@code{idlwave-system-directory} is set (@pxref{Catalogs}). One easy way
+to ensure this is to run the IDL Shell (@kbd{C-c C-s}). It will be
+queried for this directory, and the results will be cached to file for
+subsequent use.
+
+@xref{HTML Help Browser Tips}, for more information on selecting and
+configuring a browser for use with IDL's HTML help system.
+
+@defopt idlwave-html-system-help-location @file{help/online_help}
+Relative directory of the system-supplied HTML help directory,
+considered with respect to @code{idlwave-system-directory}. Relevant
+for IDL 6.2 and greater. Should not change.
+@end defopt
+
+@defopt idlwave-html-help-location @file{/usr/local/etc/}
+The directory where the @file{idl_html_help} HTML directory live.
+Obsolete and ignored for IDL 6.2 and greater
+(@code{idlwave-html-system-help-location} is used instead).
+@end defopt
+
+@defopt idlwave-help-use-assistant @code{t}
+If set, use the IDL Assistant if possible for online HTML help,
+otherwise use the browser function specified in
+@code{idlwave-help-browser-function}.
+@end defopt
+
+@defopt idlwave-help-browser-function
+The browser function to use to display IDLWAVE HTML help. Should be
+one of the functions available for setting
+@code{browse-url-browser-function}, which see.
+@end defopt
+
+@defopt idlwave-help-browser-is-local
+Is the browser selected in @code{idlwave-help-browser-function} run in a
+local Emacs buffer or window? Defaults to @code{t} if the function
+contains "-w3".
+@end defopt
+
+@defopt idlwave-help-link-face
+The face for links to IDLWAVE online help.
+@end defopt
+
+@node Help with Source, , Help with HTML Documentation, Online Help
+@subsection Help with Source
+@cindex Help using routine source
+
+@cindex Source code, as online help
+@cindex DocLib header, as online help
+For routines which are not documented in an HTML manual (for example
+personal or library routines), the source code itself is used as help
+text. If the requested information can be found in a (more or less)
+standard DocLib file header, IDLWAVE shows the header (scrolling down to
+a keyword, if appropriate). Otherwise the routine definition statement
+(@code{pro}/@code{function}) is shown. The doclib header sections which
+are searched for include @samp{NAME} and @samp{KEYWORDS}. Localization
+support can be added by customizing the @code{idlwave-help-doclib-name}
+and @code{idlwave-help-doclib-keyword} variables.
+
+@cindex Structure tags, in online help
+@cindex Class tags, in online help
+Help is also available for class structure tags (@code{self.TAG}), and
+generic structure tags, if structure tag completion is enabled
+(@pxref{Structure Tag Completion}). This is implemented by visiting the
+tag within the class or structure definition source itself. Help is not
+available on built-in system class tags.
+
+The help window is normally displayed in the same frame, but can be
+popped-up in a separate frame. The following commands can be used to
+navigate inside the help system for source files:
+
+@multitable @columnfractions .15 .85
+@item @kbd{@key{SPACE}}
+@tab Scroll forward one page.
+@item @kbd{@key{RET}}
+@tab Scroll forward one line.
+@item @kbd{@key{DEL}}
+@tab Scroll back one page.
+@item @kbd{h}
+@tab Jump to DocLib Header of the routine whose source is displayed
+as help.
+@item @kbd{H}
+@tab Jump to the first DocLib Header in the file.
+@item @kbd{.} @r{(Dot)}
+@tab Jump back and forth between the routine definition (the
+@code{pro}/@code{function} statement) and the description of the help
+item in the DocLib header.
+@item @kbd{F}
+@tab Fontify the buffer like source code. See the variable @code{idlwave-help-fontify-source-code}.
+@item @kbd{q}
+@tab Kill the help window.
+@end multitable
+
+
+@defopt idlwave-help-use-dedicated-frame (@code{nil})
+Non-@code{nil} means use a separate frame for Online Help if possible.
+@end defopt
+
+@defopt idlwave-help-frame-parameters
+The frame parameters for the special Online Help frame.
+@end defopt
+
+@defopt idlwave-max-popup-menu-items (@code{20})
+Maximum number of items per pane in pop-up menus.
+@end defopt
+
+@defopt idlwave-extra-help-function
+Function to call for help if the normal help fails.
+@end defopt
+
+@defopt idlwave-help-fontify-source-code (@code{nil})
+Non-@code{nil} means fontify source code displayed as help.
+@end defopt
+
+@defopt idlwave-help-source-try-header (@code{t})
+Non-@code{nil} means try to find help in routine header when
+displaying source file.
+@end defopt
+
+@defopt idlwave-help-doclib-name (@code{"name"})
+The case-insensitive heading word in doclib headers to locate the
+@emph{name} section. Can be a regexp, e.g. @code{"\\(name\\|nom\\)"}.
+@end defopt
+
+@defopt idlwave-help-doclib-keyword (@code{"KEYWORD"})
+The case-insensitive heading word in doclib headers to locate the
+@emph{keywords} section. Can be a regexp.
+@end defopt
+
+
+@node Completion, Routine Source, Online Help, The IDLWAVE Major Mode
+@section Completion
+@cindex Completion
+@cindex Keyword completion
+@cindex Method completion
+@cindex Object method completion
+@cindex Class name completion
+@cindex Function name completion
+@cindex Procedure name completion
+
+@kindex M-@key{TAB}
+@kindex C-c C-i
+IDLWAVE offers completion for class names, routine names, keywords,
+system variables, system variable tags, class structure tags, regular
+structure tags and file names. As in many programming modes, completion
+is bound to @kbd{M-@key{TAB}} (or simply @kbd{@key{TAB}} in the IDLWAVE
+Shell --- @pxref{Using the Shell}). Completion uses exactly the same
+internal information as routine info, so when necessary (rarely) it can
+be updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}).
+
+The completion function is context sensitive and figures out what to
+complete based on the location of the point. Here are example lines and
+what @kbd{M-@key{TAB}} would try to complete when the cursor is on the
+position marked with a @samp{_}:
+
+@example
+plo_ @r{Procedure}
+x = a_ @r{Function}
+plot,xra_ @r{Keyword of @code{plot} procedure}
+plot,x,y,/x_ @r{Keyword of @code{plot} procedure}
+plot,min(_ @r{Keyword of @code{min} function}
+obj -> a_ @r{Object method (procedure)}
+a[2,3] = obj -> a_ @r{Object method (function)}
+x = obj_new('IDL_ @r{Class name}
+x = obj_new('MyCl',a_ @r{Keyword to @code{Init} method in class @code{MyCl}}
+pro A_ @r{Class name}
+pro _ @r{Fill in @code{Class::} of first method in this file}
+!v_ @r{System variable}
+!version.t_ @r{Structure tag of system variable}
+self.g_ @r{Class structure tag in methods}
+state.w_ @r{Structure tag, if tag completion enabled}
+name = 'a_ @r{File name (default inside quotes)}
+@end example
+
+@cindex Completion, ambiguity
+@cindex Completion, forcing function name
+The only place where completion is ambiguous is procedure/function
+@emph{keywords} versus @emph{functions}. After @samp{plot,x,_}, IDLWAVE
+will always assume a keyword to @samp{plot}. However, a function is
+also a possible completion here. You can force completion of a function
+name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}.
+
+Giving two prefix arguments (@kbd{C-u C-u M-@key{TAB}}) prompts for a
+regular expression to search among the commands to be completed. As
+an example, completing a blank line in this way will allow you to
+search for a procedure matching a regexp.
+
+@cindex Scrolling the @file{*Completions*} window
+@cindex Completion, scrolling
+@cindex Completion, Online Help
+@cindex Online Help in @file{*Completions*} buffer
+If the list of completions is too long to fit in the
+@file{*Completions*} window, the window can be scrolled by pressing
+@kbd{M-@key{TAB}} repeatedly. Online help (if installed) for each
+possible completion is available by clicking with @kbd{Mouse-3} on the
+item. Items for which system online help (from the IDL manual) is
+available will be emphasized (e.g. colored blue). For other items, the
+corresponding source code or DocLib header will be used as the help
+text.
+
+@cindex Completion, cancelling
+@cindex Cancelling completion
+Completion is not a blocking operation --- you are free to continue
+editing, enter commands, or simply ignore the @file{*Completions*}
+buffer during a completion operation. If, however, the most recent
+command was a completion, @kbd{C-g} will remove the buffer and restore
+the window configuration. You can also remove the buffer at any time
+with no negative consequences.
+
+@defopt idlwave-keyword-completion-adds-equal (@code{t})
+Non-@code{nil} means completion automatically adds @samp{=} after
+completed keywords.
+@end defopt
+
+@defopt idlwave-function-completion-adds-paren (@code{t})
+Non-@code{nil} means completion automatically adds @samp{(} after
+completed function. A value of `2' means also add the closing
+parenthesis and position the cursor between the two.
+@end defopt
+
+@defopt idlwave-completion-restore-window-configuration (@code{t})
+Non-@code{nil} means restore window configuration after successful
+completion.
+@end defopt
+
+@defopt idlwave-highlight-help-links-in-completion (@code{t})
+Non-@code{nil} means highlight completions for which system help is
+available.
+@end defopt
+
+@menu
+* Case of Completed Words:: CaseOFcomPletedWords
+* Object Method Completion and Class Ambiguity:: obj->Method, what?
+* Object Method Completion in the Shell::
+* Class and Keyword Inheritance:: obj->Method, _EXTRA=e
+* Structure Tag Completion:: Completing state.Tag
+@end menu
+
+@node Case of Completed Words, Object Method Completion and Class Ambiguity, Completion, Completion
+@subsection Case of Completed Words
+@cindex Case of completed words
+@cindex Mixed case completion
+IDL is a case-insensitive language, so casing is a matter of style
+only. IDLWAVE helps maintain a consistent casing style for completed
+items. The case of the completed words is determined by what is
+already in the buffer. As an exception, when the partial word being
+completed is all lower case, the completion will be lower case as
+well. If at least one character is upper case, the string will be
+completed in upper case or mixed case, depending on the value of the
+variable @code{idlwave-completion-case}. The default is to use upper
+case for procedures, functions and keywords, and mixed case for object
+class names and methods, similar to the conventions in the IDL
+manuals. For instance, to enable mixed-case completion for routines
+in addition to classes and methods, you need an entry such as
+@code{(routine . preserve)} in that variable. To enable total control
+over the case of completed items, independent of buffer context, set
+@code{idlwave-completion-force-default-case} to non-@code{nil}.
+
+@defopt idlwave-completion-case
+Association list setting the case (UPPER/lower/Capitalized/MixedCase...)
+of completed words.
+@end defopt
+
+@defopt idlwave-completion-force-default-case (@code{nil})
+Non-@code{nil} means completion will always honor the settings in
+@code{idlwave-completion-case}. When nil (the default), entirely lower
+case strings will always be completed to lower case, no matter what the
+settings in @code{idlwave-completion-case}.
+@end defopt
+
+@defopt idlwave-complete-empty-string-as-lower-case (@code{nil})
+Non-@code{nil} means the empty string is considered lower case for
+completion.
+@end defopt
+
+@node Object Method Completion and Class Ambiguity, Object Method Completion in the Shell, Case of Completed Words, Completion
+@subsection Object Method Completion and Class Ambiguity
+@cindex Object methods
+@cindex Class ambiguity
+@cindex @code{self} object, default class
+An object method is not uniquely determined without the object's class.
+Since the class is almost always omitted in the calling source (as
+required to obtain the true benefits of object-based programming),
+IDLWAVE considers all available methods in all classes as possible
+method name completions. The combined list of keywords of the current
+method in @emph{all} known classes which contain that method will be
+considered for keyword completion. In the @file{*Completions*} buffer,
+the matching classes will be shown next to each item (see option
+@code{idlwave-completion-show-classes}). As a special case, the class
+of an object called @samp{self} is always taken to be the class of the
+current routine, when in an IDLWAVE buffer. All inherits classes are
+considered as well.
+
+@cindex Forcing class query.
+@cindex Class query, forcing
+You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u
+M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to
+narrow down the number of possible completions. The variable
+@code{idlwave-query-class} can be configured to make such prompting the
+default for all methods (not recommended), or selectively for very
+common methods for which the number of completing keywords would be too
+large (e.g. @code{Init,SetProperty,GetProperty}).
+
+@cindex Saving object class on @code{->}
+@cindex @code{->}
+After you have specified the class for a particular statement (e.g. when
+completing the method), IDLWAVE can remember it for the rest of the
+editing session. Subsequent completions in the same statement
+(e.g. keywords) can then reuse this class information. This works by
+placing a text property on the method invocation operator @samp{->},
+after which the operator will be shown in a different face (bold by
+default). The variable @code{idlwave-store-inquired-class} can be used
+to turn it off or on.
+
+@defopt idlwave-completion-show-classes (@code{1})
+Non-@code{nil} means show up to that many classes in
+@file{*Completions*} buffer when completing object methods and
+keywords.
+@end defopt
+
+@defopt idlwave-completion-fontify-classes (@code{t})
+Non-@code{nil} means fontify the classes in completions buffer.
+@end defopt
+
+@defopt idlwave-query-class (@code{nil})
+Association list governing query for object classes during completion.
+@end defopt
+
+@defopt idlwave-store-inquired-class (@code{t})
+Non-@code{nil} means store class of a method call as text property on
+@samp{->}.
+@end defopt
+
+@defopt idlwave-class-arrow-face
+Face to highlight object operator arrows @samp{->} which carry a saved
+class text property.
+@end defopt
+
+@node Object Method Completion in the Shell, Class and Keyword Inheritance, Object Method Completion and Class Ambiguity, Completion
+@subsection Object Method Completion in the Shell
+@cindex Method Completion in Shell
+In the IDLWAVE Shell (@pxref{The IDLWAVE Shell}), objects on which
+methods are being invoked have a special property: they must exist as
+variables, and so their class can be determined (for instance, using the
+@code{obj_class()} function). In the Shell, when attempting completion,
+routine info, or online help within a method routine, a query is sent to
+determine the class of the object. If this query is successful, the
+class found will be used to select appropriate completions, routine
+info, or help. If unsuccessful, information from all known classes will
+be used (as in the buffer).
+
+@node Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion in the Shell, Completion
+@subsection Class and Keyword Inheritance
+@cindex Inheritance, class
+@cindex Keyword inheritance
+@cindex Inheritance, keyword
+
+Class inheritance affects which methods are called in IDL. An object of
+a class which inherits methods from one or more superclasses can
+override that method by defining its own method of the same name, extend
+the method by calling the method(s) of its superclass(es) in its
+version, or inherit the method directly by making no modifications.
+IDLWAVE examines class definitions during completion and routine
+information display, and records all inheritance information it finds.
+This information is displayed if appropriate with the calling sequence
+for methods (@pxref{Routine Info}), as long as variable
+@code{idlwave-support-inheritance} is non-@code{nil}.
+
+In many class methods, @emph{keyword} inheritance (@code{_EXTRA} and
+@code{_REF_EXTRA}) is used hand-in-hand with class inheritance and
+method overriding. E.g., in a @code{SetProperty} method, this technique
+allows a single call @code{obj->SetProperty} to set properties up the
+entire class inheritance chain. This is often referred to as
+@emph{chaining}, and is characterized by chained method calls like
+@w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}.
+
+IDLWAVE can accommodate this special synergy between class and keyword
+inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a
+method's keyword parameters, all keywords of superclass versions of
+the method being considered can be included in completion. There is
+of course no guarantee that this type of keyword chaining actually
+occurs, but for some methods it's a very convenient assumption. The
+variable @code{idlwave-keyword-class-inheritance} can be used to
+configure which methods have keyword inheritance treated in this
+simple, class-driven way. By default, only @code{Init} and
+@code{(Get|Set)Property} are. The completion buffer will label
+keywords based on their originating class.
+
+@defopt idlwave-support-inheritance (@code{t})
+Non-@code{nil} means consider inheritance during completion, online help etc.
+@end defopt
+
+@defopt idlwave-keyword-class-inheritance
+A list of regular expressions to match methods for which simple
+class-driven keyword inheritance will be used for Completion.
+@end defopt
+
+@node Structure Tag Completion, , Class and Keyword Inheritance, Completion
+@subsection Structure Tag Completion
+@cindex Completion, structure tag
+@cindex Structure tag completion
+
+In many programs, especially those involving widgets, large structures
+(e.g. the @samp{state} structure) are used to communicate among
+routines. It is very convenient to be able to complete structure tags,
+in the same way as for instance variables (tags) of the @samp{self}
+object (@pxref{Object Method Completion and Class Ambiguity}). Add-in
+code for structure tag completion is available in the form of a loadable
+completion module: @file{idlw-complete-structtag.el}. Tag completion in
+structures is highly ambiguous (much more so than @samp{self}
+completion), so @code{idlw-complete-structtag} makes an unusual and very
+specific assumption: the exact same variable name is used to refer to
+the structure in all parts of the program. This is entirely unenforced
+by the IDL language, but is a typical convention. If you consistently
+refer to the same structure with the same variable name
+(e.g. @samp{state}), structure tags which are read from its definition
+in the same file can be used for completion.
+
+Structure tag completion is not enabled by default. To enable it,
+simply add the following to your @file{.emacs}:
+
+@lisp
+ (add-hook 'idlwave-load-hook
+ (lambda () (require 'idlw-complete-structtag)))
+@end lisp
+
+Once enabled, you'll also be able to access online help on the structure
+tags, using the usual methods (@pxref{Online Help}). In addition,
+structure variables in the shell will be queried for tag names, similar
+to the way object variables in the shell are queried for method names.
+So, e.g.:
+
+@example
+IDL> st.[Tab]
+@end example
+
+@noindent will complete with all structure fields of the structure
+@code{st}.
+
+@node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode
+@section Routine Source
+@cindex Routine source file
+@cindex Module source file
+@cindex Source file, of a routine
+@kindex C-c C-v
+In addition to clicking on a @i{Source:} line in the routine info
+window, there is another way to quickly visit the source file of a
+routine. The command @kbd{C-c C-v} (@code{idlwave-find-module}) asks
+for a module name, offering the same default as
+@code{idlwave-routine-info} would have used, taken from nearby buffer
+contents. In the minibuffer, specify a complete routine name (including
+any class part). IDLWAVE will display the source file in another
+window, positioned at the routine in question. You can also limit this
+to a routine in the current buffer only, with completion, and a
+context-sensitive default, by using a single prefix (@kbd{C-u C-c C-v})
+or the convenience binding @kbd{C-c C-t}.
+
+@cindex Buffers, killing
+@cindex Killing autoloaded buffers
+Since getting the source of a routine into a buffer is so easy with
+IDLWAVE, too many buffers visiting different IDL source files are
+sometimes created. The special command @kbd{C-c C-k}
+(@code{idlwave-kill-autoloaded-buffers}) can be used to easily remove
+these buffers.
+
+@node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode
+@section Resolving Routines
+@cindex @code{RESOLVE_ROUTINE}
+@cindex Compiling library modules
+@cindex Routines, resolving
+
+The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve}
+and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL
+in order to resolve (compile) it. The default routine to be resolved is
+taken from context, but you get a chance to edit it. Usually this is
+not necessary, since IDL automatically discovers routines on its path.
+
+@code{idlwave-resolve} is one way to get a library module within reach
+of IDLWAVE's routine info collecting functions. A better way is to
+keep routine information available in catalogs (@pxref{Catalogs}).
+Routine info on modules will then be available without the need to
+compile the modules first, and even without a running shell.
+
+@xref{Sources of Routine Info}, for more information on the ways IDLWAVE
+collects data about routines, and how to update this information.
+
+@node Code Templates, Abbreviations, Resolving Routines, The IDLWAVE Major Mode
+@section Code Templates
+@cindex Code templates
+@cindex Templates
+
+IDLWAVE can insert IDL code templates into the buffer. For a few
+templates, this is done with direct key bindings:
+
+@multitable @columnfractions .15 .85
+@item @kbd{C-c C-c}
+@tab @code{CASE} statement template
+@item @kbd{C-c C-f}
+@tab @code{FOR} loop template
+@item @kbd{C-c C-r}
+@tab @code{REPEAT} loop template
+@item @kbd{C-c C-w}
+@tab @code{WHILE} loop template
+@end multitable
+
+All code templates are also available as abbreviations
+(@pxref{Abbreviations}).
+
+@node Abbreviations, Actions, Code Templates, The IDLWAVE Major Mode
+@section Abbreviations
+@cindex Abbreviations
+
+Special abbreviations exist to enable rapid entry of commonly used
+commands. Emacs abbreviations are expanded by typing text into the
+buffer and pressing @key{SPC} or @key{RET}. The special abbreviations
+used to insert code templates all start with a @samp{\} (the backslash),
+or, optionally, any other character set in
+@code{idlwave-abbrev-start-char}. IDLWAVE ensures that abbreviations are
+only expanded where they should be (i.e., not in a string or comment),
+and permits the point to be moved after an abbreviation expansion ---
+very useful for positioning the mark inside of parentheses, etc.
+
+Special abbreviations are pre-defined for code templates and other
+useful items. To visit the full list of abbreviations, use @kbd{M-x
+idlwave-list-abbrevs}.
+
+Template abbreviations:
+
+@multitable @columnfractions .15 .85
+@item @code{\pr}
+@tab @code{PROCEDURE} template
+@item @code{\fu}
+@tab @code{FUNCTION} template
+@item @code{\c}
+@tab @code{CASE} statement template
+@item @code{\f}
+@tab @code{FOR} loop template
+@item @code{\r}
+@tab @code{REPEAT} loop template
+@item @code{\w}
+@tab @code{WHILE} loop template
+@item @code{\i}
+@tab @code{IF} statement template
+@item @code{\elif}
+@tab @code{IF-ELSE} statement template
+@end multitable
+
+String abbreviations:
+
+@multitable @columnfractions .15 .85
+@item @code{\ap}
+@tab @code{arg_present()}
+@item @code{\b}
+@tab @code{begin}
+@item @code{\cb}
+@tab @code{byte()}
+@item @code{\cc}
+@tab @code{complex()}
+@item @code{\cd}
+@tab @code{double()}
+@item @code{\cf}
+@tab @code{float()}
+@item @code{\cl}
+@tab @code{long()}
+@item @code{\co}
+@tab @code{common}
+@item @code{\cs}
+@tab @code{string()}
+@item @code{\cx}
+@tab @code{fix()}
+@item @code{\e}
+@tab @code{else}
+@item @code{\ec}
+@tab @code{endcase}
+@item @code{\ee}
+@tab @code{endelse}
+@item @code{\ef}
+@tab @code{endfor}
+@item @code{\ei}
+@tab @code{endif else if}
+@item @code{\el}
+@tab @code{endif else}
+@item @code{\en}
+@tab @code{endif}
+@item @code{\er}
+@tab @code{endrep}
+@item @code{\es}
+@tab @code{endswitch}
+@item @code{\ew}
+@tab @code{endwhile}
+@item @code{\g}
+@tab @code{goto,}
+@item @code{\h}
+@tab @code{help,}
+@item @code{\ik}
+@tab @code{if keyword_set() then}
+@item @code{\iap}
+@tab @code{if arg_present() then}
+@item @code{\ine}
+@tab @code{if n_elements() eq 0 then}
+@item @code{\inn}
+@tab @code{if n_elements() ne 0 then}
+@item @code{\k}
+@tab @code{keyword_set()}
+@item @code{\n}
+@tab @code{n_elements()}
+@item @code{\np}
+@tab @code{n_params()}
+@item @code{\oi}
+@tab @code{on_ioerror,}
+@item @code{\or}
+@tab @code{openr,}
+@item @code{\ou}
+@tab @code{openu,}
+@item @code{\ow}
+@tab @code{openw,}
+@item @code{\p}
+@tab @code{print,}
+@item @code{\pt}
+@tab @code{plot,}
+@item @code{\pv}
+@tab @code{ptr_valid()}
+@item @code{\re}
+@tab @code{read,}
+@item @code{\rf}
+@tab @code{readf,}
+@item @code{\rt}
+@tab @code{return}
+@item @code{\ru}
+@tab @code{readu,}
+@item @code{\s}
+@tab @code{size()}
+@item @code{\sc}
+@tab @code{strcompress()}
+@item @code{\sl}
+@tab @code{strlowcase()}
+@item @code{\sm}
+@tab @code{strmid()}
+@item @code{\sn}
+@tab @code{strlen()}
+@item @code{\sp}
+@tab @code{strpos()}
+@item @code{\sr}
+@tab @code{strtrim()}
+@item @code{\st}
+@tab @code{strput()}
+@item @code{\su}
+@tab @code{strupcase()}
+@item @code{\t}
+@tab @code{then}
+@item @code{\u}
+@tab @code{until}
+@item @code{\wc}
+@tab @code{widget_control,}
+@item @code{\wi}
+@tab @code{widget_info()}
+@item @code{\wu}
+@tab @code{writeu,}
+@end multitable
+
+@noindent You can easily add your own abbreviations or override existing
+abbrevs with @code{define-abbrev} in your mode hook, using the
+convenience function @code{idlwave-define-abbrev}:
+
+@lisp
+(add-hook 'idlwave-mode-hook
+ (lambda ()
+ (idlwave-define-abbrev "wb" "widget_base()"
+ (idlwave-keyword-abbrev 1))
+ (idlwave-define-abbrev "ine" "IF N_Elements() EQ 0 THEN"
+ (idlwave-keyword-abbrev 11))))
+@end lisp
+
+Notice how the abbreviation (here @emph{wb}) and its expansion
+(@emph{widget_base()}) are given as arguments, and the single argument to
+@code{idlwave-keyword-abbrev} (here @emph{1}) specifies how far back to
+move the point upon expansion (in this example, to put it between the
+parentheses).
+
+The abbreviations are expanded in upper or lower case, depending upon
+the variables @code{idlwave-abbrev-change-case} and, for reserved word
+templates, @code{idlwave-reserved-word-upcase} (@pxref{Case Changes}).
+
+@defopt idlwave-abbrev-start-char (@code{"\"})
+A single character string used to start abbreviations in abbrev mode.
+Beware of common characters which might naturally occur in sequence with
+abbreviation strings.
+@end defopt
+
+@defopt idlwave-abbrev-move (@code{t})
+Non-@code{nil} means the abbrev hook can move point, e.g. to end up
+between the parentheses of a function call.
+@end defopt
+
+@node Actions, Doc Header, Abbreviations, The IDLWAVE Major Mode
+@section Actions
+@cindex Actions
+@cindex Coding standards, enforcing
+
+@emph{Actions} are special formatting commands which are executed
+automatically while you write code in order to check the structure of
+the program or to enforce coding standards. Most actions which have
+been implemented in IDLWAVE are turned off by default, assuming that the
+average user wants her code the way she writes it. But if you are a
+lazy typist and want your code to adhere to certain standards, actions
+can be helpful.
+
+Actions can be applied in three ways:
+
+@itemize @bullet
+@item
+Some actions are applied directly while typing. For example, pressing
+@samp{=} can run a check to make sure that this operator is surrounded
+by spaces and insert these spaces if necessary. Pressing @key{SPC}
+after a reserved word can call a command to change the word to upper
+case.
+@item
+When a line is re-indented with @key{TAB}, actions can be applied to the
+entire line. To enable this, the variable @code{idlwave-do-actions}
+must be non-@code{nil}.
+@item
+@cindex Foreign code, adapting
+@cindex Actions, applied to foreign code
+Actions can also be applied to a larger piece of code, e.g. to convert
+foreign code to your own style. To do this, mark the relevant part of
+the code and execute @kbd{M-x expand-region-abbrevs}. Useful marking
+commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current
+subprogram). @xref{Code Indentation}, for information how to adjust the
+indentation of the code.
+@end itemize
+
+@defopt idlwave-do-actions (@code{nil})
+Non-@code{nil} means performs actions when indenting. Individual action
+settings are described below and set separately.
+@end defopt
+
+@menu
+* Block Boundary Check:: Is the END statement correct?
+* Padding Operators:: Enforcing space around `=' etc
+* Case Changes:: Enforcing upper case keywords
+@end menu
+
+@node Block Boundary Check, Padding Operators, Actions, Actions
+@subsection Block Boundary Check
+@cindex Block boundary check
+@cindex @code{END} type checking
+@cindex @code{END}, automatic insertion
+@cindex @code{END}, expanding
+@cindex Block, closing
+@cindex Closing a block
+
+Whenever you type an @code{END} statement, IDLWAVE finds the
+corresponding start of the block and the cursor blinks back to that
+location for a second. If you have typed a specific @code{END}, like
+@code{ENDIF} or @code{ENDCASE}, you get a warning if that terminator
+does not match the type of block it terminates.
+
+Set the variable @code{idlwave-expand-generic-end} in order to have all
+generic @code{END} statements automatically expanded to the appropriate
+type. You can also type @kbd{C-c ]} to close the current block by
+inserting the appropriate @code{END} statement.
+
+@defopt idlwave-show-block (@code{t})
+Non-@code{nil} means point blinks to block beginning for
+@code{idlwave-show-begin}.
+@end defopt
+
+@defopt idlwave-expand-generic-end (@code{t})
+Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc.
+@end defopt
+
+@defopt idlwave-reindent-end (@code{t})
+Non-@code{nil} means re-indent line after END was typed.
+@end defopt
+
+@node Padding Operators, Case Changes, Block Boundary Check, Actions
+@subsection Padding Operators
+@cindex Padding operators with spaces
+@cindex Operators, padding with spaces
+@cindex Space, around operators
+
+Some operators can be automatically surrounded by spaces. This can
+happen when the operator is typed, or later when the line is indented.
+IDLWAVE can pad the operators @samp{<}, @samp{>}, @samp{,}, @samp{=},
+and @samp{->}, as well as the modified assignment operators
+(@samp{AND=}, @samp{OR=}, etc.). This feature is turned off by default.
+If you want to turn it on, customize the variables
+@code{idlwave-surround-by-blank} and @code{idlwave-do-actions} and turn
+both on. You can also define similar actions for other operators by
+using the function @code{idlwave-action-and-binding} in the mode hook.
+For example, to enforce space padding of the @samp{+} and @samp{*}
+operators (outside of strings and comments, of course), try this in
+@file{.emacs}
+
+@lisp
+(add-hook 'idlwave-mode-hook
+ (lambda ()
+ (setq idlwave-surround-by-blank t) ; Turn this type of actions on
+ (idlwave-action-and-binding "*" '(idlwave-surround 1 1))
+ (idlwave-action-and-binding "+" '(idlwave-surround 1 1))))
+@end lisp
+
+Note that the modified assignment operators which begin with a word
+(@samp{AND=}, @samp{OR=}, @samp{NOT=}, etc.) require a leading space to
+be recognized (e.g @code{vAND=4} would be interpreted as a variable
+@code{vAND}). Also note that, since e.g., @code{>} and @code{>=} are
+both valid operators, it is impossible to surround both by blanks while
+they are being typed. Similarly with @code{&} and @code{&&}. For
+these, a compromise is made: the padding is placed on the left, and if
+the longer operator is keyed in, on the right as well (otherwise you
+must insert spaces to pad right yourself, or press simply press Tab to
+repad everything if @code{idlwave-do-actions} is on).
+
+@defopt idlwave-surround-by-blank (@code{nil})
+Non-@code{nil} means enable @code{idlwave-surround}. If non-@code{nil},
+@samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->}, and the
+modified assignment operators (@samp{AND=}, @samp{OR=}, etc.) are
+surrounded with spaces by @code{idlwave-surround}.
+@end defopt
+
+@defopt idlwave-pad-keyword (@code{t})
+Non-@code{nil} means space-pad the @samp{=} in keyword assignments.
+@end defopt
+
+@node Case Changes, , Padding Operators, Actions
+@subsection Case Changes
+@cindex Case changes
+@cindex Upcase, enforcing for reserved words
+@cindex Downcase, enforcing for reserved words
+
+Actions can be used to change the case of reserved words or expanded
+abbreviations by customizing the variables
+@code{idlwave-abbrev-change-case} and
+@code{idlwave-reserved-word-upcase}. If you want to change the case of
+additional words automatically, put something like the following into
+your @file{.emacs} file:
+
+@lisp
+(add-hook 'idlwave-mode-hook
+ (lambda ()
+ ;; Capitalize system vars
+ (idlwave-action-and-binding idlwave-sysvar '(capitalize-word 1) t)
+ ;; Capitalize procedure name
+ (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<"
+ '(capitalize-word 1) t)
+ ;; Capitalize common block name
+ (idlwave-action-and-binding "\\<common\\>[ \t]+\\<"
+ '(capitalize-word 1) t)))
+@end lisp
+
+For more information, see the documentation string for the function
+@code{idlwave-action-and-binding}. For information on controlling the
+case of routines, keywords, classes, and methods as they are completed, see
+@ref{Completion}.
+
+@defopt idlwave-abbrev-change-case (@code{nil})
+Non-@code{nil} means all abbrevs will be forced to either upper or lower
+case. Valid values are @code{nil}, @code{t}, and @code{down}.
+@end defopt
+
+@defopt idlwave-reserved-word-upcase (@code{nil})
+Non-@code{nil} means reserved words will be made upper case via abbrev
+expansion.
+@end defopt
+
+
+@node Doc Header, Motion Commands, Actions, The IDLWAVE Major Mode
+@section Documentation Header
+@cindex Documentation header
+@cindex DocLib header
+@cindex Modification timestamp
+@cindex Header, for file documentation
+@cindex Timestamp, in doc header.
+@cindex Changelog, in doc header.
+
+@kindex C-c C-h
+@kindex C-c C-m
+The command @kbd{C-c C-h} inserts a standard routine header into the
+buffer, with the usual fields for documentation (a different header can
+be specified with @code{idlwave-file-header}). One of the keywords is
+@samp{MODIFICATION HISTORY} under which the changes to a routine can be
+recorded. The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION
+HISTORY} of the current routine or file and inserts the user name with a
+timestamp.
+
+@defopt idlwave-file-header
+The doc-header template or a path to a file containing it.
+@end defopt
+
+@defopt idlwave-header-to-beginning-of-file (@code{nil})
+Non-@code{nil} means the documentation header will always be at start
+of file.
+@end defopt
+
+@defopt idlwave-timestamp-hook
+The hook function used to update the timestamp of a function.
+@end defopt
+
+@defopt idlwave-doc-modifications-keyword
+The modifications keyword to use with the log documentation commands.
+@end defopt
+
+@defopt idlwave-doclib-start
+Regexp matching the start of a document library header.
+@end defopt
+
+@defopt idlwave-doclib-end
+Regexp matching the start of a document library header.
+@end defopt
+
+@node Motion Commands, Misc Options, Doc Header, The IDLWAVE Major Mode
+@section Motion Commands
+@cindex Motion commands
+@cindex Program structure, moving through
+@cindex Code structure, moving through
+@cindex @file{Func-menu}, XEmacs package
+@cindex @file{Imenu}, Emacs package
+@cindex Function definitions, jumping to
+@cindex Procedure definitions, jumping to
+
+IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages
+which make it easy to jump to the definitions of functions and
+procedures in the current file with a pop-up selection. To bind
+@file{Imenu} to a mouse-press, use in your @file{.emacs}:
+
+@lisp
+(define-key global-map [S-down-mouse-3] 'imenu)
+@end lisp
+
+@cindex @file{Speedbar}, Emacs package
+
+In addition, @file{Speedbar} support allows convenient navigation of a
+source tree of IDL routine files, quickly stepping to routine
+definitions. See @code{Tools->Display Speedbar}.
+
+Several commands allow you to move quickly through the structure of an
+IDL program:
+
+@multitable @columnfractions .15 .85
+@item @kbd{C-M-a}
+@tab Beginning of subprogram
+@item @kbd{C-M-e}
+@tab End of subprogram
+@item @kbd{C-c @{}
+@tab Beginning of block (stay inside the block)
+@item @kbd{C-c @}}
+@tab End of block (stay inside the block)
+@item @kbd{C-M-n}
+@tab Forward block (on same level)
+@item @kbd{C-M-p}
+@tab Backward block (on same level)
+@item @kbd{C-M-d}
+@tab Down block (enters a block)
+@item @kbd{C-M-u}
+@tab Backward up block (leaves a block)
+@item @kbd{C-c C-n}
+@tab Next Statement
+@end multitable
+
+
+@node Misc Options, , Motion Commands, The IDLWAVE Major Mode
+@section Miscellaneous Options
+@cindex Hooks
+
+@defopt idlwave-help-application
+The external application providing reference help for programming.
+@end defopt
+
+@defopt idlwave-startup-message (@code{t})
+Non-@code{nil} means display a startup message when @code{idlwave-mode}'
+is first called.
+@end defopt
+
+@defopt idlwave-mode-hook
+Normal hook. Executed when a buffer is put into @code{idlwave-mode}.
+@end defopt
+
+@defopt idlwave-load-hook
+Normal hook. Executed when @file{idlwave.el} is loaded.
+@end defopt
+
+@node The IDLWAVE Shell, Acknowledgements, The IDLWAVE Major Mode, Top
+@chapter The IDLWAVE Shell
+@cindex IDLWAVE shell
+@cindex Major mode, @code{idlwave-shell-mode}
+@cindex IDL, as Emacs subprocess
+@cindex Subprocess of Emacs, IDL
+@cindex Comint, Emacs package
+@cindex Windows
+@cindex MacOS
+
+The IDLWAVE shell is an Emacs major mode which permits running the IDL
+program as an inferior process of Emacs, and works closely with the
+IDLWAVE major mode in buffers. It can be used to work with IDL
+interactively, to compile and run IDL programs in Emacs buffers and to
+debug these programs. The IDLWAVE shell is built on @file{comint}, an
+Emacs packages which handles the communication with the IDL program.
+Unfortunately, IDL for Windows does not have command-prompt versions and
+thus do not allow the interaction with Emacs --- so the IDLWAVE shell
+currently only works under Unix and MacOSX.
+
+@menu
+* Starting the Shell:: How to launch IDL as a subprocess
+* Using the Shell:: Interactively working with the Shell
+* Commands Sent to the Shell::
+* Debugging IDL Programs::
+* Examining Variables::
+* Custom Expression Examination::
+@end menu
+
+@node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell
+@section Starting the Shell
+@cindex Starting the shell
+@cindex Shell, starting
+@cindex Dedicated frame, for shell buffer
+@cindex Frame, for shell buffer
+@cindex Subprocess of Emacs, IDL
+
+@kindex C-c C-s
+The IDLWAVE shell can be started with the command @kbd{M-x
+idlwave-shell}. In @code{idlwave-mode} the function is bound to
+@kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to
+interact with the shell. If the shell is already running, @kbd{C-c
+C-s} will simply switch to the shell buffer. The command @kbd{C-c
+C-l} (@code{idlwave-shell-recenter-shell-window}) displays the shell
+window without selecting it. The shell can also be started
+automatically when another command tries to send a command to it. To
+enable auto start, set the variable
+@code{idlwave-shell-automatic-start} to @code{t}.
+
+In order to create a separate frame for the IDLWAVE shell buffer, call
+@code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or
+@kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell
+window, configure the variable
+@code{idlwave-shell-use-dedicated-frame}.
+
+To launch a quick IDLWAVE shell directly from a shell prompt without
+an IDLWAVE buffer (e.g., as a replacement for running inside an
+xterm), define a system alias with the following content:
+
+@example
+emacs -geometry 80x32 -eval "(idlwave-shell 'quick)"
+@end example
+
+Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer
+the Emacs process to run directly inside the terminal window.
+
+@cindex ENVI
+@cindex IDL> Prompt
+
+To use IDLWAVE with ENVI or other custom packages which change the
+@samp{IDL> } prompt, you must change the
+@code{idlwave-shell-prompt-pattern}, which defaults to @samp{"^ ?IDL>
+"}. Normally, you can just replace the @samp{IDL} in this expression
+with the prompt you see. A suitable pattern which matches the prompt
+for both ENVI and IDL simultaneously is @samp{"^ ?\\(ENVI\\|IDL\\)> "}.
+
+@defopt idlwave-shell-explicit-file-name (@file{idl})
+This is the command to run IDL.
+@end defopt
+
+@defopt idlwave-shell-command-line-options
+A list of command line options for calling the IDL program.
+@end defopt
+
+@defopt idlwave-shell-prompt-pattern
+Regexp to match IDL prompt at beginning of a line.
+@end defopt
+
+@defopt idlwave-shell-process-name
+Name to be associated with the IDL process.
+@end defopt
+
+@defopt idlwave-shell-automatic-start (@code{nil})
+Non-@code{nil} means attempt to invoke idlwave-shell if not already
+running.
+@end defopt
+
+@defopt idlwave-shell-initial-commands
+Initial commands, separated by newlines, to send to IDL.
+@end defopt
+
+@defopt idlwave-shell-save-command-history (@code{t})
+Non-@code{nil} means preserve command history between sessions.
+@end defopt
+
+@defopt idlwave-shell-command-history-file (@file{~/.idlwave/.idlwhist})
+The file in which the command history of the idlwave shell is saved.
+Unless it's an absolute path, it goes in
+@code{idlwave-config-directory}.
+@end defopt
+
+@defopt idlwave-shell-use-dedicated-frame (@code{nil})
+Non-@code{nil} means IDLWAVE should use a special frame to display the
+shell buffer.
+@end defopt
+
+@defopt idlwave-shell-use-dedicated-window (@code{nil})
+Non-@code{nil} means use a dedicated window for the shell, taking care
+not it replace it with other buffers.
+@end defopt
+
+@defopt idlwave-shell-frame-parameters
+The frame parameters for a dedicated idlwave-shell frame.
+@end defopt
+
+@defopt idlwave-shell-raise-frame (@code{t})
+Non-@code{nil} means `idlwave-shell' raises the frame showing the shell
+window.
+@end defopt
+
+@defopt idlwave-shell-temp-pro-prefix
+The prefix for temporary IDL files used when compiling regions.
+@end defopt
+
+@cindex Hooks
+@defopt idlwave-shell-mode-hook
+Hook for customizing @code{idlwave-shell-mode}.
+@end defopt
+
+@node Using the Shell, Commands Sent to the Shell, Starting the Shell, The IDLWAVE Shell
+@section Using the Shell
+@cindex Comint
+@cindex Shell, basic commands
+
+The IDLWAVE shell works in the same fashion as other shell modes in
+Emacs. It provides command history, command line editing and job
+control. The @key{UP} and @key{DOWN} arrows cycle through the input
+history just like in an X terminal@footnote{This is different from
+normal Emacs/Comint behavior, but more like an xterm. If you prefer the
+default comint functionality, check the variable
+@code{idlwave-shell-arrows-do-history}.}. The history is preserved
+between emacs and IDL sessions. Here is a list of commonly used
+commands:
+
+@multitable @columnfractions .12 .88
+@item @key{UP}, @key{M-p}
+@tab Cycle backwards in input history
+@item @key{DOWN}, @key{M-n}
+@tab Cycle forwards in input history
+@item @kbd{M-r}
+@tab Previous input matching a regexp
+@item @kbd{M-s}
+@tab Next input matching a regexp
+@item @kbd{return}
+@tab Send input or copy line to current prompt
+@item @kbd{C-c C-a}
+@tab Beginning of line; skip prompt
+@item @kbd{C-c C-u}
+@tab Kill input to beginning of line
+@item @kbd{C-c C-w}
+@tab Kill word before cursor
+@item @kbd{C-c C-c}
+@tab Send ^C
+@item @kbd{C-c C-z}
+@tab Send ^Z
+@item @kbd{C-c C-\}
+@tab Send ^\
+@item @kbd{C-c C-o}
+@tab Delete last batch of process output
+@item @kbd{C-c C-r}
+@tab Show last batch of process output
+@item @kbd{C-c C-l}
+@tab List input history
+@end multitable
+
+In addition to these standard @file{comint} commands,
+@code{idlwave-shell-mode} provides many of the same commands which
+simplify writing IDL code available in IDLWAVE buffers. This includes
+abbreviations, online help, and completion. See @ref{Routine Info} and
+@ref{Online Help} and @ref{Completion} for more information on these
+commands.
+
+@cindex Completion, in the shell
+@cindex Routine info, in the shell
+@cindex Online Help, in the shell
+@multitable @columnfractions .12 .88
+@item @kbd{@key{TAB}}
+@tab Completion of file names (between quotes and after executive
+commands @samp{.run} and @samp{.compile}), routine names, class names,
+keywords, system variables, system variable tags etc.
+(@code{idlwave-shell-complete}).
+@item @kbd{M-@key{TAB}}
+@tab Same as @key{TAB}
+@item @kbd{C-c ?}
+@tab Routine Info display (@code{idlwave-routine-info})
+@item @kbd{M-?}
+@tab IDL online help on routine (@code{idlwave-routine-info-from-idlhelp})
+@item @kbd{C-c C-i}
+@tab Update routine info from buffers and shell
+(@code{idlwave-update-routine-info})
+@item @kbd{C-c C-v}
+@tab Find the source file of a routine (@code{idlwave-find-module})
+@item @kbd{C-c C-t}
+@tab Find the source file of a routine in the currently visited file
+(@code{idlwave-find-module-this-file}).
+@item @kbd{C-c =}
+@tab Compile a library routine (@code{idlwave-resolve})
+@end multitable
+
+@defopt idlwave-shell-arrows-do-history (@code{t})
+Non-@code{nil} means @key{UP} and @key{DOWN} arrows move through command
+history like xterm.
+@end defopt
+
+@defopt idlwave-shell-comint-settings
+Alist of special settings for the comint variables in the IDLWAVE Shell.
+@end defopt
+
+@defopt idlwave-shell-file-name-chars
+The characters allowed in file names, as a string. Used for file name
+completion.
+@end defopt
+
+@defopt idlwave-shell-graphics-window-size
+Size of IDL graphics windows popped up by special IDLWAVE command.
+@end defopt
+
+@cindex Input mode
+@cindex Character input mode (Shell)
+@cindex Line input mode (Shell)
+@cindex Magic spells, for input mode
+@cindex Spells, magic
+IDLWAVE works in line input mode: You compose a full command line, using
+all the power Emacs gives you to do this. When you press @key{RET}, the
+whole line is sent to IDL. Sometimes it is necessary to send single
+characters (without a newline), for example when an IDL program is
+waiting for single character input with the @code{GET_KBRD} function.
+You can send a single character to IDL with the command @kbd{C-c C-x}
+(@code{idlwave-shell-send-char}). When you press @kbd{C-c C-y}
+(@code{idlwave-shell-char-mode-loop}), IDLWAVE runs a blocking loop
+which accepts characters and immediately sends them to IDL. The loop
+can be exited with @kbd{C-g}. It terminates also automatically when the
+current IDL command is finished. Check the documentation of the two
+variables described below for a way to make IDL programs trigger
+automatic switches of the input mode.
+
+@defopt idlwave-shell-use-input-mode-magic (@code{nil})
+Non-@code{nil} means IDLWAVE should check for input mode spells in
+output.
+@end defopt
+
+@defopt idlwave-shell-input-mode-spells
+The three regular expressions which match the magic spells for input
+modes.
+@end defopt
+
+@node Commands Sent to the Shell, Debugging IDL Programs, Using the Shell, The IDLWAVE Shell
+@section Commands Sent to the Shell
+@cindex Commands in shell, showing
+@cindex Showing commands in shell
+
+The IDLWAVE buffers and shell interact very closely. In addition to the
+normal commands you enter at the @code{IDL>} prompt, many other special
+commands are sent to the shell, sometimes as a direct result of invoking
+a key command, menu item, or toolbar button, but also automatically, as
+part of the normal flow of information updates between the buffer and
+shell.
+
+The commands sent include @code{breakpoint}, @code{.step} and other
+debug commands (@pxref{Debugging IDL Programs}), @code{.run} and other
+compilation statements (@pxref{Compiling Programs}), examination
+commands like @code{print} and @code{help} (@pxref{Examining
+Variables}), and other special purpose commands designed to keep
+information on the running shell current.
+
+By default, much of this background shell input and output is hidden
+from the user, but this is configurable. The custom variable
+@code{idlwave-abbrev-show-commands} allows you to configure which
+commands sent to the shell are shown there. For a related customization
+for separating the output of @emph{examine} commands, see @ref{Examining
+Variables}.
+
+@defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)})
+A list of command types to echo in the shell when sent. Possible values
+are @code{run} for @code{.run}, @code{.compile} and other run commands,
+@code{misc} for lesser used commands like @code{window},
+@code{retall},@code{close}, etc., @code{breakpoint} for breakpoint
+setting and clearing commands, and @code{debug} for other debug,
+stepping, and continue commands. In addition, if the variable is set to
+the single symbol @code{'everything}, all the copious shell input is
+displayed (which is probably only useful for debugging purposes).
+N.B. For hidden commands which produce output by side-effect, that
+output remains hidden (e.g., stepping through a @code{print} command).
+As a special case, any error message in the output will be displayed
+(e.g., stepping to an error).
+@end defopt
+
+@node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell
+@section Debugging IDL Programs
+@cindex Debugging
+@cindex Keybindings for debugging
+@cindex Toolbar
+
+Programs can be compiled, run, and debugged directly from the source
+buffer in Emacs, walking through arbitrarily deeply nested code,
+printing expressions and skipping up and down the calling stack along
+the way. IDLWAVE makes compiling and debugging IDL programs far less
+cumbersome by providing a full-featured, key/menu/toolbar-driven
+interface to commands like @code{breakpoint}, @code{.step},
+@code{.run}, etc. It can even perform complex debug operations not
+natively supported by IDL (like continuing to the line at the cursor).
+
+The IDLWAVE shell installs key bindings both in the shell buffer and
+in all IDL code buffers of the current Emacs session, so debug
+commands work in both places (in the shell, commands operate on the
+last file compiled). On Emacs versions which support it, a debugging
+toolbar is also installed. The toolbar display can be toggled with
+@kbd{C-c C-d C-t} (@code{idlwave-shell-toggle-toolbar}).
+
+
+@defopt idlwave-shell-use-toolbar (@code{t})
+Non-@code{nil} means use the debugging toolbar in all IDL related
+buffers.
+@end defopt
+
+@menu
+* A Tale of Two Modes::
+* Debug Key Bindings::
+* Breakpoints and Stepping::
+* Compiling Programs::
+* Walking the Calling Stack::
+* Electric Debug Mode::
+@end menu
+
+
+@node A Tale of Two Modes, Debug Key Bindings, Debugging IDL Programs, Debugging IDL Programs
+@subsection A Tale of Two Modes
+@cindex Electric Debug Mode
+@cindex Debugging Interface
+
+The many debugging, compiling, and examination commands provided in
+IDLWAVE are available simultaneously through two different interfaces:
+the original, multi-key command interface, and the new Electric Debug
+Mode. The functionality they offer is similar, but the way you interact
+with them is quite different. The main difference is that, in Electric
+Debug Mode, the source buffers are made read-only, and single
+key-strokes are used to step through, examine expressions, set and
+remove breakpoints, etc. The same variables, prefix arguments, and
+settings apply to both versions, and both can be used interchangeably.
+By default, when breakpoints are hit, Electric Debug Mode is enabled.
+The traditional interface is described first. @xref{Electric Debug
+Mode}, for more on that mode. Note that electric debug mode can be
+prevented from activating automatically by customizing the variable
+@code{idlwave-shell-automatic-electric-debug}.
+
+@node Debug Key Bindings, Breakpoints and Stepping, A Tale of Two Modes, Debugging IDL Programs
+@subsection Debug Key Bindings
+@kindex C-c C-d
+@cindex Key bindings
+
+The standard debugging key bindings are always available by default on
+the prefix key @kbd{C-c C-d}, so, for example, setting a breakpoint is
+done with @kbd{C-c C-d C-b}, and compiling a source file with @kbd{C-c
+C-d C-c}. You can also easily configure IDLWAVE to use one or more
+modifier keys not in use by other commands, in lieu of the prefix
+@kbd{C-c C-d} (though these bindings will typically also be available
+--- see @code{idlwave-shell-activate-prefix-keybindings}). For
+example, if you include in @file{.emacs}:
+
+@lisp
+(setq idlwave-shell-debug-modifiers '(control shift))
+@end lisp
+
+@noindent a breakpoint can then be set by pressing @kbd{b} while holding down
+@kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a
+source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d},
+etc. In the remainder of this chapter we will assume that the
+@kbd{C-c C-d} bindings are active, but each of these bindings will
+have an equivalent shortcut if modifiers are given in the
+@code{idlwave-shell-debug-modifiers} variable (@pxref{Lesson II --
+Customization}). A much simpler and faster form of debugging for
+running code is also available by default --- see @ref{Electric Debug
+Mode}.
+
+@defopt idlwave-shell-prefix-key (@kbd{C-c C-d})
+The prefix key for the debugging map
+@code{idlwave-shell-mode-prefix-map}.
+@end defopt
+
+@defopt idlwave-shell-activate-prefix-keybindings (@code{t})
+Non-@code{nil} means debug commands will be bound to the prefix
+key, like @kbd{C-c C-d C-b}.
+@end defopt
+
+@defopt idlwave-shell-debug-modifiers (@code{nil})
+List of modifier keys to use for additional, alternative binding of
+debugging commands in the shell and source buffers. Can be one or
+more of @code{control}, @code{meta}, @code{super}, @code{hyper},
+@code{alt}, and @code{shift}.
+@end defopt
+
+@node Breakpoints and Stepping, Compiling Programs, Debug Key Bindings, Debugging IDL Programs
+@subsection Breakpoints and Stepping
+@cindex Breakpoints
+@cindex Stepping
+@cindex Execution, controlled
+
+@kindex C-c C-d C-b
+@kindex C-c C-d C-b
+IDLWAVE helps you set breakpoints and step through code. Setting a
+breakpoint in the current line of the source buffer is accomplished
+with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a
+prefix arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a
+@code{/ONCE} keyword, meaning that it will be deleted after first use.
+With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}),
+the breakpoint will only be active the @code{nth} time it is hit.
+With a single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt
+for a condition --- an IDL expression to be evaluated and trigger the
+breakpoint only if true. To clear the breakpoint in the current line,
+use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When
+executed from the shell window, the breakpoint where IDL is currently
+stopped will be deleted. To clear all breakpoints, use @kbd{C-c C-d
+C-a} (@code{idlwave-clear-all-bp}). Breakpoints can also be disabled
+and re-enabled: @kbd{C-c C-d C-\}
+(@code{idlwave-shell-toggle-enable-current-bp}).
+
+Breakpoint lines are highlighted or indicated with an icon in the source
+code (different icons for conditional, after, and other break types).
+Disabled breakpoints are @emph{grayed out} by default. Note that IDL
+places breakpoints as close as possible on or after the line you
+specify. IDLWAVE queries the shell for the actual breakpoint location
+which was set, so the exact line you specify may not be marked. You can
+re-sync the breakpoint list and update the display at any time (e.g., if
+you add or remove some on the command line) using @kbd{C-c C-d C-l}.
+
+In recent IDLWAVE versions, the breakpoint line is highlighted when the
+mouse is moved over it, and a tooltip pops up describing the break
+details. @kbd{Mouse-3} on the breakpoint line pops up a menu of
+breakpoint actions, including clearing, disabling, and adding or
+changing break conditions or ``after'' break count.
+
+Once the program has stopped somewhere, you can step through it. The
+most important stepping commands are @kbd{C-c C-d C-s} to execute one
+line of IDL code ("step into"); @kbd{C-c C-d C-n} to step a single line,
+treating procedure and function calls as a single step ("step over");
+@kbd{C-c C-d C-h} to continue execution to the line at the cursor and
+@kbd{C-c C-d C-r} to continue execution. @xref{Commands Sent to the
+Shell}, for information on displaying or hiding the breakpoint and
+stepping commands the shell receives. Here is a summary of the
+breakpoint and stepping commands:
+
+@multitable @columnfractions .23 .77
+@item @kbd{C-c C-d C-b}
+@tab Set breakpoint (@code{idlwave-shell-break-here})
+@item @kbd{C-c C-d C-i}
+@tab Set breakpoint in module named here (@code{idlwave-shell-break-in})
+@item @kbd{C-c C-d C-d}
+@tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp})
+@item @kbd{C-c C-d C-a}
+@tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp})
+@item @kbd{C-c C-d [}
+@tab Go to the previous breakpoint (@code{idlwave-shell-goto-previous-bp})
+@item @kbd{C-c C-d ]}
+@tab Go to the next breakpoint (@code{idlwave-shell-goto-next-bp})
+@item @kbd{C-c C-d C-\}
+@tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp})
+@item @kbd{C-c C-d C-j}
+@tab Set a breakpoint at the beginning of the enclosing routine.
+@item @kbd{C-c C-d C-s}
+@tab Step, into function calls (@code{idlwave-shell-step})
+@item @kbd{C-c C-d C-n}
+@tab Step, over function calls (@code{idlwave-shell-stepover})
+@item @kbd{C-c C-d C-k}
+@tab Skip one statement (@code{idlwave-shell-skip})
+@item @kbd{C-c C-d C-u}
+@tab Continue to end of block (@code{idlwave-shell-up})
+@item @kbd{C-c C-d C-m}
+@tab Continue to end of function (@code{idlwave-shell-return})
+@item @kbd{C-c C-d C-o}
+@tab Continue past end of function (@code{idlwave-shell-out})
+@item @kbd{C-c C-d C-h}
+@tab Continue to line at cursor position (@code{idlwave-shell-to-here})
+@item @kbd{C-c C-d C-r}
+@tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont})
+@item @kbd{C-c C-d C-up}
+@tab Show higher level in calling stack (@code{idlwave-shell-stack-up})
+@item @kbd{C-c C-d C-down}
+@tab Show lower level in calling stack (@code{idlwave-shell-stack-down})
+@end multitable
+
+All of these commands have equivalents in Electric Debug Mode, which
+provides faster single-key access (@pxref{Electric Debug Mode}).
+
+The line where IDL is currently stopped, at breakpoints, halts, and
+errors, etc., is marked with a color overlay or arrow, depending on the
+setting in @code{idlwave-shell-mark-stop-line}. If an overlay face is
+used to mark the stop line (as it is by default), when stepping through
+code, the face color is temporarily changed to gray, until IDL completes
+the next command and moves to the new line.
+
+@defopt idlwave-shell-mark-breakpoints (@code{t})
+Non-@code{nil} means mark breakpoints in the source file buffers. The
+value indicates the preferred method. Valid values are @code{nil},
+@code{t}, @code{face}, and @code{glyph}.
+@end defopt
+
+@defopt idlwave-shell-breakpoint-face
+The face for breakpoint lines in the source code if
+@code{idlwave-shell-mark-breakpoints} has the value @code{face}.
+@end defopt
+
+@defopt idlwave-shell-breakpoint-popup-menu (@code{t})
+Whether to pop-up a menu and present a tooltip description on
+breakpoint lines.
+@end defopt
+
+@defopt idlwave-shell-mark-stop-line (@code{t})
+Non-@code{nil} means mark the source code line where IDL is currently
+stopped. The value specifies the preferred method. Valid values are
+@code{nil}, @code{t}, @code{arrow}, and @code{face}.
+@end defopt
+
+@defopt idlwave-shell-overlay-arrow (@code{">"})
+The overlay arrow to display at source lines where execution halts, if
+configured in @code{idlwave-shell-mark-stop-line}.
+@end defopt
+
+@defopt idlwave-shell-stop-line-face
+The face which highlights the source line where IDL is stopped, if
+configured in @code{idlwave-shell-mark-stop-line}.
+@end defopt
+
+
+@node Compiling Programs, Walking the Calling Stack, Breakpoints and Stepping, Debugging IDL Programs
+@subsection Compiling Programs
+@cindex Compiling programs
+@cindex Programs, compiling
+@cindex Default command line, executing
+@cindex Executing a default command line
+
+@kindex C-c C-d C-c
+In order to compile the current buffer under the IDLWAVE shell, press
+@kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the
+current buffer and then sends the command @samp{.run path/to/file} to the
+shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in
+which case the most recently compiled buffer will be saved and
+re-compiled.
+
+When developing or debugging a program, it is often necessary to execute
+the same command line many times. A convenient way to do this is
+@kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}).
+This command first resets IDL from a state of interrupted execution by
+closing all files and returning to the main interpreter level. Then a
+default command line is send to the shell. To edit the default command
+line, call @code{idlwave-shell-execute-default-command-line} with a
+prefix argument: @kbd{C-u C-c C-d C-y}. If no default command line has
+been set (or you give two prefix arguments), the last command on the
+@code{comint} input history is sent.
+
+@kindex C-c C-d C-e
+@cindex Compiling regions
+For quickly compiling and running the currently marked region as a main
+level program @kbd{C-c C-d C-e} (@code{idlwave-shell-run-region}) is
+very useful. A temporary file is created holding the contents of the
+current region (with @code{END} appended), and run from the shell.
+
+@node Walking the Calling Stack, Electric Debug Mode, Compiling Programs, Debugging IDL Programs
+@subsection Walking the Calling Stack
+@cindex Calling stack, walking
+
+While debugging a program, it can be very useful to check the context in
+which the current routine was called, for instance to help understand
+the value of the arguments passed. To do so conveniently you need to
+examine the calling stack. If execution is stopped somewhere deep in a
+program, you can use the commands @kbd{C-c C-d C-@key{UP}}
+(@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}}
+(@code{idlwave-shell-stack-down}), or the corresponding toolbar buttons,
+to move up or down through the calling stack. The mode line of the
+shell window will indicate the position within the stack with a label
+like @samp{[-3:MYPRO]}. The line of IDL code at that stack position
+will be highlighted. If you continue execution, IDLWAVE will
+automatically return to the current level. @xref{Examining Variables},
+for information how to examine the value of variables and expressions on
+higher calling stack levels.
+
+@html
+<A NAME="EDEBUG"></A>
+@end html
+@node Electric Debug Mode, , Walking the Calling Stack, Debugging IDL Programs
+@subsection Electric Debug Mode
+@cindex Electric Debug Mode
+@cindex @samp{*Debugging*}
+
+Even with a convenient debug key prefix enabled, repetitive stepping,
+variable examination (@pxref{Examining Variables}), and other debugging
+activities can be awkward and slow using commands which require multiple
+keystrokes. Luckily, there's a better way, inspired by the lisp e-debug
+mode, and available through the @emph{Electric Debug Mode}. By default,
+as soon as a breakpoint is hit, this minor mode is enabled. The buffer
+showing the line where execution has halted is switched to Electric
+Debug Mode. This mode is visible as @samp{*Debugging*} in the mode
+line, and a different face (violet by default, if color is available)
+for the line stopped at point. The buffer is made read-only and
+single-character bindings for the most commonly used debugging commands
+are enabled. These character commands (a list of which is available
+with @kbd{C-?}) are:
+
+@multitable @columnfractions .2 .8
+@item @kbd{a}
+@tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp})
+@item @kbd{b}
+@tab Set breakpoint, @kbd{C-u b} for a conditional break, @kbd{C-n b} for nth hit (@code{idlwave-shell-break-here})
+@item @kbd{d}
+@tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp})
+@item @kbd{e}
+@tab Prompt for expression to print (@code{idlwave-shell-clear-current-bp}).
+@item @kbd{h}
+@tab Continue to the line at cursor position (@code{idlwave-shell-to-here})
+@item @kbd{i}
+@tab Set breakpoint in module named here (@code{idlwave-shell-break-in})
+@item @kbd{[}
+@tab Go to the previous breakpoint in the file (@code{idlwave-shell-goto-previous-bp})
+@item @kbd{]}
+@tab Go to the next breakpoint in the file
+(@code{idlwave-shell-goto-next-bp})
+@item @kbd{\}
+@tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp})
+@item @kbd{j}
+@tab Set breakpoint at beginning of enclosing routine (@code{idlwave-shell-break-this-module})
+@item @kbd{k}
+@tab Skip one statement (@code{idlwave-shell-skip})
+@item @kbd{m}
+@tab Continue to end of function (@code{idlwave-shell-return})
+@item @kbd{n}
+@tab Step, over function calls (@code{idlwave-shell-stepover})
+@item @kbd{o}
+@tab Continue past end of function (@code{idlwave-shell-out})
+@item @kbd{p}
+@tab Print expression near point or in region with @kbd{C-u p} (@code{idlwave-shell-print})
+@item @kbd{q}
+@tab End the debugging session and return to the Shell's main level
+(@code{idlwave-shell-retall})
+@item @kbd{r}
+@tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont})
+@item @kbd{s} or @kbd{@key{SPACE}}
+@tab Step, into function calls (@code{idlwave-shell-step})
+@item @kbd{t}
+@tab Print a calling-level traceback in the shell
+@item @kbd{u}
+@tab Continue to end of block (@code{idlwave-shell-up})
+@item @kbd{v}
+@tab Turn Electric Debug Mode off
+(@code{idlwave-shell-electric-debug-mode})
+@item @kbd{x}
+@tab Examine expression near point (or in region with @kbd{C-u x})
+with shortcut of examine type.
+@item @kbd{z}
+@tab Reset IDL (@code{idlwave-shell-reset})
+@item @kbd{+} or @kbd{=}
+@tab Show higher level in calling stack (@code{idlwave-shell-stack-up})
+@item @kbd{-} or @kbd{_}
+@tab Show lower level in calling stack (@code{idlwave-shell-stack-down})
+@item @kbd{?}
+@tab Help on expression near point or in region with @kbd{C-u ?}
+(@code{idlwave-shell-help-expression})
+@item @kbd{C-?}
+@tab Show help on the commands available.
+@end multitable
+
+Most single-character electric debug bindings use the final keystroke
+of the equivalent multiple key commands (which are of course also
+still available), but some differ (e.g. @kbd{e},@kbd{t},@kbd{q},@kbd{x}).
+Some have additional convenience bindings (like @kbd{@key{SPACE}} for
+stepping). All prefix and other argument options described in this
+section for the commands invoked by electric debug bindings are still
+valid. For example, @kbd{C-u b} sets a conditional breakpoint, just
+as it did with @kbd{C-u C-c C-d C-b}.
+
+You can toggle the electric debug mode at any time in a buffer using
+@kbd{C-c C-d C-v} (@kbd{v} to turn it off while in the mode), or from
+the Debug menu. Normally the mode will be enabled and disabled at the
+appropriate times, but occasionally you might want to edit a file
+while still debugging it, or switch to the mode for conveniently
+setting lots of breakpoints.
+
+To quickly abandon a debugging session and return to normal editing at
+the Shell's main level, use @kbd{q} (@code{idlwave-shell-retall}).
+This disables electric debug mode in all IDLWAVE buffers@footnote{Note
+that this binding is not symmetric: @kbd{C-c C-d C-q} is bound to
+@code{idlwave-shell-quit}, which quits your IDL session.}. Help is
+available for the command shortcuts with @kbd{C-?}. If you find this
+mode gets in your way, you can keep it from automatically activating
+by setting the variable @code{idlwave-shell-automatic-electric-debug}
+to @code{nil}, or @code{'breakpoint}. If you'd like the convenient
+electric debug shortcuts available also when run-time errors are
+encountered, set to @code{t}.
+
+@defopt idlwave-shell-automatic-electric-debug (@code{'breakpoint})
+Whether to enter electric debug mode automatically when a breakpoint
+or run-time error is encountered, and then disable it in all buffers
+when the $MAIN$ level is reached (either through normal program
+execution, or retall). In addition to @code{nil} for never, and
+@code{t} for both breakpoints and errors, this can be
+@code{'breakpoint} (the default) to enable it only at breakpoint
+halts.
+@end defopt
+
+@defopt idlwave-shell-electric-stop-color (Violet)
+Default color of the stopped line overlay when in electric debug mode.
+@end defopt
+
+@defopt idlwave-shell-electric-stop-line-face
+The face to use for the stopped line. Defaults to a face similar to the
+modeline, with color @code{idlwave-shell-electric-stop-color}.
+@end defopt
+
+@defopt idlwave-shell-electric-zap-to-file (@code{t})
+If set, when entering electric debug mode, select the window displaying
+the file where point is stopped. This takes point away from the shell
+window, but is useful for immediate stepping, etc.
+@end defopt
+
+@html
+<A NAME="EXAMINE"></A>
+@end html
+@node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell
+@section Examining Variables
+@cindex @code{PRINT} expressions
+@cindex @code{HELP}, on expressions
+@cindex Expressions, printing & help
+@cindex Examining expressions
+@cindex Printing expressions
+@cindex Mouse binding to print expressions
+
+@kindex C-c C-d C-p
+Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)},
+and similar statements to remind yourself of the
+type/size/structure/value/etc. of variables and expressions in your code
+or at the command line? IDLWAVE has a suite of special commands to
+automate these types of variable or expression examinations. They work
+by sending statements to the shell formatted to include the indicated
+expression, and can be accessed in several ways.
+
+These @emph{examine} commands can be used in the shell or buffer at any
+time (as long as the shell is running), and are very useful when
+execution is stopped in a buffer due to a triggered breakpoint or error,
+or while composing a long command in the IDLWAVE shell. In the latter
+case, the command is sent to the shell and its output is visible, but
+point remains unmoved in the command being composed --- you can inspect
+the constituents of a command you're building without interrupting the
+process of building it! You can even print arbitrary expressions from
+older input or output further up in the shell window --- any expression,
+variable, number, or function you see can be examined.
+
+If the variable @code{idlwave-shell-separate-examine-output} is
+non-@code{nil} (the default), all examine output will be sent to a
+special @file{*Examine*} buffer, rather than the shell. The output of
+prior examine commands is saved in this buffer. In this buffer @key{c}
+clears the contents, and @key{q} hides the buffer.
+
+The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to
+print the expression at point, and @kbd{C-c C-d ?}, to invoke help on
+this expression@footnote{Available as @kbd{p} and @kbd{?} in Electric
+Debug Mode (@pxref{Electric Debug Mode})}. The expression at point is
+either an array expression or a function call, or the contents of a pair
+of parentheses. The chosen expression is highlighted, and
+simultaneously the resulting output is highlighted in the shell or
+separate output buffer. Calling the above commands with a prefix
+argument will use the current region as expression instead of using the
+one at point. which can be useful for examining complicated, multi-line
+expressions. Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will
+prompt for an expression to print directly. By default, when invoking
+print, only an initial portion of long arrays will be printed, up to
+@code{idlwave-shell-max-print-length}.
+
+For added speed and convenience, there are mouse bindings which allow
+you to click on expressions and examine their values. Use
+@kbd{S-Mouse-2} to print an expression and @kbd{C-M-Mouse-2} to invoke
+help (i.e. you need to hold down @key{META} and @key{CONTROL} while
+clicking with the middle mouse button). If you simply click, the
+nearest expression will be selected in the same manner as described
+above. You can also @emph{drag} the mouse in order to highlight
+exactly the specific expression or sub-expression you want to examine.
+For custom expression examination, and the powerful customizable
+pop-up examine selection, @xref{Custom Expression Examination}.
+
+@cindex Printing expressions, on calling stack
+@cindex Restrictions for expression printing
+The same variable inspection commands work both in the IDL Shell and
+IDLWAVE buffers, and even for variables at higher levels of the calling
+stack. For instance, if you're stopped at a breakpoint in a routine,
+you can examine the values of variables and expressions inside its
+calling routine, and so on, all the way up through the calling stack.
+Simply step up the stack, and print variables as you see them
+(@pxref{Walking the Calling Stack}, for information on stepping back
+through the calling stack). The following restrictions apply for all
+levels except the current:
+
+@itemize @bullet
+@item
+Array expressions must use the @samp{[ ]} index delimiters. Identifiers
+with a @samp{( )} will be interpreted as function calls.
+@item
+@cindex ROUTINE_NAMES, IDL procedure
+N.B.: printing values of expressions on higher levels of the calling
+stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES},
+which may or may not be available in future versions of IDL. Caveat
+Examinor.
+@end itemize
+
+@defopt idlwave-shell-expression-face
+The face for @code{idlwave-shell-expression-overlay}.
+Allows you to choose the font, color and other properties for
+the expression printed by IDL.
+@end defopt
+
+@defopt idlwave-shell-output-face
+The face for @code{idlwave-shell-output-overlay}.
+Allows to choose the font, color and other properties for the most
+recent output of IDL when examining an expression."
+@end defopt
+
+@defopt idlwave-shell-separate-examine-output (@code{t})
+If non-@code{nil}, re-direct the output of examine commands to a special
+@file{*Examine*} buffer, instead of in the shell itself.
+@end defopt
+
+@defopt idlwave-shell-max-print-length (200)
+The maximum number of leading array entries to print, when examining
+array expressions.
+@end defopt
+
+@node Custom Expression Examination, , Examining Variables, The IDLWAVE Shell
+@section Custom Expression Examination
+@cindex Expressions, custom examination
+@cindex Custom expression examination
+
+The variety of possible variable and expression examination commands is
+endless (just look, for instance, at the keyword list to
+@code{widget_info()}). Rather than attempt to include them all, IDLWAVE
+provides two easy methods to customize your own commands, with a special
+mouse examine command, and two macros for generating your own examine
+key and mouse bindings.
+
+The most powerful and flexible mouse examine command of all is
+available on @kbd{C-S-Mouse-2}. Just as for all the other mouse
+examine commands, it permits click or drag expression selection, but
+instead of sending hard-coded commands to the shell, it pops-up a
+customizable selection list of examine functions to choose among,
+configured with the @code{idlwave-shell-examine-alist}
+variable@footnote{In Electric Debug Mode (@pxref{Electric Debug
+Mode}), the key @kbd{x} provides a single-character shortcut interface
+to the same examine functions for the expression at point or marked by
+the region.}. This variable is a list of key-value pairs (an
+@emph{alist} in Emacs parlance), where the key gives a name to be
+shown for the examine command, and the value is the command strings
+itself, in which the text @code{___} (three underscores) will be
+replaced by the selected expression before being sent to the shell.
+An example might be key @code{Structure Help} with value
+@code{help,___,/STRUCTURE}. In that case, you'd be prompted with
+@emph{Structure Help}, which might send something like
+@code{help,var,/STRUCTURE} to the shell for output.
+@code{idlwave-shell-examine-alist} comes configured by default with a
+large list of examine commands, but you can easily customize it to add
+your own.
+
+In addition to configuring the functions available to the pop-up mouse
+command, you can easily create your own customized bindings to inspect
+expressions using the two convenience macros
+@code{idlwave-shell-examine} and @code{idlwave-shell-mouse-examine}.
+These create keyboard or mouse-based custom inspections of variables,
+sharing all the same properties of the built-in examine commands.
+Both functions take a single string argument sharing the syntax of the
+@code{idlwave-shell-examine-alist} values, e.g.:
+
+@lisp
+(add-hook 'idlwave-shell-mode-hook
+ (lambda ()
+ (idlwave-shell-define-key-both [s-down-mouse-2]
+ (idlwave-shell-mouse-examine
+ "print, size(___,/DIMENSIONS)"))
+ (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
+ "print, size(___,/DIMENSIONS)"))
+ (idlwave-shell-define-key-both [f10] (idlwave-shell-examine
+ "print,size(___,/TNAME)"))
+ (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
+ "help,___,/STRUCTURE"))))
+@end lisp
+
+@noindent Now pressing @key{f9}, or middle-mouse dragging with the
+@key{SUPER} key depressed, will print the dimensions of the nearby or
+highlighted expression. Pressing @key{f10} will give the type string,
+and @key{f11} will show the contents of a nearby structure. As you can
+see, the possibilities are only marginally finite.
+
+@defopt idlwave-shell-examine-alist
+An alist of examine commands in which the keys name the command and
+are displayed in the selection pop-up, and the values are custom IDL
+examine command strings to send, after all instances of @code{___}
+(three underscores) are replaced by the indicated expression.
+@end defopt
+
+@node Acknowledgements, Sources of Routine Info, The IDLWAVE Shell, Top
+@chapter Acknowledgements
+@cindex Acknowledgements
+@cindex Maintainer, of IDLWAVE
+@cindex Authors, of IDLWAVE
+@cindex Contributors, to IDLWAVE
+@cindex Email address, of Maintainer
+@cindex Thanks
+
+@noindent
+The main contributors to the IDLWAVE package have been:
+
+@itemize @minus
+@item
+@uref{mailto:chase@@att.com, @b{Chris Chase}}, the original author.
+Chris wrote @file{idl.el} and @file{idl-shell.el} and maintained them
+for several years.
+
+@item
+@uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}} was in charge
+of the package from version 3.0, during which time he overhauled almost
+everything, modernized IDLWAVE with many new features, and developed the
+manual.
+
+@item
+@uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current
+maintainer, as of version 4.10, helped shape object method completion
+and most new features introduced in versions 4.x, and introduced many
+new features for IDLWAVE versions 5.x and 6.x.
+@end itemize
+
+@noindent
+The following people have also contributed to the development of IDLWAVE
+with patches, ideas, bug reports and suggestions.
+
+@itemize @minus
+@item
+Ulrik Dickow <dickow__at__nbi.dk>
+@item
+Eric E. Dors <edors__at__lanl.gov>
+@item
+Stein Vidar H. Haugan <s.v.h.haugan__at__astro.uio.no>
+@item
+David Huenemoerder <dph__at__space.mit.edu>
+@item
+Kevin Ivory <Kevin.Ivory__at__linmpi.mpg.de>
+@item
+Dick Jackson <dick__at__d-jackson.com>
+@item
+Xuyong Liu <liu__at__stsci.edu>
+@item
+Simon Marshall <Simon.Marshall__at__esrin.esa.it>
+@item
+Craig Markwardt <craigm__at__cow.physics.wisc.edu>
+@item
+Laurent Mugnier <mugnier__at__onera.fr>
+@item
+Lubos Pochman <lubos__at__rsinc.com>
+@item
+Bob Portmann <portmann__at__al.noaa.gov>
+@item
+Patrick M. Ryan <pat__at__jaameri.gsfc.nasa.gov>
+@item
+Marty Ryba <ryba__at__ll.mit.edu>
+@item
+Phil Williams <williams__at__irc.chmcc.org>
+@item
+Phil Sterne <sterne__at__dublin.llnl.gov>
+@item
+Paul Sorenson <aardvark62__at__msn.com>
+@end itemize
+
+Doug Dirks was instrumental in providing the crucial IDL XML catalog to
+support HTML help with IDL v6.2 and later, and Ali Bahrami provided
+scripts and documentation to interface with the IDL Assistant.
+
+@noindent
+Thanks to everyone!
+
+@node Sources of Routine Info, HTML Help Browser Tips, Acknowledgements, Top
+@appendix Sources of Routine Info
+
+@cindex Sources of routine information
+In @ref{Routine Info} and @ref{Completion} we showed how IDLWAVE
+displays the calling sequence and keywords of routines, and completes
+routine names and keywords. For these features to work, IDLWAVE must
+know about the accessible routines.
+
+@menu
+* Routine Definitions:: Where IDL Routines are defined.
+* Routine Information Sources:: So how does IDLWAVE know about...
+* Catalogs::
+* Load-Path Shadows:: Routines defined in several places
+* Documentation Scan:: Scanning the IDL Manuals
+@end menu
+
+@node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info
+@appendixsec Routine Definitions
+@cindex Routine definitions
+@cindex IDL variable @code{!PATH}
+@cindex @code{!PATH}, IDL variable
+@cindex @code{CALL_EXTERNAL}, IDL routine
+@cindex @code{LINKIMAGE}, IDL routine
+@cindex External routines
+
+@noindent Routines which can be used in an IDL program can be defined in
+several places:
+
+@enumerate
+@item
+@emph{Builtin routines} are defined inside IDL itself. The source code
+of such routines is not available, but instead are learned about through
+the IDL documentation.
+@item
+Routines which are @emph{part of the current program}, are defined in a
+file explicitly compiled by the user. This file may or may not be
+located on the IDL search path.
+@item
+@emph{Library routines} are defined in files located on IDL's search
+path. When a library routine is called for the first time, IDL will
+find the source file and compile it dynamically. A special sub-category
+of library routines are the @emph{system routines} distributed with IDL,
+and usually available in the @file{lib} subdirectory of the IDL
+distribution.
+@item
+External routines written in other languages (like Fortran or C) can be
+called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE},
+or included as dynamically loaded modules (DLMs). Currently IDLWAVE
+cannot provide routine info and completion for such external routines,
+except by querying the Shell for calling information (DLMs only).
+@end enumerate
+
+@node Routine Information Sources, Catalogs, Routine Definitions, Sources of Routine Info
+@appendixsec Routine Information Sources
+@cindex Routine info sources
+@cindex Builtin list of routines
+@cindex Updating routine info
+@cindex Scanning buffers for routine info
+@cindex Buffers, scanning for routine info
+@cindex Shell, querying for routine info
+
+@noindent To maintain the most comprehensive information about all IDL
+routines on a system, IDLWAVE collects data from many sources:
+
+@enumerate
+
+@item
+It has a @emph{builtin list} with information about the routines IDL
+ships with. IDLWAVE @value{VERSION} is distributed with a list of
+@value{NSYSROUTINES} routines and object methods, reflecting IDL version
+@value{IDLVERSION}. As of IDL v6.2, the routine info is distributed
+directly with IDL in the form of an XML catalog which IDLWAVE scans.
+Formerly, this list was created by scanning the IDL manuals to produce
+the file @file{idlw-rinfo.el}.
+
+@item
+IDLWAVE @emph{scans} all its @emph{buffers} in the current Emacs session
+for routine definitions. This is done automatically when routine
+information or completion is first requested by the user. Each new
+buffer and each buffer saved after making changes is also scanned. The
+command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used
+at any time to rescan all buffers.
+
+@item
+If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will
+@emph{query the shell} for compiled routines and their arguments. This
+happens automatically when routine information or completion is first
+requested by the user. Each time an Emacs buffer is compiled with
+@kbd{C-c C-d C-c}, the routine info for that file is queried. Though
+rarely necessary, the command @kbd{C-c C-i}
+(@code{idlwave-update-routine-info}) can be used to explicitly update
+the shell routine data.
+
+@item
+Many popular libraries are distributed with routine information already
+scanned into @emph{library catalogs} (@pxref{Library Catalogs}). These
+per-directory catalog files can also be built by the user with the
+supplied @file{idlwave_catalog} tool. They are automatically discovered
+by IDLWAVE.
+
+@item
+IDLWAVE can scan selected directories of source files and store the
+result in a single @emph{user catalog} file which will be
+automatically loaded just like @file{idlw-rinfo.el}. @xref{User
+Catalog}, for information on how to scan files in this way.
+@end enumerate
+
+Loading all the routine and catalog information can be a time consuming
+process, especially over slow networks. Depending on the system and
+network configuration it could take up to 30 seconds (though locally on
+fast systems is usually only a few seconds). In order to minimize the
+wait time upon your first completion or routine info command in a
+session, IDLWAVE uses Emacs idle time to do the initialization in six
+steps, yielding to user input in between. If this gets into your way,
+set the variable @code{idlwave-init-rinfo-when-idle-after} to 0 (zero).
+The more routines documented in library and user catalogs, the slower
+the loading will be, so reducing this number can help alleviate any long
+load times.
+
+@defopt idlwave-init-rinfo-when-idle-after (@code{10})
+Seconds of idle time before routine info is automatically initialized.
+@end defopt
+
+@defopt idlwave-scan-all-buffers-for-routine-info (@code{t})
+Non-@code{nil} means scan all buffers for IDL programs when updating
+info.
+@end defopt
+
+@defopt idlwave-query-shell-for-routine-info (@code{t})
+Non-@code{nil} means query the shell for info about compiled routines.
+@end defopt
+
+@defopt idlwave-auto-routine-info-updates
+Controls under what circumstances routine info is updated automatically.
+@end defopt
+
+@html
+<A NAME="CATALOGS"></A>
+@end html
+@node Catalogs, Load-Path Shadows, Routine Information Sources, Sources of Routine Info
+@appendixsec Catalogs
+@cindex Catalogs
+
+@emph{Catalogs} are files containing scanned information on individual
+routines, including arguments and keywords, calling sequence, file path,
+class and procedure vs. function type, etc. They represent a way of
+extending the internal built-in information available for IDL system
+routines (@pxref{Routine Info}) to other source collections.
+
+Starting with version 5.0, there are two types of catalogs available
+with IDLWAVE. The traditional @emph{user catalog} and the newer
+@emph{library catalogs}. Although they can be used interchangeably, the
+library catalogs are more flexible, and preferred. There are few
+occasions when a user catalog might be preferred --- read below. Both
+types of catalogs can coexist without causing problems.
+
+To facilitate the catalog systems, IDLWAVE stores information it gathers
+from the shell about the IDL search paths, and can write this
+information out automatically, or on-demand (menu @code{Debug->Save Path
+Info}). On systems with no shell from which to discover the path
+information (e.g. Windows), a library path must be specified in
+@code{idlwave-library-path} to allow library catalogs to be located, and
+to setup directories for user catalog scan (@pxref{User Catalog} for
+more on this variable). Note that, before the shell is running, IDLWAVE
+can only know about the IDL search path by consulting the file pointed
+to by @code{idlwave-path-file} (@file{~/.idlwave/idlpath.el}, by
+default). If @code{idlwave-auto-write-path} is enabled (which is the
+default), the paths are written out whenever the IDLWAVE shell is
+started.
+
+@defopt idlwave-auto-write-path (@code{t})
+Write out information on the !PATH and !DIR paths from IDL automatically
+when they change and when the Shell is closed. These paths are needed
+to locate library catalogs.
+@end defopt
+
+@defopt idlwave-library-path
+IDL library path for Windows and MacOS. Under Unix/MacOSX, will be
+obtained from the Shell when run.
+@end defopt
+
+@defopt idlwave-system-directory
+The IDL system directory for Windows and MacOS. Also needed for
+locating HTML help and the IDL Assistant for IDL v6.2 and later. Under
+Unix/MacOSX, will be obtained from the Shell and recorded, if run.
+@end defopt
+
+@defopt idlwave-config-directory (@file{~/.idlwave})
+Default path where IDLWAVE saves configuration information, a user
+catalog (if any), and a cached scan of the XML catalog (IDL v6.2 and
+later).
+@end defopt
+
+@menu
+* Library Catalogs::
+* User Catalog::
+@end menu
+
+@html
+<A NAME="LIBRARY_CATALOGS"></A>
+@end html
+@node Library Catalogs, User Catalog, Catalogs, Catalogs
+@appendixsubsec Library Catalogs
+@cindex @file{.idlwave_catalog}
+@cindex Library catalogs
+@cindex @code{idlwave_catalog}
+
+Library catalogs consist of files named @file{.idlwave_catalog} stored
+in directories containing @code{.pro} routine files. They are
+discovered on the IDL search path and loaded automatically when routine
+information is read. Each catalog file documents the routines found in
+that directory --- one catalog per directory. Every catalog has a
+library name associated with it (e.g. @emph{AstroLib}). This name will
+be shown briefly when the catalog is found, and in the routine info of
+routines it documents.
+
+Many popular libraries of routines are shipped with IDLWAVE catalog
+files by default, and so will be automatically discovered. Library
+catalogs are scanned externally to Emacs using a tool provided with
+IDLWAVE. Each catalog can be re-scanned independently of any other.
+Catalogs can easily be made available system-wide with a common source
+repository, providing uniform routine information, and lifting the
+burden of scanning from the user (who may not even know they're using a
+scanned catalog). Since all catalogs are independent, they can be
+re-scanned automatically to gather updates, e.g. in a @file{cron} job.
+Scanning is much faster than with the built-in user catalog method. One
+minor disadvantage: the entire IDL search path is scanned for catalog
+files every time IDLWAVE starts up, which might be slow if accessing IDL
+routines over a slow network.
+
+A Perl tool to create library catalogs is distributed with IDLWAVE:
+@code{idlwave_catalog}. It can be called quite simply:
+@example
+idlwave_catalog MyLib
+@end example
+
+@noindent This will scan all directories recursively beneath the current and
+populate them with @file{.idlwave_catalog} files, tagging the routines
+found there with the name library ``MyLib''. The full usage
+information:
+
+@example
+Usage: idlwave_catalog [-l] [-v] [-d] [-s] [-f] [-h] libname
+ libname - Unique name of the catalog (4 or more alphanumeric
+ characters).
+ -l - Scan local directory only, otherwise recursively
+ catalog all directories at or beneath this one.
+ -v - Print verbose information.
+ -d - Instead of scanning, delete all .idlwave_catalog files
+ here or below.
+ -s - Be silent.
+ -f - Force overwriting any catalogs found with a different
+ library name.
+ -h - Print this usage.
+@end example
+
+To re-load the library catalogs on the IDL path, force a system routine
+info update using a single prefix to @code{idlwave-update-routine-info}:
+@kbd{C-u C-c C-i}.
+
+@defopt idlwave-use-library-catalogs (@code{t})
+Whether to search for and load library catalogs. Disable if load
+performance is a problem and/or the catalogs are not needed.
+@end defopt
+
+@node User Catalog, , Library Catalogs, Catalogs
+@appendixsubsec User Catalog
+@cindex User catalog
+@cindex IDL library routine info
+@cindex Windows
+@cindex MacOS
+@cindex IDL variable @code{!DIR}
+@cindex @code{!DIR}, IDL variable
+
+The user catalog is the old routine catalog system. It is produced
+within Emacs, and stored in a single file in the user's home directory
+(@file{.idlwave/idlusercat.el} by default). Although library catalogs
+are more flexible, there may be reasons to prefer a user catalog
+instead, including:
+
+@itemize @bullet
+@item The scan is internal to Emacs, so you don't need a working Perl
+installation, as you do for library catalogs.
+@item Can be used to scan directories for which the user has no write
+privileges.
+@item Easy widget-based path selection.
+@end itemize
+
+However, no routine info is available in the user catalog by default;
+the user must actively complete a scan. In addition, this type of
+catalog is all or nothing: if a single routine changes, the entire
+catalog must be rescanned to update it. Creating the user catalog is
+also much slower than scanning library catalogs.
+
+You can scan any of the directories on the currently known path. Under
+Windows and MacOS (not OSX), you need to specify the IDL search path in
+the variable @code{idlwave-library-path}, and the location of the IDL
+directory (the value of the @code{!DIR} system variable) in the variable
+@code{idlwave-system-directory}, like this@footnote{The initial @samp{+}
+leads to recursive expansion of the path, just like in IDL}:
+
+@lisp
+(setq idlwave-library-path
+ '("+c:/RSI/IDL56/lib/" "+c:/user/me/idllibs"))
+(setq idlwave-system-directory "c:/RSI/IDL56/")
+@end lisp
+
+@noindent Under GNU/Linux and UNIX, these values will be automatically
+gathered from the IDLWAVE shell, if run.
+
+The command @kbd{M-x idlwave-create-user-catalog-file} (or the menu item
+@samp{IDLWAVE->Routine Info->Select Catalog Directories}) can then be
+used to create a user catalog. It brings up a widget in which you can
+select some or all directories on the search path. Directories which
+already contain a library catalog are marked with @samp{[LIB]}, and need
+not be scanned (although there is no harm if you do so, other than the
+additional memory used for the duplication).
+
+After selecting directories, click on the @w{@samp{[Scan & Save]}}
+button in the widget to scan all files in the selected directories and
+write out the resulting routine information. In order to update the
+library information using the directory selection, call the command
+@code{idlwave-update-routine-info} with a double prefix argument:
+@w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously
+selected directories, write an updated version of the user catalog file
+and rebuild IDLWAVE's internal lists. If you give three prefix
+arguments @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a
+background job@footnote{Unix systems only, I think.}. You can continue
+to work, and the library catalog will be re-read when it is ready. If
+you find you need to update the user catalog often, you should consider
+building a library catalog for your routines instead (@pxref{Library
+Catalogs}).
+
+@defopt idlwave-special-lib-alist
+Alist of regular expressions matching special library directories for
+labeling in routine-info display.
+@end defopt
+
+@node Load-Path Shadows, Documentation Scan, Catalogs, Sources of Routine Info
+@appendixsec Load-Path Shadows
+@cindex Load-path shadows
+@cindex Shadows, load-path
+@cindex Duplicate routines
+@cindex Multiply defined routines
+@cindex Routine definitions, multiple
+@cindex Application, testing for shadowing
+@cindex Buffer, testing for shadowing
+
+IDLWAVE can compile a list of routines which are (re-)defined in more
+than one file. Since one definition will hide (shadow) the others
+depending on which file is compiled first, such multiple definitions are
+called "load-path shadows". IDLWAVE has several routines to scan for
+load path shadows. The output is placed into the special buffer
+@file{*Shadows*}. The format of the output is identical to the source
+section of the routine info buffer (@pxref{Routine Info}). The
+different definitions of a routine are ordered by @emph{likelihood of
+use}. So the first entry will be most likely the one you'll get if an
+unsuspecting command uses that routine. Before listing shadows, you
+should make sure that routine info is up-to-date by pressing @kbd{C-c
+C-i}. Here are the different routines (also available in the Menu
+@samp{IDLWAVE->Routine Info}):
+
+@table @asis
+@item @kbd{M-x idlwave-list-buffer-load-path-shadows}
+This commands checks the names of all routines defined in the current
+buffer for shadowing conflicts with other routines accessible to
+IDLWAVE. The command also has a key binding: @kbd{C-c C-b}
+@item @kbd{M-x idlwave-list-shell-load-path-shadows}.
+Checks all routines compiled under the shell for shadowing. This is
+very useful when you have written a complete application. Just compile
+the application, use @code{RESOLVE_ALL} to compile any routines used by
+your code, update the routine info inside IDLWAVE with @kbd{C-c C-i} and
+then check for shadowing.
+@item @kbd{M-x idlwave-list-all-load-path-shadows}
+This command checks all routines accessible to IDLWAVE for conflicts.
+@end table
+
+For these commands to work fully you need to scan the entire load path
+in either a user or library catalog. Also, IDLWAVE should be able to
+distinguish between the system library files (normally installed in
+@file{/usr/local/rsi/idl/lib}) and any site specific or user specific
+files. Therefore, such local files should not be installed inside the
+@file{lib} directory of the IDL directory. This is also advisable for
+many other reasons.
+
+@cindex Windows
+@cindex MacOS
+@cindex IDL variable @code{!DIR}
+@cindex @code{!DIR}, IDL variable
+Users of Windows and MacOS (not X) also must set the variable
+@code{idlwave-system-directory} to the value of the @code{!DIR} system
+variable in IDL. IDLWAVE appends @file{lib} to the value of this
+variable and assumes that all files found on that path are system
+routines.
+
+Another way to find out if a specific routine has multiple definitions
+on the load path is routine info display (@pxref{Routine Info}).
+
+@node Documentation Scan, , Load-Path Shadows, Sources of Routine Info
+@appendixsec Documentation Scan
+@cindex @file{get_html_rinfo}
+@cindex @file{idlw-rinfo.el}
+@cindex Scanning the documentation
+@cindex Perl program, to create @file{idlw-rinfo.el}
+
+@strong{Starting with version 6.2, IDL is distributed directly with HTML
+online help, and an XML-based catalog of routine information}. This
+makes scanning the manuals with the tool @file{get_html_rinfo}, and the
+@file{idlw-rinfo.el} file it produced, as described here, entirely
+unnecessary. The information is left here for users wishing to produce
+a catalog of older IDL versions' help.
+
+
+IDLWAVE derives its knowledge about system routines from the IDL
+manuals. The file @file{idlw-rinfo.el} contains the routine information
+for the IDL system routines, and links to relevant sections of the HTML
+documentation. The Online Help feature of IDLWAVE requires HTML
+versions of the IDL manuals to be available; the HTML documentation is
+not distributed with IDLWAVE by default, but must be downloaded
+separately.
+
+The HTML files and related images can be produced from the
+@file{idl.chm} HTMLHelp file distributed with IDL using the free
+Microsoft HTML Help Workshop. If you are lucky, the maintainer of
+IDLWAVE will always have access to the newest version of IDL and provide
+updates. The IDLWAVE distribution also contains the Perl program
+@file{get_html_rinfo} which constructs the @file{idlw-rinfo.el} file by
+scanning the HTML documents produced from the IDL documentation.
+Instructions on how to use @file{get_html_rinfo} are in the program
+itself.
+
+@node HTML Help Browser Tips, Configuration Examples, Sources of Routine Info, Top
+@appendix HTML Help Browser Tips
+@cindex Browser Tips
+
+There are a wide variety of possible browsers to use for displaying
+the online HTML help available with IDLWAVE (starting with version
+5.0). Since IDL v6.2, a single cross-platform HTML help browser, the
+@emph{IDL Assistant} is distributed with IDL. If this help browser is
+available, it is the preferred choice, and the default. The variable
+@code{idlwave-help-use-assistant}, enabled by default, controls
+whether this help browser is used. If you use the IDL Assistant, the
+tips here are not relevant.
+
+Since IDLWAVE runs on a many different system types, a single browser
+configuration is not possible, but choices abound. On many systems,
+the default browser configured in @code{browse-url-browser-function},
+and hence inherited by default by
+@code{idlwave-help-browser-function}, is Netscape. Unfortunately, the
+HTML manuals decompiled from the original source contain formatting
+structures which Netscape 4.x does not handle well, though they are
+still readable. A much better choice is Mozilla, or one of the
+Mozilla-derived browsers such as
+@uref{http://galeon.sourceforge.net/,Galeon} (GNU/Linux),
+@uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or
+@uref{http://www.mozilla.org/projects/firebird/,Firebird} (all
+platforms). Newer versions of Emacs provide a browser-function choice
+@code{browse-url-gnome-moz} which uses the Gnome-configured browser.
+
+Note that the HTML files decompiled from the help sources contain
+specific references to the @samp{Symbol} font, which by default is not
+permitted in normal encodings (it's invalid, technically). Though it
+only impacts a few symbols, you can trick Mozilla-based browsers into
+recognizing @samp{Symbol} by following the directions
+@uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}. With
+this fix in place, HTML help pages look almost identical to their PDF
+equivalents (yet can be bookmarked, browsed as history, searched,
+etc.).
+
+@noindent Individual platform recommendations:
+
+@itemize @bullet
+@item Unix/MacOSX: The @uref{http://www.w3m.org,@code{w3m}} browser
+and its associated
+@uref{http://emacs-w3m.namazu.org/,@code{emacs-w3m}} emacs mode
+provide in-buffer browsing with image display, and excellent speed and
+formatting. Both the Emacs mode and the browser itself must be
+downloaded separately. To use this browser, include
+
+@lisp
+(setq idlwave-help-browser-function 'w3m-browse-url)
+@end lisp
+
+in your @file{.emacs}. Setting a few other nice @code{w3m} options
+cuts down on screen clutter:
+
+@lisp
+(setq w3m-use-tab nil
+ w3m-use-header-line nil
+ w3m-use-toolbar nil)
+@end lisp
+
+If you use a dedicated frame for help, you might want to add the
+following, to get consistent behavior with the @kbd{q} key:
+
+@lisp
+;; Close my help window when w3m closes.
+(defadvice w3m-close-window (after idlwave-close activate)
+ (if (boundp 'idlwave-help-frame)
+ (idlwave-help-quit)))
+@end lisp
+
+Note that you can open the file in an external browser from within
+@code{w3m} using @kbd{M}.
+@end itemize
+
+@node Configuration Examples, Windows and MacOS, HTML Help Browser Tips, Top
+@appendix Configuration Examples
+@cindex Configuration examples
+@cindex Example configuration
+@cindex @file{.emacs}
+@cindex Default settings, of options
+@cindex Interview, with the maintainer
+
+@noindent
+@b{Question:} You have all these complicated configuration options in
+your package, but which ones do @emph{you} as the maintainer actually
+set in your own configuration?
+
+@noindent
+@b{Answer:} Not many, beyond custom key bindings. I set most defaults
+the way that seems best. However, the default settings do not turn on
+features which:
+
+@itemize @minus
+@item
+are not self-evident (i.e. too magic) when used by an unsuspecting user.
+@item
+are too intrusive.
+@item
+will not work properly on all Emacs installations.
+@item
+break with widely used standards.
+@item
+use function or other non-standard keys.
+@item
+are purely personal customizations, like additional key bindings, and
+library names.
+@end itemize
+
+@noindent To see what I mean, here is the @emph{entire} configuration
+the old maintainer had in his @file{.emacs}:
+
+@lisp
+(setq idlwave-shell-debug-modifiers '(control shift)
+ idlwave-store-inquired-class t
+ idlwave-shell-automatic-start t
+ idlwave-main-block-indent 2
+ idlwave-init-rinfo-when-idle-after 2
+ idlwave-help-dir "~/lib/emacs/idlwave"
+ idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib")
+ ("/jhuapl/" . "JHUAPL-Lib")
+ ("/dominik/lib/idl/" . "MyLib")))
+@end lisp
+
+However, if you are an Emacs power-user and want IDLWAVE to work
+completely differently, you can change almost every aspect of it. Here
+is an example of a much more extensive configuration of IDLWAVE. The
+user is King!
+
+@example
+;;; Settings for IDLWAVE mode
+
+(setq idlwave-block-indent 3) ; Indentation settings
+(setq idlwave-main-block-indent 3)
+(setq idlwave-end-offset -3)
+(setq idlwave-continuation-indent 1)
+(setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;"
+ ; anchored at start of line.
+(setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,>
+(setq idlwave-pad-keyword nil) ; Remove spaces for keyword '='
+(setq idlwave-expand-generic-end t) ; convert END to ENDIF etc...
+(setq idlwave-reserved-word-upcase t) ; Make reserved words upper case
+ ; (with abbrevs only)
+(setq idlwave-abbrev-change-case nil) ; Don't force case of expansions
+(setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill
+(setq idlwave-show-block nil) ; Turn off blinking to begin
+(setq idlwave-abbrev-move t) ; Allow abbrevs to move point
+(setq idlwave-query-class '((method-default . nil) ; No query for method
+ (keyword-default . nil); or keyword completion
+ ("INIT" . t) ; except for these
+ ("CLEANUP" . t)
+ ("SETPROPERTY" .t)
+ ("GETPROPERTY" .t)))
+
+;; Using w3m for help (must install w3m and emacs-w3m)
+(autoload 'w3m-browse-url "w3m" "Interface for w3m on Emacs." t)
+(setq idlwave-help-browser-function 'w3m-browse-url
+ w3m-use-tab nil ; no tabs, location line, or toolbar
+ w3m-use-header-line nil
+ w3m-use-toolbar nil)
+
+;; Close my help window or frame when w3m closes with `q'
+(defadvice w3m-close-window (after idlwave-close activate)
+ (if (boundp 'idlwave-help-frame)
+ (idlwave-help-quit)))
+
+;; Some setting can only be done from a mode hook. Here is an example:
+(add-hook 'idlwave-mode-hook
+ (lambda ()
+ (setq case-fold-search nil) ; Make searches case sensitive
+ ;; Run other functions here
+ (font-lock-mode 1) ; Turn on font-lock mode
+ (idlwave-auto-fill-mode 0) ; Turn off auto filling
+ (setq idlwave-help-browser-function 'browse-url-w3)
+
+ ;; Pad with 1 space (if -n is used then make the
+ ;; padding a minimum of n spaces.) The defaults use -1
+ ;; instead of 1.
+ (idlwave-action-and-binding "=" '(idlwave-expand-equal 1 1))
+ (idlwave-action-and-binding "<" '(idlwave-surround 1 1))
+ (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-)))
+ (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
+
+ ;; Only pad after comma and with exactly 1 space
+ (idlwave-action-and-binding "," '(idlwave-surround nil 1))
+ (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
+
+ ;; Pad only after `->', remove any space before the arrow
+ (idlwave-action-and-binding "->" '(idlwave-surround 0 -1 nil 2))
+
+ ;; Set some personal bindings
+ ;; (In this case, makes `,' have the normal self-insert behavior.)
+ (local-set-key "," 'self-insert-command)
+ (local-set-key [f5] 'idlwave-shell-break-here)
+ (local-set-key [f6] 'idlwave-shell-clear-current-bp)
+
+ ;; Create a newline, indenting the original and new line.
+ ;; A similar function that does _not_ reindent the original
+ ;; line is on "\C-j" (The default for emacs programming modes).
+ (local-set-key "\n" 'idlwave-newline)
+ ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference.
+
+ ;; Some personal abbreviations
+ (define-abbrev idlwave-mode-abbrev-table
+ (concat idlwave-abbrev-start-char "wb") "widget_base()"
+ (idlwave-keyword-abbrev 1))
+ (define-abbrev idlwave-mode-abbrev-table
+ (concat idlwave-abbrev-start-char "on") "obj_new()"
+ (idlwave-keyword-abbrev 1))
+ ))
+
+;;; Settings for IDLWAVE SHELL mode
+
+(setq idlwave-shell-overlay-arrow "=>") ; default is ">"
+(setq idlwave-shell-use-dedicated-frame t) ; Make a dedicated frame
+(setq idlwave-shell-prompt-pattern "^WAVE> ") ; default is "^IDL> "
+(setq idlwave-shell-explicit-file-name "wave")
+(setq idlwave-shell-process-name "wave")
+(setq idlwave-shell-use-toolbar nil) ; No toolbar
+
+;; Most shell interaction settings can be done from the shell-mode-hook.
+(add-hook 'idlwave-shell-mode-hook
+ (lambda ()
+ ;; Set up some custom key and mouse examine commands
+ (idlwave-shell-define-key-both [s-down-mouse-2]
+ (idlwave-shell-mouse-examine
+ "print, size(___,/DIMENSIONS)"))
+ (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
+ "print, size(___,/DIMENSIONS)"))
+ (idlwave-shell-define-key-both [f10] (idlwave-shell-examine
+ "print,size(___,/TNAME)"))
+ (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
+ "help,___,/STRUCTURE"))))
+@end example
+
+@html
+<A NAME="WIN_MAC"></A>
+@end html
+@node Windows and MacOS, Troubleshooting, Configuration Examples, Top
+@appendix Windows and MacOS
+@cindex Windows
+@cindex MacOS
+@cindex MacOSX
+
+IDLWAVE was developed on a UNIX system. However, thanks to the
+portability of Emacs, much of IDLWAVE does also work under different
+operating systems like Windows (with NTEmacs or NTXEmacs) or MacOS.
+
+The only real problem is that there is no command-line version of IDL
+for Windows or MacOS(<=9) with which IDLWAVE can interact. As a
+result, the IDLWAVE Shell does not work and you have to rely on IDLDE
+to run and debug your programs. However, editing IDL source files
+with Emacs/IDLWAVE works with all bells and whistles, including
+routine info, completion and fast online help. Only a small amount of
+additional information must be specified in your @file{.emacs} file:
+the path names which, on a UNIX system, are automatically gathered by
+talking to the IDL program.
+
+Here is an example of the additional configuration needed for a Windows
+system. I am assuming that IDLWAVE has been installed in
+@w{@samp{C:\Program Files\IDLWAVE}} and that IDL is installed in
+@w{@samp{C:\RSI\IDL63}}.
+
+@lisp
+;; location of the lisp files (only needed if IDLWAVE is not part of
+;; your default X/Emacs installation)
+(setq load-path (cons "c:/program files/IDLWAVE" load-path))
+
+;; The location of the IDL library directories, both standard, and your own.
+;; note that the initial "+" expands the path recursively
+(setq idlwave-library-path
+ '("+c:/RSI/IDL63/lib/" "+c:/path/to/my/idllibs" ))
+
+;; location of the IDL system directory (try "print,!DIR")
+(setq idlwave-system-directory "c:/RSI/IDL63/")
+
+@end lisp
+
+@noindent Furthermore, Windows sometimes tries to outsmart you --- make
+sure you check the following things:
+
+@itemize @bullet
+@item When you download the IDLWAVE distribution, make sure you save the
+file under the names @file{idlwave.tar.gz}.
+@item M-TAB switches among running programs --- use Esc-TAB
+instead.
+@item Other issues as yet unnamed...
+@end itemize
+
+Windows users who'd like to make use of IDLWAVE's context-aware HTML
+help can skip the browser and use the HTMLHelp functionality directly.
+@xref{Help with HTML Documentation}.
+
+@html
+<A NAME="TROUBLE"></A>
+@end html
+@node Troubleshooting, GNU Free Documentation License, Windows and MacOS, Top
+@appendix Troubleshooting
+@cindex Troubleshooting
+
+Although IDLWAVE usually installs and works without difficulty, a few
+common problems and their solutions are documented below.
+
+@enumerate
+
+@item @strong{Whenever an IDL error occurs or a breakpoint is hit, I get
+errors or strange behavior when I try to type anything into some of my
+IDLWAVE buffers.}
+
+This is a @emph{feature}, not an error. You're in @emph{Electric
+Debug Mode} (@pxref{Electric Debug Mode}). You should see
+@code{*Debugging*} in the mode-line. The buffer is read-only and all
+debugging and examination commands are available as single keystrokes;
+@kbd{C-?} lists these shortcuts. Use @kbd{q} to quit the mode, and
+customize the variable @code{idlwave-shell-automatic-electric-debug}
+if you prefer not to enter electric debug on breakpoints@dots{} but
+you really should try it before you disable it! You can also
+customize this variable to enter debug mode when errors are
+encountered.
+
+@item @strong{I get errors like @samp{Searching for program: no such
+file or directory, idl} when attempting to start the IDL shell.}
+
+IDLWAVE needs to know where IDL is in order to run it as a process.
+By default, it attempts to invoke it simply as @samp{idl}, which
+presumes such an executable is on your search path. You need to
+ensure @samp{idl} is on your @samp{$PATH}, or specify the full
+pathname to the idl program with the variable
+@code{idlwave-shell-explicit-file-name}. Note that you may need to
+set your shell search path in two places when running Emacs as an Aqua
+application with MacOSX; see the next topic.
+
+@item @strong{IDLWAVE is disregarding my @samp{IDL_PATH} which I set
+under MacOSX}
+
+If you run Emacs directly as an Aqua application, rather than from the
+console shell, the environment is set not from your usual shell
+configuration files (e.g. @file{.cshrc}), but from the file
+@file{~/.MacOSX/environment.plist}. Either include your path settings
+there, or start Emacs and IDLWAVE from the shell.
+
+@item @strong{I get errors like @samp{Symbol's function is void:
+overlayp}}
+
+You don't have the @samp{fsf-compat} package installed, which IDLWAVE
+needs to run under XEmacs. Install it, or find an XEmacs distribution
+which includes it by default.
+
+@item @strong{I'm getting errors like @samp{Symbol's value as variable is void:
+cl-builtin-gethash} on completion or routine info.}
+
+This error arises if you upgraded Emacs from 20.x to 21.x without
+re-installing IDLWAVE. Old Emacs and new Emacs are not byte-compatible
+in compiled lisp files. Presumably, you kept the original .elc files in
+place, and this is the source of the error. If you recompile (or just
+"make; make install") from source, it should resolve this problem.
+Another option is to recompile the @file{idlw*.el} files by hand using
+@kbd{M-x byte-compile-file}.
+
+@item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches
+windows on my desktop.}
+
+Your system is trapping @kbd{M-@key{TAB}} and using it for its own
+nefarious purposes: Emacs never sees the keystrokes. On many Unix
+systems, you can reconfigure your window manager to use another key
+sequence for switching among windows. Another option is to use the
+equivalent sequence @kbd{@key{ESC}-@key{TAB}}.
+
+@item @strong{When stopping at breakpoints or errors, IDLWAVE does not
+seem to highlight the relevant line in the source.}
+
+IDLWAVE scans for error and halt messages and highlights the stop
+location in the correct file. However, if you've changed the system
+variable @samp{!ERROR_STATE.MSG_PREFIX}, it is unable to parse these
+message correctly. Don't do that.
+
+@item @strong{IDLWAVE doesn't work correctly when using ENVI.}
+
+Though IDLWAVE was not written with ENVI in mind, it works just fine
+with it, as long as you update the prompt it's looking for (@samp{IDL>
+} by default). You can do this with the variable
+@code{idlwave-shell-prompt-pattern} (@pxref{Starting the Shell}), e.g.,
+in your @file{.emacs}:
+
+@lisp
+(setq idlwave-shell-prompt-pattern "^\r? ?\\(ENVI\\|IDL\\)> ")
+@end lisp
+
+@item @strong{Attempts to set breakpoints fail: no breakpoint is
+indicated in the IDLWAVE buffer.}
+
+IDL changed its breakpoint reporting format starting with IDLv5.5. The
+first version of IDLWAVE to support the new format is IDLWAVE v4.10. If
+you have an older version and are using IDL >v5.5, you need to upgrade,
+and/or make sure your recent version of IDLWAVE is being found on the
+Emacs load-path (see the next entry). You can list the version being
+used with @kbd{C-h v idlwave-mode-version @key{RET}}.
+
+@item @strong{I installed a new version of IDLWAVE, but the old
+version is still being used} or @strong{IDLWAVE works, but when I
+tried to install the optional modules @file{idlw-roprompt.el} or
+@file{idlw-complete-structtag}, I get errors like @samp{Cannot open
+load file}}.
+
+The problem is that your Emacs is not finding the version of IDLWAVE you
+installed. Many Emacsen come with an older bundled copy of IDLWAVE
+(e.g. v4.7 for Emacs 21.x), which is likely what's being used instead.
+You need to make sure your Emacs @emph{load-path} contains the directory
+where IDLWAVE is installed (@file{/usr/local/share/emacs/site-lisp}, by
+default), @emph{before} Emacs' default search directories. You can
+accomplish this by putting the following in your @file{.emacs}:
+
+@lisp
+(setq load-path (cons "/usr/local/share/emacs/site-lisp" load-path))
+@end lisp
+
+@noindent You can check on your load-path value using @kbd{C-h v
+load-path @key{RET}}, and @kbd{C-h m} in an IDLWAVE buffer should show
+you the version Emacs is using.
+
+@item @strong{IDLWAVE is screwing up the formatting of my @file{.idl} files.}
+
+Actually, this isn't IDLWAVE at all, but @samp{idl-mode}, an unrelated
+programming mode for CORBA's Interface Definition Language (you should
+see @samp{(IDL)}, not @samp{(IDLWAVE)} in the mode-line). One
+solution: don't name your file @file{.idl}, but rather @file{.pro}.
+Another solution: make sure @file{.idl} files load IDLWAVE instead of
+@samp{idl-mode} by adding the following to your @file{.emacs}:
+
+@lisp
+(setcdr (rassoc 'idl-mode auto-mode-alist) 'idlwave-mode)
+@end lisp
+
+@item @strong{The routine info for my local routines is out of date!}
+
+IDLWAVE collects routine info from various locations (@pxref{Routine
+Information Sources}). Routines in files visited in a buffer or
+compiled in the shell should be up to date. For other routines, the
+information is only as current as the most recent scan. If you have a
+rapidly changing set of routines, and you'd like the latest routine
+information to be available for it, one powerful technique is to make
+use of the library catalog tool, @samp{idlwave_catalog}. Simply add a
+line to your @samp{cron} file (@samp{crontab -e} will let you edit this
+on some systems), like this
+
+@example
+45 3 * * 1-5 (cd /path/to/myidllib; /path/to/idlwave_catalog MyLib)
+@end example
+
+@noindent where @samp{MyLib} is the name of your library. This will
+rescan all @file{.pro} files at or below @file{/path/to/myidllib} every
+week night at 3:45am. You can even scan site-wide libraries with this
+method, and the most recent information will be available to all users.
+Since the scanning is very fast, there is very little impact.
+
+@item @strong{All the Greek-font characters in the HTML help are
+displayed as Latin characters!}
+
+Unfortunately, the HTMLHelp files RSI provides attempt to switch to
+@samp{Symbol} font to display Greek characters, which is not really an
+permitted method for doing this in HTML. There is a "workaround" for
+some browsers: @xref{HTML Help Browser Tips}.
+
+@item @strong{In the shell, my long commands are truncated at 256 characters!}
+
+This actually happens when running IDL in an XTerm as well. There are
+a couple of workarounds: @code{define_key,/control,'^d'} (e.g. in
+your @file{$IDL_STARTUP} file) will disable the @samp{EOF} character
+and give you a 512 character limit. You won't be able to use
+@key{C-d} to quit the shell, however. Another possibility is
+@code{!EDIT_INPUT=0}, which gives you an @emph{infinite} limit (OK, a
+memory-bounded limit), but disables the processing of background
+widget events (those with @code{/NO_BLOCK} passed to @code{XManager}).
+
+@item @strong{When I invoke IDL HTML help on a routine, the page which
+is loaded is one page off, e.g. for @code{CONVERT_COORD}, I get
+@code{CONTOUR}.}
+
+You have a mismatch between your help index and the HTML help package
+you downloaded. You need to ensure you download a ``downgrade kit'' if
+you are using anything older than the latest HTML help package. A new
+help package appears with each IDL release (assuming the documentation
+is updated).
+Starting with IDL 6.2, the HTML help and its catalog are
+distributed with IDL, and so should never be inconsistent.
+
+@item @strong{I get errors such as @samp{void-variable
+browse-url-browser-function} or similar when attempting to load IDLWAVE
+under XEmacs.}
+
+You don't have the @samp{browse-url} (or other required) XEmacs package.
+Unlike GNU Emacs, XEmacs distributes many packages separately from the
+main program. IDLWAVE is actually among these, but is not always the
+most up to date. When installing IDLWAVE as an XEmacs package, it
+should prompt you for required additional packages. When installing it
+from source, it won't and you'll get this error. The easiest solution
+is to install all the packages when you install XEmacs (the so-called
+@samp{sumo} bundle). The minimum set of XEmacs packages required by
+IDLWAVE is @samp{fsf-compat, xemacs-base, mail-lib}.
+
+@end enumerate
+
+@node GNU Free Documentation License, Index, Troubleshooting, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index, , GNU Free Documentation License, Top
+@unnumbered Index
+@printindex cp
+
+@bye
+
+@ignore
+ arch-tag: f1d73958-1423-4127-b8aa-f7b953d64492
+@end ignore
--- /dev/null
+\input texinfo.tex @c -*-texinfo-*-
+@c We must \input texinfo.tex instead of texinfo, otherwise make
+@c distcheck in the Texinfo distribution fails, because the texinfo Info
+@c file is made first, and texi2dvi must include . first in the path.
+@comment %**start of header
+@setfilename info.info
+@settitle Info
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex ky cp
+@comment %**end of header
+
+@copying
+This file describes how to use Info, the on-line, menu-driven GNU
+documentation system.
+
+Copyright @copyright{} 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001,
+2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and
+modify this GNU Manual, like GNU software. Buying copies from GNU
+Press supports the FSF in developing GNU and promoting software
+freedom.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Texinfo documentation system
+@direntry
+* Info: (info). How to use the documentation browsing system.
+@end direntry
+
+@titlepage
+@title Info
+@subtitle The online, hyper-text GNU documentation system
+@author Brian Fox
+@author and the GNU Texinfo community
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Info: An Introduction
+
+The GNU Project distributes most of its on-line manuals in the
+@dfn{Info format}, which you read using an @dfn{Info reader}. You are
+probably using an Info reader to read this now.
+
+There are two primary Info readers: @code{info}, a stand-alone program
+designed just to read Info files, and the @code{info} package in GNU
+Emacs, a general-purpose editor. At present, only the Emacs reader
+supports using a mouse.
+
+@ifinfo
+If you are new to the Info reader and want to learn how to use it,
+type the command @kbd{h} now. It brings you to a programmed
+instruction sequence.
+
+To read about advanced Info commands, type @kbd{n} twice. This
+brings you to @cite{Advanced Info Commands}, skipping over the `Getting
+Started' chapter.
+@end ifinfo
+@end ifnottex
+
+@menu
+* Getting Started:: Getting started using an Info reader.
+* Advanced:: Advanced Info commands.
+* Expert Info:: Info commands for experts.
+* Index:: An index of topics, commands, and variables.
+@end menu
+
+@node Getting Started, Advanced, Top, Top
+@comment node-name, next, previous, up
+@chapter Getting Started
+
+This first part of this Info manual describes how to get around inside
+of Info. The second part of the manual describes various advanced
+Info commands. The third part briefly explains how to generate Info
+files from Texinfo files, and describes how to write an Info file
+by hand.
+
+@ifnotinfo
+This manual is primarily designed for browsing with an Info reader
+program on a computer, so that you can try Info commands while reading
+about them. Reading it on paper or with an HTML browser is less
+effective, since you must take it on faith that the commands described
+really do what the manual says. By all means go through this manual
+now that you have it; but please try going through the on-line version
+as well.
+
+@cindex Info reader, how to invoke
+@cindex entering Info
+There are two ways of looking at the online version of this manual:
+
+@enumerate
+@item
+Type @code{info} at your shell's command line. This approach uses a
+stand-alone program designed just to read Info files.
+
+@item
+Type @code{emacs} at the command line; then type @kbd{C-h i}
+(@kbd{Control-h}, followed by @kbd{i}). This approach uses the Info
+mode of the Emacs editor.
+@end enumerate
+
+In either case, then type @kbd{mInfo} (just the letters), followed by
+@key{RET}---the ``Return'' or ``Enter'' key. At this point, you should
+be ready to follow the instructions in this manual as you read them on
+the screen.
+@c FIXME! (pesch@cygnus.com, 14 dec 1992)
+@c Is it worth worrying about what-if the beginner goes to somebody
+@c else's Emacs session, which already has an Info running in the middle
+@c of something---in which case these simple instructions won't work?
+@end ifnotinfo
+
+@menu
+* Help-Small-Screen:: Starting Info on a Small Screen.
+* Help:: How to use Info.
+* Help-P:: Returning to the Previous node.
+* Help-^L:: The Space, DEL, B and ^L commands.
+* Help-Inv:: Invisible text in Emacs Info.
+* Help-M:: Menus.
+* Help-Xref:: Following cross-references.
+* Help-Int:: Some intermediate Info commands.
+* Help-Q:: Quitting Info.
+@end menu
+
+@node Help-Small-Screen
+@section Starting Info on a Small Screen
+
+@ifnotinfo
+(In Info, you only see this section if your terminal has a small
+number of lines; most readers pass by it without seeing it.)
+@end ifnotinfo
+
+@cindex small screen, moving around
+Since your terminal has a relatively small number of lines on its
+screen, it is necessary to give you special advice at the beginning.
+
+If the entire text you are looking at fits on the screen, the text
+@samp{All} will be displayed at the bottom of the screen. In the
+stand-alone Info reader, it is displayed at the bottom right corner of
+the screen; in Emacs, it is displayed on the modeline. If you see the
+text @samp{Top} instead, it means that there is more text below that
+does not fit. To move forward through the text and see another screen
+full, press @key{SPC}, the Space bar. To move back up, press the key
+labeled @samp{Backspace} or @samp{DEL} (on some keyboards, this key
+might be labeled @samp{Delete}).
+
+@ifinfo
+Here are 40 lines of junk, so you can try @key{SPC} and @key{DEL} and
+see what they do. At the end are instructions of what you should do
+next.
+
+@format
+This is line 20
+This is line 21
+This is line 22
+This is line 23
+This is line 24
+This is line 25
+This is line 26
+This is line 27
+This is line 28
+This is line 29
+This is line 30
+This is line 31
+This is line 32
+This is line 33
+This is line 34
+This is line 35
+This is line 36
+This is line 37
+This is line 38
+This is line 39
+This is line 40
+This is line 41
+This is line 42
+This is line 43
+This is line 44
+This is line 45
+This is line 46
+This is line 47
+This is line 48
+This is line 49
+This is line 50
+This is line 51
+This is line 52
+This is line 53
+This is line 54
+This is line 55
+This is line 56
+This is line 57
+This is line 58
+This is line 59
+@end format
+
+If you have managed to get here, go back to the beginning with
+@kbd{DEL} (or @key{BACKSPACE}), and come back here again, then you
+understand the about the @samp{Space} and @samp{Backspace} keys. So
+now type an @kbd{n}---just one character; don't type the quotes and
+don't type the Return key afterward---to get to the normal start of
+the course.
+@end ifinfo
+
+@node Help, Help-P, Help-Small-Screen, Getting Started
+@comment node-name, next, previous, up
+@section How to use Info
+
+You are talking to the program Info, for reading documentation.
+
+ There are two ways to use Info: from within Emacs or as a
+stand-alone reader that you can invoke from a shell using the command
+@command{info}.
+
+@cindex node, in Info documents
+ Right now you are looking at one @dfn{Node} of Information.
+A node contains text describing a specific topic at a specific
+level of detail. This node's topic is ``how to use Info''. The mode
+line says that this is node @samp{Help} in the file @file{info}.
+
+@cindex header of Info node
+ The top line of a node is its @dfn{header}. This node's header
+(look at it now) says that the @samp{Next} node after this one is the
+node called @samp{Help-P}. An advanced Info command lets you go to
+any node whose name you know. In the stand-alone Info reader program,
+the header line shows the names of this node and the Info file as
+well. In Emacs, the header line is displayed with a special typeface,
+and remains at the top of the window all the time even if you scroll
+through the node.
+
+ Besides a @samp{Next}, a node can have a @samp{Previous} link, or an
+@samp{Up} link, or both. As you can see, this node has all of these
+links.
+
+@kindex n @r{(Info mode)}
+ Now it is time to move on to the @samp{Next} node, named @samp{Help-P}.
+
+@format
+>> Type @kbd{n} to move there. Type just one character;
+ do not type the quotes and do not type a @key{RET} afterward.
+@end format
+
+@noindent
+@samp{>>} in the margin means it is really time to try a command.
+
+@format
+>> If you are in Emacs and have a mouse, and if you already practiced
+ typing @kbd{n} to get to the next node, click now with the left
+ mouse button on the @samp{Next} link to do the same ``the mouse way''.
+@end format
+
+@node Help-P, Help-^L, Help, Getting Started
+@comment node-name, next, previous, up
+@section Returning to the Previous node
+
+@kindex p @r{(Info mode)}
+This node is called @samp{Help-P}. The @samp{Previous} node, as you see,
+is @samp{Help}, which is the one you just came from using the @kbd{n}
+command. Another @kbd{n} command now would take you to the next
+node, @samp{Help-^L}.
+
+@format
+>> But do not type @kbd{n} yet. First, try the @kbd{p} command, or
+ (in Emacs) click on the @samp{Prev} link. That takes you to
+ the @samp{Previous} node. Then use @kbd{n} to return here.
+@end format
+
+ If you read this in Emacs, you will see an @samp{Info} item in the
+menu bar, close to its right edge. Clicking the mouse on the
+@samp{Info} menu-bar item opens a menu of commands which include
+@samp{Next} and @samp{Previous} (and also some others which you didn't yet
+learn about).
+
+ This all probably seems insultingly simple so far, but @emph{please
+don't} start skimming. Things will get complicated soon enough!
+Also, please do not try a new command until you are told it is time
+to. You could make Info skip past an important warning that was
+coming up.
+
+@format
+>> Now do an @kbd{n}, or (in Emacs) click the middle mouse button on
+ the @samp{Next} link, to get to the node @samp{Help-^L} and learn more.
+@end format
+
+@node Help-^L, Help-Inv, Help-P, Getting Started
+@comment node-name, next, previous, up
+@section The Space, DEL, B and ^L commands
+
+ This node's mode line tells you that you are now at node
+@samp{Help-^L}, and the header line tells you that @kbd{p} would get
+you back to @samp{Help-P}. The node's title is highlighted and may be
+underlined as well; it says what the node is about.
+
+ This is a big node and it does not all fit on your display screen.
+You can tell that there is more that is not visible because you
+can see the text @samp{Top} rather than @samp{All} near the bottom of
+the screen.
+
+@kindex SPC @r{(Info mode)}
+@kindex DEL @r{(Info mode)}
+@kindex BACKSPACE @r{(Info mode)}
+@findex Info-scroll-up
+@findex Info-scroll-down
+ The @key{SPC}, @key{BACKSPACE} (or @key{DEL})@footnote{The key which
+we call ``Backspace or DEL'' in this manual is labeled differently on
+different keyboards. Look for a key which is a little ways above the
+@key{ENTER} or @key{RET} key and which you normally use outside Emacs
+to erase the character before the cursor, i.e.@: the character you
+typed last. It might be labeled @samp{Backspace} or @samp{<-} or
+@samp{DEL}, or sometimes @samp{Delete}.} and @kbd{b} commands exist to
+allow you to ``move around'' in a node that does not all fit on the
+screen at once. @key{SPC} moves forward, to show what was below the
+bottom of the screen. @key{DEL} or @key{BACKSPACE} moves backward, to
+show what was above the top of the screen (there is not anything above
+the top until you have typed some spaces).
+
+@format
+>> Now try typing a @key{SPC} (afterward, type a @key{BACKSPACE} to
+ return here).
+@end format
+
+ When you type the @key{SPC}, the two lines that were at the bottom of
+the screen appear at the top, followed by more lines. @key{DEL} or
+@key{BACKSPACE} takes the two lines from the top and moves them to the
+bottom, @emph{usually}, but if there are not a full screen's worth of
+lines above them they may not make it all the way to the bottom.
+
+ If you are reading this in Emacs, note that the header line is
+always visible, never scrolling off the display. That way, you can
+always see the @samp{Next}, @samp{Prev}, and @samp{Up} links, and you
+can conveniently go to one of these links at any time by
+clicking the middle mouse button on the link.
+
+@cindex reading Info documents top to bottom
+@cindex Info documents as tutorials
+ @key{SPC} and @key{DEL} not only move forward and backward through
+the current node. They also move between nodes. @key{SPC} at the end
+of a node moves to the next node; @key{DEL} (or @key{BACKSPACE}) at
+the beginning of a node moves to the previous node. In effect, these
+commands scroll through all the nodes in an Info file as a single
+logical sequence. You can read an entire manual top to bottom by just
+typing @key{SPC}, and move backward through the entire manual from
+bottom to top by typing @key{DEL} (or @key{BACKSPACE}).
+
+ In this sequence, a node's subnodes appear following their parent.
+If a node has a menu, @key{SPC} takes you into the subnodes listed in
+the menu, one by one. Once you reach the end of a node, and have seen
+all of its subnodes, @key{SPC} takes you to the next node or to the
+parent's next node.
+
+@kindex PAGEUP @r{(Info mode)}
+@kindex PAGEDOWN @r{(Info mode)}
+ Many keyboards nowadays have two scroll keys labeled @samp{PageUp}
+and @samp{PageDown} (or maybe @samp{Prior} and @samp{Next}). If your
+keyboard has these keys, you can use them to move forward and backward
+through the text of one node, like @key{SPC} and @key{BACKSPACE} (or
+@key{DEL}). However, @key{PAGEUP} and @key{PAGEDOWN} keys never
+scroll beyond the beginning or the end of the current node.
+
+@kindex C-l @r{(Info mode)}
+ If your screen is ever garbaged, you can tell Info to display it
+again by typing @kbd{C-l} (@kbd{Control-L}---that is, hold down
+@key{CTRL} and type @kbd{L} or @kbd{l}).
+
+@format
+>> Type @kbd{C-l} now.
+@end format
+
+@kindex b @r{(Info mode)}
+ To move back to the beginning of the node you are on, you can type
+the @key{BACKSPACE} key (or @key{DEL}) many times. You can also type
+@kbd{b} just once. @kbd{b} stands for ``beginning.''
+
+@format
+>> Try that now. (We have put in enough verbiage to push this past
+ the first screenful, but screens are so big nowadays that perhaps it
+ isn't enough. You may need to shrink your Emacs or Info window.)
+ Then come back, by typing @key{SPC} one or more times.
+@end format
+
+@kindex ? @r{(Info mode)}
+@findex Info-summary
+ You have just learned a considerable number of commands. If you
+want to use one but have trouble remembering which, you should type
+@kbd{?}, which displays a brief list of commands. When you are
+finished looking at the list, make it go away by typing @key{SPC}
+repeatedly.
+
+@format
+>> Type a @key{?} now. Press @key{SPC} to see consecutive screenfuls of
+ the list until finished. Then type @key{SPC} several times. If
+ you are using Emacs, the help will then go away automatically.
+@end format
+
+ (If you are using the stand-alone Info reader, type @kbd{C-x 0} to
+return here, that is---press and hold @key{CTRL}, type an @kbd{x},
+then release @key{CTRL} and @kbd{x}, and press @kbd{0}; that's a zero,
+not the letter ``o''.)
+
+ From now on, you will encounter large nodes without warning, and
+will be expected to know how to use @key{SPC} and @key{BACKSPACE} to
+move around in them without being told. Since not all terminals have
+the same size screen, it would be impossible to warn you anyway.
+
+@format
+>> Now type @kbd{n}, or click the middle mouse button on the @samp{Next} link,
+ to visit the next node.
+@end format
+
+@node Help-Inv, Help-M, Help-^L, Getting Started
+@comment node-name, next, previous, up
+@section Invisible text in Emacs Info
+
+ Before discussing menus, we need to make some remarks that are only
+relevant to users reading Info using Emacs. Users of the stand-alone
+version can skip this node by typing @kbd{]} now.
+
+@cindex invisible text in Emacs
+ In Emacs, certain text that appears in the stand-alone version is
+normally hidden, technically because it has the @samp{invisibility}
+property. Invisible text is really a part of the text. It becomes
+visible (by default) after killing and yanking, it appears in printed
+output, it gets saved to file just like any other text, and so on.
+Thus it is useful to know it is there.
+
+@findex visible-mode
+You can make invisible text visible by using the command @kbd{M-x
+visible-mode}. Visible mode is a minor mode, so using the command a
+second time will make the text invisible again. Watch the effects of
+the command on the ``menu'' below and the top line of this node.
+
+If you prefer to @emph{always} see the invisible text, you can set
+@code{Info-hide-note-references} to @code{nil}. Enabling Visible mode
+permanently is not a real alternative, because Emacs Info also uses
+(although less extensively) another text property that can change the
+text being displayed, the @samp{display} property. Only the
+invisibility property is affected by Visible mode. When, in this
+tutorial, we refer to the @samp{Emacs} behavior, we mean the
+@emph{default} Emacs behavior.
+
+Now type @kbd{]}, to learn about the @kbd{]} and @kbd{[} commands.
+
+@menu
+* ]: Help-]. Node telling about ].
+* stuff: Help-]. Same node.
+* Help-]:: Yet again, same node.
+@end menu
+
+@node Help-], , , Help-Inv
+@subsection The @kbd{]} and @kbd{[} commands
+
+If you type @kbd{n} now, you get an error message saying that this
+node has no next node. Similarly, if you type @kbd{p}, the error
+message tells you that there is no previous node. (The exact message
+depends on the Info reader you use.) This is because @kbd{n} and
+@kbd{p} carry you to the next and previous node @emph{at the same
+level}. The present node is contained in a menu (see next) of the
+node you came from, and hence is considered to be at a lower level.
+It is the only node in the previous node's menu (even though it was
+listed three times). Hence it has no next or previous node that
+@kbd{n} or @kbd{p} could move to.
+
+If you systematically move through a manual by typing @kbd{n}, you run
+the risk of skipping many nodes. You do not run this risk if you
+systematically use @kbd{@key{SPC}}, because, when you scroll to the
+bottom of a node and type another @kbd{@key{SPC}}, then this carries
+you to the following node in the manual @emph{regardless of level}.
+If you immediately want to go to that node, without having to scroll
+to the bottom of the screen first, you can type @kbd{]}.
+
+Similarly, @kbd{@key{BACKSPACE}} carries you to the preceding node
+regardless of level, after you scrolled to the beginning of the
+present node. If you want to go to the preceding node immediately,
+you can type @kbd{[}.
+
+For instance, typing this sequence will come back here in three steps:
+@kbd{[ n [}. To do the same backward, type @kbd{] p ]}.
+
+Now type @kbd{]} to go to the next node and learn about menus.
+
+@node Help-M, Help-Xref, Help-Inv, Getting Started
+@comment node-name, next, previous, up
+@section Menus and the @kbd{m} command
+
+@cindex menus in an Info document
+@cindex Info menus
+ With only the @kbd{n} (next), @kbd{p} (previous), @kbd{@key{SPC}},
+@kbd{@key{BACKSPACE}}, @kbd{]} and @kbd{[} commands for moving between
+nodes, nodes are restricted to a linear sequence. Menus allow a
+branching structure. A menu is a list of other nodes you can move to.
+It is actually just part of the text of the node formatted specially
+so that Info can interpret it. The beginning of a menu is always
+identified by a line which starts with @w{@samp{* Menu:}}. A node
+contains a menu if and only if it has a line in it which starts that
+way. The only menu you can use at any moment is the one in the node
+you are in. To use a menu in any other node, you must move to that
+node first.
+
+ After the start of the menu, each line that starts with a @samp{*}
+identifies one subtopic. The line usually contains a brief name for
+the subtopic (followed by a @samp{:}, normally hidden in Emacs), the
+name of the node that talks about that subtopic (again, normally
+hidden in Emacs), and optionally some further description of the
+subtopic. Lines in the menu that do not start with a @samp{*} have no
+special meaning---they are only for the human reader's benefit and do
+not define additional subtopics. Here is an example:
+
+@example
+* Foo: Node about FOO. This tells about FOO.
+@end example
+
+The subtopic name is Foo, and the node describing it is @samp{Node
+about FOO}. The rest of the line is just for the reader's
+Information. [[ But this line is not a real menu item, simply because
+there is no line above it which starts with @w{@samp{* Menu:}}. Also,
+in a real menu item, the @samp{*} would appear at the very start of
+the line. This is why the ``normally hidden'' text in Emacs, namely
+@samp{: Node about FOO.}, is actually visible in this example, even
+when Visible mode is off.]]
+
+ When you use a menu to go to another node (in a way that will be
+described soon), what you specify is the subtopic name, the first
+thing in the menu line. Info uses it to find the menu line, extracts
+the node name from it, and goes to that node. The reason that there
+is both a subtopic name and a node name is that the node name must be
+meaningful to the computer and may therefore have to be ugly looking.
+The subtopic name can be chosen just to be convenient for the user to
+specify. Often the node name is convenient for the user to specify
+and so both it and the subtopic name are the same. There is an
+abbreviation for this:
+
+@example
+* Foo:: This tells about FOO.
+@end example
+
+@noindent
+This means that the subtopic name and node name are the same; they are
+both @samp{Foo}. (The @samp{::} is normally hidden in Emacs.)
+
+@format
+>> Now use @key{SPC} to find the menu in this node, then come back to
+ the front with a @kbd{b} and some @key{SPC}s. As you see, a menu is
+ actually visible in its node. If you cannot find a menu in a node
+ by looking at it, then the node does not have a menu and the
+ @kbd{m} command is not available.
+@end format
+
+If you keep typing @key{SPC} once the menu appears on the screen, it
+will move to another node (the first one in the menu). If that
+happens, type @key{BACKSPACE} to come back.
+
+@kindex m @r{(Info mode)}
+ The command to go to one of the subnodes is @kbd{m}. This is very
+different from the commands you have used: it is a command that
+prompts you for more input.
+
+ The Info commands you know do not need additional input; when you
+type one of them, Info processes it instantly and then is ready for
+another command. The @kbd{m} command is different: it needs to know
+the @dfn{name of the subtopic}. Once you have typed @kbd{m}, Info
+tries to read the subtopic name.
+
+ Now, in the stand-alone Info, look for the line containing many
+dashes near the bottom of the screen. (This is the stand-alone
+equivalent for the mode line in Emacs.) There is one more line
+beneath that one, but usually it is blank. (In Emacs, this is the
+echo area.) When it is blank, Info is ready for a command, such as
+@kbd{n} or @kbd{b} or @key{SPC} or @kbd{m}. If that line contains
+text ending in a colon, it means Info is reading more input for the
+last command. You can't type an Info command then, because Info is
+trying to read input, not commands. You must either give the input
+and finish the command you started, or type @kbd{Control-g} to cancel
+the command. When you have done one of those things, the input entry
+line becomes blank again. Then you can type Info commands again.
+
+@findex Info-menu
+ The command to go to a subnode via a menu is @kbd{m}. After you type
+the @kbd{m}, the line at the bottom of the screen says @samp{Menu item: }.
+You must then type the name of the subtopic you want, and end it with
+a @key{RET}.
+
+@cindex abbreviating Info subnodes
+ You can abbreviate the subtopic name. If the abbreviation is not
+unique, the first matching subtopic is chosen. Some menus put
+the shortest possible abbreviation for each subtopic name in capital
+letters, so you can see how much you need to type. It does not
+matter whether you use upper case or lower case when you type the
+subtopic. You should not put any spaces at the end, or inside of the
+item name, except for one space where a space appears in the item in
+the menu.
+
+@cindex completion of Info node names
+ You can also use the @dfn{completion} feature to help enter the
+subtopic name. If you type the @key{TAB} key after entering part of a
+name, it will fill in more of the name---as much as Info can deduce
+from the part you have entered.
+
+ If you move the cursor to one of the menu subtopic lines, then you do
+not need to type the argument: you just type a @key{RET}, and it
+stands for the subtopic of the line you are on. You can also click
+the middle mouse button directly on the subtopic line to go there.
+
+Here is a menu to give you a chance to practice. This menu gives you
+three ways of going to one place, Help-FOO:
+
+@menu
+* Foo: Help-FOO. A node you can visit for fun.
+* Bar: Help-FOO. We have made two ways to get to the same place.
+* Help-FOO:: And yet another!
+@end menu
+
+(Turn Visible mode on if you are using Emacs.)
+
+@format
+>> Now type just an @kbd{m} and see what happens:
+@end format
+
+ Now you are ``inside'' an @kbd{m} command. Commands cannot be used
+now; the next thing you will type must be the name of a subtopic.
+
+ You can change your mind about doing the @kbd{m} by typing
+@kbd{Control-g}.
+
+@format
+>> Try that now; notice the bottom line clear.
+@end format
+
+@format
+>> Then type another @kbd{m}.
+@end format
+
+@format
+>> Now type @kbd{BAR}, the item name. Do not type @key{RET} yet.
+@end format
+
+ While you are typing the item name, you can use the @key{DEL} (or
+@key{BACKSPACE}) key to cancel one character at a time if you make a
+mistake.
+
+@format
+>> Press @key{DEL} to cancel the @samp{R}. You could type another @kbd{R}
+ to replace it. But you do not have to, since @samp{BA} is a valid
+ abbreviation.
+@end format
+
+@format
+>> Now you are ready to go. Type a @key{RET}.
+@end format
+
+ After visiting @samp{Help-FOO}, you should return here.
+
+ Another way to move to the menu subtopic lines and between them is
+to type @key{TAB}. Each time you type a @key{TAB}, you move to the
+next subtopic line. To move to a previous subtopic line in the
+stand-alone reader, type @kbd{M-@key{TAB}}---that is, press and hold
+the @key{META} key and then press @key{TAB}. (On some keyboards, the
+@key{META} key might be labeled @samp{Alt}.) In Emacs Info, type
+@kbd{S-@key{TAB}} to move to a previous subtopic line (press and hold
+the @key{Shift} key and then press @key{TAB}).
+
+ Once you move cursor to a subtopic line, press @key{RET} to go to
+that subtopic's node.
+
+@cindex mouse support in Info mode
+@kindex Mouse-2 @r{(Info mode)}
+ If your terminal supports a mouse, you have yet another way of going
+to a subtopic. Move your mouse pointer to the subtopic line,
+somewhere between the beginning @samp{*} and the colon @samp{:} which
+ends the subtopic's brief name. You will see the subtopic's name
+change its appearance (usually, its background color will change), and
+the shape of the mouse pointer will change if your platform supports
+that. After a while, if you leave the mouse on that spot, a small
+window will pop up, saying ``Mouse-2: go to that node,'' or the same
+message may appear at the bottom of the screen.
+
+ @kbd{Mouse-2} is the second button of your mouse counting from the
+left---the middle button on a 3-button mouse. (On a 2-button mouse,
+you may have to press both buttons together to ``press the middle
+button''.) The message tells you pressing @kbd{Mouse-2} with the
+current position of the mouse pointer (on subtopic in the menu) will
+go to that subtopic.
+
+@findex Info-mouse-follow-nearest-node
+ More generally, @kbd{Mouse-2} in an Info buffer finds the nearest
+link to another node and goes there. For example, near a cross
+reference it acts like @kbd{f}, in a menu it acts like @kbd{m}, on the
+node's header line it acts like @kbd{n}, @kbd{p}, or @kbd{u}, etc. At
+end of the node's text @kbd{Mouse-2} moves to the next node, or up if
+there's no next node.
+
+@format
+>> Type @kbd{n} to see more commands.
+@end format
+
+@node Help-FOO, , , Help-M
+@subsection The @kbd{u} command
+
+ Congratulations! This is the node @samp{Help-FOO}. It has an @samp{Up}
+pointer @samp{Help-M}, the node you just came from via the @kbd{m}
+command. This is the usual convention---the nodes you reach from a menu
+have @samp{Up} nodes that lead back to the menu. Menus move Down in the
+tree, and @samp{Up} moves Up. @samp{Previous}, on the other hand, is
+usually used to ``stay on the same level but go backwards''.
+
+@kindex u @r{(Info mode)}
+@findex Info-up
+ You can go back to the node @samp{Help-M} by typing the command
+@kbd{u} for ``Up''. This puts you at the menu subtopic line pointing
+to the subnode that the @kbd{u} command brought you from. (Some Info
+readers may put you at the @emph{front} of the node instead---to get
+back to where you were reading, you have to type some @key{SPC}s.)
+
+ Another way to go Up is to click @kbd{Mouse-2} on the @samp{Up}
+pointer shown in the header line (provided that you have a mouse).
+
+@format
+>> Now type @kbd{u} to move back up to @samp{Help-M}.
+@end format
+
+@node Help-Xref, Help-Int, Help-M, Getting Started
+@comment node-name, next, previous, up
+@section Following Cross-References
+
+@cindex cross references in Info documents
+ In Info documentation, you will see many @dfn{cross references}.
+Cross references look like this: @xref{Help-Cross, Cross}. That text
+is a real, live cross reference, whose name is @samp{Cross} and which
+points to the node named @samp{Help-Cross}. (The node name is hidden
+in Emacs. Do @kbd{M-x visible-mode} to show or hide it.)
+
+@kindex f @r{(Info mode)}
+@findex Info-follow-reference
+ You can follow a cross reference by moving the cursor to it and
+press @key{RET}, just as in a menu. In Emacs, you can also click
+@kbd{Mouse-1} on a cross reference to follow it; you can see that the
+cross reference is mouse-sensitive by moving the mouse pointer to the
+reference and watching how the underlying text and the mouse pointer
+change in response.
+
+ Another way to follow a cross reference is to type @kbd{f} and then
+specify the name of the cross reference (in this case, @samp{Cross})
+as an argument. For this command, it does not matter where the cursor
+was. If the cursor is on or near a cross reference, @kbd{f} suggests
+that reference name in parentheses as the default; typing @key{RET}
+will follow that reference. However, if you type a different
+reference name, @kbd{f} will follow the other reference which has that
+name.
+
+@format
+>> Type @kbd{f}, followed by @kbd{Cross}, and then @key{RET}.
+@end format
+
+ As you enter the reference name, you can use the @key{DEL} (or
+@key{BACKSPACE}) key to edit your input. If you change your mind
+about following any reference, you can use @kbd{Control-g} to cancel
+the command. Completion is available in the @kbd{f} command; you can
+complete among all the cross reference names in the current node by
+typing a @key{TAB}.
+
+ To get a list of all the cross references in the current node, you
+can type @kbd{?} after an @kbd{f}. The @kbd{f} continues to await a
+cross reference name even after displaying the list, so if you don't
+actually want to follow a reference, you should type a @kbd{Control-g}
+to cancel the @kbd{f}.
+
+@format
+>> Type @kbd{f?} to get a list of the cross references in this node. Then
+ type a @kbd{Control-g} and see how the @samp{f} gives up.
+@end format
+
+ The @key{TAB}, @kbd{M-@key{TAB}} and @kbd{S-@key{TAB}} keys,
+which move between menu items in a menu, also move between cross
+references outside of menus.
+
+ Sometimes a cross reference (or a node) can lead to another file (in
+other words another ``manual''), or, on occasion, even a file on a
+remote machine (although Info files distributed with Emacs or the
+stand-alone Info avoid using remote links). Such a cross reference
+looks like this: @xref{Top,, Overview of Texinfo, texinfo, Texinfo:
+The GNU Documentation Format}. (After following this link, type
+@kbd{l} to get back to this node.) Here the name @samp{texinfo}
+between parentheses refers to the file name. This file name appears
+in cross references and node names if it differs from the current
+file, so you can always know that you are going to be switching to
+another manual and which one.
+
+However, Emacs normally hides some other text in cross-references.
+If you put your mouse over the cross reference, then the information
+appearing in a separate box (tool tip) or in the echo area will show
+the full cross-reference including the file name and the node name of
+the cross reference. If you have a mouse, just leave it over the
+cross reference @xref{Top,, Overview of Texinfo, texinfo, Texinfo:
+The GNU Documentation Format}, and watch what happens. If you
+always like to have that information visible without having to move
+your mouse over the cross reference, use @kbd{M-x visible-mode}, or
+set @code{Info-hide-note-references} to a value other than @code{t}
+(@pxref{Emacs Info Variables}).
+
+@format
+>> Now type @kbd{n} to learn more commands.
+@end format
+
+@node Help-Int, Help-Q, Help-Xref, Getting Started
+@comment node-name, next, previous, up
+@section Some intermediate Info commands
+
+ The introductory course is almost over; please continue
+a little longer to learn some intermediate-level commands.
+
+ Most Info files have an index, which is actually a large node
+containing little but a menu. The menu has one menu item for each
+topic listed in the index. (As a special feature, menus for indices
+may also include the line number within the node of the index entry.
+This allows Info readers to go to the exact line of an entry, not just
+the start of the containing node.)
+
+ You can get to the index from the main menu of the file with the
+@kbd{m} command and the name of the index node; then you can use the
+@kbd{m} command again in the index node to go to the node that
+describes the topic you want.
+
+ There is also a short-cut Info command, @kbd{i}, which does all of
+that for you. It searches the index for a given topic (a string) and
+goes to the node which is listed in the index for that topic.
+@xref{Search Index}, for a full explanation.
+
+@kindex l @r{(Info mode)}
+@findex Info-history-back
+@cindex going back in Info history
+ If you have been moving around to different nodes and wish to
+retrace your steps, the @kbd{l} command (@kbd{l} for @dfn{last}) will
+do that, one node-step at a time. As you move from node to node, Info
+records the nodes where you have been in a special history list. The
+@kbd{l} command revisits nodes in the history list; each successive
+@kbd{l} command moves one step back through the history.
+
+@format
+>> Try typing @kbd{p p n} and then three @kbd{l}'s, pausing in between
+to see what each @kbd{l} does. You should wind up right back here.
+@end format
+
+ Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to
+where @emph{you} last were, whereas @kbd{p} always moves to the node
+which the header says is the @samp{Previous} node (from this node, the
+@samp{Prev} link leads to @samp{Help-Xref}).
+
+@kindex r @r{(Info mode)}
+@findex Info-history-forward
+@cindex going forward in Info history
+ You can use the @kbd{r} command (@code{Info-history-forward} in Emacs)
+to revisit nodes in the history list in the forward direction, so that
+@kbd{r} will return you to the node you came from by typing @kbd{l}.
+
+@kindex d @r{(Info mode)}
+@findex Info-directory
+@cindex go to Directory node
+ The @kbd{d} command (@code{Info-directory} in Emacs) gets you
+instantly to the Directory node. This node, which is the first one
+you saw when you entered Info, has a menu which leads (directly or
+indirectly, through other menus), to all the nodes that exist. The
+Directory node lists all the manuals and other Info documents that
+are, or could be, installed on your system.
+
+@format
+>> Try doing a @kbd{d}, then do an @kbd{l} to return here (yes,
+ @emph{do} return).
+@end format
+
+@kindex t @r{(Info mode)}
+@findex Info-top-node
+@cindex go to Top node
+ The @kbd{t} command moves to the @samp{Top} node of the manual.
+This is useful if you want to browse the manual's main menu, or select
+some specific top-level menu item. The Emacs command run by @kbd{t}
+is @code{Info-top-node}.
+
+@format
+>> Now type @kbd{n} to see the last node of the course.
+@end format
+
+ @xref{Advanced}, for more advanced Info features.
+
+@c If a menu appears at the end of this node, remove it.
+@c It is an accident of the menu updating command.
+
+@node Help-Q, , Help-Int, Getting Started
+@comment node-name, next, previous, up
+@section Quitting Info
+
+@kindex q @r{(Info mode)}
+@findex Info-exit
+@cindex quitting Info mode
+ To get out of Info, back to what you were doing before, type @kbd{q}
+for @dfn{Quit}. This runs @code{Info-exit} in Emacs.
+
+ This is the end of the basic course on using Info. You have learned
+how to move in an Info document, and how to follow menus and cross
+references. This makes you ready for reading manuals top to bottom,
+as new users should do when they learn a new package.
+
+ Another set of Info commands is useful when you need to find
+something quickly in a manual---that is, when you need to use a manual
+as a reference rather than as a tutorial. We urge you to learn
+these search commands as well. If you want to do that now, follow this
+cross reference to @ref{Advanced}.
+
+Yet another set of commands are meant for experienced users; you can
+find them by looking in the Directory node for documentation on Info.
+Finding them will be a good exercise in using Info in the usual
+manner.
+
+@format
+>> Type @kbd{d} to go to the Info directory node; then type
+ @kbd{mInfo} and Return, to get to the node about Info and
+ see what other help is available.
+@end format
+
+
+@node Advanced
+@chapter Advanced Info Commands
+
+ This chapter describes various advanced Info commands. (If you
+are using a stand-alone Info reader, there are additional commands
+specific to it, which are documented in several chapters of @ref{Top,,
+GNU Info, info-stnd, GNU Info}.)
+
+@kindex C-q @r{(Info mode)}
+ One advanced command useful with most of the others described here
+is @kbd{C-q}, which ``quotes'' the next character so that it is
+entered literally (@pxref{Inserting Text,,,emacs,The GNU Emacs
+Manual}). For example, pressing @kbd{?} ordinarily brings up a list
+of completion possibilities. If you want to (for example) search for
+an actual @samp{?} character, the simplest way is to insert it using
+@kbd{C-q ?}. This works the same in Emacs and stand-alone Info.
+
+@menu
+* Search Text:: How to search Info documents.
+* Search Index:: How to search the indices for specific subjects.
+* Go to node:: How to go to a node by name.
+* Choose menu subtopic:: How to choose a menu subtopic by its number.
+* Create Info buffer:: How to create a new Info buffer in Emacs.
+* Emacs Info Variables:: Variables modifying the behavior of Emacs Info.
+@end menu
+
+
+@node Search Text, Search Index, , Advanced
+@comment node-name, next, previous, up
+@section How to search Info documents
+
+@cindex searching Info documents
+@cindex Info document as a reference
+ The commands which move between and inside nodes allow you to read
+the entire manual or its large portions. But what if you need to find
+some information in the manual as fast as you can, and you don't know
+or don't remember in what node to look for it? This need arises when
+you use a manual as a @dfn{reference}, or when it is impractical to
+read the entire manual before you start using the programs it
+describes.
+
+ Info has powerful searching facilities that let you find things
+quickly. You can search either the manual text or its indices.
+
+@kindex s @r{(Info mode)}
+@findex Info-search
+ The @kbd{s} command allows you to search a whole Info file for a string.
+It switches to the next node if and when that is necessary. You
+type @kbd{s} followed by the string to search for, terminated by
+@key{RET}. To search for the same string again, just @kbd{s} followed
+by @key{RET} will do. The file's nodes are scanned in the order
+they are in the file, which has no necessary relationship to the
+order that they may be in the tree structure of menus and @samp{next}
+pointers. But normally the two orders are not very different. In any
+case, you can always look at the mode line to find out what node you have
+reached, if the header is not visible (this can happen, because @kbd{s}
+puts your cursor at the occurrence of the string, not at the beginning
+of the node).
+
+@kindex M-s @r{(Info mode)}
+ In Emacs, @kbd{Meta-s} is equivalent to @kbd{s}. That is for
+compatibility with other GNU packages that use @kbd{M-s} for a similar
+kind of search command. Both @kbd{s} and @kbd{M-s} run in Emacs the
+command @code{Info-search}.
+
+@kindex C-s @r{(Info mode)}
+@kindex C-r @r{(Info mode)}
+@findex isearch
+ Instead of using @kbd{s} in Emacs Info and in the stand-alone Info,
+you can use an incremental search started with @kbd{C-s} or @kbd{C-r}.
+It can search through multiple Info nodes. @xref{Incremental Search,,,
+emacs, The GNU Emacs Manual}. In Emacs, you can disable this behavior
+by setting the variable @code{Info-isearch-search} to @code{nil}
+(@pxref{Emacs Info Variables}).
+
+@node Search Index, Go to node, Search Text, Advanced
+@comment node-name, next, previous, up
+@section How to search the indices for specific subjects
+
+@cindex searching Info indices
+@kindex i @r{(Info mode)}
+@findex Info-index
+ Since most topics in the manual should be indexed, you should try
+the index search first before the text search. The @kbd{i} command
+prompts you for a subject and then looks up that subject in the
+indices. If it finds an index entry with the subject you typed, it
+goes to the node to which that index entry points. You should browse
+through that node to see whether the issue you are looking for is
+described there. If it isn't, type @kbd{,} one or more times to go
+through additional index entries which match your subject.
+
+ The @kbd{i} command and subsequent @kbd{,} commands find all index
+entries which include the string you typed @emph{as a substring}.
+For each match, Info shows in the echo area the full index entry it
+found. Often, the text of the full index entry already gives you
+enough information to decide whether it is relevant to what you are
+looking for, so we recommend that you read what Info shows in the echo
+area before looking at the node it displays.
+
+ Since @kbd{i} looks for a substring, you can search for subjects even
+if you are not sure how they are spelled in the index. For example,
+suppose you want to find something that is pertinent to commands which
+complete partial input (e.g., when you type @key{TAB}). If you want
+to catch index entries that refer to ``complete,'' ``completion,'' and
+``completing,'' you could type @kbd{icomplet@key{RET}}.
+
+ Info documents which describe programs should index the commands,
+options, and key sequences that the program provides. If you are
+looking for a description of a command, an option, or a key, just type
+their names when @kbd{i} prompts you for a topic. For example, if you
+want to read the description of what the @kbd{C-l} key does, type
+@kbd{iC-l@key{RET}} literally.
+
+@findex info-apropos
+@findex index-apropos
+If you aren't sure which manual documents the topic you are looking
+for, try the @kbd{M-x info-apropos} command in Emacs, or the @kbd{M-x
+index-apropos} command in the stand-alone reader. It prompts for
+a string and then looks up that string in all the indices of all the
+Info documents installed on your system.
+
+@node Go to node, Choose menu subtopic, Search Index, Advanced
+@comment node-name, next, previous, up
+@section @kbd{g} goes to a node by name
+
+@kindex g @r{(Info mode)}
+@findex Info-goto-node
+@cindex go to a node by name
+ If you know a node's name, you can go there by typing @kbd{g}, the
+name, and @key{RET}. Thus, @kbd{gTop@key{RET}} would go to the node
+called @samp{Top} in this file. (This is equivalent to @kbd{t}, see
+@ref{Help-Int}.) @kbd{gGo to node@key{RET}} would come back here.
+
+ Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations.
+But it does allow completion, so you can type @key{TAB} to complete a
+partial node name.
+
+@cindex go to another Info file
+ To go to a node in another file, you can include the file name in the
+node name by putting it at the front, in parentheses. Thus,
+@kbd{g(dir)Top@key{RET}} would go to the Info Directory node, which is
+the node @samp{Top} in the Info file @file{dir}. Likewise,
+@kbd{g(emacs)Top@key{RET}} goes to the top node of the Emacs manual.
+
+ The node name @samp{*} specifies the whole file. So you can look at
+all of the current file by typing @kbd{g*@key{RET}} or all of any
+other file with @kbd{g(@var{filename})*@key{RET}}.
+
+@node Choose menu subtopic, Create Info buffer, Go to node, Advanced
+@comment node-name, next, previous, up
+@section @kbd{1}--@kbd{9} choose a menu subtopic by its number
+
+@kindex 1 @r{through} 9 @r{(Info mode)}
+@findex Info-nth-menu-item
+@cindex select @var{n}'th menu item
+ If you begrudge each character of type-in which your system requires,
+you might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4},
+@dots{}, @kbd{9}. They are short for the @kbd{m} command together
+with a name of a menu subtopic. @kbd{1} goes through the first item
+in the current node's menu; @kbd{2} goes through the second item, etc.
+In the stand-alone reader, @kbd{0} goes through the last menu item;
+this is so you need not count how many entries are there.
+
+ If your display supports multiple fonts, colors or underlining, and
+you are using Emacs' Info mode to read Info files, the third, sixth
+and ninth menu items have a @samp{*} that stands out, either in color
+or in some other attribute, such as underline; this makes it easy to
+see at a glance which number to use for an item.
+
+ Some terminals don't support either multiple fonts, colors or
+underlining. If you need to actually count items, it is better to use
+@kbd{m} instead, and specify the name, or use @key{TAB} to quickly
+move between menu items.
+
+@node Create Info buffer, Emacs Info Variables, Choose menu subtopic, Advanced
+@comment node-name, next, previous, up
+@section @kbd{M-n} creates a new independent Info buffer in Emacs
+
+@kindex M-n @r{(Info mode)}
+@findex clone-buffer
+@cindex multiple Info buffers
+ If you are reading Info in Emacs, you can select a new independent
+Info buffer in a new Emacs window by typing @kbd{M-n}. The new buffer
+starts out as an exact copy of the old one, but you will be able to
+move independently between nodes in the two buffers. (In Info mode,
+@kbd{M-n} runs the Emacs command @code{clone-buffer}.)
+
+ In Emacs Info, you can also produce new Info buffers by giving a
+numeric prefix argument to the @kbd{m} and @kbd{g} commands. @kbd{C-u
+m} and @kbd{C-u g} go to a new node in exactly the same way that
+@kbd{m} and @kbd{g} do, but they do so in a new Info buffer which they
+select in another window.
+
+ Another way to produce new Info buffers in Emacs is to use a numeric
+prefix argument for the @kbd{C-h i} command (@code{info}) which
+switches to the Info buffer with that number. Thus, @kbd{C-u 2 C-h i}
+switches to the buffer @samp{*info*<2>}, creating it if necessary.
+
+@node Emacs Info Variables, , Create Info buffer, Advanced
+@comment node-name, next, previous, up
+@section Emacs Info-mode Variables
+
+The following variables may modify the behavior of Info-mode in Emacs;
+you may wish to set one or several of these variables interactively,
+or in your init file. @xref{Examining, Examining and Setting
+Variables, Examining and Setting Variables, emacs, The GNU Emacs
+Manual}. The stand-alone Info reader program has its own set of
+variables, described in @ref{Variables,, Manipulating Variables,
+info-stnd, GNU Info}.
+
+@vtable @code
+@item Info-directory-list
+The list of directories to search for Info files. Each element is a
+string (directory name) or @code{nil} (try default directory). If not
+initialized Info uses the environment variable @env{INFOPATH} to
+initialize it, or @code{Info-default-directory-list} if there is no
+@env{INFOPATH} variable in the environment.
+
+If you wish to customize the Info directory search list for both Emacs
+Info and stand-alone Info, it is best to set the @env{INFOPATH}
+environment variable, since that applies to both programs.
+
+@item Info-additional-directory-list
+A list of additional directories to search for Info documentation files.
+These directories are not searched for merging the @file{dir} file.
+
+@item Info-mode-hook
+Hooks run when @code{Info-mode} is called. By default, it contains
+the hook @code{turn-on-font-lock} which enables highlighting of Info
+files. You can change how the highlighting looks by customizing the
+faces @code{info-node}, @code{info-xref}, @code{info-xref-visited},
+@code{info-header-xref}, @code{info-header-node}, @code{info-menu-header},
+@code{info-menu-star}, and @code{info-title-@var{n}} (where @var{n}
+is the level of the section, a number between 1 and 4). To customize
+a face, type @kbd{M-x customize-face @key{RET} @var{face} @key{RET}},
+where @var{face} is one of the face names listed here.
+
+@item Info-fontify-maximum-menu-size
+Maximum size of menu to fontify if @code{font-lock-mode} is non-@code{nil}.
+
+@item Info-fontify-visited-nodes
+If non-@code{nil}, menu items and cross-references pointing to visited
+nodes are displayed in the @code{info-xref-visited} face.
+
+@item Info-use-header-line
+If non-@code{nil}, Emacs puts in the Info buffer a header line showing
+the @samp{Next}, @samp{Prev}, and @samp{Up} links. A header line does
+not scroll with the rest of the buffer, making these links always
+visible.
+
+@item Info-hide-note-references
+As explained in earlier nodes, the Emacs version of Info normally
+hides some text in menus and cross-references. You can completely
+disable this feature, by setting this option to @code{nil}. Setting
+it to a value that is neither @code{nil} nor @code{t} produces an
+intermediate behavior, hiding a limited amount of text, but showing
+all text that could potentially be useful.
+
+@item Info-scroll-prefer-subnodes
+If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or
+@key{DEL}) keys in a menu visit subnodes of the current node before
+scrolling to its end or beginning, respectively. For example, if the
+node's menu appears on the screen, the next @key{SPC} moves to a
+subnode indicated by the following menu item. Setting this option to
+@code{nil} results in behavior similar to the stand-alone Info reader
+program, which visits the first subnode from the menu only when you
+hit the end of the current node. The default is @code{nil}.
+
+@item Info-isearch-search
+If non-@code{nil}, isearch in Info searches through multiple nodes.
+
+@item Info-enable-active-nodes
+When set to a non-@code{nil} value, allows Info to execute Lisp code
+associated with nodes. The Lisp code is executed when the node is
+selected. The Lisp code to be executed should follow the node
+delimiter (the @samp{DEL} character) and an @samp{execute: } tag, like
+this:
+
+@example
+^_execute: (message "This is an active node!")
+@end example
+@end vtable
+
+
+@node Expert Info
+@chapter Info for Experts
+
+ This chapter explains how to write an Info file by hand. However,
+in most cases, writing a Texinfo file is better, since you can use it
+to make a printed manual or produce other formats, such as HTML and
+DocBook, as well as for generating Info files.
+
+The @code{makeinfo} command converts a Texinfo file into an Info file;
+@code{texinfo-format-region} and @code{texinfo-format-buffer} are GNU
+Emacs functions that do the same.
+
+@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU
+Documentation Format}, for how to write a Texinfo file.
+
+@xref{Creating an Info File,,, texinfo, Texinfo: The GNU Documentation
+Format}, for how to create an Info file from a Texinfo file.
+
+@xref{Installing an Info File,,, texinfo, Texinfo: The GNU
+Documentation Format}, for how to install an Info file after you
+have created one.
+
+However, if you want to edit an Info file manually and install it manually,
+here is how.
+
+@menu
+* Add:: Describes how to add new nodes to the hierarchy.
+ Also tells what nodes look like.
+* Menus:: How to add to or create menus in Info nodes.
+* Cross-refs:: How to add cross-references to Info nodes.
+* Tags:: How to make tags tables for Info files.
+* Checking:: Checking an Info File.
+@end menu
+
+@node Add, Menus, , Expert Info
+@comment node-name, next, previous, up
+@section Adding a new node to Info
+
+To add a new topic to the list in the Info directory, you must:
+
+@enumerate
+@item
+Create some nodes, in some file, to document that topic.
+@item
+Put that topic in the menu in the directory. @xref{Menus, Menu}.
+@end enumerate
+
+@cindex node delimiters
+ The new node can live in an existing documentation file, or in a new
+one. It must have a @samp{^_} character before it (invisible to the
+user; this node has one but you cannot see it), and it ends with either
+a @samp{^_}, a @samp{^L} (``formfeed''), or the end of file.@footnote{If
+you put in a @samp{^L} to end a new node, be sure that there is a
+@samp{^_} after it to start the next one, since @samp{^L} cannot
+@emph{start} a node. Also, a nicer way to make a node boundary be a
+page boundary as well is to put a @samp{^L} @emph{right after} the
+@samp{^_}.}
+
+ The @samp{^_} starting a node must be followed by a newline or a
+@samp{^L} newline, after which comes the node's header line. The
+header line must give the node's name (by which Info finds it), and
+state the names of the @samp{Next}, @samp{Previous}, and @samp{Up}
+nodes (if there are any). As you can see, this node's @samp{Up} node
+is the node @samp{Expert Info}. The @samp{Next} node is @samp{Menus}.
+
+@cindex node header line format
+@cindex format of node headers
+ The keywords @dfn{Node}, @dfn{Next}, @dfn{Previous}, and @dfn{Up}
+may appear in any order, anywhere in the header line, but the
+recommended order is the one in this sentence. Each keyword must be
+followed by a colon, spaces and tabs, and then the appropriate name.
+The name may be terminated with a tab, a comma, or a newline. A space
+does not end it; node names may contain spaces. The case of letters
+in the names is insignificant.
+
+@cindex node name format
+@cindex Directory node
+ A node name has two forms. A node in the current file is named by
+what appears after the @samp{Node: } in that node's first line. For
+example, this node's name is @samp{Add}. A node in another file is
+named by @samp{(@var{filename})@var{node-within-file}}, as in
+@samp{(info)Add} for this node. If the file name starts with @samp{./},
+then it is relative to the current directory; otherwise, it is
+relative starting from the standard directory for Info files of your
+site. The name @samp{(@var{filename})Top} can be abbreviated to just
+@samp{(@var{filename})}. By convention, the name @samp{Top} is used
+for the ``highest'' node in any single file---the node whose @samp{Up}
+points out of the file. The @samp{Directory} node is @file{(dir)}, it
+points to a file @file{dir} which holds a large menu listing all the
+Info documents installed on your site. The @samp{Top} node of a
+document file listed in the @samp{Directory} should have an @samp{Up:
+(dir)} in it.
+
+@cindex unstructured documents
+ The node name @kbd{*} is special: it refers to the entire file.
+Thus, @kbd{g*} shows you the whole current file. The use of the
+node @kbd{*} is to make it possible to make old-fashioned,
+unstructured files into nodes of the tree.
+
+ The @samp{Node:} name, in which a node states its own name, must not
+contain a file name, since when Info searches for a node, it does not
+expect a file name to be there. The @samp{Next}, @samp{Previous} and
+@samp{Up} names may contain them. In this node, since the @samp{Up}
+node is in the same file, it was not necessary to use one.
+
+ Note that the nodes in this file have a file name in the header
+line. The file names are ignored by Info, but they serve as comments
+to help identify the node for the user.
+
+@node Menus, Cross-refs, Add, Expert Info
+@comment node-name, next, previous, up
+@section How to Create Menus
+
+ Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes.
+The @kbd{m} command searches the current node's menu for the topic which it
+reads from the terminal.
+
+@cindex menu and menu entry format
+ A menu begins with a line starting with @w{@samp{* Menu:}}. The
+rest of the line is a comment. After the starting line, every line
+that begins with a @samp{* } lists a single topic. The name of the
+topic---what the user must type at the @kbd{m}'s command prompt to
+select this topic---comes right after the star and space, and is
+followed by a colon, spaces and tabs, and the name of the node which
+discusses that topic. The node name, like node names following
+@samp{Next}, @samp{Previous} and @samp{Up}, may be terminated with a
+tab, comma, or newline; it may also be terminated with a period.
+
+ If the node name and topic name are the same, then rather than
+giving the name twice, the abbreviation @samp{* @var{name}::} may be
+used (and should be used, whenever possible, as it reduces the visual
+clutter in the menu).
+
+ It is considerate to choose the topic names so that they differ
+from each other very near the beginning---this allows the user to type
+short abbreviations. In a long menu, it is a good idea to capitalize
+the beginning of each item name which is the minimum acceptable
+abbreviation for it (a long menu is more than 5 or so entries).
+
+ The nodes listed in a node's menu are called its ``subnodes,'' and it
+is their ``superior''. They should each have an @samp{Up:} pointing at
+the superior. It is often useful to arrange all or most of the subnodes
+in a sequence of @samp{Next} and @samp{Previous} pointers so that
+someone who wants to see them all need not keep revisiting the Menu.
+
+ The Info Directory is simply the menu of the node @samp{(dir)Top}---that
+is, node @samp{Top} in file @file{.../info/dir}. You can put new entries
+in that menu just like any other menu. The Info Directory is @emph{not} the
+same as the file directory called @file{info}. It happens that many of
+Info's files live in that file directory, but they do not have to; and
+files in that directory are not automatically listed in the Info
+Directory node.
+
+ Also, although the Info node graph is claimed to be a ``hierarchy,''
+in fact it can be @emph{any} directed graph. Shared structures and
+pointer cycles are perfectly possible, and can be used if they are
+appropriate to the meaning to be expressed. There is no need for all
+the nodes in a file to form a connected structure. In fact, this file
+has two connected components. You are in one of them, which is under
+the node @samp{Top}; the other contains the node @samp{Help} which the
+@kbd{h} command goes to. In fact, since there is no garbage
+collector on the node graph, nothing terrible happens if a substructure
+is not pointed to, but such a substructure is rather useless since nobody
+can ever find out that it exists.
+
+@node Cross-refs, Tags, Menus, Expert Info
+@comment node-name, next, previous, up
+@section Creating Cross References
+
+@cindex cross reference format
+ A cross reference can be placed anywhere in the text, unlike a menu
+item which must go at the front of a line. A cross reference looks
+like a menu item except that it has @samp{*note} instead of @samp{*}.
+It @emph{cannot} be terminated by a @samp{)}, because @samp{)}'s are
+so often part of node names. If you wish to enclose a cross reference
+in parentheses, terminate it with a period first. Here are two
+examples of cross references pointers:
+
+@example
+*Note details: commands. (See *note 3: Full Proof.)
+@end example
+
+@noindent
+@emph{These are just examples.} The places they ``lead to'' do not
+really exist!
+
+@menu
+* Help-Cross:: Target of a cross-reference.
+@end menu
+
+
+@node Help-Cross, , , Cross-refs
+@subsection The node reached by the cross reference in Info
+
+ This is the node reached by the cross reference named @samp{Cross}.
+
+ While this node is specifically intended to be reached by a cross
+reference, most cross references lead to nodes that ``belong''
+someplace else far away in the structure of an Info document. So you
+cannot expect this node to have a @samp{Next}, @samp{Previous} or
+@samp{Up} links pointing back to where you came from. In general, the
+@kbd{l} (el) command is the only way to get back there.
+
+@format
+>> Type @kbd{l} to return to the node where the cross reference was.
+@end format
+
+@node Tags, Checking, Cross-refs, Expert Info
+@comment node-name, next, previous, up
+@section Tags Tables for Info Files
+
+@cindex tags tables in Info files
+ You can speed up the access to nodes of a large Info file by giving
+it a tags table. Unlike the tags table for a program, the tags table for
+an Info file lives inside the file itself and is used
+automatically whenever Info reads in the file.
+
+@findex Info-tagify
+ To make a tags table, go to a node in the file using Emacs Info mode and type
+@kbd{M-x Info-tagify}. Then you must use @kbd{C-x C-s} to save the
+file. Info files produced by the @code{makeinfo} command that is part
+of the Texinfo package always have tags tables to begin with.
+
+@cindex stale tags tables
+@cindex update Info tags table
+ Once the Info file has a tags table, you must make certain it is up
+to date. If you edit an Info file directly (as opposed to editing its
+Texinfo source), and, as a result of deletion of text, any node moves back
+more than a thousand characters in the file from the position
+recorded in the tags table, Info will no longer be able to find that
+node. To update the tags table, use the @code{Info-tagify} command
+again.
+
+ An Info file tags table appears at the end of the file and looks like
+this:
+
+@example
+^_^L
+Tag Table:
+File: info, Node: Cross-refs^?21419
+File: info, Node: Tags^?22145
+^_
+End Tag Table
+@end example
+
+@noindent
+Note that it contains one line per node, and this line contains
+the beginning of the node's header (ending just after the node name),
+a @samp{DEL} character, and the character position in the file of the
+beginning of the node.
+
+@node Checking, , Tags, Expert Info
+@section Checking an Info File
+
+When creating an Info file, it is easy to forget the name of a node when
+you are making a pointer to it from another node. If you put in the
+wrong name for a node, this is not detected until someone tries to go
+through the pointer using Info. Verification of the Info file is an
+automatic process which checks all pointers to nodes and reports any
+pointers which are invalid. Every @samp{Next}, @samp{Previous}, and
+@samp{Up} is checked, as is every menu item and every cross reference. In
+addition, any @samp{Next} which does not have a @samp{Previous} pointing
+back is reported. Only pointers within the file are checked, because
+checking pointers to other files would be terribly slow. But those are
+usually few.
+
+@findex Info-validate
+To check an Info file, do @kbd{M-x Info-validate} while looking at any
+node of the file with Emacs Info mode.
+
+@node Index
+@unnumbered Index
+
+This is an alphabetical listing of all the commands, variables, and
+topics discussed in this document.
+
+@printindex cp
+
+@bye
+
+@ignore
+ arch-tag: 965c1638-01d6-4156-9227-b10418b9d8e8
+@end ignore
--- /dev/null
+#### -*- Makefile -*- for the Emacs Manual and other documentation.
+
+# Copyright (C) 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+# This file is part of GNU Emacs.
+
+# GNU Emacs 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 3, or (at your option)
+# any later version.
+
+# GNU Emacs 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 GNU Emacs; see the file COPYING. If not, write to
+# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+# Boston, MA 02110-1301, USA.
+
+# Where to find the source code. The source code for Emacs's C kernel is
+# expected to be in $(srcdir)/src, and the source code for Emacs's
+# utility programs is expected to be in $(srcdir)/lib-src. This is
+# set by the configure script's `--srcdir' option.
+srcdir=.
+
+infodir = $(srcdir)/../info
+
+# The makeinfo program is part of the Texinfo distribution.
+MAKEINFO = makeinfo --force
+MULTI_INSTALL_INFO = $(srcdir)\..\nt\multi-install-info.bat
+INFO_TARGETS = $(infodir)/emacs $(infodir)/ccmode \
+ $(infodir)/cl $(infodir)/dired-x $(infodir)/ediff \
+ $(infodir)/forms $(infodir)/gnus $(infodir)/message \
+ $(infodir)/sieve $(infodir)/pgg $(infodir)/emacs-mime \
+ $(infodir)/info $(infodir)/mh-e $(infodir)/reftex \
+ $(infodir)/sc $(infodir)/vip $(infodir)/viper \
+ $(infodir)/widget $(infodir)/efaq $(infodir)/ada-mode \
+ $(infodir)/autotype $(infodir)/calc $(infodir)/idlwave \
+ $(infodir)/eudc $(infodir)/ebrowse $(infodir)/pcl-cvs \
+ $(infodir)/woman $(infodir)/eshell $(infodir)/org \
+ $(infodir)/url $(infodir)/speedbar $(infodir)/tramp \
+ $(infodir)/ses $(infodir)/smtpmail $(infodir)/flymake \
+ $(infodir)/newsticker $(infodir)/rcirc $(infodir)/erc
+DVI_TARGETS = emacs.dvi calc.dvi cc-mode.dvi cl.dvi dired-x.dvi \
+ ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \
+ gnus.dvi message.dvi sieve.dvi pgg.dvi mh-e.dvi \
+ reftex.dvi sc.dvi vip.dvi viper.dvi widget.dvi faq.dvi \
+ ada-mode.dvi autotype.dvi idlwave.dvi eudc.dvi ebrowse.dvi \
+ pcl-cvs.dvi woman.dvi eshell.dvi org.dvi url.dvi \
+ speedbar.dvi tramp.dvi ses.dvi smtpmail.dvi flymake.dvi \
+ newsticker.dvi emacs-xtra.dvi rcirc.dvi erc.dvi
+INFOSOURCES = info.texi
+
+# The following rule does not work with all versions of `make'.
+.SUFFIXES: .texi .dvi
+.texi.dvi:
+ texi2dvi $<
+
+TEXI2DVI = texi2dvi
+ENVADD = $(srcdir)\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \
+ "MAKEINFO=$(MAKEINFO) -I$(srcdir)" /C
+
+EMACS_XTRA=\
+ $(srcdir)/arevert-xtra.texi \
+ $(srcdir)/cal-xtra.texi \
+ $(srcdir)/dired-xtra.texi \
+ $(srcdir)/picture-xtra.texi \
+ $(srcdir)/emerge-xtra.texi \
+ $(srcdir)/vc-xtra.texi \
+ $(srcdir)/vc1-xtra.texi \
+ $(srcdir)/vc2-xtra.texi \
+ $(srcdir)/fortran-xtra.texi \
+ $(srcdir)/msdog-xtra.texi
+
+EMACSSOURCES= \
+ $(srcdir)/emacs.texi \
+ $(srcdir)/doclicense.texi \
+ $(srcdir)/screen.texi \
+ $(srcdir)/commands.texi \
+ $(srcdir)/entering.texi \
+ $(srcdir)/basic.texi \
+ $(srcdir)/mini.texi \
+ $(srcdir)/m-x.texi \
+ $(srcdir)/help.texi \
+ $(srcdir)/mark.texi \
+ $(srcdir)/killing.texi \
+ $(srcdir)/regs.texi \
+ $(srcdir)/display.texi \
+ $(srcdir)/search.texi \
+ $(srcdir)/fixit.texi \
+ $(srcdir)/files.texi \
+ $(srcdir)/buffers.texi \
+ $(srcdir)/windows.texi \
+ $(srcdir)/frames.texi \
+ $(srcdir)/mule.texi \
+ $(srcdir)/major.texi \
+ $(srcdir)/indent.texi \
+ $(srcdir)/text.texi \
+ $(srcdir)/programs.texi \
+ $(srcdir)/building.texi \
+ $(srcdir)/maintaining.texi \
+ $(srcdir)/abbrevs.texi \
+ $(srcdir)/sending.texi \
+ $(srcdir)/rmail.texi \
+ $(srcdir)/dired.texi \
+ $(srcdir)/calendar.texi \
+ $(srcdir)/misc.texi \
+ $(srcdir)/custom.texi \
+ $(srcdir)/trouble.texi \
+ $(srcdir)/cmdargs.texi \
+ $(srcdir)/xresources.texi \
+ $(srcdir)/anti.texi \
+ $(srcdir)/macos.texi \
+ $(srcdir)/msdog.texi \
+ $(srcdir)/gnu.texi \
+ $(srcdir)/glossary.texi \
+ $(srcdir)/ack.texi \
+ $(srcdir)/kmacro.texi \
+ $(EMACS_XTRA)
+
+info: $(INFO_TARGETS)
+
+dvi: $(DVI_TARGETS)
+
+# Note that all the Info targets build the Info files
+# in srcdir. There is no provision for Info files
+# to exist in the build directory.
+# In a distribution of Emacs, the Info files should be up to date.
+
+# The following target uses an explicit -o switch to work around
+# the @setfilename directive in info.texi, which is required for
+# the Texinfo distribution.
+# Some Windows ports of makeinfo seem to require -o to come before the
+# texi filename, contrary to GNU standards.
+
+$(infodir)/dir:
+ $(MULTI_INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS)
+
+$(infodir)/info: $(INFOSOURCES)
+ $(MAKEINFO) --no-split -o $@ info.texi
+
+info.dvi: $(INFOSOURCES)
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/info.texi
+
+$(infodir)/emacs: $(EMACSSOURCES)
+ $(MAKEINFO) emacs.texi
+
+emacs.dvi: $(EMACSSOURCES)
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs.texi
+
+# This target is here so you could easily get the list of the *.texi
+# files which belong to the Emacs manual (as opposed to the separate
+# manuals for CL, CC Mode, Ebrowse, etc.). With this target, you can
+# say things like "grep foo `make emacsman`".
+emacsman:
+ @echo $(EMACSSOURCES)
+
+$(infodir)/ccmode: cc-mode.texi
+ $(MAKEINFO) cc-mode.texi
+cc-mode.dvi: cc-mode.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/cc-mode.texi
+
+$(infodir)/ada-mode: ada-mode.texi
+ $(MAKEINFO) ada-mode.texi
+ada-mode.dvi: ada-mode.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/ada-mode.texi
+
+$(infodir)/pcl-cvs: pcl-cvs.texi
+ $(MAKEINFO) pcl-cvs.texi
+pcl-cvs.dvi: pcl-cvs.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/pcl-cvs.texi
+
+$(infodir)/eshell: eshell.texi
+ $(MAKEINFO) eshell.texi
+eshell.dvi: eshell.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/eshell.texi
+
+$(infodir)/cl: cl.texi
+ $(MAKEINFO) cl.texi
+cl.dvi: cl.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/cl.texi
+
+$(infodir)/dired-x: dired-x.texi
+ $(MAKEINFO) dired-x.texi
+dired-x.dvi: dired-x.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/dired-x.texi
+
+$(infodir)/ediff: ediff.texi
+ $(MAKEINFO) ediff.texi
+ediff.dvi: ediff.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/ediff.texi
+
+$(infodir)/flymake: flymake.texi
+ $(MAKEINFO) flymake.texi
+flymake.dvi: flymake.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/flymake.texi
+
+$(infodir)/forms: forms.texi
+ $(MAKEINFO) forms.texi
+forms.dvi: forms.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/forms.texi
+
+# gnus/message/emacs-mime/sieve/pgg are part of Gnus:
+$(infodir)/gnus: gnus.texi
+ $(MAKEINFO) gnus.texi
+gnus.dvi: gnus.texi
+ sed -e "/@iflatex/,/@end iflatex/d" $(srcdir)/gnus.texi > gnustmp.texi
+ $(ENVADD) $(TEXI2DVI) gnustmp.texi
+ cp gnustmp.dvi $*.dvi
+ rm gnustmp.*
+#
+$(infodir)/message: message.texi
+ $(MAKEINFO) message.texi
+message.dvi: message.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/message.texi
+#
+$(infodir)/emacs-mime: emacs-mime.texi
+ $(MAKEINFO) --enable-encoding emacs-mime.texi
+emacs-mime.dvi: emacs-mime.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-mime.texi
+#
+$(infodir)/sieve: sieve.texi
+ $(MAKEINFO) sieve.texi
+sieve.dvi: sieve.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/sieve.texi
+#
+$(infodir)/pgg: pgg.texi
+ $(MAKEINFO) pgg.texi
+pgg.dvi: pgg.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/pgg.texi
+
+$(infodir)/mh-e: mh-e.texi
+ $(MAKEINFO) mh-e.texi
+mh-e.dvi: mh-e.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/mh-e.texi
+
+$(infodir)/reftex: reftex.texi
+ $(MAKEINFO) reftex.texi
+reftex.dvi: reftex.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/reftex.texi
+
+$(infodir)/sc: sc.texi
+ $(MAKEINFO) sc.texi
+sc.dvi: sc.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/sc.texi
+
+$(infodir)/vip: vip.texi
+ $(MAKEINFO) vip.texi
+vip.dvi: vip.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/vip.texi
+
+$(infodir)/viper: viper.texi
+ $(MAKEINFO) viper.texi
+viper.dvi: viper.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/viper.texi
+
+$(infodir)/widget: widget.texi
+ $(MAKEINFO) widget.texi
+widget.dvi: widget.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/widget.texi
+
+$(infodir)/efaq: faq.texi
+ $(MAKEINFO) faq.texi
+faq.dvi: faq.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/faq.texi
+
+../etc/GNU: gnu1.texi gnu.texi
+ $(MAKEINFO) --no-headers -o ../etc/GNU gnu1.texi
+
+$(infodir)/autotype: autotype.texi
+ $(MAKEINFO) autotype.texi
+autotype.dvi: autotype.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/autotype.texi
+
+$(infodir)/calc: calc.texi
+ $(MAKEINFO) calc.texi
+
+calc.dvi: calc.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/calc.texi
+
+# This is produced with --no-split to avoid making files whose
+# names clash on DOS 8+3 filesystems
+$(infodir)/idlwave: idlwave.texi
+ $(MAKEINFO) --no-split idlwave.texi
+idlwave.dvi: idlwave.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/idlwave.texi
+
+$(infodir)/eudc: eudc.texi
+ $(MAKEINFO) eudc.texi
+eudc.dvi: eudc.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/eudc.texi
+
+$(infodir)/ebrowse: ebrowse.texi
+ $(MAKEINFO) ebrowse.texi
+ebrowse.dvi: ebrowse.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/ebrowse.texi
+
+$(infodir)/woman: woman.texi
+ $(MAKEINFO) woman.texi
+woman.dvi: woman.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/woman.texi
+
+$(infodir)/speedbar: speedbar.texi
+ $(MAKEINFO) speedbar.texi
+speedbar.dvi: speedbar.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/speedbar.texi
+
+$(infodir)/tramp: tramp.texi
+ $(MAKEINFO) tramp.texi
+tramp.dvi: tramp.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/tramp.texi
+
+$(infodir)/ses: ses.texi
+ $(MAKEINFO) ses.texi
+ses.dvi: ses.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/ses.texi
+
+$(infodir)/smtpmail: smtpmail.texi
+ $(MAKEINFO) smtpmail.texi
+smtpmail.dvi: smtpmail.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/smtpmail.texi
+
+emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA)
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-xtra.texi
+
+$(infodir)/org: org.texi
+ $(MAKEINFO) org.texi
+org.dvi: org.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/org.texi
+
+$(infodir)/url: url.texi
+ $(MAKEINFO) url.texi
+url.dvi: url.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/url.texi
+
+$(infodir)/newsticker: newsticker.texi
+ $(MAKEINFO) newsticker.texi
+newsticker.dvi: newsticker.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/newsticker.texi
+
+$(infodir)/rcirc: rcirc.texi
+ $(MAKEINFO) rcirc.texi
+rcirc.dvi: rcirc.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/rcirc.texi
+
+$(infodir)/erc: erc.texi
+ $(MAKEINFO) erc.texi
+erc.dvi: erc.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/erc.texi
+
+mostlyclean:
+ - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.*
+
+clean: mostlyclean
+ - $(DEL) *.dvi
+ - $(DEL) $(infodir)/emacs* $(infodir)/ccmode* \
+ $(infodir)/cl* $(infodir)/dired-x* \
+ $(infodir)/ediff* $(infodir)/forms* \
+ $(infodir)/gnus* $(infodir)/info* \
+ $(infodir)/message* $(infodir)/mh-e* \
+ $(infodir)/reftex* $(infodir)/sc* \
+ $(infodir)/vip* $(infodir)/widget* \
+ $(infodir)/efaq* $(infodir)/ada-mode* \
+ $(infodir)/autotype* $(infodir)/calc* \
+ $(infodir)/idlwave* $(infodir)/eudc* \
+ $(infodir)/ebrowse* $(infodir)/pcl-cvs* \
+ $(infodir)/woman* $(infodir)/eshell* \
+ $(infodir)/speedbar* $(infodir)/tramp* \
+ $(infodir)/ses* $(infodir)/smtpmail* \
+ $(infodir)/url* $(infodir)/org* \
+ $(infodir)/flymake* $(infodir)/newsticker* \
+ $(infodir)/sieve* $(infodir)/pgg* \
+ $(infodir)/erc* $(infodir)/rcirc*
+
+distclean: clean
+
+maintainer-clean: distclean
+ - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc
+# Don't delete these, because they are outside the current directory.
+# for file in $(INFO_TARGETS); do rm -f $${file}*; done
+
+
+# Formerly this directory had texindex.c and getopt.c in it
+# and this makefile built them to make texindex.
+# That caused trouble because this is run entirely in the source directory.
+# Since we expect to get texi2dvi from elsewhere,
+# it is ok to expect texindex from elsewhere also.
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+
+@setfilename ../info/message
+@settitle Message Manual
+@synindex fn cp
+@synindex vr cp
+@synindex pg cp
+@copying
+This file documents Message, the Emacs message composition mode.
+
+Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
+2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Message: (message). Mail and news composition mode that goes with Gnus.
+@end direntry
+@iftex
+@finalout
+@end iftex
+@setchapternewpage odd
+
+@titlepage
+@title Message Manual
+
+@author by Lars Magne Ingebrigtsen
+@page
+
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+@page
+
+@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.
+* GNU Free Documentation License:: The license for this documentation.
+* Index:: Variable, function and concept index.
+* Key Index:: List of Message mode keys.
+@end menu
+
+@c Adjust ../Makefile.in if you change the following lines:
+Message is distributed with Gnus. The Gnus distribution
+@c
+corresponding to this manual is Gnus v5.11.
+
+
+@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.
+* Mailing Lists:: Send mail to mailing lists.
+@end menu
+
+You can customize the Message Mode tool bar, see @kbd{M-x
+customize-apropos RET message-tool-bar}. This feature is only available
+in Emacs.
+
+@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")
+ (list (cons 'To (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 list. In this case, it
+returns @code{((To . "Whom"))} 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.
+
+Each list element should be a cons, where the @sc{car} should be the
+name of a header (e.g. @code{Cc}) and the @sc{cdr} should be the header
+value (e.g. @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}).
+
+@vindex message-dont-reply-to-names
+Addresses that match the @code{message-dont-reply-to-names} regular
+expression will be removed from the @code{Cc} header.
+
+@vindex message-wide-reply-confirm-recipients
+If @code{message-wide-reply-confirm-recipients} is non-@code{nil} you
+will be asked to confirm that you want to reply to multiple
+recipients. The default is @code{nil}.
+
+@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.
+
+@vindex message-cancel-message
+The value of @code{message-cancel-message} is inserted in the body of
+the cancel message. The default is @samp{I am canceling my own
+article.}.
+
+@cindex Cancel Locks
+@vindex message-insert-canlock
+@cindex canlock
+When Message posts news messages, it inserts @code{Cancel-Lock}
+headers by default. This is a cryptographic header that ensures that
+only you can cancel your own messages, which is nice. The downside
+is that if you lose your @file{.emacs} file (which is where Gnus
+stores the secret cancel lock password (which is generated
+automatically the first time you use this feature)), you won't be
+able to cancel your message. If you want to manage a password yourself,
+you can put something like the following in your @file{~/.gnus.el} file:
+
+@lisp
+(setq canlock-password "geheimnis"
+ canlock-password-for-verify canlock-password)
+@end lisp
+
+Whether to insert the header or not is controlled by the
+@code{message-insert-canlock} variable.
+
+Not many news servers respect the @code{Cancel-Lock} header yet, but
+this is expected to change in the future.
+
+
+@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:\\|^X-Trace:\\|^X-Complaints-To:\\|@*
+Return-Path:\\|^Supersedes:\\|^NNTP-Posting-Date:\\|^X-Trace:\\|@*
+^X-Complaints-To:\\|^Cancel-Lock:\\|^Cancel-Key:\\|^X-Hashcash:\\|@*
+^X-Payment:}.
+
+
+
+@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-ignored-headers
+@vindex message-forward-ignored-headers
+All headers that match this regexp will be deleted when forwarding a message.
+
+@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}.
+
+@item message-forward-as-mime
+@vindex message-forward-as-mime
+If this variable is @code{t} (the default), forwarded messages are
+included as inline @acronym{MIME} RFC822 parts. If it's @code{nil}, forwarded
+messages will just be copied inline to the new message, like previous,
+non @acronym{MIME}-savvy versions of Gnus would do.
+
+@item message-forward-before-signature
+@vindex message-forward-before-signature
+If non-@code{nil}, put forwarded message before signature, else after.
+
+@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.
+
+
+@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\\|Delivered-To\\):}.
+
+
+@node Mailing Lists
+@section Mailing Lists
+
+@cindex Mail-Followup-To
+Sometimes while posting to mailing lists, the poster needs to direct
+followups to the post to specific places. The Mail-Followup-To (MFT)
+was created to enable just this. Three example scenarios where this is
+useful:
+
+@itemize @bullet
+@item
+A mailing list poster can use MFT to express that responses should be
+sent to just the list, and not the poster as well. This will happen
+if the poster is already subscribed to the list.
+
+@item
+A mailing list poster can use MFT to express that responses should be
+sent to the list and the poster as well. This will happen if the poster
+is not subscribed to the list.
+
+@item
+If a message is posted to several mailing lists, MFT may also be used
+to direct the following discussion to one list only, because
+discussions that are spread over several lists tend to be fragmented
+and very difficult to follow.
+
+@end itemize
+
+Gnus honors the MFT header in other's messages (i.e. while following
+up to someone else's post) and also provides support for generating
+sensible MFT headers for outgoing messages as well.
+
+@c @menu
+@c * Honoring an MFT post:: What to do when one already exists
+@c * Composing with a MFT header:: Creating one from scratch.
+@c @end menu
+
+@c @node Composing with a MFT header
+@subsection Composing a correct MFT header automagically
+
+The first step in getting Gnus to automagically generate a MFT header
+in posts you make is to give Gnus a list of the mailing lists
+addresses you are subscribed to. You can do this in more than one
+way. The following variables would come in handy.
+
+@table @code
+
+@vindex message-subscribed-addresses
+@item message-subscribed-addresses
+This should be a list of addresses the user is subscribed to. Its
+default value is @code{nil}. Example:
+@lisp
+(setq message-subscribed-addresses
+ '("ding@@gnus.org" "bing@@noose.org"))
+@end lisp
+
+@vindex message-subscribed-regexps
+@item message-subscribed-regexps
+This should be a list of regexps denoting the addresses of mailing
+lists subscribed to. Default value is @code{nil}. Example: If you
+want to achieve the same result as above:
+@lisp
+(setq message-subscribed-regexps
+ '("\\(ding@@gnus\\)\\|\\(bing@@noose\\)\\.org")
+@end lisp
+
+@vindex message-subscribed-address-functions
+@item message-subscribed-address-functions
+This can be a list of functions to be called (one at a time!!) to
+determine the value of MFT headers. It is advisable that these
+functions not take any arguments. Default value is @code{nil}.
+
+There is a pre-defined function in Gnus that is a good candidate for
+this variable. @code{gnus-find-subscribed-addresses} is a function
+that returns a list of addresses corresponding to the groups that have
+the @code{subscribed} (@pxref{Group Parameters, ,Group Parameters,
+gnus, The Gnus Manual}) group parameter set to a non-@code{nil} value.
+This is how you would do it.
+
+@lisp
+(setq message-subscribed-address-functions
+ '(gnus-find-subscribed-addresses))
+@end lisp
+
+@vindex message-subscribed-address-file
+@item message-subscribed-address-file
+You might be one organized human freak and have a list of addresses of
+all subscribed mailing lists in a separate file! Then you can just
+set this variable to the name of the file and life would be good.
+
+@end table
+
+You can use one or more of the above variables. All their values are
+``added'' in some way that works :-)
+
+Now you are all set. Just start composing a message as you normally do.
+And just send it; as always. Just before the message is sent out, Gnus'
+MFT generation thingy kicks in and checks if the message already has a
+MFT field. If there is one, it is left alone. (Except if it's empty -
+in that case, the field is removed and is not replaced with an
+automatically generated one. This lets you disable MFT generation on a
+per-message basis.) If there is none, then the list of recipient
+addresses (in the To: and Cc: headers) is checked to see if one of them
+is a list address you are subscribed to. If none of them is a list
+address, then no MFT is generated; otherwise, a MFT is added to the
+other headers and set to the value of all addresses in To: and Cc:
+
+@kindex C-c C-f C-a
+@findex message-generate-unsubscribed-mail-followup-to
+@kindex C-c C-f C-m
+@findex message-goto-mail-followup-to
+Hm. ``So'', you ask, ``what if I send an email to a list I am not
+subscribed to? I want my MFT to say that I want an extra copy.'' (This
+is supposed to be interpreted by others the same way as if there were no
+MFT, but you can use an explicit MFT to override someone else's
+to-address group parameter.) The function
+@code{message-generate-unsubscribed-mail-followup-to} might come in
+handy. It is bound to @kbd{C-c C-f C-a} by default. In any case, you
+can insert a MFT of your own choice; @kbd{C-c C-f C-m}
+(@code{message-goto-mail-followup-to}) will help you get started.
+
+@c @node Honoring an MFT post
+@subsection Honoring an MFT post
+
+@vindex message-use-mail-followup-to
+When you followup to a post on a mailing list, and the post has a MFT
+header, Gnus' action will depend on the value of the variable
+@code{message-use-mail-followup-to}. This variable can be one of:
+
+@table @code
+@item use
+ Always honor MFTs. The To: and Cc: headers in your followup will be
+ derived from the MFT header of the original post. This is the default.
+
+@item nil
+ Always dishonor MFTs (just ignore the darned thing)
+
+@item ask
+Gnus will prompt you for an action.
+
+@end table
+
+It is considered good netiquette to honor MFT, as it is assumed the
+fellow who posted a message knows where the followups need to go
+better than you do.
+
+@node Commands
+@chapter Commands
+
+@menu
+* Buffer Entry:: Commands after entering a Message buffer.
+* Header Commands:: Commands for moving headers or changing headers.
+* Movement:: Moving around in message buffers.
+* Insertion:: Inserting things into message buffers.
+* MIME:: @acronym{MIME} considerations.
+* IDNA:: Non-@acronym{ASCII} domain name considerations.
+* Security:: Signing and encrypting messages.
+* Various Commands:: Various things.
+* Sending:: Actually sending the message.
+* Mail Aliases:: How to use mail aliases.
+* Spelling:: Having Emacs check your spelling.
+@end menu
+
+
+@node Buffer Entry
+@section Buffer Entry
+@cindex undo
+@kindex C-_
+
+You most often end up in a Message buffer when responding to some other
+message of some sort. Message does lots of handling of quoted text, and
+may remove signatures, reformat the text, or the like---depending on
+which used settings you're using. Message usually gets things right,
+but sometimes it stumbles. To help the user unwind these stumblings,
+Message sets the undo boundary before each major automatic action it
+takes. If you press the undo key (usually located at @kbd{C-_}) a few
+times, you will get back the un-edited message you're responding to.
+
+
+@node Header Commands
+@section Header Commands
+
+@subsection Commands for moving to headers
+
+These following 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 describe-mode
+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-o
+@kindex C-c C-f C-o
+@findex message-goto-from
+Go to the @code{From} header (@code{message-goto-from}). (The ``o''
+in the key binding is for Originator.)
+
+@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}).
+
+@item C-c C-f C-i
+@kindex C-c C-f C-i
+@findex message-insert-or-toggle-importance
+This inserts the @samp{Importance:} header with a value of
+@samp{high}. This header is used to signal the importance of the
+message to the receiver. If the header is already present in the
+buffer, it cycles between the three valid values according to RFC
+1376: @samp{low}, @samp{normal} and @samp{high}.
+
+@item C-c C-f C-a
+@kindex C-c C-f C-a
+@findex message-generate-unsubscribed-mail-followup-to
+Insert a reasonable @samp{Mail-Followup-To:} header
+(@pxref{Mailing Lists}) in a post to an
+unsubscribed list. When making original posts to a mailing list you are
+not subscribed to, you have to type in a @samp{Mail-Followup-To:} header
+by hand. The contents, usually, are the addresses of the list and your
+own address. This function inserts such a header automatically. It
+fetches the contents of the @samp{To:} header in the current mail
+buffer, and appends the current @code{user-mail-address}.
+
+If the optional argument @code{include-cc} is non-@code{nil}, the
+addresses in the @samp{Cc:} header are also put into the
+@samp{Mail-Followup-To:} header.
+
+@end table
+
+@subsection Commands to change headers
+
+@table @kbd
+
+@item C-c C-o
+@kindex C-c C-o
+@findex message-sort-headers
+@vindex message-header-format-alist
+Sort headers according to @code{message-header-format-alist}
+(@code{message-sort-headers}).
+
+@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 C-l
+@kindex C-c C-l
+@findex message-to-list-only
+Send a message to the list only. Remove all addresses but the list
+address from @code{To:} and @code{Cc:} headers.
+
+@item C-c M-n
+@kindex C-c M-n
+@findex message-insert-disposition-notification-to
+Insert a request for a disposition
+notification. (@code{message-insert-disposition-notification-to}).
+This means that if the recipient support RFC 2298 she might send you a
+notification that she received the message.
+
+@item M-x message-insert-importance-high
+@kindex M-x message-insert-importance-high
+@findex message-insert-importance-high
+@cindex Importance
+Insert an @samp{Importance} header with a value of @samp{high},
+deleting headers if necessary.
+
+@item M-x message-insert-importance-low
+@kindex M-x message-insert-importance-low
+@findex message-insert-importance-low
+@cindex Importance
+Insert an @samp{Importance} header with a value of @samp{low}, deleting
+headers if necessary.
+
+@item C-c C-f s
+@kindex C-c C-f s
+@findex message-change-subject
+@cindex Subject
+Change the current @samp{Subject} header. Ask for new @samp{Subject}
+header and append @samp{(was: <Old Subject>)}. The old subject can be
+stripped on replying, see @code{message-subject-trailing-was-query}
+(@pxref{Message Headers}).
+
+@item C-c C-f x
+@kindex C-c C-f x
+@findex message-cross-post-followup-to
+@vindex message-cross-post-default
+@vindex message-cross-post-note-function
+@cindex X-Post
+@cindex cross-post
+Set up the @samp{FollowUp-To} header with a target newsgroup for a
+cross-post, add that target newsgroup to the @samp{Newsgroups} header if
+it is not a member of @samp{Newsgroups}, and insert a note in the body.
+If @code{message-cross-post-default} is @code{nil} or if this command is
+called with a prefix-argument, only the @samp{FollowUp-To} header will
+be set but the target newsgroup will not be added to the
+@samp{Newsgroups} header. The function to insert a note is controlled
+by the @code{message-cross-post-note-function} variable.
+
+@item C-c C-f t
+@kindex C-c C-f t
+@findex message-reduce-to-to-cc
+Replace contents of @samp{To} header with contents of @samp{Cc} or
+@samp{Bcc} header. (Iff @samp{Cc} header is not present, @samp{Bcc}
+header will be used instead.)
+
+@item C-c C-f w
+@kindex C-c C-f w
+@findex message-insert-wide-reply
+Insert @samp{To} and @samp{Cc} headers as if you were doing a wide
+reply even if the message was not made for a wide reply first.
+
+@item C-c C-f a
+@kindex C-c C-f a
+@findex message-add-archive-header
+@vindex message-archive-header
+@vindex message-archive-note
+@cindex X-No-Archive
+Insert @samp{X-No-Archive: Yes} in the header and a note in the body.
+The header and the note can be customized using
+@code{message-archive-header} and @code{message-archive-note}. When
+called with a prefix argument, ask for a text to insert. If you don't
+want the note in the body, set @code{message-archive-note} to
+@code{nil}.
+
+@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}).
+
+@item C-a
+@kindex C-a
+@findex message-beginning-of-line
+@vindex message-beginning-of-line
+If at beginning of header value, go to beginning of line, else go to
+beginning of header value. (The header value comes after the header
+name and the colon.) This behavior can be disabled by toggling
+the variable @code{message-beginning-of-line}.
+
+@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-M-y
+@kindex C-c C-M-y
+@findex message-yank-buffer
+Prompt for a buffer name and yank the contents of that buffer into the
+message buffer (@code{message-yank-buffer}).
+
+@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}).
+
+@item C-c M-h
+@kindex C-c M-h
+@findex message-insert-headers
+Insert the message headers (@code{message-insert-headers}).
+
+@item C-c M-m
+@kindex C-c M-m
+@findex message-mark-inserted-region
+Mark some region in the current article with enclosing tags.
+See @code{message-mark-insert-begin} and @code{message-mark-insert-end}.
+
+@item C-c M-f
+@kindex C-c M-f
+@findex message-mark-insert-file
+Insert a file in the current article with enclosing tags.
+See @code{message-mark-insert-begin} and @code{message-mark-insert-end}.
+
+@end table
+
+
+@node MIME
+@section MIME
+@cindex MML
+@cindex MIME
+@cindex multipart
+@cindex attachment
+
+Message is a @acronym{MIME}-compliant posting agent. The user generally
+doesn't have to do anything to make the @acronym{MIME} happen---Message will
+automatically add the @code{Content-Type} and
+@code{Content-Transfer-Encoding} headers.
+
+@findex mml-attach-file
+@kindex C-c C-a
+The most typical thing users want to use the multipart things in
+@acronym{MIME} for is to add ``attachments'' to mail they send out.
+This can be done with the @kbd{C-c C-a} command (@kbd{M-x mml-attach-file}),
+which will prompt for a file name and a @acronym{MIME} type.
+
+@vindex mml-dnd-protocol-alist
+@vindex mml-dnd-attach-options
+If your Emacs supports drag and drop, you can also drop the file in the
+Message buffer. The variable @code{mml-dnd-protocol-alist} specifies
+what kind of action is done when you drop a file into the Message
+buffer. The variable @code{mml-dnd-attach-options} controls which
+@acronym{MIME} options you want to specify when dropping a file. If it
+is a list, valid members are @code{type}, @code{description} and
+@code{disposition}. @code{disposition} implies @code{type}. If it is
+@code{nil}, don't ask for options. If it is @code{t}, ask the user
+whether or not to specify options.
+
+You can also create arbitrarily complex multiparts using the @acronym{MML}
+language (@pxref{Composing, , Composing, emacs-mime, The Emacs MIME
+Manual}).
+
+@node IDNA
+@section IDNA
+@cindex IDNA
+@cindex internationalized domain names
+@cindex non-ascii domain names
+
+Message is a @acronym{IDNA}-compliant posting agent. The user
+generally doesn't have to do anything to make the @acronym{IDNA}
+happen---Message will encode non-@acronym{ASCII} domain names in @code{From},
+@code{To}, and @code{Cc} headers automatically.
+
+Until @acronym{IDNA} becomes more well known, Message queries you
+whether @acronym{IDNA} encoding of the domain name really should
+occur. Some users might not be aware that domain names can contain
+non-@acronym{ASCII} now, so this gives them a safety net if they accidently
+typed a non-@acronym{ASCII} domain name.
+
+@vindex message-use-idna
+The @code{message-use-idna} variable control whether @acronym{IDNA} is
+used. If the variable is @code{nil} no @acronym{IDNA} encoding will
+ever happen, if it is set to the symbol @code{ask} the user will be
+queried, and if set to @code{t} (which is the default if @acronym{IDNA}
+is fully available) @acronym{IDNA} encoding happens automatically.
+
+@findex message-idna-to-ascii-rhs
+If you want to experiment with the @acronym{IDNA} encoding, you can
+invoke @kbd{M-x message-idna-to-ascii-rhs RET} in the message buffer
+to have the non-@acronym{ASCII} domain names encoded while you edit
+the message.
+
+Note that you must have @uref{http://www.gnu.org/software/libidn/, GNU
+Libidn} installed in order to use this functionality.
+
+@node Security
+@section Security
+@cindex Security
+@cindex S/MIME
+@cindex PGP
+@cindex PGP/MIME
+@cindex sign
+@cindex encrypt
+@cindex secure
+
+Using the @acronym{MML} language, Message is able to create digitally
+signed and digitally encrypted messages. Message (or rather
+@acronym{MML}) currently support @acronym{PGP} (RFC 1991),
+@acronym{PGP/MIME} (RFC 2015/3156) and @acronym{S/MIME}.
+
+@menu
+* Signing and encryption:: Signing and encrypting commands.
+* Using S/MIME:: Using S/MIME
+* Using PGP/MIME:: Using PGP/MIME
+* PGP Compatibility:: Compatibility with older implementations
+@end menu
+
+@node Signing and encryption
+@subsection Signing and encrypting commands
+
+Instructing @acronym{MML} to perform security operations on a
+@acronym{MIME} part is done using the @kbd{C-c C-m s} key map for
+signing and the @kbd{C-c C-m c} key map for encryption, as follows.
+@table @kbd
+
+@item C-c C-m s s
+@kindex C-c C-m s s
+@findex mml-secure-message-sign-smime
+
+Digitally sign current message using @acronym{S/MIME}.
+
+@item C-c C-m s o
+@kindex C-c C-m s o
+@findex mml-secure-message-sign-pgp
+
+Digitally sign current message using @acronym{PGP}.
+
+@item C-c C-m s p
+@kindex C-c C-m s p
+@findex mml-secure-message-sign-pgpmime
+
+Digitally sign current message using @acronym{PGP/MIME}.
+
+@item C-c C-m c s
+@kindex C-c C-m c s
+@findex mml-secure-message-encrypt-smime
+
+Digitally encrypt current message using @acronym{S/MIME}.
+
+@item C-c C-m c o
+@kindex C-c C-m c o
+@findex mml-secure-message-encrypt-pgp
+
+Digitally encrypt current message using @acronym{PGP}.
+
+@item C-c C-m c p
+@kindex C-c C-m c p
+@findex mml-secure-message-encrypt-pgpmime
+
+Digitally encrypt current message using @acronym{PGP/MIME}.
+
+@item C-c C-m C-n
+@kindex C-c C-m C-n
+@findex mml-unsecure-message
+Remove security related @acronym{MML} tags from message.
+
+@end table
+
+These commands do not immediately sign or encrypt the message, they
+merely insert the proper @acronym{MML} secure tag to instruct the
+@acronym{MML} engine to perform that operation when the message is
+actually sent. They may perform other operations too, such as locating
+and retrieving a @acronym{S/MIME} certificate of the person you wish to
+send encrypted mail to. When the mml parsing engine converts your
+@acronym{MML} into a properly encoded @acronym{MIME} message, the secure
+tag will be replaced with either a part or a multipart tag. If your
+message contains other mml parts, a multipart tag will be used; if no
+other parts are present in your message a single part tag will be used.
+This way, message mode will do the Right Thing (TM) with
+signed/encrypted multipart messages.
+
+Since signing and especially encryption often is used when sensitive
+information is sent, you may want to have some way to ensure that your
+mail is actually signed or encrypted. After invoking the above
+sign/encrypt commands, it is possible to preview the raw article by
+using @kbd{C-u C-c RET P} (@code{mml-preview}). Then you can
+verify that your long rant about what your ex-significant other or
+whomever actually did with that funny looking person at that strange
+party the other night, actually will be sent encrypted.
+
+@emph{Note!} Neither @acronym{PGP/MIME} nor @acronym{S/MIME} encrypt/signs
+RFC822 headers. They only operate on the @acronym{MIME} object. Keep this
+in mind before sending mail with a sensitive Subject line.
+
+By default, when encrypting a message, Gnus will use the
+``signencrypt'' mode, which means the message is both signed and
+encrypted. If you would like to disable this for a particular
+message, give the @code{mml-secure-message-encrypt-*} command a prefix
+argument, e.g., @kbd{C-u C-c C-m c p}.
+
+Actually using the security commands above is not very difficult. At
+least not compared with making sure all involved programs talk with each
+other properly. Thus, we now describe what external libraries or
+programs are required to make things work, and some small general hints.
+
+@node Using S/MIME
+@subsection Using S/MIME
+
+@emph{Note!} This section assume you have a basic familiarity with
+modern cryptography, @acronym{S/MIME}, various PKCS standards, OpenSSL and
+so on.
+
+The @acronym{S/MIME} support in Message (and @acronym{MML}) require
+OpenSSL. OpenSSL performs the actual @acronym{S/MIME} sign/encrypt
+operations. OpenSSL can be found at @uref{http://www.openssl.org/}.
+OpenSSL 0.9.6 and later should work. Version 0.9.5a cannot extract mail
+addresses from certificates, and it insert a spurious CR character into
+@acronym{MIME} separators so you may wish to avoid it if you would like
+to avoid being regarded as someone who send strange mail. (Although by
+sending @acronym{S/MIME} messages you've probably already lost that
+contest.)
+
+To be able to send encrypted mail, a personal certificate is not
+required. Message (@acronym{MML}) need a certificate for the person to whom you
+wish to communicate with though. You're asked for this when you type
+@kbd{C-c C-m c s}. Currently there are two ways to retrieve this
+certificate, from a local file or from DNS. If you chose a local
+file, it need to contain a X.509 certificate in @acronym{PEM} format.
+If you chose DNS, you're asked for the domain name where the
+certificate is stored, the default is a good guess. To my belief,
+Message (@acronym{MML}) is the first mail agent in the world to support
+retrieving @acronym{S/MIME} certificates from DNS, so you're not
+likely to find very many certificates out there. At least there
+should be one, stored at the domain @code{simon.josefsson.org}. LDAP
+is a more popular method of distributing certificates, support for it
+is planned. (Meanwhile, you can use @code{ldapsearch} from the
+command line to retrieve a certificate into a file and use it.)
+
+As for signing messages, OpenSSL can't perform signing operations
+without some kind of configuration. Especially, you need to tell it
+where your private key and your certificate is stored. @acronym{MML}
+uses an Emacs interface to OpenSSL, aptly named @code{smime.el}, and it
+contain a @code{custom} group used for this configuration. So, try
+@kbd{M-x customize-group RET smime RET} and look around.
+
+Currently there is no support for talking to a CA (or RA) to create
+your own certificate. None is planned either. You need to do this
+manually with OpenSSL or using some other program. I used Netscape
+and got a free @acronym{S/MIME} certificate from one of the big CA's on the
+net. Netscape is able to export your private key and certificate in
+PKCS #12 format. Use OpenSSL to convert this into a plain X.509
+certificate in PEM format as follows.
+
+@example
+$ openssl pkcs12 -in ns.p12 -clcerts -nodes > key+cert.pem
+@end example
+
+The @file{key+cert.pem} file should be pointed to from the
+@code{smime-keys} variable. You should now be able to send signed mail.
+
+@emph{Note!} Your private key is now stored unencrypted in the file,
+so take care in handling it. Storing encrypted keys on the disk are
+supported, and Gnus will ask you for a passphrase before invoking
+OpenSSL. Read the OpenSSL documentation for how to achieve this. If
+you use unencrypted keys (e.g., if they are on a secure storage, or if
+you are on a secure single user machine) simply press @code{RET} at
+the passphrase prompt.
+
+@node Using PGP/MIME
+@subsection Using PGP/MIME
+
+@acronym{PGP/MIME} requires an external OpenPGP implementation, such
+as @uref{http://www.gnupg.org/, GNU Privacy Guard}. Pre-OpenPGP
+implementations such as PGP 2.x and PGP 5.x are also supported. One
+Emacs interface to the PGP implementations, PGG (@pxref{Top, ,PGG,
+pgg, PGG Manual}), is included, but Mailcrypt and Florian Weimer's
+@code{gpg.el} are also supported. @xref{PGP Compatibility}.
+
+@cindex gpg-agent
+Message internally calls GnuPG (the @command{gpg} command) to perform
+data encryption, and in certain cases (decrypting or signing for
+example), @command{gpg} requires user's passphrase. Currently the
+recommended way to supply your passphrase to @command{gpg} is to use the
+@command{gpg-agent} program.
+
+To use @command{gpg-agent} in Emacs, you need to run the following
+command from the shell before starting Emacs.
+
+@example
+eval `gpg-agent --daemon`
+@end example
+
+This will invoke @command{gpg-agent} and set the environment variable
+@code{GPG_AGENT_INFO} to allow @command{gpg} to communicate with it.
+It might be good idea to put this command in your @file{.xsession} or
+@file{.bash_profile}. @xref{Invoking GPG-AGENT, , , gnupg, Using the
+GNU Privacy Guard}.
+
+Once your @command{gpg-agent} is set up, it will ask you for a
+passphrase as needed for @command{gpg}. Under the X Window System,
+you will see a new passphrase input dialog appear. The dialog is
+provided by PIN Entry (the @command{pinentry} command), and as of
+version 0.7.2, @command{pinentry} cannot cooperate with Emacs on a
+single tty. So, if you are using a text console, you may need to put
+a passphrase into gpg-agent's cache beforehand. The following command
+does the trick.
+
+@example
+gpg --use-agent --sign < /dev/null > /dev/null
+@end example
+
+The Lisp variable @code{pgg-gpg-use-agent} controls whether to use
+@command{gpg-agent}. See also @xref{Caching passphrase, , , pgg, The
+PGG Manual}.
+
+
+@node PGP Compatibility
+@subsection Compatibility with older implementations
+
+@vindex gpg-temp-directory
+Note, if you are using the @code{gpg.el} you must make sure that the
+directory specified by @code{gpg-temp-directory} have permissions
+0700.
+
+Creating your own key is described in detail in the documentation of
+your PGP implementation, so we refer to it.
+
+If you have imported your old PGP 2.x key into GnuPG, and want to send
+signed and encrypted messages to your fellow PGP 2.x users, you'll
+discover that the receiver cannot understand what you send. One
+solution is to use PGP 2.x instead (i.e., if you use @code{pgg}, set
+@code{pgg-default-scheme} to @code{pgp}). If you do want to use
+GnuPG, you can use a compatibility script called @code{gpg-2comp}
+available from
+@uref{http://muppet.faveve.uni-stuttgart.de/~gero/gpg-2comp/}. You
+could also convince your fellow PGP 2.x users to convert to GnuPG.
+@vindex mml-signencrypt-style-alist
+As a final workaround, you can make the sign and encryption work in
+two steps; separately sign, then encrypt a message. If you would like
+to change this behavior you can customize the
+@code{mml-signencrypt-style-alist} variable. For example:
+
+@lisp
+(setq mml-signencrypt-style-alist '(("smime" separate)
+ ("pgp" separate)
+ ("pgpauto" separate)
+ ("pgpmime" separate)))
+@end lisp
+
+This causes to sign and encrypt in two passes, thus generating a
+message that can be understood by PGP version 2.
+
+(Refer to @uref{http://www.gnupg.org/gph/en/pgp2x.html} for more
+information about the problem.)
+
+@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
+@vindex message-elide-ellipsis
+Elide the text between point and mark (@code{message-elide-region}).
+The text is killed and replaced with the contents of the variable
+@code{message-elide-ellipsis}. The default value is to use an ellipsis
+(@samp{[...]}).
+
+@item C-c C-z
+@kindex C-c C-z
+@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
+@findex 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 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.
+
+@item TAB
+@kindex TAB
+@findex message-tab
+@vindex message-tab-body-function
+If @code{message-tab-body-function} is non-@code{nil}, execute the
+function it specifies. Otherwise use the function bound to @kbd{TAB} in
+@code{text-mode-map} or @code{global-map}.
+
+@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 Spelling
+@section Spelling
+@cindex spelling
+@findex ispell-message
+
+There are two popular ways to have Emacs spell-check your messages:
+@code{ispell} and @code{flyspell}. @code{ispell} is the older and
+probably more popular package. You typically first write the message,
+and then run the entire thing through @code{ispell} and fix all the
+typos. To have this happen automatically when you send a message, put
+something like the following in your @file{.emacs} file:
+
+@lisp
+(add-hook 'message-send-hook 'ispell-message)
+@end lisp
+
+@vindex ispell-message-dictionary-alist
+If you're in the habit of writing in different languages, this can be
+controlled by the @code{ispell-message-dictionary-alist} variable:
+
+@lisp
+(setq ispell-message-dictionary-alist
+ '(("^Newsgroups:.*\\bde\\." . "deutsch8")
+ (".*" . "default")))
+@end lisp
+
+@code{ispell} depends on having the external @samp{ispell} command
+installed.
+
+The other popular method is using @code{flyspell}. This package checks
+your spelling while you're writing, and marks any mis-spelled words in
+various ways.
+
+To use @code{flyspell}, put something like the following in your
+@file{.emacs} file:
+
+@lisp
+(defun my-message-setup-routine ()
+ (flyspell-mode 1))
+(add-hook 'message-setup-hook 'my-message-setup-routine)
+@end lisp
+
+@code{flyspell} depends on having the external @samp{ispell} command
+installed.
+
+
+@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.
+* Insertion Variables:: Customizing how things are inserted.
+* 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 @code{t}, generate all required headers before starting to
+compose the message. This can also be a list of headers to generate:
+
+@lisp
+(setq message-generate-headers-first
+ '(References))
+@end lisp
+
+@vindex message-required-headers
+The variables @code{message-required-headers},
+@code{message-required-mail-headers} and
+@code{message-required-news-headers} specify which headers are
+required.
+
+Note that some headers will be removed and re-generated before posting,
+because of the variable @code{message-deletable-headers} (see below).
+
+@item message-draft-headers
+@vindex message-draft-headers
+When running Message from Gnus, the message buffers are associated
+with a draft group. @code{message-draft-headers} says which headers
+should be generated when a draft is written to the draft group.
+
+@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
+@cindex Aw
+@cindex Sv
+@cindex Re
+Responses to messages have subjects that start with @samp{Re: }. This
+is @emph{not} an abbreviation of the English word ``response'', but is
+Latin, and means ``in response to''. Some illiterate nincompoops have
+failed to grasp this fact, and have ``internationalized'' their software
+to use abominations 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.
+
+Here's an example of a value to deal with these headers when
+responding to a message:
+
+@lisp
+(setq message-subject-re-regexp
+ (concat
+ "^[ \t]*"
+ "\\("
+ "\\("
+ "[Aa][Nn][Tt][Ww]\\.?\\|" ; antw
+ "[Aa][Ww]\\|" ; aw
+ "[Ff][Ww][Dd]?\\|" ; fwd
+ "[Oo][Dd][Pp]\\|" ; odp
+ "[Rr][Ee]\\|" ; re
+ "[Rr][\311\351][Ff]\\.?\\|" ; ref
+ "[Ss][Vv]" ; sv
+ "\\)"
+ "\\(\\[[0-9]*\\]\\)"
+ "*:[ \t]*"
+ "\\)"
+ "*[ \t]*"
+ ))
+@end lisp
+
+@item message-subject-trailing-was-query
+@vindex message-subject-trailing-was-query
+@vindex message-subject-trailing-was-ask-regexp
+@vindex message-subject-trailing-was-regexp
+Controls what to do with trailing @samp{(was: <old subject>)} in subject
+lines. If @code{nil}, leave the subject unchanged. If it is the symbol
+@code{ask}, query the user what to do. In this case, the subject is
+matched against @code{message-subject-trailing-was-ask-regexp}. If
+@code{message-subject-trailing-was-query} is @code{t}, always strip the
+trailing old subject. In this case,
+@code{message-subject-trailing-was-regexp} is used.
+
+@item message-alternative-emails
+@vindex message-alternative-emails
+Regexp matching alternative email addresses. The first address in the
+To, Cc or From headers of the original article matching this variable is
+used as the From field of outgoing messages, replacing the default From
+value.
+
+For example, if you have two secondary email addresses john@@home.net
+and john.doe@@work.com and want to use them in the From field when
+composing a reply to a message addressed to one of them, you could set
+this variable like this:
+
+@lisp
+(setq message-alternative-emails
+ (regexp-opt '("john@@home.net" "john.doe@@work.com")))
+@end lisp
+
+This variable has precedence over posting styles and anything that runs
+off @code{message-setup-hook}.
+
+@item message-allow-no-recipients
+@vindex message-allow-no-recipients
+Specifies what to do when there are no recipients other than
+@code{Gcc} or @code{Fcc}. If it is @code{always}, the posting is
+allowed. If it is @code{never}, the posting is not allowed. If it is
+@code{ask} (the default), you are prompted.
+
+@item message-hidden-headers
+@vindex message-hidden-headers
+A regexp, a list of regexps, or a list where the first element is
+@code{not} and the rest are regexps. It says which headers to keep
+hidden when composing a message.
+
+@lisp
+(setq message-hidden-headers
+ '(not "From" "Subject" "To" "Cc" "Newsgroups"))
+@end lisp
+
+@item message-header-synonyms
+@vindex message-header-synonyms
+A list of lists of header synonyms. E.g., if this list contains a
+member list with elements @code{Cc} and @code{To}, then
+@code{message-carefully-insert-headers} will not insert a @code{To}
+header when the message is already @code{Cc}ed to the recipient.
+
+@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 Subject Date (optional . In-Reply-To) Message-ID
+(optional . User-Agent))} 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:\\|^Xref:\\|^X-Draft-From:\\|@*
+^X-Gnus-Agent-Meta-Information:}.
+
+@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
+@findex message-send-mail-with-sendmail
+@findex message-send-mail-with-mh
+@findex message-send-mail-with-qmail
+@findex message-smtpmail-send-it
+@findex smtpmail-send-it
+@findex feedmail-send-it
+Function used to send the current buffer as mail. The default is
+@code{message-send-mail-with-sendmail}. Other valid values include
+@code{message-send-mail-with-mh}, @code{message-send-mail-with-qmail},
+@code{message-smtpmail-send-it}, @code{smtpmail-send-it} and
+@code{feedmail-send-it}.
+
+@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.
+
+@item message-qmail-inject-program
+@vindex message-qmail-inject-program
+@cindex qmail
+Location of the qmail-inject program.
+
+@item message-qmail-inject-args
+@vindex message-qmail-inject-args
+Arguments passed to qmail-inject programs.
+This should be a list of strings, one string for each argument. It
+may also be a function.
+
+For e.g., if you wish to set the envelope sender address so that bounces
+go to the right place or to deal with listserv's usage of that address, you
+might set this variable to @code{'("-f" "you@@some.where")}.
+
+@item message-sendmail-f-is-evil
+@vindex message-sendmail-f-is-evil
+@cindex sendmail
+Non-@code{nil} means don't add @samp{-f username} to the sendmail
+command line. Doing so would be even more evil than leaving it out.
+
+@item message-sendmail-envelope-from
+@vindex message-sendmail-envelope-from
+When @code{message-sendmail-f-is-evil} is @code{nil}, this specifies
+the address to use in the @acronym{SMTP} envelope. If it is
+@code{nil}, use @code{user-mail-address}. If it is the symbol
+@code{header}, use the @samp{From} header of the message.
+
+@item message-mailer-swallows-blank-line
+@vindex message-mailer-swallows-blank-line
+Set this to non-@code{nil} if the system's mailer runs the header and
+body together. (This problem exists on SunOS 4 when sendmail is run
+in remote mode.) The value should be an expression to test whether
+the problem will actually occur.
+
+@item message-send-mail-partially-limit
+@vindex message-send-mail-partially-limit
+@cindex split large message
+The limitation of messages sent as message/partial. The lower bound
+of message size in characters, beyond which the message should be sent
+in several parts. If it is @code{nil}, the size is unlimited.
+
+@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
+@vindex message-user-organization
+@vindex message-user-organization-file
+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 message-user-fqdn
+@vindex mail-host-address
+@vindex user-mail-address
+@findex system-name
+@cindex Sun
+@cindex i-did-not-set--mail-host-address--so-tickle-me
+This required header will be generated by Message. A unique ID will be
+created based on the date, time, user name (for the local part) and the
+domain part. For the domain part, message will look (in this order) at
+@code{message-user-fqdn}, @code{system-name}, @code{mail-host-address}
+and @code{message-user-mail-address} (i.e. @code{user-mail-address})
+until a probably valid fully qualified domain name (FQDN) was found.
+
+@item User-Agent
+@cindex User-Agent
+This optional header will be filled out according to the
+@code{message-newsreader} local variable.
+
+@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
+@vindex message-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
+@vindex message-distribution-function
+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
+@vindex message-user-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 @sc{car} of this cons
+should be a symbol. This symbol's name is the name of the header, and
+the @sc{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 @sc{car} of the cons is
+@code{optional}, the @sc{cdr} of this cons will only be inserted if it is
+non-@code{nil}.
+
+If you want to delete an entry from this list, the following Lisp
+snippet might be useful. Adjust accordingly if you want to remove
+another element.
+
+@lisp
+(setq message-required-news-headers
+ (delq 'Message-ID message-required-news-headers))
+@end lisp
+
+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 approved
+@cindex approved
+Check whether the article has an @code{Approved} header, which is
+something only moderators should include.
+@item continuation-headers
+Check whether there are continuation header lines that don't begin with
+whitespace.
+@item control-chars
+Check for invalid characters.
+@item empty
+Check whether the article is empty.
+@item existing-newsgroups
+Check whether the newsgroups mentioned in the @code{Newsgroups} and
+@code{Followup-To} headers exist.
+@item from
+Check whether the @code{From} header seems nice.
+@item illegible-text
+Check whether there is any non-printable character in the body.
+@item invisible-text
+Check whether there is any invisible text in the buffer.
+@item long-header-lines
+Check for too long header lines.
+@item long-lines
+@cindex long lines
+Check for too long lines in the body.
+@item message-id
+Check whether the @code{Message-ID} looks syntactically ok.
+@item multiple-headers
+Check for the existence of multiple equal headers.
+@item new-text
+Check whether there is any new text in the messages.
+@item newsgroups
+Check whether the @code{Newsgroups} header exists and is not empty.
+@item quoting-style
+Check whether text follows last quoted portion.
+@item repeated-newsgroups
+Check whether the @code{Newsgroups} and @code{Followup-to} headers
+contains repeated group names.
+@item reply-to
+Check whether the @code{Reply-To} header looks ok.
+@item sender
+@cindex Sender
+Insert a new @code{Sender} header if the @code{From} header looks odd.
+@item sendsys
+@cindex sendsys
+Check for the existence of version and sendsys commands.
+@item shoot
+Check whether the domain part of the @code{Message-ID} header looks ok.
+@item shorten-followup-to
+Check whether to add a @code{Followup-to} header to shorten the number
+of groups to post to.
+@item signature
+Check the length of the signature.
+@item size
+Check for excessive size.
+@item subject
+Check whether the @code{Subject} header exists and is not empty.
+@item subject-cmsg
+Check the subject for commands.
+@item valid-newsgroups
+Check whether the @code{Newsgroups} and @code{Followup-to} headers
+are valid syntactically.
+@end table
+
+All these conditions are checked by default, except for @code{sender}
+for which the check is disabled by default if
+@code{message-insert-canlock} is non-@code{nil} (@pxref{Canceling News}).
+
+@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:\\|@*
+^X-Draft-From:\\|^X-Gnus-Agent-Meta-Information:}.
+
+@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 Insertion Variables
+@section Insertion Variables
+
+@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-cite-prefix-regexp
+@vindex message-cite-prefix-regexp
+Regexp matching the longest possible citation prefix on a line.
+
+@item message-citation-line-function
+@vindex message-citation-line-function
+@cindex attribution line
+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.
+
+Note that Gnus provides a feature where clicking on `writes:' hides the
+cited text. If you change the citation line too much, readers of your
+messages will have to adjust their Gnus, too. See the variable
+@code{gnus-cite-attribution-suffix}. @xref{Article Highlighting, ,
+Article Highlighting, gnus, The Gnus Manual}, for details.
+
+@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 line you yank will have
+@code{message-yank-prefix} prepended to it (except for quoted and
+empty lines which uses @code{message-yank-cited-prefix}). The default
+is @samp{> }.
+
+@item message-yank-cited-prefix
+@vindex message-yank-cited-prefix
+@cindex yanking
+@cindex cited
+@cindex quoting
+When yanking text from an article which contains no text or already
+cited text, each line will be prefixed with the contents of this
+variable. The default is @samp{>}. See also
+@code{message-yank-prefix}.
+
+@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-mark-insert-begin
+@vindex message-mark-insert-begin
+String to mark the beginning of some inserted text.
+
+@item message-mark-insert-end
+@vindex message-mark-insert-end
+String to mark the end of some inserted text.
+
+@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 @file{~/.signature}.
+
+@item message-signature-insert-empty-line
+@vindex message-signature-insert-empty-line
+If @code{t} (the default value) an empty line is inserted before the
+signature separator.
+
+@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 @acronym{ASCII} graphics is an efficient way to get
+everybody to believe that you are silly and have nothing important to
+say.
+
+
+@node Various Message Variables
+@section Various Message Variables
+
+@table @code
+@item message-default-charset
+@vindex message-default-charset
+@cindex charset
+Symbol naming a @acronym{MIME} charset. Non-@acronym{ASCII} characters
+in messages are assumed to be encoded using this charset. The default
+is @code{iso-8859-1} on non-@sc{mule} Emacsen; otherwise @code{nil},
+which means ask the user. (This variable is used only on non-@sc{mule}
+Emacsen.) @xref{Charset Translation, , Charset Translation, emacs-mime,
+Emacs MIME Manual}, for details on the @sc{mule}-to-@acronym{MIME}
+translation process.
+
+@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/}.
+All other mail file variables are derived from @code{message-directory}.
+
+@item message-auto-save-directory
+@vindex message-auto-save-directory
+Directory where Message auto-saves buffers if Gnus isn't running. If
+@code{nil}, Message won't auto-save. The default is @file{~/Mail/drafts/}.
+
+@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 "X-In-No-Sense: Nonsense")
+ (message-add-header "X-Whatever: no"))
+@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. This hook is run very late --
+just before the message is actually sent as mail.
+
+@item message-send-news-hook
+@vindex message-send-news-hook
+Hook run before sending news messages. This hook is run very late --
+just before the message is actually sent as news.
+
+@item message-sent-hook
+@vindex message-sent-hook
+Hook run after sending messages.
+
+@item message-cancel-hook
+@vindex message-cancel-hook
+Hook run when canceling news articles.
+
+@item message-mode-syntax-table
+@vindex message-mode-syntax-table
+Syntax table used in message mode buffers.
+
+@item message-strip-special-text-properties
+@vindex message-strip-special-text-properties
+Emacs has a number of special text properties which can break message
+composing in various ways. If this option is set, message will strip
+these properties from the message composition buffer. However, some
+packages requires these properties to be present in order to work. If
+you use one of these packages, turn this option off, and hope the
+message composition doesn't break too bad.
+
+@item message-send-method-alist
+@vindex message-send-method-alist
+@findex message-mail-p
+@findex message-news-p
+@findex message-send-via-mail
+@findex message-send-via-news
+Alist of ways to send outgoing messages. Each element has the form:
+
+@lisp
+(@var{type} @var{predicate} @var{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}. The function will be called in
+the buffer where the message is.
+
+@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
+
+The default is:
+
+@lisp
+((news message-news-p message-send-via-news)
+ (mail message-mail-p message-send-via-mail))
+@end lisp
+
+The @code{message-news-p} function returns non-@code{nil} if the message
+looks like news, and the @code{message-send-via-news} function sends the
+message according to the @code{message-send-news-function} variable
+(@pxref{News Variables}). The @code{message-mail-p} function returns
+non-@code{nil} if the message looks like mail, and the
+@code{message-send-via-mail} function sends the message according to the
+@code{message-send-mail-function} variable (@pxref{Mail Variables}).
+
+All the elements in this alist will be tried in order, so a message
+containing both a valid @samp{Newsgroups} header and a valid @samp{To}
+header, for example, will be sent as news, and then as mail.
+@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"}.
+
+@item message-fcc-externalize-attachments
+@vindex message-fcc-externalize-attachments
+If @code{nil}, attach files as normal parts in Fcc copies; if it is
+non-@code{nil}, attach local files as external parts.
+
+@item message-interactive
+@vindex message-interactive
+If non-@code{nil} wait for and display errors when sending a message;
+if @code{nil} let the mailer mail back a message to report errors.
+
+@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
+Controls whether to create a new message buffer to compose a message.
+Valid values include:
+
+@table @code
+@item nil
+Generate the buffer name in the Message way (e.g., *mail*, *news*, *mail
+to whom*, *news on group*, etc.) and continue editing in the existing
+buffer of that name. If there is no such buffer, it will be newly
+created.
+
+@item unique
+@item t
+Create the new buffer with the name generated in the Message way. This
+is the default.
+
+@item unsent
+Similar to @code{unique} but the buffer name begins with "*unsent ".
+
+@item standard
+Similar to @code{nil} but the buffer name is simpler like *mail
+message*.
+@end table
+@table @var
+@item function
+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.
+@end table
+
+The default value is @code{unique}.
+
+@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
+@sc{car} is a function and the @sc{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 @file{.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 GNU Free Documentation License
+@chapter GNU Free Documentation License
+@include doclicense.texi
+
+@node Index
+@chapter Index
+@printindex cp
+
+@node Key Index
+@chapter Key Index
+@printindex ky
+
+@summarycontents
+@contents
+@bye
+
+@c End:
+
+@ignore
+ arch-tag: 16ab76af-a281-4e34-aed6-5624569f7601
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c
+@c Note: This document requires makeinfo version 4.6 or greater to build.
+@c
+@c %**start of header
+@setfilename ../info/mh-e
+@settitle The MH-E Manual
+@c %**end of header
+
+@c Version of the software and manual.
+@set VERSION 8.0.3
+@c Edition of the manual. It is either empty for the first edition or
+@c has the form ", nth Edition" (without the quotes).
+@set EDITION
+@set UPDATED 2006-11-12
+@set UPDATE-MONTH November, 2006
+
+@c Other variables.
+@set MH-BOOK-HOME http://rand-mh.sourceforge.net/book/mh
+@set MH-E-HOME http://mh-e.sourceforge.net/
+
+@c Copyright
+@copying
+This is version @value{VERSION}@value{EDITION} of @cite{The MH-E
+Manual}, last updated @value{UPDATED}.
+
+Copyright @copyright{} 1995, 2001, 2002, 2003, 2005, 2006, 2007 Free
+Software Foundation, Inc.
+
+@quotation
+The MH-E manual is free documentation; you can redistribute it and/or
+modify it under the terms of either:
+
+@enumerate a
+@item
+the GNU Free Documentation License, Version 1.2 or any later version
+published by the Free Software Foundation; with no Invariant Sections,
+no Front-Cover Texts, and no Back-Cover Texts.
+
+@item
+the GNU General Public License as published by the Free Software
+Foundation; either version 3, or (at your option) any later version.
+@end enumerate
+
+The MH-E manual 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 or GNU Free Documentation License for more
+details.
+
+The GNU General Public License and the GNU Free Documentation License
+appear as appendices to this document. You may also request copies by
+writing to the Free Software Foundation, Inc., 51 Franklin Street,
+Fifth Floor, Boston, MA 02110-1301, USA.
+@end quotation
+@end copying
+
+@c Info Directory Entry
+@dircategory Emacs
+@direntry
+* MH-E: (mh-e). Emacs interface to the MH mail system.
+@end direntry
+
+@c Title Page
+@setchapternewpage odd
+@titlepage
+@title The MH-E Manual
+@subtitle Version @value{VERSION}@value{EDITION}
+@subtitle @value{UPDATE-MONTH}
+@author Bill Wohler
+
+@c Copyright Page
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnottex
+@html
+<!--
+@end html
+@node Top, Preface, (dir), (dir)
+@top The MH-E Manual
+@html
+-->
+@end html
+@insertcopying
+@end ifnottex
+
+@c Table of Contents
+@contents
+
+@html
+<!--
+@end html
+
+@menu
+* Preface:: Preface
+* Conventions:: GNU Emacs Terms and Conventions
+* Getting Started:: Getting Started
+* Tour Through MH-E:: Tour Through MH-E
+* Using This Manual:: Using This Manual
+* Incorporating Mail:: Incorporating Mail
+* Reading Mail:: Reading Mail
+* Folders:: Organizing Your Mail with Folders
+* Sending Mail:: Sending Mail
+* Editing Drafts:: Editing a Draft
+* Aliases:: Aliases
+* Identities:: Identities
+* Speedbar:: The Speedbar
+* Menu Bar:: The Menu Bar
+* Tool Bar:: The Tool Bar
+* Searching:: Searching Through Messages
+* Threading:: Viewing Message Threads
+* Limits:: Limiting Display
+* Sequences:: Using Sequences
+* Junk:: Dealing With Junk Mail
+* Miscellaneous:: Miscellaneous Commands, Variables, and Buffers
+* Scan Line Formats:: Scan Line Formats
+* Procmail:: Reading Mailing Lists Effectively
+* Odds and Ends:: Odds and Ends
+* History:: History of MH-E
+* GFDL:: GNU Free Documentation License
+* GPL:: GNU Public License
+* Key Index:: Key (Character) Index
+* Command Index:: Command Index
+* Option Index:: Option (Variable) Index
+* Concept Index:: Concept Index
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Tour Through MH-E
+
+* Sending Mail Tour::
+* Reading Mail Tour::
+* Processing Mail Tour::
+* Leaving MH-E::
+* More About MH-E::
+
+Using This Manual
+
+* Options::
+* Ranges::
+* Folder Selection::
+
+Reading Your Mail
+
+* Viewing::
+* Viewing Attachments::
+* HTML::
+* Digests::
+* Reading PGP::
+* Printing::
+* Files and Pipes::
+* Navigating::
+* Miscellaneous Commands and Options::
+
+Sending Mail
+
+* Composing::
+* Replying::
+* Forwarding::
+* Redistributing::
+* Editing Again::
+
+Editing a Draft
+
+* Editing Message::
+* Inserting Letter::
+* Inserting Messages::
+* Signature::
+* Picture::
+* Adding Attachments::
+* Sending PGP::
+* Checking Recipients::
+* Sending Message::
+* Killing Draft::
+
+Odds and Ends
+
+* Bug Reports::
+* Mailing Lists::
+* MH FAQ and Support::
+* Getting MH-E::
+
+History of MH-E
+
+* From Brian Reid::
+* From Jim Larus::
+* From Stephen Gildea::
+* From Bill Wohler::
+
+@end detailmenu
+@end menu
+
+@html
+-->
+@end html
+
+@node Preface, Conventions, Top, Top
+@unnumbered Preface
+
+@cindex Emacs
+@cindex Unix commands, Emacs
+@cindex preface
+
+This manual introduces another interface to the MH mail system 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.
+
+The MH-E package is distributed with GNU Emacs@footnote{Version
+@value{VERSION} of MH-E will appear in GNU Emacs 22.1. It is supported
+in GNU Emacs 21, as well as XEmacs 21 (except for versions
+21.5.9-21.5.16). It is compatible with MH versions 6.8.4 and higher,
+all versions of nmh, and GNU mailutils 1.0 and higher.}, so you
+shouldn't have to do anything special to use it. This manual covers
+MH-E version @value{VERSION}. To help you decide which version you
+have, see @ref{Getting Started}.
+
+@findex help-with-tutorial
+@kindex C-h t
+
+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}). (To learn about this notation, see
+@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, GNU Emacs Manual},
+@end ifinfo
+@ifhtml
+@uref{http://www.gnu.org/software/emacs/manual/html_node/,
+@cite{GNU Emacs Manual}},
+@end ifhtml
+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.
+
+@cindex @cite{MH & nmh: Email for Users & Programmers}
+@cindex MH book
+@cindex info
+@kindex C-h i
+
+This manual is available in both Info and online formats. The Info
+version is distributed with Emacs and can be accessed with the
+@command{info} command (@samp{info mh-e}) or within Emacs (@kbd{C-h i
+m mh-e @key{RET}}). The online version is available at
+@uref{http://mh-e.sourceforge.net/manual/, SourceForge}. Another great
+online resource is the book @uref{http://www.ics.uci.edu/~mh/book/,
+@cite{MH & nmh: Email for Users & Programmers}} (also known as
+@dfn{the MH book}).
+
+I hope you enjoy this manual! If you have any comments, or suggestions
+for this document, please let me know.
+
+@cindex Bill Wohler
+@cindex Wohler, Bill
+
+@noindent
+Bill Wohler <@i{wohler at newt.com}>@*
+8 February 1995@*
+24 February 2006
+
+@node Conventions, Getting Started, Preface, Top
+@chapter GNU Emacs Terms and Conventions
+
+@cindex Emacs
+@cindex Emacs, conventions
+@cindex Emacs, terms
+@cindex Unix commands, Emacs
+@cindex conventions, Emacs
+@cindex terms, Emacs
+
+If you're an experienced Emacs user, you can skip the following
+conventions and definition of terms and go directly to the next
+section (@pxref{Getting Started}).
+
+@cindex Emacs commands
+@cindex MH commands
+@cindex Unix commands
+@cindex commands
+@cindex commands, MH
+@cindex commands, Unix
+@cindex commands, shell
+@cindex functions
+@cindex shell commands
+
+In general, @dfn{functions} in this text refer to Emacs Lisp functions
+that one would call from within Emacs Lisp programs (for example,
+@code{(mh-inc-folder)}). On the other hand, @dfn{commands} are those
+things that are run by the user, such as @kbd{i} or @kbd{M-x
+mh-inc-folder}. Programs outside of Emacs are specifically called MH
+commands, shell commands, or Unix commands.
+
+@cindex conventions, key names
+@cindex key names
+
+The conventions for key names are as follows:
+
+@table @kbd
+@item C-x
+Hold down the @key{CTRL} (Control) key and press the @kbd{x} key.
+@c -------------------------
+@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}, and then pressing the @kbd{x} key.
+@c -------------------------
+@item @key{RET}
+Press the @key{RETURN} or @key{ENTER} key. This is normally used to
+complete a command.
+@c -------------------------
+@item @key{SPC}
+Press the space bar.
+@c -------------------------
+@item @key{TAB}
+Press the @key{TAB} key.
+@c -------------------------
+@item @key{DEL}
+Press the @key{DELETE} key.
+@c -------------------------
+@item @key{BS}
+Press the @key{BACKSPACE} key@footnote{If you are using Version 20 or
+earlier of Emacs, you will need to use the @key{DEL} key.}.
+@end table
+
+@cindex Emacs, prefix argument
+@cindex prefix argument
+@kindex C-u
+
+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 1
+@center @strong{NOTE}
+
+@quotation
+The prefix @kbd{C-u} or @kbd{M-} is not necessary in MH-E's MH-Folder
+mode (@pxref{Reading Mail Tour}). In this mode, simply enter the
+numerical argument before entering the command.
+@end quotation
+@sp 1
+
+@cindex @file{.emacs}
+@cindex Emacs, variables
+@cindex files, @file{.emacs}
+@cindex variables
+@findex setq
+
+Emacs uses @dfn{variables} to hold values. These can be changed via
+calls to the function @code{setq} in @file{~/.emacs}.
+
+@cindex Emacs, options
+@cindex options
+@findex customize-group
+@findex customize-option
+
+Variables in MH-E that are normally modified by the user are called
+@dfn{options} and are modified through the customize functions (such
+as @kbd{M-x customize-option} or @kbd{M-x customize-group}).
+@ifnothtml
+@xref{Easy Customization,,,emacs,The GNU Emacs Manual}, in @cite{The
+GNU Emacs Manual}.
+@end ifnothtml
+@ifhtml
+See section
+@uref{http://www.gnu.org/software/emacs/manual/html_node/Easy-Customization.html,
+Easy Customization} in @cite{The GNU Emacs Manual}.
+@end ifhtml
+@xref{Options}.
+
+@cindex Emacs, faces
+@cindex faces
+@cindex highlighting
+@findex customize-face
+
+You can specify various styles for displaying text using @dfn{faces}.
+MH-E provides a set of faces that you can use to personalize the look
+of your MH-E buffers. Use the command @kbd{M-x customize-face} to do
+this.
+@ifnothtml
+@xref{Face Customization,,,emacs,The GNU Emacs Manual}, in @cite{The
+GNU Emacs Manual}.
+@end ifnothtml
+@ifhtml
+See section
+@uref{http://www.gnu.org/software/emacs/manual/html_node/Face-Customization.html,
+Face Customization} in @cite{The GNU Emacs Manual}.
+@end ifhtml
+
+@cindex abnormal hooks
+@cindex hooks
+@cindex normal hooks
+@findex add-hook
+@findex customize-option
+
+Commands often offer @dfn{hooks} which enable you to extend or modify
+the way a command works.
+@ifnothtml
+@ref{Hooks, , Hooks, emacs, The GNU Emacs Manual}, in @cite{The GNU
+Emacs Manual}
+@end ifnothtml
+@ifhtml
+See section
+@uref{http://www.gnu.org/software/emacs/manual/html_node/Hooks.html,
+Hooks} in @cite{The GNU Emacs Manual}
+@end ifhtml
+for a description about @dfn{normal hooks} and @dfn{abnormal hooks}.
+MH-E uses normal hooks in nearly all cases, so you can assume that we
+are talking about normal hooks unless we explicitly mention that a
+hook is abnormal. We also follow the conventions described in that
+section: the name of the abnormal hooks end in @code{-hooks} and all
+the rest of the MH-E hooks end in @code{-hook}. You can add hooks with
+either @code{customize-option} or @code{add-hook}.
+
+@cindex Emacs, mark
+@cindex Emacs, point
+@cindex Emacs, region
+@cindex mark
+@cindex point
+@cindex region
+@kindex C-@@
+@kindex C-@key{SPC}
+
+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-@key{SPC}}).
+
+@cindex completion
+@cindex Emacs, completion
+@cindex Emacs, file completion
+@cindex Emacs, folder completion
+@cindex Emacs, minibuffer
+@cindex file completion
+@cindex folder completion
+@cindex minibuffer
+@kindex SPC
+@kindex TAB
+
+The @dfn{minibuffer} is the bottom line of the Emacs window, where all
+prompting and multiple-character input is directed. You can use
+@dfn{completion} to enter values such as folders. Completion means
+that Emacs fills in text for you when you type @key{SPC} or @key{TAB}.
+A second @key{SPC} or @key{TAB} will list all possibilities at that
+point.
+@ifnothtml
+@xref{Completion, , Completion, emacs, The GNU Emacs Manual}.
+@end ifnothtml
+@ifhtml
+See the section
+@uref{http://www.gnu.org/software/emacs/manual/html_node/Completion.html,
+Completion} in @cite{The GNU Emacs Manual}.
+@end ifhtml
+Note that @key{SPC} cannot be used for completing filenames and
+folders.
+
+@findex help-with-tutorial
+@kindex C-h t
+@kindex M-x
+
+The minibuffer is also where you enter Emacs function names after
+typing @kbd{M-x}. For example, in the preface, 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 ~
+
+The @samp{~} notation in filenames represents your home directory.
+This notation is used by many shells including @command{bash},
+@code{tcsh}, and @command{csh}. It is analogous to the environment
+variable @samp{$HOME}. For example, @file{~/.emacs} can be written
+@file{$HOME/.emacs} or using the absolute path as in
+@file{/home/wohler/.emacs} instead.
+
+@cindex Emacs, interrupting
+@cindex Emacs, quitting
+@cindex interrupting
+@cindex 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, Tour Through MH-E, Conventions, Top
+@chapter Getting Started
+
+@cindex MH-E, versions
+@cindex history
+@cindex versions of MH-E
+
+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 8}
+which is pretty close to @w{Version 6} and @w{Version 7}. It differs
+from @w{Version 4} and @w{Version 5} and is vastly different from
+@w{Version 3}. @xref{History}.
+
+@findex mh-version
+
+To determine which version of MH-E that you have, enter @kbd{M-x
+mh-version @key{RET}}. Hopefully it says that you're running
+@w{Version @value{VERSION}} which is the latest version as of this
+printing.
+
+If your version is much older than this, please consider upgrading.
+You can have your system administrator upgrade the system-wide
+version, or you can install your own personal version. It's really
+quite easy. @xref{Getting MH-E}, for instructions for getting and
+installing MH-E.
+
+If the @code{mh-version} command displays @samp{No MH variant
+detected}@footnote{In very old versions of MH-E, you may get the error
+message, @samp{Cannot find the commands `inc' and `mhl' and the file
+`components'} if MH-E can't find MH. In this case, you need to update
+MH-E, and you may need to install MH too. However, newer versions of
+MH-E are better at finding MH if it is on your system.}, then you need
+to install MH or tell MH-E where to find MH.
+
+@cindex Debian
+@cindex nmh
+@cindex GNU mailutils
+
+If you don't have MH on your system already, you must install a
+variant of MH. The Debian mh-e package does this for you automatically
+(@pxref{Getting MH-E}). Most people use
+@uref{http://www.nongnu.org/nmh/, nmh}, but you may be interested in
+trying out @uref{http://www.gnu.org/software/mailutils/, GNU
+mailutils}, which supports IMAP. Your GNU/Linux distribution probably
+has packages for both of these.
+
+@cindex @command{install-mh}
+@cindex MH commands, @command{install-mh}
+@cindex MH book
+
+If you've never run MH before, you need to run @command{install-mh}
+from the shell before you continue. This sets up your personal MH
+environment@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/../overall/setup.html, Setting Up MH} in the
+MH book.}. If you don't, you'll be greeted with the error message:
+@samp{Install MH and run install-mh before running MH-E}. This is all
+you need to know about MH to use MH-E, but the more you know about MH,
+the more you can leverage its power. See the
+@uref{@value{MH-BOOK-HOME}/../, MH book} to learn more about MH.
+
+@cindex @samp{Path:} MH profile component
+@cindex MH profile
+@cindex MH profile component
+@cindex MH profile component, @samp{Path:}
+
+Your MH environment includes your @dfn{MH profile} which is found in
+the file @file{~/.mh_profile}. This file contains a number of @dfn{MH
+profile components}. For example, the @samp{Path:} MH profile
+component contains the path to your mail directory, which is
+@file{~/Mail} by default.
+
+@cindex @command{mhparam}
+@cindex MH commands, @command{mhparam}
+@vindex exec-path
+@vindex mh-path
+@vindex mh-sys-path
+@vindex mh-variant
+@vindex mh-variant-in-use
+
+There are several options MH-E uses to interact with your MH
+installation. The option @code{mh-variant} specifies the variant used
+by MH-E (@pxref{Options}). The default setting of this option is
+@samp{Auto-detect} which means that MH-E will automatically choose the
+first of nmh, MH, or GNU mailutils that it finds in the directories
+listed in @code{mh-path} (which you can customize),
+@code{mh-sys-path}, and @code{exec-path}. If MH-E can't find MH at
+all, you may have to customize @code{mh-path} and add the directory in
+which the command @command{mhparam} is located. If, on the other hand,
+you have both nmh and mailutils installed (for example) and
+@code{mh-variant-in-use} was initialized to nmh but you want to use
+mailutils, then you can set @code{mh-variant} to @samp{mailutils}.
+
+@vindex mh-flists-present-flag
+@vindex mh-lib
+@vindex mh-lib-progs
+@vindex mh-progs
+
+When @code{mh-variant} is changed, MH-E resets @code{mh-progs},
+@code{mh-lib}, @code{mh-lib-progs}, @code{mh-flists-present-flag}, and
+@code{mh-variant-in-use} accordingly.
+
+@cindex @file{.emacs}
+@cindex files, @file{.emacs}
+
+@sp 1
+@center @strong{NOTE}
+
+@quotation
+Prior to version 8, it was often necessary to set some of these
+variables in @file{~/.emacs}; now it is no longer necessary and can
+actually cause problems.
+@end quotation
+@sp 1
+
+@cindex MH profile component, @samp{Draft-Folder:}
+@cindex MH profile component, @samp{Path:}
+@cindex MH profile component, @samp{Previous-Sequence:}
+@cindex MH profile component, @samp{Unseen-Sequence:}
+@cindex @samp{Draft-Folder:} MH profile component
+@cindex @samp{Path:} MH profile component
+@cindex @samp{Previous-Sequence:} MH profile component
+@cindex @samp{Unseen-Sequence:} MH profile component
+@findex mh-find-path
+@vindex mh-draft-folder
+@vindex mh-find-path-hook
+@vindex mh-inbox
+@vindex mh-previous-seq
+@vindex mh-unseen-seq
+@vindex mh-user-path
+
+In addition to setting variables that point to MH itself, MH-E also
+sets a handful of variables that point to where you keep your mail.
+During initialization, the function @code{mh-find-path} sets
+@code{mh-user-path} from your @samp{Path:} MH profile component (but
+defaults to @samp{Mail} if one isn't present), @code{mh-draft-folder}
+from @samp{Draft-Folder:}, @code{mh-unseen-seq} from
+@samp{Unseen-Sequence:}, @code{mh-previous-seq} from
+@samp{Previous-Sequence:}, and @code{mh-inbox} from @samp{Inbox:}
+(defaults to @samp{+inbox}). The hook @code{mh-find-path-hook} is run
+after these variables have been set. This hook can be used the change
+the value of these variables if you need to run with different values
+between MH and MH-E.
+
+@node Tour Through MH-E, Using This Manual, Getting Started, Top
+@chapter Tour Through MH-E
+
+@cindex introduction
+@cindex tour
+@cindex tutorial
+
+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
+chapter 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 or adventurous type, read the rest of the manual to be able to
+use all the features of MH-E. I suggest you read this chapter first to
+get the big picture, and then you can read the manual as you wish.
+
+@menu
+* Sending Mail Tour::
+* Reading Mail Tour::
+* Processing Mail Tour::
+* Leaving MH-E::
+* More About MH-E::
+@end menu
+
+@node Sending Mail Tour, Reading Mail Tour, Tour Through MH-E, Tour Through MH-E
+@section Sending Mail
+
+@cindex MH-Letter mode
+@cindex mode
+@cindex modes, MH-Letter
+@cindex sending mail
+@findex mh-smail
+@kindex M-x 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. 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 your login name in the @samp{To:} header field. Press the
+@key{TAB} twice to move the cursor past the @samp{Cc:} field, since no
+carbon copies are to be sent, and on to the @samp{Subject:} field.
+Enter @kbd{Test} or anything else that comes to mind.
+
+Press @key{TAB} again to move the cursor to the body of the message.
+Enter some text, 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 menu bar and a tool bar. I've
+left out the menu bar and tool bar in all of the example screens.}:
+
+@cartouche
+@smallexample
+
+
+
+
+
+
+--:-- *scratch* All L1 (Lisp Interaction)-------------------------
+To: wohler
+cc:
+Subject: Test
+X-Mailer: MH-E 8.0; nmh 1.1; GNU Emacs 22.1
+--------
+This is a test message to get the wheels churning...#
+
+
+--:** @{draft@} All L5 (MH-Letter)----------------------------------
+Type C-c C-c to send message, C-C ? for help
+@end smallexample
+@end cartouche
+@i{MH-E message composition window}
+
+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.
+
+@cindex help
+@findex describe-mode
+@kindex C-c ?
+@kindex C-c C-c
+@kindex C-h m
+
+There are several commands specific to MH-Letter mode@footnote{You can
+get quick help for the commands used most often with @kbd{C-c ?} or
+more complete help with the @kbd{C-h m} (@code{describe-mode})
+command.}, 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 @command{inc}
+@cindex @command{scan}
+@cindex MH commands, @command{inc}
+@cindex MH commands, @command{scan}
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+@cindex reading mail
+@findex mh-rmail
+@kindex M-x mh-rmail
+
+To read the mail you've just sent yourself, enter @kbd{M-x mh-rmail}.
+This incorporates the new mail and puts the output from
+@command{inc}@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next
+prev} in the MH book.} (called @dfn{scan lines} after the MH program
+@command{scan}@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/faswsprs.html, Find and Specify with scan
+pick Ranges Sequences} in the MH book.} which prints a one-line
+summary of each message) into a buffer called @samp{+inbox} whose
+major mode is MH-Folder.
+
+@findex mh-rmail
+@kindex F r
+@kindex M-x mh-rmail
+
+@sp 1
+@center @strong{NOTE}
+
+@quotation
+
+The @kbd{M-x mh-rmail} command will show you only new mail, not mail
+you have already read. If you were to run this tour again, you would
+use @kbd{F r} to pull all your messages into MH-E.
+@end quotation
+@sp 1
+
+@kindex @key{RET}
+@kindex n
+@kindex p
+
+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:
+
+@cartouche
+@smallexample
+ 3 t08/24 root received fax files on Wed Aug 24 11:00:13 PDT 1
+# 4+t08/24 To:wohler Test<<This is a test message to get the wheels
+
+-:%% @{+inbox/select@} 4 msgs (1-4) Bot L4 (MH-Folder Show)---------
+To: wohler
+Subject: Test
+X-Mailer: MH-E 8.0; nmh 1.1; GNU Emacs 22.1
+Date: Fri, 17 Mar 2006 10:49:11 -0800
+From: Bill Wohler <wohler@@stop.mail-abuse.org>
+
+This is a test message to get the wheels churning...
+
+
+
+--:-- @{show-+inbox@} 4 All L1 (MH-Show)----------------------------
+
+@end smallexample
+@end cartouche
+@i{After incorporating new messages}
+
+@kindex @key{DEL}
+@kindex @key{SPC}
+
+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
+@kindex @key{RET}
+@kindex r
+
+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. You can press @key{TAB} to see these
+choices. If you simply press @key{RET}, you'll reply only to the
+sender. Press @key{RET} now.
+
+You'll find yourself in an Emacs buffer similar to that when you were
+sending the original message, like this:
+
+@cartouche
+@smallexample
+To:
+cc:
+Subject: Re: Test
+In-reply-to: <31054.1142621351@@stop.mail-abuse.org>
+References: <31054.1142621351@@stop.mail-abuse.org>
+Comments: In-reply-to Bill Wohler <wohler@@stop.mail-abuse.org>
+ message dated "Fri, 17 Mar 2006 10:49:11 -0800."
+X-Mailer: MH-E 8.0; nmh 1.1; GNU Emacs 22.1
+--------
+#
+
+--:-- @{draft@} All L10 (MH-Letter)----------------------------------
+To: wohler
+Subject: Test
+X-Mailer: MH-E 8.0; nmh 1.1; GNU Emacs 22.1
+Date: Fri, 17 Mar 2006 10:49:11 -0800
+From: Bill Wohler <wohler@@stop.mail-abuse.org>
+
+This is a test message to get the wheels churning...
+
+--:-- @{show-+inbox@} 4 All L1 (MH-Show)----------------------------
+Type C-c C-c to send message, C-c ? for help
+@end smallexample
+@end cartouche
+@i{Composition window during reply}
+
+@findex backward-char
+@findex forward-char
+@findex next-line
+@findex previous-line
+@kindex C-b
+@kindex C-c C-c
+@kindex C-c C-f C-t
+@kindex C-f
+@kindex C-n
+@kindex C-p
+@kindex @key{BS}
+
+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{BS}. When you're finished
+editing your message, send it with @kbd{C-c C-c} as before.
+
+@cindex @command{refile}
+@cindex MH commands, @command{refile}
+@cindex folders
+@kindex @key{SPC}
+@kindex o
+
+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
+(@command{refile} in MH parlance) that message to a folder. Enter
+@kbd{test} at the @samp{Destination folder:} 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
+@kindex d
+@kindex i
+@kindex @key{RET}
+@kindex n
+@kindex p
+@kindex x
+
+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 mh-smail
+@kindex m
+@kindex M-x 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!
+
+@cindex help
+@cindex prefix characters
+@findex describe-mode
+@kindex ?
+@kindex C-h m
+@kindex F ?
+
+You can get a quick reminder about these commands by typing @kbd{?}.
+This lists several @dfn{prefix characters}. To list the commands
+available via the prefix characters, type the prefix character
+followed by a @kbd{?}, for example, @kbd{F ?}. More complete help is
+available with the @kbd{C-h m} (@code{describe-mode}) command.
+
+@node Leaving MH-E, More About MH-E, Processing Mail Tour, Tour Through MH-E
+@section Leaving MH-E
+
+@cindex Emacs, quitting
+@cindex quitting
+@kindex C-x C-c
+@kindex x
+
+You may now wish to exit @command{emacs} entirely. Use @kbd{C-x C-c}
+to exit @command{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.
+
+@findex mh-rmail
+@kindex C-x b
+@kindex C-x k
+@kindex M-x mh-rmail
+@kindex q
+
+If you don't want to leave Emacs, you can type @kbd{q} to bury (hide)
+the MH-E folder or delete it entirely with @kbd{C-x k}. You can then
+later recall it with @kbd{C-x b} or @kbd{M-x mh-rmail}.
+
+@cindex @command{packf}
+@cindex MH commands, @command{packf}
+@cindex exporting folders
+@cindex folders, exporting
+@cindex mbox-style folder
+
+On the other hand, if you no longer want to use MH and MH-E, you can
+take your mail with you. You can copy all of your mail into a single
+file, mbox-style, by using the MH command @command{packf}. For
+example, to create a file called @file{msgbox} with the messages in
+your @samp{+inbox} folder, use @samp{packf +inbox}. The
+@command{packf} command will append the messages to the file if it
+already exists, so you can use @samp{folders -recurse -fast} in a
+script to copy all of your messages into a single file, or using the
+@samp{-file} argument, a file for each folder.
+
+@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 the rest of the manual
+to find out how you can:
+
+@itemize @bullet
+@item
+Print your messages (@pxref{Printing}).
+@c -------------------------
+@item
+Edit messages and include your signature (@pxref{Editing Drafts}).
+@c -------------------------
+@item
+Forward messages (@pxref{Forwarding}).
+@c -------------------------
+@item
+Read digests (@pxref{Digests}).
+@c -------------------------
+@item
+Edit bounced messages (@pxref{Editing Again}).
+@c -------------------------
+@item
+Send multimedia messages (@pxref{Adding Attachments}).
+@c -------------------------
+@item
+Read HTML messages (@pxref{HTML}).
+@c -------------------------
+@item
+Use aliases and identities (see @ref{Aliases}, @pxref{Identities}).
+@c -------------------------
+@item
+Create different views of your mail (see @ref{Threading}, @pxref{Limits}).
+@c -------------------------
+@item
+Deal with junk mail (@pxref{Junk}).
+@c -------------------------
+@item
+Handle signed and encrypted messages (see @ref{Reading PGP},
+@pxref{Sending PGP}).
+@c -------------------------
+@item
+Process mail that was sent with @command{shar} or @command{uuencode}
+(@pxref{Files and Pipes}).
+@c -------------------------
+@item
+Use sequences conveniently (@pxref{Sequences}).
+@c -------------------------
+@item
+Use the speedbar, tool bar, and menu bar (see @ref{Speedbar}, see @ref{Tool
+Bar}, @pxref{Menu Bar}).
+@c -------------------------
+@item
+Show header fields in different fonts (@pxref{Reading Mail}).
+@c -------------------------
+@item
+Find previously refiled messages (@pxref{Searching}).
+@c -------------------------
+@item
+Place messages in a file (@pxref{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 This Manual, Incorporating Mail, Tour Through MH-E, Top
+@chapter Using This Manual
+
+This chapter begins the meat of the manual which goes into more detail
+about every MH-E command and option.
+
+@cindex Emacs, info
+@cindex Emacs, online help
+@cindex info
+@cindex online help
+@findex describe-mode
+@findex mh-help
+@kindex ?
+@kindex C-c ?
+@kindex C-h C-h
+@kindex C-h C-k i
+@kindex C-h i
+@kindex C-h m
+
+There are many commands, but don't get intimidated. There are command
+summaries at the beginning of each chapter. 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,
+@kbd{?} (@code{mh-help}) for an even briefer summary@footnote{This
+help appears in a buffer called @samp{*MH-E Help*}
+(@pxref{Miscellaneous}).} (@kbd{C-c ?} in MH-Letter mode), or @kbd{C-h
+i} to read this manual via Info. The online help is quite good; try
+running @kbd{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}). Another useful help feature is to view the manual section
+that describes a given key (such as @kbd{C-h K i}). In addition,
+review @ref{Conventions}, if any of the GNU Emacs conventions are
+strange to you.
+
+In addition to all of the commands, it is also possible to reconfigure
+MH-E to fit the needs of even the most demanding user. The following
+chapters also describe all of the options, show the defaults, and make
+recommendations for customization.
+
+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 Emacs Lisp Manual
+@cindex Emacs, Emacs Lisp Manual
+@cindex Emacs, info
+@cindex Emacs, online help
+@cindex info
+@cindex online help
+
+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
+@key{RET}}. It is also available online at @*
+@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/}. You
+can also 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 at
+gnu.org}.}
+@end iftex
+@ifinfo
+@footnote{@xref{Top, The GNU Emacs Lisp Reference Manual, , elisp, GNU
+Emacs Lisp Reference Manual}, which may be available online in the
+Info system. It is also available online at
+@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/}. You
+can also 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 at
+gnu.org}.}
+@end ifinfo
+@ifhtml
+@footnote{The
+@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/,
+The GNU Emacs Lisp Reference Manual} may also be available online in
+the Info system by typing @kbd{C-h i m Emacs Lisp @key{RET}}. You can
+also 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 at
+gnu.org}.}
+@end ifhtml
+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/mh-e}) 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 @key{RET}}. If you write your own functions,
+please do not prefix your symbols (variables and functions) with
+@samp{mh-}. This prefix is reserved for the MH-E package. To avoid
+conflicts with existing MH-E symbols, use a prefix like @samp{my-} or
+your initials. (Unless, of course, your initials happen to be @emph{mh}!)
+
+@menu
+* Options::
+* Ranges::
+* Folder Selection::
+@end menu
+
+@node Options, Ranges, Using This Manual, Using This Manual
+@section Options
+
+@cindex Emacs, customizing
+@cindex Emacs, setting options
+@cindex customizing MH-E
+@cindex setting options
+@findex customize-option
+@vindex mh-lpr-command-format, example
+
+Many string or integer options are easy to modify using @kbd{M-x
+customize-option}. For example, to modify the option that controls
+printing, you would run @kbd{M-x customize-option @key{RET}
+mh-lpr-command-format @key{RET}}. In the buffer that appears, modify
+the string to the right of the variable. For example, you may change
+the @command{lpr} command with @samp{nenscript -G -r -2 -i'%s'}. Then
+use the @samp{State} combo box and select @samp{Save for Future
+Sessions}. To read more about @code{mh-lpr-command-format}, see
+@ref{Printing}.
+
+@cindex nil
+@cindex off, option
+@cindex on, option
+@cindex option, turning on and off
+@cindex t
+@findex customize-option
+@vindex mh-bury-show-buffer-flag, example
+
+Options can also hold boolean values. In Emacs Lisp, the boolean
+values are @code{nil}, which means false, and @code{t}, which means
+true. The @code{customize-option} function makes it easy to change
+boolean values; simply click on the toggle button in the customize
+buffer to switch between @samp{on} (@code{t}) and @samp{off}
+(@code{nil}). For example, try setting @code{mh-bury-show-buffer-flag}
+to @samp{off} to keep the MH-Show buffer at the top of the buffer
+stack. Use the @samp{State} combo box and choose @samp{Set for Current
+Session} to see how the option affects the show buffer. Then choose
+the @samp{Erase Customization} menu item to reset the option to the
+default, which places the MH-Show buffer at the bottom of the buffer
+stack.
+
+@vindex mh-mhl-format-file, example
+
+The text usually says to turn on an option by setting it to a
+@emph{non-@code{nil}} value, because sometimes values other than
+@samp{on} are meaningful. An example of this is the variable
+@code{mh-mhl-format-file} (@pxref{Viewing}). Other options, such as
+hooks, involve a little more Emacs Lisp programming expertise.
+
+@cindex customization group, @samp{mh}
+@cindex @samp{mh} customization group
+@findex customize-group
+@findex mh-customize
+
+You can browse all of the MH-E options with the @code{customize-group}
+function. Try entering @kbd{M-x customize-group @key{RET} mh
+@key{RET}} to view the top-level options as well as buttons for all of
+the MH-E customization groups. Another way to view the MH-E
+customization group is to use @kbd{M-x mh-customize @key{RET}}.
+
+@node Ranges, Folder Selection, Options, Using This Manual
+@section Ranges
+
+@c Sync with mh-folder-mode docstring.
+
+@cindex message abbreviations
+@cindex message ranges
+@cindex ranges
+
+Many commands that operate on individual messages, such as
+@code{mh-forward} or @code{mh-refile-msg} take a @code{RANGE}
+argument. This argument can be used in several ways.
+
+@kindex C-u, with ranges
+
+If you provide the prefix argument @kbd{C-u} to these commands, then
+you will be prompted for the message range. This can be any valid MH
+range which can include messages, sequences (@pxref{Sequences}), and
+the abbreviations (described in the @command{mh}(1) man page):
+
+@table @samp
+@item <num1>-<num2>
+Indicates all messages in the range <num1> to <num2>, inclusive. The
+range must be nonempty.
+@c -------------------------
+@item <num>:N
+@itemx <num>:+N
+@itemx <num>:-N
+Up to N messages beginning with (or ending with) message num. Num may
+be any of the predefined symbols: first, prev, cur, next or last.
+@c -------------------------
+@item first:N
+@itemx prev:N
+@itemx next:N
+@itemx last:N
+The first, previous, next or last messages, if they exist.
+@c -------------------------
+@item all
+All of the messages.
+@end table
+
+For example, a range that shows all of these things is @samp{1 2 3
+5-10 last:5 unseen}.
+
+@vindex transient-mark-mode
+
+If the option @code{transient-mark-mode} is turned on and you set a
+region in the MH-Folder buffer, then the MH-E command will perform the
+operation on all messages in that region.
+
+@cindex @samp{mh-range} customization group
+@cindex customization group, @samp{mh-range}
+
+The @samp{mh-range} customization group contains a single option which
+affects how ranges are interpreted.
+
+@vtable @code
+@item mh-interpret-number-as-range-flag
+On means interpret a number as a range (default: @samp{on}).
+@end vtable
+
+@vindex mh-interpret-number-as-range-flag
+
+Since one of the most frequent ranges used is @samp{last:N}, MH-E will
+interpret input such as @samp{200} as @samp{last:200} if the
+@code{mh-interpret-number-as-range-flag} option is on (which is the
+default). If you need to scan just the message 200, then use the range
+@samp{200:1} or @samp{200-200}.
+
+@node Folder Selection, , Ranges, Using This Manual
+@section Folder Selection
+
+@cindex completion, folders
+@cindex folders, completion
+@cindex folders, selecting
+
+When you choose a folder in MH-E via a command such as @kbd{o}
+(@code{mh-refile-msg}), completion is used to enter the folder
+@ifnothtml
+(@pxref{Completion, , , emacs, The GNU Emacs Manual}).
+@end ifnothtml
+@ifhtml
+(see the section
+@uref{http://www.gnu.org/software/emacs/manual/html_node/Completion.html,
+Completion} in @cite{The GNU Emacs Manual}).
+@end ifhtml
+In addition, MH-E has several ways of choosing a suitable default so
+that the folder can often be selected with a single @key{RET} key.
+
+@cindex customization group, @samp{mh-folder-selection}
+@cindex @samp{mh-folder-selection} customization group
+
+The @samp{mh-folder-selection} customization group contains some
+options which are used to help with this.
+
+@vtable @code
+@item mh-default-folder-for-message-function
+Function to select a default folder for refiling or @samp{Fcc:}
+(default: @code{nil}).
+@c -------------------------
+@item mh-default-folder-list
+List of addresses and folders (default: @code{nil}).
+@c -------------------------
+@item mh-default-folder-must-exist-flag
+On means guessed folder name must exist to be used (default:
+@samp{on}).
+@c -------------------------
+@item mh-default-folder-prefix
+Prefix used for folder names generated from aliases (default: @code{""}).
+@end vtable
+
+@vindex mh-default-folder-for-message-function
+
+You can set the option @code{mh-default-folder-for-message-function}
+to a function that provides a default folder for the message to be
+refiled. When this function is called, the current buffer contains the
+message being refiled and point is at the start of the message. This
+function should return the default folder as a string with a leading
+@samp{+} sign. It can also return @code{nil} so that the last folder
+name is used as the default, or an empty string to suppress the
+default entirely.
+
+Otherwise, the name of the destination folder is derived from the
+sender as follows:
+
+@enumerate
+@vindex mh-default-folder-list
+@item
+The folder name associated with the first address found in the list
+@code{mh-default-folder-list} is used. Each element in this list
+contains a @samp{Check Recipient} item. If this item is turned on,
+then the address is checked against the recipient instead of the
+sender. This is useful for mailing lists.
+@c -------------------------
+@vindex mh-default-folder-prefix
+@item
+An alias prefixed by @code{mh-default-folder-prefix} corresponding to
+the address is used. The prefix is used to prevent clutter in your
+mail directory. @xref{Aliases}.
+@end enumerate
+
+@vindex mh-default-folder-must-exist-flag
+
+If the derived folder does not exist, and
+@code{mh-default-folder-must-exist-flag} is @code{t}, then the last
+folder name used is suggested. This is useful if you get mail from
+various people for whom you have an alias, but file them all in the
+same project folder.
+
+@node Incorporating Mail, Reading Mail, Using This Manual, Top
+@chapter Incorporating Your Mail
+
+@cindex @samp{Folder} menu
+@cindex incorporating
+@cindex menu, @samp{Folder}
+
+This chapter talks about getting mail from your system mailbox into
+your MH @samp{+inbox} folder. The following command accomplishes that
+and is found in the @samp{Folder} menu.
+
+@table @kbd
+@cindex @samp{Folder > Incorporate New Mail} menu item
+@cindex menu item, @samp{Folder > Incorporate New Mail}
+@findex mh-inc-folder
+@kindex i
+@item i
+Incorporate new mail into a folder (@code{mh-inc-folder}).
+@end table
+
+@cindex @samp{mh-inc} customization group
+@cindex customization group, @samp{mh-inc}
+
+The following options in the @samp{mh-inc} customization group are
+used.
+
+@vtable @code
+@item mh-inc-prog
+Program to incorporate mail (default: @code{"inc"}).
+@c -------------------------
+@item mh-inc-spool-list
+Alternate spool files (default: @code{nil}).
+@end vtable
+
+The following hook is available.
+
+@vtable @code
+@findex mh-inc-folder
+@item mh-inc-folder-hook
+Hook run by @code{mh-inc-folder} after incorporating mail into a
+folder (default: @code{nil}).
+@end vtable
+
+@cindex @samp{+inbox}
+@findex mh-inc-folder
+@kindex i
+
+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 as well as the destination folder (for
+example, @kbd{C-u i ~/mbox @key{RET} +tmp @key{RET}}).
+
+@cindex @file{.emacs}
+@cindex Emacs, notification of new mail
+@cindex files, @file{.emacs}
+@cindex new mail
+@cindex notification of new mail
+
+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 as well, add the following to @file{~/.emacs}:
+
+@findex display-time
+
+@smalllisp
+(display-time)
+@end smalllisp
+
+@cindex @command{inc}
+@cindex incorporating
+@cindex MH commands, @command{inc}
+@vindex mh-inc-prog
+@vindex mh-progs
+
+The name of the program that incorporates new mail is stored in
+@code{mh-inc-prog}; it is @code{"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 (@pxref{Getting Started}). You may also link
+a file to @command{inc} that uses a different format (see
+@samp{mh-profile}(5), and sections
+@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next
+prev} and @uref{@value{MH-BOOK-HOME}/mhstr.html, MH Format Strings} in
+the MH book). You'll then need to modify several variables
+appropriately (@pxref{Scan Line Formats}).
+
+@vindex mh-inc-spool-list
+
+You can use the @code{mh-inc-spool-list} variable to direct MH-E to
+retrieve mail from arbitrary spool files other than your system
+mailbox, file it in folders other than your @samp{+inbox}, and assign
+key bindings to incorporate this mail.
+
+@cindex @command{procmail}
+@cindex @file{.procmailrc}
+@cindex Unix commands, @command{procmail}
+@cindex files, @file{.procmailrc}
+
+Suppose you are subscribed to the @i{mh-e-devel} mailing list and you
+use @command{procmail} to filter this mail into @file{~/mail/mh-e}
+with the following recipe in @file{.procmailrc}:
+
+@smallexample
+PATH=$PATH:/usr/bin/mh
+MAILDIR=$HOME/`mhparam Path`
+:0:
+* ^From mh-e-devel-admin@@stop.mail-abuse.org
+mh-e
+@end smallexample
+
+@findex mh-inc-spool-*
+@kindex I *
+
+In order to incorporate @file{~/mail/mh-e} into @samp{+mh-e} with an
+@kbd{I m} (@code{mh-inc-spool-mh-e}) command, customize this option,
+and click on the @samp{INS} button. Enter a @samp{Spool File} of
+@samp{~/mail/mh-e}, a @samp{Folder} of @samp{mh-e}, and a @samp{Key
+Binding} of @samp{m}.
+
+@cindex @command{emacsclient}
+@cindex @command{gnuclient}
+@cindex @command{xbuffy}
+@cindex @samp{gnuserv}
+@cindex Unix commands, @command{emacsclient}
+@cindex Unix commands, @command{gnuclient}
+@cindex Unix commands, @command{xbuffy}
+
+You can use @command{xbuffy} to automate the incorporation of this
+mail using the Emacs 22 command @command{emacsclient} as follows:
+
+@smallexample
+box ~/mail/mh-e
+ title mh-e
+ origMode
+ polltime 10
+ headertime 0
+ command emacsclient --eval '(mh-inc-spool-mh-e)'
+@end smallexample
+
+In XEmacs, the command @command{gnuclient} is used in a similar
+fashion.
+
+@findex mh-inc-folder
+@kindex i
+@vindex mh-inc-folder-hook
+
+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 mh-execute-commands
+@findex mh-rescan-folder, example
+@findex mh-show, example
+@vindex mh-inc-folder-hook, example
+
+@smalllisp
+@group
+(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)
+
+@i{Rescan folder after incorporating new mail via mh-inc-folder-hook}
+
+@end group
+@end smalllisp
+
+@node Reading Mail, Folders, Incorporating Mail, Top
+@chapter Reading Your Mail
+
+@cindex @samp{+inbox}
+@cindex MH-Folder mode
+@cindex MH-Show mode
+@cindex modes, MH-Folder
+@cindex modes, MH-Show
+@cindex reading mail
+@findex mh-rmail
+@kindex F r
+@kindex F v
+@kindex M-x mh-rmail
+
+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 command @kbd{M-x mh-rmail} shows
+you only new mail, not mail you have already read@footnote{If you want
+to see your old mail as well, use @kbd{F 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{F v} (for example, @kbd{C-u
+M-x mh-rmail @key{RET} bob @key{RET}}). @xref{Folders}.}.
+
+@findex display-time
+@vindex read-mail-command
+
+There are some commands that need to read mail, such as @kbd{Mouse-2}
+over the @samp{Mail} button that @code{display-time} adds to the mode
+line. You can configure Emacs to have these commands use MH-E by
+setting the option @code{read-mail-command} to @samp{mh-rmail}.
+
+@cindex @command{scan}
+@cindex @samp{Message} menu
+@cindex MH commands, @command{scan}
+@cindex menu, @samp{Message}
+@cindex scan lines
+
+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- or two-letter commands in either
+the MH-Folder or MH-Show buffers or by using the @samp{Message} menu.
+See @command{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
+@kindex ?
+@findex mh-help
+@item ?
+Display cheat sheet for the MH-E commands (@code{mh-help}).
+@c -------------------------
+@cindex @samp{Message > Show Message} menu item
+@cindex menu item, @samp{Message > Show Message}
+@kindex @key{RET}
+@findex mh-show
+@item @key{RET}
+Display message (@code{mh-show}).
+@c -------------------------
+@cindex @samp{Message > Show Message with Header} menu item
+@cindex menu item, @samp{Message > Show Message with Header}
+@kindex , (comma)
+@findex mh-header-display
+@item , (comma)
+Display message with all header fields (@code{mh-header-display}).
+@c -------------------------
+@kindex ; (semicolon)
+@findex mh-toggle-mh-decode-mime-flag
+@item ; (semicolon)
+Toggle the value of @code{mh-decode-mime-flag}
+(@code{mh-toggle-mh-decode-mime-flag}).
+@c -------------------------
+@kindex @key{SPC}
+@findex mh-page-msg
+@item @key{SPC}
+Display next page in message (@code{mh-page-msg}).
+@c -------------------------
+@kindex @key{BS}
+@findex mh-previous-page
+@item @key{BS}
+Display previous page in message (@code{mh-previous-page}).
+@c -------------------------
+@cindex @samp{Message > Write Message to File...} menu item
+@cindex menu item, @samp{Message > Write Message to File...}
+@kindex >
+@findex mh-write-msg-to-file
+@item >
+Append message to end of file (@code{mh-write-msg-to-file}).
+@c -------------------------
+@cindex @samp{Message > Pipe Message to Command...} menu item
+@cindex menu item, @samp{Message > Pipe Message to Command...}
+@kindex |
+@findex mh-pipe-msg
+@item |
+Pipe message through shell command (@code{mh-pipe-msg}).
+@c -------------------------
+@kindex C-d
+@findex mh-delete-msg-no-motion
+@item C-d
+Delete range, don't move to next message
+(@code{mh-delete-msg-no-motion}).
+@c -------------------------
+@cindex @samp{Message > Delete Message} menu item
+@cindex menu item, @samp{Message > Delete Message}
+@kindex d
+@findex mh-delete-msg
+@item d
+Delete range (@code{mh-delete-msg}).
+@c -------------------------
+@kindex D ?
+@findex mh-prefix-help
+@item D ?
+Display cheat sheet for the commands of the current prefix in
+minibuffer (@code{mh-prefix-help}).
+@c -------------------------
+@kindex D @key{SPC}
+@findex mh-page-digest
+@item D @key{SPC}
+Display next message in digest (@code{mh-page-digest}).
+@c -------------------------
+@kindex D @key{BS}
+@findex mh-page-digest-backwards
+@item D @key{BS}
+Display previous message in digest (@code{mh-page-digest-backwards}).
+@c -------------------------
+@cindex @samp{Message > Burst Digest Message} menu item
+@cindex menu item, @samp{Message > Burst Digest Message}
+@kindex D b
+@findex mh-burst-digest
+@item D b
+Break up digest into separate messages (@code{mh-burst-digest}).
+@c -------------------------
+@cindex @samp{Message > Go to Message by Number...} menu item
+@cindex menu item, @samp{Message > Go to Message by Number...}
+@kindex g
+@findex mh-goto-msg
+@item g
+Go to a message (@code{mh-goto-msg}).
+@c -------------------------
+@kindex k
+@findex mh-delete-subject-or-thread
+@item k
+Delete messages with same subject or thread
+(@code{mh-delete-subject-or-thread}).
+@c -------------------------
+@kindex K ?
+@findex mh-prefix-help
+@item K ?
+Display cheat sheet for the commands of the current prefix in
+minibuffer (@code{mh-prefix-help}).
+@c -------------------------
+@kindex K @key{TAB}
+@findex mh-next-button
+@item K @key{TAB}
+Go to the next button (@code{mh-next-button}).
+@c -------------------------
+@kindex K S-@key{TAB}
+@findex mh-prev-button
+@item K S-@key{TAB}
+Go to the previous button (@code{mh-prev-button}).
+@c -------------------------
+@kindex K a
+@findex mh-mime-save-parts
+@item K a
+Save attachments (@code{mh-mime-save-parts}).
+@c -------------------------
+@kindex K e
+@findex mh-display-with-external-viewer
+@item K e
+View attachment externally (@code{mh-display-with-external-viewer}).
+@c -------------------------
+@kindex K i
+@findex mh-folder-inline-mime-part
+@item K i
+Show attachment verbatim (@code{mh-folder-inline-mime-part}).
+@c -------------------------
+@kindex K o
+@findex mh-folder-save-mime-part
+@item K o
+Save (output) attachment (@code{mh-folder-save-mime-part}).
+@c -------------------------
+@kindex K t
+@findex mh-toggle-mime-buttons
+@item K t
+Toggle option @code{mh-display-buttons-for-inline-parts-flag}
+(@code{mh-toggle-mime-buttons}).
+@c -------------------------
+@kindex K v
+@findex mh-folder-toggle-mime-part
+@item K v
+View attachment (@code{mh-folder-toggle-mime-part}).
+@c -------------------------
+@cindex @samp{Message > Modify Message} menu item
+@cindex menu item, @samp{Message > Modify Message}
+@kindex M
+@findex mh-modify
+@item M
+Edit message (@code{mh-modify}).
+@c -------------------------
+@cindex @samp{Message > Go to First Message} menu item
+@cindex menu item, @samp{Message > Go to First Message}
+@kindex M-<
+@findex mh-first-msg
+@item M-<
+Display first message (@code{mh-first-msg}).
+@c -------------------------
+@cindex @samp{Message > Go to Last Message} menu item
+@cindex menu item, @samp{Message > Go to Last Message}
+@kindex M->
+@findex mh-last-msg
+@item M->
+Display last message (@code{mh-last-msg}).
+@c -------------------------
+@kindex M-n
+@findex mh-next-unread-msg
+@item M-n
+Display next unread message (@code{mh-next-unread-msg}).
+@c -------------------------
+@kindex M-p
+@findex mh-previous-unread-msg
+@item M-p
+Display previous unread message (@code{mh-previous-unread-msg}).
+@c -------------------------
+@cindex @samp{Message > Next Message} menu item
+@cindex menu item, @samp{Message > Next Message}
+@kindex n
+@findex mh-next-undeleted-msg
+@item n
+Display next message (@code{mh-next-undeleted-msg}).
+@c -------------------------
+@cindex @samp{Message > Previous Message} menu item
+@cindex menu item, @samp{Message > Previous Message}
+@kindex p
+@findex mh-previous-undeleted-msg
+@item p
+Display previous message (@code{mh-previous-undeleted-msg}).
+@c -------------------------
+@kindex P ?
+@findex mh-prefix-help
+@item P ?
+Display cheat sheet for the commands of the current prefix in
+minibuffer (@code{mh-prefix-help}).
+@c -------------------------
+@kindex P C
+@findex mh-ps-print-toggle-color
+@item P C
+Toggle whether color is used in printing messages
+(@code{mh-ps-print-toggle-color}).
+@c -------------------------
+@kindex P F
+@findex mh-ps-print-toggle-faces
+@item P F
+Toggle whether printing is done with faces or not
+(@code{mh-ps-print-toggle-faces}).
+@c -------------------------
+@kindex P f
+@findex mh-ps-print-msg-file
+@item P f
+Print range to file (@code{mh-ps-print-msg-file}).
+@c -------------------------
+@cindex @samp{Message > Print Message} menu item
+@cindex menu item, @samp{Message > Print Message}
+@kindex P l
+@findex mh-print-msg
+@item P l
+Print range the old fashioned way
+(@code{mh-print-msg}).
+@c -------------------------
+@kindex P p
+@findex mh-ps-print-msg
+@item P p
+Print range (@code{mh-ps-print-msg}).
+@c -------------------------
+@kindex X ?
+@findex mh-prefix-help
+@item X ?
+Display cheat sheet for the commands of the current prefix in
+minibuffer (@code{mh-prefix-help}).
+@c -------------------------
+@cindex @samp{Message > Unpack Uuencoded Message...} menu item
+@cindex menu item, @samp{Message > Unpack Uuencoded Message...}
+@kindex X s
+@kindex X u
+@findex mh-store-msg
+@item X s
+@itemx X u
+Unpack message created with @command{uudecode} or @command{shar}
+(@code{mh-store-msg}).
+@c -------------------------
+@kindex Mouse-2
+@findex mh-show-mouse
+@item Mouse-2
+Move point to mouse event and show message (@code{mh-show-mouse}).
+@end table
+
+Within the MH-Show buffer, the following command is defined.
+
+@table @kbd
+@kindex @key{RET}
+@kindex Mouse-1
+@kindex Mouse-2
+@findex mh-press-button
+@item @key{RET}
+@itemx Mouse-1
+@itemx Mouse-2
+View contents of button (@code{mh-press-button}).
+@end table
+
+@cindex @samp{mh-show} customization group
+@cindex customization group, @samp{mh-show}
+
+The following table lists options in the @samp{mh-show} customization
+group that are used while reading mail.
+
+@vtable @code
+@item mh-bury-show-buffer-flag
+On means show buffer is buried (default: @samp{on}).
+@c -------------------------
+@item mh-clean-message-header-flag
+On means remove extraneous header fields (default: @samp{on}).
+@c -------------------------
+@item mh-decode-mime-flag
+On means attachments are handled (default: @samp{on} if the Gnus
+@samp{mm-decode} package is present).
+@c -------------------------
+@item mh-display-buttons-for-alternatives-flag
+On means display buttons for all alternative attachments (default:
+@samp{off}).
+@c -------------------------
+@item mh-display-buttons-for-inline-parts-flag
+On means display buttons for all inline attachments (default:
+@samp{off}).
+@c -------------------------
+@item mh-do-not-confirm-flag
+On means non-reversible commands do not prompt for confirmation
+(default: @samp{off}).
+@c -------------------------
+@item mh-fetch-x-image-url
+Control fetching of @samp{X-Image-URL:} header field image (default:
+@samp{Never Fetch}).
+@c -------------------------
+@item mh-graphical-smileys-flag
+On means graphical smileys are displayed (default: @samp{on}).
+@c -------------------------
+@item mh-graphical-emphasis-flag
+On means graphical emphasis is displayed (default: @samp{on}).
+@c -------------------------
+@item mh-highlight-citation-style
+Style for highlighting citations (default: @samp{Multicolor}).
+@c -------------------------
+@item mh-invisible-header-fields-default
+List of hidden header fields (default: a checklist too long to list
+here).
+@c -------------------------
+@item mh-invisible-header-fields
+Additional header fields to hide (default: @code{nil}).
+@c -------------------------
+@item mh-lpr-command-format
+Command used to print (default: @code{"lpr -J '%s'"}).
+@c -------------------------
+@item mh-max-inline-image-height
+Maximum inline image height if @samp{Content-Disposition:} is not
+present (default: 0).
+@c -------------------------
+@item mh-max-inline-image-width
+Maximum inline image width if @samp{Content-Disposition:} is not
+present(default: 0).
+@c -------------------------
+@item mh-mhl-format-file
+Specifies the format file to pass to the @command{mhl} program
+(default: @samp{Use Default mhl Format (Printing Only)}).
+@c -------------------------
+@item mh-mime-save-parts-default-directory
+Default directory to use for @kbd{K a}.
+@c -------------------------
+@item mh-print-background-flag
+On means messages should be printed in the background (default:
+@samp{off}).
+@c -------------------------
+@item mh-show-buffer-mode-line-buffer-id
+Format string to produce @code{mode-line-buffer-identification} for
+show buffers (default: @code{" @{show-%s@} %d"}).
+@c -------------------------
+@item mh-show-maximum-size
+Maximum size of message (in bytes) to display automatically (default:
+0).
+@c -------------------------
+@item mh-show-use-xface-flag
+On means display face images in MH-Show buffers (default: @samp{on}).
+@c -------------------------
+@item mh-store-default-directory
+Default directory for @kbd{X s} (default: @samp{Current}).
+@c -------------------------
+@item mh-summary-height
+Number of lines in MH-Folder buffer (including the mode line)
+(default: depends on size of frame).
+@end vtable
+
+The following hooks are available.
+
+@vtable @code
+@item mh-delete-msg-hook
+Hook run after marking each message for deletion (default: @code{nil}).
+@c -------------------------
+@item mh-show-hook
+Hook run after @key{RET} shows a message (default: @code{nil}).
+@c -------------------------
+@item mh-show-mode-hook
+Hook run upon entry to @code{mh-show-mode} (default: @code{nil}).
+@end vtable
+
+The following faces are available.
+
+@vtable @code
+@item mh-show-cc
+Face used to highlight @samp{cc:} header fields.
+@c -------------------------
+@item mh-show-date
+Face used to highlight @samp{Date:} header fields.
+@c -------------------------
+@item mh-show-from
+Face used to highlight @samp{From:} header fields.
+@c -------------------------
+@item mh-show-header
+Face used to deemphasize less interesting header fields.
+@c -------------------------
+@item mh-show-pgg-bad
+Bad PGG signature face.
+@c -------------------------
+@item mh-show-pgg-good
+Good PGG signature face.
+@c -------------------------
+@item mh-show-pgg-unknown
+Unknown or untrusted PGG signature face.
+@c -------------------------
+@item mh-show-signature
+Signature face.
+@c -------------------------
+@item mh-show-subject
+Face used to highlight @samp{Subject:} header fields.
+@c -------------------------
+@item mh-show-to
+Face used to highlight @samp{To:} header fields.
+@c -------------------------
+@item mh-show-xface
+X-Face image face.
+@end vtable
+
+The functions and variables introduced here are explained in more
+detail in the following sections.
+
+@menu
+* Viewing::
+* Viewing Attachments::
+* HTML::
+* Digests::
+* Reading PGP::
+* Printing::
+* Files and Pipes::
+* Navigating::
+* Miscellaneous Commands and Options::
+@end menu
+
+@node Viewing, Viewing Attachments, Reading Mail, Reading Mail
+@section Viewing Your Mail
+
+@findex mh-header-display
+@findex mh-page-msg
+@findex mh-previous-page
+@findex mh-show
+@findex mh-show-mouse
+@kindex , (comma)
+@kindex . (period)
+@kindex @key{BS}
+@kindex @key{RET}
+@kindex @key{SPC}
+@kindex Mouse-2
+
+The command @key{RET} (@code{mh-show}) displays the message that the
+cursor is on while @kbd{Mouse-2} (@code{mh-show-mouse}) displays the
+message that the mouse 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{BS} (@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 @key{SPC}}). The @key{SPC}
+command will also show the next undeleted message if it is used at the
+bottom of a message. 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 command @kbd{,} (comma;
+@code{mh-header-display}).
+
+@vindex mh-show-maximum-size
+
+The option @code{mh-show-maximum-size} provides an opportunity to skip
+over large messages which may be slow to load. The default value of 0
+means that all message are shown regardless of size.
+
+A litany of options control what displayed messages look like.
+
+@vindex mh-show-cc
+@vindex mh-show-date
+@vindex mh-show-from
+@vindex mh-show-header
+@vindex mh-show-subject
+@vindex mh-show-to
+
+First, the appearance of the header fields can be modified by
+customizing the associated face: @code{mh-show-to}, @code{mh-show-cc},
+@code{mh-show-from}, @code{mh-show-date}, and @code{mh-show-subject}.
+The face @code{mh-show-header} is used to deemphasize the other, less
+interesting, header fields.
+
+@cindex regular expressions, @code{mh-invisible-header-fields}
+@vindex mh-clean-message-header-flag
+@vindex mh-invisible-header-fields
+@vindex mh-invisible-header-fields-default
+
+Normally messages are delivered with a handful of uninteresting header
+fields. These are hidden by turning on the option
+@code{mh-clean-message-header-flag} (which it is by default). The
+header fields listed in the option
+@code{mh-invisible-header-fields-default} are hidden, although you can
+check off any field that you would like to see. Header fields that you
+would like to hide that aren't listed can be added to the option
+@code{mh-invisible-header-fields} with a couple of caveats. Regular
+expressions are not allowed. Unique fields should have a @samp{:}
+suffix; otherwise, the element can be used to render invisible an
+entire class of fields that start with the same prefix. If you think a
+header field should be generally ignored, report a bug (@pxref{Bug
+Reports}).
+
+@cindex header field, @samp{Face:}
+@cindex header field, @samp{X-Face:}
+@cindex header field, @samp{X-Image-URL:}
+@cindex @samp{Face:} header field
+@cindex @samp{X-Face:} header field
+@cindex @samp{X-Image-URL:} header field
+@vindex mh-show-use-xface-flag
+
+MH-E can display the content of @samp{Face:}, @samp{X-Face:}, and
+@samp{X-Image-URL:} header fields. If any of these fields occur in the
+header of your message, the sender's face will appear in the
+@samp{From:} header field. If more than one of these fields appear,
+then the first field found in the order @samp{Face:}, @samp{X-Face:},
+and @samp{X-Image-URL:} will be used. The option
+@code{mh-show-use-xface-flag} is used to turn this feature on and off.
+This feature will be turned on by default if your system supports it.
+
+The first header field used, if present, is the Gnus-specific
+@samp{Face:} field@footnote{The @samp{Face:} field appeared in GNU
+Emacs 21 and XEmacs. For more information, see
+@uref{http://quimby.gnus.org/circus/face/}.}.
+
+@cindex @command{uncompface}
+@cindex Emacs, packages, x-face
+@cindex Unix commands, @command{uncompface}
+@cindex x-face package
+@vindex mh-show-xface
+
+Next is the traditional @samp{X-Face:} header field@footnote{The
+display of this field requires the
+@uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z,
+@command{uncompface} program}. Recent versions of XEmacs have internal
+support for @samp{X-Face:} images. If your version of XEmacs does not,
+then you'll need both @command{uncompface} and the
+@uref{ftp://ftp.jpl.org/pub/elisp/, @samp{x-face} package}.}. MH-E
+renders the foreground and background of the image using the
+associated attributes of the face @code{mh-show-xface}.
+
+@cindex @command{convert}
+@cindex @command{wget}
+@cindex ImageMagick
+@cindex Unix commands, @command{convert}
+@cindex Unix commands, @command{wget}
+@vindex mh-fetch-x-image-url
+
+Finally, MH-E will display images referenced by the
+@samp{X-Image-URL:} header field if neither the @samp{Face:} nor the
+@samp{X-Face:} fields are present@footnote{The display of the images
+requires the @uref{http://www.gnu.org/software/wget/wget.html,
+@command{wget} program} to fetch the image and the @command{convert}
+program from the @uref{http://www.imagemagick.org/, ImageMagick
+suite}.}. Of the three header fields this is the most efficient in
+terms of network usage since the image doesn't need to be transmitted
+with every single mail. The option @code{mh-fetch-x-image-url}
+controls the fetching of the @samp{X-Image-URL:} header field image
+with the following values:
+
+@table @samp
+@item Ask Before Fetching
+You are prompted before the image is fetched. MH-E will remember your
+reply and will either use the already fetched image the next time the
+same URL is encountered or silently skip it if you didn't fetch it the
+first time. This is a good setting.
+@c -------------------------
+@item Never Fetch
+Images are never fetched and only displayed if they are already
+present in the cache. This is the default.
+@end table
+
+There isn't a value of @samp{Always Fetch} for privacy and DOS (denial
+of service) reasons. For example, fetching a URL can tip off a spammer
+that you've read his email (which is why you shouldn't blindly answer
+yes if you've set this option to @samp{Ask Before Fetching}). Someone
+may also flood your network and fill your disk drive by sending a
+torrent of messages, each specifying a unique URL to a very large
+file.
+
+@cindex @file{.mhe-x-image-cache}
+@cindex files, @file{.mhe-x-image-cache}
+
+The cache of images is found in the directory
+@file{.mhe-x-image-cache} within your MH directory. You can add your
+own face to the @samp{From:} field too. @xref{Picture}.
+
+@cindex @command{mhl}
+@cindex MH commands, @command{mhl}
+@vindex mh-mhl-format-file
+
+Normally MH-E takes care of displaying messages itself (rather than
+calling an MH program to do the work). If you'd rather have
+@command{mhl} display the message (within MH-E), change the option
+@code{mh-mhl-format-file} from its default value of @samp{Use Default
+mhl Format (Printing Only)}. You can set this option to @samp{Use
+Default mhl Format} to get the same output as you would get if you ran
+@command{mhl} from the shell. If you have a format file that you want
+MH-E to use, you can set this option to @samp{Specify an mhl Format
+File} and enter the name of your format file (@command{mhl}(1) or
+section @uref{@value{MH-BOOK-HOME}/shomes.html#Usisho, Using mhl} in
+the MH book tells you how to write one). Your format file should
+specify a non-zero value for @samp{overflowoffset} to allow MH-E to
+parse the header. Note that @command{mhl} is always used for printing
+and forwarding; in this case, the value of @code{mh-mhl-format-file}
+is consulted if you have specified a format file.
+
+@cindex citations, highlighting
+@cindex highlighting citations
+@vindex mh-highlight-citation-style
+
+If the sender of the message has cited other messages in his message,
+then MH-E will highlight these citations to emphasize the sender's
+actual response. The option @code{mh-highlight-citation-style} can be
+customized to change the highlighting style. The @samp{Multicolor}
+method uses a different color for each indentation while the
+@samp{Monotone} method highlights all citations in red. To disable
+highlighting of citations entirely, choose @samp{None}.
+
+@cindex URLs, highlighting
+@cindex email addresses, highlighting
+@cindex highlighting URLs
+@cindex highlighting email addresses
+@cindex links, following
+@findex goto-address-at-point
+@kindex C-c @key{RET}
+@kindex Mouse-2
+@vindex goto-address-highlight-p
+
+Email addresses and URLs in the message are highlighted if the option
+@code{goto-address-highlight-p} is on, which it is by default. To view
+the web page for a highlighted URL or to send a message using a
+highlighted email address, use @kbd{Mouse-2} or @kbd{C-c @key{RET}}
+(@code{goto-address-at-point}). @xref{Sending Mail}, to see how to
+configure Emacs to send the message using MH-E.
+
+@cindex boldface, showing
+@cindex emphasis
+@cindex italics, showing
+@cindex smileys
+@cindex typesetting
+@cindex underline, showing
+@vindex gnus-emphasis-alist
+@vindex mh-decode-mime-flag
+@vindex mh-graphical-emphasis-flag
+@vindex mh-graphical-smileys-flag
+
+It is a long standing custom to inject body language using a
+cornucopia of punctuation, also known as the @dfn{smileys}. MH-E can
+render these as graphical widgets if the option
+@code{mh-graphical-smileys-flag} is turned on, which it is by default.
+Smileys include patterns such as :-) and ;-). Similarly, a few
+typesetting features are indicated in ASCII text with certain
+characters. If your terminal supports it, MH-E can render these
+typesetting directives naturally if the option
+@code{mh-graphical-emphasis-flag} is turned on, which it is by
+default. For example, _underline_ will be
+@ifhtml
+@html
+<u>underlined</u>,
+@end html
+@end ifhtml
+@ifnothtml
+underlined,
+@end ifnothtml
+*bold* will appear in @b{bold}, /italics/ will appear in @i{italics},
+and so on. See the option @code{gnus-emphasis-alist} for the whole
+list. Both of these options are disabled if the option
+@code{mh-decode-mime-flag} is turned off. @xref{Viewing Attachments}.
+
+@cindex signature separator
+@cindex vCard
+@vindex mh-show-signature
+
+MH-E normally renders signatures and vCards in italics so that the
+body of the message stands out more. MH-E depends on the presence of
+the @dfn{signature separator} (@code{"-- "}) to do this. You can also
+customize the face @code{mh-show-signature} so the appearance of the
+signature block is more to your liking.
+
+@vindex mh-show-hook
+@vindex 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
+the message display. It is usually used to perform some action on the
+message's content. 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.
+
+@cindex MH-Show mode
+@cindex modes, MH-Show
+@vindex mh-show-buffer-mode-line-buffer-id
+
+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 @code{"@{show-%s@} %d"} yields a mode line of
+
+@smallexample
+-----@{show-+inbox@} 4 (MH-Show)--Bot--------------------------------
+@end smallexample
+
+@node Viewing Attachments, HTML, Viewing, Reading Mail
+@section Viewing Attachments
+
+@cindex attachments
+@cindex body parts
+@cindex @command{mhshow}
+@cindex @command{show}
+@cindex MH commands, @command{mhshow}
+@cindex MH commands, @command{show}
+@cindex MIME
+@cindex multimedia mail
+
+MH has the ability to display @dfn{@sc{mime}} (Multipurpose Internet
+Mail Extensions) messages which are simply messages with additional
+@dfn{body parts} or @dfn{attachments}. You can use the MH commands
+@command{show}@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next
+prev} in the MH book.} or @command{mhshow}@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/usimim.html#ReMIMa, Reading MIME Mail} in
+the MH book.} 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 mhshow @var{message-number}}. You can
+leave out the @samp{xterm -e} if you use @command{mhlist} or
+@command{mhstore}.}.
+
+@cindex Emacs, packages, mm-decode
+@cindex mm-decode package
+@findex mh-toggle-mh-decode-mime-flag
+@kindex ; (semicolon)
+@vindex mh-decode-mime-flag
+
+MH-E can handle attachments as well if the Gnus @samp{mm-decode}
+package is present. If so, the option @code{mh-decode-mime-flag} will
+be on. Otherwise, you'll see the @sc{mime} body parts rather than text
+or attachments. There isn't much point in turning off the option
+@code{mh-decode-mime-flag}; however, you can inspect it if it appears
+that the body parts are not being interpreted correctly or toggle it
+with the command @kbd{;} (semicolon;
+@code{mh-toggle-mh-decode-mime-flag}) to view the raw message. This
+option also controls the display of quoted-printable messages and
+other graphical widgets. @xref{Viewing}.
+
+@cindex buttons
+
+Attachments in MH-E are indicated by @dfn{buttons} like this:
+
+@smallexample
+[1. image/jpeg; foo.jpg]...
+@end smallexample
+
+@findex mh-next-button
+@findex mh-press-button
+@findex mh-prev-button
+@kindex @key{RET}
+@kindex K @key{TAB}
+@kindex K S-@key{TAB}
+@kindex Mouse-1
+@kindex Mouse-2
+
+To view the contents of the button, use either @kbd{Mouse-1} or
+@kbd{Mouse-2} on the button or @key{RET} (@code{mh-press-button}) when
+the cursor is over the button. This command is a toggle so if you use
+it again on the same attachment, it is hidden. If Emacs does not know
+how to display the attachment, then Emacs offers to save the
+attachment in a file. To move the cursor to the next button, use the
+command @kbd{K @key{TAB}} (@code{mh-next-button}). If the end of the
+buffer is reached then the search wraps over to the start of the
+buffer. To move the cursor to the previous button, use the command
+@kbd{K S-@key{TAB}} (@code{mh-prev-button}). If the beginning of the
+buffer is reached then the search wraps over to the end of the buffer.
+
+@cindex attachments, viewing
+@cindex viewing attachments
+@findex mh-folder-toggle-mime-part
+@kindex K v
+
+Another way to view the contents of a button is to use the command
+@kbd{K v} (@code{mh-folder-toggle-mime-part}). This command displays
+(or hides) the attachment associated with the button under the cursor.
+If the cursor is not located over a button, then the cursor first
+moves to the next button, wrapping to the beginning of the message if
+necessary. This command has the advantage over the previous commands
+of working from the MH-Folder buffer. You can also provide a numeric
+prefix argument (as in @kbd{4 K v}) to view the attachment labeled
+with that number. If Emacs does not know how to display the
+attachment, then Emacs offers to save the attachment in a file.
+
+@cindex @file{/etc/mailcap}
+@cindex files, @file{/etc/mailcap}
+@findex mailcap-mime-info
+@findex mh-display-with-external-viewer
+@kindex K e
+
+If Emacs does not know how to view an attachment, you could save it
+into a file and then run some program to open it. It is easier,
+however, to launch the program directly from MH-E with the command
+@kbd{K e} (@code{mh-display-with-external-viewer}). While you'll most
+likely use this to view spreadsheets and documents, it is also useful
+to use your browser to view HTML attachments with higher fidelity than
+what Emacs can provide. This command displays the attachment
+associated with the button under the cursor. If the cursor is not
+located over a button, then the cursor first moves to the next button,
+wrapping to the beginning of the message if necessary. You can provide
+a numeric prefix argument (as in @kbd{4 K e}) to view the attachment
+labeled with that number. This command tries to provide a reasonable
+default for the viewer by calling the Emacs function
+@code{mailcap-mime-info}. This function usually reads the file
+@file{/etc/mailcap}.
+
+@cindex attachments, saving
+@cindex saving attachments
+@findex mh-folder-save-mime-part
+@kindex K o
+
+Use the command @kbd{K o} (@code{mh-folder-save-mime-part}) to save
+attachments (the mnemonic is ``output''). This command saves the
+attachment associated with the button under the cursor. If the cursor
+is not located over a button, then the cursor first moves to the next
+button, wrapping to the beginning of the message if necessary. You can
+also provide a numeric prefix argument (as in @kbd{3 K o}) to save the
+attachment labeled with that number. This command prompts you for a
+filename and suggests a specific name if it is available.
+
+@cindex @command{mhn}
+@cindex @command{mhstore}
+@cindex MH commands, @command{mhn}
+@cindex MH commands, @command{mhstore}
+@findex mh-mime-save-parts
+@kindex K a
+@vindex mh-mime-save-parts-default-directory
+
+You can save all of the attachments at once with the command @kbd{K a}
+(@code{mh-mime-save-parts}). The attachments are saved in the
+directory specified by the option
+@code{mh-mime-save-parts-default-directory} unless you use a prefix
+argument (as in @kbd{C-u K a}) in which case you are prompted for the
+directory. These directories may be superseded by MH profile
+components, since this function calls on @command{mhstore}
+(@command{mhn}) to do the work.
+
+@vindex mh-mime-save-parts-default-directory
+
+The default value for the option
+@code{mh-mime-save-parts-default-directory} is @samp{Prompt Always} so
+that you are always prompted for the directory in which to save the
+attachments. However, if you usually use the same directory within a
+session, then you can set this option to @samp{Prompt the First Time}
+to avoid the prompt each time. you can make this directory permanent
+by choosing @samp{Directory} and entering the directory's name.
+
+@cindex attachments, inline
+@cindex inline attachments
+@findex mh-toggle-mime-buttons
+@kindex K t
+@vindex mh-display-buttons-for-inline-parts-flag
+
+The sender can request that attachments should be viewed inline so
+that they do not really appear like an attachment at all to the
+reader. Most of the time, this is desirable, so by default MH-E
+suppresses the buttons for inline attachments. On the other hand, you
+may receive code or HTML which the sender has added to his message as
+inline attachments so that you can read them in MH-E. In this case, it
+is useful to see the buttons so that you know you don't have to cut
+and paste the code into a file; you can simply save the attachment. If
+you want to make the buttons visible for inline attachments, you can
+use the command @kbd{K t} (@code{mh-toggle-mime-buttons}) to toggle
+the visibility of these buttons. You can turn on these buttons
+permanently by turning on the option
+@code{mh-display-buttons-for-inline-parts-flag}.
+
+MH-E cannot display all attachments inline however. It can display
+text (including @sc{html}) and images.
+
+@cindex header field, @samp{Content-Disposition:}
+@cindex inline images
+@cindex @samp{Content-Disposition:} header field
+@vindex mh-max-inline-image-height
+@vindex mh-max-inline-image-width
+
+Some older mail programs do not insert the needed
+plumbing@footnote{This plumbing is the @samp{Content-Disposition:}
+header field.} to tell MH-E whether to display the attachments inline
+or not. If this is the case, MH-E will display these images inline if
+they are smaller than the window. However, you might want to allow
+larger images to be displayed inline. To do this, you can change the
+options @code{mh-max-inline-image-width} and
+@code{mh-max-inline-image-height} from their default value of zero to
+a large number. The size of your screen is a good choice for these
+numbers.
+
+@cindex alternatives
+@cindex attachments, alternatives
+@vindex mh-display-buttons-for-alternatives-flag
+
+Sometimes, a mail program will produce multiple alternatives of an
+attachment in increasing degree of faithfulness to the original
+content. By default, only the preferred alternative is displayed. If
+the option @code{mh-display-buttons-for-alternatives-flag} is on, then
+the preferred part is shown inline and buttons are shown for each of
+the other alternatives.
+
+@vindex mm-discouraged-alternatives
+
+Many people prefer to see the @samp{text/plain} alternative rather
+than the @samp{text/html} alternative. To do this in MH-E, customize
+the option @code{mm-discouraged-alternatives}, and add
+@samp{text/html}. The next best alternative, if any, will be shown.
+
+@kindex K i
+@findex mh-folder-inline-mime-part
+
+You can view the raw contents of an attachment with the command @kbd{K
+i} (@code{mh-folder-inline-mime-part}). This command displays (or
+hides) the contents of the attachment associated with the button under
+the cursor verbatim. If the cursor is not located over a button, then
+the cursor first moves to the next button, wrapping to the beginning
+of the message if necessary. You can also provide a numeric prefix
+argument (as in @kbd{4 K i}) to view the attachment labeled with that
+number.
+
+For additional information on buttons, see
+@ifinfo
+@ref{Article Buttons,,,gnus}, and @ref{MIME Commands,,,gnus}.
+@end ifinfo
+@ifnotinfo
+the chapters @uref{http://www.gnus.org/manual/gnus_101.html#SEC101,
+Article Buttons} and
+@uref{http://www.gnus.org/manual/gnus_108.html#SEC108, MIME Commands}
+in the @cite{The Gnus Manual}.
+@end ifnotinfo
+
+@node HTML, Digests, Viewing Attachments, Reading Mail
+@section HTML
+
+@cindex HTML
+@cindex Gnus
+
+MH-E can display messages that have been sent in HTML@footnote{This
+feature depends on a version of Gnus that is at least 5.10.}. The
+content of the message will appear in the MH-Show buffer as you would
+expect if the entire message is HTML, or there is an inline HTML body
+part. However, if there is an HTML body part that is an attachment,
+then you'll see a button like this:
+
+@smallexample
+[1. text/html; foo.html]...
+@end smallexample
+
+To see how to read the contents of this body part, see @ref{Viewing
+Attachments}.
+
+@vindex mm-text-html-renderer
+
+The browser that MH-E uses is determined by the option
+@code{mm-text-html-renderer}. The default setting is set automatically
+based upon the presence of a known browser on your system. If you wish
+to use a different browser, then set this option accordingly. See the
+documentation for the browser you use for additional information on
+how to use it. In particular, find and disable the option to render
+images as this can tip off spammers that the email address they have
+used is valid.
+
+@vindex mm-text-html-renderer
+
+If you're confused about which @code{mm-text-html-renderer} to use,
+here's a brief description of each, sorted by popularity, that
+includes the results of a quick poll of MH-E users from 2005-12-23.
+
+@table @asis
+@cindex browser, @samp{w3m}
+@cindex @samp{w3m}
+@kindex Mouse-2
+@kindex S-Mouse-2
+@item @samp{w3m} 7
+The @samp{w3m} browser requires an external program. It's quick,
+produces pretty nice output, and best of all, it's the only browser
+that highlights links. These can be clicked with @kbd{Mouse-2} to view
+the content of the link in @samp{w3m} or with @kbd{S-Mouse-2} to view
+the content of the link in an external browser. The @samp{w3m} browser
+handles tables well and actually respects the table's width parameter
+(which can cause text to wrap if the author didn't anticipate that the
+page would be viewed in Emacs).
+@c -------------------------
+@cindex browser, @samp{w3m-standalone}
+@cindex @samp{w3m-standalone}
+@item @samp{w3m-standalone} 3
+This browser, along with @samp{nil} for the external browser, are the
+only choices that work without having to download a separate lisp
+package or external program. This browser is quick, but does not show
+links. It handles simple tables but some tables get rendered much
+wider than the Emacs frame. This browser was the only one not to
+handle the escape @samp{–} (it printed a @samp{?}), but it did
+render @samp{®}.
+@c -------------------------
+@cindex browser, @samp{links}
+@cindex @samp{links}
+@item @samp{links} 1
+The @samp{links} browser requires an external program. It's quick, and
+produces nicer output than @samp{lynx} on single column mails in
+tables. However, it doesn't show links and it doesn't do as nice a job
+on multi-column tables as some lines wrap. At least it fits in 80
+columns and thus seems better than @samp{w3} and
+@samp{w3m-standalone}. Converts escapes such as @samp{®} to (R).
+@c -------------------------
+@cindex browser, @samp{lynx}
+@cindex @samp{lynx}
+@item @samp{lynx} 1
+The @samp{lynx} browser requires an external program. It's quick and
+produces pretty decent output but it doesn't show links. It doesn't
+seem to do multi-column tables which makes output much cleaner. It
+centers the output and wraps long lines more than most. Handles
+@samp{®}.
+@c -------------------------
+@item @samp{nil} 1
+This choice obviously requires an external browser. Like
+@samp{w3m-standalone}, it works out of the box. With this setting,
+HTML messages have a button for the body part which you can view with
+@kbd{K v} (@code{mh-folder-toggle-mime-part}).
+@c -------------------------
+@cindex browser, @samp{w3}
+@cindex @samp{w3}
+@item @samp{w3} 0
+This choice does not require an external program as all of the
+rendering is done in lisp. You do need to get the package separately.
+This browser is @strong{slow}, and doesn't appear to have been updated
+since 2001 and the author hasn't responded to my emails. It displays
+unknown tags instead of hiding them, so you get to see all the
+Microsoft crap in certain messages. Tends to make multi-column tables
+wider than even a full-screen Emacs can handle. Like @samp{w3m}, you
+can follow links, but you have to find them first as they are not
+highlighted. Performs well on single-column tables and handles escapes
+such as @samp{®}.
+@c -------------------------
+@cindex browser, @samp{html2text}
+@cindex @samp{html2text}
+@item @samp{html2text} 0
+The @samp{html2text} browser requires an external program. I noticed
+that it can do some nasty things with simple HTML mails (like filling
+the entire message as if it were one paragraph, including signature).
+On another message, it displayed half of the HTML tags for some
+reason.
+@end table
+
+@vindex mm-text-html-renderer
+
+For a couple more sources of information about
+@code{mm-text-html-renderer},
+@ifinfo
+@xref{Display Customization,,,emacs-mime}, and the documentation for
+the Gnus command @kbd{W h} (@pxref{Article Washing,,,gnus},).
+@end ifinfo
+@ifnotinfo
+see section @uref{http://www.gnus.org/manual/emacs-mime_6.html,
+Display Customization} in the @cite{The Emacs MIME Manual} and the
+documentation for the Gnus command @kbd{W h} (see section
+@uref{http://www.gnus.org/manual/gnus_99.html, Article Washing} in the
+@cite{The Gnus Manual}).
+@end ifnotinfo
+
+@node Digests, Reading PGP, HTML, Reading Mail
+@section Digests
+
+@cindex digests
+@findex mh-page-digest
+@findex mh-page-digest-backwards
+@kindex D @key{BS}
+@kindex D @key{SPC}
+@kindex @key{BS}
+@kindex @key{SPC}
+
+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{BS} 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{D @key{SPC}} (@code{mh-page-digest}). To return to a previous message,
+use @kbd{D @key{BS}} (@code{mh-page-digest-backwards}).
+
+@cindex @command{burst}
+@cindex MH commands, @command{burst}
+@cindex MH-Folder Show mode
+@cindex modes, MH-Folder Show
+@findex mh-burst-digest
+@kindex d
+@kindex D b
+@kindex t
+
+Another handy command is @kbd{D b} (@code{mh-burst-digest}). This
+command uses the MH command @command{burst}@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/burdig.html, Bursting Messages} in the MH
+book.} 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{Folders}) so that the scan lines fill the screen
+and messages aren't displayed. Then use @kbd{d} (@pxref{Reading Mail})
+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 (@pxref{Editing
+Drafts}).
+
+@node Reading PGP, Printing, Digests, Reading Mail
+@section Signed and Encrypted Messages
+
+@cindex GPG
+@cindex GnuPG
+@cindex Gnus
+@cindex OpenPGP
+@cindex PGP
+@cindex RFC 3156
+@cindex encrypted messages
+@cindex security
+@cindex signed messages
+
+You can read encrypted or signed PGP or GPG messages with
+MH-E@footnote{This feature depends on post-5.10 versions of Gnus.
+@cite{MIME Security with OpenPGP} is documented in
+@uref{http://www.rfc-editor.org/rfc/rfc3156.txt, RFC 3156}. However,
+MH-E can also decrypt old-style PGP messages that are not in MIME
+format.}. This section assumes that you already have a good
+understanding of GPG and have set up your keys appropriately.
+
+If someone sends you a signed message, here is what you'll see:
+
+@smallexample
+@group
+[[PGP Signed Part:Bill Wohler <wohler@@stop.mail-abuse.org>]]
+This is a signed message.
+
+[[End of PGP Signed Part]]
+@end group
+@end smallexample
+
+@cindex keychain
+@cindex key server
+@cindex signed messages
+
+If the key for the given signature is not in your keychain, you'll be
+given the opportunity to fetch the key from a key server and verify
+the key. If the message is really large, the verification process can
+take a long time. You can press @kbd{C-g} at any time to
+cancel@footnote{Unfortunately in the current version, the validation
+process doesn't display a message so it appears that MH-E has hung. We
+hope that this will be fixed in the future.}.
+
+If the signature doesn't check out, you might see something like this:
+
+@smallexample
+@group
+[[PGP Signed Part:Failed]]
+This is a signed message.
+This is garbage added after the signature was made.
+
+[[End of PGP Signed Part]]
+@end group
+@end smallexample
+
+@cindex decrypting messages
+
+If someone sends you an encrypted message, MH-E will ask for your
+passphrase to decrypt the message. You should see something like this:
+
+@smallexample
+@group
+[[PGP Encrypted Part:OK]]
+
+[[PGP Signed Part:Bill Wohler <wohler@@stop.mail-abuse.org>]]
+This is the secret message.
+
+[[End of PGP Signed Part]]
+
+[[End of PGP Encrypted Part]]
+@end group
+@end smallexample
+
+If there is a problem decrypting the message, the button will say:
+
+@smallexample
+[[PGP Encrypted Part:Failed]]
+@end smallexample
+
+You can read the contents of this button using the methods described in
+@ref{Viewing Attachments}. If the message were corrupted, you'd see
+this:
+
+@smallexample
+[[PGP Encrypted Part:Failed]
+Invalid base64 data]
+@end smallexample
+
+If your passphrase were incorrect, you'd see something like this:
+
+@smallexample
+[GNUPG:] ENC_TO CD9C88BB610BD9AD 1 0
+[GNUPG:] USERID_HINT CD9C88BB610BD9AD Bill Wohler <wohler@@stop.mail-abuse.org>
+[GNUPG:] NEED_PASSPHRASE CD9C88BB610BD9AD CD9C88BB610BD9AD 1 0
+[GNUPG:] BAD_PASSPHRASE CD9C88BB610BD9AD
+gpg: encrypted with 1024-bit RSA key, ID 610BD9AD, created 1997-09-09
+ "Bill Wohler <wohler@@stop.mail-abuse.org>"
+gpg: public key decryption failed: bad passphrase
+[GNUPG:] BEGIN_DECRYPTION
+[GNUPG:] DECRYPTION_FAILED
+gpg: decryption failed: secret key not available
+[GNUPG:] END_DECRYPTION
+
+gpg exited abnormally: '2'
+@end smallexample
+
+@vindex mh-show-pgg-bad
+@vindex mh-show-pgg-good
+@vindex mh-show-pgg-unknown
+
+The appearance of the buttons is controlled by the faces
+@code{mh-show-pgg-good}, @code{mh-show-pgg-bad}, and
+@code{mh-show-pgg-unknown} depending on the validity of the signature.
+The latter is used whether the signature is unknown or untrusted.
+
+@cindex @samp{pgg} customization group
+@cindex PGG
+@cindex customization group, @samp{pgg}
+
+The @samp{pgg} customization group may have some settings which may
+interest you.
+@iftex
+See @cite{The PGG Manual}.
+@end iftex
+@ifinfo
+@xref{Top, , The PGG Manual, pgg, The PGG Manual}.
+@end ifinfo
+@ifhtml
+See
+@uref{http://www.dk.xemacs.org/Documentation/packages/html/pgg.html,
+@cite{The PGG Manual}}.
+@end ifhtml
+
+@node Printing, Files and Pipes, Reading PGP, Reading Mail
+@section Printing Your Mail
+
+@cindex printing
+@findex mh-ps-print-msg
+@findex mh-ps-print-msg-file
+@kindex P f
+@kindex P p
+@vindex mh-lpr-command-format
+@vindex mh-print-background-flag
+
+To print messages in MH-E, use the command @kbd{P p}
+(@code{mh-ps-print-msg}). You can print all the messages in a range
+(as in @kbd{C-u P p 1 3 5-7 last:5 frombob @key{RET}},
+@pxref{Ranges}). You can also send the output to a file with @kbd{P f}
+(@code{mh-ps-print-msg-file}). This command will print inline text
+attachments but will not decrypt messages. However, when a message is
+displayed in an MH-Show buffer, then that buffer is used verbatim for
+printing with the caveat that only text attachments, if opened inline,
+are printed. Therefore, encrypted messages can be printed by showing
+and decrypting them first. The commands @kbd{P p} and @kbd{P f} do not
+use the options @code{mh-lpr-command-format} or
+@code{mh-print-background-flag}, described below.
+
+@findex mh-ps-print-toggle-color
+@kindex P C
+@vindex ps-print-color-p
+
+Colors are emulated on black-and-white printers with shades of gray.
+This might produce illegible output, even if your screen colors only
+use shades of gray. If this is the case, try using the command @kbd{P
+C} (@code{mh-ps-print-toggle-color}) to toggle between color, no
+color, and a black and white representation of the colors and see
+which works best. You change this setting permanently by customizing
+the option @code{ps-print-color-p}.
+
+@findex mh-ps-print-toggle-faces
+@kindex P F
+
+Another related function is the command @kbd{P F}
+(@code{mh-ps-print-toggle-faces}). This command toggles between using
+faces and not. When faces are enabled, the printed message will look
+very similar to the message in the MH-Show buffer.
+
+@cindex ps-print package
+@cindex Emacs, packages, ps-print
+
+MH-E uses the @samp{ps-print} package to do the printing, so you can
+customize the printing further by going to the @samp{ps-print}
+customization group.
+
+@cindex @command{lpr}
+@cindex @command{mhl}
+@cindex MH commands, @command{mhl}
+@cindex Unix commands, @command{lpr}
+@findex mh-print-msg
+@kindex P l
+
+An alternative to using the @samp{ps-print} package is the command
+@kbd{P l} (@code{mh-print-msg}) (the @i{l} is for @i{l}ine printer or
+@i{l}pr). You can print all the messages in a range. The message is
+formatted with @command{mhl}@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/shomes.html#Usisho, Using mhl} in the MH
+book.} and printed with the @command{lpr} command.
+
+@kindex P f
+@kindex P l
+@kindex P p
+@vindex mh-lpr-command-format
+@vindex mh-print-background-flag
+
+The command @kbd{P l} uses two options. The option
+@code{mh-lpr-command-format} contains the Unix command line which
+performs the actual printing. The string can contain one escape,
+@samp{%s}, which is replaced by the name of the folder and the message
+number and is useful for print job names. The default setting is
+@code{"lpr -J '%s'"}. I use @code{"mpage -h'%s' -b Letter -H1of -mlrtb
+-P"} which produces a nice header and adds a bit of margin so the text
+fits within my printer's margins. Normally messages are printed in the
+foreground. If this is slow on your system, you may elect to turn on
+the option @code{mh-print-background-flag} 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. These options are not used by the
+commands @kbd{P p} or @kbd{P f}.
+
+@node Files and Pipes, Navigating, Printing, Reading Mail
+@section Files and Pipes
+
+@cindex files
+@cindex pipes
+@findex mh-refile-or-write-again
+@findex mh-write-msg-to-file
+@kindex >
+@kindex !
+
+MH-E does offer a couple of commands that are not a part of MH@. The
+first one, @kbd{>} (@code{mh-write-msg-to-file}), writes a message to
+a file. 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 > /tmp/foobar @key{RET}}). Subsequent writes to the same file
+can be made with the command @kbd{!}
+(@code{mh-refile-or-write-again}).
+
+@findex mh-pipe-msg
+@kindex |
+@kindex l
+
+You can also pipe the message through a Unix shell command with the
+command @kbd{|} (@code{mh-pipe-msg}). You are prompted for the Unix
+command through which you wish to run your message. If you give a
+prefix 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 @command{shar}
+@cindex @command{uuencode}
+@cindex Unix commands, @command{shar}
+@cindex Unix commands, @command{uuencode}
+@findex mh-store-msg
+@kindex X s
+@vindex mh-store-default-directory
+
+If the message is a shell archive @command{shar} or has been run
+through @command{uuencode} use @kbd{X s} (@code{mh-store-msg}) to
+extract the body of the message. The default directory for extraction
+is the current directory; however, 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. If you would
+like to change the initial default directory, customize the option
+@code{mh-store-default-directory}, change the value from
+@samp{Current} to @samp{Directory}, and then enter the name of the
+directory for storing the content of these messages.
+
+@findex mh-store-buffer
+@kindex @key{RET}
+@kindex X s
+
+By the way, @kbd{X s} 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 @command{uuencode} or @command{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 Navigating, Miscellaneous Commands and Options, Files and Pipes, Reading Mail
+@section Navigating
+
+@cindex moving between messages
+@cindex navigation
+@findex mh-first-msg
+@findex mh-goto-msg
+@findex mh-last-msg
+@findex mh-next-undeleted-msg
+@findex mh-next-unread-msg
+@findex mh-previous-undeleted-msg
+@findex mh-previous-unread-msg
+@kindex g
+@kindex M-<
+@kindex M->
+@kindex M-n
+@kindex M-p
+@kindex n
+@kindex p
+
+To move on to the next message, use the command @kbd{n}
+(@code{mh-next-undeleted-msg}); use @kbd{p}
+(@code{mh-previous-undeleted-msg}) to read the previous message. To
+move to the next unread message, use @kbd{M-n}
+(@code{mh-next-unread-msg}); use @kbd{M-p}
+(@code{mh-previous-unread-msg}) to move to the previous unread
+message. 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
+@findex next-line
+@findex previous-line
+@kindex C-n
+@kindex C-p
+@kindex @key{RET}
+
+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
+@key{RET} to look at deleted or refiled messages.
+
+@cindex deleting messages
+@findex mh-delete-msg
+@kindex d
+@kindex n
+@kindex p
+
+To mark a message for deletion, use the command @kbd{d}
+(@code{mh-delete-msg}). A @samp{D} is placed by the message in the
+scan window, and the next undeleted message is displayed. If the
+previous command had been @kbd{p}, then the next message displayed is
+the first undeleted message previous to the message just deleted. Use
+@kbd{n} to force subsequent @kbd{d} commands to move forward to the
+next undeleted message after deleting the message under the cursor.
+You may also specify a range (for example, @kbd{C-u d 1 3 5-7 last:5
+frombob @key{RET}}, @pxref{Ranges}).
+
+@findex mh-delete-msg-no-motion
+@kindex C-d
+
+The command @kbd{C-d} (@code{mh-delete-msg-no-motion}) marks the
+message (or messages in range) for deletion but leaves the cursor at
+the current message in case you wish to perform other operations on
+the message.
+
+@findex mh-delete-subject
+@findex mh-delete-subject-or-thread
+@findex mh-thread-delete
+@findex mh-undo
+@kindex k
+@kindex T d
+@kindex u
+
+And to delete more messages faster, you can use @kbd{k}
+(@code{mh-delete-subject-or-thread}) to delete all the messages with
+the same subject as the current message. This command puts these
+messages in a sequence named @samp{subject}. You can undo this action
+by using @kbd{u} (@code{mh-undo}) with a prefix argument and then
+specifying the @samp{subject} sequence. However, if the buffer is
+displaying a threaded view of the folder then @kbd{k} behaves like
+@kbd{T d} (@code{mh-thread-delete}). @xref{Threading}.
+
+@findex mh-execute-commands
+@kindex x
+
+However you mark a message for deletion, the command @kbd{x}
+(@code{mh-execute-commands}) actually carries out the deletion
+(@pxref{Folders}).
+
+@vindex mh-delete-msg-hook
+
+The hook @code{mh-delete-msg-hook} is called after you mark a message
+for deletion. For example, a past maintainer of MH-E used this once
+when he kept statistics on his mail usage.
+
+@node Miscellaneous Commands and Options, , Navigating, Reading Mail
+@section Miscellaneous Commands and Options
+
+This section contains a few more miscellaneous commands and options.
+
+@cindex editing message
+@findex mh-modify
+@kindex M
+
+There are times when you need to edit a message. For example, you may
+need to fix a broken Content-Type header field. You can do this with
+the command @kbd{M} (@code{mh-modify}). It displays the raw message in
+an editable buffer. When you are done editing, save and kill the
+buffer as you would any other.
+
+@findex mh-kill-folder
+@findex mh-pack-folder
+@vindex mh-do-not-confirm-flag
+
+Commands such as @code{mh-pack-folder} prompt to confirm whether to
+process outstanding moves and deletes or not before continuing.
+Turning on the option @code{mh-do-not-confirm-flag} means that these
+actions will be performed---which is usually desired but cannot be
+retracted---without question@footnote{In previous versions of MH-E,
+this option suppressed the confirmation in @code{mh-kill-folder}.
+Since this kept most users from setting this option,
+@code{mh-kill-folder} was modified in version 6.0 to always ask for
+confirmation subject to @code{mh-kill-folder-suppress-prompt-hook}.
+@xref{Folders}.}.
+
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+@vindex mh-summary-height
+
+The option @code{mh-summary-height} controls the number of scan lines
+displayed in the MH-Folder window, including the mode line. The
+default value of this option is @samp{Automatic} which means that the
+MH-Folder buffer will maintain the same proportional size if the frame
+is resized. If you'd prefer a fixed height, then choose the
+@samp{Fixed Size} option and enter the number of lines you'd like to
+see.
+
+@vindex mh-bury-show-buffer-flag
+
+Normally the buffer for displaying messages is buried at the bottom at
+the buffer stack. You may wish to disable this feature by turning off
+the option @code{mh-bury-show-buffer-flag}. 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.
+
+@cindex @file{.emacs}
+@cindex files, @file{.emacs}
+@cindex reading mail
+
+Before we leave this section, I'll include 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 section, simply add the following
+code to @file{~/.emacs}.
+
+@iftex
+@filbreak
+@end iftex
+
+@findex mh-rmail, example
+
+@smalllisp
+@group
+(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 @key{RET}}
+
+@i{Starting MH-E}
+
+@end group
+@end smalllisp
+
+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 the @samp{+inbox} buffer 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.
+
+@node Folders, Sending Mail, Reading Mail, Top
+@chapter Organizing Your Mail with Folders
+
+@cindex @samp{Folder} menu
+@cindex @samp{Message} menu
+@cindex folders
+@cindex menu, @samp{Folder}
+@cindex menu, @samp{Message}
+@cindex using folders
+
+This chapter discusses the things you can do with folders within MH-E.
+The commands in this chapter are also found in the @samp{Folder} and
+@samp{Message} menus.
+
+@table @kbd
+@kindex ?
+@findex mh-help
+@item ?
+Display cheat sheet for the MH-E commands (@code{mh-help}).
+@c -------------------------
+@kindex !
+@findex mh-refile-or-write-again
+@item !
+Repeat last output command (@code{mh-refile-or-write-again}).
+@c -------------------------
+@cindex @samp{Message > Copy Message to Folder...} menu item
+@cindex menu item, @samp{Message > Copy Message to Folder...}
+@kindex c
+@findex mh-copy-msg
+@item c
+Copy range to folder (@code{mh-copy-msg}).
+@c -------------------------
+@kindex F ?
+@findex mh-prefix-help
+@item F ?
+Display cheat sheet for the commands of the current prefix in
+minibuffer (@code{mh-prefix-help}).
+@c -------------------------
+@kindex F '
+@findex mh-index-ticked-messages
+@item F '
+Display ticked messages (@code{mh-index-ticked-messages}).
+@c -------------------------
+@kindex F c
+@findex mh-catchup
+@item F c
+Delete range from the @samp{unseen} sequence (@code{mh-catchup}).
+@c -------------------------
+@kindex F k
+@findex mh-kill-folder
+@item F k
+Remove folder (@code{mh-kill-folder}).
+@c -------------------------
+@cindex @samp{Folder > List Folders} menu item
+@cindex menu item, @samp{Folder > List Folders}
+@kindex F l
+@findex mh-list-folders
+@item F l
+List all folders (@code{mh-list-folders}).
+@c -------------------------
+@cindex @samp{Folder > View New Messages} menu item
+@cindex menu item, @samp{Folder > View New Messages}
+@kindex F n
+@findex mh-index-new-messages
+@item F n
+Display unseen messages (@code{mh-index-new-messages}).
+@c -------------------------
+@cindex @samp{Folder > Pack Folder} menu item
+@cindex menu item, @samp{Folder > Pack Folder}
+@kindex F p
+@findex mh-pack-folder
+@item F p
+Pack folder (@code{mh-pack-folder}).
+@c -------------------------
+@kindex F q
+@findex mh-index-sequenced-messages
+@item F q
+Display messages in any sequence (@code{mh-index-sequenced-messages}).
+@c -------------------------
+@cindex @samp{Folder > Rescan Folder} menu item
+@cindex menu item, @samp{Folder > Rescan Folder}
+@kindex F r
+@findex mh-rescan-folder
+@item F r
+Rescan folder (@code{mh-rescan-folder}).
+@c -------------------------
+@cindex @samp{Folder > Search...} menu item
+@cindex menu item, @samp{Folder > Search...}
+@kindex F s
+@findex mh-search
+@item F s
+Search your MH mail (@code{mh-search}).
+@c -------------------------
+@cindex @samp{Folder > Sort Folder} menu item
+@cindex menu item, @samp{Folder > Sort Folder}
+@kindex F S
+@findex mh-sort-folder
+@item F S
+Sort folder (@code{mh-sort-folder}).
+@c -------------------------
+@kindex F u
+@findex mh-undo-folder
+@item F u
+Undo all refiles and deletes in the current folder (@code{mh-undo-folder}).
+@c -------------------------
+@cindex @samp{Folder > Visit a Folder...} menu item
+@cindex menu item, @samp{Folder > Visit a Folder...}
+@kindex F v
+@findex mh-visit-folder
+@item F v
+Visit folder (@code{mh-visit-folder}).
+@c -------------------------
+@cindex @samp{Message > Refile Message} menu item
+@cindex menu item, @samp{Message > Refile Message}
+@kindex o
+@findex mh-refile-msg
+@item o
+Refile (output) range into folder (@code{mh-refile-msg}).
+@c -------------------------
+@cindex @samp{Folder > Quit MH-E} menu item
+@cindex menu item, @samp{Folder > Quit MH-E}
+@kindex q
+@findex mh-quit
+@item q
+Quit the current MH-E folder (@code{mh-quit}).
+@c -------------------------
+@cindex @samp{Folder > Toggle Show/Folder} menu item
+@cindex menu item, @samp{Folder > Toggle Show/Folder}
+@kindex t
+@findex mh-toggle-showing
+@item t
+Toggle between MH-Folder and MH-Folder Show modes
+(@code{mh-toggle-showing}).
+@c -------------------------
+@cindex @samp{Message > Undo Delete/Refile} menu item
+@cindex menu item, @samp{Message > Undo Delete/Refile}
+@kindex u
+@findex mh-undo
+@item u
+Undo pending deletes or refiles in range (@code{mh-undo}).
+@c -------------------------
+@cindex @samp{Message > Execute Delete/Refile} menu item
+@cindex menu item, @samp{Message > Execute Delete/Refile}
+@kindex x
+@findex mh-execute-commands
+@item x
+Process outstanding delete and refile requests
+(@code{mh-execute-commands}).
+@end table
+
+@cindex @samp{mh-folder} customization group
+@cindex customization group, @samp{mh-folder}
+
+The @samp{mh-folder} customization group is used to tune these
+commands.
+
+@vtable @code
+@item mh-new-messages-folders
+Folders searched for the @samp{unseen} sequence (default:
+@code{Inbox}).
+@c -------------------------
+@item mh-ticked-messages-folders
+Folders searched for @code{mh-tick-seq} (default: @code{t}).
+@c -------------------------
+@item mh-large-folder
+The number of messages that indicates a large folder (default: 200).
+@c -------------------------
+@item mh-recenter-summary-flag
+On means to recenter the summary window (default: @samp{off}).
+@c -------------------------
+@item mh-recursive-folders-flag
+On means that commands which operate on folders do so recursively
+(default: @samp{off}).
+@c -------------------------
+@item mh-sortm-args
+Additional arguments for @command{sortm} (default: @code{nil}).
+@end vtable
+
+The following hooks are available.
+
+@vtable @code
+@item mh-after-commands-processed-hook
+Hook run by @kbd{x} after performing outstanding refile and delete
+requests (default: @code{nil}).
+@c -------------------------
+@item mh-before-commands-processed-hook
+Hook run by @kbd{x} before performing outstanding refile and delete
+requests (default: @code{nil}).
+@c -------------------------
+@item mh-before-quit-hook
+Hook run by q before quitting MH-E (default: @code{nil}).
+@c -------------------------
+@item mh-folder-mode-hook
+Hook run by @code{mh-folder-mode} when visiting a new folder (default:
+@code{nil}).
+@c -------------------------
+@item mh-kill-folder-suppress-prompt-hook
+Abnormal hook run at the beginning of @code{mh-kill-folder} (default:
+@code{'mh-search-p}).
+@c -------------------------
+@item mh-quit-hook
+Hook run by q after quitting MH-E (default: @code{nil}).
+@c -------------------------
+@item mh-refile-msg-hook
+Hook run by o after marking each message for refiling (default:
+@code{nil}).
+@end vtable
+
+The following faces are available for customizing the appearance of
+the MH-Folder buffer. @xref{Scan Line Formats}.
+
+@vtable @code
+@item mh-folder-address
+Recipient face.
+@c -------------------------
+@item mh-folder-body
+Body text face.
+@c -------------------------
+@item mh-folder-cur-msg-number
+Current message number face.
+@c -------------------------
+@item mh-folder-date
+Date face.
+@c -------------------------
+@item mh-folder-deleted
+Deleted message face.
+@c -------------------------
+@item mh-folder-followup
+@samp{Re:} face.
+@c -------------------------
+@item mh-folder-msg-number
+Message number face.
+@c -------------------------
+@item mh-folder-refiled
+Refiled message face.
+@c -------------------------
+@vindex mh-scan-format-nmh
+@vindex mh-scan-sent-to-me-sender-regexp
+@item mh-folder-sent-to-me-hint
+Fontification hint face in messages sent directly to us. The detection
+of messages sent to us is governed by the scan format
+@code{mh-scan-format-nmh} and regular expression
+@code{mh-scan-sent-to-me-sender-regexp}.
+@c -------------------------
+@vindex mh-scan-format-nmh
+@vindex mh-scan-sent-to-me-sender-regexp
+@item mh-folder-scan-format
+Sender face in messages sent directly to us. The detection of messages
+sent to us is governed by the scan format @code{mh-scan-format-nmh}
+and regular expression @code{mh-scan-sent-to-me-sender-regexp}.
+@c -------------------------
+@item mh-folder-subject
+Subject face.
+@c -------------------------
+@item mh-folder-tick
+Ticked message face.
+@c -------------------------
+@item mh-folder-to
+@samp{To:} face.
+@end vtable
+
+@vindex mh-folder-mode-hook
+
+The hook @code{mh-folder-mode-hook} is called when visiting a new
+folder in MH-Folder mode. This could be used to set your own key
+bindings, for example:
+
+@vindex mh-folder-mode-hook, example
+
+@smalllisp
+@group
+(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 "//" 'my-search-msg)
+ (local-set-key "b" 'mh-burst-digest) ; @r{better use of @kbd{b}}
+ (setq my-mh-init-done t))))
+
+(add-hook 'mh-folder-mode-hook 'my-mh-folder-mode-hook)
+
+(defun my-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}
+ ; @r{ when done}
+
+@i{Create additional key bindings via mh-folder-mode-hook}
+
+@end group
+@end smalllisp
+
+@cindex @command{folder}
+@cindex @command{refile}
+@cindex MH commands, @command{folder}
+@cindex MH commands, @command{refile}
+@findex mh-refile-msg
+@kindex o
+@vindex mh-refile-msg-hook
+
+MH-E has analogies for each of the MH @command{folder} and
+@command{refile} commands@footnote{See the sections
+@uref{@value{MH-BOOK-HOME}/fol.html#Youfol, Your Current Folder:
+folder} and @uref{@value{MH-BOOK-HOME}/fol.html#Movref, Moving and
+Linking Messages: refile} in the MH book.}. To refile a message in
+another folder, use the command @kbd{o} (@code{mh-refile-msg})
+(mnemonic: ``output''). You are prompted for the folder name
+(@pxref{Folder Selection}). Note that this command can also be used to
+create folders. If you specify a folder that does not exist, you will
+be prompted to create it. The hook @code{mh-refile-msg-hook} is called
+after a message is marked to be refiled.
+
+@findex mh-write-msg-to-file
+@kindex !
+
+If you are refiling several messages into the same folder, you can use
+the command @kbd{!} (@code{mh-refile-or-write-again}) to repeat the
+last refile or write (for the description of @kbd{>}
+(@code{mh-write-msg-to-file}), @pxref{Files and Pipes}). You can use a
+range in either case (for example, @kbd{C-u o 1 3 5-7 last:5 frombob
+@key{RET}}, @pxref{Ranges}).
+
+@cindex expunging refiles and deletes
+@cindex undoing refiles and deletes
+@findex mh-undo
+@kindex u
+
+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 are found in a
+given range (@pxref{Ranges}).
+
+@findex mh-undo-folder
+@kindex F u
+
+Alternatively, you can use @kbd{F u} (@code{mh-undo-folder}) to undo
+all refiles and deletes in the current folder.
+
+@findex mh-execute-commands
+@kindex x
+
+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{F r} or @kbd{F 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.
+
+@kindex x
+@vindex mh-after-commands-processed-hook
+@vindex mh-before-commands-processed-hook
+
+The command @kbd{x} runs @code{mh-before-commands-processed-hook}
+before the commands are processed and
+@code{mh-after-commands-processed-hook} after the commands are
+processed. Variables that are useful with the former hook include
+@code{mh-delete-list} and @code{mh-refile-list} which can be used to
+see which changes will be made to the current folder,
+@code{mh-current-folder}. Variables that are useful with the latter
+hook include @code{mh-folders-changed}, which lists which folders were
+affected by deletes and refiles. This list will always include the
+current folder @code{mh-current-folder}.
+
+@findex mh-copy-msg
+@kindex c
+@kindex o
+
+If you wish to copy a message to another folder, you can use the
+command @kbd{c} (@code{mh-copy-msg}) (see the @option{-link} argument
+to @command{refile}(1)). Like the command @kbd{o}, this command
+prompts you for the name of the target folder and you can specify a
+range (@pxref{Ranges}). Note that unlike the command @kbd{o}, the copy
+takes place immediately. The original copy remains in the current
+folder.
+
+@cindex junk mail
+@cindex MH-Folder mode
+@cindex MH-Folder Show mode
+@cindex modes, MH-Folder
+@cindex modes, MH-Folder Show
+@cindex spam
+@findex mh-toggle-showing
+@kindex t
+
+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.
+
+@cindex MH-Folder mode
+@cindex MH-Show mode
+@cindex modes, MH-Folder
+@cindex modes, MH-Show
+@cindex moving between messages
+@kindex t
+@vindex mh-recenter-summary-flag
+
+When you use @kbd{t} to toggle from MH-Folder Show mode to MH-Folder
+mode, the MH-Show buffer is hidden and the MH-Folder buffer is left
+alone. Setting @code{mh-recenter-summary-flag} 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-flag} is rather useful, but it can be
+annoying on a slow network connection.
+
+@findex mh-visit-folder
+@kindex F v
+@vindex mh-large-folder
+
+When you want to read the messages that you have refiled into folders,
+use the command @kbd{F v} (@code{mh-visit-folder}) to visit the
+folder. You are prompted for the folder name. The folder buffer will
+show just unseen messages if there are any; otherwise, it will show
+all the messages in the buffer as long there are fewer than
+@code{mh-large-folder} messages. If there are more, then you are
+prompted for a range of messages to scan. You can provide a prefix
+argument in order to specify a range of messages to show when you
+visit the folder (@pxref{Ranges}). In this case, regions are not used
+to specify the range and @code{mh-large-folder} is ignored. Note that
+this command can also be used to create folders. If you specify a
+folder that does not exist, you will be prompted to create it.
+
+@findex mh-search
+@kindex F s
+
+If you forget where you've refiled your messages, you can find them
+using @kbd{F s} (@code{mh-search}). @xref{Searching}.
+
+@cindex @command{procmail}
+@cindex @samp{unseen} sequence
+@cindex sequence, @samp{unseen}
+@cindex Unix commands, @command{procmail}
+@cindex unseen messages, viewing
+@findex mh-index-new-messages
+@kindex F n
+@vindex mh-new-messages-folders
+
+If you use a program such as @command{procmail} to file your incoming
+mail automatically, you can display new, unseen, messages using the
+command @kbd{F n} (@code{mh-index-new-messages}). All messages in the
+@samp{unseen} sequence from the folders in
+@code{mh-new-messages-folders} are listed. However, this list of
+folders can be overridden with a prefix argument: with a prefix
+argument, enter a space-separated list of folders, or nothing to
+search all folders.
+
+@cindex @samp{tick} sequence
+@cindex sequence, @samp{tick}
+@cindex ticked messages, viewing
+@findex mh-index-ticked-messages
+@kindex F '
+@vindex mh-ticked-messages-folders
+
+If you have ticked messages (@pxref{Sequences}), you can display them
+using the command @kbd{F '} (@code{mh-index-ticked-messages}). All
+messages in the @samp{tick} sequence from the folders in
+@code{mh-ticked-messages-folders} are listed. With a prefix argument,
+enter a space-separated list of folders, or nothing to search all
+folders.
+
+@findex mh-index-sequenced-messages
+@kindex F q
+@vindex mh-new-messages-folders
+
+You can display messages in any sequence with the command @kbd{F q}
+(@code{mh-index-sequenced-messages}). All messages from the folders in
+@code{mh-new-messages-folders} in the sequence you provide are listed.
+With a prefix argument, enter a space-separated list of folders at the
+prompt, or nothing to search all folders.
+
+@vindex mh-new-messages-folders
+@vindex mh-recursive-folders-flag
+@vindex mh-ticked-messages-folders
+
+Set the options @code{mh-new-messages-folders} and
+@code{mh-ticked-messages-folders} to @samp{Inbox} to search the
+@samp{+inbox} folder or @samp{All} to search all of the top level
+folders. Otherwise, list the folders that should be searched with the
+@samp{Choose Folders} menu item. See @code{mh-recursive-folders-flag}.
+
+@cindex buffers, @samp{*MH-E Folders*}
+@cindex @samp{*MH-E Folders*}
+@findex mh-kill-folder
+@findex mh-list-folders
+@findex mh-pack-folder
+@findex mh-rescan-folder
+@findex mh-sort-folder
+@kindex F k
+@kindex F l
+@kindex F p
+@kindex F r
+@kindex F S
+
+Other commands you can perform on folders include: @kbd{F l}
+(@code{mh-list-folders}), to place a listing of all the folders in
+your mail directory in a buffer called @samp{*MH-E Folders*}
+(@pxref{Miscellaneous}); @kbd{F k} (@code{mh-kill-folder}), to remove
+a folder; @kbd{F S} (@code{mh-sort-folder}), to sort the messages by
+date (see @command{sortm}(1) to see how to sort by other criteria);
+@kbd{F p} (@code{mh-pack-folder}), to pack a folder, removing gaps
+from the numbering sequence; and @kbd{F r} (@code{mh-rescan-folder}),
+to rescan the folder, which is useful to grab all messages in your
+@samp{+inbox} after processing your new mail for the first time. If
+you don't want to rescan the entire folder, the commands @kbd{F r} or
+@kbd{F p} will accept a range (@pxref{Ranges}).
+
+@kindex @key{TAB}
+@vindex mh-recursive-folders-flag
+
+By default, operations on folders work only one level at a time. Set
+@code{mh-recursive-folders-flag} 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.
+
+@findex mh-search-p
+@kindex k
+@vindex mh-kill-folder-suppress-prompt-hooks
+
+The hook @code{mh-kill-folder-suppress-prompt-hooks} is an abnormal
+hook run at the beginning of the command @kbd{k}. The hook functions
+are called with no arguments and should return a non-nil value to
+suppress the normal prompt when you remove a folder. This is useful
+for folders that are easily regenerated. The default value of
+@code{mh-search-p} suppresses the prompt on folders generated by
+searching.
+
+@sp 1
+@center @strong{NOTE}
+
+@quotation
+Use this hook with care. If there is a bug in your hook which returns
+@code{t} on @samp{+inbox} and you press @kbd{k} by accident in the
+@code{+inbox} folder, you will not be happy.
+@end quotation
+@sp 1
+
+@cindex @command{sortm}
+@cindex @file{.mh_profile}
+@cindex files, @file{.mh_profile}
+@cindex MH commands, @command{sortm}
+@cindex MH profile component, @samp{sortm:}
+@cindex @samp{sortm:} MH profile component
+@kindex F S
+@vindex mh-sortm-args
+
+The option @code{mh-sortm-args} holds extra arguments to pass on to
+the command @command{sortm}@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/sorsor.html, Sorting Messages: sortm} in the
+MH book.} when a prefix argument is used with @kbd{F S}. Normally
+default arguments to @command{sortm} are specified in the MH profile.
+This option may be used to provide an alternate view. For example,
+@samp{'(\"-nolimit\" \"-textfield\" \"subject\")} is a useful setting.
+
+@cindex exiting
+@cindex quitting
+@findex mh-quit
+@kindex q
+
+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}. It also removes any MH-E working
+buffers whose name begins with @samp{ *mh-} or @samp{*MH-E }
+(@pxref{Miscellaneous}). You can later restore your MH-E session by
+selecting the @samp{+inbox} buffer or by running @kbd{M-x mh-rmail}
+again.
+
+@findex mh-execute-commands
+@kindex q
+@vindex mh-before-quit-hook
+@vindex mh-before-quit-hook, example
+@vindex mh-quit-hook
+@vindex mh-quit-hook, example
+
+The two hooks @code{mh-before-quit-hook} and @code{mh-quit-hook} are
+called by @kbd{q}. 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. If you find that @kbd{q} buries a lot of
+buffers that you would rather remove, you can use both
+@code{mh-before-quit-hook} and @code{mh-quit-hook} to accomplish that.
+
+@smalllisp
+@group
+(defvar my-mh-folder-buffer-to-delete nil
+ "Folder buffer that is being quit.")
+
+(defun my-mh-before-quit-hook ()
+ "Save folder buffer that is to be deleted."
+ (setq my-mh-folder-buffer-to-delete (current-buffer)))
+
+(defun my-mh-quit-hook ()
+ "Kill folder buffer rather than just bury it."
+ (set-buffer my-mh-folder-buffer-to-delete)
+ (if (get-buffer mh-show-buffer)
+ (kill-buffer mh-show-buffer))
+ (kill-buffer (current-buffer)))
+
+@i{Kill MH-Folder buffer instead of burying it}
+@end group
+@end smalllisp
+
+@cindex folders, renaming
+@cindex renaming folders
+@findex dired
+@findex dired-do-rename
+
+You can use dired to manipulate the folders themselves. For example, I
+renamed my @samp{+out} folder to the more common @samp{+outbox} by
+running dired on my mail directory (@kbd{M-x dired RET ~/Mail RET}),
+moving my cursor to @samp{out} and using the command @kbd{R}
+(@code{dired-do-rename}).
+
+@node Sending Mail, Editing Drafts, Folders, Top
+@chapter Sending Mail
+
+@cindex sending mail
+@findex mh-smail
+@kindex M-x 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
+
+@smallexample
+$ @kbd{emacs -f mh-smail}
+@end smallexample
+
+@findex goto-address-at-point
+@vindex mail-user-agent
+
+There are some commands that need to send a mail message, such as
+@code{goto-address-at-point}. You can configure Emacs to have these
+commands use MH-E by setting the option @code{mail-user-agent} to
+@samp{Emacs interface to MH}.
+
+@cindex @samp{Message} menu
+@cindex menu, @samp{Message}
+
+From within MH-E's MH-Folder mode, other methods of sending mail are
+available as well. These can also be found in the @samp{Message} menu.
+
+@table @kbd
+@cindex @samp{Message > Edit Message Again} menu item
+@cindex menu item, @samp{Message > Edit Message Again}
+@kindex e
+@findex mh-edit-again
+@item e
+Edit a message to send it again (@code{mh-edit-again}).
+@c -------------------------
+@cindex @samp{Message > Re-edit a Bounced Message} menu item
+@cindex menu item, @samp{Message > Re-edit a Bounced Message}
+@kindex E
+@findex mh-extract-rejected-mail
+@item E
+Edit a message that was returned by the mail system
+(@code{mh-extract-rejected-mail}).
+@c -------------------------
+@cindex @samp{Message > Forward Message...} menu item
+@cindex menu item, @samp{Message > Forward Message...}
+@kindex f
+@findex mh-forward
+@item f
+Forward message (@code{mh-forward}).
+@c -------------------------
+@cindex @samp{Message > Reply to Message...} menu item
+@cindex menu item, @samp{Message > Reply to Message...}
+@kindex r
+@findex mh-reply
+@item r
+Reply to a message (@code{mh-reply}).
+@c -------------------------
+@cindex @samp{Message > Compose a New Message} menu item
+@cindex menu item, @samp{Message > Compose a New Message}
+@kindex s
+@findex mh-send
+@item s
+Compose a message (@code{mh-send}).
+@c -------------------------
+@cindex @samp{Message > Redistribute Message...} menu item
+@cindex menu item, @samp{Message > Redistribute Message...}
+@kindex M-d
+@findex mh-redistribute
+@item M-d
+Redistribute a message (@code{mh-redistribute}).
+@c -------------------------
+@findex mh-smail
+@item M-x mh-smail
+Compose a message with the MH mail system.
+@c -------------------------
+@findex mh-smail-other-window
+@item M-x mh-smail-other-window
+Compose a message with the MH mail system in other window.
+@end table
+
+@cindex @samp{mh-sending-mail} customization group
+@cindex customization group, @samp{mh-sending-mail}
+
+In addition, several options from the @samp{mh-sending-mail}
+customization group are useful when sending mail or replying to mail.
+They are summarized in the following table.
+
+@vtable @code
+@item mh-compose-forward-as-mime-flag
+On means that messages are forwarded as attachments (default:
+@samp{on}).
+@c -------------------------
+@item mh-compose-letter-function
+Hook run when starting a new draft (default: @code{nil}).
+@c -------------------------
+@item mh-compose-prompt-flag
+On means prompt for header fields when composing a new draft (default:
+@samp{off}).
+@c -------------------------
+@item mh-forward-subject-format
+Format string for forwarded message subject (default: @code{"%s:
+%s"}).
+@c -------------------------
+@item mh-insert-x-mailer-flag
+On means append an @samp{X-Mailer:} header field to the header
+(default: @samp{on}).
+@c -------------------------
+@item mh-redist-full-contents-flag
+On means the @command{dist} command needs entire letter for
+redistribution (default: @samp{off}).
+@c -------------------------
+@item mh-reply-default-reply-to
+Sets the person or persons to whom a reply will be sent (default:
+@samp{Prompt}).
+@c -------------------------
+@item mh-reply-show-message-flag
+On means the MH-Show buffer is displayed using @kbd{r}
+(@code{mh-reply}) (default: @samp{on}).
+@end vtable
+
+The following hooks are available.
+
+@vtable @code
+@item mh-forward-hook
+Hook run by @code{mh-forward} on a forwarded letter (default:
+@code{nil}).
+@c -------------------------
+@item mh-letter-mode-hook
+Hook run by @code{mh-letter-mode} on a new letter (default:
+@code{nil}).
+@end vtable
+
+The functions and options introduced here are explained in more detail
+in the following sections.
+
+@menu
+* Composing::
+* Replying::
+* Forwarding::
+* Redistributing::
+* Editing Again::
+@end menu
+
+@node Composing, Replying, Sending Mail, Sending Mail
+@section Composing
+
+@cindex @file{.emacs}
+@cindex MH-Folder mode
+@cindex composing mail
+@cindex draft
+@cindex files, @file{.emacs}
+@cindex modes, MH-Folder
+@cindex sending mail
+@findex mh-smail
+@findex mh-smail-other-window
+@kindex M-x mh-smail
+@kindex M-x mh-smail-other-window
+
+Outside of an MH-Folder buffer, you must call either @kbd{M-x
+mh-smail} or @kbd{M-x mh-smail-other-window} to compose a new message.
+The former command always creates a two-window layout with the current
+buffer on top and the draft on the bottom. Use the latter command if
+you would rather preserve the window layout. You may find adding the
+following key bindings to @file{~/.emacs} useful:
+
+@smalllisp
+(global-set-key "\C-xm" 'mh-smail)
+(global-set-key "\C-x4m" 'mh-smail-other-window)
+@end smalllisp
+
+@cindex draft folder
+@cindex MH-Letter mode
+@cindex modes, MH-Letter
+@findex mh-send
+@kindex m
+
+From within a MH-Folder buffer, you can simply use the command @kbd{m}
+(@code{mh-send}). However you invoke @code{mh-send}, your letter
+appears in an Emacs buffer whose mode is MH-Letter (to see what the
+buffer looks like, @pxref{Sending Mail Tour}). MH-Letter mode allows
+you to edit your message, to check the validity of the recipients, to
+insert attachments and 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 named @samp{+drafts} for example, and add the profile
+component @samp{Draft-Folder: drafts} (see @code{mh-profile}(5)).} (a
+message you're composing) in just a moment (@pxref{Editing Drafts}).
+
+@vindex mh-compose-prompt-flag
+
+If you prefer to be prompted for the recipient and subject fields
+before the MH-Letter buffer appears, turn on the option
+@code{mh-compose-prompt-flag}.
+
+@cindex header field, @samp{X-Mailer:}
+@cindex @samp{X-Mailer:} header field
+@vindex mh-insert-x-mailer-flag
+
+MH-E adds an @samp{X-Mailer:} header field to the header that includes
+the version of MH-E and Emacs that you are using. If you don't want to
+participate in our marketing, you can turn off the option
+@code{mh-insert-x-mailer-flag}.
+
+@cindex @command{repl}
+@cindex @file{components}
+@cindex MH commands, @command{repl}
+@cindex MH-Letter mode
+@cindex Mail mode
+@cindex files, @file{components}
+@cindex modes, MH-Letter
+@cindex modes, Mail
+@vindex mail-mode-hook
+@vindex mh-letter-mode-hook
+@vindex text-mode-hook
+
+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@footnote{Actually, because
+MH-Letter mode inherits from Mail mode, the hooks
+@code{text-mode-hook} and @code{mail-mode-hook} are run (in that
+order) before @code{mh-letter-mode-hook}.}. For example, you may wish
+to modify the header after @command{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.
+
+@findex mh-insert-signature, example
+
+@smalllisp
+@group
+(defvar letter-mode-init-done-flag nil
+ "Non-nil means one-time MH-E settings have been made.")
+
+(defun my-mh-letter-mode-hook ()
+ "Prepare letter for editing."
+ (when (not letter-mode-init-done) ; @r{only need to bind the keys once}
+ (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))
+ (save-excursion
+ (goto-char (point-max)) ; @r{go to end of message to}
+ (mh-insert-signature))) ; @r{insert signature}
+
+@i{Prepare draft for editing via mh-letter-mode-hook}
+
+@end group
+@end smalllisp
+
+The function, @code{add-enriched-text} is defined in the example in
+@ref{Adding Attachments}.
+
+@vindex mh-compose-letter-function
+@vindex mh-letter-mode-hook
+
+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.
+
+@node Replying, Forwarding, Composing, Sending Mail
+@section Replying to Mail
+
+@cindex @command{mhl}
+@cindex @file{mhl.reply}
+@cindex MH commands, @command{mhl}
+@cindex files, @file{mhl.reply}
+@cindex replying
+@findex mh-reply
+@kindex r
+
+To compose a reply to a message, use the @kbd{r} (@code{mh-reply})
+command.
+
+When you reply to a message, you are first prompted with @samp{Reply
+to whom?}. You have several choices here.
+
+@quotation
+@multitable @columnfractions .20 .80
+@c @headitem Response @tab Reply Goes To
+@c XXX @headitem not yet supported by SourceForge's texi2pdf.
+@item @b{Response} @tab @b{Reply Goes To}
+@c -------------------------
+@item @kbd{from}
+@tab
+The person who sent the message. This is the default, so @key{RET} is
+sufficient.
+@c -------------------------
+@item @kbd{to}
+@tab
+Replies to the sender, plus all recipients in the @samp{To:} header field.
+@c -------------------------
+@item @kbd{cc}@*@kbd{all}
+@tab
+Forms a reply to the addresses in the @samp{Mail-Followup-To:} header
+field if one exists; otherwise forms a reply to the sender, plus all
+recipients.
+@end multitable
+@end quotation
+
+@cindex @command{repl}
+@cindex MH commands, @command{repl}
+@vindex mh-reply-default-reply-to
+
+Depending on your answer, @command{repl}@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/reprep.html, Replying to Messages: repl} in
+the MH book.} is given a different argument to form your reply.
+Specifically, a choice of @kbd{from} or none at all runs @samp{repl
+-nocc all}, and a choice of @kbd{to} runs @samp{repl -cc to}. Finally,
+either @kbd{cc} or @kbd{all} runs @samp{repl -cc all -nocc me}. If you
+find that most of the time you specify one of these choices when you
+reply to a message, you can change the option
+@code{mh-reply-default-reply-to} from its default value of
+@samp{Prompt} to one of the choices listed above. You can always edit
+the recipients in the draft.
+
+@cindex @samp{repl:} MH profile component
+@cindex MH profile component, @samp{repl:}
+@cindex MH-Letter mode
+@cindex MH-Show mode
+@cindex draft
+@cindex modes, MH-Letter
+@cindex modes, MH-Show
+
+Two windows are then created. One window contains the message to which
+you are replying in an MH-Show buffer. Your draft, in MH-Letter mode
+(@pxref{Editing Drafts}), is in the other window. If the reply draft
+was not one that you expected, check the things that affect the
+behavior of @command{repl} which include the @samp{repl:} profile
+component and the @file{replcomps} and @file{replgroupcomps} files.
+
+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 @command{mhl} with the format file @file{mhl.reply}. See
+@command{mhl}(1) or the section
+@uref{@value{MH-BOOK-HOME}/shomes.html#Usisho, Using mhl} in the MH
+book to see how you can modify the default @file{mhl.reply} file.
+
+@vindex mh-yank-behavior
+
+Alternatively, you can customize the option @code{mh-yank-behavior}
+and choose one of its @samp{Automatically} variants to do the same
+thing. @xref{Inserting Letter}. If you do so, the prefix argument has
+no effect.
+
+Another way to include the message automatically in your draft is to
+use @samp{repl: -filter repl.filter} in your MH profile.
+
+@vindex mh-reply-show-message-flag
+
+If you include the message automatically, you can hide the MH-Show
+buffer by turning off the option @code{mh-reply-show-message-flag}.
+
+If you wish to customize the header or other parts of the reply draft,
+please see @command{repl}(1) and @code{mh-format}(5).
+
+@node Forwarding, Redistributing, Replying, Sending Mail
+@section Forwarding Mail
+
+@cindex @command{forw}
+@cindex draft
+@cindex forwarding
+@cindex MH commands, @command{forw}
+@findex mh-forward
+@kindex f
+@vindex mh-forward-hook
+
+To forward a message, use the @kbd{f} (@code{mh-forward}) command. You
+are prompted for the @samp{To:} and @samp{cc:} recipients. You are
+given a draft to edit that looks like it would if you had run the MH
+command @command{forw}@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/forfor.html, Forwarding Messages: forw} in
+the MH book.}. You can then add some text (@pxref{Editing Drafts}).
+You can forward several messages by using a range (@pxref{Ranges}).
+All of the messages in the range are inserted into your draft. The
+hook @code{mh-forward-hook} is called on the draft.
+
+@cindex @file{.mh_profile}
+@cindex files, @file{.mh_profile}
+@cindex MH profile component, @samp{forw:}
+@cindex @samp{forw:} MH profile component
+@vindex mh-compose-forward-as-mime-flag
+
+By default, the option @code{mh-compose-forward-as-mime-flag} is on
+which means that the forwarded messages are included as attachments.
+If you would prefer to forward your messages verbatim (as text,
+inline), then turn off this option. Forwarding messages verbatim works
+well for short, textual messages, but your recipient won't be able to
+view any non-textual attachments that were in the forwarded message.
+Be aware that if you have @samp{forw: -mime} in your MH profile, then
+forwarded messages will always be included as attachments regardless
+of the settings of @code{mh-compose-forward-as-mime-flag}.
+
+@vindex mh-forward-subject-format
+
+The format of the @samp{Subject:} header field for forwarded messages
+is controlled by the option @code{mh-forward-subject-format}. This
+option 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 @code{"%s: %s"} takes a message with the header:
+
+@smallexample
+@group
+To: Bill Wohler <wohler@@stop.mail-abuse.org>
+Subject: Re: 49er football
+From: Greg DesBrisay <gd@@stop.mail-abuse.org>
+@end group
+@end smallexample
+
+and creates a subject header field of:
+
+@smallexample
+Subject: Greg DesBrisay: Re: 49er football
+@end smallexample
+
+@node Redistributing, Editing Again, Forwarding, Sending Mail
+@section Redistributing Your Mail
+
+@cindex @command{dist}
+@cindex MH commands, @command{dist}
+@cindex redistributing
+@findex mh-redistribute
+@kindex M-d
+
+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.
+When you run this command, you are prompted for the recipients.
+
+@findex mh-edit-again
+@kindex e
+
+For more information on redistributing messages, see
+@command{dist}(1). Also investigate the command @kbd{e}
+(@code{mh-edit-again}) for another way to redistribute messages
+(@pxref{Editing Again}).
+
+@cindex @command{send}
+@cindex MH commands, @command{send}
+@vindex mh-redist-full-contents-flag
+
+The option @code{mh-redist-full-contents-flag} must be turned on if
+@command{dist}@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/disdis.html, Distributing Messages with
+dist} in the MH book.} requires the whole letter for redistribution,
+which is the case if @command{send}@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/sensen.html, Sending Some Mail: comp send}
+in the MH book.} is compiled with the @sc{berk} option (which many
+people abhor). If you find that MH will not allow you to redistribute
+a message that has been redistributed before, turn off this option.
+
+@node Editing Again, , Redistributing, Sending Mail
+@section Editing Old Drafts and Bounced Messages
+
+@cindex @file{draft}
+@cindex files, @file{draft}
+@cindex re-editing drafts
+@findex mh-edit-again
+@kindex F v drafts
+@kindex e
+@kindex n
+
+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{e} (@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{F v drafts
+@key{RET}}, use @kbd{n} to move to the appropriate message, and then
+use @kbd{e} to prepare the message for editing.
+
+@kindex e
+
+The @kbd{e} command can also be used to take messages that were sent
+to you and to send them to more people.
+
+@cindex Mailer-Daemon
+@findex mh-extract-rejected-mail
+@kindex C-c C-c
+@kindex E
+
+Don't use @kbd{e} 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{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 Editing Drafts, Aliases, Sending Mail, Top
+@chapter Editing a Draft
+
+@cindex @samp{Letter} menu
+@cindex MH-Letter mode
+@cindex draft
+@cindex editing draft
+@cindex menu, @samp{Letter}
+@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. These can also be found in the @samp{Letter} menu.
+
+@table @kbd
+@kindex @key{SPC}
+@findex mh-letter-complete-or-space
+@item @key{SPC}
+Perform completion or insert space (@code{mh-letter-complete-or-space}).
+@c -------------------------
+@kindex M-@key{TAB}
+@findex mh-letter-complete
+@item M-@key{TAB}
+Perform completion on header field or word preceding point
+(@code{mh-letter-complete}).
+@c -------------------------
+@kindex , (comma)
+@findex mh-letter-confirm-address
+@item , (comma)
+Flash alias expansion (@code{mh-letter-confirm-address}).
+@c -------------------------
+@kindex @key{TAB}
+@findex mh-letter-next-header-field-or-indent
+@item @key{TAB}
+Cycle to next field (@code{mh-letter-next-header-field-or-indent}).
+@c -------------------------
+@kindex S-@key{TAB}
+@findex mh-letter-previous-header-field
+@item S-@key{TAB}
+Cycle to the previous header field
+(@code{mh-letter-previous-header-field}).
+@c -------------------------
+@kindex C-c ?
+@findex mh-help
+@item C-c ?
+Display cheat sheet for the MH-E commands (@code{mh-help}).
+@c -------------------------
+@cindex @samp{Letter > Send This Draft} menu item
+@cindex menu item, @samp{Letter > Send This Draft}
+@kindex C-c C-c
+@findex mh-send-letter
+@item C-c C-c
+Save draft and send message (@code{mh-send-letter}).
+@c -------------------------
+@kindex C-c C-d
+@findex mh-insert-identity
+@item C-c C-d
+Insert fields specified by the given identity
+(@code{mh-insert-identity}). @xref{Identities}.
+@c -------------------------
+@cindex @samp{Letter > Pull in All Compositions (MH)} menu item
+@cindex menu item, @samp{Letter > Pull in All Compositions (MH)}
+@kindex C-c C-e
+@findex mh-mh-to-mime
+@item C-c C-e
+Compose @sc{mime} message from MH-style directives
+(@code{mh-mh-to-mime}).
+@c -------------------------
+@kindex C-c C-f C-a
+@kindex C-c C-f a
+@findex mh-to-field
+@item C-c C-f C-a
+@itemx C-c C-f a
+Move to @samp{Mail-Reply-To:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-b
+@kindex C-c C-f b
+@item C-c C-f C-b
+@itemx C-c C-f b
+Move to @samp{Bcc:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-c
+@kindex C-c C-f c
+@item C-c C-f C-c
+@itemx C-c C-f c
+Move to @samp{Cc:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-d
+@kindex C-c C-f d
+@item C-c C-f C-d
+@itemx C-c C-f d
+Move to @samp{Dcc:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-f
+@kindex C-c C-f f
+@findex mh-to-fcc
+@item C-c C-f C-f
+@itemx C-c C-f f
+Move to @samp{Fcc:} header field (@code{mh-to-fcc}).
+@c -------------------------
+@kindex C-c C-f C-l
+@kindex C-c C-f l
+@item C-c C-f C-l
+@itemx C-c C-f l
+Move to @samp{Mail-Followup-To:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-m
+@kindex C-c C-f m
+@item C-c C-f C-m
+@itemx C-c C-f m
+Move to @samp{From:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-r
+@kindex C-c C-f r
+@item C-c C-f C-r
+@itemx C-c C-f r
+Move to @samp{Reply-To:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-s
+@kindex C-c C-f s
+@item C-c C-f C-s
+@itemx C-c C-f s
+Move to @samp{Subject:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-t
+@kindex C-c C-f t
+@item C-c C-f C-t
+@itemx C-c C-f t
+Move to @samp{To:} header field (@code{mh-to-field}).
+@c -------------------------
+@cindex @samp{Letter > Insert a Message...} menu item
+@cindex menu item, @samp{Letter > Insert a Message...}
+@kindex C-c C-i
+@findex mh-insert-letter
+@item C-c C-i
+Insert a message (@code{mh-insert-letter}).
+@c -------------------------
+@kindex C-c C-m C-e
+@findex mh-mml-secure-message-encrypt
+@item C-c C-m C-e
+Add tag to encrypt the message (@code{mh-mml-secure-message-encrypt}).
+@c -------------------------
+@cindex @samp{Letter > Compose Forward...} menu item
+@cindex menu item, @samp{Letter > Compose Forward...}
+@kindex C-c C-m C-f
+@kindex C-c C-m f
+@findex mh-compose-forward
+@item C-c C-m C-f
+@itemx C-c C-m f
+Add tag to forward a message (@code{mh-compose-forward}).
+@c -------------------------
+@cindex @samp{Letter > Compose Get File (MH)...} menu item
+@cindex menu item, @samp{Letter > Compose Get File (MH)...}
+@kindex C-c C-m C-g
+@kindex C-c C-m g
+@findex mh-mh-compose-anon-ftp
+@item C-c C-m C-g
+@itemx C-c C-m g
+Add tag to include anonymous ftp reference to a file
+(@code{mh-mh-compose-anon-ftp}).
+@c -------------------------
+@cindex @samp{Letter > Compose Insertion...} menu item
+@cindex menu item, @samp{Letter > Compose Insertion...}
+@kindex C-c C-m C-i
+@kindex C-c C-m i
+@findex mh-compose-insertion
+@item C-c C-m C-i
+@itemx C-c C-m i
+Add tag to include a file such as an image or sound
+(@code{mh-compose-insertion}).
+@c -------------------------
+@cindex @samp{Letter > Pull in All Compositions (MML)} menu item
+@cindex menu item, @samp{Letter > Pull in All Compositions (MML)}
+@kindex C-c C-m C-m
+@kindex C-c C-m m
+@findex mh-mml-to-mime
+@item C-c C-m C-m
+@itemx C-c C-m m
+Compose @sc{mime} message from MML tags (@code{mh-mml-to-mime}).
+@c -------------------------
+@kindex C-c C-m C-n
+@kindex C-c C-m n
+@findex mh-mml-unsecure-message
+@item C-c C-m C-n
+@itemx C-c C-m n
+Remove any secure message tags (@code{mh-mml-unsecure-message}).
+@c -------------------------
+@kindex C-c C-m C-s
+@findex mh-mml-secure-message-sign
+@item C-c C-m C-s
+Add tag to sign the message (@code{mh-mml-secure-message-sign}).
+@c -------------------------
+@cindex @samp{Letter > Compose Compressed tar (MH)...} menu item
+@cindex menu item, @samp{Letter > Compose Compressed tar (MH)...}
+@kindex C-c C-m C-t
+@kindex C-c C-m t
+@findex mh-mh-compose-external-compressed-tar
+@item C-c C-m C-t
+@itemx C-c C-m t
+Add tag to include anonymous ftp reference to a compressed tar file
+(@code{mh-mh-compose-external-compressed-tar}).
+@c -------------------------
+@cindex @samp{Letter > Revert to Non-MIME Edit (MH)} menu item
+@cindex menu item, @samp{Letter > Revert to Non-MIME Edit (MH)}
+@kindex C-c C-m C-u
+@kindex C-c C-m u
+@findex mh-mh-to-mime-undo
+@item C-c C-m C-u
+@itemx C-c C-m u
+Undo effects of @kbd{C-c C-e} (@code{mh-mh-to-mime-undo}).
+@c -------------------------
+@kindex C-c C-m C-x
+@kindex C-c C-m x
+@findex mh-mh-compose-external-type
+@item C-c C-m C-x
+@itemx C-c C-m x
+Add tag to refer to a remote file
+(@code{mh-mh-compose-external-type}).
+@c -------------------------
+@kindex C-c C-m e e
+@findex mh-mml-secure-message-encrypt
+@item C-c C-m e e
+Add tag to encrypt the message (@code{mh-mml-secure-message-encrypt}).
+@c -------------------------
+@kindex C-c C-m e s
+@findex mh-mml-secure-message-signencrypt
+@item C-c C-m e s
+Add tag to encrypt and sign the message@*
+(@code{mh-mml-secure-message-signencrypt}).
+@c -------------------------
+@kindex C-c C-m s e
+@findex mh-mml-secure-message-signencrypt
+@item C-c C-m s e
+Add tag to encrypt and sign the message@*
+(@code{mh-mml-secure-message-signencrypt}).
+@c -------------------------
+@kindex C-c C-m s s
+@findex mh-mml-secure-message-sign
+@item C-c C-m s s
+Add tag to sign the message (@code{mh-mml-secure-message-sign}).
+@c -------------------------
+@cindex @samp{Letter > Split Current Line} menu item
+@cindex menu item, @samp{Letter > Split Current Line}
+@kindex C-c C-o
+@findex mh-open-line
+@item C-c C-o
+Insert a newline and leave point before it (@code{mh-open-line}).
+@c -------------------------
+@cindex @samp{Letter > Kill This Draft} menu item
+@cindex menu item, @samp{Letter > Kill This Draft}
+@kindex C-c C-q
+@findex mh-fully-kill-draft
+@item C-c C-q
+Quit editing and delete draft message (@code{mh-fully-kill-draft}).
+@c -------------------------
+@cindex @samp{Letter > Insert Signature} menu item
+@cindex menu item, @samp{Letter > Insert Signature}
+@kindex C-c C-s
+@findex mh-insert-signature
+@item C-c C-s
+Insert signature in message (@code{mh-insert-signature}).
+@c -------------------------
+@kindex C-c C-t
+@findex mh-letter-toggle-header-field-display
+@item C-c C-t
+Toggle display of header field at point
+(@code{mh-letter-toggle-header-field-display}).
+@c -------------------------
+@cindex @samp{Letter > Check Recipient} menu item
+@cindex menu item, @samp{Letter > Check Recipient}
+@kindex C-c C-w
+@findex mh-check-whom
+@item C-c C-w
+Verify recipients, showing expansion of any aliases
+(@code{mh-check-whom}).
+@c -------------------------
+@cindex @samp{Letter > Yank Current Message} menu item
+@cindex menu item, @samp{Letter > Yank Current Message}
+@kindex C-c C-y
+@findex mh-yank-cur-msg
+@item C-c C-y
+Insert the current message into the draft buffer
+(@code{mh-yank-cur-msg}).
+@c -------------------------
+@kindex C-c M-d
+@findex mh-insert-auto-fields
+@item C-c M-d
+Insert custom fields if recipient is found in
+@code{mh-auto-fields-list} (@code{mh-insert-auto-fields}).
+@xref{Identities}.
+@end table
+
+@cindex @samp{mh-letter} customization group
+@cindex customization group, @samp{mh-letter}
+
+Several options from the @samp{mh-letter} customization group are used
+while editing a draft.
+
+@vtable @code
+@item mh-compose-insertion
+Type of @sc{mime} message tags in messages (default: @samp{MML} if
+available; otherwise @samp{MH}).
+@c -------------------------
+@item mh-compose-skipped-header-fields
+List of header fields to skip over when navigating in draft (default:
+@code{'("From"} @code{"Organization"} @code{"References"}
+@code{"In-Reply-To"} @code{"X-Face"} @code{"Face"}
+@code{"X-Image-URL"} @code{"X-Mailer")}.
+@c -------------------------
+@item mh-compose-space-does-completion-flag
+On means @key{SPC} does completion in message header (default:
+@samp{off}).
+@c -------------------------
+@item mh-delete-yanked-msg-window-flag
+On means delete any window displaying the message (default: @samp{off}).
+@c -------------------------
+@item mh-extract-from-attribution-verb
+Verb to use for attribution when a message is yanked by @kbd{C-c C-y}
+(default: @code{"wrote:"}).
+@c -------------------------
+@item mh-ins-buf-prefix
+String to put before each line of a yanked or inserted message
+(default: @code{"> "}).
+@c -------------------------
+@item mh-letter-complete-function
+Function to call when completing outside of address or folder fields
+(default: @code{ispell-complete-word}).
+@c -------------------------
+@item mh-letter-fill-column
+Fill column to use in MH-Letter mode (default: 72).
+@c -------------------------
+@item mh-mml-method-default
+Default method to use in security tags (default: @samp{PGP (MIME)} if
+support for it is available; otherwise @samp{None}).
+@c -------------------------
+@item mh-signature-file-name
+Source of user's signature (default: @code{"~/.signature"}).
+@c -------------------------
+@item mh-signature-separator-flag
+On means a signature separator should be inserted (default:
+@samp{on}).
+@c -------------------------
+@item mh-x-face-file
+File containing X-Face or Face header field to insert in outgoing mail.
+(default: @code{"~/.face"}).
+@c -------------------------
+@item mh-yank-behavior
+Controls which part of a message is yanked by @kbd{C-c C-y} (default:
+@samp{Body With Attribution}).
+@end vtable
+
+The following hooks are available.
+
+@vtable @code
+@item mail-citation-hook
+Hook for modifying a citation just inserted in the mail buffer
+(default: @code{nil}).
+@c -------------------------
+@item mh-before-send-letter-hook
+Hook run at the beginning of the @kbd{C-c C-c} command (default:
+@samp{nil}).
+@c -------------------------
+@item mh-mh-to-mime-hook
+Hook run on the formatted letter by @kbd{C-c C-e} (default:
+@samp{nil}).
+@c -------------------------
+@item mh-insert-signature-hook
+Hook run by @kbd{C-c C-s} after signature has been inserted (default:
+@code{nil}).
+@end vtable
+
+The following face is available.
+
+@vtable @code
+@item mh-letter-header-field
+Editable header field value face in draft buffers.
+@end vtable
+
+The commands and options introduced here are explained in more
+detail in the following sections.
+
+@menu
+* Editing Message::
+* Inserting Letter::
+* Inserting Messages::
+* Signature::
+* Picture::
+* Adding Attachments::
+* Sending PGP::
+* Checking Recipients::
+* Sending Message::
+* Killing Draft::
+@end menu
+
+@node Editing Message, Inserting Letter, Editing Drafts, Editing Drafts
+@section Editing the Message
+
+@cindex @samp{Bcc:} header field
+@cindex @samp{Cc:} header field
+@cindex @samp{Dcc:} header field
+@cindex @samp{From:} header field
+@cindex @samp{Mail-Followup-To:} header field
+@cindex @samp{Mail-Reply-To:} header field
+@cindex @samp{Reply-To:} header field
+@cindex @samp{Subject:} header field
+@cindex @samp{To:} header field
+@cindex editing header
+@cindex header field, @samp{Bcc:}
+@cindex header field, @samp{Cc:}
+@cindex header field, @samp{Dcc:}
+@cindex header field, @samp{From:}
+@cindex header field, @samp{Mail-Followup-To:}
+@cindex header field, @samp{Mail-Reply-To:}
+@cindex header field, @samp{Reply-To:}
+@cindex header field, @samp{Subject:}
+@cindex header field, @samp{To:}
+@findex mh-to-field
+@kindex C-c C-f C-t
+@kindex C-c C-f t
+
+Because the header is part of the message, you can edit the header
+fields as you wish. However, several convenience commands 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
+commands for moving to the @samp{Cc:}, @samp{Subject:}, @samp{From:},
+@samp{Reply-To:}, @samp{Mail-Reply-To:}, @samp{Mail-Followup-To},
+@samp{Bcc:}, and @samp{Dcc:} header fields are similar.
+
+@findex mh-to-fcc
+@kindex C-c C-f C-f
+@kindex C-c C-f f
+
+One command 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 command
+will prompt you for the folder name in which to file a copy of the
+draft. @xref{Folder Selection}.
+
+@findex indent-relative
+@findex mh-letter-next-header-field-or-indent
+@findex mh-letter-previous-header-field
+@kindex @key{TAB}
+@kindex S-@key{TAB}
+@vindex mh-compose-skipped-header-fields
+@vindex mh-letter-header-field
+
+Within the header of the message, the command@* @key{TAB}
+(@code{mh-letter-next-header-field-or-indent}) moves between fields
+that are highlighted with the face @code{mh-letter-header-field},
+skipping those fields listed in
+@code{mh-compose-skipped-header-fields}. After the last field, this
+command then moves point to the message body before cycling back to
+the first field. If point is already past the first line of the
+message body, then this command indents by calling
+@code{indent-relative} with the given prefix argument. The command
+@kbd{S-@key{TAB}} (@code{mh-letter-previous-header-field}) moves
+backwards between the fields and cycles to the body of the message
+after the first field. Unlike the command @key{TAB}, it will always
+take point to the last field from anywhere in the body.
+
+@cindex alias completion
+@cindex completion
+@cindex spell check
+@findex ispell-complete-word
+@findex mh-letter-complete
+@findex mh-letter-complete-or-space
+@findex mh-letter-confirm-address
+@kindex , (comma)
+@kindex @key{SPC}
+@kindex M-@key{TAB}
+@vindex mh-alias-flash-on-comma
+@vindex mh-compose-space-does-completion-flag
+@vindex mh-letter-complete-function
+
+If the field contains addresses (for example, @samp{To:} or
+@samp{Cc:}) or folders (for example, @samp{Fcc:}) then the command
+@kbd{M-@key{TAB}} (@code{mh-letter-complete}) will provide alias
+completion (@pxref{Aliases}). In the body of the message,
+@kbd{M-@key{TAB}} runs @code{mh-letter-complete-function} instead,
+which is set to @samp{'ispell-complete-word} by default. The command
+@kbd{M-@key{TAB}} (@code{mh-letter-complete}) takes a prefix argument
+that is passed to the @code{mh-letter-complete-function}. In addition,
+turn on the option @code{mh-compose-space-does-completion-flag} to use
+the command @key{SPC} (@code{mh-letter-complete-or-space}) to perform
+completion in the header as well; use a prefix argument to specify
+more than one space. Addresses are separated by a comma; when you
+press the comma, the command @code{mh-letter-confirm-address} flashes
+the alias expansion in the minibuffer if
+@code{mh-alias-flash-on-comma} is turned on.
+
+@c XXX Document the replacement for the inaccessible 'long argument.
+
+@findex mh-letter-toggle-header-field-display
+@kindex C-c C-t
+
+Use the command @kbd{C-c C-t}
+@code{mh-letter-toggle-header-field-display} to display truncated
+header fields. This command is a toggle so entering it again will hide
+the field. This command takes a prefix argument: if negative then the
+field is hidden, if positive then the field is displayed (for example,
+@kbd{C-u C-c C-t}).
+
+Be sure to leave a row of dashes or a blank line between the header
+and the body of the message.
+
+@vindex mh-letter-fill-column
+
+The body of the message is edited as you would edit any Emacs buffer
+although there are a few commands and options to assist you. You can
+change the fill column in MH-Letter mode with the option
+@code{mh-letter-fill-column}. By default, this option is 72 to allow
+others to quote your message without line wrapping.
+
+@cindex filling paragraphs
+@cindex paragraphs, filling
+@findex fill-paragraph
+@kindex M-q
+@vindex mh-ins-buf-prefix
+
+You'll often include messages that were sent from user agents that
+haven't yet realized that paragraphs consist of more than a single
+line. This makes for long lines that wrap in an ugly fashion. You'll
+find that @kbd{M-q} (@code{fill-paragraph}) works well even on these
+quoted messages, even if they are nested, just as long as all of the
+quotes match the value of @code{mh-ins-buf-prefix} (@pxref{Inserting
+Letter}). For example, let's assume you have the following in your
+draft:
+
+@smallexample
+@group
+> Hopefully this gives you an idea of what I'm currently doing. I'm \
+not sure yet whether I'm completely satisfied with my setup, but \
+it's worked okay for me so far.
+@end group
+@end smallexample
+
+Running @kbd{M-q} on this paragraph produces:
+
+@smallexample
+@group
+> Hopefully this gives you an idea of what I'm currently doing. I'm not
+> sure yet whether I'm completely satisfied with my setup, but it's
+> worked okay for me so far.
+@end group
+@end smallexample
+
+@findex mh-open-line
+@findex open-line
+@kindex C-c C-o
+@kindex C-o
+
+The command @kbd{C-c C-o} (@code{mh-open-line}) is similar to the
+command @kbd{C-o} (@code{open-line}) in that it inserts a newline
+after point. It differs in that it also inserts the right number of
+quoting characters and spaces so that the next line begins in the same
+column as it was. This is useful when breaking up paragraphs in
+replies. For example, if this command was used when point was after
+the first period in the paragraph above, the result would be this:
+
+@smallexample
+@group
+> Hopefully this gives you an idea of what I'm currently doing.
+
+> I'm not
+> sure yet whether I'm completely satisfied with my setup, but it's
+> worked okay for me so far.
+@end group
+@end smallexample
+
+@node Inserting Letter, Inserting Messages, Editing Message, Editing Drafts
+@section Inserting Letter to Which You're Replying
+
+@cindex inserting messages
+@cindex replying to messages
+@cindex yanking messages
+@findex mh-yank-cur-msg
+@kindex C-c C-y
+@vindex mh-ins-buf-prefix
+
+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 adding an
+attribution, yanking a portion of text from the message to which
+you're replying, and inserting @code{mh-ins-buf-prefix} (@samp{> })
+before each line.
+
+@smallexample
+@group
+Michael W Thelen <thelenm@@stop.mail-abuse.org> wrote:
+
+> Hopefully this gives you an idea of what I'm currently doing. I'm not
+> sure yet whether I'm completely satisfied with my setup, but it's
+> worked okay for me so far.
+@end group
+@end smallexample
+
+@vindex mh-extract-from-attribution-verb
+
+The attribution consists of the sender's name and email address
+followed by the content of the option
+@code{mh-extract-from-attribution-verb}. This option can be set to
+@samp{wrote:}, @samp{a écrit:}, and @samp{schrieb:}. You can also use
+the @samp{Custom String} menu item to enter your own verb.
+
+@vindex mail-citation-hook
+@vindex mh-ins-buf-prefix
+@vindex mh-yank-behavior
+
+The prefix @code{"> "} is the default setting for the option
+@code{mh-ins-buf-prefix}. I suggest that you not modify this option
+since it is used by many mailers and news readers: messages are far
+easier to read if several included messages have all been indented by
+the same string. This prefix is not inserted if you use one of the
+supercite flavors of @code{mh-yank-behavior} or you have added a
+@code{mail-citation-hook} as described below.
+
+@vindex mh-delete-yanked-msg-window-flag
+
+You can also turn on the @code{mh-delete-yanked-msg-window-flag}
+option to delete the window containing the original message after
+yanking it to make more room on your screen for your reply.
+
+@cindex Emacs, packages, supercite
+@cindex supercite package
+@kindex r
+@vindex mail-citation-hook
+@vindex mh-yank-behavior
+
+You can control how the message to which you are replying is yanked
+into your reply using @code{mh-yank-behavior}. To include the entire
+message, including the entire header, use @samp{Body and
+Header}@footnote{If you'd rather have the header cleaned up, use
+@kbd{C-u r} instead of @kbd{r} when replying
+(@pxref{Replying}).}@footnote{In the past you would use this setting
+and set @code{mail-citation-hook} to @samp{supercite}, but this usage
+is now deprecated in favor of the @samp{Invoke supercite} setting.}.
+Use @samp{Body} to yank just the body without the header. To yank only
+the portion of the message following the point, set this option to
+@samp{Below Point}.
+
+Choose @samp{Invoke supercite}@footnote{@emph{Supercite} is a
+full-bodied, full-featured, citation package that comes standard with
+Emacs.} to pass the entire message and header through supercite.
+
+@vindex mh-extract-from-attribution-verb
+
+If the @samp{Body With Attribution} setting is used, then the message
+minus the header is yanked and a simple attribution line is added at
+the top using the value of the option
+@code{mh-extract-from-attribution-verb}. This is the default.
+
+@kindex C-c C-y
+@vindex mh-delete-yanked-msg-window-flag
+
+If the @samp{Invoke supercite} or @samp{Body With Attribution}
+settings are used, the @samp{-noformat} argument is passed to the
+@command{repl} program to override a @samp{-filter} or @samp{-format}
+argument. These settings also have @samp{Automatically} variants that
+perform the action automatically when you reply so that you don't need
+to use @kbd{C-c C-y} at all. Note that this automatic action is only
+performed if the show buffer matches the message being replied to.
+People who use the automatic variants tend to turn on the option
+@code{mh-delete-yanked-msg-window-flag} as well so that the show
+window is never displayed.
+
+@vindex mh-yank-behavior
+
+If the show buffer has a region, the option @code{mh-yank-behavior} is
+ignored unless its value is one of @samp{Attribution} variants in
+which case the attribution is added to the yanked region.
+
+@findex trivial-cite
+@vindex mail-citation-hook
+@vindex mh-ins-buf-prefix
+@vindex mh-yank-behavior
+
+If this isn't enough, you can gain full control over the appearance of
+the included text by setting @code{mail-citation-hook} to a function
+that modifies it. This hook is ignored if the option
+@code{mh-yank-behavior} is set to one of the supercite flavors.
+Otherwise, this option controls how much of the message is passed to
+the hook. The function can find the citation between point and mark
+and it should leave point and mark around the modified citation text
+for the next hook function. The standard prefix
+@code{mh-ins-buf-prefix} is not added if this hook is set.
+
+@cindex Emacs, packages, trivial-cite
+@cindex trivial-cite package
+@vindex mh-yank-behavior
+
+For example, if you use the hook function
+@uref{http://shasta.cs.uiuc.edu/~lrclause/tc.html,
+@code{trivial-cite}} (which is NOT part of Emacs), set
+@code{mh-yank-behavior} to @samp{Body and Header}.
+
+@node Inserting Messages, Signature, Inserting Letter, Editing Drafts
+@section Inserting Messages
+
+@cindex inserting messages
+@findex mh-insert-letter
+@findex mh-yank-behavior
+@kindex C-c C-i
+@vindex mh-ins-buf-prefix
+@vindex mh-invisible-header-fields-compiled
+@vindex mh-yank-behavior
+
+Messages can be inserted with @kbd{C-c C-i} (@code{mh-insert-letter}).
+This command prompts you for the folder and message number, which
+defaults to the current message in that folder. It then inserts the
+messages, indented by @code{mh-ins-buf-prefix} (@samp{> }) unless
+@code{mh-yank-behavior} is set to one of the supercite flavors in
+which case supercite is used to format the message. Certain
+undesirable header fields (see
+@code{mh-invisible-header-fields-compiled}) 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. This command leaves the mark before the
+letter and point after it.
+
+@node Signature, Picture, Inserting Messages, Editing Drafts
+@section Inserting Your Signature
+
+@cindex signature
+@findex mh-insert-signature
+@kindex C-c C-s
+
+You can insert your signature at the current cursor location with the
+command @kbd{C-c C-s} (@code{mh-insert-signature}).
+
+@cindex files, @file{.signature}
+@cindex @file{.signature}
+@cindex vCard
+@vindex mh-signature-file-name
+
+By default, the text of your signature is taken from the file
+@file{~/.signature}. You can read from other sources by changing the
+option @code{mh-signature-file-name}. This file may contain a
+@dfn{vCard} in which case an attachment is added with the vCard.
+
+@findex mh-signature-separator-p
+@vindex mh-signature-file-name
+@vindex mh-signature-separator
+@vindex mh-signature-separator-regexp
+
+The option @code{mh-signature-file-name} may also be a symbol, in
+which case that function is called. You may not want a signature
+separator to be added for you; instead you may want to insert one
+yourself. Options that you may find useful to do this include
+@code{mh-signature-separator} (when inserting a signature separator)
+and @code{mh-signature-separator-regexp} (for finding said separator).
+The function @code{mh-signature-separator-p}, which reports @code{t}
+if the buffer contains a separator, may be useful as well.
+
+@cindex signature separator
+@vindex mh-signature-separator-flag
+
+A signature separator (@code{"-- "}) will be added if the signature
+block does not contain one and @code{mh-signature-separator-flag} is
+on. It is not recommended that you change this option since various
+mail user agents, including MH-E, use the separator to present the
+signature differently, and to suppress the signature when replying or
+yanking a letter into a draft.
+
+@vindex mh-insert-signature-hook
+@vindex mh-signature-file-name
+
+The hook @code{mh-insert-signature-hook} is run after the signature is
+inserted. Hook functions may access the actual name of the file or the
+function used to insert the signature with
+@code{mh-signature-file-name}.
+
+The signature can also be inserted using Identities.
+@xref{Identities}.
+
+@node Picture, Adding Attachments, Signature, Editing Drafts
+@section Inserting Your Picture
+
+@cindex @file{.face}
+@cindex files, @file{.face}
+@vindex mh-x-face-file
+
+You can insert your picture in the header of your mail message so that
+recipients see your face in the @samp{From:} header field if their
+mail user agent is sophisticated enough. In MH-E, this is done by
+placing your image in the file named by the option
+@code{mh-x-face-file} which is @file{~/.face} by default.
+
+@cindex @samp{Face:} header field
+@cindex @samp{X-Face:} header field
+@cindex @samp{X-Image-URL:} header field
+@cindex header field, @samp{Face:}
+@cindex header field, @samp{X-Face:}
+@cindex header field, @samp{X-Image-URL:}
+
+If the file starts with either of the strings @samp{X-Face:},
+@samp{Face:} or @samp{X-Image-URL:} then the contents are added to the
+message header verbatim. Otherwise it is assumed that the file
+contains the value of the @samp{X-Face:} header field.
+
+@cindex @command{compface}
+@cindex Unix commands, @command{compface}
+
+The @samp{X-Face:} header field, which is a low-resolution, black and
+white image, can be generated using the
+@uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z,
+@command{compface}} command. The @uref{http://www.dairiki.org/xface/,
+@cite{Online X-Face Converter}} is a useful resource for quick
+conversion of images into @samp{X-Face:} header fields.
+
+Use the @uref{http://quimby.gnus.org/circus/face/make-face,
+@command{make-face}} script to convert a JPEG image to the higher
+resolution, color, @samp{Face:} header field.
+
+The URL of any image can be used for the @samp{X-Image-URL:} field and
+no processing of the image is required.
+
+@vindex mh-x-face-file
+
+To prevent the setting of any of these header fields, either set
+@code{mh-x-face-file} to @code{nil}, or simply ensure that the file
+defined by this option doesn't exist.
+
+@xref{Viewing}, to see how these header fields are displayed in MH-E.
+
+@node Adding Attachments, Sending PGP, Picture, Editing Drafts
+@section Adding Attachments
+
+@cindex @command{mhbuild}
+@cindex @command{mhn}
+@cindex MH commands, @command{mhbuild}
+@cindex MH commands, @command{mhn}
+@cindex MIME
+@cindex multimedia mail
+
+MH-E has the capability to create multimedia messages. It uses the
+@sc{mime} (Multipurpose Internet Mail Extensions)
+protocol@footnote{@sc{mime} is defined in
+@uref{http://www.rfc-editor.org/rfc/rfc2045.txt, RFC 2045}.} 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!
+
+@kindex C-c C-m
+
+If you were to create a multimedia message with plain MH commands, you
+would insert @command{mhbuild} or @command{mhn} directives (henceforth
+called @dfn{MH-style directives} into your draft and use the
+@command{mhbuild} command in nmh or @command{mhn} command in MH and
+GNU mailutils to expand them. MH-E works in much the same way,
+although it provides a handful of commands prefixed with @kbd{C-c C-m}
+to insert the directives so you don't need to remember the syntax of
+them. Remember: you can always add MH-style directives by
+hand@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/usimim.html#SeMIMa, Sending MIME Mail} in
+the MH book.}.
+
+@cindex MIME Meta Language (MML)
+@cindex MML
+@vindex mh-compose-insertion
+
+In addition to MH-style directives, MH-E also supports MML (@sc{mime}
+Meta Language) tags@footnote{
+@ifinfo
+@c Although the third argument should default to the
+@c first, makeinfo goes to the wrong Info file without it being
+@c different--it seems to be getting our own Composing node.
+@xref{Composing,,Composing with MML,emacs-mime}.
+@end ifinfo
+@ifnotinfo
+See the section Composing in
+@uref{http://www.gnus.org/manual/emacs-mime.html, @cite{The Emacs MIME
+Manual}}.
+@end ifnotinfo
+}. The option @code{mh-compose-insertion} can be used to choose
+between them. By default, this option is set to @samp{MML} if it is
+supported since it provides a lot more functionality. This option can
+also be set to @samp{MH} if MH-style directives are preferred.
+
+@cindex media types
+@cindex MIME, media types
+
+The MH-E @sc{mime} commands require a @dfn{media type} for each body
+part or attachment. For example, a PDF document is of type
+@samp{application/pdf} and an HTML document is of type
+@samp{text/html}. Some commands fill in the media type for you,
+whereas others require you to enter one.
+
+@cindex @command{file}
+@cindex @file{/etc/mime.types}
+@cindex files, @file{/etc/mime.types}
+@cindex Unix commands, @command{file}
+@findex mailcap-mime-types
+
+In the cases where MH-E can do so, it will determine the media type
+automatically. It uses the @command{file} command to do this. Failing
+that, the Emacs function @code{mailcap-mime-types} is used to provide
+a list from which to choose. This function usually reads the file
+@file{/etc/mime.types}.
+
+Whether the media type is chosen automatically, or you choose it from
+a list, use the type that seems to match best the file that you are
+including. In the case of binaries, the media type
+@samp{application/x-executable} can be useful. If you can't find an
+appropriate media type, use @samp{text/plain} for text messages and
+@samp{application/octet-stream} for everything else.
+
+@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.
+
+You can also create your own @sc{mime} body parts. In the following
+example, I describe how you can create and edit a @samp{text/enriched}
+body part to liven up your plain text messages with boldface,
+underlining, and italics. I include an Emacs function which inserts
+enriched text tags.
+
+@smalllisp
+@group
+(defvar enriched-text-types '(("b" . "bold") ("i" . "italic")
+ ("u" . "underline")
+ ("s" . "smaller") ("B" . "bigger")
+ ("f" . "fixed")
+ ("c" . "center"))
+ "Alist of (final-character . tag) choices for add-enriched-text.
+Additional types can be found in RFC 1563.")
+
+(defun add-enriched-text (begin end)
+ "Add enriched text tags around region.
+The tag 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 tag 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 tag}
+ (goto-char (point-max)) ; @r{move to end of text}
+ (insert "</" type ">")))) ; @r{insert terminating tag}
+@i{Emacs function for entering enriched text}
+
+@end group
+@end smalllisp
+
+To use the function @code{add-enriched-text}, first add it to
+@file{~/.emacs} and create key bindings for it (@pxref{Composing}).
+
+Then, in your plain text message, set the mark with @kbd{C-@@} or
+@kbd{C-@key{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>}.
+
+Before sending this message, use @kbd{C-c C-m C-m}
+(@code{mh-mml-to-mime})@footnote{Use @kbd{C-c C-e}
+(@code{mh-mh-to-mime}) if you're using MH-style directives.} to add
+MIME header fields. Then replace @samp{text/plain} with
+@samp{text/enriched} in the @samp{Content-Type:} header field.
+
+You may also be interested in investigating @code{sgml-mode}.
+
+@subheading Including Files
+
+@cindex attachments, inserting
+@cindex images
+@cindex MIME, images
+@cindex MIME, sound
+@cindex MIME, video
+@cindex sound
+@cindex video
+@findex mh-compose-insertion
+@kindex C-c C-m C-i
+@kindex C-c C-m i
+@vindex mh-compose-insertion
+
+Binaries, images, sound, and video can be inserted in your message
+with the command @kbd{C-c C-m C-i} (@code{mh-compose-insertion}). You
+are prompted for the filename containing the object, the media type if
+it cannot be determined automatically, and a content description. If
+you're using MH-style directives, you will also be prompted for
+additional attributes.
+
+@subheading Forwarding Multimedia Messages
+
+@findex mh-compose-forward
+@kindex C-c C-m C-f
+@kindex C-c C-m f
+
+Mail may be forwarded with @sc{mime} using the command @kbd{C-c C-m
+C-f} (@code{mh-compose-forward}). You are prompted for a content
+description, the name of the folder in which the messages to forward
+are located, and a range of messages, which defaults to the current
+message in that folder. @xref{Ranges}.
+
+@subheading Including an FTP Reference
+
+@cindex @command{ftp}
+@cindex MIME, @command{ftp}
+@cindex Unix commands, @command{ftp}
+@findex mh-mh-compose-anon-ftp
+@kindex C-c C-m C-g
+@kindex C-c C-m g
+
+You can have your message initiate an @command{ftp} transfer when the
+recipient reads the message. To do this, use the command @kbd{C-c C-m
+C-g} (@code{mh-mh-compose-anon-ftp}). You are prompted for the remote
+host and filename, the media type, and the content description.
+
+@subheading Including tar Files
+
+@cindex @command{ftp}
+@cindex @command{tar}
+@cindex MIME, @command{ftp}
+@cindex MIME, @command{tar}
+@cindex Unix commands, @command{ftp}
+@cindex Unix commands, @command{tar}
+@findex mh-mh-compose-anon-ftp
+@findex mh-mh-compose-external-compressed-tar
+@kindex C-c C-m C-g
+@kindex C-c C-m C-t
+@kindex C-c C-m t
+
+If the remote file is a compressed tar file, you can use @kbd{C-c C-m
+C-t} (@code{mh-mh-compose-external-compressed-tar}). Then, in addition
+to retrieving the file via anonymous @emph{ftp} as per the command
+@kbd{C-c C-m C-g} (@code{mh-mh-compose-anon-ftp}), the file will also
+be uncompressed and untarred. You are prompted for the remote host and
+filename and the content description.
+
+@subheading Including Other External Files
+
+@findex mh-mh-compose-external-type
+@kindex C-c C-m C-x
+@kindex C-c C-m x
+
+The command @kbd{C-c C-m C-x} (@code{mh-mh-compose-external-type}) is
+a general utility for referencing external files. In fact, all of the
+other commands that insert tags to access external files call this
+command. You are prompted for the access type, remote host and
+filename, and content type. If you provide a prefix argument, you are
+also prompted for a content description, attributes, parameters, and a
+comment.
+
+@subheading Previewing Multimedia Messages
+
+When you are finished editing a @sc{mime} message, it might look like this:
+
+@cartouche
+@smallexample
+3 t08/24 root received fax files on Wed Aug 24 11:00:
+4+t08/24 To:wohler Test<<This is a test message to get the
+
+
+
+
+
+--:%% @{+inbox@} 4 msgs (1-4) Bot L4 (MH-Folder Show)---------------
+To: wohler
+cc:
+Subject: Test of MIME
+--------
+Here is the SETI@@Home logo:
+
+<#part type="image/x-xpm" filename="~/lib/images/setiathome.xpm"
+disposition=inline description="SETI@@home logo">
+<#/part>
+--:** @{draft@} All L8 (MH-Letter)----------------------------------
+
+@end smallexample
+@end cartouche
+@i{MH-E @sc{mime} draft}
+
+@findex mh-mml-to-mime
+@kindex C-c C-m C-m
+@kindex C-c C-m m
+
+Typically, you send a message with attachments just like any other
+message (@pxref{Sending Message}).
+
+@findex mh-mml-to-mime
+@kindex C-c C-m C-m
+
+However, you may take a sneak preview of the @sc{mime} encoding if you
+wish by running the command @kbd{C-c C-m C-m} (@code{mh-mml-to-mime}).
+The following screen shows the @sc{mime} encoding specified by the
+tags. You can see why mail user agents are usually built to hide these
+details from the user.
+
+@cartouche
+@smallexample
+To: wohler
+cc:
+Subject: Test of MIME
+X-Mailer: MH-E 8.0; nmh 1.1; GNU Emacs 22.1
+MIME-Version: 1.0
+Content-Type: multipart/mixed; boundary="=-=-="
+--------
+--=-=-=
+
+Here is the SETI@@Home logo:
+
+
+--=-=-=
+Content-Type: image/x-xpm
+Content-Disposition: inline; filename=setiathome.xpm
+Content-Transfer-Encoding: base64
+Content-Description: SETI@@home logo
+
+LyogWFBNICovCnN0YXRpYyBjaGFyICogc2V0aWF0aG9tZV94cG1bXSA9IHsKIjQ1IDQ1IDc2N
+--:-- @{draft@} Top L1 (MH-Letter)----------------------------------
+
+@end smallexample
+@end cartouche
+@i{MH-E @sc{mime} draft ready to send}
+
+@cindex undo effects of mh-mml-to-mime
+
+This action can be undone by running @kbd{C-_} (@code{undo}).
+
+@cindex @command{mhbuild}
+@cindex @command{mhn}
+@cindex MH commands, @command{mhbuild}
+@cindex MH commands, @command{mhn}
+@cindex undo effects of mh-mh-to-mime
+@findex mh-mh-to-mime
+@findex mh-mh-to-mime-undo
+@kindex C-c C-e
+@kindex C-c C-m C-m
+@kindex C-c C-m C-u
+@kindex C-c C-m u
+
+If you're using MH-style directives, use @kbd{C-c C-e}
+(@code{mh-mh-to-mime}) instead of @kbd{C-c C-m C-m}. This runs the
+command @command{mhbuild} (@command{mhn}) on the message which expands
+the tags@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/usimim.html#SeMIMa, Sending MIME Mail} in
+the MH book.}. This action can be undone by running @kbd{C-c C-m C-u}
+(@code{mh-mh-to-mime-undo}), which works 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}).
+
+@kindex C-c C-e
+@vindex mh-mh-to-mime-args
+
+If you wish to pass additional arguments to @command{mhbuild}
+(@command{mhn}) to affect how it builds your message, use the option
+@code{mh-mh-to-mime-args}. For example, you can build a consistency
+check into the message by setting @code{mh-mh-to-mime-args} to
+@samp{-check}. The recipient of your message can then run
+@samp{mhbuild -check} on the message---@command{mhbuild}
+(@command{mhn}) will complain if the message has been corrupted on the
+way. The command @kbd{C-c C-e} only consults this option when given a
+prefix argument (as in @kbd{C-u C-c C-e}).
+
+@kindex C-c C-e
+@vindex mh-mh-to-mime-hook
+
+The hook @code{mh-mh-to-mime-hook} is called after the message has
+been formatted by @kbd{C-c C-e}.
+
+@node Sending PGP, Checking Recipients, Adding Attachments, Editing Drafts
+@section Signing and Encrypting Messages
+
+@cindex signing messages
+@cindex encrypting messages
+@cindex RFC 3156
+
+MH-E can sign and encrypt messages as defined in
+@uref{http://www.rfc-editor.org/rfc/rfc3156.txt, RFC 3156}. If you
+should choose to sign or encrypt your message, use one of the
+following commands to do so any time before sending your message.
+
+@findex mh-mml-secure-message-encrypt
+@findex mh-mml-secure-message-sign
+@findex mh-mml-secure-message-signencrypt
+@kindex C-c C-m C-e
+@kindex C-c C-m C-s
+@kindex C-c C-m e e
+@kindex C-c C-m e s
+@kindex C-c C-m s e
+@kindex C-c C-m s s
+
+The command @kbd{C-c C-m C-s} (@code{mh-mml-secure-message-sign})
+inserts the following tag:
+
+@smallexample
+<#secure method=pgpmime mode=sign>
+@end smallexample
+
+This is used to sign your message digitally. Likewise, the command
+@kbd{C-c C-m C-e} (@code{mh-mml-secure-message-encrypt}) inserts the
+following tag:
+
+@smallexample
+<#secure method=pgpmime mode=encrypt>
+@end smallexample
+
+This is used to encrypt your message. Finally, the command @kbd{C-c
+C-m s e} (@code{mh-mml-secure-message-signencrypt}) inserts the
+following tag:
+
+@smallexample
+<#secure method=pgpmime mode=signencrypt>
+@end smallexample
+
+@findex mh-mml-unsecure-message
+@kindex C-c C-m C-n
+@kindex C-c C-m n
+@vindex mh-mml-method-default
+
+This is used to sign and encrypt your message. In each of these cases,
+a proper multipart message is created for you when you send the
+message. Use the command @kbd{C-c C-m C-n}
+(@code{mh-mml-unsecure-message}) to remove these tags. Use a prefix
+argument (as in @kbd{C-u C-c C-m s e}) to be prompted for one of the
+possible security methods (see @code{mh-mml-method-default}).
+
+@vindex mh-mml-method-default
+
+The option @code{mh-mml-method-default} is used to select between a
+variety of mail security mechanisms. The default is @samp{PGP (MIME)}
+if it is supported; otherwise, the default is @samp{None}. Other
+mechanisms include vanilla @samp{PGP} and @samp{S/MIME}.
+
+@cindex @samp{pgg} customization group
+@cindex PGG
+@cindex customization group, @samp{pgg}
+
+The @samp{pgg} customization group may have some settings which may
+interest you.
+@iftex
+See @cite{The PGG Manual}.
+@end iftex
+@ifinfo
+@xref{Top, , The PGG Manual, pgg, The PGG Manual}.
+@end ifinfo
+@ifhtml
+See
+@uref{http://www.dk.xemacs.org/Documentation/packages/html/pgg.html,
+@cite{The PGG Manual}}.
+@end ifhtml
+
+@cindex header field, @samp{Fcc:}
+@cindex @samp{Fcc:} header field
+@vindex pgg-encrypt-for-me
+
+In particular, I turn on the option @code{pgg-encrypt-for-me} so that
+all messages I encrypt are encrypted with my public key as well. If
+you keep a copy of all of your outgoing mail with a @samp{Fcc:} header
+field, this setting is vital so that you can read the mail you write!
+
+@node Checking Recipients, Sending Message, Sending PGP, Editing Drafts
+@section Checking Recipients
+
+@cindex @samp{*MH-E Recipients*}
+@cindex @command{whom}
+@cindex MH commands, @command{whom}
+@cindex buffers, @samp{*MH-E Recipients*}
+@cindex checking recipients
+@cindex recipients, checking
+@findex mh-check-whom
+@kindex C-c C-w
+
+The command @kbd{C-c C-w} (@code{mh-check-whom}) expands aliases so
+you can check the actual address(es) in the alias. A new buffer named
+@samp{*MH-E Recipients*} is created with the output of @command{whom}
+(@pxref{Miscellaneous})@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/senove.html#WhaPro, What now? -- and the
+whatnow Program} in the MH book.}.
+
+@node Sending Message, Killing Draft, Checking Recipients, Editing Drafts
+@section Sending a Message
+
+@cindex buffers, @samp{*MH-E Mail Delivery*}
+@cindex @samp{*MH-E Mail Delivery*}
+@cindex sending mail
+@findex mh-send-letter
+@kindex C-c C-c
+
+When you are all through editing a message, you send it with the
+command @kbd{C-c C-c} (@code{mh-send-letter}). You can give a prefix
+argument (as in @kbd{C-u C-c C-c}) to monitor the first stage of the
+delivery; this output can be found in a buffer called @samp{*MH-E Mail
+Delivery*} (@pxref{Miscellaneous}).
+
+@cindex sending mail
+@cindex spell check
+@findex ispell-message
+@kindex C-c C-c
+@vindex mh-before-send-letter-hook
+
+The hook @code{mh-before-send-letter-hook} is run at the beginning of
+the command @kbd{C-c C-c}. For example, if you want to check your
+spelling in your message before sending, add the function
+@code{ispell-message}.
+
+@cindex @command{send}
+@cindex MH commands, @command{send}
+@vindex mh-send-prog
+
+In case the MH @command{send} program@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/sensen.html, Sending Some Mail: comp send}
+in the MH book.} is installed under a different name, use
+@code{mh-send-prog} to tell MH-E the name.
+
+@node Killing Draft, , Sending Message, Editing Drafts
+@section Killing the Draft
+
+@cindex killing draft
+@findex kill-buffer
+@findex mh-fully-kill-draft
+@kindex C-c C-q
+@kindex C-x k
+
+If for some reason you are not happy with the draft, you can use the
+command @kbd{C-c C-q} (@code{mh-fully-kill-draft}) to kill the draft
+buffer and delete the draft message. Use the command @kbd{C-x k}
+(@code{kill-buffer}) if you don't want to delete the draft message.
+
+@node Aliases, Identities, Editing Drafts, Top
+@chapter Aliases
+
+@cindex aliases
+
+MH aliases are used in the same way in MH-E as they are in MH. Any
+alias listed as a recipient will be expanded when the message is sent.
+This chapter discusses other things you can do with aliases in MH-E.
+
+@cindex MH-Letter mode
+@cindex modes, MH-Letter
+
+The following commands are available in MH-Letter mode with the
+exception of @code{mh-alias-reload} which can be called from anywhere.
+
+@table @kbd
+@kindex @key{SPC}
+@findex mh-letter-complete-or-space
+@item @key{SPC}
+Perform completion or insert space (@code{mh-letter-complete-or-space}).
+@c -------------------------
+@kindex M-@key{TAB}
+@findex mh-letter-complete
+@item M-@key{TAB}
+Perform completion on header field or word preceding point
+(@code{mh-letter-complete}).
+@c -------------------------
+@findex mh-alias-apropos
+@item mh-alias-apropos
+Show all aliases or addresses that match a regular expression.
+@c -------------------------
+@findex mh-alias-grab-from-field
+@item mh-alias-grab-from-field
+Add alias for the sender of the current message
+@c -------------------------
+@findex mh-alias-reload
+@item mh-alias-reload
+Reload MH aliases.
+@end table
+
+@cindex @samp{mh-alias} customization group
+@cindex customization group, @samp{mh-alias}
+
+The @samp{mh-alias} customization group contains options associated
+with aliases.
+
+@vtable @code
+@item mh-alias-completion-ignore-case-flag
+On means don't consider case significant in MH alias completion
+(default: @samp{on}).
+@c -------------------------
+@item mh-alias-expand-aliases-flag
+On means to expand aliases entered in the minibuffer (default:
+@samp{off}).
+@c -------------------------
+@item mh-alias-flash-on-comma
+Specify whether to flash address or warn on translation (default: @samp{Flash
+but Don't Warn If No Alias}).
+@c -------------------------
+@item mh-alias-insert-file
+Filename used to store a new MH-E alias (default: @samp{Use Aliasfile
+Profile Component}).
+@c -------------------------
+@item mh-alias-insertion-location
+Specifies where new aliases are entered in alias files (default:
+@samp{Alphabetical}).
+@c -------------------------
+@item mh-alias-local-users
+If @samp{on}, local users are added to alias completion (default:
+@samp{on}).
+@c -------------------------
+@item mh-alias-local-users-prefix
+String prefixed to the real names of users from the password file
+(default: @code{"local."}.
+@c -------------------------
+@item mh-alias-passwd-gecos-comma-separator-flag
+On means the GECOS field in the password file uses a comma separator
+(default: @samp{on}).
+@end vtable
+
+The following hook is available.
+
+@vtable @code
+@item mh-alias-reloaded-hook
+Hook run by @code{mh-alias-reload} after loading aliases (default:
+@code{nil}).
+@end vtable
+
+@subheading Adding Addresses to Draft
+
+You can use aliases when you are adding recipients to a message.
+
+@findex minibuffer-complete
+@kindex @key{TAB}
+@vindex mh-alias-expand-aliases-flag
+@vindex mh-compose-prompt-flag
+
+In order to use minibuffer prompting for recipients and the subject
+line in the minibuffer, turn on the option
+@code{mh-compose-prompt-flag} (@pxref{Composing}), and use the
+@key{TAB} (@code{minibuffer-complete}) command to complete aliases
+(and optionally local logins) when prompted for the recipients. Turn
+on the option @code{mh-alias-expand-aliases-flag} if you want these
+aliases to be expanded to their respective addresses in the draft.
+
+@findex mh-letter-complete
+@findex mh-letter-complete-or-space
+@kindex @key{SPC}
+@kindex M-@key{TAB}
+
+Otherwise, you can complete aliases in the header of the draft with
+@kbd{M-@key{TAB}} (@code{mh-letter-complete}) or @key{SPC}
+(@code{mh-letter-complete-or-space}).
+
+@vindex mh-alias-completion-ignore-case-flag
+
+As MH ignores case in the aliases, so too does MH-E. However, you may
+turn off the option @code{mh-alias-completion-ignore-case-flag} to
+make case significant which can be used to segregate completion of
+your aliases. You might use uppercase for mailing lists and lowercase
+for people. For example, you might have:
+
+@smallexample
+mark.baushke: Mark Baushke <mdb@@stop.mail-abuse.org>
+MH-E: MH-E Mailing List <mh-e-devel@@stop.mail-abuse.org>
+@end smallexample
+
+When this option is turned off, if you were to type @kbd{M} in the
+@samp{To:} field and then @kbd{M-@key{TAB}}, then you'd get the list;
+if you started with @kbd{m} and then entered @kbd{M-@key{TAB}}, then
+you'd get Mark's address. Note that this option affects completion
+only. If you were to enter @kbd{Mark.Baushke}, it would still be
+identified with your @samp{mark.baushke} alias.
+
+@findex mh-alias-minibuffer-confirm-address
+@findex mh-letter-confirm-address
+@vindex mh-alias-flash-on-comma
+@vindex mh-compose-prompt-flag
+
+To verify that the alias you've entered is valid, the alias will be
+displayed in the minibuffer when you type a comma
+(@code{mh-letter-confirm-address} or
+@code{mh-alias-minibuffer-confirm-address} if the option
+@code{mh-compose-prompt-flag} is turned on). @xref{Composing}. This
+behavior can be controlled with the option
+@code{mh-alias-flash-on-comma} which provides three choices:
+@samp{Flash but Don't Warn If No Alias}, @samp{Flash and Warn If No
+Alias}, and @samp{Don't Flash Nor Warn If No Alias}.
+
+For another way to verify the alias expansion, see @ref{Checking
+Recipients}.
+
+@subheading Loading Aliases
+
+@cindex @command{ali}
+@cindex @file{/etc/nmh/MailAliases}
+@cindex @samp{Aliasfile:} MH profile component
+@cindex MH commands, @command{ali}
+@cindex MH profile component, @samp{Aliasfile:}
+@cindex files, @file{/etc/nmh/MailAliases}
+
+MH-E loads aliases for completion and folder name hints from various
+places. It uses the MH command @command{ali}@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/mh.html, MH Aliases} in the MH book.} to
+read aliases from the files listed in the profile component
+@samp{Aliasfile:} as well as system-wide aliases (for example,
+@file{/etc/nmh/MailAliases}).
+
+@cindex @file{/etc/passwd}
+@cindex files, @file{/etc/passwd}
+
+In addition, aliases are created from @file{/etc/passwd} entries with
+a user ID larger than a magical number, typically 200. This can be a
+handy tool on a machine where you and co-workers exchange messages.
+These aliases have the form @samp{local.@var{first.last}} if a real
+name is present in the password file. Otherwise, the alias will have
+the form @samp{local.@var{login}}.
+
+@vindex mh-alias-local-users-prefix
+
+The prefix @samp{local.} can be modified via the option
+@code{mh-alias-local-users-prefix}. This option can also be set to
+@samp{Use Login}.
+
+For example, consider the following password file entry:
+
+@smallexample
+psg:x:1000:1000:Peter S Galbraith,,,:/home/psg:/bin/tcsh
+@end smallexample
+
+@vindex mh-alias-local-users-prefix
+
+The following settings of option @code{mh-alias-local-users-prefix}
+will produce the associated aliases:
+
+@table @code
+@item "local."
+local.peter.galbraith
+@c -------------------------
+@item ""
+peter.galbraith
+@c -------------------------
+@item Use Login
+psg
+@end table
+
+@vindex mh-alias-passwd-gecos-comma-separator-flag
+
+In the example above, commas are used to separate different values
+within the so-called GECOS field. This is a fairly common usage.
+However, in the rare case that the GECOS field in your password file
+is not separated by commas and whose contents may contain commas, you
+can turn the option @code{mh-alias-passwd-gecos-comma-separator-flag}
+off.
+
+@cindex NIS, obtaining local aliases from
+@cindex @samp{ypcat passwd}
+@vindex mh-alias-local-users
+
+If you're on a system with thousands of users you don't know, and the
+loading of local aliases slows MH-E down noticeably, then the local
+alias feature can be disabled by turning off the option
+@code{mh-alias-local-users}. This option also takes a string which is
+executed to generate the password file. For example, use @samp{ypcat
+passwd} to obtain the NIS password file.
+
+@findex mh-alias-reload
+@kindex M-x mh-alias-reload
+@vindex mh-alias-reloaded-hook
+
+Since aliases are updated frequently, MH-E reloads aliases
+automatically whenever an alias lookup occurs if an alias source has
+changed. However, you can reload your aliases manually by calling the
+command @kbd{M-x mh-alias-reload} directly. This command runs
+@code{mh-alias-reloaded-hook} after the aliases have been loaded.
+
+@subheading Adding Aliases
+
+In the past, you have manually added aliases to your alias file(s)
+listed in your @samp{Aliasfile:} profile component. MH-E provides
+other methods for maintaining your alias file(s).
+
+@findex mh-alias-add-alias
+@kindex M-x mh-alias-add-alias
+
+You can use the @kbd{M-x mh-alias-add-alias} command which will prompt
+you for the alias and address that you would like to add. If the alias
+exists already, you will have the choice of inserting the new alias
+before or after the old alias. In the former case, this alias will be
+used when sending mail to this alias. In the latter case, the alias
+serves as an additional folder name hint when filing messages
+(@pxref{Folder Selection}).
+
+Earlier, the alias prefix @samp{local} was presented. You can use
+other prefixes to organize your aliases or disambiguate entries. You
+might use prefixes for locales, jobs, or activities. For example, I
+have:
+
+@smallexample
+@group
+; Work
+attensity.don.mitchell: Don Mitchell <dmitchell@@stop.mail-abuse.com>
+isharp.don.mitchell: Don Mitchell <donaldsmitchell@@stop.mail-abuse.com>
+...
+; Sport
+diving.ken.mayer: Ken Mayer <kmayer@@stop.mail-abuse.com>
+sailing.mike.maloney: Mike Maloney <mmaloney@@stop.mail-abuse.com>
+...
+; Personal
+ariane.kolkmann: Ariane Kolkmann <ArianeKolkmann@@stop.mail-abuse.com>
+...
+@end group
+@end smallexample
+
+Using prefixes instead of postfixes helps you explore aliases during
+completion. If you forget the name of an old dive buddy, you can enter
+@samp{div} and then @key{SPC} to get a listing of all your dive buddies.
+
+@kindex M-x mh-alias-add-address-under-point
+@kindex M-x mh-alias-grab-from-field
+
+An alias for the sender of the current message is added automatically
+by clicking on the @samp{Grab From alias} tool bar button or by running
+the @kbd{M-x mh-alias-grab-from-field} command. Aliases for other
+recipients of the current message are added by placing your cursor
+over the desired recipient and giving the @kbd{M-x
+mh-alias-add-address-under-point} command.
+
+@vindex mh-alias-insert-file
+@vindex mh-alias-insertion-location
+
+The options @code{mh-alias-insert-file} and
+@code{mh-alias-insertion-location} controls how and where these aliases
+are inserted.
+
+@vindex mh-alias-insert-file
+
+The default setting of option @code{mh-alias-insert-file} is @samp{Use
+Aliasfile Profile Component}. This option can also hold the name of a
+file or a list a file names. If this option is set to a list of file
+names, or the @samp{Aliasfile:} profile component contains more than
+one file name, MH-E will prompt for one of them.
+
+@vindex mh-alias-insertion-location
+
+The option @code{mh-alias-insertion-location} is set to
+@samp{Alphabetical} by default. If you organize your alias file in
+other ways, then the settings @samp{Top} and @samp{Bottom} might be
+more appropriate.
+
+@subheading Querying Aliases
+
+@cindex regular expressions, @code{mh-alias-apropos}
+@findex mh-alias-apropos
+@kindex M-x mh-alias-apropos
+
+If you can't quite remember an alias, you can use @kbd{M-x
+mh-alias-apropos} to show all aliases or addresses that match a
+regular expression
+@ifnothtml
+(@pxref{Regexps, , Syntax of Regular Expressions, emacs, The
+GNU Emacs Manual}).
+@end ifnothtml
+@ifhtml
+(see the section
+@uref{http://www.gnu.org/software/emacs/manual/html_node/Regexps.html,
+Syntax of Regular Expressions} in
+@cite{The GNU Emacs Manual}).
+@end ifhtml
+
+@node Identities, Speedbar, Aliases, Top
+@chapter Identities
+
+@cindex identities
+@cindex multiple personalities
+
+MH-E supports the concept of multiple personalities or identities.
+This means that you can easily have a different header and signature
+at home and at work.
+
+@cindex @samp{Identity} menu
+@cindex menu, @samp{Identity}
+
+A couple of commands are used to insert identities in MH-Letter mode
+which are also found in the @samp{Identity} menu.
+
+@table @kbd
+@kindex C-c C-d
+@findex mh-insert-identity
+@item C-c C-d
+Insert fields specified by given identity (@code{mh-insert-identity}).
+@c -------------------------
+@cindex @samp{Identity > Insert Auto Fields} menu item
+@cindex menu item, @samp{Identity > Insert Auto Fields}
+@kindex C-c M-d
+@findex mh-insert-auto-fields
+@item C-c M-d
+Insert custom fields if recipient found in @code{mh-auto-fields-list}
+(@code{mh-insert-auto-fields}).
+@end table
+
+@cindex @samp{mh-identity} customization group
+@cindex customization group, @samp{mh-identity}
+
+The @samp{mh-identity} customization group contains the following
+options.
+
+@vtable @code
+@item mh-auto-fields-list
+List of recipients for which header lines are automatically inserted
+(default: @code{nil}).
+@c -------------------------
+@item mh-auto-fields-prompt-flag
+On means to prompt before sending if fields inserted (default:
+@samp{on})
+@c -------------------------
+@item mh-identity-default
+Default identity to use when @code{mh-letter-mode} is called (default:
+@samp{None}).
+@c -------------------------
+@item mh-identity-handlers
+Handler functions for fields in @code{mh-identity-list}.
+@c -------------------------
+@item mh-identity-list
+List of identities (default: @code{nil}).
+@end vtable
+
+Some of the common header fields that people change depending on the
+context are the @samp{From:} and @samp{Organization:} fields, as well
+as the signature.
+
+@vindex mh-identity-list
+
+This is done by customizing the option @code{mh-identity-list}. In the
+customization buffer for this option, click on the @samp{INS} button
+and enter a label such as @samp{Home} or @samp{Work}. Then click on
+the @samp{INS} button with the label @samp{Add at least one item
+below}. The @samp{Value Menu} has the following menu items:
+
+@table @samp
+@cindex header field, @samp{From:}
+@cindex @samp{From:} header field
+@item From Field
+Specify an alternate @samp{From:} header field. You must include a
+valid email address. A standard format is @samp{First Last
+<login@@host.domain>}. If you use an initial with a period, then you
+must quote your name as in @samp{"First I. Last"
+<login@@host.domain>}.
+@c -------------------------
+@cindex header field, @samp{Organization:}
+@cindex @samp{Organization:} header field
+@item Organization Field
+People usually list the name of the company where they work here.
+@c -------------------------
+@item Other Field
+Set any arbitrary header field and value here. Unless the header field
+is a standard one, precede the name of your field's label with
+@samp{X-}, as in @samp{X-Fruit-of-the-Day:}.
+@c -------------------------
+@item Attribution Verb
+This value overrides the setting of
+@code{mh-extract-from-attribution-verb}. @xref{Inserting Letter}.
+@c -------------------------
+@cindex signature
+@vindex mh-signature-file-name
+@item Signature
+Set your signature with this item. You can specify the contents of
+@code{mh-signature-file-name}, a file, or a function.
+@xref{Signature}.
+@c -------------------------
+@item GPG Key ID
+Specify a different key to sign or encrypt messages.
+@end table
+
+@cindex Identity menu
+@cindex menu, Identity
+@findex mh-insert-identity
+@kindex C-c C-d
+
+You can select the identities you have added via the menu called
+@samp{Identity} in the MH-Letter buffer. You can also use @kbd{C-c
+C-d} (@code{mh-insert-identity}). To clear the fields and signature
+added by the identity, select the @samp{None} identity.
+
+@cindex menu item, @samp{Identity > Customize Identities}
+@cindex menu item, @samp{Identity > Save as Default}
+@cindex menu item, @samp{Identity > Set Default for Session}
+@cindex @samp{Identity > Customize Identities} menu item
+@cindex @samp{Identity > Save as Default} menu item
+@cindex @samp{Identity > Set Default for Session} menu item
+@vindex mh-identity-default
+
+The @samp{Identity} menu contains two other items to save you from
+having to set the identity on every message. The menu item @samp{Set
+Default for Session} can be used to set the default identity to the
+current identity until you exit Emacs. The menu item @samp{Save as
+Default} sets the option @code{mh-identity-default} to the current
+identity setting. You can also customize the option
+@code{mh-identity-default} in the usual fashion. If you find that you
+need to add another identity, the menu item @samp{Customize
+Identities} is available for your convenience.
+
+@cindex regular expressions, @code{mh-auto-fields-list}
+@vindex mh-auto-fields-list
+
+The option @code{mh-auto-fields-list} can also be used to set the
+identity depending on the recipient to provide even more control. To
+customize @code{mh-auto-fields-list}, click on the @samp{INS} button
+and enter a regular expression for the recipient's address
+@ifnothtml
+(@pxref{Regexps, , Syntax of Regular Expressions, emacs, The
+GNU Emacs Manual}).
+@end ifnothtml
+@ifhtml
+(see the section
+@uref{http://www.gnu.org/software/emacs/manual/html_node/Regexps.html,
+Syntax of Regular Expressions} in
+@cite{The GNU Emacs Manual}).
+@end ifhtml
+Click on the @samp{INS} button with the @samp{Add at least one item
+below} label. The @samp{Value Menu} contains the following menu items:
+
+@table @samp
+@item Identity
+Select an identity from those configured in @code{mh-identity-list}.
+All of the information for that identity will be added if the
+recipient matches.
+@c -------------------------
+@cindex @samp{Fcc:} header field
+@cindex header field, @samp{Fcc:}
+@item Fcc Field
+Insert an @samp{Fcc:} header field with the folder you provide. When
+you send the message, MH will put a copy of your message in this
+folder.
+@c -------------------------
+@cindex @samp{Mail-Followup-To:} header field
+@cindex header field, @samp{Mail-Followup-To:}
+@item Mail-Followup-To Field
+Insert an @samp{Mail-Followup-To:} header field with the recipients
+you provide. If the recipient's mail user agent supports this header
+field@footnote{@samp{Mail-Followup-To:} is supported by nmh.}, then
+their replies will go to the addresses listed. This is useful if their
+replies go both to the list and to you and you don't have a mechanism
+to suppress duplicates. If you reply to someone not on the list, you
+must either remove the @samp{Mail-Followup-To:} field, or ensure the
+recipient is also listed there so that he receives replies to your
+reply.
+@c -------------------------
+@item Other Field
+Other header fields may be added using this menu item.
+@end table
+
+@findex mh-insert-auto-fields
+@kindex C-c M-d
+@vindex mh-auto-fields-prompt-flag
+
+These fields can only be added after the recipient is known. Because
+you can continue to add recipients as you edit the draft, MH-E waits
+until the message is sent to perform the auto-insertions. This seems
+strange at first, but you'll get used to it. There are two ways to
+help you feel that the desired fields are added. The first is the
+action when the message is sent: if any fields are added
+automatically, you are given a chance to see and to confirm these
+fields before the message is actually sent. You can do away with this
+confirmation by turning off the option
+@code{mh-auto-fields-prompt-flag}. The second method is manual: once
+the header contains one or more recipients, you may run the command
+@kbd{C-c M-d} (@code{mh-insert-auto-fields}) or choose the
+@samp{Identity -> Insert Auto Fields} menu item to insert these fields
+manually. However, if you use this command, the automatic insertion
+when the message is sent is disabled.
+
+@vindex mh-auto-fields-list
+@vindex mh-identity-list
+
+You should avoid using the same header field in
+@code{mh-auto-fields-list} and @code{mh-identity-list} definitions
+that may apply to the same message as the result is undefined.
+
+@vindex mh-identity-handlers
+@vindex mh-identity-list
+
+The option @code{mh-identity-handlers} is used to change the way that
+fields, signatures, and attributions in @code{mh-identity-list} are
+added. To customize @code{mh-identity-handlers}, replace the name of
+an existing handler function associated with the field you want to
+change with the name of a function you have written. You can also
+click on an @samp{INS} button and insert a field of your choice and
+the name of the function you have written to handle it.
+
+@vindex mh-identity-list
+
+The @samp{Field} field can be any field that you've used in your
+@code{mh-identity-list}. The special fields @samp{:attribution-verb},
+@samp{:signature}, or @samp{:pgg-default-user-id} are used for the
+@code{mh-identity-list} choices @samp{Attribution Verb},
+@samp{Signature}, and @samp{GPG Key ID} respectively.
+
+The handler associated with the @samp{:default} field is used when no
+other field matches.
+
+The handler functions are passed two or three arguments: the field
+itself (for example, @samp{From}), or one of the special fields (for
+example, @samp{:signature}), and the action @samp{'remove} or
+@samp{'add}. If the action is @samp{'add}, an additional argument
+containing the value for the field is given.
+
+@node Speedbar, Menu Bar, Identities, Top
+@chapter The Speedbar
+
+@cindex folder navigation
+@cindex speedbar
+@findex mh-visit-folder
+@kindex F v
+@kindex M-x speedbar
+@kindex Mouse-2
+
+You can also use the speedbar
+@ifnothtml
+(@pxref{Speedbar, , Speedbar Frames, emacs, The GNU Emacs Manual},)
+@end ifnothtml
+@ifhtml
+(see the section
+@uref{http://www.gnu.org/software/emacs/manual/html_node/Speedbar.html,
+Speedbar Frames} in @cite{The GNU Emacs Manual})
+@end ifhtml
+to view your folders. To bring up the speedbar, run @kbd{M-x speedbar
+@key{RET}}. You will see a new frame appear with all of your MH
+folders. Folders with unseen messages appear in boldface. Click on a
+folder name with @kbd{Mouse-2} to visit that folder in a similar
+fashion to the command @kbd{F v} (@code{mh-visit-folder})
+(@pxref{Folders}). Click on the @samp{+} icon to expand and view the
+sub-folders of that folder.
+
+The speedbar can be manipulated with the keyboard as well. Use the
+Emacs navigational keys (like the arrow keys, or @kbd{C-n}) to move
+the cursor over the desired folder and then use the shortcuts for the
+menu items listed in the table below.
+
+@table @samp
+@findex mh-speed-view
+@item Visit Folder (@key{RET})
+Visits the selected folder just as if you had used @kbd{F v}
+(@code{mh-speed-view}).
+@c -------------------------
+@findex mh-speed-expand-folder
+@item Expand Nested Folders (@kbd{+})
+Expands the selected folder in the speedbar, exposing the children
+folders inside it (@code{mh-speed-expand-folder}).
+@c -------------------------
+@findex mh-speed-contract-folder
+@item Contract Nested Folders (@kbd{-})
+Contracts or collapses the selected folder in the speedbar, hiding the
+children folders inside it (@code{mh-speed-contract-folder}).
+@c -------------------------
+@findex mh-speed-refresh
+@item Refresh Speedbar (@kbd{r})
+Regenerates the list of folders in the speedbar. Run this command if
+you've added or deleted a folder, or want to update the unseen message
+count before the next automatic update (@code{mh-speed-refresh}).
+@end table
+
+@findex delete-frame
+@kindex C-x 5 0
+@kindex Mouse-3
+
+You can click on @kbd{Mouse-3} to bring up a context menu that
+contains these items. Dismiss the speedbar with @kbd{C-x 5 0}
+(@code{delete-frame}).
+
+@cindex @command{flists}
+@cindex MH commands, @command{flists}
+@cindex @samp{mh-speedbar} customization group
+@cindex customization group, @samp{mh-speedbar}
+
+The MH-E speedbar uses the MH command @command{flists}@footnote{See
+the section @uref{@value{MH-BOOK-HOME}/morseq.html#flist, Searching for
+Sequences with flist} in the MH book.} to generate the list of
+folders. The @samp{mh-speedbar} customization group contains the
+following option which controls how often the speedbar calls
+@command{flists}.
+
+@vtable @code
+@item mh-speed-update-interval
+Time between speedbar updates in seconds (default: 60). Set to 0 to
+disable automatic update.
+@end vtable
+
+You can modify the appearance of the folders in the speedbar by
+customizing the following faces.
+
+@vtable @code
+@item mh-speedbar-folder
+Basic folder face.
+@c -------------------------
+@item mh-speedbar-folder-with-unseen-messages
+Folder face when folder contains unread messages.
+@c -------------------------
+@item mh-speedbar-selected-folder
+Selected folder face.
+@c -------------------------
+@item mh-speedbar-selected-folder-with-unseen-messages
+Selected folder face when folder contains unread messages.
+@end vtable
+
+@node Menu Bar, Tool Bar, Speedbar, Top
+@chapter The Menu Bar
+
+@cindex @samp{Folder} menu
+@cindex @samp{Identity} menu
+@cindex @samp{Letter} menu
+@cindex @samp{Message} menu
+@cindex @samp{Search} menu
+@cindex @samp{Sequence} menu
+@cindex Folder menu
+@cindex Identity menu
+@cindex Letter menu
+@cindex MH-Folder mode
+@cindex MH-Letter mode
+@cindex MH-Search mode
+@cindex Message menu
+@cindex Search menu
+@cindex Sequence menu
+@cindex menu bar
+@cindex menu, Folder
+@cindex menu, Identity
+@cindex menu, Letter
+@cindex menu, Message
+@cindex menu, Search
+@cindex menu, Sequence
+@cindex menu, @samp{Folder}
+@cindex menu, @samp{Identity}
+@cindex menu, @samp{Letter}
+@cindex menu, @samp{Message}
+@cindex menu, @samp{Search}
+@cindex menu, @samp{Sequence}
+@cindex modes, MH-Folder
+@cindex modes, MH-Letter
+@cindex modes, MH-Search
+
+For those of you who prefer to mouse and menu instead of using the
+meta-coke-bottle-bucky keys, MH-E provides menu items for most of its
+functions. The MH-Folder buffer adds the @samp{Folder},
+@samp{Message}, and @samp{Sequence} menus. The MH-Letter buffer adds
+the @samp{Identity} and @samp{Letter} menus. The MH-Search buffer adds
+the @samp{Search} menu. There's no need to list the actual items here,
+as you can more easily see them for yourself, and the functions are
+already described elsewhere in this manual.
+
+For a description of the menu bar, please
+@ifnothtml
+@xref{Menu Bar, , The Menu Bar, emacs, The GNU Emacs Manual}.
+@end ifnothtml
+@ifhtml
+see the section
+@uref{http://www.gnu.org/software/emacs/manual/html_node/Menu-Bar.html,
+The Menu Bar} in @cite{The GNU Emacs Manual}.
+@end ifhtml
+
+The Emacs manual describes how to get online help for a particular
+menu item. You can also look up a menu item in the index of this
+manual in two ways: all of the menu items are listed alphabetically,
+and you can also browse all of the items under the index entry
+@samp{menu item}.
+
+@node Tool Bar, Searching, Menu Bar, Top
+@chapter The Tool Bar
+
+@cindex tool bar
+
+Emacs also provides a graphical tool bar. For a description of the
+tool bar, please
+@ifnothtml
+@xref{Tool Bars, , Tool Bars, emacs, The GNU Emacs Manual}.
+@end ifnothtml
+@ifhtml
+see the section
+@uref{http://www.gnu.org/software/emacs/manual/html_node/Tool-Bars.html,
+Tool Bars} in @cite{The GNU Emacs Manual}.
+@end ifhtml
+
+@cindex @samp{mh-tool-bar} customization group
+@cindex customization group, @samp{mh-tool-bar}
+
+MH-E adds several icons to this tool bar; you can modify the MH-E
+aspects of the tool bar via the @samp{mh-tool-bar} customization group.
+
+@vtable @code
+@item mh-tool-bar-folder-buttons
+List of buttons to include in MH-Folder tool bar (default: a checklist
+too long to list here).
+@c -------------------------
+@item mh-tool-bar-letter-buttons
+List of buttons to include in MH-Letter tool bar (default: a checklist
+too long to list here).
+@c -------------------------
+@item mh-tool-bar-search-function
+Function called by the tool bar search button (default:
+@code{mh-search}).
+@c -------------------------
+@item mh-xemacs-tool-bar-position
+Tool bar location (default: @samp{Same As Default Tool Bar}).
+@c -------------------------
+@item mh-xemacs-use-tool-bar-flag
+If @samp{on}, use tool bar (default: @samp{on}, if supported).
+@end vtable
+
+In GNU Emacs, icons for some of MH-E's functions are added to the tool
+bar. In XEmacs, you have the opportunity to create a separate tool bar for
+the MH-E icons.
+
+@vindex mh-tool-bar-folder-buttons
+@vindex mh-tool-bar-letter-buttons
+
+In either case, you can select which of these functions you'd like to
+see by customizing the options @code{mh-tool-bar-folder-buttons} and
+@code{mh-tool-bar-letter-buttons}. As you probably guessed, the former
+customizes the tool bar in MH-Folder mode and the latter in MH-Letter
+mode. Both of these options present you with a list of functions;
+check the functions whose icons you want to see and clear the check
+boxes for those you don't.
+
+@findex mh-search
+@vindex mh-tool-bar-search-function
+
+The function associated with the searching icon can be set via the
+option @code{mh-tool-bar-search-function}. By default, this is set to
+@code{mh-search}. @xref{Searching}. You can also choose @samp{Other
+Function} from the @samp{Value Menu} and enter a function of your own
+choosing.
+
+@vindex mh-xemacs-use-tool-bar-flag
+
+XEmacs provides a couple of extra options. The first,
+@code{mh-xemacs-use-tool-bar-flag}, controls whether to show the MH-E
+icons at all. By default, this option is turned on if the window
+system supports tool bars. If your system doesn't support tool bars,
+then you won't be able to turn on this option.
+
+@vindex mh-xemacs-tool-bar-position
+
+The second extra option is @code{mh-xemacs-tool-bar-position} which
+controls the placement of the tool bar along the four edges of the
+frame. You can choose from one of @samp{Same As Default Tool Bar},
+@samp{Top}, @samp{Bottom}, @samp{Left}, or @samp{Right}. If this
+variable is set to anything other than @samp{Same As Default Tool Bar}
+and the default tool bar is in a different location, then two tool
+bars will be displayed: the MH-E tool bar and the default tool bar.
+
+@node Searching, Threading, Tool Bar, Top
+@chapter Searching Through Messages
+
+@cindex @samp{Search} menu
+@cindex menu, @samp{Search}
+@cindex searching
+@findex mh-search
+@kindex F s
+
+Earlier, the command @kbd{F s} (@code{mh-search}) was introduced which
+helps you find messages that lie buried in your folders
+(@pxref{Folders}). This chapter covers this command in more detail.
+Several commands are used to compose the search criteria and to start
+searching. A couple of them can be found in the @samp{Search} menu.
+
+@table @kbd
+@kindex C-c ?
+@findex mh-help
+@item C-c ?
+Display cheat sheet for the MH-E commands (@code{mh-help}).
+@c -------------------------
+@cindex @samp{Search > Perform Search} menu item
+@cindex menu item, @samp{Search > Perform Search}
+@kindex C-c C-c
+@findex mh-index-do-search
+@item C-c C-c
+Find messages using @code{mh-search-program}
+(@code{mh-index-do-search}).
+@c -------------------------
+@cindex @samp{Search > Search with pick} menu item
+@cindex menu item, @samp{Search > Search with pick}
+@kindex C-c C-p
+@findex mh-pick-do-search
+@item C-c C-p
+Find messages using @command{pick} (@code{mh-pick-do-search}).
+@c -------------------------
+@kindex C-c ?
+@findex mh-help
+@item C-c ?
+Display cheat sheet for the MH-E commands (@code{mh-help}).
+@c -------------------------
+@kindex C-c C-f C-a
+@kindex C-c C-f a
+@findex mh-to-field
+@item C-c C-f a
+@itemx C-c C-f C-a
+Move to @samp{Mail-Reply-To:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-b
+@kindex C-c C-f b
+@item C-c C-f b
+@itemx C-c C-f C-b
+Move to @samp{Bcc:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-c
+@kindex C-c C-f c
+@item C-c C-f c
+@itemx C-c C-f C-c
+Move to @samp{Cc:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-d
+@kindex C-c C-f d
+@item C-c C-f d
+@itemx C-c C-f C-d
+Move to @samp{Dcc:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-f
+@kindex C-c C-f f
+@item C-c C-f f
+@itemx C-c C-f C-f
+Move to @samp{Fcc:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-l
+@kindex C-c C-f l
+@item C-c C-f l
+@itemx C-c C-f C-l
+Move to @samp{Mail-Followup-To:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-m
+@kindex C-c C-f m
+@item C-c C-f m
+@itemx C-c C-f C-m
+Move to @samp{From:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-r
+@kindex C-c C-f r
+@item C-c C-f r
+@itemx C-c C-f C-r
+Move to @samp{Reply-To:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-s
+@kindex C-c C-f s
+@item C-c C-f s
+@itemx C-c C-f C-s
+Move to @samp{Subject:} header field (@code{mh-to-field}).
+@c -------------------------
+@kindex C-c C-f C-t
+@kindex C-c C-f t
+@item C-c C-f t
+@itemx C-c C-f C-t
+Move to @samp{To:} header field (@code{mh-to-field}).
+@end table
+
+Another few commands are available in the MH-Folder buffer resulting
+from a search.
+
+@table @kbd
+@kindex @key{TAB}
+@findex mh-index-next-folder
+@item @key{TAB}
+Jump to the next folder marker (@code{mh-index-next-folder}).
+@c -------------------------
+@kindex S-@key{TAB}
+@findex mh-index-previous-folder
+@item S-@key{TAB}
+Jump to the previous folder marker (@code{mh-index-previous-folder}).
+@c -------------------------
+@kindex v
+@findex mh-index-visit-folder
+@item v
+Visit original folder from where the message at point was found
+(@code{mh-index-visit-folder}).
+@end table
+
+@cindex @samp{mh-search} customization group
+@cindex customization group, @samp{mh-search}
+
+There is one option from the @samp{mh-search} customization group used
+in searching.
+
+@vtable @code
+@item mh-search-program
+Search program that MH-E shall use (default: @samp{Auto-detect}).
+@end vtable
+
+The following hook is available.
+
+@vtable @code
+@item mh-search-mode-hook
+Hook run upon entry to @code{mh-search-mode} (default: @code{nil}).
+@end vtable
+
+The following face is available.
+
+@vtable @code
+@item mh-search-folder
+Folder heading face in MH-Folder buffers created by searches.
+@end vtable
+
+@findex mh-search-folder
+@kindex F s
+
+The command @kbd{F s} (@code{mh-search-folder}) helps you find
+messages in your entire corpus of mail. You can search 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.
+
+@cindex @command{pick}
+@cindex MH commands, @command{pick}
+
+Out of the box, MH-E uses @command{pick} to find messages. With a
+little extra effort, you can set an indexing program which rewards you
+with extremely quick results. The drawback is that sometimes the index
+does not contain the words you're looking for. You can still use
+@command{pick} in these situations.
+
+You are prompted for the folder to search. This can be @samp{all} to
+search all folders. Note that the search works recursively on the
+listed folder.
+
+@cindex MH-Search mode
+@cindex modes, MH-Search
+
+Next, an MH-Search buffer appears where you can enter search criteria.
+
+@cartouche
+@smallexample
+From:
+To:
+Cc:
+Date:
+Subject:
+--------
+#
+
+
+
+
+
+
+
+
+--:** search-pattern All L7 (MH-Search)---------------------------
+Type C-c C-c to search messages, C-c C-p to use pick, C-c ? for help
+@end smallexample
+@end cartouche
+@i{Search window}
+
+@cindex @command{pick}
+@cindex MH commands, @command{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.
+
+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:
+
+@smallexample
+@group
+From: ginnean
+To:
+Cc:
+Date: Jan 1994
+Subject:
+--------
+horse
+kosciusko
+@end group
+@end smallexample
+
+@findex mh-to-field
+@kindex C-c C-f C-t
+
+As with MH-Letter mode, MH-Search provides commands like @kbd{C-c C-f
+C-t} (@code{mh-to-field}) to help you fill in the blanks.
+@xref{Editing Message}.
+
+@kindex F s
+@vindex mh-search-mode-hook
+
+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-search-mode-hook}, which is called
+when @kbd{F s} is run on a new pattern.
+
+@findex mh-index-do-search
+@findex mh-pick-do-search
+@kindex C-c C-c
+@kindex C-c C-p
+
+To perform the search, type @kbd{C-c C-c} (@code{mh-index-do-search}).
+Sometimes you're searching for text that is either not indexed, or
+hasn't been indexed yet. In this case you can override the default
+method with the pick method by running the command @kbd{C-c C-p}
+(@code{mh-pick-do-search}).
+
+@cindex folders, @samp{+mhe-index}
+@cindex @samp{+mhe-index}
+@findex mh-index-next-folder
+@findex mh-index-previous-folder
+@kindex @key{TAB}
+@kindex S-@key{TAB}
+@vindex mh-search-folder
+
+The messages that are found are put in a temporary sub-folder of
+@samp{+mhe-index} and are displayed in an MH-Folder buffer. This
+buffer is special because it displays messages from multiple folders;
+each set of messages from a given folder has a heading with the folder
+name. The appearance of the heading can be modified by customizing the
+face @code{mh-search-folder}. You can jump back and forth between the
+headings using the commands @kbd{@key{TAB}}
+(@code{mh-index-next-folder}) and @kbd{S-@key{TAB}}
+(@code{mh-index-previous-folder}).
+
+@findex mh-index-visit-folder
+@findex mh-rescan-folder
+@kindex F r
+@kindex v
+
+In addition, the command @kbd{v} (@code{mh-index-visit-folder}) can be
+used to visit the folder of the message at point. Initially, only the
+messages that matched the search criteria are displayed in the folder.
+While the temporary buffer has its own set of message numbers, the
+actual messages numbers are shown in the visited folder. Thus, the
+command @kbd{v} is useful to find the actual message number of an
+interesting message, or to view surrounding messages with the command
+@kbd{F r} @code{mh-rescan-folder}. @xref{Folders}.
+
+@findex mh-kill-folder
+@kindex F k
+
+Because this folder is temporary, you'll probably get in the habit of
+killing it when you're done with @kbd{F k} (@code{mh-kill-folder}).
+@xref{Folders}.
+
+@kindex F s
+
+You can regenerate the results by running @kbd{F s} with a prefix
+argument.
+
+@cindex @command{procmail}
+@cindex Unix commands, @command{procmail}
+@cindex @samp{X-MHE-Checksum:} header field
+@cindex header field, @samp{X-MHE-Checksum:}
+
+Note: This command uses an @samp{X-MHE-Checksum:} header field to
+cache the MD5 checksum of a message. This means that if an incoming
+message already contains an @samp{X-MHE-Checksum:} field, that message
+might not be found by this command. The following @command{procmail}
+recipe avoids this problem by renaming the existing header field:
+
+@smallexample
+@group
+:0 wf
+| formail -R "X-MHE-Checksum" "X-Old-MHE-Checksum"
+@end group
+@end smallexample
+
+@xref{Limits}, for an alternative interface to searching.
+
+@section Configuring Indexed Searches
+
+@cindex @command{grep}
+@cindex @command{mairix}
+@cindex @command{namazu}
+@cindex @command{pick}
+@cindex @command{swish++}
+@cindex @command{swish-e}
+@cindex Unix commands, @command{grep}
+@cindex Unix commands, @command{mairix}
+@cindex Unix commands, @command{namazu}
+@cindex Unix commands, @command{pick}
+@cindex Unix commands, @command{swish++}
+@cindex Unix commands, @command{swish-e}
+@findex mh-search
+@kindex F s
+@vindex mh-search-program
+
+The command @kbd{F s} (@code{mh-search}) runs the command defined by
+the option @code{mh-search-program}. The default value is
+@samp{Auto-detect} which means that MH-E will automatically choose one
+of @command{swish++}, @command{swish-e}, @command{mairix},
+@command{namazu}, @command{pick} and @command{grep} in that order. If,
+for example, you have both @command{swish++} and @command{mairix}
+installed and you want to use @command{mairix}, then you can set this
+option to @samp{mairix}.
+
+The following sub-sections describe how to set up the various indexing
+programs to use with MH-E.
+
+@subsection swish++
+
+@cindex @command{swish++}
+@cindex Unix commands, @command{swish++}
+
+In the examples below, replace @file{/home/user/Mail} with the path to
+your MH directory.
+
+First create the directory @file{/home/user/Mail/.swish++}. Then
+create the file @file{/home/user/Mail/.swish++/swish++.conf} with the
+following contents:
+
+@smallexample
+@group
+IncludeMeta Bcc Cc Comments Content-Description From Keywords
+IncludeMeta Newsgroups Resent-To Subject To
+IncludeMeta Message-Id References In-Reply-To
+IncludeFile Mail *
+IndexFile /home/user/Mail/.swish++/swish++.index
+@end group
+@end smallexample
+
+Use the following command line to generate the swish index. Run this
+daily from cron:
+
+@smallexample
+@group
+find /home/user/Mail -path /home/user/Mail/mhe-index -prune \
+ -o -path /home/user/Mail/.swish++ -prune \
+ -o -name "[0-9]*" -print \
+ | index -c /home/user/Mail/.swish++/swish++.conf -
+@end group
+@end smallexample
+
+This command does not index the folders that hold the results of your
+searches in @samp{+mhe-index} since they tend to be ephemeral and the
+original messages are indexed anyway.
+
+@cindex @command{index}
+@cindex Unix commands, @command{index}
+@cindex @command{index++}
+@cindex Unix commands, @command{index++}
+
+On some systems (Debian GNU/Linux, for example), use @command{index++}
+instead of @command{index}.
+
+@subsection swish
+
+@cindex @command{swish-e}
+@cindex Unix commands, @command{swish-e}
+
+In the examples below, replace @file{/home/user/Mail} with the path to
+your MH directory.
+
+First create the directory @file{/home/user/Mail/.swish}. Then create
+the file @file{/home/user/Mail/.swish/config} with the following
+contents:
+
+@smallexample
+@group
+DefaultContents TXT*
+IndexDir /home/user/Mail
+IndexFile /home/user/Mail/.swish/index
+IndexName "Mail Index"
+IndexDescription "Mail Index"
+IndexPointer "http://nowhere"
+IndexAdmin "nobody"
+#MetaNames automatic
+IndexReport 3
+FollowSymLinks no
+UseStemming no
+IgnoreTotalWordCountWhenRanking yes
+WordCharacters abcdefghijklmnopqrstuvwxyz0123456789-
+BeginCharacters abcdefghijklmnopqrstuvwxyz
+EndCharacters abcdefghijklmnopqrstuvwxyz0123456789
+IgnoreLimit 50 1000
+IndexComments 0
+FileRules filename contains \D
+FileRules pathname contains /home/user/Mail/.swish
+FileRules pathname contains /home/user/Mail/mhe-index
+FileRules filename is index
+@end group
+@end smallexample
+
+This configuration does not index the folders that hold the results of
+your searches in @samp{+mhe-index} since they tend to be ephemeral and
+the original messages are indexed anyway.
+
+If there are any directories you would like to ignore, append lines
+like the following to @file{config}:
+
+@smallexample
+FileRules pathname contains /home/user/Mail/scripts
+@end smallexample
+
+@cindex @command{swish-e}
+@cindex Unix commands, @command{swish-e}
+
+Use the following command line to generate the swish index. Run this
+daily from cron:
+
+@smallexample
+swish-e -c /home/user/Mail/.swish/config
+@end smallexample
+
+@subsection mairix
+
+@cindex @command{mairix}
+@cindex Unix commands, @command{mairix}
+
+In the examples below, replace @file{/home/user/Mail} with the path to
+your MH directory.
+
+First create the directory @file{/home/user/Mail/.mairix}. Then create
+the file @file{/home/user/Mail/.mairix/config} with the following
+contents:
+
+@smallexample
+@group
+base=/home/user/Mail
+
+# List of folders that should be indexed. 3 dots at the end means there
+# are subfolders within the folder
+mh=archive...:inbox:drafts:news:sent:trash
+
+vfolder_format=raw
+database=/home/user/Mail/mairix/database
+@end group
+@end smallexample
+
+Use the following command line to generate the mairix index. Run this daily
+from cron:
+
+@smallexample
+mairix -f /home/user/Mail/.mairix/config
+@end smallexample
+
+@subsection namazu
+
+@cindex @command{namazu}
+@cindex Unix commands, @command{namazu}
+
+In the examples below, replace @file{/home/user/Mail} with the path to
+your MH directory.
+
+First create the directory @file{/home/user/Mail/.namazu}. Then create
+the file @file{/home/user/Mail/.namazu/mknmzrc} with the following
+contents:
+
+@smallexample
+@group
+package conf; # Don't remove this line!
+$ADDRESS = 'user@@localhost';
+$ALLOW_FILE = "[0-9]*";
+$EXCLUDE_PATH = "^/home/user/Mail/(mhe-index|spam)";
+@end group
+@end smallexample
+
+This configuration does not index the folders that hold the results of
+your searches in @samp{+mhe-index} since they tend to be ephemeral and
+the original messages are indexed anyway.
+
+Use the following command line to generate the namazu index. Run this
+daily from cron:
+
+@smallexample
+mknmz -f /home/user/Mail/.namazu/mknmzrc -O /home/user/Mail/.namazu \
+ /home/user/Mail
+@end smallexample
+
+@subsection pick
+
+@cindex @command{pick}
+@cindex MH commands, @command{pick}
+
+This search method does not require any setup.
+
+Read @command{pick}(1) or the section
+@uref{@value{MH-BOOK-HOME}/finpic.html, Finding Messages with pick} in
+the MH book to find out more about how to enter the criteria.
+
+@subsection grep
+
+@cindex @command{grep}
+@cindex Unix commands, @command{grep}
+
+This search method does not require any setup.
+
+Unlike the other search methods, this method does not use the
+MH-Search buffer. Instead, you simply enter a regular expression in
+the minibuffer. For help in constructing regular expressions, see your
+man page for @command{grep}.
+
+@node Threading, Limits, Searching, Top
+@chapter Viewing Message Threads
+
+@cindex threading
+
+MH-E groups messages by @dfn{threads} which are messages that are part
+of the same discussion and usually all have the same @samp{Subject:}
+header field. Other ways to organize messages in a folder include
+limiting (@pxref{Limits}) or using full-text indexed searches
+(@pxref{Searching}).
+
+@cindex root, in threads
+@cindex siblings, in threads
+@cindex ancestor, in threads
+
+A thread begins with a single message called a @dfn{root}. All replies
+to the same message are @dfn{siblings} of each other. Any message that
+has replies to it is an @dfn{ancestor} of those replies.
+
+There are several commands that you can use to navigate and operate on
+threads.
+
+@table @kbd
+@kindex T ?
+@findex mh-prefix-help
+@item T ?
+Display cheat sheet for the commands of the current prefix in
+minibuffer (@code{mh-prefix-help}).
+@c -------------------------
+@kindex T o
+@findex mh-thread-refile
+@item T o
+Refile (output) thread into folder (@code{mh-thread-refile}).
+@c -------------------------
+@kindex T d
+@findex mh-thread-delete
+@item T d
+Delete thread (@code{mh-thread-delete}).
+@c -------------------------
+@kindex T t
+@findex mh-toggle-threads
+@item T t
+Toggle threaded view of folder (@code{mh-toggle-threads}).
+@c -------------------------
+@kindex T n
+@findex mh-thread-next-sibling
+@item T n
+Display next sibling (@code{mh-thread-next-sibling}).
+@c -------------------------
+@kindex T p
+@findex mh-thread-previous-sibling
+@item T p
+Display previous sibling (@code{mh-thread-previous-sibling}).
+@c -------------------------
+@kindex T u
+@findex mh-thread-ancestor
+@item T u
+Display ancestor of current message (@code{mh-thread-ancestor}).
+@end table
+
+@cindex @samp{mh-thread} customization group
+@cindex customization group, @samp{mh-thread}
+
+The @samp{mh-thread} customization group contains one option.
+
+@vtable @code
+@item mh-show-threads-flag
+On means new folders start in threaded mode (default: @samp{off}).
+@end vtable
+
+@findex mh-toggle-threads
+@kindex T t
+@vindex mh-large-folder
+@vindex mh-show-threads-flag
+
+Threading large number of messages can be time consuming so the option
+@code{mh-show-threads-flag} is turned off by default. If you turn on
+this option, then threading will be done only if the number of
+messages being threaded is less than @code{mh-large-folder}. In any
+event, threading can be turned on (and off) with the command @kbd{T t}
+(@code{mh-toggle-threads}).
+
+@findex mh-thread-ancestor
+@findex mh-thread-next-sibling
+@findex mh-thread-previous-sibling
+@kindex T n
+@kindex T p
+@kindex T u
+
+There are a few commands to help you navigate threads. If you do not
+care for the way a particular thread has turned, you can move up the
+chain of messages with the command @kbd{T u}
+(@code{mh-thread-ancestor}. At any point you can use @kbd{T n}
+(@code{mh-thread-next-sibling} or @kbd{T p}
+(@code{mh-thread-previous-sibling}) to jump to the next or previous
+sibling, skipping the sub-threads. The command @kbd{T u} can also take
+a prefix argument to jump to the message that started everything.
+
+@findex mh-delete-subject-or-thread
+@findex mh-thread-delete
+@findex mh-thread-refile
+@kindex k
+@kindex T d
+@kindex T o
+
+There are threaded equivalents for the commands that delete and refile
+messages. For example, @kbd{T o} (@code{mh-thread-refile}) refiles the
+current message and all its children. Similarly, the command @kbd{T d}
+(@code{mh-thread-delete}) deletes the current message and all its
+children. These commands do not refile or delete sibling messages.
+@xref{Navigating}, for a description of the similar command @kbd{k}
+(@code{mh-delete-subject-or-thread}).
+
+@vindex mh-large-folder
+
+If you find that threading is too slow, it may be that you have
+@code{mh-large-folder} set too high. Also, threading is one of the few
+features of MH-E that really benefits from compiling. If you haven't
+compiled MH-E, I encourage you to do so@footnote{If you're not sure if
+MH-E has been byte-compiled, you could try running @samp{locate
+mh-thread.elc} or otherwise find MH-E on your system and ensure that
+@file{mh-thread.elc} exists. If you have multiple versions and you
+find that one is compiled but the other is not, then go into your
+@samp{*scratch*} buffer in Emacs, enter @kbd{load-path C-j}, and
+ensure that the byte-compiled version appears first in the
+@code{load-path}. If you find that MH-E is not compiled and you
+installed MH-E yourself, please refer to the installation directions
+in the file @file{README} in the distribution.}.
+
+@node Limits, Sequences, Threading, Top
+@chapter Limiting Display
+
+@cindex limits
+@cindex filters
+
+Another way to organize messages in a folder besides threading
+(@pxref{Threading}) or using full-text indexed searches
+(@pxref{Searching}) is by limiting the folder display to messages that
+are similar to the current message.
+
+@table @kbd
+@kindex / ?
+@findex mh-prefix-help
+@item / ?
+Display cheat sheet for the commands of the current prefix in
+minibuffer (@code{mh-prefix-help}).
+@c -------------------------
+@cindex @samp{Sequence > Narrow to Tick Sequence} menu item
+@cindex menu item, @samp{Sequence > Narrow to Tick Sequence}
+@kindex / '
+@findex mh-narrow-to-tick
+@item / '
+Limit to messages in the @samp{tick} sequence
+(@code{mh-narrow-to-tick}).
+@c -------------------------
+@kindex / c
+@findex mh-narrow-to-cc
+@item / c
+Limit to messages with the same @samp{Cc:} field
+(@code{mh-narrow-to-cc}).
+@c -------------------------
+@kindex / m
+@findex mh-narrow-to-from
+@item / m
+Limit to messages with the same @samp{From:} field
+(@code{mh-narrow-to-from}).
+@c -------------------------
+@kindex / g
+@findex mh-narrow-to-range
+@item / g
+Limit to range (@code{mh-narrow-to-range}).
+@c -------------------------
+@cindex @samp{Sequence > Narrow to Subject Sequence} menu item
+@cindex menu item, @samp{Sequence > Narrow to Subject Sequence}
+@kindex / s
+@findex mh-narrow-to-subject
+@item / s
+Limit to messages with the same @samp{Subject:} field
+(@code{mh-narrow-to-subject}).
+@c -------------------------
+@kindex / t
+@findex mh-narrow-to-to
+@item / t
+Limit to messages with the same @samp{To:} field
+(@code{mh-narrow-to-to}).
+@c -------------------------
+@cindex @samp{Sequence > Widen from Sequence} menu item
+@cindex menu item, @samp{Sequence > Widen from Sequence}
+@kindex / w
+@findex mh-widen
+@item / w
+Remove last restriction (@code{mh-widen}).
+@end table
+
+All of the limiting commands above refine the display in some way.
+
+@cindex @command{pick}
+@cindex MH commands, @command{pick}
+@findex mh-narrow-to-cc
+@findex mh-narrow-to-from
+@findex mh-narrow-to-subject
+@findex mh-narrow-to-to
+@kindex / c
+@kindex / m
+@kindex / s
+@kindex / t
+
+The commands @kbd{/ c} (@code{mh-narrow-to-cc}), @kbd{/ m}
+(@code{mh-narrow-to-from}), @kbd{/ s} (@code{mh-narrow-to-subject}),
+and @kbd{/ t} (@code{mh-narrow-to-to}) restrict the display to
+messages matching the content of the respective field in the current
+message. However, you can give any of these a prefix argument to edit
+the @command{pick} expression used to narrow the view@footnote{See
+@command{pick}(1) or the section
+@uref{@value{MH-BOOK-HOME}/finpic.html, Finding Messages with pick} in
+the MH book.}.
+
+@cindex @samp{tick} sequence
+@cindex sequence, @samp{tick}
+@cindex ticked messages, viewing
+@findex mh-narrow-to-range
+@findex mh-narrow-to-tick
+@kindex / '
+@kindex / g
+
+You can also limit the display to messages in the @samp{tick} sequence
+with the command @kbd{/ '} (@code{mh-narrow-to-tick}).
+@xref{Sequences}, for information on putting message into the
+@samp{tick} sequence. Use the @kbd{/ g} (@code{mh-narrow-to-range})
+command to limit the display to messages in a range (@pxref{Ranges}).
+
+@findex mh-widen
+@kindex / w
+
+Each limit can be undone in turn with the @kbd{/ w} (@code{mh-widen})
+command. Give this command a prefix argument to remove all limits.
+
+@node Sequences, Junk, Limits, Top
+@chapter Using Sequences
+
+@cindex @samp{Sequence} menu
+@cindex menu, @samp{Sequence}
+@cindex sequences
+
+For the whole scoop on MH sequences, refer to
+@samp{mh-sequence}(5)@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/morseq.html, More About Sequences} in the MH
+book.}. 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. These commands are also
+available in the @samp{Sequence} menu.
+
+@table @kbd
+@cindex @samp{Sequence > Toggle Tick Mark} menu item
+@cindex menu item, @samp{Sequence > Toggle Tick Mark}
+@kindex '
+@findex mh-toggle-tick
+@item '
+Toggle tick mark of range (@code{mh-toggle-tick}).
+@c -------------------------
+@kindex S ?
+@findex mh-prefix-help
+@item S ?
+Display cheat sheet for the commands of the current prefix in
+minibuffer (@code{mh-prefix-help}).
+@c -------------------------
+@cindex @samp{Sequence > Narrow to Tick Sequence} menu item
+@cindex menu item, @samp{Sequence > Narrow to Tick Sequence}
+@kindex S '
+@findex mh-narrow-to-tick
+@item S '
+Limit to ticked messages (@code{mh-narrow-to-tick}).
+@c -------------------------
+@cindex @samp{Sequence > Delete Message from Sequence...} menu item
+@cindex menu item, @samp{Sequence > Delete Message from Sequence...}
+@kindex S d
+@findex mh-delete-msg-from-seq
+@item S d
+Delete range from sequence (@code{mh-delete-msg-from-seq}).
+@c -------------------------
+@cindex @samp{Sequence > Delete Sequence...} menu item
+@cindex menu item, @samp{Sequence > Delete Sequence...}
+@kindex S k
+@findex mh-delete-seq
+@item S k
+Delete sequence (@code{mh-delete-seq}).
+@c -------------------------
+@cindex @samp{Sequence > List Sequences in Folder...} menu item
+@cindex menu item, @samp{Sequence > List Sequences in Folder...}
+@kindex S l
+@findex mh-list-sequences
+@item S l
+List all sequences in folder (@code{mh-list-sequences}).
+@c -------------------------
+@cindex @samp{Sequence > Narrow to Sequence...} menu item
+@cindex menu item, @samp{Sequence > Narrow to Sequence...}
+@kindex S n
+@findex mh-narrow-to-seq
+@item S n
+Restrict display to messages in sequence (@code{mh-narrow-to-seq}).
+@c -------------------------
+@cindex @samp{Sequence > Add Message to Sequence...} menu item
+@cindex menu item, @samp{Sequence > Add Message to Sequence...}
+@kindex S p
+@findex mh-put-msg-in-seq
+@item S p
+Add range to sequence (@code{mh-put-msg-in-seq}).
+@c -------------------------
+@cindex @samp{Sequence > List Sequences for Message} menu item
+@cindex menu item, @samp{Sequence > List Sequences for Message}
+@kindex S s
+@findex mh-msg-is-in-seq
+@item S s
+Display the sequences in which the current message appears
+(@code{mh-msg-is-in-seq}).
+@c -------------------------
+@cindex @samp{Sequence > Widen from Sequence} menu item
+@cindex menu item, @samp{Sequence > Widen from Sequence}
+@kindex S w
+@findex mh-widen
+@item S w
+Remove last restriction (@code{mh-widen}).
+@c -------------------------
+@findex mh-update-sequences
+@item M-x mh-update-sequences
+Flush MH-E's state out to MH@.
+@end table
+
+@cindex @samp{mh-sequences} customization group
+@cindex customization group, @samp{mh-sequences}
+
+The @samp{mh-sequences} customization group contains the options
+associated with sequences.
+
+@vtable @code
+@item mh-refile-preserves-sequences-flag
+On means that sequences are preserved when messages are refiled
+(default: @samp{on}).
+@c -------------------------
+@item mh-tick-seq
+The name of the MH sequence for ticked messages (default: @samp{'tick}).
+@c -------------------------
+@item mh-update-sequences-after-mh-show-flag
+On means flush MH sequences to disk after message is shown (default:
+@samp{on}).
+@end vtable
+
+The following hook is available.
+
+@vtable @code
+@item mh-unseen-updated-hook
+Hook run after the unseen sequence has been updated (default: @code{nil}).
+@end vtable
+
+@cindex @command{pick}
+@cindex MH commands, @command{pick}
+@findex mh-put-msg-in-seq
+@kindex S p
+
+To place a message in a sequence, use @kbd{S p}
+(@code{mh-put-msg-in-seq}). Give @kbd{S p} a range and you can add all
+the messages in a sequence to another sequence (for example, @kbd{C-u
+S p SourceSequence @key{RET} DestSequence @key{RET}}, @pxref{Ranges}).
+
+@cindex @samp{tick} sequence
+@cindex sequence, @samp{tick}
+@cindex ticking messages
+@findex mh-index-ticked-messages
+@findex mh-toggle-tick
+@kindex '
+@kindex F '
+@kindex S p
+
+One specific use of the @kbd{S p} command is @kbd{'}
+(@code{mh-toggle-tick}) which adds messages to the @samp{tick}
+sequence. This sequence can be viewed later with the @kbd{F '}
+(@code{mh-index-ticked-messages}) command (@pxref{Folders}).
+
+@vindex mh-tick-seq
+
+You can customize the option @code{mh-tick-seq} if you already use the
+@samp{tick} sequence for your own use. You can also disable all of the
+ticking functions by choosing the @samp{Disable Ticking} item but
+there isn't much advantage to that.
+
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+@findex mh-narrow-to-seq
+@findex mh-narrow-to-tick
+@findex mh-widen
+@kindex S '
+@kindex S n
+@kindex S w
+
+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{S 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. To narrow the view to the messages in the @samp{tick}
+sequence, use @kbd{S '} (@code{mh-narrow-to-tick}). When you want to
+widen the view to all your messages again, use @kbd{S w}
+(@code{mh-widen}).
+
+@cindex buffers, @samp{*MH-E Sequences*}
+@cindex @samp{*MH-E Sequences*}
+@findex mh-list-sequences
+@findex mh-msg-is-in-seq
+@kindex S l
+@kindex S s
+
+You can see which sequences in which a message appears with the
+command @kbd{S s} (@code{mh-msg-is-in-seq}). Use a prefix argument to
+display the sequences in which another message appears (as in @kbd{C-u
+42 S s @key{RET}}). Or, you can list all sequences in a selected
+folder (default is current folder) with @kbd{S l}
+(@code{mh-list-sequences}). The list appears in a buffer named
+@samp{*MH-E Sequences*} (@pxref{Miscellaneous}).
+
+@cindex MH profile component, @samp{Previous-Sequence:}
+@cindex @samp{cur} sequence
+@cindex @samp{Previous-Sequence:} MH profile component
+@cindex sequence, @samp{cur}
+@cindex sequence, @samp{Previous-Sequence}
+@vindex mh-refile-preserves-sequences-flag
+
+If a message is in any sequence (except
+@samp{Previous-Sequence:}@footnote{See @samp{mh-profile}(5)).} and
+@samp{cur}) when it is refiled, then it will still be in those
+sequences in the destination folder. If this behavior is not desired,
+then turn off the option @code{mh-refile-preserves-sequences-flag}.
+
+@findex mh-delete-msg-from-seq
+@findex mh-delete-seq
+@kindex d
+@kindex S d
+@kindex S k
+
+If you want to remove a message (or range, @pxref{Ranges}) from a
+sequence, use @kbd{S d} (@code{mh-delete-msg-from-seq}). If you want
+to delete an entire sequence, use @kbd{S k} (@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} (@pxref{Reading
+Mail}).
+
+@cindex @samp{Unseen-Sequence:} MH profile component
+@cindex @samp{cur} sequence
+@cindex @samp{tick} sequence
+@cindex MH profile component, @samp{Unseen-Sequence:}
+@cindex sequence, @samp{Unseen-Sequence}
+@cindex sequence, @samp{cur}
+@cindex sequence, @samp{tick}
+@findex mh-update-sequences
+@kindex M-x mh-update-sequences
+@kindex q
+@kindex x
+@vindex mh-tick-seq
+@vindex mh-update-sequences-after-mh-show-flag
+
+Three sequences are maintained internally by MH-E and pushed out to MH
+when a message is shown. They include the sequence specified by your
+@samp{Unseen-Sequence:} profile component, @samp{cur}, and the
+sequence listed by the option @code{mh-tick-seq} which is @samp{tick}
+by default. If you do not like this behavior, turn off the option
+@code{mh-update-sequences-after-mh-show-flag}. You can then update the
+state manually with the @kbd{x}, @kbd{q}, or @kbd{M-x
+mh-update-sequences} commands.
+
+@vindex mh-seen-list
+@vindex mh-unseen-updated-hook
+
+The hook @code{mh-unseen-updated-hook} is run after the unseen
+sequence has been updated. The variable @code{mh-seen-list} can be
+used by this hook to obtain the list of messages which were removed
+from the unseen sequence.
+
+@cindex @command{mark}
+@cindex MH commands, @command{mark}
+@kindex S n
+@kindex S w
+
+With the exceptions of @kbd{S n} and @kbd{S w}, the underlying MH
+command dealing with sequences is @command{mark}@footnote{See the
+section @uref{@value{MH-BOOK-HOME}/mmbwm.html, Make Message Bookmarks
+with mark} in the MH book.}.
+
+@node Junk, Miscellaneous, Sequences, Top
+@chapter Dealing With Junk Mail
+
+@cindex Marshall Rose
+@cindex junk mail
+@cindex spam
+
+Marshall Rose once wrote a paper on MH entitled, @cite{How to process
+200 messages a day and still get some real work done}. This chapter
+could be entitled, @cite{How to process 1000 spams a day and still get
+some real work done}.
+
+@cindex blacklisting
+@cindex ham
+@cindex viruses
+@cindex whitelisting
+@cindex worms
+
+We use the terms @dfn{junk mail} and @dfn{spam} interchangeably for
+any unwanted message which includes spam, @dfn{viruses}, and
+@dfn{worms}. The opposite of spam is @dfn{ham}. The act of classifying
+a sender as one who sends junk mail is called @dfn{blacklisting}; the
+opposite is called @dfn{whitelisting}.
+
+@table @kbd
+@kindex J ?
+@findex mh-prefix-help
+@item J ?
+Display cheat sheet for the commands of the current prefix in
+minibuffer (@code{mh-prefix-help}).
+@c -------------------------
+@kindex J b
+@findex mh-junk-blacklist
+@item J b
+Blacklist range as spam (@code{mh-junk-blacklist}).
+@c -------------------------
+@kindex J w
+@findex mh-junk-whitelist
+@item J w
+Whitelist range as ham (@code{mh-junk-whitelist}).
+@c -------------------------
+@item @code{mh-spamassassin-identify-spammers}
+Identify spammers who are repeat offenders.
+@end table
+
+@cindex @samp{mh-junk} customization group
+@cindex customization group, @samp{mh-junk}
+
+The following table lists the options from the @samp{mh-junk}
+customization group.
+
+@vtable @code
+@item mh-junk-background
+If on, spam programs are run in background (default: @samp{off}).
+@c -------------------------
+@item mh-junk-disposition
+Disposition of junk mail (default: @samp{Delete Spam}).
+@c -------------------------
+@item mh-junk-program
+Spam program that MH-E should use (default: @samp{Auto-detect}).
+@end vtable
+
+@cindex SpamProbe
+@cindex Spamassassin
+@cindex bogofilter
+@cindex spam filters, SpamProbe
+@cindex spam filters, Spamassassin
+@cindex spam filters, bogofilter
+
+MH-E depends on @uref{http://spamassassin.apache.org/, SpamAssassin},
+@uref{http://bogofilter.sourceforge.net/, bogofilter}, or
+@uref{http://spamprobe.sourceforge.net/, SpamProbe} to throw the dreck
+away. This chapter describes briefly how to configure these programs
+to work well with MH-E and how to use MH-E's interface that provides
+continuing education for these programs.
+
+@vindex mh-junk-program
+
+The default setting of the option @code{mh-junk-program} is
+@samp{Auto-detect} which means that MH-E will automatically choose one
+of SpamAssassin, bogofilter, or SpamProbe in that order. If, for
+example, you have both SpamAssassin and bogofilter installed and you
+want to use bogofilter, then you can set this option to
+@samp{Bogofilter}.
+
+@findex mh-junk-blacklist
+@kindex J b
+@vindex mh-junk-disposition
+
+The command @kbd{J b} (@code{mh-junk-blacklist}) trains the spam
+program in use with the content of the range (@pxref{Ranges}) and then
+handles the message(s) as specified by the option
+@code{mh-junk-disposition}. By default, this option is set to
+@samp{Delete Spam} but you can also specify the name of the folder
+which is useful for building a corpus of spam for training purposes.
+
+@findex mh-junk-whitelist
+@kindex J w
+
+In contrast, the command @kbd{J w} (@code{mh-junk-whitelist})
+reclassifies a range of messages (@pxref{Ranges}) as ham if it were
+incorrectly classified as spam. It then refiles the message into the
+@file{+inbox} folder.
+
+@cindex @samp{*MH-E Log*}
+@cindex buffers, @samp{*MH-E Log*}
+@findex call-process
+@vindex mh-junk-background
+
+By default, the programs are run in the foreground, but this can be
+slow when junking large numbers of messages. If you have enough memory
+or don't junk that many messages at the same time, you might try
+turning on the option @code{mh-junk-background}. @footnote{Note that
+the option @code{mh-junk-background} is used as the @code{display}
+argument in the call to @code{call-process}. Therefore, turning on
+this option means setting its value to @samp{0}. You can also set its
+value to @samp{t} to direct the programs' output to the @samp{*MH-E
+Log*} buffer; this may be useful for debugging.}
+
+The following sections discuss the various counter-spam measures that
+MH-E can work with.
+
+@cindex @file{.procmailrc}
+@cindex files, @file{.procmailrc}
+
+@subheading SpamAssassin
+
+@cindex Spamassassin
+@cindex spam filters, Spamassassin
+
+SpamAssassin is one of the more popular spam filtering programs. Get
+it from your local distribution or from the
+@uref{http://spamassassin.apache.org/, SpamAssassin web site}.
+
+To use SpamAssassin, add the following recipes to @file{~/.procmailrc}:
+
+@cindex @command{spamc}
+@cindex @samp{X-Spam-Level:} header field
+@cindex @samp{X-Spam-Status:} header field
+@cindex header field, @samp{X-Spam-Level:}
+@cindex header field, @samp{X-Spam-Status:}
+
+@smallexample
+PATH=$PATH:/usr/bin/mh
+MAILDIR=$HOME/`mhparam Path`
+
+# Fight spam with SpamAssassin.
+:0fw
+| spamc
+
+# Anything with a spam level of 10 or more is junked immediately.
+:0:
+* ^X-Spam-Level: ..........
+/dev/null
+
+:0:
+* ^X-Spam-Status: Yes
+spam/.
+@end smallexample
+
+If you don't use @command{spamc}, use @samp{spamassassin -P -a}.
+
+Note that one of the recipes above throws away messages with a score
+greater than or equal to 10. Here's how you can determine a value that
+works best for you.
+
+First, run @samp{spamassassin -t} on every mail message in your
+archive and use @command{gnumeric} to verify that the average plus the
+standard deviation of good mail is under 5, the SpamAssassin default
+for ``spam''.
+
+Using @command{gnumeric}, sort the messages by score and view the
+messages with the highest score. Determine the score which encompasses
+all of your interesting messages and add a couple of points to be
+conservative. Add that many dots to the @samp{X-Spam-Level:} header
+field above to send messages with that score down the drain.
+
+In the example above, messages with a score of 5-9 are set aside in
+the @samp{+spam} folder for later review. The major weakness of
+rules-based filters is a plethora of false positives so it is
+worthwhile to check.
+
+@findex mh-junk-blacklist
+@findex mh-junk-whitelist
+@kindex J b
+@kindex J w
+
+If SpamAssassin classifies a message incorrectly, or is unsure, you can
+use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and
+@kbd{J w} (@code{mh-junk-whitelist}).
+
+@cindex @command{sa-learn}
+@cindex @file{.spamassassin/user_prefs}
+@cindex files, @file{.spamassassin/user_prefs}
+
+The command @kbd{J b} (@code{mh-junk-blacklist}) adds a
+@samp{blacklist_from} entry to @file{~/spamassassin/user_prefs},
+deletes the message, and sends the message to the Razor, so that
+others might not see this spam. If the @command{sa-learn} command is
+available, the message is also recategorized as spam.
+
+The command@kbd{J w} (@code{mh-junk-whitelist}) adds a
+@samp{whitelist_from} rule to @samp{~/.spamassassin/user_prefs}. If
+the @command{sa-learn} command is available, the message is also
+recategorized as ham.
+
+Over time, you'll observe that the same host or domain occurs
+repeatedly in the @samp{blacklist_from} entries, so you might think
+that you could avoid future spam by blacklisting all mail from a
+particular domain. The utility function
+@code{mh-spamassassin-identify-spammers} helps you do precisely that.
+This function displays a frequency count of the hosts and domains in
+the @samp{blacklist_from} entries from the last blank line in
+@file{~/.spamassassin/user_prefs} to the end of the file. This
+information can be used so that you can replace multiple
+@samp{blacklist_from} entries with a single wildcard entry such as:
+
+@smallexample
+blacklist_from *@@*amazingoffersdirect2u.com
+@end smallexample
+
+In versions of SpamAssassin (2.50 and on) that support a Bayesian
+classifier, @kbd{J b} @code{(mh-junk-blacklist}) uses the program
+@command{sa-learn} to recategorize the message as spam. Neither MH-E,
+nor SpamAssassin, rebuilds the database after adding words, so you
+will need to run @samp{sa-learn --rebuild} periodically. This can be
+done by adding the following to your @file{crontab}:
+
+@smallexample
+0 * * * * sa-learn --rebuild > /dev/null 2>&1
+@end smallexample
+
+@subheading Bogofilter
+
+@cindex bogofilter
+@cindex spam filters, bogofilter
+
+Bogofilter is a Bayesian spam filtering program. Get it from your
+local distribution or from the
+@uref{http://bogofilter.sourceforge.net/, bogofilter web site}.
+
+Bogofilter is taught by running:
+
+@smallexample
+bogofilter -n < good-message
+@end smallexample
+
+on every good message, and
+
+@smallexample
+bogofilter -s < spam-message
+@end smallexample
+
+@cindex full training
+
+on every spam message. This is called a @dfn{full training}; three
+other training methods are described in the FAQ that is distributed
+with bogofilter. Note that most Bayesian filters need 1000 to 5000 of
+each type of message to start doing a good job.
+
+To use bogofilter, add the following recipes to @file{~/.procmailrc}:
+
+@cindex @samp{X-Bogosity:} header field
+@cindex header field, @samp{X-Bogosity:}
+
+@smallexample
+PATH=$PATH:/usr/bin/mh
+MAILDIR=$HOME/`mhparam Path`
+
+# Fight spam with Bogofilter.
+:0fw
+| bogofilter -3 -e -p
+
+:0:
+* ^X-Bogosity: Yes, tests=bogofilter
+spam/.
+
+:0:
+* ^X-Bogosity: Unsure, tests=bogofilter
+spam/unsure/.
+@end smallexample
+
+@findex mh-junk-blacklist
+@findex mh-junk-whitelist
+@kindex J b
+@kindex J w
+
+If bogofilter classifies a message incorrectly, or is unsure, you can
+use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J
+w} (@code{mh-junk-whitelist}) to update bogofilter's training.
+
+The @cite{Bogofilter FAQ} suggests that you run the following
+occasionally to shrink the database:
+
+@smallexample
+bogoutil -d wordlist.db | bogoutil -l wordlist.db.new
+mv wordlist.db wordlist.db.prv
+mv wordlist.db.new wordlist.db
+@end smallexample
+
+The @cite{Bogofilter tuning HOWTO} describes how you can fine-tune
+bogofilter.
+
+@subheading SpamProbe
+
+@cindex SpamProbe
+@cindex spam filters, SpamProbe
+
+SpamProbe is a Bayesian spam filtering program. Get it from your local
+distribution or from the @uref{http://spamprobe.sourceforge.net,
+SpamProbe web site}.
+
+To use SpamProbe, add the following recipes to @file{~/.procmailrc}:
+
+@cindex @command{formail}
+@cindex @samp{X-SpamProbe:} header field
+@cindex header field, @samp{X-SpamProbe:}
+
+@smallexample
+PATH=$PATH:/usr/bin/mh
+MAILDIR=$HOME/`mhparam Path`
+
+# Fight spam with SpamProbe.
+:0
+SCORE=| spamprobe receive
+
+:0 wf
+| formail -I "X-SpamProbe: $SCORE"
+
+:0:
+*^X-SpamProbe: SPAM
+spam/.
+@end smallexample
+
+@findex mh-junk-blacklist
+@findex mh-junk-whitelist
+@kindex J b
+@kindex J w
+
+If SpamProbe classifies a message incorrectly, you can use the MH-E
+commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J w}
+(@code{mh-junk-whitelist}) to update SpamProbe's training.
+
+@subheading Other Things You Can Do
+
+There are a couple of things that you can add to @file{~/.procmailrc}
+in order to filter out a lot of spam and viruses. The first is to
+eliminate any message with a Windows executable (which is most likely
+a virus). The second is to eliminate mail in character sets that you
+can't read.
+
+@cindex @samp{Content-Transfer-Encoding:} header field
+@cindex @samp{Content-Type:} header field
+@cindex @samp{Subject:} header field
+@cindex header field, @samp{Content-Transfer-Encoding:}
+@cindex header field, @samp{Content-Type:}
+@cindex header field, @samp{Subject:}
+
+@smallexample
+PATH=$PATH:/usr/bin/mh
+MAILDIR=$HOME/`mhparam Path`
+
+#
+# Filter messages with win32 executables/virii.
+#
+# These attachments are base64 and have a TVqQAAMAAAAEAAAA//8AALg
+# pattern. The string "this program cannot be run in MS-DOS mode"
+# encoded in base64 is 4fug4AtAnNIbg and helps to avoid false
+# positives (Roland Smith via Pete from the bogofilter mailing list).
+#
+:0 B:
+* ^Content-Transfer-Encoding:.*base64
+* ^TVqQAAMAAAAEAAAA//8AALg
+* 4fug4AtAnNIbg
+spam/exe/.
+
+#
+# Filter mail in unreadable character sets (from the Bogofilter FAQ).
+#
+UNREADABLE='[^?"]*big5|iso-2022-jp|ISO-2022-KR|euc-kr|gb2312|ks_c_5601-1987'
+
+:0:
+* 1^0 $ ^Subject:.*=\?($UNREADABLE)
+* 1^0 $ ^Content-Type:.*charset="?($UNREADABLE)
+spam/unreadable/.
+
+:0:
+* ^Content-Type:.*multipart
+* B ?? $ ^Content-Type:.*^?.*charset="?($UNREADABLE)
+spam/unreadable/.
+@end smallexample
+
+@node Miscellaneous, Scan Line Formats, Junk, Top
+@chapter Miscellaneous Commands, Variables, and Buffers
+
+This chapter covers the following command and the various MH-E
+buffers,
+
+@ftable @code
+@item mh-version
+Display version information about MH-E and the MH mail handling
+system.
+@end ftable
+
+@cindex buffers, @samp{*MH-E Info*}
+@cindex MH-E version
+@cindex @samp{*MH-E Info*}
+@cindex version
+@kindex M-x mh-version
+
+One command worth noting is @kbd{M-x mh-version}. You can compare the
+version this command prints to the latest release (@pxref{Getting
+MH-E}). The output of @kbd{M-x mh-version}, found in a buffer named
+@samp{*MH-E Info*}, should usually be included with any bug report you
+submit (@pxref{Bug Reports}).
+
+@subheading MH-E Buffers
+
+Besides the MH-Folder, MH-Show, and MH-Letter buffers, MH-E creates
+several other buffers. They are:
+
+@table @samp
+@cindex @samp{*MH-E Folders*}
+@cindex buffers, @samp{*MH-E Folders*}
+@findex mh-list-folders
+@item *MH-E Folders*
+@kindex F l
+This buffer contains the output of @kbd{F l} (@code{mh-list-folders}).
+@xref{Folders}.
+@c -------------------------
+@cindex @samp{*MH-E Help*}
+@cindex buffers, @samp{*MH-E Help*}
+@findex mh-help
+@item *MH-E Help*
+@kindex ?
+@kindex C-c ?
+This buffer contains the output of @kbd{?} (@code{mh-help}) and
+@kbd{C-c ?} in MH-Letter mode. @xref{Using This Manual}.
+@c -------------------------
+@cindex @samp{*MH-E Info*}
+@cindex buffers, @samp{*MH-E Info*}
+@item *MH-E Info*
+This buffer contains the output of @kbd{M-x mh-version @key{RET}}.
+@c -------------------------
+@cindex @samp{*MH-E Log*}
+@cindex buffers, @samp{*MH-E Log*}
+@item *MH-E Log*
+This buffer contains the last 100 lines of the output of the various
+MH commands.
+@c -------------------------
+@cindex @samp{*MH-E Mail Delivery*}
+@cindex buffers, @samp{*MH-E Mail Delivery*}
+@item *MH-E Mail Delivery*
+This buffer contains the transcript of a mail delivery. @xref{Sending
+Message}.
+@c -------------------------
+@cindex @samp{*MH-E Recipients*}
+@cindex buffers, @samp{*MH-E Recipients*}
+@findex mh-check-whom
+@item *MH-E Recipients*
+@kindex C-c C-w
+This buffer contains the output of @kbd{C-c C-w}
+(@code{mh-check-whom}) and is killed when draft is sent.
+@xref{Checking Recipients}.
+@c -------------------------
+@cindex @samp{*MH-E Sequences*}
+@cindex buffers, @samp{*MH-E Sequences*}
+@item *MH-E Sequences*
+This buffer contains the output of @kbd{S l}
+(@code{mh-list-sequences}). @xref{Sequences}.
+@c -------------------------
+@cindex @samp{*mh-temp*}
+@cindex buffers, @samp{*mh-temp*}
+@item *mh-temp*
+This is a scratch, ephemeral, buffer used by MH-E functions. Note that
+it is hidden because the first character in the name is a space.
+You'll generally not have any need for this buffer.
+@end table
+
+@node Scan Line Formats, Procmail, Miscellaneous, Top
+@appendix Scan Line Formats
+
+@cindex scan line formats
+
+This appendix discusses how MH-E creates, parses, and manipulates scan
+lines. If you have your own MH scan or inc format files, you
+@strong{can} teach MH-E how to handle them, but it isn't easy as
+you'll see.
+
+@cindex @samp{mh-scan-line-formats} customization group
+@cindex customization group, @samp{mh-scan-line-formats}
+
+This table lists the options in the @samp{mh-scan-line-formats}
+customization group.
+
+@vtable @code
+@item mh-adaptive-cmd-note-flag
+On means that the message number width is determined dynamically
+(default: @samp{on}).
+@c -------------------------
+@item mh-scan-format-file
+Specifies the format file to pass to the scan program (default:
+@samp{Use MH-E scan Format}).
+@c -------------------------
+@item mh-scan-prog
+Program used to scan messages (default: @code{"scan"}).
+@end vtable
+
+@vindex mh-adaptive-cmd-note-flag
+
+There are a couple of caveats when creating your own scan format file.
+First, MH-E will not work if your scan lines do not include message
+numbers. It will work poorly if you don't dedicate a column for
+showing the current message and notations. You won't be able to use
+the option @code{mh-adaptive-cmd-note-flag} or the threading features
+(@pxref{Threading}).
+
+@cindex message numbers
+@findex mh-set-cmd-note
+@vindex mh-adaptive-cmd-note-flag
+@vindex mh-scan-format-file
+
+If you've created your own format to handle long message numbers,
+you'll be pleased to know you no longer need it since MH-E adapts its
+internal format based upon the largest message number if
+@code{mh-adaptive-cmd-note-flag} is on (the default). If you prefer
+fixed-width message numbers, turn off @code{mh-adaptive-cmd-note-flag}
+and call @code{mh-set-cmd-note} with the width specified by your
+format file (see @code{mh-scan-format-file}). For example, the default
+width is 4, so you would use @samp{(mh-set-cmd-note 4)}.
+
+@vindex mh-adaptive-cmd-note-flag
+@vindex mh-scan-format-file
+@vindex mh-scan-format-mh
+@vindex mh-scan-format-nmh
+
+The default setting for @code{mh-scan-format-file} is @samp{Use MH-E
+scan Format}. This means that the format string will be taken from the
+either @code{mh-scan-format-mh} or @code{mh-scan-format-nmh} depending
+on whether MH or nmh (or GNU mailutils) is in use. This setting also
+enables you to turn on the option @code{mh-adaptive-cmd-note-flag}.
+You can also set this option to @samp{Use Default scan Format} to get
+the same output as you would get if you ran @command{scan} from the
+shell. If you have a format file that you want MH-E to use but not MH,
+you can set this option to @samp{Specify a scan Format File} and enter
+the name of your format file.
+
+@vindex mh-scan-format-file
+@vindex mh-scan-format-mh
+@vindex mh-scan-format-nmh
+
+The scan format that MH-E uses when @code{mh-scan-format-file} is set
+to its default of @samp{Use MH-E scan Format} is held in the variables
+@code{mh-scan-format-nmh} and @code{mh-scan-format-mh} depending on
+whether you are using nmh (or GNU mailutils) or not. Typically, you
+create your own format files rather than modifying these variables.
+The value of @code{mh-scan-format-nmh} is:
+
+@smallexample
+(concat
+ "%4(msg)"
+ "%<(cur)+%| %>"
+ "%<@{replied@}-"
+ "%?(nonnull(comp@{to@}))%<(mymbox@{to@})t%>"
+ "%?(nonnull(comp@{cc@}))%<(mymbox@{cc@})c%>"
+ "%?(nonnull(comp@{bcc@}))%<(mymbox@{bcc@})b%>"
+ "%?(nonnull(comp@{newsgroups@}))n%>"
+ "%<(zero) %>"
+ "%02(mon@{date@})/%02(mday@{date@})%<@{date@} %|*%>"
+ "%<(mymbox@{from@})%<@{to@}To:%14(decode(friendly@{to@}))%>%>"
+ "%<(zero)%17(decode(friendly@{from@}))%> "
+ "%(decode@{subject@})%<@{body@}<<%@{body@}%>")
+@end smallexample
+
+@cindex decoding RFC 2047
+@cindex RFC 2047, decoding
+@vindex mh-scan-format-mh
+
+The setting for @code{mh-scan-format-mh} is similar, except that MH
+doesn't have the function @code{decode} (which is used to decode RFC
+2047 encodings).
+
+@cindex notations, scan line
+@cindex scan line notations
+
+These strings are passed to the @command{scan} program via the
+@option{-format} argument. The formats are identical to the defaults
+except that additional hints for fontification have been added to the
+existing notations in the fifth column (remember that in Emacs, the
+columns start at 0). The values of the fifth column, in priority
+order, are: @samp{-} if the message has been replied to, @samp{t} if
+an address in the @samp{To:} field matches one of the mailboxes of the
+current user, @samp{c} if the @samp{Cc:} field matches, @samp{b} if
+the @samp{Bcc:} field matches, and @samp{n} if a non-empty
+@samp{Newsgroups:} field is present.
+
+@cindex @command{scan}
+@cindex MH commands, @command{scan}
+@vindex mh-progs
+@vindex mh-scan-prog
+
+The name of the program that generates a listing of one line per
+message is held in @code{mh-scan-prog} (default: @code{"scan"}).
+Unless this variable contains an absolute pathname, it is assumed to
+be in the @code{mh-progs} directory (@pxref{Getting Started}). You may
+link another program to @command{scan} (see @samp{mh-profile}(5)) to
+produce a different type of listing@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/faswsprs.html, Find and Specify with scan
+pick Ranges Sequences} in the MH book.}.
+
+@cindex regular expressions, scan line formats
+@findex mh-set-cmd-note
+@findex setq
+
+If you change the format of the scan lines you'll need to tell MH-E
+how to parse the new format. As you will see, quite a lot of variables
+are involved to do that. Use @kbd{M-x apropos @key{RET}
+mh-scan.*regexp @key{RET}} to obtain a list of these variables. You
+will also have to call @code{mh-set-cmd-note} if your notations are
+not in column 4 (columns in Emacs start with 0). Note that unlike most
+of the user options described in this manual, these are variables and
+must be set with @code{setq} instead of in a customization buffer. For
+help with regular expressions, see
+@ifnothtml
+@ref{Regexps, , Syntax of Regular Expressions, emacs, The
+GNU Emacs Manual}.
+@end ifnothtml
+@ifhtml
+section
+@uref{http://www.gnu.org/software/emacs/manual/html_node/Regexps.html,
+Syntax of Regular Expressions} in @cite{The GNU Emacs Manual}.
+@end ifhtml
+
+The first variable has to do with pruning out garbage.
+
+@vtable @code
+@cindex @command{inc}
+@cindex MH commands, @command{inc}
+@cindex @command{scan}
+@cindex MH commands, @command{scan}
+@item mh-scan-valid-regexp
+This regular expression describes a valid scan line. This is used to
+eliminate error messages that are occasionally produced by
+@command{inc}@footnote{See the section
+@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next
+prev} in the MH book.} or @command{scan} (default: @code{"^ *[0-9]"}).
+@end vtable
+
+Next, many variables control how the scan lines are parsed.
+
+@vtable @code
+@vindex mh-folder-body
+@vindex mh-folder-font-lock-keywords
+@item mh-scan-body-regexp
+This regular expression matches the message body fragment. Note that
+the default setting of @code{mh-folder-font-lock-keywords} expects
+this expression to contain at least one parenthesized expression which
+matches the body text as in the default of
+@code{"\\(<<\\([^\n]+\\)?\\)"}. If this regular expression is not
+correct, the body fragment will not be highlighted with the face
+@code{mh-folder-body}.
+@c -------------------------
+@vindex mh-folder-cur-msg-number
+@vindex mh-folder-font-lock-keywords
+@vindex mh-note-cur
+@item mh-scan-cur-msg-number-regexp
+This regular expression matches the current message. It must match
+from the beginning of the line. Note that the default setting of
+@code{mh-folder-font-lock-keywords} expects this expression to contain
+at least one parenthesized expression which matches the message number
+as in the default of @w{@code{"^\\( *[0-9]+\\+\\).*"}}. This
+expression includes the leading space and current message marker
+@samp{+} within the parenthesis since it looks better to highlight
+these items as well. The highlighting is done with the face
+@code{mh-folder-cur-msg-number}. This regular expression should be
+correct as it is needed by non-fontification functions. See also
+@code{mh-note-cur}.
+@c -------------------------
+@vindex mh-folder-date
+@vindex mh-folder-font-lock-keywords
+@vindex mh-scan-sent-to-me-sender-regexp
+@item mh-scan-date-regexp
+This regular expression matches a valid date. It must @strong{not} be
+anchored to the beginning or the end of the line. Note that the
+default setting of @code{mh-folder-font-lock-keywords} expects this
+expression to contain only one parenthesized expression which matches
+the date field as in the default of
+@code{"\\([0-9][0-9]/[0-9][0-9]\\)"}. If this regular expression is
+not correct, the date will not be highlighted with the face
+@code{mh-folder-date}.
+@c -------------------------
+@vindex mh-folder-deleted
+@vindex mh-folder-font-lock-keywords
+@vindex mh-note-deleted
+@item mh-scan-deleted-msg-regexp
+This regular expression matches deleted messages. It must match from
+the beginning of the line. Note that the default setting of
+@code{mh-folder-font-lock-keywords} expects this expression to contain
+at least one parenthesized expression which matches the message number
+as in the default of @code{"^\\( *[0-9]+\\)D"}. This expression
+includes the leading space within the parenthesis since it looks
+better to highlight it as well. The highlighting is done with the face
+@code{mh-folder-deleted}. This regular expression should be correct as
+it is needed by non-fontification functions. See also
+@code{mh-note-deleted}.
+@c -------------------------
+@vindex mh-folder-font-lock-keywords
+@vindex mh-folder-msg-number
+@item mh-scan-good-msg-regexp
+This regular expression matches ``good'' messages. It must match from
+the beginning of the line. Note that the default setting of
+@code{mh-folder-font-lock-keywords} expects this expression to contain
+at least one parenthesized expression which matches the message number
+as in the default of @w{@code{"^\\( *[0-9]+\\)[^D^0-9]"}}. This
+expression includes the leading space within the parenthesis since it
+looks better to highlight it as well. The highlighting is done with
+the face @code{mh-folder-msg-number}. This regular expression should
+be correct as it is needed by non-fontification functions.
+@c -------------------------
+@vindex mh-scan-format-file
+@item mh-scan-msg-format-regexp
+This regular expression finds the message number width in a scan
+format. Note that the message number must be placed in a parenthesized
+expression as in the default of @code{"%\\([0-9]*\\)(msg)"}. This
+variable is only consulted if @code{mh-scan-format-file} is set to
+@samp{Use MH-E scan Format}.
+@c -------------------------
+@vindex mh-scan-format-file
+@item mh-scan-msg-format-string
+This is a format string for the width of the message number in a scan
+format. Use @samp{0%d} for zero-filled message numbers. This variable
+is only consulted if @code{mh-scan-format-file} is set to @samp{Use
+MH-E scan Format} (default: @code{"%d"}).
+@c -------------------------
+@item mh-scan-msg-number-regexp
+This regular expression extracts the message number. It must match
+from the beginning of the line. Note that the message number must be
+placed in a parenthesized expression as in the default of @w{@code{"^
+*\\([0-9]+\\)"}}.
+@c -------------------------
+@item mh-scan-msg-overflow-regexp
+This regular expression matches overflowed message numbers (default:
+@code{"^[?0-9][0-9]"}).
+@c -------------------------
+@item mh-scan-msg-search-regexp
+This regular expression matches a particular message. It is a format
+string; use @samp{%d} to represent the location of the message number
+within the expression as in the default of @code{"^[^0-9]*%d[^0-9]"}.
+@c -------------------------
+@vindex mh-folder-address
+@vindex mh-folder-font-lock-keywords
+@vindex mh-folder-to
+@item mh-scan-rcpt-regexp
+This regular expression specifies the recipient in messages you sent.
+Note that the default setting of @code{mh-folder-font-lock-keywords}
+expects this expression to contain two parenthesized expressions. The
+first is expected to match the @samp{To:} that the default scan format
+file generates. The second is expected to match the recipient's name
+as in the default of @code{"\\(To:\\)\\(..............\\)"}. If this
+regular expression is not correct, the @samp{To:} string will not be
+highlighted with the face @code{mh-folder-to} and the recipient will not be
+highlighted with the face @code{mh-folder-address}.
+@c -------------------------
+@vindex mh-folder-font-lock-keywords
+@vindex mh-folder-refiled
+@vindex mh-note-refiled
+@item mh-scan-refiled-msg-regexp
+This regular expression matches refiled messages. It must match from
+the beginning of the line. Note that the default setting of
+@code{mh-folder-font-lock-keywords} expects this expression to contain
+at least one parenthesized expression which matches the message number
+as in the default of @w{@code{"^\\( *[0-9]+\\)\\^"}}. This expression
+includes the leading space within the parenthesis since it looks
+better to highlight it as well. The highlighting is done with the face
+@code{mh-folder-refiled}. This regular expression should be correct as
+it is needed by non-fontification functions. See also
+@code{mh-note-refiled}.
+@c -------------------------
+@vindex mh-folder-font-lock-keywords
+@vindex mh-folder-sent-to-me-sender
+@vindex mh-mh-folder-sent-to-me-hint
+@vindex mh-scan-format-nmh
+@item mh-scan-sent-to-me-sender-regexp
+This regular expression matches messages sent to us. Note that the
+default setting of @code{mh-folder-font-lock-keywords} expects this
+expression to contain at least two parenthesized expressions. The
+first should match the fontification hint (see
+@code{mh-scan-format-nmh}) and the second should match the user name
+as in the default of
+@w{@code{"^ *[0-9]+.\\([bct]\\).....[ ]*\\(..................\\)"}}.
+If this regular expression is not correct, the notation hints will not
+be highlighted with the face @code{mh-mh-folder-sent-to-me-hint} and
+the sender will not be highlighted with the face
+@code{mh-folder-sent-to-me-sender}.
+@c -------------------------
+@vindex mh-folder-followup
+@vindex mh-folder-font-lock-keywords
+@vindex mh-folder-subject
+@item mh-scan-subject-regexp
+This regular expression matches the subject. It must match from the
+beginning of the line. Note that the default setting of
+@samp{mh-folder-font-lock-keywords} expects this expression to contain
+at least three parenthesized expressions. The first is expected to
+match the @samp{Re:} string, if any, and is highlighted with the face
+@code{mh-folder-followup}. The second matches an optional bracketed
+number after @samp{Re:}, such as in @samp{Re[2]:} (and is thus a
+sub-expression of the first expression). The third is expected to
+match the subject line itself which is highlighted with the face
+@code{mh-folder-subject}. For example, the default is
+@w{@code{"^ *[0-9]+........[ ]*...................}}@*
+@w{@code{\\([Rr][Ee]\\(\\[[0-9]+\\]\\)?:\\s-*\\)*\\([^<\n]*\\)"}}.
+This regular expression should be correct as it is needed by
+non-fontification functions. Note that this example is broken up on
+two lines for readability, but is actually a single string.
+@end vtable
+
+Finally, there are a slew of variables that control how MH-E annotates
+the scan lines.
+
+@vtable @code
+@findex mh-set-cmd-note
+@vindex mh-adaptive-cmd-note-flag
+@item mh-cmd-note
+Column for notations (default: 4). This variable should be set with
+the function @code{mh-set-cmd-note}. This variable may be updated
+dynamically if @code{mh-adaptive-cmd-note-flag} is on. The following
+variables contain the notational characters. Note that columns in
+Emacs start with 0.
+@c -------------------------
+@item mh-note-copied
+Messages that have been copied are marked by this character (default:
+@code{?C}).
+@c -------------------------
+@vindex mh-scan-cur-msg-number-regexp
+@item mh-note-cur
+The current message (in MH, not in MH-E) is marked by this character
+(default: @code{?+}). See also @code{mh-scan-cur-msg-number-regexp}.
+@c -------------------------
+@vindex mh-scan-deleted-msg-regexp
+@item mh-note-deleted
+Messages that have been deleted are marked by this character (default:
+@code{?D}). See also @code{mh-scan-deleted-msg-regexp}.
+@c -------------------------
+@item mh-note-dist
+Messages that have been redistributed are marked by this character
+(default: @code{?R}).
+@c -------------------------
+@item mh-note-forw
+Messages that have been forwarded are marked by this character
+(default: @code{?F}).
+@c -------------------------
+@item mh-note-printed
+Messages that have been printed are marked by this character (default:
+@code{?P}).
+@c -------------------------
+@vindex mh-scan-refiled-msg-regexp
+@item mh-note-refiled
+Messages that have been refiled are marked by this character (default:
+@code{?^}). See also @code{mh-scan-refiled-msg-regexp}.
+@c -------------------------
+@item mh-note-repl
+Messages that have been replied to are marked by this character
+(default: @code{?-}).
+@c -------------------------
+@item mh-note-seq
+Messages in a user-defined sequence are marked by this character
+(default: @code{?%}). Messages in the @samp{search} sequence are
+marked by this character as well.
+@end vtable
+
+For example, let's say I have the following in @file{scan.format}
+which displays the sender, the subject, and the message number. This
+format places a @samp{+} after the message number for the current
+message according to MH; it also uses that column for notations.
+
+@smallexample
+%20(decode(friendly@{from@})) %50(decode@{subject@}) %4(msg)%<(cur)+%| %>
+@end smallexample
+
+@vindex mh-adaptive-cmd-note-flag
+@vindex mh-scan-format-file
+@vindex mh-scan-format-file, example
+
+The first thing you have to do is tell MH-E to use this file.
+Customize @code{mh-scan-format-file} and set its value to @samp{Use
+Default scan Format}. If you didn't get already turn off
+@code{mh-adaptive-cmd-note-flag}, you'll need to do that first.
+
+Next, tell MH-E what a valid scan line looks like so that you can at
+least display the output of scan in your MH-Folder buffer.
+
+@vindex mh-scan-valid-regexp, example
+
+@smalllisp
+(setq mh-scan-valid-regexp "[0-9]+[+D^ ]$")
+@end smalllisp
+
+Now, in order to get rid of the @samp{Cursor not pointing to message}
+message, you need to tell MH-E how to access the message number. You
+should also see why MH-E requires that you include a message number in
+the first place.
+
+@vindex mh-scan-msg-number-regexp, example
+@vindex mh-scan-msg-search-regexp, example
+
+@smalllisp
+(setq mh-scan-msg-number-regexp "^.* \\([0-9]+\\)[+D^ ]$")
+(setq mh-scan-msg-search-regexp " %d[+D^ ]$")
+@end smalllisp
+
+In order to get the next and previous commands working, add this.
+
+@vindex mh-scan-good-msg-regexp, example
+
+@smalllisp
+(setq mh-scan-good-msg-regexp "^.* \\([0-9]+\\)[+D^ ]$")
+@end smalllisp
+
+Note that the current message isn't marked with a @samp{+} when moving
+between the next and previous messages. Here is the code required to
+get this working.
+
+@vindex set-mh-cmd-note, example
+@vindex mh-scan-cur-msg-number-regexp, example
+
+@smalllisp
+(set-mh-cmd-note 76)
+(setq mh-scan-cur-msg-number-regexp "^.* \\([0-9]+\\)\\+$")
+@end smalllisp
+
+Finally, add the following to delete and refile messages.
+
+@vindex mh-scan-deleted-msg-regexp, example
+@vindex mh-scan-refiled-msg-regexp, example
+
+@smalllisp
+(setq mh-scan-deleted-msg-regexp "^.* \\([0-9]+\\)D$")
+(setq mh-scan-refiled-msg-regexp "^.* \\([0-9]+\\)\\^$")
+@end smalllisp
+
+This is just a bare minimum; it's best to adjust all of the regular
+expressions to ensure that MH-E and highlighting perform well.
+
+@node Procmail, Odds and Ends, Scan Line Formats, Top
+@appendix Reading Mailing Lists Effectively
+
+@cindex @command{procmail}
+@cindex @command{slocal}
+@cindex Gnus
+@cindex MH commands, @command{slocal}
+@cindex Unix commands, @command{procmail}
+@cindex mailing lists, reading
+
+This appendix explains how to use @uref{http://www.procmail.org/,
+procmail} to file mail from mailing lists into folders which can then
+be read easily with MH-E@footnote{The MH equivalent, @command{slocal},
+can be used as well, but procmail is more flexible and more packages
+exist for procmail than for slocal.}. Some mailing lists have such
+high traffic that Gnus must be used and I discuss how to use Gnus
+side-by-side with MH-E.
+
+@cindex @file{.procmailrc}
+@cindex files, @file{.procmailrc}
+
+First, I'll describe how to put mail from your mailing lists directly
+into an MH folder using @command{procmail}. First, add the following
+to @file{~/.procmailrc}. While the logging variables aren't strictly
+necessary, they are extremely useful.
+
+@smallexample
+[1] # Update PATH so procmail can find myrcvstore, rcvstore and mhparam.
+[2] PATH=$PATH:/usr/lib/mh:/usr/bin/mh:$HOME/bin
+[3]
+[4] # Point LOGFILE at the actual log file.
+[5] LOGFILE=$HOME/.procmail.log
+[6]
+[7] # This setting provides just the right amount of information.
+[8] LOGABSTRACT=all
+[9]
+[10] # Uncomment the following line to see how your patterns match.
+[11] #VERBOSE=yes
+[12]
+[13] # Place mail sent to any MH-E mailing list in +mh-e.
+[14] :0 w: mh-e$LOCKEXT
+[15] * ^TO.*mh-e-.*@.*sourceforge.net
+[16] | myrcvstore -create +mh-e
+@end smallexample
+
+@cindex @command{rcvstore}
+@cindex MH commands, @command{rcvstore}
+
+Line 14 creates a lock file in your mail directory based upon the name
+of the folder. This is done because @command{rcvstore} does not
+perform locking. While this lock file will prevent @command{procmail}
+from writing to a folder concurrently, there is a slight chance that
+you might lose a message if you're performing operations on a folder
+at the same time @command{rcvstore} is placing a message there. You
+have been warned. Now that that disclaimer is out of the way, note
+that I've been using this set-up for over a decade and haven't lost
+anything to my knowledge@footnote{See
+@uref{https://savannah.nongnu.org/bugs/?func=detailbug&bug_id=4361&group_id=2166,
+Savannah issue #4361} to see if @command{rcvstore} locking is still an
+issue.}.
+
+@cindex @samp{Unseen-Sequence:} MH profile component
+@cindex MH profile component, @samp{Unseen-Sequence:}
+
+Line 16 uses the following script, @code{myrcvstore}, to massage the
+message as described in the comment and file the message in the given
+folder@footnote{The @samp{-create} argument wasn't always the default
+to @command{rcvstore}.}.
+
+@smallexample
+#! /bin/sh
+
+# Accepts a message on standard input and passes it through rcvstore
+# after first passing it through any filters. All arguments are passed
+# on to rcvstore.
+
+# Force the "From user date" to become part of header. One reason this
+# is done is because the presence of the From field confuses dist so
+# that dist adds a new header, rather than using the existing header.
+# Note that this should not be done for any message that goes into a
+# Gnus incoming file (Gnus will thrown an error) nor should it be
+# applied to any message that goes to the system mailbox because the
+# entire mailbox will be incorporated as a single message.
+formail -c -z -R 'From ' X-Envelope-From: |
+rcvstore $@@
+@end smallexample
+
+If your version of @command{rcvstore} doesn't add messages to the
+@samp{unseen} sequence by default, add the following line to your MH
+profile:
+
+@smallexample
+Unseen-Sequence: unseen
+@end smallexample
+
+Now view your new messages with the speedbar (@pxref{Speedbar}) or with
+@kbd{F n} (@code{mh-index-new-messages}). @xref{Folders}.
+
+If you're on a mailing list that is so voluminous that it is
+impossible to read every message, it usually better to read the
+mailing list like a newsgroup in a news reader. Emacs has a built-in
+newsreader called Gnus. The remainder of this appendix talks about how
+to use Gnus with an MH message store. The version of Gnus that was
+used to prepare this manual was 5.10. Versions 5.8 through 5.10 should
+work but versions prior to 5.8 use different options.
+
+This table contains a list of Gnus options that you will have to
+modify. Note that for them to become accessible, you'll have to load
+@file{nnml.el} first. This can be done with @kbd{M-x load-library
+@key{RET} nnml @key{RET}}.
+
+@vtable @code
+@item gnus-secondary-select-methods
+Select the @samp{nnml} value. This select method uses directories for
+folders and individual files for messages, just like MH. You do not
+have to set an address.
+@c -------------------------
+@item mail-sources
+Select the @samp{Several files in a directory} value, check the
+@samp{Path} box and enter @file{~/Mail} to tell Gnus where to find
+your mail.
+@c -------------------------
+@vindex mail-user-agent
+@item message-mail-user-agent
+In order to send mail within Gnus using MH-E, set this option to
+@samp{mail-user-agent} and set the @code{mail-user-agent} option to
+@samp{Emacs interface to MH}.
+@c -------------------------
+@item nnmail-keep-last-article
+Since Gnus keeps track of which messages you have read, it would be
+bad if Gnus expired the last message, for example, message 100, and
+@command{rcvstore} gave the next new message number 1. Gnus would then
+ignore it since it thinks that you've read messages 1-100. Turning on
+this option ensures that the last message is never removed thereby
+eliminating this problem.
+@end vtable
+
+Next add the following to @file{~/.procmailrc}. If you don't subscribe
+to the GnuCash mailing list, substitute one to which you are
+subscribed.
+
+@smallexample
+PATH=$PATH:/usr/bin/mh
+MAILDIR=$HOME/`mhparam Path`
+# Place mail sent to the GnuCash mailing list in gnucash.spool, where
+# Gnus will pick it up.
+:0:
+* ^TO.*gnucash.*@.*gnucash.org
+gnucash.spool
+@end smallexample
+
+Wait for some messages to appear in @file{gnucash.spool} and run Gnus
+with @kbd{M-x gnus @key{RET}}. To view the folder created in the
+example above, you would tell Gnus about it the first time only with
+@kbd{G m gnucash @key{RET} nnml @key{RET}}. In MH-E, this folder is
+known as @samp{+gnucash}.
+
+@node Odds and Ends, History, Procmail, 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 lists.
+I also point out some additional sources of information.
+
+@menu
+* Bug Reports::
+* Mailing Lists::
+* MH FAQ and Support::
+* Getting MH-E::
+@end menu
+
+@node Bug Reports, Mailing Lists, Odds and Ends, Odds and Ends
+@appendixsec Bug Reports
+
+@cindex bugs
+@cindex SourceForge
+@kindex M-x mh-version
+
+Bug reports should be filed at
+@uref{https://sourceforge.net/tracker/?group_id=13357&atid=113357,
+SourceForge}. You need to be a SourceForge user to submit bug reports,
+but this is easy enough to do that it shouldn't be a restriction for
+you. Please include the output of @kbd{M-x mh-version}
+(@pxref{Miscellaneous}) in any bug report you send unless you're 110%
+positive we won't ask for it.
+
+@node Mailing Lists, MH FAQ and Support, Bug Reports, Odds and Ends
+@appendixsec MH-E Mailing Lists
+
+@cindex SourceForge
+@cindex mailing lists
+
+There are several mailing lists for MH-E. They are @i{mh-e-users at
+lists.sourceforge.net}, @i{mh-e-announce at lists.sourceforge.net},
+and @i{mh-e-devel at lists.sourceforge.net}. You can subscribe or view
+the archives at @uref{https://sourceforge.net/mail/?group_id=13357,
+SourceForge}. Do not report bugs on these lists; please submit them
+via SourceForge (@pxref{Bug Reports}).
+
+@node MH FAQ and Support, Getting MH-E, Mailing Lists, Odds and Ends
+@appendixsec MH FAQ and Support
+
+@cindex FAQ
+@cindex MH FAQ
+
+The article @uref{http://www.newt.com/faq/mh.html, @cite{MH Frequently
+Asked Questions (FAQ) with Answers}} 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.
+
+@cindex support
+
+You can find FAQs on MH-E at the
+@uref{https://sourceforge.net/tracker/?group_id=13357&atid=213357,
+Support Requests} page on SourceForge. If you don't find the answer to
+your question, file a support request and your question will become a
+new FAQ!
+
+@node Getting MH-E, , MH FAQ and Support, Odds and Ends
+@appendixsec Getting MH-E
+
+@cindex MH-E, obtaining
+@cindex getting MH-E
+@cindex obtaining MH-E
+
+Because MH-E is undergoing a phase of sustained growth, the version of
+MH-E in your Emacs is likely to be out of date although it is most
+likely to be more up to date than the copy that comes with the MH
+distribution in @file{miscellany/mh-e}.
+
+@cindex change log
+@cindex release notes
+
+New MH-E releases are always available for downloading at
+@uref{https://sourceforge.net/project/showfiles.php?group_id=13357,
+SourceForge} before they appear in an Emacs release. You can read the
+release notes on that page to determine if the given release of MH-E
+is already installed in your version of Emacs. You can also read the
+change log to see if you are interested in what the given release of
+MH-E has to offer (although we have no doubt that you will be
+extremely interested in all new releases).
+
+@cindex Debian
+
+If you use Debian, you can install the Debian
+@uref{http://packages.debian.org/unstable/mail/mh-e, mh-e package}
+instead.
+
+@cindex files, @samp{MH-E-NEWS}
+@cindex files, @samp{README}
+@cindex news
+@cindex @samp{MH-E-NEWS}
+@cindex @samp{README}
+@kindex M-x mh-version
+
+After you download and extract the MH-E tarball, read the
+@file{README} file and @file{MH-E-NEWS}. These correspond to the
+release notes and change log mentioned above. The file @file{README}
+contains instructions on installing MH-E. 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}.
+
+@cindex contributed software
+@cindex manual
+@cindex documentation
+
+In addition to the mh-e package, the
+@uref{https://sourceforge.net/project/showfiles.php?group_id=13357,
+SourceForge} site also contains doc and contrib packages. The former
+is the latest release of this manual, and the latter contains a few
+contributed packages you might find useful.
+
+@node History, GFDL, Odds and Ends, Top
+@appendix History of MH-E
+
+@cindex Bill Wohler
+@cindex Brian Reid
+@cindex Gildea, Stephen
+@cindex Jim Larus
+@cindex Larus, Jim
+@cindex MH-E, versions
+@cindex Reid, Brian
+@cindex SourceForge
+@cindex Stephen Gildea
+@cindex Wohler, Bill
+@cindex history of MH-E
+@cindex versions of MH-E
+
+MH-E was originally written by Brian Reid in 1983 and has changed
+hands several times 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 added many
+improvements. Bill Wohler then took over in 2000 and moved its
+development to @uref{http://sourceforge.net/, SourceForge} where it
+lives today.
+
+@menu
+* From Brian Reid::
+* From Jim Larus::
+* From Stephen Gildea::
+* From Bill Wohler::
+@end menu
+
+@node From Brian Reid, From Jim Larus, History, History
+@appendixsec From Brian Reid
+
+@cindex 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 sub-process 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
+(draft form editing was introduced in version 7.4).}.
+
+Brian Reid, June 1994
+
+@node From Jim Larus, From Stephen Gildea, From Brian Reid, History
+@appendixsec From Jim Larus
+
+@cindex 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 @command{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 @command{xmh}. A few months later, he came back and said
+that he couldn't stand @command{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 Bill Wohler, From Jim Larus, History
+@appendixsec From Stephen Gildea
+
+@cindex Gildea, Stephen
+@cindex Stephen Gildea
+
+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 From Bill Wohler, , From Stephen Gildea, History
+@appendixsec From Bill Wohler
+
+@cindex Wohler, Bill
+@cindex Bill Wohler
+
+The preface originally included the following text which I use to
+begin my story:
+
+@quotation
+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. Next, @w{Version
+5.0} was released, which fixed some bugs and incompatibilities, and
+was incorporated into @w{Emacs 19.29}.
+@end quotation
+
+After a long break, Stephen handed the reins over to me in 2000. I
+moved the project to a new site called SourceForge and organized a
+great team of developers. Our first release in late 2001 was version
+6. It appeared around the time of Emacs 21.2 and had menus and tool
+bar buttons.
+
+Then, indexed searches, improved MIME handling, a speedbar, multiple
+identities, alias completion, an index view of unseen messages, spam
+software support, Face and X-Image-URL header field support, Fcc
+completion, arbitrary range handling, and draft form editing were
+introduced in the version 7 series around the time of Emacs 21.4
+(2004). Still, Emacs itself contained version 5 of MH-E released back
+in 1994.
+
+Version 8 development was mostly driven by the rewrite of the manual.
+It also brought mailutils support, S/MIME support, picon support, and
+an improved interface for hiding header fields. The CVS repository was
+migrated from SourceForge to Savannah (only for those files that were
+already part of Emacs) and the software was completely reorganized to
+push back two decades of entropy. Version 8 will appear in Emacs 22.1,
+expected to be released in 2006.
+
+Bill Wohler, February 2006
+
+@node GFDL, GPL, History, Top
+@appendix GNU FREE DOCUMENTATION LICENSE
+@center Version 1.2, November 2002
+
+@display
+Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+@sp 1
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document ``free'' in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@sp 1
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque.''
+
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+@sp 1
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+@sp 1
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+@sp 1
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+A. Use in the Title Page (and on the covers, if any) a title distinct
+ from that of the Document, and from those of previous versions
+ (which should, if there were any, be listed in the History section
+ of the Document). You may use the same title as a previous version
+ if the original publisher of that version gives permission.@*
+B. List on the Title Page, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the Modified
+ Version, together with at least five of the principal authors of the
+ Document (all of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.@*
+C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.@*
+D. Preserve all the copyright notices of the Document.@*
+E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.@*
+F. Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the Modified Version under the
+ terms of this License, in the form shown in the Addendum below.@*
+G. Preserve in that license notice the full lists of Invariant Sections
+ and required Cover Texts given in the Document's license notice.@*
+H. Include an unaltered copy of this License.@*
+I. Preserve the section Entitled ``History'', Preserve its Title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section Entitled ``History'' in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.@*
+J. Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions
+ it was based on. These may be placed in the ``History'' section.
+ You may omit a network location for a work that was published at
+ least four years before the Document itself, or if the original
+ publisher of the version it refers to gives permission.@*
+K. For any section Entitled ``Acknowledgements'' or ``Dedications'',
+ Preserve the Title of the section, and preserve in the section all
+ the substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.@*
+L. Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.@*
+M. Delete any section Entitled ``Endorsements.'' Such a section
+ may not be included in the Modified Version.@*
+N. Do not retitle any existing section to be Entitled ``Endorsements''
+ or to conflict in title with any Invariant Section.@*
+O. Preserve any Warranty Disclaimers.@*
+@sp 1
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+@sp 1
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications.'' You must delete all sections
+Entitled ``Endorsements.''
+@sp 1
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+@sp 1
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+@sp 1
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+@sp 1
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document 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.
+@sp 1
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation 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. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+@end enumerate
+
+@unnumberedsec ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+Copyright (C) @var{year} @var{your name}.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with...Texts.'' line with this:
+
+@smallexample
+@group
+with the Invariant Sections being @var{list their titles}, with the
+Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
+@var{list}.
+@end group
+@end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@node GPL, Key Index, GFDL, Top
+@appendix GNU GENERAL PUBLIC LICENSE
+@center Version 2, June 1991
+
+@display
+Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@unnumberedsec 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 Lesser 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
+@unnumberedsec 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
+@unnumberedsec 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) @var{yyyy} @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 3
+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.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 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) @var{yyyy} @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 Lesser General
+Public License instead of this License.
+
+@node Key Index, Command Index, GPL, Top
+@unnumbered Key (Character) Index
+@printindex ky
+
+@node Command Index, Option Index, Key Index, Top
+@unnumbered Command Index
+@printindex fn
+
+@node Option Index, Concept Index, Command Index, Top
+@unnumbered Option (Variable) Index
+@printindex vr
+
+@node Concept Index, , Option Index, Top
+@unnumbered Concept Index
+@printindex cp
+
+@bye
+
+@c Ispell Helpers
+@c
+@c The following are words that ispell should ignore that would not
+@c normally be in a dictionary (global or personal). Be careful not to
+@c include words here that could potentially be typos of other words
+@c (such as url, elisp, or MHE).
+@c
+@c LocalWords: CTRL ESC SPC f's
+@c LocalWords: addr Aliasfile alist
+@c LocalWords: Baushke Bcc BBN Beranek bogofilter bogofilter's
+@c LocalWords: cmd CMU contrib cron
+@c LocalWords: DesBrisay Dcc devel dir dired docstring filll forw
+@c LocalWords: GECOS Gildea Gildea's Ginnean GnuCash goto gnuserv htm
+@c LocalWords: ImageMagick inbox ispell keychain
+@c LocalWords: Larus licensor LocalWords lookup lpr
+@c LocalWords: makeinfo mairix mbox mh mhbuild mhl mhpath mlisp
+@c LocalWords: MML msg multipart
+@c LocalWords: Namazu NIS nenscript nnml num
+@c LocalWords: packmbox passphrase pathname prev procmail prog repl
+@c LocalWords: slocal sortm SpamAssassin spammers SpamProbe SpamProbe's
+@c LocalWords: sublicense supercite speedbar
+@c LocalWords: Tennex texi texinfo Thelen thelenm
+@c LocalWords: UCI undeleted whatnow wohler xmh ypcat
+@c
+@c See http://www.oreilly.com/oreilly/author/stylesheet.html.
+@c See http://en.wikipedia.org/.
+@c
+@c Note the lowercase mh which is needed to avoid hits in the
+@c functions and variables. Occasionally, check for accidental
+@c inclusion of mh in text by uncommenting the following and executing
+@c it with C-x C-e. You want to see "Search failed"
+@c (let ((case-fold-search nil))
+@c (goto-char (point-min))
+@c (search-forward-regexp "^mh\\( \\|$\\)"))
+@c
+@c An extremely useful setting for texinfo-mode-hook is:
+@c (add-to-list
+@c 'ispell-skip-region-alist
+@c (list
+@c (concat "\\(@\\(small\\)?\\(example\\|lisp\\)"
+@c "\\(@\\([irw]\\|code\\|var\\){[^}]+}\\|"
+@c "@[@{}.]\\|"
+@c "[^@]\\|"
+@c "@\\(end \\)?group\\|"
+@c "@\\(end \\)?cartouche\\)+"
+@c "@end \\(small\\)?\\(example\\|lisp\\)\\|"
+@c "@\\(code\\|command\\|file\\|kbd\\|sc\\){[^}]+}\\|"
+@c "^@end [a-z]+$\\|"
+@c "^@\\([fv]\\|print\\)index .*$\\|"
+@c "@uref{[^,]+,\\|"
+@c "@[a-z]+\\|"
+@c "/[a-z.]+[/}]\\)")))))
+@c
+@c Cross References
+@c
+@c See existing cross-references to the Emacs manual and the Emacs
+@c Lisp manual (search for ``GNU Emacs Manual'' and ``GNU
+@c Emacs Lisp Reference Manual'' respectively).
+
+@c @ftable Sorting
+@c
+@c As per index (sort of): Punctuation, keyboard characters (such as
+@c RET and BS) upper and lowercase mixed (lower comes before
+@c uppercase), control characters go with uppercase C, meta characters
+@c go with uppercase M.
+@c In some cases, the sort isn't strictly ASCII.
+@c For example, SPC (mh-page-msg) reads better before BS
+@c (mh-previous-page) and . (mh-show) is better before ,
+@c (mh-header-display).
+
+@c @vtable Sorting
+@c
+@c Alphabetical, pull hooks into their own table.
+
+@c Local Variables:
+@c sentence-end-double-space: nil
+@c End:
+
+@ignore
+ arch-tag: b778477d-1a10-4a99-84de-f877a2ea6bef
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@comment %**start of header
+@setfilename ../info/newsticker
+@set VERSION 1.9
+@set UPDATED November 2005
+@settitle Newsticker @value{VERSION}
+@syncodeindex vr cp
+@syncodeindex fn cp
+@syncodeindex pg cp
+@comment %**end of header
+
+@copying
+This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}).
+
+@noindent
+Copyright @copyright{} 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
+and with the Back-Cover Texts as in (a) below. A copy of the license
+is included in the section entitled ``GNU Free Documentation License''
+in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Newsticker: (newsticker). A Newsticker for Emacs.
+@end direntry
+
+@titlepage
+@title Newsticker -- a Newsticker for Emacs
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author Ulf Jasper
+@author @email{ulf.jasper@@web.de}
+@author @uref{http://de.geocities.com/ulf_jasper}
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Newsticker
+@end ifnottex
+
+@menu
+* Overview:: General description of newsticker.
+* Requirements:: Requirements for using newsticker.
+* Installation:: Installing newsticker on your system.
+* Usage:: Basic newsticker instructions.
+* Configuration:: Customizable newsticker settings.
+* Remarks:: Remarks about newsticker.
+* GNU Free Documentation License:: The license for this documentation.
+* Index:: Variable, function, and concept index.
+@end menu
+
+@node Overview
+@chapter Overview
+
+Newsticker provides a newsticker for Emacs. A newsticker is a thing
+that asynchronously retrieves headlines from a list of news sites,
+prepares these headlines for reading, and allows for loading the
+corresponding articles in a web browser.
+
+
+Headlines consist of a title and (possibly) a small description. They
+are contained in "RSS" (RDF Site Summary) or "Atom" files. Newsticker
+should work with the following RSS formats:
+
+@itemize
+@item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or
+@uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html}),
+@item RSS 0.92 (see @uref{http://backend.userland.com/rss092}),
+@item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec}
+@item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}),
+@end itemize
+@itemize
+as well as the following Atom formats:
+@item Atom 0.3
+@item Atom 1.0 (see
+@uref{http://www.ietf.org/internet-drafts/draft-ietf-atompub-format-11.txt}).
+@end itemize
+
+That makes Newsticker.el an "Atom aggregator, "RSS reader", or "RSS
+aggregator".
+
+Newsticker provides several commands for reading headlines, navigating
+through them, marking them as read/unread, hiding old headlines etc.
+Headlines can be displayed as plain text or as rendered HTML.
+
+Headlines can be displayed in the echo area, either scrolling like
+messages in a stock-quote ticker, or just changing.
+
+Newsticker allows for automatic processing of headlines by providing
+hooks and (sample) functions for automatically downloading images and
+enclosed files (as delivered by podcasts, e.g.).
+
+@ifhtml
+Here are screen shots of the @uref{newsticker-1.7.png, version 1.7
+(current version)} and some older screen shots:
+@uref{newsticker-1.6.png, version 1.6},
+@uref{newsticker-1.5.png, version 1.5},
+@uref{newsticker-1.4.png, version 1.4}
+@uref{newsticker-1.3.png, version 1.3},
+@uref{newsticker-1.0.png, version 1.0}.
+@end ifhtml
+
+@node Requirements
+@chapter Requirements
+
+Newsticker can be used with
+@uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version
+21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}. It
+requires an XML-parser (@file{xml.el}) which is part of GNU Emacs. If
+you are using XEmacs you want to get the @file{net-utils} package
+which contains @file{xml.el} for XEmacs.
+
+Newsticker requires a program which can retrieve files via http and
+prints them to stdout. By default Newsticker will use
+@uref{http://www.gnu.org/software/wget/wget.html, wget} for this task.
+
+
+@node Installation
+@chapter Installation
+
+As Newsticker is part of GNU Emacs there is no need to perform any
+installation steps in order to use Newsticker.
+
+However, if you are using imenu, which allows for navigating with the
+help of a menu, you should add the following to your Emacs startup file
+(@file{~/.emacs}).
+
+@lisp
+(add-hook 'newsticker-mode-hook 'imenu-add-menubar-index)
+@end lisp
+
+That's it.
+
+@node Usage
+@chapter Usage
+
+@findex newsticker-show-news
+The command @code{newsticker-show-news} will display all available
+headlines in a special buffer, called @samp{*newsticker*}. It will
+also start the asynchronous download of headlines. The modeline in
+the @samp{*newsticker*} buffer informs whenever new headlines have
+arrived. Clicking mouse-button 2 or pressing RET in this buffer on a
+headline will call @code{browse-url} to load the corresponding news
+story in your favourite web browser.
+
+@findex newsticker-start-ticker
+@findex newsticker-stop-ticker
+The scrolling, or flashing of headlines in the echo area, can be
+started with the command @code{newsticker-start-ticker}. It can be
+stopped with @code{newsticker-stop-ticker}.
+
+@findex newsticker-start
+@findex newsticker-stop
+If you just want to start the periodic download of headlines use the
+command @code{newsticker-start}. Calling @code{newsticker-stop} will
+stop the periodic download, but will call
+@code{newsticker-stop-ticker} as well.
+
+@node Configuration
+@chapter Configuration
+
+All Newsticker options are customizable, i.e. they can be changed with
+Emacs customization methods: Call the command
+@code{customize-group} and enter @samp{newsticker} for the customization
+group.
+
+All Newsticker options have reasonable default values, so that in most
+cases it is not necessary to customize settings before starting Newsticker
+for the first time.
+
+Newsticker options are organized in the following groups.
+
+@itemize
+
+@item
+@code{newsticker-feed} contains options that define which news
+feeds are retrieved and how this is done.
+
+@itemize
+@item
+@vindex newsticker-url-list
+@code{newsticker-url-list} defines the list of headlines which are
+retrieved.
+@item
+@vindex newsticker-retrieval-interval
+@code{newsticker-retrieval-interval} defines how often headlines
+are retrieved.
+@end itemize
+
+@item
+@code{newsticker-headline-processing} contains options that define
+how the retrieved headlines are processed.
+
+@itemize
+@item
+@vindex newsticker-keep-obsolete-items
+@code{newsticker-keep-obsolete-items} decides whether unread
+headlines that have been removed from the feed are kept in the
+Newsticker cache.
+@end itemize
+
+@item
+@code{newsticker-layout} contains options that define how the
+buffer for reading news headlines is formatted.
+
+@itemize
+@item
+@vindex newsticker-heading-format
+@code{newsticker-item-format} defines how the title of a headline
+is formatted.
+@end itemize
+
+@item
+@code{newsticker-ticker} contains options that define how headlines
+are shown in the echo area.
+
+@itemize
+@item
+@vindex newsticker-display-interval
+@vindex newsticker-scroll-smoothly
+@code{newsticker-display-interval} and
+@code{newsticker-scroll-smoothly} define how headlines are shown in
+the echo area.
+@end itemize
+
+@item
+@code{newsticker-hooks} contains options for hooking other Emacs
+commands to newsticker functions.
+@itemize
+@item
+@vindex newsticker-new-item-functions
+@code{newsticker-new-item-functions} allows for automatic
+processing of headlines. See `newsticker-download-images', and
+`newsticker-download-enclosures' for sample functions.
+@end itemize
+
+@item
+@code{newsticker-miscellaneous} contains other Newsticker options.
+
+@end itemize
+
+Please have a look at the customization buffers for the complete list
+of options.
+
+@node Remarks
+@chapter Remarks
+
+This newsticker is designed do its job silently in the background
+without disturbing you. However, it is probably impossible to prevent
+such a tool from slightly attenuating your Editor's responsiveness
+every once in a while.
+
+Byte-compiling newsticker.el is recommended.
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@bye
+
+
+
+@ignore
+ arch-tag: 7a4de539-117c-4658-b799-0b9e3d0ccec0
+@end ignore
--- /dev/null
+\input texinfo
+@c %**start of header
+@setfilename ../info/org
+@settitle Org Mode Manual
+
+@set VERSION 5.07
+@set DATE August 2007
+
+@dircategory Emacs
+@direntry
+* Org Mode: (org). Outline-based notes management and organizer
+@end direntry
+
+@c Version and Contact Info
+@set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/org/,maintainers webpage}
+@set AUTHOR Carsten Dominik
+@set MAINTAINER Carsten Dominik
+@set MAINTAINEREMAIL @email{dominik at science dot uva dot nl}
+@set MAINTAINERCONTACT @uref{mailto:dominik at science dot uva dot nl,contact the maintainer}
+@c %**end of header
+@finalout
+
+@c Macro definitions
+
+@c Subheadings inside a table.
+@macro tsubheading{text}
+@ifinfo
+@subsubheading \text\
+@end ifinfo
+@ifnotinfo
+@item @b{\text\}
+@end ifnotinfo
+@end macro
+
+@copying
+This manual is for Org-mode (version @value{VERSION}).
+
+Copyright @copyright{} 2004, 2005, 2006, 2007 Free Software Foundation
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License.''
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+@end quotation
+@end copying
+
+@titlepage
+@title Org Mode Manual
+
+@subtitle Release @value{VERSION}
+@author by Carsten Dominik
+
+@c The following two commands start the copyright page.
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@c Output the table of contents at the beginning.
+@contents
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top Org Mode Manual
+
+@insertcopying
+@end ifnottex
+
+@menu
+* Introduction:: Getting started
+* Document structure:: A tree works like your brain
+* Tables:: Pure magic for quick formatting
+* Hyperlinks:: Notes in context
+* TODO items:: Every tree branch can be a TODO item
+* Tags:: Tagging headlines and matching sets of tags
+* Properties and columns::
+* Timestamps:: Assign date and time to items
+* Agenda views:: Collecting information into views
+* Embedded LaTeX:: LaTeX fragments and formulas
+* Exporting:: Sharing and publishing of notes
+* Publishing:: Create a web site of linked Org-mode files
+* Miscellaneous:: All the rest which did not fit elsewhere
+* Extensions and Hacking:: It is possible to write add-on code
+* History and Acknowledgments:: How Org-mode came into being
+* Index:: The fast road to specific information
+* Key Index:: Key bindings and where they are described
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Summary:: Brief summary of what Org-mode does
+* Installation:: How to install a downloaded version of Org-mode
+* Activation:: How to activate Org-mode for certain buffers.
+* Feedback:: Bug reports, ideas, patches etc.
+
+Document Structure
+
+* Outlines:: Org-mode is based on outline-mode
+* Headlines:: How to typeset org-tree headlines
+* Visibility cycling:: Show and hide, much simplified
+* Motion:: Jumping to other headlines
+* Structure editing:: Changing sequence and level of headlines
+* Archiving:: Move done task trees to a different place
+* Sparse trees:: Matches embedded in context
+* Plain lists:: Additional structure within an entry
+* Drawers:: Tucking stuff away
+* orgstruct-mode:: Structure editing outside Org-mode
+
+Archiving
+
+* ARCHIVE tag:: Marking a tree as inactive
+* Moving subtrees:: Moving a tree to an archive file
+
+Tables
+
+* Built-in table editor:: Simple tables
+* Narrow columns:: Stop wasting space in tables
+* Column groups:: Grouping to trigger vertical lines
+* orgtbl-mode:: The table editor as minor mode
+* The spreadsheet:: The table editor has spreadsheet capabilities.
+
+The spreadsheet
+
+* References:: How to refer to another field or range
+* Formula syntax for Calc:: Using Calc to compute stuff
+* Formula syntax for Lisp:: Writing formulas in Emacs Lisp
+* Field formulas:: Formulas valid for a single field
+* Column formulas:: Formulas valid for an entire column
+* Editing and debugging formulas:: Fixing formulas
+* Updating the table:: Recomputing all dependent fields
+* Advanced features:: Field names, parameters and automatic recalc
+
+Hyperlinks
+
+* Link format:: How links in Org-mode are formatted
+* Internal links:: Links to other places in the current file
+* External links:: URL-like links to the world
+* Handling links:: Creating, inserting and following
+* Using links outside Org-mode:: Linking from my C source code?
+* Link abbreviations:: Shortcuts for writing complex links
+* Search options:: Linking to a specific location
+* Custom searches:: When the default search is not enough
+* Remember:: Org-trees store quick notes
+
+Internal links
+
+* Radio targets:: Make targets trigger links in plain text.
+
+Remember
+
+* Setting up remember:: Some code for .emacs to get things going
+* Remember templates:: Define the outline of different note types
+* Storing notes:: Directly get the note to where it belongs
+
+TODO items
+
+* TODO basics:: Marking and displaying TODO entries
+* TODO extensions:: Workflow and assignments
+* Priorities:: Some things are more important than others
+* Breaking down tasks:: Splitting a task into manageable pieces
+* Checkboxes:: Tick-off lists
+
+Extended use of TODO keywords
+
+* Workflow states:: From TODO to DONE in steps
+* TODO types:: I do this, Fred the rest
+* Multiple sets in one file:: Mixing it all, and still finding your way
+* Per file keywords:: Different files, different requirements
+
+Tags
+
+* Tag inheritance:: Tags use the tree structure of the outline
+* Setting tags:: How to assign tags to a headline
+* Tag searches:: Searching for combinations of tags
+
+Properties and Columns
+
+* Property syntax:: How properties are spelled out
+* Special properties:: Access to other Org-mode features
+* Property searches:: Matching property values
+* Column view:: Tabular viewing and editing
+* Property API:: Properties for Lisp programmers
+
+Column View
+
+* Defining columns:: The COLUMNS format property
+* Using column view:: How to create and use column view
+
+Defining Columns
+
+* Scope of column definitions:: Where defined, where valid?
+* Column attributes:: Appearance and content of a column
+
+Timestamps
+
+* Time stamps:: Assigning a time to a tree entry
+* Creating timestamps:: Commands which insert timestamps
+* Deadlines and scheduling:: Planning your work
+* Progress logging:: Documenting when what work was done.
+
+Creating timestamps
+
+* The date/time prompt:: How org-mode helps you entering date and time
+* Custom time format:: Making dates look differently
+
+Deadlines and Scheduling
+
+* Inserting deadline/schedule:: Planning items
+* Repeated tasks:: Items that show up again and again
+
+Progress Logging
+
+* Closing items:: When was this entry marked DONE?
+* Tracking TODO state changes:: When did the status change?
+* Clocking work time:: When exactly did you work on this item?
+
+Agenda Views
+
+* Agenda files:: Files being searched for agenda information
+* Agenda dispatcher:: Keyboard access to agenda views
+* Built-in agenda views:: What is available out of the box?
+* Presentation and sorting:: How agenda items are prepared for display
+* Agenda commands:: Remote editing of org trees
+* Custom agenda views:: Defining special searches and views
+
+The built-in agenda views
+
+* Weekly/Daily agenda:: The calendar page with current tasks
+* Global TODO list:: All unfinished action items
+* Matching tags and properties:: Structured information with fine-tuned search
+* Timeline:: Time-sorted view for single file
+* Stuck projects:: Find projects you need to review
+
+Presentation and sorting
+
+* Categories:: Not all tasks are equal
+* Time-of-day specifications:: How the agenda knows the time
+* Sorting of agenda items:: The order of things
+
+Custom agenda views
+
+* Storing searches:: Type once, use often
+* Block agenda:: All the stuff you need in a single buffer
+* Setting Options:: Changing the rules
+* Exporting Agenda Views:: Writing agendas to files.
+* Extracting Agenda Information for other programs::
+
+Embedded LaTeX
+
+* Math symbols:: TeX macros for symbols and Greek letters
+* Subscripts and Superscripts:: Simple syntax for raising/lowering text
+* LaTeX fragments:: Complex formulas made easy
+* Processing LaTeX fragments:: Previewing LaTeX processing
+* CDLaTeX mode:: Speed up entering of formulas
+
+Exporting
+
+* ASCII export:: Exporting to plain ASCII
+* HTML export:: Exporting to HTML
+* LaTeX export:: Exporting to LaTeX
+* XOXO export:: Exporting to XOXO
+* iCalendar export:: Exporting in iCalendar format
+* Text interpretation:: How the exporter looks at the file
+
+HTML export
+
+* HTML Export commands:: How to invoke LaTeX export
+* Quoting HTML tags:: Using direct HTML in Org-mode
+* Links:: Transformation of links for HTML
+* Images:: How to include images
+* CSS support:: Changing the appearence of the output
+
+LaTeX export
+
+* LaTeX export commands:: How to invoke LaTeX export
+* Quoting LaTeX code:: Incorporating literal LaTeX code
+
+Text interpretation by the exporter
+
+* Comment lines:: Some lines will not be exported
+* Initial text:: Text before the first headline
+* Footnotes:: Numbers like [1]
+* Enhancing text:: Subscripts, symbols and more
+* Export options:: How to influence the export settings
+
+Publishing
+
+* Configuration:: Defining projects
+* Sample configuration:: Example projects
+* Triggering publication:: Publication commands
+
+Configuration
+
+* Project alist:: The central configuration variable
+* Sources and destinations:: From here to there
+* Selecting files:: What files are part of the project?
+* Publishing action:: Setting the function doing the publishing
+* Publishing options:: Tweaking HTML export
+* Publishing links:: Which links keep working after publishing?
+* Project page index:: Publishing a list of project files
+
+Sample configuration
+
+* Simple example:: One-component publishing
+* Complex example:: A multi-component publishing example
+
+Miscellaneous
+
+* Completion:: M-TAB knows what you need
+* Customization:: Adapting Org-mode to your taste
+* In-buffer settings:: Overview of the #+KEYWORDS
+* The very busy C-c C-c key:: When in doubt, press C-c C-c
+* Clean view:: Getting rid of leading stars in the outline
+* TTY keys:: Using Org-mode on a tty
+* Interaction:: Other Emacs packages
+* Bugs:: Things which do not work perfectly
+
+Interaction with other packages
+
+* Cooperation:: Packages Org-mode cooperates with
+* Conflicts:: Packages that lead to conflicts
+
+Extensions, Hooks and Hacking
+
+* Extensions:: Existing 3rd-part extensions
+* Adding hyperlink types:: New custom link types
+* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
+* Dynamic blocks:: Automatically filled blocks
+* Special agenda views:: Customized views
+* Using the property API:: Writing programs that use entry properties
+
+Tables in arbitrary syntax
+
+* Radio tables:: Sending and receiving
+* A LaTeX example:: Step by step, almost a tutorial
+* Translator functions:: Copy and modify
+
+@end detailmenu
+@end menu
+
+@node Introduction, Document structure, Top, Top
+@chapter Introduction
+@cindex introduction
+
+@menu
+* Summary:: Brief summary of what Org-mode does
+* Installation:: How to install a downloaded version of Org-mode
+* Activation:: How to activate Org-mode for certain buffers.
+* Feedback:: Bug reports, ideas, patches etc.
+@end menu
+
+@node Summary, Installation, Introduction, Introduction
+@section Summary
+@cindex summary
+
+Org-mode is a mode for keeping notes, maintaining TODO lists, and doing
+project planning with a fast and effective plain-text system.
+
+Org-mode develops organizational tasks around NOTES files that contain
+lists or information about projects as plain text. Org-mode is
+implemented on top of outline-mode, which makes it possible to keep the
+content of large files well structured. Visibility cycling and
+structure editing help to work with the tree. Tables are easily created
+with a built-in table editor. Org-mode supports TODO items, deadlines,
+time stamps, and scheduling. It dynamically compiles entries into an
+agenda that utilizes and smoothly integrates much of the Emacs calendar
+and diary. Plain text URL-like links connect to websites, emails,
+Usenet messages, BBDB entries, and any files related to the projects.
+For printing and sharing of notes, an Org-mode file can be exported as a
+structured ASCII file, as HTML, or (todo and agenda items only) as an
+iCalendar file. It can also serve as a publishing tool for a set of
+linked webpages.
+
+An important design aspect that distinguishes Org-mode from for example
+Planner/Muse is that it encourages to store every piece of information
+only once. In Planner, you have project pages, day pages and possibly
+other files, duplicating some information such as tasks. In Org-mode,
+you only have notes files. In your notes you mark entries as tasks,
+label them with tags and timestamps. All necessary lists like a
+schedule for the day, the agenda for a meeting, tasks lists selected by
+tags etc are created dynamically when you need them.
+
+Org-mode keeps simple things simple. When first fired up, it should
+feel like a straightforward, easy to use outliner. Complexity is not
+imposed, but a large amount of functionality is available when you need
+it. Org-mode is a toolbox and can be used in different ways, for
+example as:
+
+@example
+@r{@bullet{} outline extension with visibility cycling and structure editing}
+@r{@bullet{} ASCII system and table editor for taking structured notes}
+@r{@bullet{} ASCII table editor with spreadsheet-like capabilities}
+@r{@bullet{} TODO list editor}
+@r{@bullet{} full agenda and planner with deadlines and work scheduling}
+@r{@bullet{} environment to implement David Allen's GTD system}
+@r{@bullet{} a basic database application}
+@r{@bullet{} simple hypertext system, with HTML export}
+@r{@bullet{} publishing tool to create a set of interlinked webpages}
+@end example
+
+Org-mode's automatic, context sensitive table editor with spreadsheet
+capabilities can be integrated into any major mode by activating the
+minor Orgtbl-mode. Using a translation step, it can be used to maintain
+tables in arbitrary file types, for example in La@TeX{}. The structure
+editing and list creation capabilities can be used outside Org-mode with
+the minor Orgstruct-mode.
+
+@cindex FAQ
+There is a website for Org-mode which provides links to the newest
+version of Org-mode, as well as additional information, frequently asked
+questions (FAQ), links to tutorials etc. This page is located at
+@uref{http://www.astro.uva.nl/~dominik/Tools/org/}.
+
+@page
+
+
+@node Installation, Activation, Summary, Introduction
+@section Installation
+@cindex installation
+@cindex XEmacs
+
+@b{Important:} @i{If Org-mode is part of the Emacs distribution or an
+XEmacs package, please skip this section and go directly to
+@ref{Activation}.}
+
+If you have downloaded Org-mode from the Web, you must take the
+following steps to install it: Go into the Org-mode distribution
+directory and edit the top section of the file @file{Makefile}. You
+must set the name of the Emacs binary (likely either @file{emacs} or
+@file{xemacs}), and the paths to the directories where local Lisp and
+Info files are kept. If you don't have access to the system-wide
+directories, create your own two directories for these files, enter them
+into the Makefile, and make sure Emacs finds the Lisp files by adding
+the following line to @file{.emacs}:
+
+@example
+(setq load-path (cons "~/path/to/lispdir" load-path))
+@end example
+
+@b{XEmacs users now need to install the file @file{noutline.el} from
+the @file{xemacs} subdirectory of the Org-mode distribution. Use the
+command:}
+
+@example
+@b{make install-noutline}
+@end example
+
+@noindent Now byte-compile and install the Lisp files with the shell
+commands:
+
+@example
+make
+make install
+@end example
+
+@noindent If you want to install the info documentation, use this command:
+
+@example
+make install-info
+@end example
+
+@noindent Then add to @file{.emacs}:
+
+@lisp
+;; This line only if org-mode is not part of the X/Emacs distribution.
+(require 'org-install)
+@end lisp
+
+@node Activation, Feedback, Installation, Introduction
+@section Activation
+@cindex activation
+@cindex autoload
+@cindex global keybindings
+@cindex keybindings, global
+
+@iftex
+@b{Important:} @i{If you use copy-and-paste to copy lisp code from the
+PDF documentation as viewed by Acrobat reader to your .emacs file, the
+single quote character comes out incorrectly and the code will not work.
+You need to fix the single quotes by hand, or copy from Info
+documentation.}
+@end iftex
+
+Add the following lines to your @file{.emacs} file. The last two lines
+define @emph{global} keys for the commands @command{org-store-link} and
+@command{org-agenda} - please choose suitable keys yourself.
+
+@lisp
+;; The following lines are always needed. Choose your own keys.
+(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
+(global-set-key "\C-cl" 'org-store-link)
+(global-set-key "\C-ca" 'org-agenda)
+@end lisp
+
+Furthermore, you must activate @code{font-lock-mode} in org-mode
+buffers, because significant functionality depends on font-locking being
+active. You can do this with either one of the following two lines
+(XEmacs user must use the second option):
+@lisp
+(global-font-lock-mode 1) ; for all buffers
+(add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only
+@end lisp
+
+@cindex org-mode, turning on
+With this setup, all files with extension @samp{.org} will be put
+into Org-mode. As an alternative, make the first line of a file look
+like this:
+
+@example
+MY PROJECTS -*- mode: org; -*-
+@end example
+
+@noindent which will select Org-mode for this buffer no matter what
+the file's name is. See also the variable
+@code{org-insert-mode-line-in-empty-file}.
+
+@node Feedback, , Activation, Introduction
+@section Feedback
+@cindex feedback
+@cindex bug reports
+@cindex maintainer
+@cindex author
+
+If you find problems with Org-mode, or if you have questions, remarks,
+or ideas about it, please contact the maintainer @value{MAINTAINER} at
+@value{MAINTAINEREMAIL}.
+
+For bug reports, please provide as much information as possible,
+including the version information of Emacs (@kbd{C-h v emacs-version
+@key{RET}}) and Org-mode (@kbd{C-h v org-version @key{RET}}), as well as
+the Org-mode related setup in @file{.emacs}. If an error occurs, a
+backtrace can be very useful (see below on how to create one). Often a
+small example file helps, along with clear information about:
+
+@enumerate
+@item What exactly did you do?
+@item What did you expect to happen?
+@item What happened instead?
+@end enumerate
+@noindent Thank you for helping to improve this mode.
+
+@subsubheading How to create a useful backtrace
+
+@cindex backtrace of an error
+If working with Org-mode produces an error with a message you don't
+understand, you may have hit a bug. The best way to report this is by
+providing, in addition to what was mentioned above, a @emph{Backtrace}.
+This is information from the built-in debugger about where and how the
+error occurred. Here is how to produce a useful backtrace:
+
+@enumerate
+@item
+Start a fresh Emacs or XEmacs, and make sure that it will load the
+original Lisp code in @file{org.el} instead of the compiled version in
+@file{org.elc}. The backtrace contains much more information if it is
+produced with uncompiled code. To do this, either rename @file{org.elc}
+to something else before starting Emacs, or ask Emacs explicitly to load
+@file{org.el} by using the command line
+@example
+emacs -l /path/to/org.el
+@end example
+@item
+Go to the @code{Options} menu and select @code{Enter Debugger on Error}
+(XEmacs has this option in the @code{Troubleshooting} sub-menu).
+@item
+Do whatever you have to do to hit the error. Don't forget to
+document the steps you take.
+@item
+When you hit the error, a @file{*Backtrace*} buffer will appear on the
+screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and
+attach it to your bug report.
+@end enumerate
+
+@node Document structure, Tables, Introduction, Top
+@chapter Document Structure
+@cindex document structure
+@cindex structure of document
+
+Org-mode is based on outline mode and provides flexible commands to
+edit the structure of the document.
+
+@menu
+* Outlines:: Org-mode is based on outline-mode
+* Headlines:: How to typeset org-tree headlines
+* Visibility cycling:: Show and hide, much simplified
+* Motion:: Jumping to other headlines
+* Structure editing:: Changing sequence and level of headlines
+* Archiving:: Move done task trees to a different place
+* Sparse trees:: Matches embedded in context
+* Plain lists:: Additional structure within an entry
+* Drawers:: Tucking stuff away
+* orgstruct-mode:: Structure editing outside Org-mode
+@end menu
+
+@node Outlines, Headlines, Document structure, Document structure
+@section Outlines
+@cindex outlines
+@cindex outline-mode
+
+Org-mode is implemented on top of outline-mode. Outlines allow a
+document to be organized in a hierarchical structure, which (at least
+for me) is the best representation of notes and thoughts. An overview
+of this structure is achieved by folding (hiding) large parts of the
+document to show only the general document structure and the parts
+currently being worked on. Org-mode greatly simplifies the use of
+outlines by compressing the entire show/hide functionality into a single
+command @command{org-cycle}, which is bound to the @key{TAB} key.
+
+@node Headlines, Visibility cycling, Outlines, Document structure
+@section Headlines
+@cindex headlines
+@cindex outline tree
+
+Headlines define the structure of an outline tree. The headlines in
+Org-mode start with one or more stars, on the left margin@footnote{See
+the variable @code{org-special-ctrl-a/e} to configure special behavior
+of @kbd{C-a} and @kbd{C-e} in headlines.}. For example:
+
+@example
+* Top level headline
+** Second level
+*** 3rd level
+ some text
+*** 3rd level
+ more text
+
+* Another top level headline
+@end example
+
+@noindent Some people find the many stars too noisy and would prefer an
+outline that has whitespace followed by a single star as headline
+starters. @ref{Clean view} describes a setup to realize this.
+
+An empty line after the end of a subtree is considered part of it and
+will be hidden when the subtree is folded. However, if you leave at
+least two empty lines, one empty line will remain visible after folding
+the subtree, in order to structure the collapsed view. See the
+variable @code{org-cycle-separator-lines} to modify this behavior.
+
+@node Visibility cycling, Motion, Headlines, Document structure
+@section Visibility cycling
+@cindex cycling, visibility
+@cindex visibility cycling
+@cindex trees, visibility
+@cindex show hidden text
+@cindex hide text
+
+Outlines make it possible to hide parts of the text in the buffer.
+Org-mode uses just two commands, bound to @key{TAB} and
+@kbd{S-@key{TAB}} to change the visibility in the buffer.
+
+@cindex subtree visibility states
+@cindex subtree cycling
+@cindex folded, subtree visibility state
+@cindex children, subtree visibility state
+@cindex subtree, subtree visibility state
+@table @kbd
+@kindex @key{TAB}
+@item @key{TAB}
+@emph{Subtree cycling}: Rotate current subtree among the states
+
+@example
+,-> FOLDED -> CHILDREN -> SUBTREE --.
+'-----------------------------------'
+@end example
+
+The cursor must be on a headline for this to work@footnote{see, however,
+the option @code{org-cycle-emulate-tab}.}. When the cursor is at the
+beginning of the buffer and the first line is not a headline, then
+@key{TAB} actually runs global cycling (see below)@footnote{see the
+option @code{org-cycle-global-at-bob}.}. Also when called with a prefix
+argument (@kbd{C-u @key{TAB}}), global cycling is invoked.
+
+@cindex global visibility states
+@cindex global cycling
+@cindex overview, global visibility state
+@cindex contents, global visibility state
+@cindex show all, global visibility state
+@kindex S-@key{TAB}
+@item S-@key{TAB}
+@itemx C-u @key{TAB}
+@emph{Global cycling}: Rotate the entire buffer among the states
+
+@example
+,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
+'--------------------------------------'
+@end example
+
+When @kbd{S-@key{TAB}} is called with a numerical prefix N, the CONTENTS
+view up to headlines of level N will be shown.
+Note that inside tables, @kbd{S-@key{TAB}} jumps to the previous field.
+
+@cindex show all, command
+@kindex C-c C-a
+@item C-c C-a
+Show all.
+@kindex C-c C-r
+@item C-c C-r
+Reveal context around point, showing the current entry, the following
+heading and the hierarchy above. Useful for working near a location
+exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda
+command (@pxref{Agenda commands}). With prefix arg show, on each
+level, all sibling headings.
+@kindex C-c C-x b
+@item C-c C-x b
+Show the current subtree in an indirect buffer@footnote{The indirect
+buffer
+@ifinfo
+(@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual})
+@end ifinfo
+@ifnotinfo
+(see the Emacs manual for more information about indirect buffers)
+@end ifnotinfo
+will contain the entire buffer, but will be narrowed to the current
+tree. Editing the indirect buffer will also change the original buffer,
+but without affecting visibility in that buffer.}. With numerical
+prefix ARG, go up to this level and then take that tree. If ARG is
+negative, go up that many levels. With @kbd{C-u} prefix, do not remove
+the previously used indirect buffer.
+@end table
+
+When Emacs first visits an Org-mode file, the global state is set to
+OVERVIEW, i.e. only the top level headlines are visible. This can be
+configured through the variable @code{org-startup-folded}, or on a
+per-file basis by adding one of the following lines anywhere in the
+buffer:
+
+@example
+#+STARTUP: overview
+#+STARTUP: content
+#+STARTUP: showall
+@end example
+
+@node Motion, Structure editing, Visibility cycling, Document structure
+@section Motion
+@cindex motion, between headlines
+@cindex jumping, to headlines
+@cindex headline navigation
+The following commands jump to other headlines in the buffer.
+
+@table @kbd
+@kindex C-c C-n
+@item C-c C-n
+Next heading.
+@kindex C-c C-p
+@item C-c C-p
+Previous heading.
+@kindex C-c C-f
+@item C-c C-f
+Next heading same level.
+@kindex C-c C-b
+@item C-c C-b
+Previous heading same level.
+@kindex C-c C-u
+@item C-c C-u
+Backward to higher level heading.
+@kindex C-c C-j
+@item C-c C-j
+Jump to a different place without changing the current outline
+visibility. Shows the document structure in a temporary buffer, where
+you can use the following keys to find your destination:
+@example
+@key{TAB} @r{Cycle visibility.}
+@key{down} / @key{up} @r{Next/previous visible headline.}
+n / p @r{Next/previous visible headline.}
+f / b @r{Next/previous headline same level.}
+u @r{One level up.}
+0-9 @r{Digit argument.}
+@key{RET} @r{Select this location.}
+@end example
+@end table
+
+@node Structure editing, Archiving, Motion, Document structure
+@section Structure editing
+@cindex structure editing
+@cindex headline, promotion and demotion
+@cindex promotion, of subtrees
+@cindex demotion, of subtrees
+@cindex subtree, cut and paste
+@cindex pasting, of subtrees
+@cindex cutting, of subtrees
+@cindex copying, of subtrees
+@cindex subtrees, cut and paste
+
+@table @kbd
+@kindex M-@key{RET}
+@item M-@key{RET}
+Insert new heading with same level as current. If the cursor is in a
+plain list item, a new item is created (@pxref{Plain lists}). To force
+creation of a new headline, use a prefix arg, or first press @key{RET}
+to get to the beginning of the next line. When this command is used in
+the middle of a line, the line is split and the rest of the line becomes
+the new headline. If the command is used at the beginning of a
+headline, the new headline is created before the current line. If at
+the beginning of any other line, the content of that line is made the
+new heading. If the command is used at the end of a folded subtree
+(i.e. behind the ellipses at the end of a headline), then a headline
+like the current one will be inserted after the end of the subtree.
+@kindex M-S-@key{RET}
+@item M-S-@key{RET}
+Insert new TODO entry with same level as current heading.
+@kindex M-@key{left}
+@item M-@key{left}
+Promote current heading by one level.
+@kindex M-@key{right}
+@item M-@key{right}
+Demote current heading by one level.
+@kindex M-S-@key{left}
+@item M-S-@key{left}
+Promote the current subtree by one level.
+@kindex M-S-@key{right}
+@item M-S-@key{right}
+Demote the current subtree by one level.
+@kindex M-S-@key{up}
+@item M-S-@key{up}
+Move subtree up (swap with previous subtree of same
+level).
+@kindex M-S-@key{down}
+@item M-S-@key{down}
+Move subtree down (swap with next subtree of same level).
+@kindex C-c C-x C-w
+@kindex C-c C-x C-k
+@item C-c C-x C-w
+@itemx C-c C-x C-k
+Kill subtree, i.e. remove it from buffer but save in kill ring.
+@kindex C-c C-x M-w
+@item C-c C-x M-w
+Copy subtree to kill ring.
+@kindex C-c C-x C-y
+@item C-c C-x C-y
+Yank subtree from kill ring. This does modify the level of the subtree to
+make sure the tree fits in nicely at the yank position. The yank
+level can also be specified with a prefix arg, or by yanking after a
+headline marker like @samp{****}.
+@kindex C-c ^
+@item C-c ^
+Sort same-level entries. When there is an active region, all entries in
+the region will be sorted. Otherwise the children of the current
+headline are sorted. The command prompts for the sorting method, which
+can be alphabetically, numerically, by time (using the first time stamp
+in each entry), by priority, and each of these in reverse order. With a
+@kbd{C-u} prefix, sorting will be case-sensitive. With two @kbd{C-u
+C-u} prefixes, duplicate entries will also be removed.
+@end table
+
+@cindex region, active
+@cindex active region
+@cindex transient-mark-mode
+When there is an active region (transient-mark-mode), promotion and
+demotion work on all headlines in the region. To select a region of
+headlines, it is best to place both point and mark at the beginning of a
+line, mark at the beginning of the first headline, and point at the line
+just after the last headline to change. Note that when the cursor is
+inside a table (@pxref{Tables}), the Meta-Cursor keys have different
+functionality.
+
+@node Archiving, Sparse trees, Structure editing, Document structure
+@section Archiving
+@cindex archiving
+
+When a project represented by a (sub)tree is finished, you may want
+to move the tree out of the way and to stop it from contributing to the
+agenda. Org-mode knows two ways of archiving. You can mark a tree with
+the ARCHIVE tag, or you can move an entire (sub)tree to a different
+location.
+
+@menu
+* ARCHIVE tag:: Marking a tree as inactive
+* Moving subtrees:: Moving a tree to an archive file
+@end menu
+
+@node ARCHIVE tag, Moving subtrees, Archiving, Archiving
+@subsection The ARCHIVE tag
+@cindex internal archiving
+
+A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at
+its location in the outline tree, but behaves in the following way:
+@itemize @minus
+@item
+It does not open when you attempt to do so with a visibility cycling
+command (@pxref{Visibility cycling}). You can force cycling archived
+subtrees with @kbd{C-@key{TAB}}, or by setting the option
+@code{org-cycle-open-archived-trees}. Also normal outline commands like
+@code{show-all} will open archived subtrees.
+@item
+During sparse tree construction (@pxref{Sparse trees}), matches in
+archived subtrees are not exposed, unless you configure the option
+@code{org-sparse-tree-open-archived-trees}.
+@item
+During agenda view construction (@pxref{Agenda views}), the content of
+archived trees is ignored unless you configure the option
+@code{org-agenda-skip-archived-trees}.
+@item
+Archived trees are not exported (@pxref{Exporting}), only the headline
+is. Configure the details using the variable
+@code{org-export-with-archived-trees}.
+@end itemize
+
+The following commands help managing the ARCHIVE tag:
+
+@table @kbd
+@kindex C-c C-x C-a
+@item C-c C-x C-a
+Toggle the ARCHIVE tag for the current headline. When the tag is set,
+the headline changes to a shadowish face, and the subtree below it is
+hidden.
+@kindex C-u C-c C-x C-a
+@item C-u C-c C-x C-a
+Check if any direct children of the current headline should be archived.
+To do this, each subtree is checked for open TODO entries. If none are
+found, the command offers to set the ARCHIVE tag for the child. If the
+cursor is @emph{not} on a headline when this command is invoked, the
+level 1 trees will be checked.
+@kindex C-@kbd{TAB}
+@item C-@kbd{TAB}
+Cycle a tree even if it is tagged with ARCHIVE.
+@end table
+
+@node Moving subtrees, , ARCHIVE tag, Archiving
+@subsection Moving subtrees
+@cindex external archiving
+
+Once an entire project is finished, you may want to move it to a
+different location, either in the current file, or even in a different
+file, the archive file.
+
+@table @kbd
+@kindex C-c C-x C-s
+@item C-c C-x C-s
+Archive the subtree starting at the cursor position to the location
+given by @code{org-archive-location}. Context information that could be
+lost like the file name, the category, inherited tags, and the todo
+state will be store as properties in the entry.
+@kindex C-u C-c C-x C-s
+@item C-u C-c C-x C-s
+Check if any direct children of the current headline could be moved to
+the archive. To do this, each subtree is checked for open TODO entries.
+If none are found, the command offers to move it to the archive
+location. If the cursor is @emph{not} on a headline when this command
+is invoked, the level 1 trees will be checked.
+@end table
+
+@cindex archive locations
+The default archive location is a file in the same directory as the
+current file, with the name derived by appending @file{_archive} to the
+current file name. For information and examples on how to change this,
+see the documentation string of the variable
+@code{org-archive-location}. There is also an in-buffer option for
+setting this variable, for example
+
+@example
+#+ARCHIVE: %s_done::
+@end example
+
+@noindent
+You may have several such lines in the buffer, they will then be valid
+for the entries following the line (the first will also apply to any
+text before it).
+
+@node Sparse trees, Plain lists, Archiving, Document structure
+@section Sparse trees
+@cindex sparse trees
+@cindex trees, sparse
+@cindex folding, sparse trees
+@cindex occur, command
+
+An important feature of Org-mode is the ability to construct
+@emph{sparse trees} for selected information in an outline tree. A
+sparse tree means that the entire document is folded as much as
+possible, but the selected information is made visible along with the
+headline structure above it@footnote{See also the variables
+@code{org-show-hierarchy-above}, @code{org-show-following-heading}, and
+@code{org-show-siblings} for detailed control on how much context is
+shown around each match.}. Just try it out and you will see immediately
+how it works.
+
+Org-mode contains several commands creating such trees. The most
+basic one is @command{org-occur}:
+
+@table @kbd
+@kindex C-c /
+@item C-c /
+Occur. Prompts for a regexp and shows a sparse tree with all matches.
+If the match is in a headline, the headline is made visible. If the
+match is in the body of an entry, headline and body are made visible.
+In order to provide minimal context, also the full hierarchy of
+headlines above the match is shown, as well as the headline following
+the match. Each match is also highlighted; the highlights disappear
+when the buffer is changed by an editing command, or by pressing
+@kbd{C-c C-c}. When called with a @kbd{C-u} prefix argument, previous
+highlights are kept, so several calls to this command can be stacked.
+@end table
+@noindent
+For frequently used sparse trees of specific search strings, you can
+use the variable @code{org-agenda-custom-commands} to define fast
+keyboard access to specific sparse trees. These commands will then be
+accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
+For example:
+
+@lisp
+(setq org-agenda-custom-commands
+ '(("f" occur-tree "FIXME")))
+@end lisp
+
+@noindent will define the key @kbd{C-c a f} as a shortcut for creating
+a sparse tree matching the string @samp{FIXME}.
+
+Other commands use sparse trees as well. For example @kbd{C-c
+C-v} creates a sparse TODO tree (@pxref{TODO basics}).
+
+@kindex C-c C-e v
+@cindex printing sparse trees
+@cindex visible text, printing
+To print a sparse tree, you can use the Emacs command
+@code{ps-print-buffer-with-faces} which does not print invisible parts
+of the document @footnote{This does not work under XEmacs, because
+XEmacs uses selective display for outlining, not text properties.}.
+Or you can use the command @kbd{C-c C-e v} to export only the visible
+part of the document and print the resulting file.
+
+@node Plain lists, Drawers, Sparse trees, Document structure
+@section Plain lists
+@cindex plain lists
+@cindex lists, plain
+@cindex lists, ordered
+@cindex ordered lists
+
+Within an entry of the outline tree, hand-formatted lists can provide
+additional structure. They also provide a way to create lists of
+checkboxes (@pxref{Checkboxes}). Org-mode supports editing such lists,
+and the HTML exporter (@pxref{Exporting}) does parse and format them.
+
+Org-mode knows ordered and unordered lists. Unordered list items start
+with @samp{-}, @samp{+}, or @samp{*}@footnote{When using @samp{*} as a
+bullet, lines must be indented or they will be seen as top-level
+headlines. Also, when you are hiding leading stars to get a clean
+outline view, plain list items starting with a star are visually
+indistinguishable from true headlines. In short: even though @samp{*}
+is supported, it may be better not to use it for plain list items.} as
+bullets. Ordered list items start with @samp{1.} or @samp{1)}. Items
+belonging to the same list must have the same indentation on the first
+line. In particular, if an ordered list reaches number @samp{10.}, then
+the 2--digit numbers must be written left-aligned with the other numbers
+in the list. Indentation also determines the end of a list item. It
+ends before the next line that is indented like the bullet/number, or
+less. Empty lines are part of the previous item, so you can have
+several paragraphs in one item. If you would like an empty line to
+terminate all currently open plain lists, configure the variable
+@code{org-empty-line-terminates-plain-lists}. Here is an example:
+
+@example
+@group
+** Lord of the Rings
+ My favorite scenes are (in this order)
+ 1. The attack of the Rohirrim
+ 2. Eowyns fight with the witch king
+ + this was already my favorite scene in the book
+ + I really like Miranda Otto.
+ 3. Peter Jackson being shot by Legolas
+ - on DVD only
+ He makes a really funny face when it happens.
+ But in the end, not individual scenes matter but the film as a whole.
+@end group
+@end example
+
+Org-mode supports these lists by tuning filling and wrapping commands to
+deal with them correctly@footnote{Org-mode only changes the filling
+settings for Emacs. For XEmacs, you should use Kyle E. Jones'
+@file{filladapt.el}. To turn this on, put into @file{.emacs}:
+@code{(require 'filladapt)}}.
+
+The following commands act on items when the cursor is in the first line
+of an item (the line with the bullet or number).
+
+@table @kbd
+@kindex @key{TAB}
+@item @key{TAB}
+Items can be folded just like headline levels if you set the variable
+@code{org-cycle-include-plain-lists}. The level of an item is then
+given by the indentation of the bullet/number. Items are always
+subordinate to real headlines, however; the hierarchies remain
+completely separated.
+
+If @code{org-cycle-include-plain-lists} has not been set, @key{TAB}
+fixes the indentation of the curent line in a heuristic way.
+@kindex M-@key{RET}
+@item M-@key{RET}
+Insert new item at current level. With prefix arg, force a new heading
+(@pxref{Structure editing}). If this command is used in the middle of a
+line, the line is @emph{split} and the rest of the line becomes the new
+item. If this command is executed in the @emph{whitespace before a bullet or
+number}, the new item is created @emph{before} the current item. If the
+command is executed in the white space before the text that is part of
+an item but does not contain the bullet, a bullet is added to the
+current line.
+@kindex M-S-@key{RET}
+@item M-S-@key{RET}
+Insert a new item with a checkbox (@pxref{Checkboxes}).
+@kindex S-@key{up}
+@kindex S-@key{down}
+@item S-@key{up}
+@itemx S-@key{down}
+Jump to the previous/next item in the current list.
+@kindex M-S-@key{up}
+@kindex M-S-@key{down}
+@item M-S-@key{up}
+@itemx M-S-@key{down}
+Move the item including subitems up/down (swap with previous/next item
+of same indentation). If the list is ordered, renumbering is
+automatic.
+@kindex M-S-@key{left}
+@kindex M-S-@key{right}
+@item M-S-@key{left}
+@itemx M-S-@key{right}
+Decrease/increase the indentation of the item, including subitems.
+Initially, the item tree is selected based on current indentation.
+When these commands are executed several times in direct succession,
+the initially selected region is used, even if the new indentation
+would imply a different hierarchy. To use the new hierarchy, break
+the command chain with a cursor motion or so.
+@kindex C-c C-c
+@item C-c C-c
+If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
+state of the checkbox. If not, make this command makes sure that all
+the items on this list level use the same bullet. Furthermore, if this
+is an ordered list, make sure the numbering is ok.
+@kindex C-c -
+@item C-c -
+Cycle the entire list level through the different itemize/enumerate
+bullets (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}).
+With prefix arg, select the nth bullet from this list.
+@end table
+
+@node Drawers, orgstruct-mode, Plain lists, Document structure
+@section Drawers
+@cindex drawers
+@cindex visibility cycling, drawers
+
+Sometimes you want to keep information associated with an entry, but you
+normally don't want to see it. For this, Org-mode has @emph{drawers}.
+Drawers need to be configured with the variable @code{org-drawers}, and
+look like this:
+
+@example
+** This is a headline
+ Still outside the drawer
+ :DRAWERNAME:
+ This is inside the drawer.
+ :END:
+ After the drawer.
+@end example
+
+Visibility cycling (@pxref{Visibility cycling}) on the headline will
+hide and show the entry, but keep the drawer collapsed to a single line.
+In order to look inside the drawer, you need to move the cursor to the
+drawer line and press @key{TAB} there. Org-mode uses a drawer for
+storing properties (@pxref{Properties and columns}).
+
+@node orgstruct-mode, , Drawers, Document structure
+@section The Orgstruct minor mode
+@cindex orgstruct-mode
+@cindex minor mode for structure editing
+
+If you like the intuitive way the Org-mode structure editing and list
+formatting works, you might want to use these commands in other modes
+like text-mode or mail-mode as well. The minor mode Orgstruct-mode
+makes this possible. You can always toggle the mode with @kbd{M-x
+orgstruct-mode}. To turn it on by default, for example in mail mode,
+use
+
+@lisp
+(add-hook 'mail-mode-hook 'turn-on-orgstruct)
+@end lisp
+
+When this mode is active and the cursor is on a line that looks to
+Org-mode like a headline of the first line of a list item, most
+structure editing commands will work, even if the same keys normally
+have different functionality in the major mode you are using. If the
+cursor is not in one of those special lines, Orgstruct-mode lurks
+silently in the shadow.
+
+@node Tables, Hyperlinks, Document structure, Top
+@chapter Tables
+@cindex tables
+@cindex editing tables
+
+Org-mode has a very fast and intuitive table editor built-in.
+Spreadsheet-like calculations are supported in connection with the
+Emacs @file{calc} package.
+
+@menu
+* Built-in table editor:: Simple tables
+* Narrow columns:: Stop wasting space in tables
+* Column groups:: Grouping to trigger vertical lines
+* orgtbl-mode:: The table editor as minor mode
+* The spreadsheet:: The table editor has spreadsheet capabilities.
+@end menu
+
+@node Built-in table editor, Narrow columns, Tables, Tables
+@section The built-in table editor
+@cindex table editor, built-in
+
+Org-mode makes it easy to format tables in plain ASCII. Any line with
+@samp{|} as the first non-whitespace character is considered part of a
+table. @samp{|} is also the column separator. A table might look like
+this:
+
+@example
+| Name | Phone | Age |
+|-------+-------+-----|
+| Peter | 1234 | 17 |
+| Anna | 4321 | 25 |
+@end example
+
+A table is re-aligned automatically each time you press @key{TAB} or
+@key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to
+the next field (@key{RET} to the next row) and creates new table rows
+at the end of the table or before horizontal lines. The indentation
+of the table is set by the first line. Any line starting with
+@samp{|-} is considered as a horizontal separator line and will be
+expanded on the next re-align to span the whole table width. So, to
+create the above table, you would only type
+
+@example
+|Name|Phone|Age|
+|-
+@end example
+
+@noindent and then press @key{TAB} to align the table and start filling in
+fields.
+
+When typing text into a field, Org-mode treats @key{DEL},
+@key{Backspace}, and all character keys in a special way, so that
+inserting and deleting avoids shifting other fields. Also, when
+typing @emph{immediately after the cursor was moved into a new field
+with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
+field is automatically made blank. If this behavior is too
+unpredictable for you, configure the variables
+@code{org-enable-table-editor} and @code{org-table-auto-blank-field}.
+
+@table @kbd
+@tsubheading{Creation and conversion}
+@kindex C-c |
+@item C-c |
+Convert the active region to table. If every line contains at least one
+TAB character, the function assumes that the material is tab separated.
+If not, lines are split at whitespace into fields. You can use a prefix
+argument to indicate the minimum number of consecutive spaces required
+to identify a field separator (default: just one).@*
+If there is no active region, this command creates an empty Org-mode
+table. But it's easier just to start typing, like
+@kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
+
+@tsubheading{Re-aligning and field motion}
+@kindex C-c C-c
+@item C-c C-c
+Re-align the table without moving the cursor.
+@c
+@kindex @key{TAB}
+@item @key{TAB}
+Re-align the table, move to the next field. Creates a new row if
+necessary.
+@c
+@kindex S-@key{TAB}
+@item S-@key{TAB}
+Re-align, move to previous field.
+@c
+@kindex @key{RET}
+@item @key{RET}
+Re-align the table and move down to next row. Creates a new row if
+necessary. At the beginning or end of a line, @key{RET} still does
+NEWLINE, so it can be used to split a table.
+
+@tsubheading{Column and row editing}
+@kindex M-@key{left}
+@kindex M-@key{right}
+@item M-@key{left}
+@itemx M-@key{right}
+Move the current column left/right.
+@c
+@kindex M-S-@key{left}
+@item M-S-@key{left}
+Kill the current column.
+@c
+@kindex M-S-@key{right}
+@item M-S-@key{right}
+Insert a new column to the left of the cursor position.
+@c
+@kindex M-@key{up}
+@kindex M-@key{down}
+@item M-@key{up}
+@itemx M-@key{down}
+Move the current row up/down.
+@c
+@kindex M-S-@key{up}
+@item M-S-@key{up}
+Kill the current row or horizontal line.
+@c
+@kindex M-S-@key{down}
+@item M-S-@key{down}
+Insert a new row above (with arg: below) the current row.
+@c
+@kindex C-c -
+@item C-c -
+Insert a horizontal line below current row. With prefix arg, the line
+is created above the current line.
+@c
+@kindex C-c ^
+@item C-c ^
+Sort the table lines in the region. The position of point indicates the
+column to be used for sorting, and the range of lines is the range
+between the nearest horizontal separator lines, or the entire table. If
+point is before the first column, you will be prompted for the sorting
+column. If there is an active region, the mark specifies the first line
+and the sorting column, while point should be in the last line to be
+included into the sorting. The command prompts for the sorting type
+(alphabetically, numerically, or by time). When called with a prefix
+argument, alphabetic sorting will be case-sensitive.
+
+@tsubheading{Regions}
+@kindex C-c C-x M-w
+@item C-c C-x M-w
+Copy a rectangular region from a table to a special clipboard. Point
+and mark determine edge fields of the rectangle. The process ignores
+horizontal separator lines.
+@c
+@kindex C-c C-x C-w
+@item C-c C-x C-w
+Copy a rectangular region from a table to a special clipboard, and
+blank all fields in the rectangle. So this is the ``cut'' operation.
+@c
+@kindex C-c C-x C-y
+@item C-c C-x C-y
+Paste a rectangular region into a table.
+The upper right corner ends up in the current field. All involved fields
+will be overwritten. If the rectangle does not fit into the present table,
+the table is enlarged as needed. The process ignores horizontal separator
+lines.
+@c
+@kindex C-c C-q
+@item C-c C-q
+Wrap several fields in a column like a paragraph. If there is an active
+region, and both point and mark are in the same column, the text in the
+column is wrapped to minimum width for the given number of lines. A
+prefix ARG may be used to change the number of desired lines. If there
+is no region, the current field is split at the cursor position and the
+text fragment to the right of the cursor is prepended to the field one
+line down. If there is no region, but you specify a prefix ARG, the
+current field is made blank, and the content is appended to the field
+above.
+
+@tsubheading{Calculations}
+@cindex formula, in tables
+@cindex calculations, in tables
+@cindex region, active
+@cindex active region
+@cindex transient-mark-mode
+@kindex C-c +
+@item C-c +
+Sum the numbers in the current column, or in the rectangle defined by
+the active region. The result is shown in the echo area and can
+be inserted with @kbd{C-y}.
+@c
+@kindex S-@key{RET}
+@item S-@key{RET}
+When current field is empty, copy from first non-empty field above.
+When not empty, copy current field down to next row and move cursor
+along with it. Depending on the variable
+@code{org-table-copy-increment}, integer field values will be
+incremented during copy. This key is also used by CUA-mode
+(@pxref{Cooperation}).
+
+@tsubheading{Miscellaneous}
+@kindex C-c `
+@item C-c `
+Edit the current field in a separate window. This is useful for fields
+that are not fully visible (@pxref{Narrow columns}). When called with a
+@kbd{C-u} prefix, just make the full field visible, so that it can be
+edited in place.
+@c
+@kindex C-c @key{TAB}
+@item C-c @key{TAB}
+This is an alias for @kbd{C-u C-c `} to make the current field fully
+visible.
+@c
+@item M-x org-table-import
+Import a file as a table. The table should be TAB- or whitespace
+separated. Useful, for example, to import an Excel table or data from a
+database, because these programs generally can write TAB-separated text
+files. This command works by inserting the file into the buffer and
+then converting the region to a table. Any prefix argument is passed on
+to the converter, which uses it to determine the separator.
+@item C-c |
+Tables can also be imported by pasting tabular text into the org-mode
+buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
+@kbd{C-c |} command (see above under @i{Creation and conversion}.
+@c
+@item M-x org-table-export
+Export the table as a TAB-separated file. Useful for data exchange with,
+for example, Excel or database programs.
+@end table
+
+If you don't like the automatic table editor because it gets in your
+way on lines which you would like to start with @samp{|}, you can turn
+it off with
+
+@lisp
+(setq org-enable-table-editor nil)
+@end lisp
+
+@noindent Then the only table command that still works is
+@kbd{C-c C-c} to do a manual re-align.
+
+@node Narrow columns, Column groups, Built-in table editor, Tables
+@section Narrow columns
+@cindex narrow columns in tables
+
+The width of columns is automatically determined by the table editor.
+Sometimes a single field or a few fields need to carry more text,
+leading to inconveniently wide columns. To limit@footnote{This feature
+does not work on XEmacs.} the width of a column, one field anywhere in
+the column may contain just the string @samp{<N>} where @samp{N} is an
+integer specifying the width of the column in characters. The next
+re-align will then set the width of this column to no more than this
+value.
+
+@example
+@group
+|---+------------------------------| |---+--------|
+| | | | | <6> |
+| 1 | one | | 1 | one |
+| 2 | two | ----\ | 2 | two |
+| 3 | This is a long chunk of text | ----/ | 3 | This=> |
+| 4 | four | | 4 | four |
+|---+------------------------------| |---+--------|
+@end group
+@end example
+
+@noindent
+Fields that are wider become clipped and end in the string @samp{=>}.
+Note that the full text is still in the buffer, it is only invisible.
+To see the full text, hold the mouse over the field - a tool-tip window
+will show the full content. To edit such a field, use the command
+@kbd{C-c `} (that is @kbd{C-c} followed by the backquote). This will
+open a new window with the full field. Edit it and finish with @kbd{C-c
+C-c}.
+
+When visiting a file containing a table with narrowed columns, the
+necessary character hiding has not yet happened, and the table needs to
+be aligned before it looks nice. Setting the option
+@code{org-startup-align-all-tables} will realign all tables in a file
+upon visiting, but also slow down startup. You can also set this option
+on a per-file basis with:
+
+@example
+#+STARTUP: align
+#+STARTUP: noalign
+@end example
+
+@node Column groups, orgtbl-mode, Narrow columns, Tables
+@section Column groups
+@cindex grouping columns in tables
+
+When Org-mode exports tables, it does so by default without vertical
+lines because that is visually more satisfying in general. Occasionally
+however, vertical lines can be useful to structure a table into groups
+of columns, much like horizontal lines can do for groups of rows. In
+order to specify column groups, you can use a special row where the
+first field contains only @samp{/}. The further fields can either
+contain @samp{<} to indicate that this column should start a group,
+@samp{>} to indicate the end of a column, or @samp{<>} to make a column
+a group of its own. Boundaries between colum groups will upon export be
+marked with vertical lines. Here is an example:
+
+@example
+| | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
+|---+----+-----+-----+-----+---------+------------|
+| / | <> | < | | > | < | > |
+| # | 1 | 1 | 1 | 1 | 1 | 1 |
+| # | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
+| # | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
+|---+----+-----+-----+-----+---------+------------|
+#+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2))
+@end example
+
+It is also sufficient to just insert the colum group starters after
+every vertical line you'd like to have:
+
+@example
+| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
+|----+-----+-----+-----+---------+------------|
+| / | < | | | < | |
+@end example
+
+@node orgtbl-mode, The spreadsheet, Column groups, Tables
+@section The Orgtbl minor mode
+@cindex orgtbl-mode
+@cindex minor mode for tables
+
+If you like the intuitive way the Org-mode table editor works, you
+might also want to use it in other modes like text-mode or mail-mode.
+The minor mode Orgtbl-mode makes this possible. You can always toggle
+the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for
+example in mail mode, use
+
+@lisp
+(add-hook 'mail-mode-hook 'turn-on-orgtbl)
+@end lisp
+
+Furthermore, with some special setup, it is possible to maintain tables
+in arbitrary syntax with Orgtbl-mode. For example, it is possible to
+construct La@TeX{} tables with the underlying ease and power of
+Orgtbl-mode, including spreadsheet capabilities. For details, see
+@ref{Tables in arbitrary syntax}.
+
+@node The spreadsheet, , orgtbl-mode, Tables
+@section The spreadsheet
+@cindex calculations, in tables
+@cindex spreadsheet capabilities
+@cindex @file{calc} package
+
+The table editor makes use of the Emacs @file{calc} package to implement
+spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
+derive fields from other fields. While fully featured, Org-mode's
+implementation is not identical to other spreadsheets. For example,
+Org-mode knows the concept of a @emph{column formula} that will be
+applied to all non-header fields in a column without having to copy the
+formula to each relevant field.
+
+@menu
+* References:: How to refer to another field or range
+* Formula syntax for Calc:: Using Calc to compute stuff
+* Formula syntax for Lisp:: Writing formulas in Emacs Lisp
+* Field formulas:: Formulas valid for a single field
+* Column formulas:: Formulas valid for an entire column
+* Editing and debugging formulas:: Fixing formulas
+* Updating the table:: Recomputing all dependent fields
+* Advanced features:: Field names, parameters and automatic recalc
+@end menu
+
+@node References, Formula syntax for Calc, The spreadsheet, The spreadsheet
+@subsection References
+@cindex references
+
+To compute fields in the table from other fields, formulas must
+reference other fields or ranges. In Org-mode, fields can be referenced
+by name, by absolute coordinates, and by relative coordinates. To find
+out what the coordinates of a field are, press @kbd{C-c ?} in that
+field, or press @kbd{C-c @}} to toggle the display of a grid.
+
+@subsubheading Field references
+@cindex field references
+@cindex references, to fields
+
+Formulas can reference the value of another field in two ways. Like in
+any other spreadsheet, you may reference fields with a letter/number
+combination like @code{B3}, meaning the 2nd field in the 3rd row.
+@c Such references are always fixed to that field, they don't change
+@c when you copy and paste a formula to a different field. So
+@c Org-mode's @code{B3} behaves like @code{$B$3} in other spreadsheets.
+
+@noindent
+Org-mode also uses another, more general operator that looks like this:
+@example
+@@row$column
+@end example
+
+@noindent
+Column references can be absolute like @samp{1}, @samp{2},...@samp{N},
+or relative to the current column like @samp{+1} or @samp{-2}.
+
+The row specification only counts data lines and ignores horizontal
+separator lines (hlines). You can use absolute row numbers
+@samp{1}...@samp{N}, and row numbers relative to the current row like
+@samp{+3} or @samp{-1}. Or specify the row relative to one of the
+hlines: @samp{I} refers to the first hline, @samp{II} to the second etc.
+@samp{-I} refers to the first such line above the current line,
+@samp{+I} to the first such line below the current line. You can also
+write @samp{III+2} which is the second data line after the third hline
+in the table. Relative row numbers like @samp{-3} will not cross hlines
+if the current line is too close to the hline. Instead, the value
+directly at the hline is used.
+
+@samp{0} refers to the current row and column. Also, if you omit
+either the column or the row part of the reference, the current
+row/column is implied.
+
+Org-mode's references with @emph{unsigned} numbers are fixed references
+in the sense that if you use the same reference in the formula for two
+different fields, the same field will be referenced each time.
+Org-mode's references with @emph{signed} numbers are floating
+references because the same reference operator can reference different
+fields depending on the field being calculated by the formula.
+
+Here are a few examples:
+
+@example
+@@2$3 @r{2nd row, 3rd column}
+C2 @r{same as previous}
+$5 @r{column 5 in the current row}
+E& @r{same as previous}
+@@2 @r{current column, row 2}
+@@-1$-3 @r{the field one row up, three columns to the left}
+@@-I$2 @r{field just under hline above current row, column 2}
+@end example
+
+@subsubheading Range references
+@cindex range references
+@cindex references, to ranges
+
+You may reference a rectangular range of fields by specifying two field
+references connected by two dots @samp{..}. If both fields are in the
+current row, you may simply use @samp{$2..$7}, but if at least one field
+is in a different row, you need to use the general @code{@@row$column}
+format at least for the first field (i.e the reference must start with
+@samp{@@} in order to be interpreted correctly). Examples:
+
+@example
+$1..$3 @r{First three fields in the current row.}
+$P..$Q @r{Range, using column names (see under Advanced)}
+@@2$1..@@4$3 @r{6 fields between these two fields.}
+A2..C4 @r{Same as above.}
+@@-1$-2..@@-1 @r{3 numbers from the column to the left, 2 up to current row}
+@end example
+
+@noindent Range references return a vector of values that can be fed
+into Calc vector functions. Empty fields in ranges are normally
+suppressed, so that the vector contains only the non-empty fields (but
+see the @samp{E} mode switch below). If there are no non-empty fields,
+@samp{[0]} is returned to avoid syntax errors in formulas.
+
+@subsubheading Named references
+@cindex named references
+@cindex references, named
+@cindex name, of column or field
+@cindex constants, in calculations
+
+@samp{$name} is interpreted as the name of a column, parameter or
+constant. Constants are defined globally through the variable
+@code{org-table-formula-constants}, and locally (for the file) through a
+line like
+
+@example
+#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
+@end example
+
+@noindent
+Also properties (@pxref{Properties and columns}) can be used as
+constants in table formulas: For a property @samp{:XYZ:} use the name
+@samp{$PROP_XYZ}, and the property will be searched in the current
+outline entry and in the hierarchy above it. If you have the
+@file{constants.el} package, it will also be used to resolve constants,
+including natural constants like @samp{$h} for Planck's constant, and
+units like @samp{$km} for kilometers@footnote{@file{Constant.el} can
+supply the values of constants in two different unit systems, @code{SI}
+and @code{cgs}. Which one is used depends on the value of the variable
+@code{constants-unit-system}. You can use the @code{#+STARTUP} options
+@code{constSI} and @code{constcgs} to set this value for the current
+buffer.}. Column names and parameters can be specified in special table
+lines. These are described below, see @ref{Advanced features}. All
+names must start with a letter, and further consist of letters and
+numbers.
+
+@node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet
+@subsection Formula syntax for Calc
+@cindex formula syntax, Calc
+@cindex syntax, of formulas
+
+A formula can be any algebraic expression understood by the Emacs
+@file{Calc} package. @b{Note that @file{calc} has the
+non-standard convention that @samp{/} has lower precedence than
+@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.} Before
+evaluation by @code{calc-eval} (@pxref{Calling Calc from
+Your Programs,calc-eval,Calling calc from Your Lisp Programs,calc,GNU
+Emacs Calc Manual}),
+@c FIXME: The link to the calc manual in HTML does not work.
+variable substitution takes place according to the rules described above.
+@cindex vectors, in table calculations
+The range vectors can be directly fed into the calc vector functions
+like @samp{vmean} and @samp{vsum}.
+
+@cindex format specifier
+@cindex mode, for @file{calc}
+A formula can contain an optional mode string after a semicolon. This
+string consists of flags to influence Calc and other modes during
+execution. By default, Org-mode uses the standard calc modes (precision
+12, angular units degrees, fraction and symbolic modes off. The display
+format, however, has been changed to @code{(float 5)} to keep tables
+compact. The default settings can be configured using the variable
+@code{org-calc-default-modes}.
+
+@example
+p20 @r{switch the internal precision to 20 digits}
+n3 s3 e2 f4 @r{normal, scientific, engineering, or fixed display format}
+D R @r{angle modes: degrees, radians}
+F S @r{fraction and symbolic modes}
+N @r{interpret all fields as numbers, use 0 for non-numbers}
+T @r{force text interpretation}
+E @r{keep empty fields in ranges}
+@end example
+
+@noindent
+In addition, you may provide a @code{printf} format specifier to
+reformat the final result. A few examples:
+
+@example
+$1+$2 @r{Sum of first and second field}
+$1+$2;%.2f @r{Same, format result to two decimals}
+exp($2)+exp($1) @r{Math functions can be used}
+$0;%.1f @r{Reformat current cell to 1 decimal}
+($3-32)*5/9 @r{Degrees F -> C conversion}
+$c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
+tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}
+sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
+vmean($2..$7) @r{Compute column range mean, using vector function}
+vmean($2..$7);EN @r{Same, but treat empty fields as 0}
+taylor($3,x=7,2) @r{taylor series of $3, at x=7, second degree}
+@end example
+
+Calc also contains a complete set of logical operations. For example
+
+@example
+if($1<20,teen,string("")) @r{``teen'' if age $1 less than 20, else empty}
+@end example
+
+@node Formula syntax for Lisp, Field formulas, Formula syntax for Calc, The spreadsheet
+@subsection Emacs Lisp forms as formulas
+@cindex Lisp forms, as table formulas
+
+It is also possible to write a formula in Emacs Lisp; this can be useful
+for string manipulation and control structures, if the Calc's
+functionality is not enough. If a formula starts with a single quote
+followed by an opening parenthesis, then it is evaluated as a lisp form.
+The evaluation should return either a string or a number. Just as with
+@file{calc} formulas, you can specify modes and a printf format after a
+semicolon. With Emacs Lisp forms, you need to be concious about the way
+field references are interpolated into the form. By default, a
+reference will be interpolated as a Lisp string (in double quotes)
+containing the field. If you provide the @samp{N} mode switch, all
+referenced elements will be numbers (non-number fields will be zero) and
+interpolated as Lisp numbers, without quotes. If you provide the
+@samp{L} flag, all fields will be interpolated literally, without quotes.
+I.e., if you want a reference to be interpreted as a string by the Lisp
+form, enclode the reference operator itself in double quotes, like
+@code{"$3"}. Ranges are inserted as space-separated fields, so you can
+embed them in list or vector syntax. A few examples, note how the
+@samp{N} mode is used when we do computations in lisp.
+
+@example
+@r{Swap the first two characters of the content of column 1}
+ '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
+@r{Add columns 1 and 2, equivalent to the Calc's @code{$1+$2}}
+ '(+ $1 $2);N
+@r{Compute the sum of columns 1-4, like Calc's @code{vsum($1..$4)}}
+ '(apply '+ '($1..$4));N
+@end example
+
+@node Field formulas, Column formulas, Formula syntax for Lisp, The spreadsheet
+@subsection Field formulas
+@cindex field formula
+@cindex formula, for individual table field
+
+To assign a formula to a particular field, type it directly into the
+field, preceded by @samp{:=}, for example @samp{:=$1+$2}. When you
+press @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in
+the field, the formula will be stored as the formula for this field,
+evaluated, and the current field replaced with the result.
+
+Formulas are stored in a special line starting with @samp{#+TBLFM:}
+directly below the table. If you typed the equation in the 4th field of
+the 3rd data line in the table, the formula will look like
+@samp{@@3$4=$1+$2}. When inserting/deleting/swapping column and rows
+with the appropriate commands, @i{absolute references} (but not relative
+ones) in stored formulas are modified in order to still reference the
+same field. Of cause this is not true if you edit the table structure
+with normal editing commands - then you must fix the equations yourself.
+
+Instead of typing an equation into the field, you may also use the
+following command
+
+@table @kbd
+@kindex C-u C-c =
+@item C-u C-c =
+Install a new formula for the current field. The command prompts for a
+formula, with default taken from the @samp{#+TBLFM:} line, applies
+it to the current field and stores it.
+@end table
+
+@node Column formulas, Editing and debugging formulas, Field formulas, The spreadsheet
+@subsection Column formulas
+@cindex column formula
+@cindex formula, for table column
+
+Often in a table, the same formula should be used for all fields in a
+particular column. Instead of having to copy the formula to all fields
+in that column, org-mode allows to assign a single formula to an entire
+column. If the table contains horizontal separator hlines, everything
+before the first such line is considered part of the table @emph{header}
+and will not be modified by column formulas.
+
+To assign a formula to a column, type it directly into any field in the
+column, preceded by an equal sign, like @samp{=$1+$2}. When you press
+@key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the
+field, the formula will be stored as the formula for the current column,
+evaluated and the current field replaced with the result. If the field
+contains only @samp{=}, the previously stored formula for this column is
+used. For each column, Org-mode will only remember the most recently
+used formula. In the @samp{TBLFM:} line, column formulas will look like
+@samp{$4=$1+$2}.
+
+Instead of typing an equation into the field, you may also use the
+following command:
+
+@table @kbd
+@kindex C-c =
+@item C-c =
+Install a new formula for the current column and replace current field
+with the result of the formula. The command prompts for a formula, with
+default taken from the @samp{#+TBLFM} line, applies it to the current
+field and stores it. With a numerical prefix (e.g. @kbd{C-5 C-c =})
+will apply it to that many consecutive fields in the current column.
+@end table
+
+
+@node Editing and debugging formulas, Updating the table, Column formulas, The spreadsheet
+@subsection Editing and Debugging formulas
+@cindex formula editing
+@cindex editing, of table formulas
+
+You can edit individual formulas in the minibuffer or directly in the
+field. Org-mode can also prepare a special buffer with all active
+formulas of a table. When offering a formula for editing, Org-mode
+converts references to the standard format (like @code{B3} or @code{D&})
+if possible. If you prefer to only work with the internal format (like
+@code{@@3$2} or @code{$4}), configure the variable
+@code{org-table-use-standard-references}.
+
+@table @kbd
+@kindex C-c =
+@kindex C-u C-c =
+@item C-c =
+@itemx C-u C-c =
+Edit the formula associated with the current column/field in the
+minibuffer. See @ref{Column formulas} and @ref{Field formulas}.
+@kindex C-u C-u C-c =
+@item C-u C-u C-c =
+Re-insert the active formula (either a
+field formula, or a column formula) into the current field, so that you
+can edit it directly in the field. The advantage over editing in the
+minibuffer is that you can use the command @kbd{C-c ?}.
+@kindex C-c ?
+@item C-c ?
+While editing a formula in a table field, highlight the field(s)
+referenced by the reference at the cursor position in the formula.
+@kindex C-c @}
+@item C-c @}
+Toggle the display of row and column numbers for a table, using
+overlays. These are updated each time the table is aligned, you can
+force it with @kbd{C-c C-c}.
+@kindex C-c @{
+@item C-c @{
+Toggle the formula debugger on and off. See below.
+@kindex C-c '
+@item C-c '
+Edit all formulas for the current table in a special buffer, where the
+formulas will be displayed one per line. If the current field has an
+active formula, the cursor in the formula editor will mark it.
+While inside the special buffer, Org-mode will automatically highlight
+any field or range reference at the cursor position. You may edit,
+remove and add formulas, and use the following commands:
+@table @kbd
+@kindex C-c C-c
+@kindex C-x C-s
+@item C-c C-c
+@itemx C-x C-s
+Exit the formula editor and store the modified formulas. With @kbd{C-u}
+prefix, also apply the new formulas to the entire table.
+@kindex C-c C-q
+@item C-c C-q
+Exit the formula editor without installing changes.
+@kindex C-c C-r
+@item C-c C-r
+Toggle all references in the formula editor between standard (like
+@code{B3}) and internal (like @code{@@3$2}).
+@kindex @key{TAB}
+@item @key{TAB}
+Pretty-print or indent lisp formula at point. When in a line containing
+a lisp formula, format the formula according to Emacs Lisp rules.
+Another @key{TAB} collapses the formula back again. In the open
+formula, @key{TAB} re-indents just like in Emacs-lisp-mode.
+@kindex M-@key{TAB}
+@item M-@key{TAB}
+Complete Lisp symbols, just like in Emacs-lisp-mode.
+@kindex S-@key{up}
+@kindex S-@key{down}
+@kindex S-@key{left}
+@kindex S-@key{right}
+@item S-@key{up}/@key{down}/@key{left}/@key{right}
+Shift the reference at point. For example, if the reference is
+@code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}.
+This also works for relative references, and for hline references.
+@kindex M-S-@key{up}
+@kindex M-S-@key{down}
+@item M-S-@key{up}/@key{down}
+Move the test line for column formulas in the Org-mode buffer up and
+down.
+@kindex M-@key{up}
+@kindex M-@key{down}
+@item M-@key{up}/@key{down}
+Scroll the window displaying the table.
+@kindex C-c @}
+@item C-c @}
+Turn the coordinate grid in the table on and off.
+@end table
+@end table
+
+Making a table field blank does not remove the formula associated with
+the field, because that is stored in a different line (the @samp{TBLFM}
+line) - during the next recalculation the field will be filled again.
+To remove a formula from a field, you have to give an empty reply when
+prompted for the formula, or to edit the @samp{#+TBLFM} line.
+
+@kindex C-c C-c
+You may edit the @samp{#+TBLFM} directly and re-apply the changed
+equations with @kbd{C-c C-c} in that line, or with the normal
+recalculation commands in the table.
+
+@subsubheading Debugging formulas
+@cindex formula debugging
+@cindex debugging, of table formulas
+When the evaluation of a formula leads to an error, the field content
+becomes the string @samp{#ERROR}. If you would like see what is going
+on during variable substitution and calculation in order to find a bug,
+turn on formula debugging in the @code{Tbl} menu and repeat the
+calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a
+field. Detailed information will be displayed.
+
+@node Updating the table, Advanced features, Editing and debugging formulas, The spreadsheet
+@subsection Updating the Table
+@cindex recomputing table fields
+@cindex updating, table
+
+Recalculation of a table is normally not automatic, but needs to be
+triggered by a command. See @ref{Advanced features} for a way to make
+recalculation at least semi-automatically.
+
+In order to recalculate a line of a table or the entire table, use the
+following commands:
+
+@table @kbd
+@kindex C-c *
+@item C-c *
+Recalculate the current row by first applying the stored column formulas
+from left to right, and all field formulas in the current row.
+@c
+@kindex C-u C-c *
+@item C-u C-c *
+@kindex C-u C-c C-c
+@itemx C-u C-c C-c
+Recompute the entire table, line by line. Any lines before the first
+hline are left alone, assuming that these are part of the table header.
+@c
+@kindex C-u C-u C-c *
+@kindex C-u C-u C-c C-c
+@item C-u C-u C-c *
+@itemx C-u C-u C-c C-c
+Iterate the table by recomputing it until no further changes occur.
+This may be necessary if some computed fields use the value of other
+fields that are computed @i{later} in the calculation sequence.
+@end table
+
+@node Advanced features, , Updating the table, The spreadsheet
+@subsection Advanced features
+
+If you want the recalculation of fields to happen automatically, or if
+you want to be able to assign @i{names} to fields and columns, you need
+to reserve the first column of the table for special marking characters.
+@table @kbd
+@kindex C-#
+@item C-#
+Rotate the calculation mark in first column through the states @samp{},
+@samp{#}, @samp{*}, @samp{!}, @samp{$}. The meaning of these characters
+is discussed below. When there is an active region, change all marks in
+the region.
+@end table
+
+Here is an example of a table that collects exam results of students and
+makes use of these features:
+
+@example
+@group
+|---+---------+--------+--------+--------+-------+------|
+| | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
+|---+---------+--------+--------+--------+-------+------|
+| ! | | P1 | P2 | P3 | Tot | |
+| # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
+| ^ | | m1 | m2 | m3 | mt | |
+|---+---------+--------+--------+--------+-------+------|
+| # | Peter | 10 | 8 | 23 | 41 | 8.2 |
+| # | Sara | 6 | 14 | 19 | 39 | 7.8 |
+| # | Sam | 2 | 4 | 3 | 9 | 1.8 |
+|---+---------+--------+--------+--------+-------+------|
+| | Average | | | | 29.7 | |
+| ^ | | | | | at | |
+| $ | max=50 | | | | | |
+|---+---------+--------+--------+--------+-------+------|
+#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f
+@end group
+@end example
+
+@noindent @b{Important}: Please note that for these special tables,
+recalculating the table with @kbd{C-u C-c *} will only affect rows that
+are marked @samp{#} or @samp{*}, and fields that have a formula assigned
+to the field itself. The column formulas are not applied in rows with
+empty first field.
+
+@cindex marking characters, tables
+The marking characters have the following meaning:
+@table @samp
+@item !
+The fields in this line define names for the columns, so that you may
+refer to a column as @samp{$Tot} instead of @samp{$6}.
+@item ^
+This row defines names for the fields @emph{above} the row. With such
+a definition, any formula in the table may use @samp{$m1} to refer to
+the value @samp{10}. Also, if you assign a formula to a names field, it
+will be stored as @samp{$name=...}.
+@item _
+Similar to @samp{^}, but defines names for the fields in the row
+@emph{below}.
+@item $
+Fields in this row can define @emph{parameters} for formulas. For
+example, if a field in a @samp{$} row contains @samp{max=50}, then
+formulas in this table can refer to the value 50 using @samp{$max}.
+Parameters work exactly like constants, only that they can be defined on
+a per-table basis.
+@item #
+Fields in this row are automatically recalculated when pressing
+@key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row
+is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked
+lines will be left alone by this command.
+@item *
+Selects this line for global recalculation with @kbd{C-u C-c *}, but
+not for automatic recalculation. Use this when automatic
+recalculation slows down editing too much.
+@item
+Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
+All lines that should be recalculated should be marked with @samp{#}
+or @samp{*}.
+@item /
+Do not export this line. Useful for lines that contain the narrowing
+@samp{<N>} markers.
+@end table
+
+Finally, just to whet your appetite on what can be done with the
+fantastic @file{calc} package, here is a table that computes the Taylor
+series of degree @code{n} at location @code{x} for a couple of functions
+(homework: try that with Excel :-)
+
+@example
+@group
+|---+-------------+---+-----+--------------------------------------|
+| | Func | n | x | Result |
+|---+-------------+---+-----+--------------------------------------|
+| # | exp(x) | 1 | x | 1 + x |
+| # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
+| # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
+| # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
+| # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
+| * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
+|---+-------------+---+-----+--------------------------------------|
+#+TBLFM: $5=taylor($2,$4,$3);n3
+@end group
+@end example
+
+@node Hyperlinks, TODO items, Tables, Top
+@chapter Hyperlinks
+@cindex hyperlinks
+
+Just like HTML, Org-mode provides links inside a file, and external
+links to other files, Usenet articles, emails, and much more.
+
+@menu
+* Link format:: How links in Org-mode are formatted
+* Internal links:: Links to other places in the current file
+* External links:: URL-like links to the world
+* Handling links:: Creating, inserting and following
+* Using links outside Org-mode:: Linking from my C source code?
+* Link abbreviations:: Shortcuts for writing complex links
+* Search options:: Linking to a specific location
+* Custom searches:: When the default search is not enough
+* Remember:: Org-trees store quick notes
+@end menu
+
+@node Link format, Internal links, Hyperlinks, Hyperlinks
+@section Link format
+@cindex link format
+@cindex format, of links
+
+Org-mode will recognize plain URL-like links and activate them as
+clickable links. The general link format, however, looks like this:
+
+@example
+[[link][description]] @r{or alternatively} [[link]]
+@end example
+
+Once a link in the buffer is complete (all brackets present), Org-mode
+will change the display so that @samp{description} is displayed instead
+of @samp{[[link][description]]} and @samp{link} is displayed instead of
+@samp{[[link]]}. Links will be highlighted in the face @code{org-link},
+which by default is an underlined face. You can directly edit the
+visible part of a link. Note that this can be either the @samp{link}
+part (if there is no description) or the @samp{description} part. To
+edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
+cursor on the link.
+
+If you place the cursor at the beginning or just behind the end of the
+displayed text and press @key{BACKSPACE}, you will remove the
+(invisible) bracket at that location. This makes the link incomplete
+and the internals are again displayed as plain text. Inserting the
+missing bracket hides the link internals again. To show the
+internal structure of all links, use the menu entry
+@code{Org->Hyperlinks->Literal links}.
+
+@node Internal links, External links, Link format, Hyperlinks
+@section Internal links
+@cindex internal links
+@cindex links, internal
+@cindex targets, for links
+
+If the link does not look like a URL, it is considered to be internal in
+the current file. Links such as @samp{[[My Target]]} or @samp{[[My
+Target][Find my target]]} lead to a text search in the current file.
+The link can be followed with @kbd{C-c C-o} when the cursor is on the
+link, or with a mouse click (@pxref{Handling links}). The preferred
+match for such a link is a dedicated target: the same string in double
+angular brackets. Targets may be located anywhere; sometimes it is
+convenient to put them into a comment line. For example
+
+@example
+# <<My Target>>
+@end example
+
+@noindent In HTML export (@pxref{HTML export}), such targets will become
+named anchors for direct access through @samp{http} links@footnote{Note
+that text before the first headline is usually not exported, so the
+first such target should be after the first headline.}.
+
+If no dedicated target exists, Org-mode will search for the words in the
+link. In the above example the search would be for @samp{my target}.
+Links starting with a star like @samp{*My Target} restrict the search to
+headlines. When searching, Org-mode will first try an exact match, but
+then move on to more and more lenient searches. For example, the link
+@samp{[[*My Targets]]} will find any of the following:
+
+@example
+** My targets
+** TODO my targets are bright
+** my 20 targets are
+@end example
+
+To insert a link targeting a headline, in-buffer completion can be used.
+Just type a star followed by a few optional letters into the buffer and
+press @kbd{M-@key{TAB}}. All headlines in the current buffer will be
+offered as completions. @xref{Handling links}, for more commands
+creating links.
+
+Following a link pushes a mark onto Org-mode's own mark ring. You can
+return to the previous position with @kbd{C-c &}. Using this command
+several times in direct succession goes back to positions recorded
+earlier.
+
+@menu
+* Radio targets:: Make targets trigger links in plain text.
+@end menu
+
+@node Radio targets, , Internal links, Internal links
+@subsection Radio targets
+@cindex radio targets
+@cindex targets, radio
+@cindex links, radio targets
+
+Org-mode can automatically turn any occurrences of certain target names
+in normal text into a link. So without explicitly creating a link, the
+text connects to the target radioing its position. Radio targets are
+enclosed by triple angular brackets. For example, a target @samp{<<<My
+Target>>>} causes each occurrence of @samp{my target} in normal text to
+become activated as a link. The Org-mode file is scanned automatically
+for radio targets only when the file is first loaded into Emacs. To
+update the target list during editing, press @kbd{C-c C-c} with the
+cursor on or at a target.
+
+@node External links, Handling links, Internal links, Hyperlinks
+@section External links
+@cindex links, external
+@cindex external links
+@cindex links, external
+@cindex GNUS links
+@cindex BBDB links
+@cindex URL links
+@cindex file links
+@cindex VM links
+@cindex RMAIL links
+@cindex WANDERLUST links
+@cindex MH-E links
+@cindex USENET links
+@cindex SHELL links
+@cindex Info links
+@cindex elisp links
+
+Org-mode supports links to files, websites, Usenet and email messages,
+and BBDB database entries. External links are URL-like locators. They
+start with a short identifying string followed by a colon. There can be
+no space after the colon. The following list shows examples for each
+link type.
+
+@example
+http://www.astro.uva.nl/~dominik @r{on the web}
+file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
+file:papers/last.pdf @r{file, relative path}
+news:comp.emacs @r{Usenet link}
+mailto:adent@@galaxy.net @r{Mail link}
+vm:folder @r{VM folder link}
+vm:folder#id @r{VM message link}
+vm://myself@@some.where.org/folder#id @r{VM on remote machine}
+wl:folder @r{WANDERLUST folder link}
+wl:folder#id @r{WANDERLUST message link}
+mhe:folder @r{MH-E folder link}
+mhe:folder#id @r{MH-E message link}
+rmail:folder @r{RMAIL folder link}
+rmail:folder#id @r{RMAIL message link}
+gnus:group @r{GNUS group link}
+gnus:group#id @r{GNUS article link}
+bbdb:Richard Stallman @r{BBDB link}
+shell:ls *.org @r{A shell command}
+elisp:(find-file-other-frame "Elisp.org") @r{An elisp form to evaluate}
+@end example
+
+A link should be enclosed in double brackets and may contain a
+descriptive text to be displayed instead of the url (@pxref{Link
+format}), for example:
+
+@example
+[[http://www.gnu.org/software/emacs/][GNU Emacs]]
+@end example
+
+@noindent
+If the description is a file name or URL that points to an image, HTML
+export (@pxref{HTML export}) will inline the image as a clickable
+button. If there is no description at all and the link points to an
+image,
+that image will be inlined into the exported HTML file.
+
+@cindex angular brackets, around links
+@cindex plain text external links
+Org-mode also finds external links in the normal text and activates them
+as links. If spaces must be part of the link (for example in
+@samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
+about the end of the link, enclose them in angular brackets.
+
+@node Handling links, Using links outside Org-mode, External links, Hyperlinks
+@section Handling links
+@cindex links, handling
+
+Org-mode provides methods to create a link in the correct syntax, to
+insert it into an org-mode file, and to follow the link.
+
+@table @kbd
+@kindex C-c l
+@cindex storing links
+@item C-c l
+Store a link to the current location. This is a @emph{global} command
+which can be used in any buffer to create a link. The link will be
+stored for later insertion into an Org-mode buffer (see below). For
+Org-mode files, if there is a @samp{<<target>>} at the cursor, the link
+points to the target. Otherwise it points to the current headline. For
+VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, the link will
+indicate the current article/entry. For W3 and W3M buffers, the link
+goes to the current URL. For any other files, the link will point to
+the file, with a search string (@pxref{Search options}) pointing to the
+contents of the current line. If there is an active region, the
+selected words will form the basis of the search string. If the
+automatically created link is not working correctly or accurately
+enough, you can write custom functions to select the search string and
+to do the search for particular file types - see @ref{Custom searches}.
+The key binding @kbd{C-c l} is only a suggestion - see @ref{Installation}.
+@c
+@kindex C-c C-l
+@cindex link completion
+@cindex completion, of links
+@cindex inserting links
+@item C-c C-l
+Insert a link. This prompts for a link to be inserted into the buffer.
+You can just type a link, using text for an internal link, or one of the
+link type prefixes mentioned in the examples above. All links stored
+during the current session are part of the history for this prompt, so
+you can access them with @key{up} and @key{down}. Completion, on the
+other hand, will help you to insert valid link prefixes like
+@samp{http:} or @samp{ftp:}, including the prefixes defined through link
+abbreviations (@pxref{Link abbreviations}). The link will be inserted
+into the buffer@footnote{After insertion of a stored link, the link will
+be removed from the list of stored links. To keep it in the list later
+use, use a triple @kbd{C-u} prefix to @kbd{C-c C-l}, or configure the
+option @code{org-keep-stored-link-after-insertion}.}, along with a
+descriptive text. If some text was selected when this command is
+called, the selected text becomes the default description.@* Note that
+you don't have to use this command to insert a link. Links in Org-mode
+are plain text, and you can type or paste them straight into the buffer.
+By using this command, the links are automatically enclosed in double
+brackets, and you will be asked for the optional descriptive text.
+@c
+@c If the link is a @samp{file:} link and
+@c the linked file is located in the same directory as the current file or
+@c a subdirectory of it, the path of the file will be inserted relative to
+@c the current directory.
+@c
+@kindex C-u C-c C-l
+@cindex file name completion
+@cindex completion, of file names
+@item C-u C-c C-l
+When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
+a file will be inserted and you may use file name completion to select
+the name of the file. The path to the file is inserted relative to the
+directory of the current org file, if the linked file is in the current
+directory or in a subdirectory of it, or if the path is written relative
+to the current directory using @samp{../}. Otherwise an absolute path
+is used, if possible with @samp{~/} for your home directory. You can
+force an absolute path with two @kbd{C-u} prefixes.
+@c
+@item C-c C-l @r{(with cursor on existing link)}
+When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
+link and description parts of the link.
+@c
+@cindex following links
+@kindex C-c C-o
+@item C-c C-o
+Open link at point. This will launch a web browser for URLs (using
+@command{browse-url-at-point}), run vm/mh-e/wanderlust/rmail/gnus/bbdb
+for the corresponding links, and execute the command in a shell link.
+When the cursor is on an internal link, this commands runs the
+corresponding search. When the cursor is on a TAG list in a headline,
+it creates the corresponding TAGS view. If the cursor is on a time
+stamp, it compiles the agenda for that date. Furthermore, it will visit
+text and remote files in @samp{file:} links with Emacs and select a
+suitable application for local non-text files. Classification of files
+is based on file extension only. See option @code{org-file-apps}. If
+you want to override the default application and visit the file with
+Emacs, use a @kbd{C-u} prefix.
+@c
+@kindex mouse-2
+@kindex mouse-1
+@item mouse-2
+@itemx mouse-1
+On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o}
+would. Under Emacs 22, also @kbd{mouse-1} will follow a link.
+@c
+@kindex mouse-3
+@item mouse-3
+Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
+internal links to be displayed in another window@footnote{See the
+variable @code{org-display-internal-link-with-indirect-buffer}}.
+@c
+@cindex mark ring
+@kindex C-c %
+@item C-c %
+Push the current position onto the mark ring, to be able to return
+easily. Commands following an internal link do this automatically.
+@c
+@cindex links, returning to
+@kindex C-c &
+@item C-c &
+Jump back to a recorded position. A position is recorded by the
+commands following internal links, and by @kbd{C-c %}. Using this
+command several times in direct succession moves through a ring of
+previously recorded positions.
+@c
+@kindex C-c C-x C-n
+@kindex C-c C-x C-p
+@cindex links, finding next/previous
+@item C-c C-x C-n
+@itemx C-c C-x C-p
+Move forward/backward to the next link in the buffer. At the limit of
+the buffer, the search fails once, and then wraps around. The key
+bindings for this are really too long, you might want to bind this also
+to @kbd{C-n} and @kbd{C-p}
+@lisp
+(add-hook 'org-load-hook
+ (lambda ()
+ (define-key 'org-mode-map "\C-n" 'org-next-link)
+ (define-key 'org-mode-map "\C-p" 'org-previous-link)))
+@end lisp
+@end table
+
+@node Using links outside Org-mode, Link abbreviations, Handling links, Hyperlinks
+@section Using links outside Org-mode
+
+You can insert and follow links that have Org-mode syntax not only in
+Org-mode, but in any Emacs buffer. For this, you should create two
+global commands, like this (please select suitable global keys
+yourself):
+
+@lisp
+(global-set-key "\C-c L" 'org-insert-link-global)
+(global-set-key "\C-c o" 'org-open-at-point-global)
+@end lisp
+
+@node Link abbreviations, Search options, Using links outside Org-mode, Hyperlinks
+@section Link abbreviations
+@cindex link abbreviations
+@cindex abbreviation, links
+
+Long URLs can be cumbersome to type, and often many similar links are
+needed in a document. For this you can use link abbreviations. An
+abbreviated link looks like this
+
+@example
+[[linkword:tag][description]]
+@end example
+
+@noindent
+where the tag is optional. Such abbreviations are resolved according to
+the information in the variable @code{org-link-abbrev-alist} that
+relates the linkwords to replacement text. Here is an example:
+
+@lisp
+@group
+(setq org-link-abbrev-alist
+ '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
+ ("google" . "http://www.google.com/search?q=")
+ ("ads" . "http://adsabs.harvard.edu/cgi-bin/
+ nph-abs_connect?author=%s&db_key=AST")))
+@end group
+@end lisp
+
+If the replacement text contains the string @samp{%s}, it will be
+replaced with the tag. Otherwise the tag will be appended to the string
+in order to create the link. You may also specify a function that will
+be called with the tag as the only argument to create the link.
+
+With the above setting, you could link to a specific bug with
+@code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with
+@code{[[google:OrgMode]]} and find out what the Org-mode author is
+doing besides Emacs hacking with @code{[[ads:Dominik,C]]}.
+
+If you need special abbreviations just for a single Org-mode buffer, you
+can define them in the file with
+
+@example
+#+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
+#+LINK: google http://www.google.com/search?q=%s
+@end example
+
+@noindent
+In-buffer completion @pxref{Completion} can be used after @samp{[} to
+complete link abbreviations.
+
+@node Search options, Custom searches, Link abbreviations, Hyperlinks
+@section Search options in file links
+@cindex search option in file links
+@cindex file links, searching
+
+File links can contain additional information to make Emacs jump to a
+particular location in the file when following a link. This can be a
+line number or a search option after a double@footnote{For backward
+compatibility, line numbers can also follow a single colon.} colon. For
+example, when the command @kbd{C-c l} creates a link (@pxref{Handling
+links}) to a file, it encodes the words in the current line as a search
+string that can be used to find this line back later when following the
+link with @kbd{C-c C-o}.
+
+Here is the syntax of the different ways to attach a search to a file
+link, together with an explanation:
+
+@example
+[[file:~/code/main.c::255]]
+[[file:~/xx.org::My Target]]
+[[file:~/xx.org::*My Target]]
+[[file:~/xx.org::/regexp/]]
+@end example
+
+@table @code
+@item 255
+Jump to line 255.
+@item My Target
+Search for a link target @samp{<<My Target>>}, or do a text search for
+@samp{my target}, similar to the search in internal links, see
+@ref{Internal links}. In HTML export (@pxref{HTML export}), such a file
+link will become an HTML reference to the corresponding named anchor in
+the linked file.
+@item *My Target
+In an Org-mode file, restrict search to headlines.
+@item /regexp/
+Do a regular expression search for @code{regexp}. This uses the Emacs
+command @code{occur} to list all matches in a separate window. If the
+target file is in Org-mode, @code{org-occur} is used to create a
+sparse tree with the matches.
+@c If the target file is a directory,
+@c @code{grep} will be used to search all files in the directory.
+@end table
+
+As a degenerate case, a file link with an empty file name can be used
+to search the current file. For example, @code{[[file:::find me]]} does
+a search for @samp{find me} in the current file, just as
+@samp{[[find me]]} would.
+
+@node Custom searches, Remember, Search options, Hyperlinks
+@section Custom Searches
+@cindex custom search strings
+@cindex search strings, custom
+
+The default mechanism for creating search strings and for doing the
+actual search related to a file link may not work correctly in all
+cases. For example, BibTeX database files have many entries like
+@samp{year="1993"} which would not result in good search strings,
+because the only unique identification for a BibTeX entry is the
+citation key.
+
+If you come across such a problem, you can write custom functions to set
+the right search string for a particular file type, and to do the search
+for the string in the file. Using @code{add-hook}, these functions need
+to be added to the hook variables
+@code{org-create-file-search-functions} and
+@code{org-execute-file-search-functions}. See the docstring for these
+variables for more information. Org-mode actually uses this mechanism
+for Bib@TeX{} database files, and you can use the corresponding code as
+an implementation example. Search for @samp{BibTeX links} in the source
+file.
+
+
+@node Remember, , Custom searches, Hyperlinks
+@section Remember
+@cindex @file{remember.el}
+
+Another way to create org entries with links to other files is through
+the @i{remember} package by John Wiegley. @i{Remember} lets you store
+quick notes with little interruption of your work flow. See
+@uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for more
+information. The notes produced by @i{Remember} can be stored in
+different ways, and Org-mode files are a good target. Org-mode
+significantly expands the possibilities of @i{remember}: You may define
+templates for different note types, and to associate target files and
+headlines with specific templates. It also allows you to select the
+location where a note should be stored interactively, on the fly.
+
+@menu
+* Setting up remember:: Some code for .emacs to get things going
+* Remember templates:: Define the outline of different note types
+* Storing notes:: Directly get the note to where it belongs
+@end menu
+
+@node Setting up remember, Remember templates, Remember, Remember
+@subsection Setting up remember
+
+The following customization will tell @i{remember} to use org files as
+target, and to create annotations compatible with Org-mode links.
+
+@example
+(setq org-directory "~/path/to/my/orgfiles/")
+(setq org-default-notes-file "~/.notes")
+(setq remember-annotation-functions '(org-remember-annotation))
+(setq remember-handler-functions '(org-remember-handler))
+(add-hook 'remember-mode-hook 'org-remember-apply-template)
+@end example
+
+@node Remember templates, Storing notes, Setting up remember, Remember
+@subsection Remember templates
+@cindex templates, for remember
+
+In combination with Org-mode, you can use templates to generate
+different types of @i{remember} notes. For example, if you would like
+to use one template to create general TODO entries, another one for
+journal entries, and a third one for collecting random ideas, you could
+use:
+
+@example
+(setq org-remember-templates
+ '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org")
+ (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org")
+ (?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas")))
+@end example
+
+@noindent In these entries, the character specifies how to select the
+template. The first string specifies the template. Two more (optional)
+strings give the file in which, and the headline under which the new
+note should be stored. The file defaults (if not present or @code{nil})
+to @code{org-default-notes-file}, the heading to
+@code{org-remember-default-headline}. Both defaults help to get to the
+storing location quickly, but you can change the location interactively
+while storing the note.
+
+When you call @kbd{M-x remember} (or @kbd{M-x org-remember}) to remember
+something, org will prompt for a key to select the template (if you have
+more than one template) and then prepare the buffer like
+@example
+* TODO
+ [[file:link to where you called remember]]
+@end example
+
+@noindent or
+
+@example
+* [2006-03-21 Tue 15:37]
+
+ [[file:link to where you called remember]]
+@end example
+
+@noindent
+During expansion of the template, special @kbd{%}-escapes allow dynamic
+insertion of content:
+@example
+%^@{prompt@} @r{prompt the user for a string and replace this sequence with it.}
+%t @r{time stamp, date only}
+%T @r{time stamp with date and time}
+%u, %U @r{like the above, but inactive time stamps}
+%^t @r{like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}}
+ @r{You may define a prompt like @code{%^@{Birthday@}t}}
+%n @r{user name (taken from @code{user-full-name})}
+%a @r{annotation, normally the link created with @code{org-store-link}}
+%i @r{initial content, the region when remember is called with C-u.}
+ @r{The entire text will be indented like @code{%i} itself.}
+%^g @r{prompt for tags, with completion on tags in target file.}
+%^G @r{prompt for tags, with completion all tags in all agenda files.}
+%:keyword @r{specific information for certain link types, see below}
+@end example
+
+@noindent
+For specific link types, the following keywords will be defined:
+
+@example
+Link type | Available keywords
+-------------------+----------------------------------------------
+bbdb | %:name %:company
+vm, wl, mh, rmail | %:type %:subject %:message-id
+ | %:from %:fromname %:fromaddress
+ | %:to %:toname %:toaddress
+ | %:fromto @r{(either "to NAME" or "from NAME")@footnote{This will always be the other, not the user. See the variable @code{org-from-is-user-regexp}.}}
+gnus | %:group, @r{for messages also all email fields}
+w3, w3m | %:url
+info | %:file %:node
+calendar | %:date"
+@end example
+
+@noindent
+To place the cursor after template expansion use:
+
+@example
+%? @r{After completing the template, position cursor here.}
+@end example
+
+@noindent
+If you change you mind about which template to use, call
+@code{org-remember} in the remember buffer. You may then select a new
+template that will be filled with the previous context information.
+
+@node Storing notes, , Remember templates, Remember
+@subsection Storing notes
+
+When you are finished preparing a note with @i{remember}, you have to press
+@kbd{C-c C-c} to file the note away. The handler first prompts for a
+target file - if you press @key{RET}, the value specified for the
+template is used. Then the command offers the headings tree of the
+selected file, with the cursor position at the default headline (if you
+had specified one in the template). You can either immediately press
+@key{RET} to get the note placed there. Or you can use the following
+keys to find a better location:
+@example
+@key{TAB} @r{Cycle visibility.}
+@key{down} / @key{up} @r{Next/previous visible headline.}
+n / p @r{Next/previous visible headline.}
+f / b @r{Next/previous headline same level.}
+u @r{One level up.}
+@c 0-9 @r{Digit argument.}
+@end example
+@noindent
+Pressing @key{RET} or @key{left} or @key{right}
+then leads to the following result.
+
+@multitable @columnfractions 0.2 0.15 0.65
+@item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted}
+@item buffer-start @tab @key{RET} @tab as level 2 heading at end of file
+@item on headline @tab @key{RET} @tab as sublevel of the heading at cursor
+@item @tab @key{left}/@key{right} @tab as same level, before/after current heading
+@item not on headline @tab @key{RET}
+ @tab at cursor position, level taken from context.
+@end multitable
+
+So a fast way to store the note to its default location is to press
+@kbd{C-c C-c @key{RET} @key{RET}}. Even shorter would be @kbd{C-u C-c
+C-c}, which does the same without even asking for a file or showing the
+tree.
+
+Before inserting the text into a tree, the function ensures that the
+text has a headline, i.e. a first line that starts with a @samp{*}.
+If not, a headline is constructed from the current date and some
+additional data. If the variable @code{org-adapt-indentation} is
+non-nil, the entire text is also indented so that it starts in the
+same column as the headline (after the asterisks).
+
+
+@node TODO items, Tags, Hyperlinks, Top
+@chapter TODO items
+@cindex TODO items
+
+Org-mode does not maintain TODO lists as a separate document. TODO
+items are an integral part of the notes file, because TODO items
+usually come up while taking notes! With Org-mode, you simply mark
+any entry in a tree as being a TODO item. In this way, the
+information is not duplicated, and the entire context from which the
+item emerged is always present when you check.
+
+Of course, this technique causes TODO items to be scattered throughout
+your file. Org-mode provides methods to give you an overview over all
+things you have to do.
+
+@menu
+* TODO basics:: Marking and displaying TODO entries
+* TODO extensions:: Workflow and assignments
+* Priorities:: Some things are more important than others
+* Breaking down tasks:: Splitting a task into manageable pieces
+* Checkboxes:: Tick-off lists
+@end menu
+
+@node TODO basics, TODO extensions, TODO items, TODO items
+@section Basic TODO functionality
+
+Any headline can become a TODO item by starting it with the word TODO,
+for example:
+
+@example
+*** TODO Write letter to Sam Fortune
+@end example
+
+@noindent
+The most important commands to work with TODO entries are:
+
+@table @kbd
+@kindex C-c C-t
+@cindex cycling, of TODO states
+@item C-c C-t
+Rotate the TODO state of the current item among
+
+@example
+,-> (unmarked) -> TODO -> DONE --.
+'--------------------------------'
+@end example
+
+The same rotation can also be done ``remotely'' from the timeline and
+agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
+@kindex S-@key{right}
+@kindex S-@key{left}
+@item S-@key{right}
+@itemx S-@key{left}
+Select the following/preceding TODO state, similar to cycling. Mostly
+useful if more than two TODO states are possible (@pxref{TODO
+extensions}).
+@kindex C-c C-c
+@item C-c C-c
+Use the fast tag interface to quickly and directly select a specific
+TODO state. For this you need to assign keys to TODO state, like this:
+@example
+#+SEQ_TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d)
+@end example
+@noindent See @ref{Per file keywords} and @ref{Setting tags} for more
+information.
+@kindex C-c C-v
+@cindex sparse tree, for TODO
+@item C-c C-v
+View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds
+the entire buffer, but shows all TODO items and the headings hierarchy
+above them. With prefix arg, search for a specific TODO. You will be
+prompted for the keyword, and you can also give a list of keywords like
+@code{kwd1|kwd2|...}. With numerical prefix N, show the tree for the
+Nth keyword in the variable @code{org-todo-keywords}. With two prefix
+args, find all TODO and DONE entries.
+@kindex C-c a t
+@item C-c a t
+Show the global TODO list. This collects the TODO items from all
+agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in
+@code{agenda-mode}, so there are commands to examine and manipulate
+the TODO entries directly from that buffer (@pxref{Agenda commands}).
+@xref{Global TODO list}, for more information.
+@kindex S-M-@key{RET}
+@item S-M-@key{RET}
+Insert a new TODO entry below the current one.
+@end table
+
+@node TODO extensions, Priorities, TODO basics, TODO items
+@section Extended use of TODO keywords
+@cindex extended TODO keywords
+
+The default implementation of TODO entries is just two states: TODO and
+DONE. You can use the TODO feature for more complicated things by
+configuring the variable @code{org-todo-keywords}. With special setup,
+the TODO keyword system can work differently in different files.
+
+Note that @i{tags} are another way to classify headlines in general and
+TODO items in particular (@pxref{Tags}).
+
+@menu
+* Workflow states:: From TODO to DONE in steps
+* TODO types:: I do this, Fred the rest
+* Multiple sets in one file:: Mixing it all, and still finding your way
+* Per file keywords:: Different files, different requirements
+@end menu
+
+@node Workflow states, TODO types, TODO extensions, TODO extensions
+@subsection TODO keywords as workflow states
+@cindex TODO workflow
+@cindex workflow states as TODO keywords
+
+You can use TODO keywords to indicate different @emph{sequential} states
+in the process of working on an item, for example@footnote{Changing
+this variable only becomes effective after restarting Org-mode in a
+buffer.}:
+
+@lisp
+(setq org-todo-keywords
+ '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
+@end lisp
+
+The vertical bar separates the TODO keywords (states that @emph{need
+action}) from the DONE states (which need @emph{no further action}. If
+you don't provide the separator bar, the last state is used as the DONE
+state.
+@cindex completion, of TODO keywords
+With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
+to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. You may
+also use a prefix argument to quickly select a specific state. For
+example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
+If you define many keywords, you can use in-buffer completion (see
+@ref{Completion}) to insert these words into the buffer. Changing a
+todo state can be logged with a timestamp, see @ref{Tracking TODO state
+changes} for more information.
+
+@node TODO types, Multiple sets in one file, Workflow states, TODO extensions
+@subsection TODO keywords as types
+@cindex TODO types
+@cindex names as TODO keywords
+@cindex types as TODO keywords
+
+The second possibility is to use TODO keywords to indicate different
+@emph{types} of action items. For example, you might want to indicate
+that items are for ``work'' or ``home''. Or, when you work with several
+people on a single project, you might want to assign action items
+directly to persons, by using their names as TODO keywords. This would
+be set up like this:
+
+@lisp
+(setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
+@end lisp
+
+In this case, different keywords do not indicate a sequence, but rather
+different types. So the normal work flow would be to assign a task to a
+person, and later to mark it DONE. Org-mode supports this style by
+adapting the workings of the command @kbd{C-c C-t}@footnote{This is also
+true for the @kbd{t} command in the timeline and agenda buffers.}. When
+used several times in succession, it will still cycle through all names,
+in order to first select the right type for a task. But when you return
+to the item after some time and execute @kbd{C-c C-t} again, it will
+switch from any name directly to DONE. Use prefix arguments or
+completion to quickly select a specific name. You can also review the
+items of a specific TODO type in a sparse tree by using a numeric prefix
+to @kbd{C-c C-v}. For example, to see all things Lucy has to do, you
+would use @kbd{C-3 C-c C-v}. To collect Lucy's items from all agenda
+files into a single buffer, you would use the prefix arg as well when
+creating the global todo list: @kbd{C-3 C-c t}.
+
+@node Multiple sets in one file, Per file keywords, TODO types, TODO extensions
+@subsection Multiple keyword sets in one file
+@cindex todo keyword sets
+
+Sometimes you may want to use different sets of TODO keywords in
+parallel. For example, you may want to have the basic
+@code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a
+separate state indicating that an item has been canceled (so it is not
+DONE, but also does not require action). Your setup would then look
+like this:
+
+@lisp
+(setq org-todo-keywords
+ '((sequence "TODO" "|" "DONE")
+ (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
+ (sequence "|" "CANCELED")))
+@end lisp
+
+The keywords should all be different, this helps Org-mode to keep track
+of which subsequence should be used for a given entry. In this setup,
+@kbd{C-c C-t} only operates within a subsequence, so it switches from
+@code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to
+(nothing) to @code{REPORT}. Therefore you need a mechanism to initially
+select the correct sequence. Besides the obvious ways like typing a
+keyword or using completion, you may also apply the following commands:
+
+@table @kbd
+@kindex C-S-@key{right}
+@kindex C-S-@key{left}
+@item C-S-@key{right}
+@itemx C-S-@key{left}
+These keys jump from one TODO subset to the next. In the above example,
+@kbd{C-S-@key{right}} would jump from @code{TODO} or @code{DONE} to
+@code{REPORT}, and any of the words in the second row to @code{CANCELED}.
+@kindex S-@key{right}
+@kindex S-@key{left}
+@item S-@key{right}
+@itemx S-@key{left}
+@kbd{S-@key{<left>}} and @kbd{S-@key{<right>}} and walk through
+@emph{all} keywords from all sets, so for example @kbd{S-@key{<right>}}
+would switch from @code{DONE} to @code{REPORT} in the example above.
+@end table
+
+@node Per file keywords, , Multiple sets in one file, TODO extensions
+@subsection Setting up keywords for individual files
+@cindex keyword options
+@cindex per file keywords
+
+It can be very useful to use different aspects of the TODO mechanism in
+different files. For file-local settings, you need to add special lines
+to the file which set the keywords and interpretation for that file
+only. For example, to set one of the two examples discussed above, you
+need one of the following lines, starting in column zero anywhere in the
+file:
+
+@example
+#+SEQ_TODO: TODO FEEDBACK VERIFY | DONE CANCELED
+@end example
+or
+@example
+#+TYP_TODO: Fred Sara Lucy Mike | DONE
+@end example
+
+A setup for using several sets in parallel would be:
+
+@example
+#+SEQ_TODO: TODO | DONE
+#+SEQ_TODO: REPORT BUG KNOWNCAUSE | FIXED
+#+SEQ_TODO: | CANCELED
+@end example
+
+@cindex completion, of option keywords
+@kindex M-@key{TAB}
+@noindent To make sure you are using the correct keyword, type
+@samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
+
+@cindex DONE, final TODO keyword
+Remember that the keywords after the vertical bar (or the last keyword
+if no bar is there) must always mean that the item is DONE (although you
+may use a different word). After changing one of these lines, use
+@kbd{C-c C-c} with the cursor still in the line to make the changes
+known to Org-mode@footnote{Org-mode parses these lines only when
+Org-mode is activated after visiting a file. @kbd{C-c C-c} with the
+cursor in a line starting with @samp{#+} is simply restarting Org-mode
+for the current buffer.}.
+
+@node Priorities, Breaking down tasks, TODO extensions, TODO items
+@section Priorities
+@cindex priorities
+
+If you use Org-mode extensively to organize your work, you may end up
+with a number of TODO entries so large that you'd like to prioritize
+them. This can be done by placing a @emph{priority cookie} into the
+headline, like this
+
+@example
+*** TODO [#A] Write letter to Sam Fortune
+@end example
+
+@noindent
+With its standard setup, Org-mode supports priorities @samp{A},
+@samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry
+without a cookie is treated as priority @samp{B}. Priorities make a
+difference only in the agenda (@pxref{Weekly/Daily agenda}).
+
+@table @kbd
+@kindex @kbd{C-c ,}
+@item @kbd{C-c ,}
+Set the priority of the current headline. The command prompts for a
+priority character @samp{A}, @samp{B} or @samp{C}. When you press
+@key{SPC} instead, the priority cookie is removed from the headline.
+The priorities can also be changed ``remotely'' from the timeline and
+agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
+@c
+@kindex S-@key{up}
+@kindex S-@key{down}
+@item S-@key{up}
+@itemx S-@key{down}
+Increase/decrease priority of current headline. Note that these keys
+are also used to modify time stamps (@pxref{Creating timestamps}).
+Furthermore, these keys are also used by CUA-mode (@pxref{Conflicts}).
+@end table
+
+You can change the range of allowed priorities by setting the variables
+@code{org-highest-priority}, @code{org-lowest-priority}, and
+@code{org-default-priority}. For an individual buffer, you may set
+these values (highest, lowest, default) like this (please make sure that
+the highest priority is earlier in the alphabet than the lowest
+priority):
+
+@example
+#+PRIORITIES: A C B
+@end example
+
+@node Breaking down tasks, Checkboxes, Priorities, TODO items
+@section Breaking tasks down into subtasks
+@cindex tasks, breaking down
+
+It is often advisable to break down large tasks into smaller, manageable
+subtasks. You can do this by creating an outline tree below a TODO
+item, with detailed subtasks on the tree@footnote{To keep subtasks out
+of the global TODO list, see the
+@code{org-agenda-todo-list-sublevels}.}. Another possibility is the use
+of checkboxes to identify (a hierarchy of) a large number of subtasks
+(@pxref{Checkboxes}).
+
+
+@node Checkboxes, , Breaking down tasks, TODO items
+@section Checkboxes
+@cindex checkboxes
+
+Every item in a plain list (@pxref{Plain lists}) can be made a checkbox
+by starting it with the string @samp{[ ]}. This feature is similar to
+TODO items (@pxref{TODO items}), but more lightweight. Checkboxes are
+not included into the global TODO list, so they are often great to split
+a task into a number of simple steps. Or you can use them in a shopping
+list. To toggle a checkbox, use @kbd{C-c C-c}, or try Piotr Zielinski's
+@file{org-mouse.el}. Here is an example of a checkbox list.
+
+@example
+* TODO Organize party [3/6]
+ - call people [1/3]
+ - [ ] Peter
+ - [X] Sarah
+ - [ ] Sam
+ - [X] order food
+ - [ ] think about what music to play
+ - [X] talk to the neighbors
+@end example
+
+@cindex statistics, for checkboxes
+@cindex checkbox statistics
+The @samp{[3/6]} and @samp{[1/3]} in the first and second line are
+cookies indicating how many checkboxes are present in this entry, and
+how many of them have been checked off. This can give you an idea on
+how many checkboxes remain, even without opening a folded entry. The
+cookies can be placed into a headline or into (the first line of) a
+plain list item. Each cookie covers all checkboxes structurally below
+that headline/item. You have to insert the cookie yourself by typing
+either @samp{[/]} or @samp{[%]}. In the first case you get an @samp{n
+out of m} result, in the second case you get information about the
+percentage of checkboxes checked (in the above example, this would be
+@samp{[50%]} and @samp{[33%], respectively}).
+
+@noindent The following commands work with checkboxes:
+
+@table @kbd
+@kindex C-c C-c
+@item C-c C-c
+Toggle checkbox at point. With prefix argument, set it to @samp{[-]},
+which is considered to be an intermediate state.
+@kindex C-c C-x C-b
+@item C-c C-x C-b
+Toggle checkbox at point.
+@itemize @minus
+@item
+If there is an active region, toggle the first checkbox in the region
+and set all remaining boxes to the same status as the first. If you
+want to toggle all boxes in the region independently, use a prefix
+argument.
+@item
+If the cursor is in a headline, toggle checkboxes in the region between
+this headline and the next (so @emph{not} the entire subtree).
+@item
+If there is no active region, just toggle the checkbox at point.
+@end itemize
+@kindex M-S-@key{RET}
+@item M-S-@key{RET}
+Insert a new item with a checkbox.
+This works only if the cursor is already in a plain list item
+(@pxref{Plain lists}).
+@kindex C-c #
+@item C-c #
+Update the checkbox statistics in the current outline entry. When
+called with a @kbd{C-u} prefix, update the entire file. Checkbox
+statistic cookies are updated automatically if you toggle checkboxes
+with @kbd{C-c C-c} and make new ones with @kbd{M-S-@key{RET}}. If you
+delete boxes or add/change them by hand, use this command to get things
+back into synch. Or simply toggle any checkbox twice with @kbd{C-c C-c}.
+@end table
+
+
+@node Tags, Properties and columns, TODO items, Top
+@chapter Tags
+@cindex tags
+@cindex headline tagging
+@cindex matching, tags
+@cindex sparse tree, tag based
+
+If you wish to implement a system of labels and contexts for
+cross-correlating information, an excellent way is to assign @i{tags} to
+headlines. Org-mode has extensive support for using tags.
+
+Every headline can contain a list of tags, at the end of the headline.
+Tags are normal words containing letters, numbers, @samp{_}, and
+@samp{@@}. Tags must be preceded and followed by a single colon; like
+@samp{:WORK:}. Several tags can be specified like @samp{:WORK:URGENT:}.
+
+@menu
+* Tag inheritance:: Tags use the tree structure of the outline
+* Setting tags:: How to assign tags to a headline
+* Tag searches:: Searching for combinations of tags
+@end menu
+
+@node Tag inheritance, Setting tags, Tags, Tags
+@section Tag inheritance
+@cindex inheritance, of tags
+@cindex sublevels, inclusion into tags match
+
+@i{Tags} make use of the hierarchical structure of outline trees. If a
+heading has a certain tag, all subheadings will inherit the tag as
+well. For example, in the list
+
+@example
+* Meeting with the French group :WORK:
+** Summary by Frank :BOSS:NOTES:
+*** TODO Prepare slides for him :ACTION:
+@end example
+
+@noindent
+the final heading will have the tags @samp{:WORK:}, @samp{:BOSS:},
+@samp{:NOTES:}, and @samp{:ACTION:}. When executing tag searches and
+Org-mode finds that a certain headline matches the search criterion, it
+will not check any sublevel headline, assuming that these likely also
+match, and that the list of matches can become very long. This may
+not be what you want, however, and you can influence inheritance and
+searching using the variables @code{org-use-tag-inheritance} and
+@code{org-tags-match-list-sublevels}.
+
+@node Setting tags, Tag searches, Tag inheritance, Tags
+@section Setting tags
+@cindex setting tags
+@cindex tags, setting
+
+@kindex M-@key{TAB}
+Tags can simply be typed into the buffer at the end of a headline.
+After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
+also a special command for inserting tags:
+
+@table @kbd
+@kindex C-c C-c
+@item C-c C-c
+@cindex completion, of tags
+Enter new tags for the current headline. Org-mode will either offer
+completion or a special single-key interface for setting tags, see
+below. After pressing @key{RET}, the tags will be inserted and aligned
+to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
+tags in the current buffer will be aligned to that column, just to make
+things look nice. TAGS are automatically realigned after promotion,
+demotion, and TODO state changes (@pxref{TODO basics}).
+@end table
+
+Org will support tag insertion based on a @emph{list of tags}. By
+default this list is constructed dynamically, containing all tags
+currently used in the buffer. You may also globally specify a hard list
+of tags with the variable @code{org-tag-alist}. Finally you can set
+the default tags for a given file with lines like
+
+@example
+#+TAGS: @@WORK @@HOME @@TENNISCLUB
+#+TAGS: Laptop Car PC Sailboat
+@end example
+
+If you have globally defined your preferred set of tags using the
+variable @code{org-tag-alist}, but would like to use a dynamic tag list
+in a specific file: Just add an empty TAGS option line to that file:
+
+@example
+#+TAGS:
+@end example
+
+The default support method for entering tags is minibuffer completion.
+However, Org-mode also implements a much better method: @emph{fast tag
+selection}. This method allows to select and deselect tags with a
+single key per tag. To function efficiently, you should assign unique
+keys to most tags. This can be done globally with
+
+@lisp
+(setq org-tag-alist '(("@@WORK" . ?w) ("@@HOME" . ?h) ("Laptop" . ?l)))
+@end lisp
+
+@noindent or on a per-file basis with
+
+@example
+#+TAGS: @@WORK(w) @@HOME(h) @@TENNISCLUB(t) Laptop(l) PC(p)
+@end example
+
+@noindent
+You can also group together tags that are mutually exclusive. With
+curly braces@footnote{In @code{org-mode-alist} use
+@code{'(:startgroup)} and @code{'(:endgroup)}, respectively. Several
+groups are allowed.}
+
+@example
+#+TAGS: @{ @@WORK(w) @@HOME(h) @@TENNISCLUB(t) @} Laptop(l) PC(p)
+@end example
+
+@noindent you indicate that at most one of @samp{@@WORK}, @samp{@@HOME},
+and @samp{@@TENNISCLUB} should be selected.
+
+@noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
+these lines to activate any changes.
+
+If at least one tag has a selection key, pressing @kbd{C-c C-c} will
+automatically present you with a special interface, listing inherited
+tags, the tags of the current headline, and a list of all legal tags
+with corresponding keys@footnote{Keys will automatically be assigned to
+tags which have no configured keys.}. In this interface, you can use
+the following keys:
+
+@table @kbd
+@item a-z...
+Pressing keys assigned to tags will add or remove them from the list of
+tags in the current line. Selecting a tag in a group of mutually
+exclusive tags will turn off any other tags from that group.
+@kindex @key{TAB}
+@item @key{TAB}
+Enter a tag in the minibuffer, even if the tag is not in the predefined
+list. You will be able to complete on all tags present in the buffer.
+@kindex @key{SPC}
+@item @key{SPC}
+Clear all tags for this line.
+@kindex @key{RET}
+@item @key{RET}
+Accept the modified set.
+@item C-g
+Abort without installing changes.
+@item q
+If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
+@item !
+Turn off groups of mutually exclusive tags. Use this to (as an
+exception) assign several tags from such a group.
+@item C-c
+Toggle auto-exit after the next change (see below).
+If you are using expert mode, the first @kbd{C-c} will display the
+selection window.
+@end table
+
+@noindent
+This method lets you assign tags to a headline with very few keys. With
+the above setup, you could clear the current tags and set @samp{@@HOME},
+@samp{Laptop} and @samp{PC} tags with just the following keys: @kbd{C-c
+C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@HOME} to
+@samp{@@WORK} would be done with @kbd{C-c C-c w @key{RET}} or
+alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag
+@samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h
+@key{RET} @key{RET}}.
+
+If you find that most of the time, you need only a single keypress to
+modify your list of tags, set the variable
+@code{org-fast-tag-selection-single-key}. Then you no longer have to
+press @key{RET} to exit fast tag selection - it will immediately exit
+after the first change. If you then occasionally need more keys, press
+@kbd{C-c} to turn off auto-exit for the current tag selection process
+(in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-c
+C-c}). If you set the variable to the value @code{expert}, the special
+window is not even shown for single-key tag selection, it comes up only
+when you press an extra @kbd{C-c}.
+
+@node Tag searches, , Setting tags, Tags
+@section Tag searches
+@cindex tag searches
+@cindex searching for tags
+
+Once a tags system has been set up, it can be used to collect related
+information into special lists.
+
+@table @kbd
+@kindex C-c \
+@item C-c \
+Create a sparse tree with all headlines matching a tags search. With a
+@kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
+@kindex C-c a m
+@item C-c a m
+Create a global list of tag matches from all agenda files.
+@xref{Matching tags and properties}.
+@kindex C-c a M
+@item C-c a M
+Create a global list of tag matches from all agenda files, but check
+only TODO items and force checking subitems (see variable
+@code{org-tags-match-list-sublevels}).
+@end table
+
+@cindex Boolean logic, for tag searches
+A @i{tags} search string can use Boolean operators @samp{&} for AND and
+@samp{|} for OR. @samp{&} binds more strongly than @samp{|}.
+Parenthesis are currently not implemented. A tag may also be preceded
+by @samp{-}, to select against it, and @samp{+} is syntactic sugar for
+positive selection. The AND operator @samp{&} is optional when @samp{+}
+or @samp{-} is present. Examples:
+
+@table @samp
+@item +WORK-BOSS
+Select headlines tagged @samp{:WORK:}, but discard those also tagged
+@samp{:BOSS:}.
+@item WORK|LAPTOP
+Selects lines tagged @samp{:WORK:} or @samp{:LAPTOP:}.
+@item WORK|LAPTOP&NIGHT
+Like before, but require the @samp{:LAPTOP:} lines to be tagged also
+@samp{NIGHT}.
+@end table
+
+@cindex TODO keyword matching, with tags search
+If you are using multi-state TODO keywords (@pxref{TODO extensions}), it
+can be useful to also match on the TODO keyword. This can be done by
+adding a condition after a slash to a tags match. The syntax is similar
+to the tag matches, but should be applied with consideration: For
+example, a positive selection on several TODO keywords can not
+meaningfully be combined with boolean AND. However, @emph{negative
+selection} combined with AND can be meaningful. To make sure that only
+lines are checked that actually have any TODO keyword, use @kbd{C-c a
+M}, or equivalently start the todo part after the slash with @samp{!}.
+Examples:
+
+@table @samp
+@item WORK/WAITING
+Select @samp{:WORK:}-tagged TODO lines with the specific TODO
+keyword @samp{WAITING}.
+@item WORK/!-WAITING-NEXT
+Select @samp{:WORK:}-tagged TODO lines that are neither @samp{WAITING}
+nor @samp{NEXT}
+@item WORK/+WAITING|+NEXT
+Select @samp{:WORK:}-tagged TODO lines that are either @samp{WAITING} or
+@samp{NEXT}.
+@end table
+
+@cindex regular expressions, with tags search
+Any element of the tag/todo match can be a regular expression - in this
+case it must be enclosed in curly braces. For example,
+@samp{WORK+@{^BOSS.*@}} matches headlines that contain the tag
+@samp{WORK} and any tag @i{starting} with @samp{BOSS}.
+
+@cindex level, require for tags match
+You can also require a headline to be of a certain level, by writing
+instead of any TAG an expression like @samp{LEVEL=3}. For example, a
+search @samp{+LEVEL=3+BOSS/-DONE} lists all level three headlines that
+have the tag BOSS and are @emph{not} marked with the todo keyword DONE.
+
+@node Properties and columns, Timestamps, Tags, Top
+@chapter Properties and Columns
+@cindex properties
+
+Properties are a set of key-value pairs associated with an entry. There
+are two main applications for properties in Org-mode. First, properties
+are like tags, but with a value. For example, in a file where you
+document bugs and plan releases of a piece of software, instead of using
+tags like @code{:release_1:}, @code{:release_2:}, it can be more
+efficient to use a property @code{RELEASE} with a value @code{1.0} or
+@code{2.0}. Second, you can use properties to implement (very basic)
+database capabilities in an Org-mode buffer, for example to create a
+list of Music CD's you own. You can edit and view properties
+conveniently in column view (@pxref{Column view}).
+
+@menu
+* Property syntax:: How properties are spelled out
+* Special properties:: Access to other Org-mode features
+* Property searches:: Matching property values
+* Column view:: Tabular viewing and editing
+* Property API:: Properties for Lisp programmers
+@end menu
+
+@node Property syntax, Special properties, Properties and columns, Properties and columns
+@section Property Syntax
+@cindex property syntax
+@cindex drawer, for properties
+
+Properties are key-value pairs. They need to be inserted into a special
+drawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each property
+is specified on a single line, with the key (surrounded by colons)
+first, and the value after it. Here is an example:
+
+@example
+* CD collection
+** Classic
+*** Goldberg Variations
+ :PROPERTIES:
+ :Title: Goldberg Variations
+ :Composer: J.S. Bach
+ :Artist: Glen Gould
+ :Publisher: Deutsche Grammphon
+ :NDisks: 1
+ :END:
+@end example
+
+You may define the allowed values for a particular property @samp{XYZ}
+by setting a property @samp{XYZ_ALL}. This special property is
+@emph{inherited}, so if you set it in a level 1 entry, it will apply to
+the entire tree. When allowed values are defined, setting the
+corresponding property becomes easier and is less prone to typing
+errors. For the example with the CD collection, we can predefine
+publishers and the number of disks in a box like this:
+
+@example
+* CD collection
+ :PROPERTIES:
+ :NDisks_ALL: 1 2 3 4
+ :Publisher_ALL: "Deutsche Grammophon" Phillips EMI
+ :END:
+@end example
+
+If you want to set properties that can be inherited by any entry in a
+file, use a line like
+
+@example
+#+PROPERTY: NDisks_ALL 1 2 3 4
+@end example
+
+Property values set with the global variable
+@code{org-global-properties} can be inherited by all entries in all
+Org-mode files.
+
+@noindent
+The following commands help to work with properties:
+
+@table @kbd
+@kindex M-@key{TAB}
+@item M-@key{TAB}
+After an initial colon in a line, complete property keys. All keys used
+in the current file will be offered as possible completions.
+@item M-x org-insert-property-drawer
+Insert a property drawer into the current entry. The drawer will be
+inserted early in the entry, but after the lines with planning
+information like deadlines.
+@kindex C-c C-c
+@item C-c C-c
+With the cursor in a property drawer, this executes property commands.
+@item C-c C-c s
+Set a property in the current entry. Both the property and the value
+can be inserted using completion.
+@kindex S-@key{right}
+@kindex S-@key{left}
+@item S-@key{left}/@key{right}
+Switch property at point to the next/previous allowed value.
+@item C-c C-c d
+Remove a property from the current entry.
+@item C-c C-c D
+Globally remove a property, from all entries in the current file.
+@end table
+
+@node Special properties, Property searches, Property syntax, Properties and columns
+@section Special Properties
+@cindex properties, special
+
+Special properties provide alternative access method to Org-mode
+features discussed in the previous chapters, like the TODO state or the
+priority of an entry. This interface exists so that you can include
+these states into columns view (@pxref{Column view}). The following
+property names are special and should not be used as keys in the
+properties drawer:
+
+@example
+TODO @r{The TODO keyword of the entry.}
+TAGS @r{The tags defined directly in the headline.}
+ALLTAGS @r{All tags, including inherited ones.}
+PRIORITY @r{The priority of the entry, a string with a single letter.}
+DEADLINE @r{The deadline time string, without the angular brackets.}
+SCHEDULED @r{The scheduling time stamp, without the angular brackets.}
+@end example
+
+@node Property searches, Column view, Special properties, Properties and columns
+@section Property searches
+@cindex properties, searching
+
+To create sparse trees and special lists with selection based on
+properties, the same commands are used as for tag searches (@pxref{Tag
+searches}), and the same logic applies. For example, a search string
+
+@example
++WORK-BOSS+PRIORITY="A"+coffee="unlimited"+with=@{Sarah\|Denny@}
+@end example
+
+@noindent
+finds entries tagged @samp{:WORK:} but not @samp{:BOSS:}, which
+also have a priority value @samp{A}, a @samp{:coffee:} property with the
+value @samp{unlimited}, and a @samp{:with:} property that is matched by
+the regular expression @samp{Sarah\|Denny}.
+
+@node Column view, Property API, Property searches, Properties and columns
+@section Column View
+
+A great way to view and edit properties in an outline tree is
+@emph{column view}. In column view, each outline item is turned into a
+table row. Columns in this table provide access to properties of the
+entries. Org-mode implements columns by overlaying a tabular structure
+over the headline of each item. While the headlines have been turned
+into a table row, you can still change the visibility of the outline
+tree. For example, you get a compact table by switching to CONTENTS
+view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view
+is active), but you can still open, read, and edit the entry below each
+headline. Or, you can switch to column view after executing a sparse
+tree command and in this way get a table only for the selected items.
+Column view also works in agenda buffers (@pxref{Agenda views}) where
+queries have collected selected items, possibly from a number of files.
+
+@menu
+* Defining columns:: The COLUMNS format property
+* Using column view:: How to create and use column view
+@end menu
+
+@node Defining columns, Using column view, Column view, Column view
+@subsection Defining Columns
+@cindex column view, for properties
+@cindex properties, column view
+
+Setting up a column view first requires defining the columns. This is
+done by defining a column format line.
+
+@menu
+* Scope of column definitions:: Where defined, where valid?
+* Column attributes:: Appearance and content of a column
+@end menu
+
+@node Scope of column definitions, Column attributes, Defining columns, Defining columns
+@subsubsection Scope of column definitions
+
+To define a column format for an entire file, use a line like
+
+@example
+#+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
+@end example
+
+To specify a format that only applies to a specific tree, add a COLUMNS
+property to the top node of that tree, for example
+@example
+** Top node for columns view
+ :PROPERTIES:
+ :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
+ :END:
+@end example
+
+If a @code{COLUMNS} property is present in an entry, it defines columns
+for the entry itself, and for the entire subtree below it. Since the
+column definition is part of the hierarchical structure of the document,
+you can define columns on level 1 that are general enough for all
+sublevels, and more specific columns further down, when you edit a
+deeper part of the tree.
+
+@node Column attributes, , Scope of column definitions, Defining columns
+@subsubsection Column attributes
+A column definition sets the attributes of a column. The general
+definition looks like this:
+
+@example
+ %[width]property[(title)][@{summary-type@}]
+@end example
+
+@noindent
+Except for the percent sign and the property name, all items are
+optional. The individual parts have the following meaning:
+
+@example
+width @r{An integer specifying the width of the column in characters.}
+ @r{If omitted, the width will be determined automatically.}
+property @r{The property that should be edited in this column.}
+(title) @r{The header text for the column. If omitted, the}
+ @r{property name is used.}
+@{summary-type@} @r{The summary type. If specified, the column values for}
+ @r{parent nodes are computed from the children.}
+ @r{Supported summary types are:}
+ @{+@} @r{Sum numbers in this column.}
+ @{:@} @r{Sum times, HH:MM:SS, plain numbers are hours.}
+ @{X@} @r{Checkbox status, [X] if all children are [X].}
+@end example
+
+@noindent
+Here is an example for a complete columns definition, along with allowed
+values.
+
+@example
+:COLUMNS: %20ITEM %9Approved(Approved?)@{X@} %Owner %11Status %10Time_Spent@{:@}
+:Owner_ALL: Tammy Mark Karl Lisa Don
+:Status_ALL: "In progress" "Not started yet" "Finished" ""
+:Approved_ALL: "[ ]" "[X]"
+@end example
+
+The first column, @samp{%25ITEM}, means the first 25 characters of the
+item itself, i.e. of the headline. You probably always should start the
+column definition with the ITEM specifier. The other specifiers create
+columns @samp{Owner} with a list of names as allowed values, for
+@samp{Status} with four different possible values, and for a checkbox
+field @samp{Approved}. When no width is given after the @samp{%}
+character, the column will be exactly as wide as it needs to be in order
+to fully display all values. The @samp{Approved} column does have a
+modified title (@samp{Approved?}, with a question mark). Summaries will
+be created for the @samp{Time_Spent} column by adding time duration
+expressions like HH:MM, and for the @samp{Approved} column, by providing
+an @samp{[X]} status if all children have been checked.
+
+@node Using column view, , Defining columns, Column view
+@subsection Using Column View
+
+@table @kbd
+@tsubheading{Turning column view on and off}
+@kindex C-c C-x C-c
+@item C-c C-x C-c
+Create the column view for the local environment. This command searches
+the hierarchy, up from point, for a @code{COLUMNS} property that defines
+a format. When one is found, the column view table is established for
+the entire tree, starting from the entry that contains the @code{COLUMNS}
+property. If none is found, the format is taken from the @code{#+COLUMNS}
+line or from the variable @code{org-columns-default-format}, and column
+view is established for the current entry and its subtree.
+@kindex q
+@item q
+Exit column view.
+@tsubheading{Editing values}
+@item @key{left} @key{right} @key{up} @key{down}
+Move through the column view from field to field.
+@kindex S-@key{left}
+@kindex S-@key{right}
+@item S-@key{left}/@key{right}
+Switch to the next/previous allowed value of the field. For this, you
+have to have specified allowed values for a property.
+@kindex n
+@kindex p
+@itemx n / p
+Same as @kbd{S-@key{left}/@key{right}}
+@kindex e
+@item e
+Edit the property at point. For the special properties, this will
+invoke the same interface that you normally use to change that
+property. For example, when editing a TAGS property, the tag completion
+or fast selection interface will pop up.
+@kindex v
+@item v
+View the full value of this property. This is useful if the width of
+the column is smaller than that of the value.
+@kindex a
+@item a
+Edit the list of allowed values for this property. If the list is found
+in the hierarchy, the modified values is stored there. If no list is
+found, the new value is stored in the first entry that is part of the
+current column view.
+@tsubheading{Modifying the table structure}
+@kindex <
+@kindex >
+@item < / >
+Make the column narrower/wider by one character.
+@kindex S-M-@key{right}
+@item S-M-@key{right}
+Insert a new column, to the right of the current column.
+@kindex S-M-@key{left}
+@item S-M-@key{left}
+Delete the current column.
+@end table
+
+@node Property API, , Column view, Properties and columns
+@section The Property API
+@cindex properties, API
+@cindex API, for properties
+
+There is a full API for accessing and changing properties. This API can
+be used by Emacs Lisp programs to work with properties and to implement
+features based on them. For more information see @ref{Using the
+property API}.
+
+@node Timestamps, Agenda views, Properties and columns, Top
+@chapter Timestamps
+@cindex time stamps
+@cindex date stamps
+
+Items can be labeled with timestamps to make them useful for project
+planning.
+
+@menu
+* Time stamps:: Assigning a time to a tree entry
+* Creating timestamps:: Commands which insert timestamps
+* Deadlines and scheduling:: Planning your work
+* Progress logging:: Documenting when what work was done.
+@end menu
+
+
+@node Time stamps, Creating timestamps, Timestamps, Timestamps
+@section Time stamps, deadlines and scheduling
+@cindex time stamps
+@cindex ranges, time
+@cindex date stamps
+@cindex deadlines
+@cindex scheduling
+
+A time stamp is a specification of a date (possibly with time or a range
+of times) in a special format, either @samp{<2003-09-16 Tue>} or
+@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue
+12:00-12:30>}@footnote{This is the standard ISO date/time format. If
+you cannot get used to these, see @ref{Custom time format}}. A time
+stamp can appear anywhere in the headline or body of an org-tree entry.
+Its presence causes entries to be shown on specific dates in the agenda
+(@pxref{Weekly/Daily agenda}). We distinguish:
+
+@table @var
+@item Plain time stamp
+@cindex timestamp
+A simple time stamp just assigns a date/time to an item. This is just
+like writing down an appointment in a paper agenda, or like writing down
+an event in a diary, when you want to take note of when something
+happened. In the timeline and agenda displays, the headline of an entry
+associated with a plain time stamp will be shown exactly on that date.
+
+@example
+* Meet Peter at the movies <2006-11-01 Wed 19:15>
+* Discussion on climate change <2006-11-02 Thu 20:00-22:00>
+@end example
+
+@item Time stamp with repeater interval
+@cindex timestamp, with repeater interval
+A time stamp may contain a @emph{repeater interval}, indicating that it
+applies not only on the given date, but again and again after a certain
+interval of N days (d), weeks (w), months(m), or years(y). The
+following will show up in the agenda every Wednesday:
+
+@example
+* Pick up Sam at school <2007-05-16 Wed 12:30 +1w>
+@end example
+
+@item Diary-style sexp entries
+For more complex date specifications, Org-mode supports using the
+special sexp diary entries implemented in the Emacs calendar/diary
+package. For example
+
+@example
+* The nerd meeting on every 2nd Thursday of the month
+ <%%(diary-float t 4 2)>
+@end example
+
+@item Time/Date range
+@cindex timerange
+@cindex date range
+Two time stamps connected by @samp{--} denote a range. The headline
+will be shown on the first and last day of the range, and on any dates
+that are displayed and fall in the range. Here is an example:
+
+@example
+** Meeting in Amsterdam
+ <2004-08-23 Mon>--<2004-08-26 Thu>
+@end example
+
+@item Inactive time stamp
+@cindex timestamp, inactive
+@cindex inactive timestamp
+Just like a plain time stamp, but with square brackets instead of
+angular ones. These time stamps are inactive in the sense that they do
+@emph{not} trigger an entry to show up in the agenda.
+
+@example
+* Gillian comes late for the fifth time [2006-11-01 Wed]
+@end example
+
+@end table
+
+@node Creating timestamps, Deadlines and scheduling, Time stamps, Timestamps
+@section Creating timestamps
+@cindex creating timestamps
+@cindex timestamps, creating
+
+For Org-mode to recognize time stamps, they need to be in the specific
+format. All commands listed below produce time stamps in the correct
+format.
+
+@table @kbd
+@kindex C-c .
+@item C-c .
+Prompt for a date and insert a corresponding time stamp. When the
+cursor is at a previously used time stamp, it is updated to NOW. When
+this command is used twice in succession, a time range is inserted.
+@c
+@kindex C-u C-c .
+@item C-u C-c .
+Like @kbd{C-c .}, but use the alternative format which contains date
+and time. The default time can be rounded to multiples of 5 minutes,
+see the option @code{org-time-stamp-rounding-minutes}.
+@c
+@kindex C-c !
+@item C-c !
+Like @kbd{C-c .}, but insert an inactive time stamp that will not cause
+an agenda entry.
+@c
+@kindex C-c <
+@item C-c <
+Insert a time stamp corresponding to the cursor date in the Calendar.
+@c
+@kindex C-c >
+@item C-c >
+Access the Emacs calendar for the current date. If there is a
+timestamp in the current line, goto the corresponding date
+instead.
+@c
+@kindex C-c C-o
+@item C-c C-o
+Access the agenda for the date given by the time stamp or -range at
+point (@pxref{Weekly/Daily agenda}).
+@c
+@kindex S-@key{left}
+@kindex S-@key{right}
+@item S-@key{left}
+@itemx S-@key{right}
+Change date at cursor by one day. These key bindings conflict with
+CUA-mode (@pxref{Conflicts}).
+@c
+@kindex S-@key{up}
+@kindex S-@key{down}
+@item S-@key{up}
+@itemx S-@key{down}
+Change the item under the cursor in a timestamp. The cursor can be on a
+year, month, day, hour or minute. Note that if the cursor is in a
+headline and not at a time stamp, these same keys modify the priority of
+an item. (@pxref{Priorities}). The key bindings also conflict with
+CUA-mode (@pxref{Conflicts}).
+@c
+@kindex C-c C-y
+@cindex evaluate time range
+@item C-c C-y
+Evaluate a time range by computing the difference between start and
+end. With prefix arg, insert result after the time range (in a table:
+into the following column).
+@end table
+
+
+@menu
+* The date/time prompt:: How org-mode helps you entering date and time
+* Custom time format:: Making dates look differently
+@end menu
+
+@node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps
+@subsection The date/time prompt
+@cindex date, reading in minibuffer
+@cindex time, reading in minibuffer
+
+When Org-mode prompts for a date/time, the prompt suggests to enter an
+ISO date. But it will in fact accept any string containing some date
+and/or time information. You can, for example, use @kbd{C-y} to paste a
+(possibly multi-line) string copied from an email message. Org-mode
+will find whatever information is in there and will replace anything not
+specified with the current date and time. For example:
+
+@example
+ 3-2-5 --> 2003-02-05
+ feb 15 --> currentyear-02-15
+ sep 12 9 --> 2009-09-12
+ 12:45 --> today 12:45
+ 22 sept 0:34 --> currentyear-09-22 0:34
+ 12 --> currentyear-currentmonth-12
+ Fri --> nearest Friday (today or later)
+ +4 --> 4 days from now (if +N is the only thing given)
+@end example
+
+The function understands English month and weekday abbreviations. If
+you want to use unabbreviated names and/or other languages, configure
+the variables @code{parse-time-months} and @code{parse-time-weekdays}.
+
+@cindex calendar, for selecting date
+Parallel to the minibuffer prompt, a calendar is popped up@footnote{If
+you don't need/want the calendar, configure the variable
+@code{org-popup-calendar-for-date-prompt}.}. When you exit the date
+prompt, either by clicking on a date in the calendar, or by pressing
+@key{RET}, the date selected in the calendar will be combined with the
+information entered at the prompt. You can control the calendar fully
+from the minibuffer:
+
+@table @kbd
+@kindex <
+@item <
+Scroll calendar backwards by one month.
+@kindex >
+@item >
+Scroll calendar forwards by one month.
+@kindex mouse-1
+@item mouse-1
+Select date by clicking on it.
+@kindex S-@key{right}
+@item S-@key{right}
+One day forward.
+@kindex S-@key{left}
+@item S-@key{left}
+One day back.
+@kindex S-@key{down}
+@item S-@key{down}
+One week forward.
+@kindex S-@key{up}
+@item S-@key{up}
+One week back.
+@kindex M-S-@key{right}
+@item M-S-@key{right}
+One month forward.
+@kindex M-S-@key{left}
+@item M-S-@key{left}
+One month back.
+@kindex @key{RET}
+@item @key{RET}
+Choose date in calendar (only if nothing was typed into minibuffer).
+@end table
+
+@node Custom time format, , The date/time prompt, Creating timestamps
+@subsection Custom time format
+@cindex custom date/time format
+@cindex time format, custom
+@cindex date format, custom
+
+Org-mode uses the standard ISO notation for dates and times as it is
+defined in ISO 8601. If you cannot get used to this and require another
+representation of date and time to keep you happy, you can get it by
+customizing the variables @code{org-display-custom-times} and
+@code{org-time-stamp-custom-formats}.
+
+@table @kbd
+@kindex C-c C-x C-t
+@item C-c C-x C-t
+Toggle the display of custom formats for dates and times.
+@end table
+
+@noindent
+Org-mode needs the default format for scanning, so the custom date/time
+format does not @emph{replace} the default format - instead it is put
+@emph{over} the default format using text properties. This has the
+following consequences:
+@itemize @bullet
+@item
+You cannot place the cursor onto a time stamp anymore, only before or
+after.
+@item
+The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust
+each component of a time stamp. If the cursor is at the beginning of
+the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day,
+just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, the
+time will be changed by one minute.
+@item
+If the time stamp contains a range of clock times or a repeater, these
+will not be overlayed, but remain in the buffer as they were.
+@item
+When you delete a time stamp character-by-character, it will only
+disappear from the buffer after @emph{all} (invisible) characters
+belonging to the ISO timestamp have been removed.
+@item
+If the custom time stamp format is longer than the default and you are
+using dates in tables, table alignment will be messed up. If the custom
+format is shorter, things do work as expected.
+@end itemize
+
+
+@node Deadlines and scheduling, Progress logging, Creating timestamps, Timestamps
+@section Deadlines and Scheduling
+
+A time stamp may be preceded by special keywords to facilitate planning
+of work:
+
+@table @var
+@item DEADLINE
+@cindex DEADLINE keyword
+The task (most likely a TODO item) is supposed to be finished on that
+date, and it will be listed then. In addition, the compilation for
+@emph{today} will carry a warning about the approaching or missed
+deadline, starting @code{org-deadline-warning-days} before the due date,
+and continuing until the entry is marked DONE. An example:
+
+@example
+*** TODO write article about the Earth for the Guide
+ The editor in charge is [[bbdb:Ford Prefect]]
+ DEADLINE: <2004-02-29 Sun>
+@end example
+
+You can specify a different lead time for warnings for a specific
+deadlines using the following syntax. Here is an example with a warning
+period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}.
+
+@item SCHEDULED
+@cindex SCHEDULED keyword
+You are planning to start working on that task on the given date. The
+headline will be listed under the given date@footnote{It will still be
+listed on that date after it has been marked DONE. If you don't like
+this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
+addition, a reminder that the scheduled date has passed will be present
+in the compilation for @emph{today}, until the entry is marked DONE.
+I.e., the task will automatically be forwarded until completed.
+
+@example
+*** TODO Call Trillian for a date on New Years Eve.
+ SCHEDULED: <2004-12-25 Sat>
+@end example
+@end table
+
+@menu
+* Inserting deadline/schedule:: Planning items
+* Repeated tasks:: Items that show up again and again
+@end menu
+
+@node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling
+@subsection Inserting deadline/schedule
+
+The following commands allow to quickly insert a deadline or to schedule
+an item:
+
+@table @kbd
+@c
+@kindex C-c C-d
+@item C-c C-d
+Insert @samp{DEADLINE} keyword along with a stamp. The insertion will
+happen in the line directly following the headline.
+@c FIXME Any CLOSED timestamp will be removed.????????
+@c
+@kindex C-c C-w
+@cindex sparse tree, for deadlines
+@item C-c C-w
+Create a sparse tree with all deadlines that are either past-due, or
+which will become due within @code{org-deadline-warning-days}.
+With @kbd{C-u} prefix, show all deadlines in the file. With a numeric
+prefix, check that many days. For example, @kbd{C-1 C-c C-w} shows
+all deadlines due tomorrow.
+@c
+@kindex C-c C-s
+@item C-c C-s
+Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will
+happen in the line directly following the headline. Any CLOSED
+timestamp will be removed.
+@end table
+
+@node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling
+@subsection Repeated Tasks
+
+Some tasks need to be repeated again and again, and Org-mode therefore
+allows to use a repeater in a DEADLINE or SCHEDULED time stamp, for
+example:
+@example
+** TODO Pay the rent
+ DEADLINE: <2005-10-01 Sat +1m>
+@end example
+
+Deadlines and scheduled items produce entries in the agenda when they
+are over-due, so it is important to be able to mark such an entry as
+completed once you have done so. When you mark a DEADLINE or a SCHEDULE
+with the todo keyword DONE, it will no longer produce entries in the
+agenda. The problem with this is, however, that then also the
+@emph{next} instance of the repeated entry will not be active. Org-mode
+deals with this in the following way: When you try to mark such an entry
+DONE (using @kbd{C-c C-t}), it will shift the base date of the repeating
+time stamp by the repeater interval, and immediately set the entry state
+back to TODO. In the example above, setting the state to DONE would
+actually switch the date like this:
+
+@example
+** TODO Pay the rent
+ DEADLINE: <2005-11-01 Tue +1m>
+@end example
+
+You will also be prompted for a note that will be put under the DEADLINE
+line to keep a record that you actually acted on the previous instance
+of this deadline.
+
+As a consequence of shifting the base date, this entry will no longer be
+visible in the agenda when checking past dates, but all future instances
+will be visible.
+
+You may have both scheduling and deadline information for a specific
+task - just make sure that the repeater intervals on both are the same.
+
+@node Progress logging, , Deadlines and scheduling, Timestamps
+@section Progress Logging
+@cindex progress logging
+@cindex logging, of progress
+
+Org-mode can automatically record a time stamp when you mark a TODO item
+as DONE, or even each time when you change the state of a TODO item.
+You can also measure precisely the time you spent on specific items in a
+project by starting and stopping a clock when you start and stop working
+on an aspect of a project.
+
+@menu
+* Closing items:: When was this entry marked DONE?
+* Tracking TODO state changes:: When did the status change?
+* Clocking work time:: When exactly did you work on this item?
+@end menu
+
+@node Closing items, Tracking TODO state changes, Progress logging, Progress logging
+@subsection Closing items
+
+If you want to keep track of @emph{when} a certain TODO item was
+finished, turn on logging with@footnote{The corresponding in-buffer
+setting is: @code{#+STARTUP: logdone}}
+
+@lisp
+(setq org-log-done t)
+@end lisp
+
+@noindent
+Then each time you turn a TODO entry into DONE using either @kbd{C-c
+C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line
+@samp{CLOSED: [timestamp]} will be inserted just after the headline. If
+you turn the entry back into a TODO item through further state cycling,
+that line will be removed again. In the timeline (@pxref{Timeline}) and
+in the agenda (@pxref{Weekly/Daily agenda}), you can then use the
+@kbd{l} key to display the TODO items closed on each day, giving you an
+overview of what has been done on a day. If you want to record a note
+along with the timestamp, use@footnote{The corresponding in-buffer
+setting is: @code{#+STARTUP: lognotedone}}
+
+@lisp
+(setq org-log-done '(done))
+@end lisp
+
+@node Tracking TODO state changes, Clocking work time, Closing items, Progress logging
+@subsection Tracking TODO state changes
+
+When TODO keywords are used as workflow states (@pxref{Workflow
+states}), you might want to keep track of when a state change occurred,
+and you may even want to attach notes to that state change. With the
+setting
+
+@lisp
+(setq org-log-done '(state))
+@end lisp
+
+@noindent
+each state change will prompt you for a note that will be attached to
+the current headline. Very likely you do not want this verbose tracking
+all the time, so it is probably better to configure this behavior with
+in-buffer options. For example, if you are tracking purchases, put
+these into a separate file that starts with:
+
+@example
+#+SEQ_TODO: TODO ORDERED INVOICE PAYED RECEIVED SENT
+#+STARTUP: lognotestate
+@end example
+
+
+@node Clocking work time, , Tracking TODO state changes, Progress logging
+@subsection Clocking work time
+
+Org-mode allows you to clock the time you spent on specific tasks in a
+project. When you start working on an item, you can start the clock.
+When you stop working on that task, or when you mark the task done, the
+clock is stopped and the corresponding time interval is recorded. It
+also computes the total time spent on each subtree of a project.
+
+@table @kbd
+@kindex C-c C-x C-i
+@item C-c C-x C-i
+Start the clock on the current item (clock-in). This inserts the CLOCK
+keyword together with a timestamp.
+@kindex C-c C-x C-o
+@item C-c C-x C-o
+Stop the clock (clock-out). The inserts another timestamp at the same
+location where the clock was last started. It also directly computes
+the resulting time in inserts it after the time range as @samp{=>
+HH:MM}. See the variable @code{org-log-done} for the possibility to
+record an additional note together with the clock-out time
+stamp@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
+lognoteclock-out}}.
+@kindex C-c C-y
+@item C-c C-y
+Recompute the time interval after changing one of the time stamps. This
+is only necessary if you edit the time stamps directly. If you change
+them with @kbd{S-@key{cursor}} keys, the update is automatic.
+@kindex C-c C-t
+@item C-c C-t
+Changing the TODO state of an item to DONE automatically stops the clock
+if it is running in this same item.
+@kindex C-c C-x C-x
+@item C-c C-x C-x
+Cancel the current clock. This is useful if a clock was started by
+mistake, or if you ended up working on something else.
+@kindex C-c C-x C-d
+@item C-c C-x C-d
+Display time summaries for each subtree in the current buffer. This
+puts overlays at the end of each headline, showing the total time
+recorded under that heading, including the time of any subheadings. You
+can use visibility cycling to study the tree, but the overlays disappear
+when you change the buffer (see variable
+@code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}.
+@kindex C-c C-x C-r
+@item C-c C-x C-r
+Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
+report as an org-mode table into the current file.
+@example
+#+BEGIN: clocktable :maxlevel 2 :emphasize nil
+
+#+END: clocktable
+@end example
+@noindent
+If such a block already exists, its content is replaced by the new
+table. The @samp{BEGIN} line can specify options:
+@example
+:maxlevels @r{Maximum level depth to which times are listed in the table.}
+:emphasize @r{When @code{t}, emphasize level one and level two items}
+:block @r{The time block to consider. This block is specified relative}
+ @r{to the current time and may be any of these keywords:}
+ @r{@code{today}, @code{yesterday}, @code{thisweek}, @code{lastweek},}
+ @r{@code{thismonth}, @code{lastmonth}, @code{thisyear}, or @code{lastyear}}.
+:tstart @r{A time string specifying when to start considering times}
+:tend @r{A time string specifying when to stop considering times}
+@end example
+So to get a clock summary for the current day, you could write
+@example
+#+BEGIN: clocktable :maxlevel 2 :block today
+
+#+END: clocktable
+@end example
+and to use a specific time range you could write@footnote{Note that all
+parameters must be specified in a single line - the line is broken here
+only to fit it onto the manual.}
+@example
+#+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
+ :tend "<2006-08-10 Thu 12:00>"
+
+#+END: clocktable
+@end example
+@kindex C-u C-c C-x C-u
+@item C-u C-c C-x C-u
+Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
+you have several clocktable blocks in a buffer.
+@end table
+
+The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
+the agenda (@pxref{Weekly/Daily agenda}) to show which tasks have been
+worked on or closed during a day.
+
+@node Agenda views, Embedded LaTeX, Timestamps, Top
+@chapter Agenda Views
+@cindex agenda views
+
+Due to the way Org-mode works, TODO items, time-stamped items, and
+tagged headlines can be scattered throughout a file or even a number of
+files. To get an overview over open action items, or over events that
+are important for a particular date, this information must be collected,
+sorted and displayed in an organized way.
+
+Org-mode can select items based on various criteria, and display them
+in a separate buffer. Six different view types are provided:
+
+@itemize @bullet
+@item
+an @emph{agenda} that is like a calendar and shows information
+for specific dates,
+@item
+a @emph{TODO list} that covers all unfinished
+action items,
+@item
+a @emph{tags view}, showings headlines based on
+the tags associated with them,
+@item
+a @emph{timeline view} that shows all events in a single Org-mode file,
+in time-sorted view,
+@item
+a @emph{stuck projects view} showing projects that currently don't move
+along, and
+@item
+@emph{custom views} that are special tag/keyword searches and
+combinations of different views.
+@end itemize
+
+@noindent
+The extracted information is displayed in a special @emph{agenda
+buffer}. This buffer is read-only, but provides commands to visit the
+corresponding locations in the original Org-mode files, and even to
+edit these files remotely.
+
+Two variables control how the agenda buffer is displayed and whether the
+window configuration is restored when the agenda exits:
+@code{org-agenda-window-setup} and
+@code{org-agenda-restore-windows-after-quit}.
+
+@menu
+* Agenda files:: Files being searched for agenda information
+* Agenda dispatcher:: Keyboard access to agenda views
+* Built-in agenda views:: What is available out of the box?
+* Presentation and sorting:: How agenda items are prepared for display
+* Agenda commands:: Remote editing of org trees
+* Custom agenda views:: Defining special searches and views
+@end menu
+
+@node Agenda files, Agenda dispatcher, Agenda views, Agenda views
+@section Agenda files
+@cindex agenda files
+@cindex files for agenda
+
+The information to be shown is collected from all @emph{agenda files},
+the files listed in the variable @code{org-agenda-files}@footnote{If the
+value of that variable is not a list, but a single file name, then the
+list of agenda files will be maintained in that external file.}. Thus even
+if you only work with a single Org-mode file, this file should be put
+into that list@footnote{When using the dispatcher, pressing @kbd{1}
+before selecting a command will actually limit the command to the
+current file, and ignore @code{org-agenda-files} until the next
+dispatcher command.}. You can customize @code{org-agenda-files}, but
+the easiest way to maintain it is through the following commands
+
+@cindex files, adding to agenda list
+@table @kbd
+@kindex C-c [
+@item C-c [
+Add current file to the list of agenda files. The file is added to
+the front of the list. If it was already in the list, it is moved to
+the front. With prefix arg, file is added/moved to the end.
+@kindex C-c ]
+@item C-c ]
+Remove current file from the list of agenda files.
+@kindex C-,
+@kindex C-'
+@item C-,
+@itemx C-'
+Cycle through agenda file list, visiting one file after the other.
+@end table
+
+@noindent
+The Org menu contains the current list of files and can be used
+to visit any of them.
+
+@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda views
+@section The agenda dispatcher
+@cindex agenda dispatcher
+@cindex dispatching agenda commands
+The views are created through a dispatcher that should be bound to a
+global key, for example @kbd{C-c a} (@pxref{Installation}). In the
+following we will assume that @kbd{C-c a} is indeed how the dispatcher
+is accessed and list keyboard access to commands accordingly. After
+pressing @kbd{C-c a}, an additional letter is required to execute a
+command. The dispatcher offers the following default commands:
+@table @kbd
+@item a
+Create the calendar-like agenda (@pxref{Weekly/Daily agenda}).
+@item t @r{/} T
+Create a list of all TODO items (@pxref{Global TODO list}).
+@item m @r{/} M
+Create a list of headlines matching a TAGS expression (@pxref{Matching
+tags and properties}).
+@item L
+Create the timeline view for the current buffer (@pxref{Timeline}).
+@item # @r{/} !
+Create a list of stuck projects (@pxref{Stuck projects}).
+@item 1
+Restrict an agenda command to the current buffer. After pressing
+@kbd{1}, you still need to press the character selecting the command.
+@item 0
+If there is an active region, restrict the following agenda command to
+the region. Otherwise, restrict it to the current subtree. After
+pressing @kbd{0}, you still need to press the character selecting the
+command.
+@end table
+
+You can also define custom commands that will be accessible through the
+dispatcher, just like the default commands. This includes the
+possibility to create extended agenda buffers that contain several
+blocks together, for example the weekly agenda, the global TODO list and
+a number of special tags matches. @xref{Custom agenda views}.
+
+@node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda views
+@section The built-in agenda views
+
+In this section we describe the built-in views.
+
+@menu
+* Weekly/Daily agenda:: The calendar page with current tasks
+* Global TODO list:: All unfinished action items
+* Matching tags and properties:: Structured information with fine-tuned search
+* Timeline:: Time-sorted view for single file
+* Stuck projects:: Find projects you need to review
+@end menu
+
+@node Weekly/Daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views
+@subsection The weekly/daily agenda
+@cindex agenda
+@cindex weekly agenda
+@cindex daily agenda
+
+The purpose of the weekly/daily @emph{agenda} is to act like a page of a
+paper agenda, showing all the tasks for the current week or day.
+
+@table @kbd
+@cindex org-agenda, command
+@kindex C-c a a
+@item C-c a a
+Compile an agenda for the current week from a list of org files. The
+agenda shows the entries for each day. With a @kbd{C-u} prefix (or
+when the variable @code{org-agenda-include-all-todo} is @code{t}), all
+unfinished TODO items (including those without a date) are also listed at
+the beginning of the buffer, before the first date.@*
+@end table
+
+Remote editing from the agenda buffer means, for example, that you can
+change the dates of deadlines and appointments from the agenda buffer.
+The commands available in the Agenda buffer are listed in @ref{Agenda
+commands}.
+
+@subsubheading Calendar/Diary integration
+@cindex calendar integration
+@cindex diary integration
+
+Emacs contains the calendar and diary by Edward M. Reingold. The
+calendar displays a three-month calendar with holidays from different
+countries and cultures. The diary allows you to keep track of
+anniversaries, lunar phases, sunrise/set, recurrent appointments
+(weekly, monthly) and more. In this way, it is quite complementary to
+Org-mode. It can be very useful to combine output from Org-mode with
+the diary.
+
+In order to include entries from the Emacs diary into Org-mode's
+agenda, you only need to customize the variable
+
+@lisp
+(setq org-agenda-include-diary t)
+@end lisp
+
+@noindent After that, everything will happen automatically. All diary
+entries including holidays, anniversaries etc will be included in the
+agenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and
+@key{RET} can be used from the agenda buffer to jump to the diary
+file in order to edit existing diary entries. The @kbd{i} command to
+insert new entries for the current date works in the agenda buffer, as
+well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
+Sunrise/Sunset times, show lunar phases and to convert to other
+calendars, respectively. @kbd{c} can be used to switch back and forth
+between calendar and agenda.
+
+If you are using the diary only for sexp entries and holidays, it is
+faster to not use the above setting, but instead to copy or even move
+the entries into an Org-mode file. Org-mode evaluates diary-style sexp
+entries, and does it faster because there is no overhead for first
+creating the diary display. Note that the sexp entries must start at
+the left margin, no white space is allowed before them. For example,
+the following segment of an Org-mode file will be processed and entries
+will be made in the agenda:
+
+@example
+* Birthdays and similar stuff
+#+CATEGORY: Holiday
+%%(org-calendar-holiday) ; special function for holiday names
+#+CATEGORY: Ann
+%%(diary-anniversary 14 5 1956) Arthur Dent is %d years old
+%%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old
+@end example
+
+@node Global TODO list, Matching tags and properties, Weekly/Daily agenda, Built-in agenda views
+@subsection The global TODO list
+@cindex global TODO list
+@cindex TODO list, global
+
+The global TODO list contains all unfinished TODO items, formatted and
+collected into a single place.
+
+@table @kbd
+@kindex C-c a t
+@item C-c a t
+Show the global TODO list. This collects the TODO items from all
+agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in
+@code{agenda-mode}, so there are commands to examine and manipulate
+the TODO entries directly from that buffer (@pxref{Agenda commands}).
+@kindex C-c a T
+@item C-c a T
+@cindex TODO keyword matching
+Like the above, but allows selection of a specific TODO keyword. You
+can also do this by specifying a prefix argument to @kbd{C-c a t}. With
+a @kbd{C-u} prefix you are prompted for a keyword, and you may also
+specify several keywords by separating them with @samp{|} as boolean OR
+operator. With a numeric prefix, the Nth keyword in
+@code{org-todo-keywords} is selected.
+@kindex r
+The @kbd{r} key in the agenda buffer regenerates it, and you can give
+a prefix argument to this command to change the selected TODO keyword,
+for example @kbd{3 r}. If you often need a search for a specific
+keyword, define a custom command for it (@pxref{Agenda dispatcher}).@*
+Matching specific TODO keywords can also be done as part of a tags
+search (@pxref{Tag searches}).
+@end table
+
+Remote editing of TODO items means that you can change the state of a
+TODO entry with a single key press. The commands available in the
+TODO list are described in @ref{Agenda commands}.
+
+@cindex sublevels, inclusion into todo list
+Normally the global todo list simply shows all headlines with TODO
+keywords. This list can become very long. There are two ways to keep
+it more compact:
+@itemize @minus
+@item
+Some people view a TODO item that has been @emph{scheduled} for
+execution (@pxref{Time stamps}) as no longer @emph{open}. Configure the
+variable @code{org-agenda-todo-ignore-scheduled} to exclude scheduled
+items from the global TODO list.
+@item
+TODO items may have sublevels to break up the task into subtasks. In
+such cases it may be enough to list only the highest level TODO headline
+and omit the sublevels from the global list. Configure the variable
+@code{org-agenda-todo-list-sublevels} to get this behavior.
+@end itemize
+
+@node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views
+@subsection Matching Tags and Properties
+@cindex matching, of tags
+@cindex matching, of properties
+@cindex tags view
+
+If headlines in the agenda files are marked with @emph{tags}
+(@pxref{Tags}), you can select headlines based on the tags that apply
+to them and collect them into an agenda buffer.
+
+@table @kbd
+@kindex C-c a m
+@item C-c a m
+Produce a list of all headlines that match a given set of tags. The
+command prompts for a selection criterion, which is a boolean logic
+expression with tags, like @samp{+WORK+URGENT-WITHBOSS} or
+@samp{WORK|HOME} (@pxref{Tags}). If you often need a specific search,
+define a custom command for it (@pxref{Agenda dispatcher}).
+@kindex C-c a M
+@item C-c a M
+Like @kbd{C-c a m}, but only select headlines that are also TODO items
+and force checking subitems (see variable
+@code{org-tags-match-list-sublevels}). Matching specific todo keywords
+together with a tags match is also possible, see @ref{Tag searches}.
+@end table
+
+The commands available in the tags list are described in @ref{Agenda
+commands}.
+
+@node Timeline, Stuck projects, Matching tags and properties, Built-in agenda views
+@subsection Timeline for a single file
+@cindex timeline, single file
+@cindex time-sorted view
+
+The timeline summarizes all time-stamped items from a single Org-mode
+file in a @emph{time-sorted view}. The main purpose of this command is
+to give an overview over events in a project.
+
+@table @kbd
+@kindex C-c a L
+@item C-c a L
+Show a time-sorted view of the org file, with all time-stamped items.
+When called with a @kbd{C-u} prefix, all unfinished TODO entries
+(scheduled or not) are also listed under the current date.
+@end table
+
+@noindent
+The commands available in the timeline buffer are listed in
+@ref{Agenda commands}.
+
+
+@node Stuck projects, , Timeline, Built-in agenda views
+@subsection Stuck projects
+
+If you are following a system like David Allen's GTD to organize your
+work, one of the ``duties'' you have is a regular review to make sure
+that all projects move along. A @emph{stuck} project is a project that
+has no defined next actions, so it will never show up in the TODO lists
+Org-mode produces. During the review, you need to identify such
+projects and define next actions for them.
+
+@table @kbd
+@kindex C-c a #
+@item C-c a #
+List projects that are stuck.
+@kindex C-c a !
+@item C-c a !
+Customize the variable @code{org-stuck-projects} to define what a stuck
+project is and how to find it.
+@end table
+
+You almost certainly will have to configure this view before it will
+work for you. The built-in default assumes that all your projects are
+level-2 headlines, and that a project is not stuck if it has at least
+one entry marked with a todo keyword TODO or NEXT or NEXTACTION.
+
+Lets assume that you, in your own way of using Org-mode, identify
+projects with a tag PROJECT, and that you use a todo keyword MAYBE to
+indicate a project that should not be considered yet. Lets further
+assume that the todo keyword DONE marks finished projects, and that NEXT
+and TODO indicate next actions. The tag @@SHOP indicates shopping and
+is a next action even without the NEXT tag. Finally, if the project
+contains the special word IGNORE anywhere, it should not be listed
+either. In this case you would start by identifying eligible projects
+with a tags/todo match @samp{+PROJECT/-MAYBE-DONE}, and then check for
+TODO, NEXT, @@SHOP, and IGNORE in the subtree to identify projects that
+are not stuck. The correct customization for this is
+
+@lisp
+(setq org-stuck-projects
+ '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")
+ "\\<IGNORE\\>"))
+@end lisp
+
+
+@node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda views
+@section Presentation and sorting
+@cindex presentation, of agenda items
+
+Before displaying items in an agenda view, Org-mode visually prepares
+the items and sorts them. Each item occupies a single line. The line
+starts with a @emph{prefix} that contains the @emph{category}
+(@pxref{Categories}) of the item and other important information. You can
+customize the prefix using the option @code{org-agenda-prefix-format}.
+The prefix is followed by a cleaned-up version of the outline headline
+associated with the item.
+
+@menu
+* Categories:: Not all tasks are equal
+* Time-of-day specifications:: How the agenda knows the time
+* Sorting of agenda items:: The order of things
+@end menu
+
+@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
+@subsection Categories
+
+@cindex category
+The category is a broad label assigned to each agenda item. By default,
+the category is simply derived from the file name, but you can also
+specify it with a special line in the buffer, like this:
+
+@example
+#+CATEGORY: Thesis
+@end example
+
+If there are several such lines in a file, each specifies the category
+for the text below it (but the first category also applies to any text
+before the first CATEGORY line). The display in the agenda buffer looks
+best if the category is not longer than 10 characters.
+
+@node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting
+@subsection Time-of-Day Specifications
+@cindex time-of-day specification
+
+Org-mode checks each agenda item for a time-of-day specification. The
+time can be part of the time stamp that triggered inclusion into the
+agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
+ranges can be specified with two time stamps, like
+@c
+@w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
+
+In the headline of the entry itself, a time(range) may also appear as
+plain text (like @samp{12:45} or a @samp{8:30-1pm}. If the agenda
+integrates the Emacs diary (@pxref{Weekly/Daily agenda}), time
+specifications in diary entries are recognized as well.
+
+For agenda display, Org-mode extracts the time and displays it in a
+standard 24 hour format as part of the prefix. The example times in
+the previous paragraphs would end up in the agenda like this:
+
+@example
+ 8:30-13:00 Arthur Dent lies in front of the bulldozer
+ 12:45...... Ford Prefect arrives and takes Arthur to the pub
+ 19:00...... The Vogon reads his poem
+ 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
+@end example
+
+@cindex time grid
+If the agenda is in single-day mode, or for the display of today, the
+timed entries are embedded in a time grid, like
+
+@example
+ 8:00...... ------------------
+ 8:30-13:00 Arthur Dent lies in front of the bulldozer
+ 10:00...... ------------------
+ 12:00...... ------------------
+ 12:45...... Ford Prefect arrives and takes Arthur to the pub
+ 14:00...... ------------------
+ 16:00...... ------------------
+ 18:00...... ------------------
+ 19:00...... The Vogon reads his poem
+ 20:00...... ------------------
+ 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
+@end example
+
+The time grid can be turned on and off with the variable
+@code{org-agenda-use-time-grid}, and can be configured with
+@code{org-agenda-time-grid}.
+
+@node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting
+@subsection Sorting of agenda items
+@cindex sorting, of agenda items
+@cindex priorities, of agenda items
+Before being inserted into a view, the items are sorted. How this is
+done depends on the type of view.
+@itemize @bullet
+@item
+For the daily/weekly agenda, the items for each day are sorted. The
+default order is to first collect all items containing an explicit
+time-of-day specification. These entries will be shown at the beginning
+of the list, as a @emph{schedule} for the day. After that, items remain
+grouped in categories, in the sequence given by @code{org-agenda-files}.
+Within each category, items are sorted by priority (@pxref{Priorities}),
+which is composed of the base priority (2000 for priority @samp{A}, 1000
+for @samp{B}, and 0 for @samp{C}), plus additional increments for
+overdue scheduled or deadline items.
+@item
+For the TODO list, items remain in the order of categories, but within
+each category, sorting takes place according to priority
+(@pxref{Priorities}).
+@item
+For tags matches, items are not sorted at all, but just appear in the
+sequence in which they are found in the agenda files.
+@end itemize
+
+Sorting can be customized using the variable
+@code{org-agenda-sorting-strategy}.
+
+
+@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda views
+@section Commands in the agenda buffer
+@cindex commands, in agenda buffer
+
+Entries in the agenda buffer are linked back to the org file or diary
+file where they originate. You are not allowed to edit the agenda
+buffer itself, but commands are provided to show and jump to the
+original entry location, and to edit the org-files ``remotely'' from
+the agenda buffer. In this way, all information is stored only once,
+removing the risk that your agenda and note files may diverge.
+
+Some commands can be executed with mouse clicks on agenda lines. For
+the other commands, the cursor needs to be in the desired line.
+
+@table @kbd
+@tsubheading{Motion}
+@cindex motion commands in agenda
+@kindex n
+@item n
+Next line (same as @key{up}).
+@kindex p
+@item p
+Previous line (same as @key{down}).
+@tsubheading{View/GoTo org file}
+@kindex mouse-3
+@kindex @key{SPC}
+@item mouse-3
+@itemx @key{SPC}
+Display the original location of the item in another window.
+@c
+@kindex L
+@item L
+Display original location and recenter that window.
+@c
+@kindex mouse-2
+@kindex mouse-1
+@kindex @key{TAB}
+@item mouse-2
+@itemx mouse-1
+@itemx @key{TAB}
+Go to the original location of the item in another window. Under Emacs
+22, @kbd{mouse-1} will also works for this.
+@c
+@kindex @key{RET}
+@itemx @key{RET}
+Go to the original location of the item and delete other windows.
+@c
+@kindex f
+@item f
+Toggle Follow mode. In Follow mode, as you move the cursor through
+the agenda buffer, the other window always shows the corresponding
+location in the org file. The initial setting for this mode in new
+agenda buffers can be set with the variable
+@code{org-agenda-start-with-follow-mode}.
+@c
+@kindex b
+@item b
+Display the entire subtree of the current item in an indirect buffer.
+With numerical prefix ARG, go up to this level and then take that tree.
+If ARG is negative, go up that many levels. With @kbd{C-u} prefix, do
+not remove the previously used indirect buffer.
+@c
+@kindex l
+@item l
+Toggle Logbook mode. In Logbook mode, entries that where marked DONE while
+logging was on (variable @code{org-log-done}) are shown in the agenda,
+as are entries that have been clocked on that day.
+
+@tsubheading{Change display}
+@cindex display changing, in agenda
+@kindex o
+@item o
+Delete other windows.
+@c
+@kindex d
+@kindex w
+@kindex m
+@kindex y
+@item d w m y
+Switch to day/week/month/year view. When switching to day or week view,
+this setting becomes the default for subseqent agenda commands. Since
+month and year views are slow to create, the do not become the default.
+@c
+@kindex D
+@item D
+Toggle the inclusion of diary entries. See @ref{Weekly/Daily agenda}.
+@c
+@kindex g
+@item g
+Toggle the time grid on and off. See also the variables
+@code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
+@c
+@kindex r
+@item r
+Recreate the agenda buffer, for example to reflect the changes
+after modification of the time stamps of items with S-@key{left} and
+S-@key{right}. When the buffer is the global todo list, a prefix
+argument is interpreted to create a selective list for a specific TODO
+keyword.
+@c
+@kindex s
+@item s
+Save all Org-mode buffers in the current Emacs session.
+@c
+@kindex @key{right}
+@item @key{right}
+Display the following @code{org-agenda-ndays} days. For example, if
+the display covers a week, switch to the following week. With prefix
+arg, go forward that many times @code{org-agenda-ndays} days.
+@c
+@kindex @key{left}
+@item @key{left}
+Display the previous dates.
+@c
+@kindex .
+@item .
+Goto today.
+
+@tsubheading{Remote editing}
+@cindex remote editing, from agenda
+
+@item 0-9
+Digit argument.
+@c
+@cindex undoing remote-editing events
+@cindex remote editing, undo
+@kindex C-_
+@item C-_
+Undo a change due to a remote editing command. The change is undone
+both in the agenda buffer and in the remote buffer.
+@c
+@kindex t
+@item t
+Change the TODO state of the item, both in the agenda and in the
+original org file.
+@c
+@kindex C-k
+@item C-k
+Delete the current agenda item along with the entire subtree belonging
+to it in the original Org-mode file. If the text to be deleted remotely
+is longer than one line, the kill needs to be confirmed by the user. See
+variable @code{org-agenda-confirm-kill}.
+@c
+@kindex $
+@item $
+Archive the subtree corresponding to the current headline.
+@c
+@kindex T
+@item T
+Show all tags associated with the current item. Because of
+inheritance, this may be more than the tags listed in the line itself.
+@c
+@kindex :
+@item :
+Set tags for the current headline.
+@c
+@kindex a
+@item a
+Toggle the ARCHIVE tag for the current headline.
+@c
+@kindex ,
+@item ,
+Set the priority for the current item. Org-mode prompts for the
+priority character. If you reply with @key{SPC}, the priority cookie
+is removed from the entry.
+@c
+@kindex P
+@item P
+Display weighted priority of current item.
+@c
+@kindex +
+@kindex S-@key{up}
+@item +
+@itemx S-@key{up}
+Increase the priority of the current item. The priority is changed in
+the original buffer, but the agenda is not resorted. Use the @kbd{r}
+key for this.
+@c
+@kindex -
+@kindex S-@key{down}
+@item -
+@itemx S-@key{down}
+Decrease the priority of the current item.
+@c
+@kindex C-c C-s
+@item C-c C-s
+Schedule this item
+@c
+@kindex C-c C-d
+@item C-c C-d
+Set a deadline for this item.
+@c
+@kindex S-@key{right}
+@item S-@key{right}
+Change the time stamp associated with the current line by one day into
+the future. With prefix argument, change it by that many days. For
+example, @kbd{3 6 5 S-@key{right}} will change it by a year. The
+stamp is changed in the original org file, but the change is not
+directly reflected in the agenda buffer. Use the
+@kbd{r} key to update the buffer.
+@c
+@kindex S-@key{left}
+@item S-@key{left}
+Change the time stamp associated with the current line by one day
+into the past.
+@c
+@kindex >
+@item >
+Change the time stamp associated with the current line to today.
+The key @kbd{>} has been chosen, because it is the same as @kbd{S-.}
+on my keyboard.
+@c
+@kindex I
+@item I
+Start the clock on the current item. If a clock is running already, it
+is stopped first.
+@c
+@kindex O
+@item O
+Stop the previously started clock.
+@c
+@kindex X
+@item X
+Cancel the currently running clock.
+
+@tsubheading{Calendar commands}
+@cindex calendar commands, from agenda
+@kindex c
+@item c
+Open the Emacs calendar and move to the date at the agenda cursor.
+@c
+@item c
+When in the calendar, compute and show the Org-mode agenda for the
+date at the cursor.
+@c
+@cindex diary entries, creating from agenda
+@kindex i
+@item i
+Insert a new entry into the diary. Prompts for the type of entry
+(day, weekly, monthly, yearly, anniversary, cyclic) and creates a new
+entry in the diary, just as @kbd{i d} etc. would do in the calendar.
+The date is taken from the cursor position.
+@c
+@kindex M
+@item M
+Show the phases of the moon for the three months around current date.
+@c
+@kindex S
+@item S
+Show sunrise and sunset times. The geographical location must be set
+with calendar variables, see documentation of the Emacs calendar.
+@c
+@kindex C
+@item C
+Convert the date at cursor into many other cultural and historic
+calendars.
+@c
+@kindex H
+@item H
+Show holidays for three month around the cursor date.
+@c
+@c FIXME: This should be a different key.
+@kindex C-c C-x C-c
+@item C-c C-x C-c
+Export a single iCalendar file containing entries from all agenda files.
+
+@tsubheading{Exporting to a file}
+@kindex C-x C-w
+@item C-x C-w
+@cindex exporting agenda views
+@cindex agenda views, exporting
+Write the agenda view to a file. Depending on the extension of the
+selected file name, the view will be exported as HTML (extension
+@file{.html} or @file{.htm}), Postscript (extension @file{.ps}), or
+plain text (any other extension). Use the variable
+@code{org-agenda-exporter-settings} to set options for @file{ps-print}
+and for @file{htmlize} to be used during export.
+
+@tsubheading{Quit and Exit}
+@kindex q
+@item q
+Quit agenda, remove the agenda buffer.
+@c
+@kindex x
+@cindex agenda files, removing buffers
+@item x
+Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
+for the compilation of the agenda. Buffers created by the user to
+visit org files will not be removed.
+@end table
+
+
+@node Custom agenda views, , Agenda commands, Agenda views
+@section Custom agenda views
+@cindex custom agenda views
+@cindex agenda views, custom
+
+Custom agenda commands serve two purposes: to store and quickly access
+frequently used TODO and tags searches, and to create special composite
+agenda buffers. Custom agenda commands will be accessible through the
+dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
+
+@menu
+* Storing searches:: Type once, use often
+* Block agenda:: All the stuff you need in a single buffer
+* Setting Options:: Changing the rules
+* Exporting Agenda Views:: Writing agendas to files.
+* Extracting Agenda Information for other programs::
+@end menu
+
+@node Storing searches, Block agenda, Custom agenda views, Custom agenda views
+@subsection Storing searches
+
+The first application of custom searches is the definition of keyboard
+shortcuts for frequently used searches, either creating an agenda
+buffer, or a sparse tree (the latter covering of course only the current
+buffer).
+@kindex C-c a C
+Custom commands are configured in the variable
+@code{org-agenda-custom-commands}. You can customize this variable, for
+example by pressing @kbd{C-c a C}. You can also directly set it with
+Emacs Lisp in @file{.emacs}. The following example contains all valid
+search types:
+
+@lisp
+@group
+(setq org-agenda-custom-commands
+ '(("w" todo "WAITING")
+ ("W" todo-tree "WAITING")
+ ("u" tags "+BOSS-URGENT")
+ ("v" tags-todo "+BOSS-URGENT")
+ ("U" tags-tree "+BOSS-URGENT")
+ ("f" occur-tree "\\<FIXME\\>")))
+@end group
+@end lisp
+
+@noindent
+The initial single-character string in each entry defines the character
+you have to press after the dispatcher command @kbd{C-c a} in order to
+access the command. The second parameter is the search type, followed
+by the string or regular expression to be used for the matching. The
+example above will therefore define:
+
+@table @kbd
+@item C-c a w
+as a global search for TODO entries with @samp{WAITING} as the TODO
+keyword
+@item C-c a W
+as the same search, but only in the current buffer and displaying the
+results as a sparse tree
+@item C-c a u
+as a global tags search for headlines marked @samp{:BOSS:} but not
+@samp{:URGENT:}
+@item C-c a v
+as the same search as @kbd{C-c a u}, but limiting the search to
+headlines that are also TODO items
+@item C-c a U
+as the same search as @kbd{C-c a u}, but only in the current buffer and
+displaying the result as a sparse tree
+@item C-c a f
+to create a sparse tree (again: current buffer only) with all entries
+containing the word @samp{FIXME}.
+@end table
+
+@node Block agenda, Setting Options, Storing searches, Custom agenda views
+@subsection Block agenda
+@cindex block agenda
+@cindex agenda, with block views
+
+Another possibility is the construction of agenda views that comprise
+the results of @emph{several} commands, each of which creates a block in
+the agenda buffer. The available commands include @code{agenda} for the
+daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo}
+for the global todo list (as constructed with @kbd{C-c a t}), and the
+matching commands discussed above: @code{todo}, @code{tags}, and
+@code{tags-todo}. Here are two examples:
+
+@lisp
+@group
+(setq org-agenda-custom-commands
+ '(("h" "Agenda and Home-related tasks"
+ ((agenda)
+ (tags-todo "HOME")
+ (tags "GARDEN")))
+ ("o" "Agenda and Office-related tasks"
+ ((agenda)
+ (tags-todo "WORK")
+ (tags "OFFICE")))))
+@end group
+@end lisp
+
+@noindent
+This will define @kbd{C-c a h} to create a multi-block view for stuff
+you need to attend to at home. The resulting agenda buffer will contain
+your agenda for the current week, all TODO items that carry the tag
+@samp{HOME}, and also all lines tagged with @samp{GARDEN}. Finally the
+command @kbd{C-c a o} provides a similar view for office tasks.
+
+
+@node Setting Options, Exporting Agenda Views, Block agenda, Custom agenda views
+@subsection Setting Options for custom commands
+@cindex options, for custom agenda views
+
+Org-mode contains a number of variables regulating agenda construction
+and display. The global variables define the behavior for all agenda
+commands, including the custom commands. However, if you want to change
+some settings just for a single custom view, you can do so. Setting
+options requires inserting a list of variable names and values at the
+right spot in @code{org-agenda-custom-commands}. For example:
+
+@lisp
+@group
+(setq org-agenda-custom-commands
+ '(("w" todo "WAITING"
+ ((org-agenda-sorting-strategy '(priority-down))
+ (org-agenda-prefix-format " Mixed: ")))
+ ("U" tags-tree "+BOSS-URGENT"
+ ((org-show-following-heading nil)
+ (org-show-hierarchy-above nil)))))
+@end group
+@end lisp
+
+@noindent
+Now the @kbd{C-c a w} command will sort the collected entries only by
+priority, and the prefix format is modified to just say @samp{ Mixed:}
+instead of giving the category of the entry. The sparse tags tree of
+@kbd{C-c a U} will now turn out ultra-compact, because neither the
+headline hierarchy above the match, nor the headline following the match
+will be shown.
+
+For command sets creating a block agenda,
+@code{org-agenda-custom-commands} has two separate spots for setting
+options. You can add options that should be valid for just a single
+command in the set, and options that should be valid for all commands in
+the set. The former are just added to the command entry, the latter
+must come after the list of command entries. Going back to the block
+agenda example (@pxref{Block agenda}), let's change the sorting strategy
+for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort
+the results for GARDEN tags query in the opposite order,
+@code{priority-up}. This would look like this:
+
+@lisp
+@group
+(setq org-agenda-custom-commands
+ '(("h" "Agenda and Home-related tasks"
+ ((agenda)
+ (tags-todo "HOME")
+ (tags "GARDEN"
+ ((org-agenda-sorting-strategy '(priority-up)))))
+ ((org-agenda-sorting-strategy '(priority-down))))
+ ("o" "Agenda and Office-related tasks"
+ ((agenda)
+ (tags-todo "WORK")
+ (tags "OFFICE")))))
+@end group
+@end lisp
+
+As you see, the values and parenthesis setting is a little complex.
+When in doubt, use the customize interface to set this variable - it
+fully supports its structure. Just one caveat: When setting options in
+this interface, the @emph{values} are just lisp expressions. So if the
+value is a string, you need to add the double quotes around the value
+yourself.
+
+
+@node Exporting Agenda Views, Extracting Agenda Information for other programs, Setting Options, Custom agenda views
+@subsection Exporting Agenda Views
+@cindex agenda views, exporting
+
+If you are away from your computer, it can be very useful to have a
+printed version of some agenda views to carry around. Org-mode can
+export custom agenda views as plain text, HTML@footnote{You need to
+install Hrvoje Niksic' @file{htmlize.el}.} and postscript. If you want
+to do this only occasionally, use the command
+
+@table @kbd
+@kindex C-x C-w
+@item C-x C-w
+@cindex exporting agenda views
+@cindex agenda views, exporting
+Write the agenda view to a file. Depending on the extension of the
+selected file name, the view will be exported as HTML (extension
+@file{.html} or @file{.htm}), Postscript (extension @file{.ps}), or
+plain text (any other extension). Use the variable
+@code{org-agenda-exporter-settings} to set options for @file{ps-print}
+and for @file{htmlize} to be used during export, for example
+@lisp
+(setq org-agenda-exporter-settings
+ '((ps-number-of-columns 2)
+ (ps-landscape-mode t)
+ (htmlize-output-type 'css)))
+@end lisp
+@end table
+
+If you need to export certain agenda views frequently, you can associate
+any custom agenda command with a list of output file names
+@footnote{If you want to store standard views like the weekly agenda
+or the global TODO list as well, you need to define custom commands for
+them in order to be able to specify filenames.}. Here is an example
+that first does define custom commands for the agenda and the global
+todo list, together with a number of files to which to export them.
+Then we define two block agenda commands and specify filenames for them
+as well. File names can be relative to the current working directory,
+or absolute.
+
+@lisp
+@group
+(setq org-agenda-custom-commands
+ '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
+ ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
+ ("h" "Agenda and Home-related tasks"
+ ((agenda)
+ (tags-todo "HOME")
+ (tags "GARDEN"))
+ nil
+ ("~/views/home.html"))
+ ("o" "Agenda and Office-related tasks"
+ ((agenda)
+ (tags-todo "WORK")
+ (tags "OFFICE"))
+ nil
+ ("~/views/office.ps"))))
+@end group
+@end lisp
+
+The extension of the file name determines the type of export. If it is
+@file{.html}, Org-mode will use the @file{htmlize.el} package to convert
+the buffer to HTML and save it to this file name. If the extension is
+@file{.ps}, @code{ps-print-buffer-with-faces} is used to produce
+postscript output. Any other extension produces a plain ASCII file.
+
+The export files are @emph{not} created when you use one of those
+commands interactively. Instead, there is a special command to produce
+@emph{all} specified files in one step:
+
+@table @kbd
+@kindex C-c a e
+@item C-c a e
+Export all agenda views that have export filenames associated with
+them.
+@end table
+
+You can use the options section of the custom agenda commands to also
+set options for the export commands. For example:
+
+@lisp
+(setq org-agenda-custom-commands
+ '(("X" agenda ""
+ ((ps-number-of-columns 2)
+ (ps-landscape-mode t)
+ (org-agenda-prefix-format " [ ] ")
+ (org-agenda-with-colors nil)
+ (org-agenda-remove-tags t))
+ ("theagenda.ps"))))
+@end lisp
+
+@noindent
+This command sets two options for the postscript exporter, to make it
+print in two columns in landscape format - the resulting page can be cut
+in two and then used in a paper agenda. The remaining settings modify
+the agenda prefix to omit category and scheduling information, and
+instead include a checkbox to check off items. We also remove the tags
+to make the lines compact, and we don't want to use colors for the
+black-and-white printer. Settings specified in
+@code{org-agenda-exporter-settings} will also apply, but the settings
+in @code{org-agenda-custom-commands} take precedence.
+
+@noindent
+From the command line you may also use
+@example
+emacs -f org-batch-store-agenda-views -kill
+@end example
+@noindent
+or, if you need to modify some parameters
+@example
+emacs -eval '(org-batch-store-agenda-views \
+ org-agenda-ndays 30 \
+ org-agenda-include-diary nil \
+ org-agenda-files (quote ("~/org/project.org")))' \
+ -kill
+@end example
+@noindent
+which will create the agenda views restricted to the file
+@file{~/org/project.org}, without diary entries and with 30 days
+extent.
+
+@node Extracting Agenda Information for other programs, , Exporting Agenda Views, Custom agenda views
+@subsection Extracting Agenda Information for other programs
+@cindex agenda, pipe
+@cindex Scripts, for agenda processing
+
+Org-mode provides commands to access agenda information for the command
+line in emacs batch mode. This extracted information can be sent
+directly to a printer, or it can be read by a program that does further
+processing of the data. The first of these commands is the function
+@code{org-batch-agenda}, that produces an agenda view and sends it as
+ASCII text to STDOUT. The command takes a single string as parameter.
+If the string has length 1, it is used as a key to one of the commands
+you have configured in @code{org-agenda-custom-commands}, basically any
+key you can use after @kbd{C-c a}. For example, to directly print the
+current TODO list, you could use
+
+@example
+emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
+@end example
+
+If the parameter is a string with 2 or more characters, it is used as a
+tags/todo match string. For example, to print your local shopping list
+(all items with the tag @samp{shop}, but excluding the tag
+@samp{NewYork}), you could use
+
+@example
+emacs -batch -l ~/.emacs \
+ -eval '(org-batch-agenda "+shop-NewYork")' | lpr
+@end example
+
+@noindent
+You may also modify parameters on the fly like this:
+
+@example
+emacs -batch -l ~/.emacs \
+ -eval '(org-batch-agenda "a" \
+ org-agenda-ndays 30 \
+ org-agenda-include-diary nil \
+ org-agenda-files (quote ("~/org/project.org")))' \
+ | lpr
+@end example
+
+@noindent
+which will produce a 30 day agenda, fully restricted to the Org file
+@file{~/org/projects.org}, not even including the diary.
+
+If you want to process the agenda data in more sophisticated ways, you
+can use the command @code{org-batch-agenda-csv} to get a comma-separated
+list of values for each agenda item. Each line in the output will
+contain a number of fields separated by commas. The fields in a line
+are:
+
+@example
+category @r{The category of the item}
+head @r{The headline, without TODO kwd, TAGS and PRIORITY}
+type @r{The type of the agenda entry, can be}
+ todo @r{selected in TODO match}
+ tagsmatch @r{selected in tags match}
+ diary @r{imported from diary}
+ deadline @r{a deadline}
+ scheduled @r{scheduled}
+ timestamp @r{appointment, selected by timestamp}
+ closed @r{entry was closed on date}
+ upcoming-deadline @r{warning about nearing deadline}
+ past-scheduled @r{forwarded scheduled item}
+ block @r{entry has date block including date}
+todo @r{The todo keyword, if any}
+tags @r{All tags including inherited ones, separated by colons}
+date @r{The relevant date, like 2007-2-14}
+time @r{The time, like 15:00-16:50}
+extra @r{String with extra planning info}
+priority-l @r{The priority letter if any was given}
+priority-n @r{The computed numerical priority}
+@end example
+
+@noindent
+Time and date will only be given if a timestamp (or deadline/scheduled)
+lead to the selection of the item.
+
+A CSV list like this is very easy to use in a post processing script.
+For example, here is a Perl program that gets the TODO list from
+Emacs/org-mode and prints all the items, preceded by a checkbox:
+
+@example
+@group
+#!/usr/bin/perl
+
+# define the Emacs command to run
+$cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
+
+# run it and capture the output
+$agenda = qx@{$cmd 2>/dev/null@};
+
+# loop over all lines
+foreach $line (split(/\n/,$agenda)) @{
+
+ # get the individual values
+ ($category,$head,$type,$todo,$tags,$date,$time,$extra,
+ $priority_l,$priority_n) = split(/,/,$line);
+
+ # proccess and print
+ print "[ ] $head\n";
+@}
+@end group
+@end example
+
+@node Embedded LaTeX, Exporting, Agenda views, Top
+@chapter Embedded LaTeX
+@cindex @TeX{} interpretation
+@cindex La@TeX{} interpretation
+
+Plain ASCII is normally sufficient for almost all note taking. One
+exception, however, are scientific notes which need to be able to
+contain mathematical symbols and the occasional formula.
+La@TeX{}@footnote{La@TeX{} is a macro system based on Donald E. Knuth's
+@TeX{} system. Many of the features described here as ``La@TeX{}'' are
+really from @TeX{}, but for simplicity I am blurring this distinction.}
+is widely used to typeset scientific documents. Org-mode supports
+embedding La@TeX{} code into its files, because many academics are used
+to read La@TeX{} source code, and because it can be readily processed
+into images for HTML production.
+
+It is not necessary to mark La@TeX{} macros and code in any special way.
+If you observe a few conventions, Org-mode knows how to find it and what
+to do with it.
+
+@menu
+* Math symbols:: TeX macros for symbols and Greek letters
+* Subscripts and Superscripts:: Simple syntax for raising/lowering text
+* LaTeX fragments:: Complex formulas made easy
+* Processing LaTeX fragments:: Previewing LaTeX processing
+* CDLaTeX mode:: Speed up entering of formulas
+@end menu
+
+@node Math symbols, Subscripts and Superscripts, Embedded LaTeX, Embedded LaTeX
+@section Math symbols
+@cindex math symbols
+@cindex TeX macros
+
+You can use La@TeX{} macros to insert special symbols like @samp{\alpha}
+to indicate the Greek letter, or @samp{\to} to indicate an arrow.
+Completion for these macros is available, just type @samp{\} and maybe a
+few letters, and press @kbd{M-@key{TAB}} to see possible completions.
+Unlike La@TeX{} code, Org-mode allows these macros to be present
+without surrounding math delimiters, for example:
+
+@example
+Angles are written as Greek letters \alpha, \beta and \gamma.
+@end example
+
+During HTML export (@pxref{HTML export}), these symbols are translated
+into the proper syntax for HTML, for the above examples this is
+@samp{α} and @samp{→}, respectively.
+
+@node Subscripts and Superscripts, LaTeX fragments, Math symbols, Embedded LaTeX
+@section Subscripts and Superscripts
+@cindex subscript
+@cindex superscript
+
+Just like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super-
+and subscripts. Again, these can be used without embedding them in
+math-mode delimiters. To increase the readability of ASCII text, it is
+not necessary (but OK) to surround multi-character sub- and superscripts
+with curly braces. For example
+
+@example
+The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of
+the sun is R_@{sun@} = 6.96 x 10^8 m.
+@end example
+
+To avoid interpretation as raised or lowered text, you can quote
+@samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^}.
+
+During HTML export (@pxref{HTML export}), subscript and superscripts
+are surrounded with @code{<sub>} and @code{<sup>} tags, respectively.
+
+@node LaTeX fragments, Processing LaTeX fragments, Subscripts and Superscripts, Embedded LaTeX
+@section LaTeX fragments
+@cindex LaTeX fragments
+
+With symbols, sub- and superscripts, HTML is pretty much at its end when
+it comes to representing mathematical formulas@footnote{Yes, there is
+MathML, but that is not yet fully supported by many browsers, and there
+is no decent converter for turning La@TeX{} or ASCII representations of
+formulas into MathML. So for the time being, converting formulas into
+images seems the way to go.}. More complex expressions need a dedicated
+formula processor. To this end, Org-mode can contain arbitrary La@TeX{}
+fragments. It provides commands to preview the typeset result of these
+fragments, and upon export to HTML, all fragments will be converted to
+images and inlined into the HTML document@footnote{The La@TeX{} export
+will not use images for displaying La@TeX{} fragments but include these
+fragments directly into the La@TeX{} code.}. For this to work you
+need to be on a system with a working La@TeX{} installation. You also
+need the @file{dvipng} program, available at
+@url{http://sourceforge.net/projects/dvipng/}. The La@TeX{} header that
+will be used when processing a fragment can be configured with the
+variable @code{org-format-latex-header}.
+
+La@TeX{} fragments don't need any special marking at all. The following
+snippets will be identified as La@TeX{} source code:
+@itemize @bullet
+@item
+Environments of any kind. The only requirement is that the
+@code{\begin} statement appears on a new line, preceded by only
+whitespace.
+@item
+Text within the usual La@TeX{} math delimiters. To avoid conflicts with
+currency specifications, single @samp{$} characters are only recognized
+as math delimiters if the enclosed text contains at most two line breaks,
+is directly attached to the @samp{$} characters with no whitespace in
+between, and if the closing @samp{$} is followed by whitespace or
+punctuation. For the other delimiters, there is no such restriction, so
+when in doubt, use @samp{\(...\)} as inline math delimiters.
+@end itemize
+
+@noindent For example:
+
+@example
+\begin@{equation@} % arbitrary environments,
+x=\sqrt@{b@} % even tables, figures
+\end@{equation@} % etc
+
+If $a^2=b$ and \( b=2 \), then the solution must be
+either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
+@end example
+
+@noindent
+If you need any of the delimiter ASCII sequences for other purposes, you
+can configure the option @code{org-format-latex-options} to deselect the
+ones you do not wish to have interpreted by the La@TeX{} converter.
+
+@node Processing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX
+@section Processing LaTeX fragments
+@cindex LaTeX fragments, preview
+
+La@TeX{} fragments can be processed to produce a preview images of the
+typeset expressions:
+
+@table @kbd
+@kindex C-c C-x C-l
+@item C-c C-x C-l
+Produce a preview image of the La@TeX{} fragment at point and overlay it
+over the source code. If there is no fragment at point, process all
+fragments in the current entry (between two headlines). When called
+with a prefix argument, process the entire subtree. When called with
+two prefix arguments, or when the cursor is before the first headline,
+process the entire buffer.
+@kindex C-c C-c
+@item C-c C-c
+Remove the overlay preview images.
+@end table
+
+During HTML export (@pxref{HTML export}), all La@TeX{} fragments are
+converted into images and inlined into the document if the following
+setting is active:
+
+@lisp
+(setq org-export-with-LaTeX-fragments t)
+@end lisp
+
+@node CDLaTeX mode, , Processing LaTeX fragments, Embedded LaTeX
+@section Using CDLaTeX to enter math
+@cindex CDLaTeX
+
+CDLaTeX-mode is a minor mode that is normally used in combination with a
+major La@TeX{} mode like AUCTeX in order to speed-up insertion of
+environments and math templates. Inside Org-mode, you can make use of
+some of the features of cdlatex-mode. You need to install
+@file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
+AUCTeX) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.
+Don't turn cdlatex-mode itself under Org-mode, but use the light
+version @code{org-cdlatex-mode} that comes as part of Org-mode. Turn it
+on for the current buffer with @code{M-x org-cdlatex-mode}, or for all
+Org-mode files with
+
+@lisp
+(add-hook 'org-mode-hook 'turn-on-org-cdlatex)
+@end lisp
+
+When this mode is enabled, the following features are present (for more
+details see the documentation of cdlatex-mode):
+@itemize @bullet
+@kindex C-c @{
+@item
+Environment templates can be inserted with @kbd{C-c @{}.
+@item
+@kindex @key{TAB}
+The @key{TAB} key will do template expansion if the cursor is inside a
+La@TeX{} fragment@footnote{Org-mode has a method to test if the cursor is
+inside such a fragment, see the documentation of the function
+@code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will
+expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
+correctly inside the first brace. Another @key{TAB} will get you into
+the second brace. Even outside fragments, @key{TAB} will expand
+environment abbreviations at the beginning of a line. For example, if
+you write @samp{equ} at the beginning of a line and press @key{TAB},
+this abbreviation will be expanded to an @code{equation} environment.
+To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}.
+@item
+@kindex _
+@kindex ^
+Pressing @kbd{_} and @kbd{^} inside a La@TeX{} fragment will insert these
+characters together with a pair of braces. If you use @key{TAB} to move
+out of the braces, and if the braces surround only a single character or
+macro, they are removed again (depending on the variable
+@code{cdlatex-simplify-sub-super-scripts}).
+@item
+@kindex `
+Pressing the backquote @kbd{`} followed by a character inserts math
+macros, also outside La@TeX{} fragments. If you wait more than 1.5 seconds
+after the backquote, a help window will pop up.
+@item
+@kindex '
+Pressing the normal quote @kbd{'} followed by another character modifies
+the symbol before point with an accent or a font. If you wait more than
+1.5 seconds after the backquote, a help window will pop up. Character
+modification will work only inside La@TeX{} fragments, outside the quote
+is normal.
+@end itemize
+
+@node Exporting, Publishing, Embedded LaTeX, Top
+@chapter Exporting
+@cindex exporting
+
+Org-mode documents can be exported into a variety of other formats. For
+printing and sharing of notes, ASCII export produces a readable and
+simple version of an Org-mode file. HTML export allows you to publish a
+notes file on the web, while the XOXO format provides a solid base for
+exchange with a broad range of other applications. La@TeX{} export lets
+you use Org-mode and its structured editing functions to easily create
+La@TeX{} files. To incorporate entries with associated times like
+deadlines or appointments into a desktop calendar program like iCal,
+Org-mode can also produce extracts in the iCalendar format. Currently
+Org-mode only supports export, not import of these different formats.
+
+When exporting, Org-mode uses special conventions to enrich the output
+produced. @xref{Text interpretation}, for more details.
+
+@table @kbd
+@kindex C-c C-e
+@item C-c C-e
+Dispatcher for export and publishing commands. Displays a help-window
+listing the additional key(s) needed to launch an export or publishing
+command.
+@end table
+
+@menu
+* ASCII export:: Exporting to plain ASCII
+* HTML export:: Exporting to HTML
+* LaTeX export:: Exporting to LaTeX
+* XOXO export:: Exporting to XOXO
+* iCalendar export:: Exporting in iCalendar format
+* Text interpretation:: How the exporter looks at the file
+@end menu
+
+@node ASCII export, HTML export, Exporting, Exporting
+@section ASCII export
+@cindex ASCII export
+
+ASCII export produces a simple and very readable version of an Org-mode
+file.
+
+@cindex region, active
+@cindex active region
+@cindex transient-mark-mode
+@table @kbd
+@kindex C-c C-e a
+@item C-c C-e a
+Export as ASCII file. For an org file @file{myfile.org}, the ASCII file
+will be @file{myfile.txt}. The file will be overwritten without
+warning. If there is an active region, only the region will be
+exported. If the selected region is a single tree, the tree head will
+become the document title. If the tree head entry has or inherits an
+EXPORT_FILE_NAME property, that name will be used for the export.
+@kindex C-c C-e v a
+@item C-c C-e v a
+Export only the visible part of the document.
+@end table
+
+@cindex headline levels, for exporting
+In the exported version, the first 3 outline levels will become
+headlines, defining a general document structure. Additional levels
+will be exported as itemized lists. If you want that transition to occur
+at a different level, specify it with a prefix argument. For example,
+
+@example
+@kbd{C-1 C-c C-e a}
+@end example
+
+@noindent
+creates only top level headlines and does the rest as items. When
+headlines are converted to items, the indentation of the text following
+the headline is changed to fit nicely under the item. This is done with
+the assumption that the first bodyline indicates the base indentation of
+the body text. Any indentation larger than this is adjusted to preserve
+the layout relative to the first line. Should there be lines with less
+indentation than the first, these are left alone.
+
+@node HTML export, LaTeX export, ASCII export, Exporting
+@section HTML export
+@cindex HTML export
+
+Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
+HTML formatting, in ways similar to John Grubers @emph{markdown}
+language, but with additional support for tables.
+
+@menu
+* HTML Export commands:: How to invoke LaTeX export
+* Quoting HTML tags:: Using direct HTML in Org-mode
+* Links:: Transformation of links for HTML
+* Images:: How to include images
+* CSS support:: Changing the appearence of the output
+@end menu
+
+@node HTML Export commands, Quoting HTML tags, HTML export, HTML export
+@subsection HTML export commands
+
+@cindex region, active
+@cindex active region
+@cindex transient-mark-mode
+@table @kbd
+@kindex C-c C-e h
+@item C-c C-e h
+Export as HTML file @file{myfile.html}. For an org file
+@file{myfile.org}, the ASCII file will be @file{myfile.html}. The file
+will be overwritten without warning. If there is an active region, only
+the region will be exported. If the selected region is a single tree,
+the tree head will become the document title. If the tree head entry
+has or inherits an EXPORT_FILE_NAME property, that name will be used for
+the export.
+@kindex C-c C-e b
+@item C-c C-e b
+Export as HTML file and immediately open it with a browser.
+@kindex C-c C-e H
+@item C-c C-e H
+Export to a temporary buffer, do not create a file.
+@kindex C-c C-e R
+@item C-c C-e H
+Export the active region to a temporary buffer. With prefix arg, do not
+produce file header and foot, but just the plain HTML section for the
+region. This is good for cut-and-paste operations.
+@kindex C-c C-e v h
+@kindex C-c C-e v b
+@kindex C-c C-e v H
+@kindex C-c C-e v R
+@item C-c C-e v h
+@item C-c C-e v b
+@item C-c C-e v H
+@item C-c C-e v R
+Export only the visible part of the document.
+@item M-x org-export-region-as-html
+Convert the region to HTML under the assumption that it was org-mode
+syntax before. This is a global command that can be invoked in any
+buffer.
+@item M-x org-replace-region-by-HTML
+Replace the active region (assumed to be in Org-mode syntax) by HTML
+code.
+@end table
+
+@cindex headline levels, for exporting
+In the exported version, the first 3 outline levels will become
+headlines, defining a general document structure. Additional levels
+will be exported as itemized lists. If you want that transition to occur
+at a different level, specify it with a prefix argument. For example,
+
+@example
+@kbd{C-2 C-c C-e b}
+@end example
+
+@noindent
+creates two levels of headings and does the rest as items.
+
+@node Quoting HTML tags, Links, HTML Export commands, HTML export
+@subsection Quoting HTML tags
+
+Plain @samp{<} and @samp{>} are always transformed to @samp{<} and
+@samp{>} in HTML export. If you want to include simple HTML tags
+which should be interpreted as such, mark them with @samp{@@} as in
+@samp{@@<b>bold text@@</b>}. Note that this really works only for
+simple tags. For more extensive HTML that should be copied verbatim to
+the exported file use either
+
+@example
+#+HTML: Literal HTML code for export
+@end example
+
+@noindent or
+
+@example
+#+BEGIN_HTML
+All lines between these markers are exported literally
+#+END_HTML
+@end example
+
+
+@node Links, Images, Quoting HTML tags, HTML export
+@subsection Links
+
+@cindex links, in HTML export
+@cindex internal links, in HTML export
+@cindex external links, in HTML export
+Internal links (@pxref{Internal links}) will continue to work in HTML
+files only if they match a dedicated @samp{<<target>>}. Automatic links
+created by radio targets (@pxref{Radio targets}) will also work in the
+HTML file. Links to external files will still work if the HTML file is
+in the same directory as the Org-mode file. Links to other @file{.org}
+files will be translated into HTML links under the assumption that an
+HTML version also exists of the linked file. For information related to
+linking files while publishing them to a publishing directory see
+@ref{Publishing links}.
+
+@node Images, CSS support, Links, HTML export
+@subsection Images
+
+@cindex images, inline in HTML
+@cindex inlining images in HTML
+HTML export can inline images given as links in the Org-mode file, and
+it can make an image the clickable part of a link. By
+default@footnote{but see the variable
+@code{org-export-html-inline-images}}, images are inlined if a link does
+not have a description. So @samp{[[file:myimg.jpg]]} will be inlined,
+while @samp{[[file:myimg.jpg][the image]]} will just produce a link
+@samp{the image} that points to the image. If the description part
+itself is a @code{file:} link or a @code{http:} URL pointing to an
+image, this image will be inlined and activated so that clicking on the
+image will activate the link. For example, to include a thumbnail that
+will link to a high resolution version of the image, you could use:
+
+@example
+[[file:highres.jpg][file:thumb.jpg]]
+@end example
+
+@noindent
+and you could use @code{http} addresses just as well.
+
+@node CSS support, , Images, HTML export
+@subsection CSS support
+
+You can also give style information for the exported file. The HTML
+exporter assigns the following CSS classes to appropriate parts of the
+document - your style specifications may change these:
+@example
+.todo @r{TODO keywords}
+.done @r{the DONE keyword}
+.timestamp @r{time stamp}
+.timestamp-kwd @r{keyword associated with a time stamp, like SCHEDULED}
+.tag @r{tag in a headline}
+.target @r{target for links}
+@end example
+
+The default style specification can be configured through the option
+@code{org-export-html-style}. If you want to use a file-local style,
+you may use file variables, best wrapped into a COMMENT section at the
+end of the outline tree. For example@footnote{Under Emacs 21, the
+continuation lines for a variable value should have no @samp{#} at the
+start of the line.}:
+
+@example
+* COMMENT html style specifications
+
+# Local Variables:
+# org-export-html-style: " <style type=\"text/css\">
+# p @{font-weight: normal; color: gray; @}
+# h1 @{color: black; @}
+# </style>"
+# End:
+@end example
+
+Remember to execute @kbd{M-x normal-mode} after changing this to make
+the new style visible to Emacs. This command restarts org-mode for the
+current buffer and forces Emacs to re-evaluate the local variables
+section in the buffer.
+
+@c FIXME: More about header and footer styles
+@c FIXME: Talk about links and targets.
+
+@node LaTeX export, XOXO export, HTML export, Exporting
+@section LaTeX export
+@cindex LaTeX export
+
+Org-mode contains a La@TeX{} exporter written by Bastien Guerry.
+
+@menu
+* LaTeX export commands:: How to invoke LaTeX export
+* Quoting LaTeX code:: Incorporating literal LaTeX code
+@end menu
+
+@node LaTeX export commands, Quoting LaTeX code, LaTeX export, LaTeX export
+@subsection LaTeX export commands
+
+@table @kbd
+@kindex C-c C-e l
+@item C-c C-e l
+Export as La@TeX{} file @file{myfile.tex}.
+@kindex C-c C-e L
+@item C-c C-e L
+Export to a temporary buffer, do not create a file.
+@kindex C-c C-e v l
+@kindex C-c C-e v L
+@item C-c C-e v l
+@item C-c C-e v L
+Export only the visible part of the document.
+@item M-x org-export-region-as-latex
+Convert the region to La@TeX{} under the assumption that it was org-mode
+syntax before. This is a global command that can be invoked in any
+buffer.
+@item M-x org-replace-region-by-latex
+Replace the active region (assumed to be in Org-mode syntax) by La@TeX{}
+code.
+@end table
+
+@cindex headline levels, for exporting
+In the exported version, the first 3 outline levels will become
+headlines, defining a general document structure. Additional levels
+will be exported as description lists. The exporter can ignore them or
+convert them to a custom string depending on
+@code{org-latex-low-levels}.
+
+If you want that transition to occur at a different level, specify it
+with a prefix argument. For example,
+
+@example
+@kbd{C-2 C-c C-e l}
+@end example
+
+@noindent
+creates two levels of headings and does the rest as items.
+
+@node Quoting LaTeX code, , LaTeX export commands, LaTeX export
+@subsection Quoting LaTeX code
+
+Embedded La@TeX{} as described in @ref{Embedded LaTeX} will be correctly
+inserted into the La@TeX{} file. Forthermore, you can add special code
+that should only be present in La@TeX{} export with the following
+constructs:
+
+@example
+#+LaTeX: Literal LaTeX code for export
+@end example
+
+@noindent or
+
+@example
+#+BEGIN_LaTeX
+All lines between these markers are exported literally
+#+END_LaTeX
+@end example
+@node XOXO export, iCalendar export, LaTeX export, Exporting
+@section XOXO export
+@cindex XOXO export
+
+Org-mode contains an exporter that produces XOXO-style output.
+Currently, this exporter only handles the general outline structure and
+does not interpret any additional Org-mode features.
+
+@table @kbd
+@kindex C-c C-e x
+@item C-c C-e x
+Export as XOXO file @file{myfile.html}.
+@kindex C-c C-e v
+@item C-c C-e v x
+Export only the visible part of the document.
+@end table
+
+@node iCalendar export, Text interpretation, XOXO export, Exporting
+@section iCalendar export
+@cindex iCalendar export
+
+Some people like to use Org-mode for keeping track of projects, but
+still prefer a standard calendar application for anniversaries and
+appointments. In this case it can be useful to have deadlines and
+other time-stamped items in Org-mode files show up in the calendar
+application. Org-mode can export calendar information in the standard
+iCalendar format. If you also want to have TODO entries included in the
+export, configure the variable @code{org-icalendar-include-todo}.
+
+@table @kbd
+@kindex C-c C-e i
+@item C-c C-e i
+Create iCalendar entries for the current file and store them in the same
+directory, using a file extension @file{.ics}.
+@kindex C-c C-e I
+@item C-c C-e I
+Like @kbd{C-c C-e i}, but do this for all files in
+@code{org-agenda-files}. For each of these files, a separate iCalendar
+file will be written.
+@kindex C-c C-e c
+@item C-c C-e c
+Create a single large iCalendar file from all files in
+@code{org-agenda-files} and write it to the file given by
+@code{org-combined-agenda-icalendar-file}.
+@end table
+
+How this calendar is best read and updated, depends on the application
+you are using. The FAQ covers this issue.
+
+
+@node Text interpretation, , iCalendar export, Exporting
+@section Text interpretation by the exporter
+
+The exporter backends interpret additional structure in the Org-mode file
+in order to produce better output.
+
+@menu
+* Comment lines:: Some lines will not be exported
+* Initial text:: Text before the first headline
+* Footnotes:: Numbers like [1]
+* Enhancing text:: Subscripts, symbols and more
+* Export options:: How to influence the export settings
+@end menu
+
+@node Comment lines, Initial text, Text interpretation, Text interpretation
+@subsection Comment lines
+@cindex comment lines
+@cindex exporting, not
+
+Lines starting with @samp{#} in column zero are treated as comments
+and will never be exported. Also entire subtrees starting with the
+word @samp{COMMENT} will never be exported.
+
+@table @kbd
+@kindex C-c ;
+@item C-c ;
+Toggle the COMMENT keyword at the beginning of an entry.
+@end table
+
+@node Initial text, Footnotes, Comment lines, Text interpretation
+@subsection Text before the first headline
+
+Org-mode normally ignores any text before the first headline when
+exporting, leaving this region for internal links to speed up navigation
+etc. However, in publishing-oriented files, you might want to have some
+text before the first headline, like a small introduction, special HTML
+code with a navigation bar, etc. You can ask to have this part of the
+file exported as well by setting the variable
+@code{org-export-skip-text-before-1st-heading} to @code{nil}. On a
+per-file basis, you can get the same effect with
+
+@example
+#+OPTIONS: skip:nil
+@end example
+
+The text before the first headline will be fully processed
+(@pxref{Enhancing text}), and the first non-comment line becomes the
+title of the exported document. If you need to include literal HTML,
+use the special constructs described in @ref{Quoting HTML tags}. The
+table of contents is normally inserted directly before the first
+headline of the file. If you would like to get it to a different
+location, insert the string @code{[TABLE-OF-CONTENTS]} on a line by
+itself at the desired location.
+
+Finally, if you want to use the space before the first headline for
+internal purposes, but @emph{still} want to place something before the
+first headline when exporting the file, you can use the @code{#+TEXT}
+construct:
+
+@example
+#+OPTIONS: skip:t
+#+TEXT: This text will go before the *first* headline.
+#+TEXT: We place the table of contents here:
+#+TEXT: [TABLE-OF-CONTENTS]
+#+TEXT: This goes between the table of contents and the first headline
+@end example
+
+@node Footnotes, Enhancing text, Initial text, Text interpretation
+@subsection Footnotes
+@cindex footnotes
+@cindex @file{footnote.el}
+
+Numbers in square brackets are treated as footnotes, so that you can use
+the Emacs package @file{footnote.el} to create footnotes. For example:
+
+@example
+The org-mode homepage[1] clearly needs help from
+a good web designer.
+
+[1] The link is: http://www.astro.uva.nl/~dominik/Tools/org
+@end example
+
+@noindent
+@kindex C-c !
+Note that the @file{footnote} package uses @kbd{C-c !} to invoke its
+commands. This binding conflicts with the org-mode command for
+inserting inactive time stamps. You could use the variable
+@code{footnote-prefix} to switch footnotes commands to another key. Or,
+if you are too used to this binding, you could use
+@code{org-replace-disputed-keys} and @code{org-disputed-keys} to change
+the settings in Org-mode.
+
+@node Enhancing text, Export options, Footnotes, Text interpretation
+@subsection Enhancing text for export
+@cindex enhancing text
+@cindex richer text
+
+Some of the export backends of Org-mode allow for sophisticated text
+formatting, this is true in particular for the HTML and La@TeX{}
+backends. Org-mode has a number of typing conventions that allow to
+produce a richly formatted output.
+
+@itemize @bullet
+
+@cindex hand-formatted lists
+@cindex lists, hand-formatted
+@item
+Plain lists @samp{-}, @samp{*} or @samp{+} as bullet, or with @samp{1.}
+or @samp{2)} as enumerator will be recognized and transformed if the
+backend supports lists. See @xref{Plain lists}.
+
+@cindex underlined text
+@cindex bold text
+@cindex italic text
+@item
+You can make words @b{*bold*}, @i{/italic/}, _underlined_,
+@code{=code=}, and even @samp{+strikethrough+}@footnote{but remember
+that strikethrough is typographically evil and should @i{never} be
+used.}.
+
+@cindex horizontal rules, in exported files
+@item
+A line consisting of only dashes, and at least 5 of them, will be
+exported as a horizontal line (@samp{<hr/>} in HTML).
+
+@cindex LaTeX fragments, export
+@cindex TeX macros, export
+@item
+Many @TeX{} macros and entire La@TeX{} fragments are converted into HTML
+entities or images (@pxref{Embedded LaTeX}).
+
+@cindex tables, export
+@item
+Tables are transformed into native tables under the exporter, if the
+export backend supports this. Data fields before the first horizontal
+separator line will be formatted as table header fields.
+
+@cindex fixed width
+@item
+If a headline starts with the word @samp{QUOTE}, the text below the
+headline will be typeset as fixed-width, to allow quoting of computer
+codes etc. Lines starting with @samp{:} are also typeset in fixed-width
+font.
+@table @kbd
+@kindex C-c :
+@item C-c :
+Toggle fixed-width for entry (QUOTE) or region, see below.
+@end table
+
+@cindex linebreak, forced
+@item
+A double backslash @emph{at the end of a line} enforces a line break at
+this position.
+@end itemize
+
+If these conversions conflict with your habits of typing ASCII text,
+they can all be turned off with corresponding variables. See the
+customization group @code{org-export-general}, and the following section
+which explains how to set export options with special lines in a
+buffer.
+
+
+@node Export options, , Enhancing text, Text interpretation
+@subsection Export options
+@cindex options, for export
+
+@cindex completion, of option keywords
+The exporter recognizes special lines in the buffer which provide
+additional information. These lines may be put anywhere in the file.
+The whole set of lines can be inserted into the buffer with @kbd{C-c
+C-e t}. For individual lines, a good way to make sure the keyword is
+correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion
+(@pxref{Completion}).
+
+@table @kbd
+@kindex C-c C-e t
+@item C-c C-e t
+Insert template with export options, see example below.
+@end table
+
+@example
+#+TITLE: the title to be shown (default is the buffer name)
+#+AUTHOR: the author (default taken from @code{user-full-name})
+#+EMAIL: his/her email address (default from @code{user-mail-address})
+#+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language})
+#+TEXT: Some descriptive text to be inserted at the beginning.
+#+TEXT: Several lines may be given.
+#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ...
+@end example
+
+@noindent
+The OPTIONS line is a compact form to specify export settings. Here
+you can:
+@cindex headline levels
+@cindex section-numbers
+@cindex table of contents
+@cindex linebreak preservation
+@cindex quoted HTML tags
+@cindex fixed-width sections
+@cindex tables
+@cindex @TeX{}-like syntax for sub- and superscripts
+@cindex footnotes
+@cindex emphasized text
+@cindex @TeX{} macros
+@cindex La@TeX{} fragments
+@cindex author info, in export
+@cindex time info, in export
+@example
+H: @r{set the number of headline levels for export}
+num: @r{turn on/off section-numbers}
+toc: @r{turn on/off table of contents, or set level limit (integer)}
+\n: @r{turn on/off linebreak-preservation}
+@@: @r{turn on/off quoted HTML tags}
+:: @r{turn on/off fixed-width sections}
+|: @r{turn on/off tables}
+^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If}
+ @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but}
+ @r{the simple @code{a_b} will be left as it is.}
+f: @r{turn on/off foototes like this[1].}
+*: @r{turn on/off emphasized text (bold, italic, underlined)}
+TeX: @r{turn on/off simple @TeX{} macros in plain text}
+LaTeX: @r{turn on/off La@TeX{} fragments}
+skip: @r{turn on/off skipping the text before the first heading}
+author: @r{turn on/off inclusion of author name/email into exported file}
+timestamp: @r{turn on/off inclusion creation time into exported file}
+@end example
+
+These options take effect in both the HTML and La@TeX{} export, except
+for @code{TeX} and @code{LaTeX}, which are respectively @code{t} and
+@code{nil} for the La@TeX{} export.
+
+@node Publishing, Miscellaneous, Exporting, Top
+@chapter Publishing
+@cindex publishing
+
+Org-mode includes@footnote{@file{org-publish.el} is not distributed with
+Emacs 21, if you are still using Emacs 21, you need you need to download
+this file separately.} a publishing management system that allows you to
+configure automatic HTML conversion of @emph{projects} composed of
+interlinked org files. This system is called @emph{org-publish}. You can
+also configure org-publish to automatically upload your exported HTML
+pages and related attachments, such as images and source code files, to
+a web server. Org-publish turns org-mode into a web-site authoring tool.
+
+You can also use Org-publish to convert files into La@TeX{}, or even
+combine HTML and La@TeX{} conversion so that files are available in both
+formats on the server@footnote{Since La@TeX{} files on a server are not
+that helpful, you surely want to perform further conversion on them --
+e.g. convert them to @code{PDF} format.}.
+
+Org-publish has been contributed to Org-mode by David O'Toole.
+
+@menu
+* Configuration:: Defining projects
+* Sample configuration:: Example projects
+* Triggering publication:: Publication commands
+@end menu
+
+@node Configuration, Sample configuration, Publishing, Publishing
+@section Configuration
+
+Publishing needs significant configuration to specify files, destination
+and many other properties of a project.
+
+@menu
+* Project alist:: The central configuration variable
+* Sources and destinations:: From here to there
+* Selecting files:: What files are part of the project?
+* Publishing action:: Setting the function doing the publishing
+* Publishing options:: Tweaking HTML export
+* Publishing links:: Which links keep working after publishing?
+* Project page index:: Publishing a list of project files
+@end menu
+
+@node Project alist, Sources and destinations, Configuration, Configuration
+@subsection The variable @code{org-publish-project-alist}
+@cindex org-publish-project-alist
+@cindex projects, for publishing
+
+Org-publish is configured almost entirely through setting the value of
+one variable, called @code{org-publish-project-alist}.
+Each element of the list configures one project, and may be in one of
+the two following forms:
+
+@lisp
+("project-name" :property value :property value ...)
+
+@r{or}
+
+("project-name" :components ("project-name" "project-name" ...))
+
+@end lisp
+
+In both cases, projects are configured by specifying property values.
+A project defines the set of files that will be published, as well as
+the publishing configuration to use when publishing those files. When
+a project takes the second form listed above, the individual members
+of the ``components'' property are taken to be components of the
+project, which group together files requiring different publishing
+options. When you publish such a ``meta-project'' all the components
+will also publish.
+
+@node Sources and destinations, Selecting files, Project alist, Configuration
+@subsection Sources and destinations for files
+@cindex directories, for publishing
+
+Most properties are optional, but some should always be set. In
+particular, org-publish needs to know where to look for source files,
+and where to put published files.
+
+@multitable @columnfractions 0.3 0.7
+@item @code{:base-directory}
+@tab Directory containing publishing source files
+@item @code{:publishing-directory}
+@tab Directory (possibly remote) where output files will be published.
+@item @code{:preparation-function}
+@tab Function called before starting publishing process, for example to
+run @code{make} for updating files to be published.
+@end multitable
+@noindent
+
+@node Selecting files, Publishing action, Sources and destinations, Configuration
+@subsection Selecting files
+@cindex files, selecting for publishing
+
+By default, all files with extension @file{.org} in the base directory
+are considered part of the project. This can be modified by setting the
+properties
+@multitable @columnfractions 0.25 0.75
+@item @code{:base-extension}
+@tab Extension (without the dot!) of source files. This actually is a
+regular expression.
+
+@item @code{:exclude}
+@tab Regular expression to match file names that should not be
+published, even though they have been selected on the basis of their
+extension.
+
+@item @code{:include}
+@tab List of files to be included regardless of @code{:base-extension}
+and @code{:exclude}.
+@end multitable
+
+@node Publishing action, Publishing options, Selecting files, Configuration
+@subsection Publishing Action
+@cindex action, for publishing
+
+Publishing means that a file is copied to the destination directory and
+possibly transformed in the process. The default transformation is to
+export Org-mode files as HTML files, and this is done by the function
+@code{org-publish-org-to-html} which calls the HTML exporter
+(@pxref{HTML export}). But you also can publish your files in La@TeX{} by
+using the function @code{org-publish-org-to-latex} instead. Other files
+like images only need to be copied to the publishing destination. For
+non-Org-mode files, you need to specify the publishing function.
+
+
+@multitable @columnfractions 0.3 0.7
+@item @code{:publishing-function}
+@tab Function executing the publication of a file. This may also be a
+list of functions, which will all be called in turn.
+@end multitable
+
+The function must accept two arguments: a property list containing at
+least a @code{:publishing-directory} property, and the name of the file
+to be published. It should take the specified file, make the necessary
+transformation (if any) and place the result into the destination folder.
+You can write your own publishing function, but @code{org-publish}
+provides one for attachments (files that only need to be copied):
+@code{org-publish-attachment}.
+
+@node Publishing options, Publishing links, Publishing action, Configuration
+@subsection Options for the HTML/LaTeX exporters
+@cindex options, for publishing
+
+The property list can be used to set many export options for the HTML
+and La@TeX{} exporters. In most cases, these properties correspond to user
+variables in Org-mode. The table below lists these properties along
+with the variable they belong to. See the documentation string for the
+respective variable for details.
+
+@multitable @columnfractions 0.3 0.7
+@item @code{:language} @tab @code{org-export-default-language}
+@item @code{:headline-levels} @tab @code{org-export-headline-levels}
+@item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
+@item @code{:table-of-contents} @tab @code{org-export-with-toc}
+@item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
+@item @code{:emphasize} @tab @code{org-export-with-emphasize}
+@item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts}
+@item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros}
+@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments}
+@item @code{:fixed-width} @tab @code{org-export-with-fixed-width}
+@item @code{:timestamps} .@tab @code{org-export-with-timestamps}
+@item @code{:tags} .@tab @code{org-export-with-tags}
+@item @code{:tables} @tab @code{org-export-with-tables}
+@item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line}
+@item @code{:style} @tab @code{org-export-html-style}
+@item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html}
+@item @code{:inline-images} @tab @code{org-export-html-inline-images}
+@item @code{:expand-quoted-html} @tab @code{org-export-html-expand}
+@item @code{:timestamp} @tab @code{org-export-html-with-timestamp}
+@item @code{:publishing-directory} @tab @code{org-export-publishing-directory}
+@item @code{:preamble} @tab @code{org-export-html-preamble}
+@item @code{:postamble} @tab @code{org-export-html-postamble}
+@item @code{:auto-preamble} @tab @code{org-export-html-auto-preamble}
+@item @code{:auto-postamble} @tab @code{org-export-html-auto-postamble}
+@item @code{:author} @tab @code{user-full-name}
+@item @code{:email} @tab @code{user-mail-address}
+@end multitable
+
+Most of the @code{org-export-with-*} variables have the same effect in
+both HTML and La@TeX{} exporters, except for @code{:TeX-macros} and
+@code{:LaTeX-fragments}, respectively @code{nil} and @code{t} in the
+La@TeX{} export.
+
+When a property is given a value in org-publish-project-alist, its
+setting overrides the value of the corresponding user variable (if any)
+during publishing. Options set within a file (@pxref{Export
+options}), however, override everything.
+
+@node Publishing links, Project page index, Publishing options, Configuration
+@subsection Links between published files
+@cindex links, publishing
+
+To create a link from one Org-mode file to another, you would use
+something like @samp{[[file:foo.org][The foo]]} or simply
+@samp{file:foo.org.} (@pxref{Hyperlinks}). Upon publishing this link
+becomes a link to @file{foo.html}. In this way, you can interlink the
+pages of your "org web" project and the links will work as expected when
+you publish them to HTML.
+
+You may also link to related files, such as images. Provided you are
+careful with relative pathnames, and provided you have also configured
+org-publish to upload the related files, these links will work
+too. @ref{Complex example} for an example of this usage.
+
+Sometime an Org-mode file to be published may contain links that are
+only valid in your production environment, but not in the publishing
+location. In this case, use the property
+
+@multitable @columnfractions 0.4 0.6
+@item @code{:link-validation-function}
+@tab Function to validate links
+@end multitable
+
+@noindent
+to define a function for checking link validity. This function must
+accept two arguments, the file name and a directory relative to which
+the file name is interpreted in the production environment. If this
+function returns @code{nil}, then the HTML generator will only insert a
+description into the HTML file, but no link. One option for this
+function is @code{org-publish-validate-link} which checks if the given
+file is part of any project in @code{org-publish-project-alist}.
+
+@node Project page index, , Publishing links, Configuration
+@subsection Project page index
+@cindex index, of published pages
+
+The following properties may be used to control publishing of an
+index of files or summary page for a given project.
+
+@multitable @columnfractions 0.25 0.75
+@item @code{:auto-index}
+@tab When non-nil, publish an index during org-publish-current-project or
+org-publish-all.
+
+@item @code{:index-filename}
+@tab Filename for output of index. Defaults to @file{index.org} (which
+becomes @file{index.html}).
+
+@item @code{:index-title}
+@tab Title of index page. Defaults to name of file.
+
+@item @code{:index-function}
+@tab Plugin function to use for generation of index.
+Defaults to @code{org-publish-org-index}, which generates a plain list
+of links to all files in the project.
+@end multitable
+
+@node Sample configuration, Triggering publication, Configuration, Publishing
+@section Sample configuration
+
+Below we provide two example configurations. The first one is a simple
+project publishing only a set of Org-mode files. The second example is
+more complex, with a multi-component project.
+
+@menu
+* Simple example:: One-component publishing
+* Complex example:: A multi-component publishing example
+@end menu
+
+@node Simple example, Complex example, Sample configuration, Sample configuration
+@subsection Example: simple publishing configuration
+
+This example publishes a set of Org-mode files to the @file{public_html}
+directory on the local machine.
+
+@lisp
+(setq org-publish-project-alist
+ '(("org"
+ :base-directory "~/org/"
+ :publishing-directory "~/public_html"
+ :section-numbers nil
+ :table-of-contents nil
+ :style "<link rel=stylesheet
+ href=\"../other/mystyle.css\"
+ type=\"text/css\">")))
+@end lisp
+
+@node Complex example, , Simple example, Sample configuration
+@subsection Example: complex publishing configuration
+
+This more complicated example publishes an entire website, including
+org files converted to HTML, image files, emacs lisp source code, and
+stylesheets. The publishing-directory is remote and private files are
+excluded.
+
+To ensure that links are preserved, care should be taken to replicate
+your directory structure on the web server, and to use relative file
+paths. For example, if your org files are kept in @file{~/org} and your
+publishable images in @file{~/images}, you'd link to an image with
+@c
+@example
+file:../images/myimage.png
+@end example
+@c
+On the web server, the relative path to the image should be the
+same. You can accomplish this by setting up an "images" folder in the
+right place on the webserver, and publishing images to it.
+
+@lisp
+(setq org-publish-project-alist
+ '(("orgfiles"
+ :base-directory "~/org/"
+ :base-extension "org"
+ :publishing-directory "/ssh:user@@host:~/html/notebook/"
+ :publishing-function org-publish-org-to-html
+ :exclude "PrivatePage.org" ;; regexp
+ :headline-levels 3
+ :section-numbers nil
+ :table-of-contents nil
+ :style "<link rel=stylesheet
+ href=\"../other/mystyle.css\" type=\"text/css\">"
+ :auto-preamble t
+ :auto-postamble nil)
+
+ ("images"
+ :base-directory "~/images/"
+ :base-extension "jpg\\|gif\\|png"
+ :publishing-directory "/ssh:user@@host:~/html/images/"
+ :publishing-function org-publish-attachment)
+
+ ("other"
+ :base-directory "~/other/"
+ :base-extension "css\\|el"
+ :publishing-directory "/ssh:user@@host:~/html/other/"
+ :publishing-function org-publish-attachment)
+ ("website" :components ("orgfiles" "images" "other"))))
+@end lisp
+
+@node Triggering publication, , Sample configuration, Publishing
+@section Triggering publication
+
+Once org-publish is properly configured, you can publish with the
+following functions:
+
+@table @kbd
+@item C-c C-e C
+Prompt for a specific project and publish all files that belong to it.
+@item C-c C-e P
+Publish the project containing the current file.
+@item C-c C-e F
+Publish only the current file.
+@item C-c C-e A
+Publish all projects.
+@end table
+
+Org uses timestamps to track when a file has changed. The above
+functions normally only publish changed files. You can override this and
+force publishing of all files by giving a prefix argument.
+
+@node Miscellaneous, Extensions and Hacking, Publishing, Top
+@chapter Miscellaneous
+
+@menu
+* Completion:: M-TAB knows what you need
+* Customization:: Adapting Org-mode to your taste
+* In-buffer settings:: Overview of the #+KEYWORDS
+* The very busy C-c C-c key:: When in doubt, press C-c C-c
+* Clean view:: Getting rid of leading stars in the outline
+* TTY keys:: Using Org-mode on a tty
+* Interaction:: Other Emacs packages
+* Bugs:: Things which do not work perfectly
+@end menu
+
+@node Completion, Customization, Miscellaneous, Miscellaneous
+@section Completion
+@cindex completion, of @TeX{} symbols
+@cindex completion, of TODO keywords
+@cindex completion, of dictionary words
+@cindex completion, of option keywords
+@cindex completion, of tags
+@cindex completion, of property keys
+@cindex completion, of link abbreviations
+@cindex @TeX{} symbol completion
+@cindex TODO keywords completion
+@cindex dictionary word completion
+@cindex option keyword completion
+@cindex tag completion
+@cindex link abbreviations, completion of
+
+Org-mode supports in-buffer completion. This type of completion does
+not make use of the minibuffer. You simply type a few letters into
+the buffer and use the key to complete text right there.
+
+@table @kbd
+@kindex M-@key{TAB}
+@item M-@key{TAB}
+Complete word at point
+@itemize @bullet
+@item
+At the beginning of a headline, complete TODO keywords.
+@item
+After @samp{\}, complete @TeX{} symbols supported by the exporter.
+@item
+After @samp{*}, complete headlines in the current buffer so that they
+can be used in search links like @samp{[[*find this headline]]}.
+@item
+After @samp{:} in a headline, complete tags. The list of tags is taken
+from the variable @code{org-tag-alist} (possibly set through the
+@samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created
+dynamically from all tags used in the current buffer.
+@item
+After @samp{:} and not in a headline, complete property keys. The list
+of keys is constructed dynamically from all keys used in the current
+buffer.
+@item
+After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).
+@item
+After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
+@samp{OPTIONS} which set file-specific options for Org-mode. When the
+option keyword is already complete, pressing @kbd{M-@key{TAB}} again
+will insert example settings for this keyword.
+@item
+In the line after @samp{#+STARTUP: }, complete startup keywords,
+i.e. valid keys for this line.
+@item
+Elsewhere, complete dictionary words using ispell.
+@end itemize
+@end table
+
+@node Customization, In-buffer settings, Completion, Miscellaneous
+@section Customization
+@cindex customization
+@cindex options, for customization
+@cindex variables, for customization
+
+There are more than 180 variables that can be used to customize
+Org-mode. For the sake of compactness of the manual, I am not
+describing the variables here. A structured overview of customization
+variables is available with @kbd{M-x org-customize}. Or select
+@code{Browse Org Group} from the @code{Org->Customization} menu. Many
+settings can also be activated on a per-file basis, by putting special
+lines into the buffer (@pxref{In-buffer settings}).
+
+@node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous
+@section Summary of in-buffer settings
+@cindex in-buffer settings
+@cindex special keywords
+
+Org-mode uses special lines in the buffer to define settings on a
+per-file basis. These lines start with a @samp{#+} followed by a
+keyword, a colon, and then individual words defining a setting. Several
+setting words can be in the same line, but you can also have multiple
+lines for the keyword. While these settings are described throughout
+the manual, here is a summary. After changing any of those lines in the
+buffer, press @kbd{C-c C-c} with the cursor still in the line to
+activate the changes immediately. Otherwise they become effective only
+when the file is visited again in a new Emacs session.
+
+@table @kbd
+@item #+ARCHIVE: %s_done::
+This line sets the archive location for the agenda file. It applies for
+all subsequent lines until the next @samp{#+ARCHIVE} line, or the end
+of the file. The first such line also applies to any entries before it.
+The corresponding variable is @code{org-archive-location}.
+@item #+CATEGORY:
+This line sets the category for the agenda file. The category applies
+for all subsequent lines until the next @samp{#+CATEGORY} line, or the
+end of the file. The first such line also applies to any entries before it.
+@item #+COLUMNS: %25ITEM .....
+Set the default format for columns view. This format applies when
+columns view is invoked in location where no COLUMNS property applies.
+@item #+CONSTANTS: name1=value1 ...
+Set file-local values for constants to be used in table formulas. This
+line set the local variable @code{org-table-formula-constants-local}.
+The global version of theis variable is
+@code{org-table-formula-constants}.
+corresponding
+@item #+LINK: linkword replace
+These lines (several are allowed) specify link abbreviations.
+@xref{Link abbreviations}. The corresponding variable is
+@code{org-link-abbrev-alist}.
+@item #+PRIORITIES: highest lowest default
+This line sets the limits and the default for the priorities. All three
+must be either letters A-Z or numbers 0-9. The highest priority must
+have a lower ASCII number that the lowest priority.
+@item #+PROPERTY: Property_Name Value
+This line sets a default inheritance value for entries in the current
+buffer, most useful for specifying the allowed values of a property.
+@item #+STARTUP:
+This line sets options to be used at startup of Org-mode, when an
+Org-mode file is being visited. The first set of options deals with the
+initial visibility of the outline tree. The corresponding variable for
+global default settings is @code{org-startup-folded}, with a default
+value @code{t}, which means @code{overview}.
+@cindex @code{overview}, STARTUP keyword
+@cindex @code{content}, STARTUP keyword
+@cindex @code{showall}, STARTUP keyword
+@example
+overview @r{top-level headlines only}
+content @r{all headlines}
+showall @r{no folding at all, show everything}
+@end example
+Then there are options for aligning tables upon visiting a file. This
+is useful in files containing narrowed table columns. The corresponding
+variable is @code{org-startup-align-all-tables}, with a default value
+@code{nil}.
+@cindex @code{align}, STARTUP keyword
+@cindex @code{noalign}, STARTUP keyword
+@example
+align @r{align all tables}
+noalign @r{don't align tables on startup}
+@end example
+Logging TODO state changes and clock intervals (variable
+@code{org-log-done}) can be configured using these options.
+@cindex @code{logdone}, STARTUP keyword
+@cindex @code{nologging}, STARTUP keyword
+@cindex @code{lognotedone}, STARTUP keyword
+@cindex @code{lognoteclock-out}, STARTUP keyword
+@cindex @code{lognotestate}, STARTUP keyword
+@cindex @code{logrepeat}, STARTUP keyword
+@cindex @code{nologrepeat}, STARTUP keyword
+@example
+logging @r{record a timestamp when an item is marked DONE}
+nologging @r{don't record when items are marked DONE}
+lognotedone @r{record timestamp and a note when DONE}
+lognotestate @r{record timestamp and a note when TODO state changes}
+logrepeat @r{record a note when re-instating a repeating item}
+nologrepeat @r{do not record when re-instating repeating item}
+lognoteclock-out @r{record timestamp and a note when clocking out}
+@end example
+Here are the options for hiding leading stars in outline headings. The
+corresponding variables are @code{org-hide-leading-stars} and
+@code{org-odd-levels-only}, both with a default setting @code{nil}
+(meaning @code{showstars} and @code{oddeven}).
+@cindex @code{hidestars}, STARTUP keyword
+@cindex @code{showstars}, STARTUP keyword
+@cindex @code{odd}, STARTUP keyword
+@cindex @code{even}, STARTUP keyword
+@example
+hidestars @r{make all but one of the stars starting a headline invisible.}
+showstars @r{show all stars starting a headline}
+odd @r{allow only odd outline levels (1,3,...)}
+oddeven @r{allow all outline levels}
+@end example
+To turn on custom format overlays over time stamps (variables
+@code{org-put-time-stamp-overlays} and
+@code{org-time-stamp-overlay-formats}), use
+@cindex @code{customtime}, STARTUP keyword
+@example
+customtime @r{overlay custom time format}
+@end example
+The following options influence the table spreadsheet (variable
+@code{constants-unit-system}).
+@cindex @code{constcgs}, STARTUP keyword
+@cindex @code{constSI}, STARTUP keyword
+@example
+constcgs @r{@file{constants.el} should use the c-g-s unit system}
+constSI @r{@file{constants.el} should use the SI unit system}
+@end example
+@item #+TAGS: TAG1(c1) TAG2(c2)
+These lines (several such lines are allowed) specify the legal tags in
+this file, and (potentially) the corresponding @emph{fast tag selection}
+keys. The corresponding variable is @code{org-tag-alist}.
+@item #+TBLFM:
+This line contains the formulas for the table directly above the line.
+@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS:
+These lines provide settings for exporting files. For more details see
+@ref{Export options}.
+@item #+SEQ_TODO: #+TYP_TODO:
+These lines set the TODO keywords and their interpretation in the
+current file. The corresponding variables are @code{org-todo-keywords}
+and @code{org-todo-interpretation}.
+@end table
+
+@node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous
+@section The very busy C-c C-c key
+@kindex C-c C-c
+@cindex C-c C-c, overview
+
+The key @kbd{C-c C-c} has many purposes in org-mode, which are all
+mentioned scattered throughout this manual. One specific function of
+this key is to add @emph{tags} to a headline (@pxref{Tags}). In many
+other circumstances it means something like @emph{Hey Org-mode, look
+here and update according to what you see here}. Here is a summary of
+what this means in different contexts.
+
+@itemize @minus
+@item
+If there are highlights in the buffer from the creation of a sparse
+tree, or from clock display, remove these highlights.
+@item
+If the cursor is in one of the special @code{#+KEYWORD} lines, this
+triggers scanning the buffer for these lines and updating the
+information.
+@item
+If the cursor is inside a table, realign the table. This command
+works even if the automatic table editor has been turned off.
+@item
+If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
+the entire table.
+@item
+If the cursor is inside a table created by the @file{table.el} package,
+activate that table.
+@item
+If the current buffer is a remember buffer, close the note and file it.
+With a prefix argument, file it, without further interaction, to the
+default location.
+@item
+If the cursor is on a @code{<<<target>>>}, update radio targets and
+corresponding links in this buffer.
+@item
+If the cursor is in a property line or at the start or end of a property
+drawer, offer property commands.
+@item
+If the cursor is in a plain list item with a checkbox, toggle the status
+of the checkbox.
+@item
+If the cursor is on a numbered item in a plain list, renumber the
+ordered list.
+@end itemize
+
+@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
+@section A cleaner outline view
+@cindex hiding leading stars
+@cindex clean outline view
+
+Some people find it noisy and distracting that the Org-mode headlines
+are starting with a potentially large number of stars. For example
+the tree from @ref{Headlines}:
+
+@example
+* Top level headline
+** Second level
+*** 3rd level
+ some text
+*** 3rd level
+ more text
+* Another top level headline
+@end example
+
+@noindent
+Unfortunately this is deeply ingrained into the code of Org-mode and
+cannot be easily changed. You can, however, modify the display in such
+a way that all leading stars become invisible and the outline more easy
+to read. To do this, customize the variable
+@code{org-hide-leading-stars} like this:
+
+@lisp
+(setq org-hide-leading-stars t)
+@end lisp
+
+@noindent
+or change this on a per-file basis with one of the lines (anywhere in
+the buffer)
+
+@example
+#+STARTUP: showstars
+#+STARTUP: hidestars
+@end example
+
+@noindent
+Press @kbd{C-c C-c} with the cursor in a @samp{STARTUP} line to activate
+the modifications.
+
+With stars hidden, the tree becomes:
+
+@example
+* Top level headline
+ * Second level
+ * 3rd level
+ some text
+ * 3rd level
+ more text
+* Another top level headline
+@end example
+
+@noindent
+Note that the leading stars are not truly replaced by whitespace, they
+are only fontified with the face @code{org-hide} that uses the
+background color as font color. If you are not using either white or
+black background, you may have to customize this face to get the wanted
+effect. Another possibility is to set this font such that the extra
+stars are @i{almost} invisible, for example using the color
+@code{grey90} on a white background.
+
+Things become cleaner still if you skip all the even levels and use only
+odd levels 1, 3, 5..., effectively adding two stars to go from one
+outline level to the next:
+
+@example
+* Top level headline
+ * Second level
+ * 3rd level
+ some text
+ * 3rd level
+ more text
+* Another top level headline
+@end example
+
+@noindent
+In order to make the structure editing and export commands handle this
+convention correctly, use
+
+@lisp
+(setq org-odd-levels-only t)
+@end lisp
+
+@noindent
+or set this on a per-file basis with one of the following lines (don't
+forget to press @kbd{C-c C-c} with the cursor in the startup line to
+activate changes immediately).
+
+@example
+#+STARTUP: odd
+#+STARTUP: oddeven
+@end example
+
+You can convert an Org-mode file from single-star-per-level to the
+double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels
+RET} in that file. The reverse operation is @kbd{M-x
+org-convert-to-oddeven-levels}.
+
+@node TTY keys, Interaction, Clean view, Miscellaneous
+@section Using org-mode on a tty
+@cindex tty keybindings
+
+Org-mode uses a number of keys that are not accessible on a tty. This
+applies to most special keys like cursor keys, @key{TAB} and
+@key{RET}, when these are combined with modifier keys like @key{Meta}
+and/or @key{Shift}. Org-mode uses these bindings because it needs to
+provide keys for a large number of commands, and because these keys
+appeared particularly easy to remember. In order to still be able to
+access the core functionality of Org-mode on a tty, alternative
+bindings are provided. Here is a complete list of these bindings,
+which are obviously more cumbersome to use. Note that sometimes a
+work-around can be better. For example changing a time stamp is
+really only fun with @kbd{S-@key{cursor}} keys. On a tty you would
+rather use @kbd{C-c .} to re-insert the timestamp.
+
+@multitable @columnfractions 0.15 0.2 0.2
+@item @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2}
+@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab
+@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{@key{Esc} @key{left}}
+@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab
+@item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{@key{Esc} @key{right}}
+@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab
+@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{@key{Esc} @key{up}}
+@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab
+@item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{@key{Esc} @key{down}}
+@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab
+@item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab
+@item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{@key{Esc} @key{RET}}
+@item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab
+@item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab
+@item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab
+@item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab
+@item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab
+@item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab
+@item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab
+@end multitable
+
+@node Interaction, Bugs, TTY keys, Miscellaneous
+@section Interaction with other packages
+@cindex packages, interaction with other
+Org-mode lives in the world of GNU Emacs and interacts in various ways
+with other code out there.
+
+@menu
+* Cooperation:: Packages Org-mode cooperates with
+* Conflicts:: Packages that lead to conflicts
+@end menu
+
+@node Cooperation, Conflicts, Interaction, Interaction
+@subsection Packages that Org-mode cooperates with
+
+@table @asis
+@cindex @file{calc.el}
+@item @file{calc.el} by Dave Gillespie
+Org-mode uses the calc package for implementing spreadsheet
+functionality in its tables (@pxref{The spreadsheet}). Org-mode
+checks for the availability of calc by looking for the function
+@code{calc-eval} which should be autoloaded in your setup if calc has
+been installed properly. As of Emacs 22, calc is part of the Emacs
+distribution. Another possibility for interaction between the two
+packages is using calc for embedded calculations. @xref{Embedded Mode,
+, Embedded Mode, calc, GNU Emacs Calc Manual}.
+@cindex @file{constants.el}
+@item @file{constants.el} by Carsten Dominik
+In a table formula (@pxref{The spreadsheet}), it is possible to use
+names for natural constants or units. Instead of defining your own
+constants in the variable @code{org-table-formula-constants}, install
+the @file{constants} package which defines a large number of constants
+and units, and lets you use unit prefixes like @samp{M} for
+@samp{Mega} etc. You will need version 2.0 of this package, available
+at @url{http://www.astro.uva.nl/~dominik/Tools}. Org-mode checks for
+the function @code{constants-get}, which has to be autoloaded in your
+setup. See the installation instructions in the file
+@file{constants.el}.
+@item @file{cdlatex.el} by Carsten Dominik
+@cindex @file{cdlatex.el}
+Org-mode can make use of the cdlatex package to efficiently enter
+La@TeX{} fragments into Org-mode files. See @ref{CDLaTeX mode}.
+@item @file{remember.el} by John Wiegley
+@cindex @file{remember.el}
+Org mode cooperates with remember, see @ref{Remember}.
+@file{Remember.el} is not part of Emacs, find it on the web.
+@cindex @file{table.el}
+@item @file{table.el} by Takaaki Ota
+@kindex C-c C-c
+@cindex table editor, @file{table.el}
+@cindex @file{table.el}
+
+Complex ASCII tables with automatic line wrapping, column- and
+row-spanning, and alignment can be created using the Emacs table
+package by Takaaki Ota (@uref{http://sourceforge.net/projects/table},
+and also part of Emacs 22).
+When @key{TAB} or @kbd{C-c C-c} is pressed in such a table, Org-mode
+will call @command{table-recognize-table} and move the cursor into the
+table. Inside a table, the keymap of Org-mode is inactive. In order
+to execute Org-mode-related commands, leave the table.
+
+@table @kbd
+@kindex C-c C-c
+@item C-c C-c
+Recognize @file{table.el} table. Works when the cursor is in a
+table.el table.
+@c
+@kindex C-c ~
+@item C-c ~
+Insert a table.el table. If there is already a table at point, this
+command converts it between the table.el format and the Org-mode
+format. See the documentation string of the command
+@code{org-convert-table} for the restrictions under which this is
+possible.
+@end table
+@file{table.el} is part of Emacs 22.
+@cindex @file{footnote.el}
+@item @file{footnote.el} by Steven L. Baur
+Org-mode recognizes numerical footnotes as provided by this package
+(@pxref{Footnotes}).
+@end table
+
+@node Conflicts, , Cooperation, Interaction
+@subsection Packages that lead to conflicts with Org-mode
+
+@table @asis
+
+@cindex @file{allout.el}
+@item @file{allout.el} by Ken Manheimer
+Startup of Org-mode may fail with the error message
+@code{(wrong-type-argument keymapp nil)} when there is an outdated
+version @file{allout.el} on the load path, for example the version
+distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem will
+disappear. If for some reason you cannot do this, make sure that org.el
+is loaded @emph{before} @file{allout.el}, for example by putting
+@code{(require 'org)} early enough into your @file{.emacs} file.
+
+@cindex @file{CUA.el}
+@item @file{CUA.el} by Kim. F. Storm
+Keybindings in Org-mode conflict with the @kbd{S-<cursor>} keys
+used by CUA-mode (as well as pc-select-mode and s-region-mode) to
+select and extend the region. If you want to use one of these
+packages along with Org-mode, configure the variable
+@code{org-CUA-compatible}. When set, Org-mode will move the following
+keybindings in Org-mode files, and in the agenda buffer (but not
+during date selection).
+
+@example
+S-UP -> M-p S-DOWN -> M-n
+S-LEFT -> M-- S-RIGHT -> M-+
+@end example
+
+Yes, these are unfortunately more difficult to remember. If you want
+to have other replacement keys, look at the variable
+@code{org-disputed-keys}.
+@item @file{windmove.el} by Hovav Shacham
+@cindex @file{windmove.el}
+Also this package uses the @kbd{S-<cursor>} keys, so everything written
+in the paragraph above about CUA mode also applies here.
+
+@cindex @file{footnote.el}
+@item @file{footnote.el} by Steven L. Baur
+Org-mode supports the syntax of the footnote package, but only the
+numerical footnote markers. Also, the default key for footnote
+commands, @kbd{C-c !} is already used by Org-mode. You could use the
+variable @code{footnote-prefix} to switch footnotes commands to another
+key. Or, you could use @code{org-replace-disputed-keys} and
+@code{org-disputed-keys} to change the settings in Org-mode.
+
+@end table
+
+
+@node Bugs, , Interaction, Miscellaneous
+@section Bugs
+@cindex bugs
+
+Here is a list of things that should work differently, but which I
+have found too hard to fix.
+
+@itemize @bullet
+@item
+If a table field starts with a link, and if the corresponding table
+column is narrowed (@pxref{Narrow columns}) to a width too small to
+display the link, the field would look entirely empty even though it is
+not. To prevent this, Org-mode throws an error. The work-around is to
+make the column wide enough to fit the link, or to add some text (at
+least 2 characters) before the link in the same field.
+@item
+Narrowing table columns does not work on XEmacs, because the
+@code{format} function does not transport text properties.
+@item
+Text in an entry protected with the @samp{QUOTE} keyword should not
+autowrap.
+@item
+When the application called by @kbd{C-c C-o} to open a file link fails
+(for example because the application does not exist or refuses to open
+the file), it does so silently. No error message is displayed.
+@item
+Recalculating a table line applies the formulas from left to right.
+If a formula uses @emph{calculated} fields further down the row,
+multiple recalculation may be needed to get all fields consistent. You
+may use the command @code{org-table-iterate} (@kbd{C-u C-c *}) to
+recalculate until convergence.
+@item
+A single letter cannot be made bold, for example @samp{*a*}.
+@item
+The exporters work well, but could be made more efficient.
+@end itemize
+
+
+@node Extensions and Hacking, History and Acknowledgments, Miscellaneous, Top
+@appendix Extensions, Hooks and Hacking
+
+This appendix lists extensions for Org-mode written by other authors.
+It also covers some aspects where users can extend the functionality of
+Org-mode.
+
+@menu
+* Extensions:: Existing 3rd-part extensions
+* Adding hyperlink types:: New custom link types
+* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
+* Dynamic blocks:: Automatically filled blocks
+* Special agenda views:: Customized views
+* Using the property API:: Writing programs that use entry properties
+@end menu
+
+@node Extensions, Adding hyperlink types, Extensions and Hacking, Extensions and Hacking
+@section Third-party extensions for Org-mode
+@cindex extension, third-party
+
+The following extensions for Org-mode have been written by other people:
+
+@table @asis
+@cindex @file{org-publish.el}
+@item @file{org-publish.el} by David O'Toole
+This package provides facilities for publishing related sets of Org-mode
+files together with linked files like images as webpages. It is
+highly configurable and can be used for other publishing purposes as
+well. As of Org-mode version 4.30, @file{org-publish.el} is part of the
+Org-mode distribution. It is not yet part of Emacs, however, a delay
+caused by the preparations for the 22.1 release. In the mean time,
+@file{org-publish.el} can be downloaded from David's site:
+@url{http://dto.freeshell.org/e/org-publish.el}.
+@cindex @file{org-mouse.el}
+@item @file{org-mouse.el} by Piotr Zielinski
+This package implements extended mouse functionality for Org-mode. It
+allows you to cycle visibility and to edit the document structure with
+the mouse. Best of all, it provides a context-sensitive menu on
+@key{mouse-3} that changes depending on the context of a mouse-click.
+As of Org-mode version 4.53, @file{org-mouse.el} is part of the
+Org-mode distribution. It is not yet part of Emacs, however, a delay
+caused by the preparations for the 22.1 release. In the mean time,
+@file{org-mouse.el} can be downloaded from Piotr's site:
+@url{http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el}.
+@cindex @file{org-blog.el}
+@item @file{org-blog.el} by David O'Toole
+A blogging plug-in for @file{org-publish.el}.@*
+@url{http://dto.freeshell.org/notebook/OrgMode.html}.
+@cindex @file{blorg.el}
+@item @file{blorg.el} by Bastien Guerry
+Publish Org-mode files as
+blogs. @url{http://www.cognition.ens.fr/~guerry/blorg.html}.
+@cindex @file{org2rem.el}
+@item @file{org2rem.el} by Bastien Guerry
+Translates Org-mode files into something readable by
+Remind. @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}.
+@end table
+
+@page
+
+@node Adding hyperlink types, Tables in arbitrary syntax, Extensions, Extensions and Hacking
+@section Adding hyperlink types
+@cindex hyperlinks, adding new types
+
+Org-mode has a large number of hyperlink types built-in
+(@pxref{Hyperlinks}). If you would like to add new link types, it
+provides an interface for doing so. Lets look at an example file
+@file{org-man.el} that will add support for creating links like
+@samp{[[man:printf][The printf manpage]]} to show unix manual pages inside
+emacs:
+
+@lisp
+;;; org-man.el - Support for links to manpages in Org-mode
+
+(require 'org)
+
+(org-add-link-type "man" 'org-man-open)
+(add-hook 'org-store-link-functions 'org-man-store-link)
+
+(defcustom org-man-command 'man
+ "The Emacs command to be used to display a man page."
+ :group 'org-link
+ :type '(choice (const man) (const woman)))
+
+(defun org-man-open (path)
+ "Visit the manpage on PATH.
+PATH should be a topic that can be thrown at the man command."
+ (funcall org-man-command path))
+
+(defun org-man-store-link ()
+ "Store a link to a manpage."
+ (when (memq major-mode '(Man-mode woman-mode))
+ ;; This is a man page, we do make this link
+ (let* ((page (org-man-get-page-name))
+ (link (concat "man:" page))
+ (description (format "Manpage for %s" page)))
+ (org-store-link-props
+ :type "man"
+ :link link
+ :description description))))
+
+(defun org-man-get-page-name ()
+ "Extract the page name from the buffer name."
+ ;; This works for both `Man-mode' and `woman-mode'.
+ (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
+ (match-string 1 (buffer-name))
+ (error "Cannot create link to this man page")))
+
+(provide 'org-man)
+
+;;; org-man.el ends here
+@end lisp
+
+@noindent
+You would activate this new link type in @file{.emacs} with
+
+@lisp
+(require 'org-man)
+@end lisp
+
+@noindent
+Lets go through the file and see what it does.
+@enumerate
+@item
+It does @code{(require 'org)} to make sure that @file{org.el} has been
+loaded.
+@item
+The next line calls @code{org-add-link-type} to define a new link type
+with prefix @samp{man}. The call also contains the name of a function
+that will be called to follow such a link.
+@item
+The next line adds a function to @code{org-store-link-functions}, in
+order to allow the command @kbd{C-c l} to record a useful link in a
+buffer displaying a man page.
+@end enumerate
+
+The rest of the file defines the necessary variables and functions.
+First there is a customization variable that determines which emacs
+command should be used to display manpages. There are two options,
+@code{man} and @code{woman}. Then the function to follow a link is
+defined. It gets the link path as an argument - in this case the link
+path is just a topic for the manual command. The function calls the
+value of @code{org-man-command} to display the man page.
+
+Finally the function @code{org-man-store-link} is defined. When you try
+to store a link with @kbd{C-c l}, also this function will be called to
+try to make a link. The function must first decide if it is supposed to
+create the link for this buffer type, we do this by checking the value
+of the variable @code{major-mode}. If not, the function must exit and
+retunr the value @code{nil}. If yes, the link is created by getting the
+manual tpoic from the buffer name and prefixing it with the string
+@samp{man:}. Then it must call the command @code{org-store-link-props}
+and set the @code{:type} and @code{:link} properties. Optionally you
+can also set the @code{:description} property to provide a default for
+the link description when the link is later inserted into tan Org-mode
+buffer with @kbd{C-c C-l}.
+
+@node Tables in arbitrary syntax, Dynamic blocks, Adding hyperlink types, Extensions and Hacking
+@section Tables in arbitrary syntax
+@cindex tables, in other modes
+@cindex orgtbl-mode
+
+Since Orgtbl-mode can be used as a minor mode in arbitrary buffers, a
+frequent feature request has been to make it work with native tables in
+specific languages, for example La@TeX{}. However, this is extremely hard
+to do in a general way, would lead to a customization nightmare, and
+would take away much of the simplicity of the Orgtbl-mode table editor.
+
+This appendix describes a different approach. We keep the Orgtbl-mode
+table in its native format (the @i{source table}), and use a custom
+function to @i{translate} the table to the correct syntax, and to
+@i{install} it in the right location (the @i{target table}). This puts
+the burden of writing conversion functions on the user, but it allows
+for a very flexible system.
+
+@menu
+* Radio tables:: Sending and receiving
+* A LaTeX example:: Step by step, almost a tutorial
+* Translator functions:: Copy and modify
+@end menu
+
+@node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax
+@subsection Radio tables
+@cindex radio tables
+
+To define the location of the target table, you first need to create two
+lines that are comments in the current mode, but contain magic words for
+Orgtbl-mode to find. Orgtbl-mode will insert the translated table
+between these lines, replacing whatever was there before. For example:
+
+@example
+/* BEGIN RECEIVE ORGTBL table_name */
+/* END RECEIVE ORGTBL table_name */
+@end example
+
+@noindent
+Just above the source table, we put a special line that tells
+Orgtbl-mode how to translate this table and where to install it. For
+example:
+@example
+#+ORGTBL: SEND table_name translation_function arguments....
+@end example
+
+@noindent
+@code{table_name} is the reference name for the table that is also used
+in the receiver lines. @code{translation_function} is the Lisp function
+that does the translation. Furthermore, the line can contain a list of
+arguments (alternating key and value) at the end. The arguments will be
+passed as a property list to the translation function for
+interpretation. A few standard parameters are already recognized and
+acted upon before the translation function is called:
+
+@table @code
+@item :skip N
+Skip the first N lines of the table. Hlines do count!
+@item :skipcols (n1 n2 ...)
+List of columns that should be skipped. If the table has a column with
+calculation marks, that column is automatically discarded as well.
+Please note that the translator function sees the table @emph{after} the
+removal of these columns, the function never knows that there have been
+additional columns.
+@end table
+
+@noindent
+The one problem remaining is how to keep the source table in the buffer
+without disturbing the normal workings of the file, for example during
+compilation of a C file or processing of a La@TeX{} file. There are a
+number of different solutions:
+
+@itemize @bullet
+@item
+The table could be placed in a block comment if that is supported by the
+language. For example, in C-mode you could wrap the table between
+@samp{/*} and @samp{*/} lines.
+@item
+Sometimes it is possible to put the table after some kind of @i{END}
+statement, for example @samp{\bye} in TeX and @samp{\end@{document@}}
+in La@TeX{}.
+@item
+You can just comment the table line by line whenever you want to process
+the file, and uncomment it whenever you need to edit the table. This
+only sounds tedious - the command @kbd{M-x orgtbl-toggle-comment} does
+make this comment-toggling very easy, in particular if you bind it to a
+key.
+@end itemize
+
+@node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax
+@subsection A LaTeX example
+@cindex LaTeX, and orgtbl-mode
+
+The best way to wrap the source table in La@TeX{} is to use the
+@code{comment} environment provided by @file{comment.sty}. It has to be
+activated by placing @code{\usepackage@{comment@}} into the document
+header. Orgtbl-mode can insert a radio table skeleton@footnote{By
+default this works only for La@TeX{}, HTML, and TeXInfo. Configure the
+variable @code{orgtbl-radio-tables} to install templates for other
+modes.} with the command @kbd{M-x orgtbl-insert-radio-table}. You will
+be prompted for a table name, lets say we use @samp{salesfigures}. You
+will then get the following template:
+
+@example
+% BEGIN RECEIVE ORGTBL salesfigures
+% END RECEIVE ORGTBL salesfigures
+\begin@{comment@}
+#+ORGTBL: SEND salesfigures orgtbl-to-latex
+| | |
+\end@{comment@}
+@end example
+
+@noindent
+The @code{#+ORGTBL: SEND} line tells orgtbl-mode to use the function
+@code{orgtbl-to-latex} to convert the table into La@TeX{} and to put it
+into the receiver location with name @code{salesfigures}. You may now
+fill in the table, feel free to use the spreadsheet features@footnote{If
+the @samp{#+TBLFM} line contains an odd number of dollar characters,
+this may cause problems with font-lock in latex-mode. As shown in the
+example you can fix this by adding an extra line inside the
+@code{comment} environment that is used to balance the dollar
+expressions. If you are using AUCTeX with the font-latex library, a
+much better solution is to add the @code{comment} environment to the
+variable @code{LaTeX-verbatim-environments}.}:
+
+@example
+% BEGIN RECEIVE ORGTBL salesfigures
+% END RECEIVE ORGTBL salesfigures
+\begin@{comment@}
+#+ORGTBL: SEND salesfigures orgtbl-to-latex
+| Month | Days | Nr sold | per day |
+|-------+------+---------+---------|
+| Jan | 23 | 55 | 2.4 |
+| Feb | 21 | 16 | 0.8 |
+| March | 22 | 278 | 12.6 |
+#+TBLFM: $4=$3/$2;%.1f
+% $ (optional extra dollar to keep font-lock happy, see footnote)
+\end@{comment@}
+@end example
+
+@noindent
+When you are done, press @kbd{C-c C-c} in the table to get the converted
+table inserted between the two marker lines.
+
+Now lets assume you want to make the table header by hand, because you
+want to control how columns are aligned etc. In this case we make sure
+that the table translator does skip the first 2 lines of the source
+table, and tell the command to work as a @i{splice}, i.e. to not produce
+header and footer commands of the target table:
+
+@example
+\begin@{tabular@}@{lrrr@}
+Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\
+% BEGIN RECEIVE ORGTBL salesfigures
+% END RECEIVE ORGTBL salesfigures
+\end@{tabular@}
+%
+\begin@{comment@}
+#+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
+| Month | Days | Nr sold | per day |
+|-------+------+---------+---------|
+| Jan | 23 | 55 | 2.4 |
+| Feb | 21 | 16 | 0.8 |
+| March | 22 | 278 | 12.6 |
+#+TBLFM: $4=$3/$2;%.1f
+\end@{comment@}
+@end example
+
+The La@TeX{} translator function @code{orgtbl-to-latex} is already part of
+Orgtbl-mode. It uses a @code{tabular} environment to typeset the table
+and marks horizontal lines with @code{\hline}. Furthermore, it
+interprets the following parameters:
+
+@table @code
+@item :splice nil/t
+When set to t, return only table body lines, don't wrap them into a
+tabular environment. Default is nil.
+
+@item :fmt fmt
+A format to be used to wrap each field, should contain @code{%s} for the
+original field value. For example, to wrap each field value in dollars,
+you could use @code{:fmt "$%s$"}. This may also be a property list with
+column numbers and formats. for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.
+
+@item :efmt efmt
+Use this format to print numbers with exponentials. The format should
+have @code{%s} twice for inserting mantissa and exponent, for example
+@code{"%s\\times10^@{%s@}"}. The default is @code{"%s\\,(%s)"}. This
+may also be a property list with column numbers and formats, for example
+@code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After
+@code{efmt} has been applied to a value, @code{fmt} will also be
+applied.
+@end table
+
+@node Translator functions, , A LaTeX example, Tables in arbitrary syntax
+@subsection Translator functions
+@cindex HTML, and orgtbl-mode
+@cindex translator function
+
+Orgtbl-mode has several translator functions built-in:
+@code{orgtbl-to-latex}, @code{orgtbl-to-html}, and
+@code{orgtbl-to-texinfo}. Except for @code{orgtbl-to-html}@footnote{The
+HTML translator uses the same code that produces tables during HTML
+export.}, these all use a generic translator, @code{orgtbl-to-generic}.
+For example, @code{orgtbl-to-latex} itself is a very short function that
+computes the column definitions for the @code{tabular} environment,
+defines a few field and line separators and then hands over to the
+generic translator. Here is the entire code:
+
+@lisp
+@group
+(defun orgtbl-to-latex (table params)
+ "Convert the orgtbl-mode TABLE to LaTeX."
+ (let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
+ org-table-last-alignment ""))
+ (params2
+ (list
+ :tstart (concat "\\begin@{tabular@}@{" alignment "@}")
+ :tend "\\end@{tabular@}"
+ :lstart "" :lend " \\\\" :sep " & "
+ :efmt "%s\\,(%s)" :hline "\\hline")))
+ (orgtbl-to-generic table (org-combine-plists params2 params))))
+@end group
+@end lisp
+
+As you can see, the properties passed into the function (variable
+@var{PARAMS}) are combined with the ones newly defined in the function
+(variable @var{PARAMS2}). The ones passed into the function (i.e. the
+ones set by the @samp{ORGTBL SEND} line) take precedence. So if you
+would like to use the La@TeX{} translator, but wanted the line endings to
+be @samp{\\[2mm]} instead of the default @samp{\\}, you could just
+overrule the default with
+
+@example
+#+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
+@end example
+
+For a new language, you can either write your own converter function in
+analogy with the La@TeX{} translator, or you can use the generic function
+directly. For example, if you have a language where a table is started
+with @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines are
+started with @samp{!BL!}, ended with @samp{!EL!} and where the field
+separator is a TAB, you could call the generic translator like this (on
+a single line!):
+
+@example
+#+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
+ :lstart "!BL! " :lend " !EL!" :sep "\t"
+@end example
+
+@noindent
+Please check the documentation string of the function
+@code{orgtbl-to-generic} for a full list of parameters understood by
+that function and remember that you can pass each of them into
+@code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function
+using the generic function.
+
+Of course you can also write a completely new function doing complicated
+things the generic translator cannot do. A translator function takes
+two arguments. The first argument is the table, a list of lines, each
+line either the symbol @code{hline} or a list of fields. The second
+argument is the property list containing all parameters specified in the
+@samp{#+ORGTBL: SEND} line. The function must return a single string
+containing the formatted table. If you write a generally useful
+translator, please post it on @code{emacs-orgmode@@gnu.org} so that
+others can benefit from your work.
+
+@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Extensions and Hacking
+@section Dynamic blocks
+@cindex dynamic blocks
+
+Org-mode documents can contain @emph{dynamic blocks}. These are
+specially marked regions that are updated by some user-written function.
+A good example for such a block is the clock table inserted by the
+command @kbd{C-c C-x C-r} (@pxref{Clocking work time}).
+
+Dynamic block are enclosed by a BEGIN-END structure that assigns a name
+to the block and can also specify parameters for the function producing
+the content of the block.
+
+@example
+#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
+
+#+END:
+@end example
+
+Dynamic blocks are updated with the following commands
+
+@table @kbd
+@kindex C-c C-x C-u
+@item C-c C-x C-u
+Update dynamic block at point.
+@kindex C-u C-c C-x C-u
+@item C-u C-c C-x C-u
+Update all dynamic blocks in the current file.
+@end table
+
+Updating a dynamic block means to remove all the text between BEGIN and
+END, parse the BEGIN line for parameters and then call the specific
+writer function for this block to insert the new content. For a block
+with name @code{myblock}, the writer function is
+@code{org-dblock-write:myblock} with as only parameter a property list
+with the parameters given in the begin line. Here is a trivial example
+of a block that keeps track of when the block update function was last
+run:
+
+@example
+#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
+
+#+END:
+@end example
+
+@noindent
+The corresponding block writer function could look like this:
+
+@lisp
+(defun org-dblock-write:block-update-time (params)
+ (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
+ (insert "Last block update at: "
+ (format-time-string fmt (current-time)))))
+@end lisp
+
+If you want to make sure that all dynamic blocks are always up-to-date,
+you could add the function @code{org-update-all-dblocks} to a hook, for
+example @code{before-save-hook}. @code{org-update-all-dblocks} is
+written in a way that is does nothing in buffers that are not in Org-mode.
+
+@node Special agenda views, Using the property API, Dynamic blocks, Extensions and Hacking
+@section Special Agenda Views
+@cindex agenda views, user-defined
+
+Org-mode provides a special hook that can be used to narrow down the
+selection made by any of the agenda views. You may specify a function
+that is used at each match to verify if the match should indeed be part
+of the agenda view, and if not, how much should be skipped.
+
+Let's say you want to produce a list of projects that contain a WAITING
+tag anywhere in the project tree. Let's further assume that you have
+marked all tree headings that define a project with the todo keyword
+PROJECT. In this case you would run a todo search for the keyword
+PROJECT, but skip the match unless there is a WAITING tag anywhere in
+the subtree belonging to the project line.
+
+To achieve this, you must write a function that searches the subtree for
+the tag. If the tag is found, the function must return @code{nil} to
+indicate that this match should not be skipped. If there is no such
+tag, return the location of the end of the subtree, to indicate that
+search should continue from there.
+
+@lisp
+(defun my-skip-unless-waiting ()
+ "Skip trees that are not waiting"
+ (let ((subtree-end (save-excursion (org-end-of-subtree t))))
+ (if (re-search-forward ":WAITING:" subtree-end t)
+ nil ; tag found, do not skip
+ subtree-end))) ; tag not found, continue after end of subtree
+@end lisp
+
+Now you may use this function in an agenda custom command, for example
+like this:
+
+@lisp
+(org-add-agenda-custom-command
+ '("b" todo "PROJECT"
+ ((org-agenda-skip-function 'my-org-waiting-projects)
+ (org-agenda-overriding-header "Projects waiting for something: "))))
+@end lisp
+
+Note that this also binds @code{org-agenda-overriding-header} to get a
+meaningful header in the agenda view.
+
+You may also put a Lisp form into @code{org-agenda-skip-function}. In
+particular, you may use the functions @code{org-agenda-skip-entry-if}
+and @code{org-agenda-skip-subtree-if} in this form, for example:
+
+@table @code
+@item '(org-agenda-skip-entry-if 'scheduled)
+Skip current entry if it has been scheduled.
+@item '(org-agenda-skip-entry-if 'notscheduled)
+Skip current entry if it has not been scheduled.
+@item '(org-agenda-skip-entry-if 'deadline)
+Skip current entry if it has a deadline.
+@item '(org-agenda-skip-entry-if 'scheduled 'deadline)
+Skip current entry if it has a deadline, or if it is scheduled.
+@item '(org-agenda-skip-entry 'regexp "regular expression")
+Skip current entry if the regular expression contained in the variable
+@code{org-agenda-skip-regexp} matches in the entry.
+@item '(org-agenda-skip-subtree-if 'regexp "regular expression")
+Same as above, but check and skip the entire subtree.
+@end table
+
+Therefore we could also have written the search for WAITING projects
+like this, even without defining a special function:
+
+@lisp
+(org-add-agenda-custom-command
+ '("b" todo "PROJECT"
+ ((org-agenda-skip-function '(org-agenda-skip-subtree-if
+ 'regexp ":WAITING:"))
+ (org-agenda-overriding-header "Projects waiting for something: "))))
+@end lisp
+
+
+@node Using the property API, , Special agenda views, Extensions and Hacking
+@section Using the property API
+@cindex API, for properties
+@cindex properties, API
+
+Here is a description of the functions that can be used to work with
+properties.
+
+@defun org-entry-properties &optional pom which
+Get all properties of the entry at point-or-marker POM.
+This includes the TODO keyword, the tags, time strings for deadline,
+scheduled, and clocking, and any additional properties defined in the
+entry. The return value is an alist, keys may occur multiple times
+if the property key was used several times.
+POM may also be nil, in which case the current entry is used.
+If WHICH is nil or `all', get all properties. If WHICH is
+`special' or `standard', only get that subclass.
+@end defun
+@defun org-entry-get pom property &optional inherit
+Get value of PROPERTY for entry at point-or-marker POM.
+If INHERIT is non-nil and the entry does not have the property,
+then also check higher levels of the hierarchy.
+@end defun
+
+@defun org-entry-delete pom property
+Delete the property PROPERTY from entry at point-or-marker POM.
+@end defun
+
+@defun org-entry-put pom property value
+Set PROPERTY to VALUE for entry at point-or-marker POM.
+@end defun
+
+@defun org-buffer-property-keys &optional include-specials
+Get all property keys in the current buffer.
+@end defun
+
+@defun org-insert-property-drawer
+Insert a property drawer at point.
+@end defun
+
+@node History and Acknowledgments, Index, Extensions and Hacking, Top
+@appendix History and Acknowledgments
+@cindex acknowledgments
+@cindex history
+@cindex thanks
+
+Org-mode was borne in 2003, out of frustration over the user interface
+of the Emacs outline-mode. I was trying to organize my notes and
+projects, and using Emacs seemed to be the natural way to go. However,
+having to remember eleven different commands with two or three keys per
+command, only to hide and unhide parts of the outline tree, that seemed
+entirely unacceptable to me. Also, when using outlines to take notes, I
+constantly want to restructure the tree, organizing it parallel to my
+thoughts and plans. @emph{Visibility cycling} and @emph{structure
+editing} were originally implemented in the package
+@file{outline-magic.el}, but quickly moved to the more general
+@file{org.el}. As this environment became comfortable for project
+planning, the next step was adding @emph{TODO entries}, basic @emph{time
+stamps}, and @emph{table support}. These areas highlight the two main
+goals that Org-mode still has today: To create a new, outline-based,
+plain text mode with innovative and intuitive editing features, and to
+incorporate project planning functionality directly into a notes file.
+
+Since the first release, literally thousands of emails to me or on
+@code{emacs-orgmode@@gnu.org} have provided a constant stream of bug
+reports, feedback, new ideas, and sometimes patches and add-on code.
+Many thanks to everyone who has helped to improve this package. I am
+trying to keep here a list of the people who had significant influence
+in shaping one or more aspects of Org-mode. The list may not be
+complete, if I have forgotten someone, please accept my apologies and
+let me know.
+
+@itemize @bullet
+
+@item
+@i{Russel Adams} came up with the idea for drawers.
+@item
+@i{Thomas Baumann} contributed the code for links to the MH-E email
+system.
+@item
+@i{Alex Bochannek} provided a patch for rounding time stamps.
+@item
+@i{Charles Cave}'s suggestion sparked the implementation of templates
+for Remember.
+@item
+@i{Pavel Chalmoviansky} influenced the agenda treatment of items with
+specified time.
+@item
+@i{Gregory Chernov} patched support for lisp forms into table
+calculations and improved XEmacs compatibility, in particular by porting
+@file{nouline.el} to XEmacs.
+@item
+@i{Sacha Chua} suggested to copy some linking code from Planner.
+@item
+@i{Eddward DeVilla} proposed and tested checkbox statistics. He also
+came up with the idea of properties, and that there should be an API for
+them.
+@item
+@i{Kees Dullemond} used to edit projects lists directly in HTML and so
+inspired some of the early development, including HTML export. He also
+asked for a way to narrow wide table columns.
+@item
+@i{Christian Egli} converted the documentation into TeXInfo format,
+patched CSS formatting into the HTML exporter, and inspired the agenda.
+@item
+@i{David Emery} provided a patch for custom CSS support in exported
+HTML agendas.
+@item
+@i{Nic Ferrier} contributed mailcap and XOXO support.
+@item
+@i{John Foerch} figured out how to make incremental search show context
+around a match in a hidden outline tree.
+@item
+@i{Niels Giessen} had the idea to automatically archive DONE trees.
+@item
+@i{Bastien Guerry} wrote the La@TeX{} exporter and has been prolific
+with patches, ideas, and bug reports.
+to Org-mode.
+@item
+@i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
+@item
+@i{Scott Jaderholm} proposed footnotes, control over whitespace between
+folded entries, and column view for properties.
+@item
+@i{Shidai Liu} ("Leo") asked for embedded La@TeX{} and tested it. He also
+provided frequent feedback and some patches.
+@item
+@i{Jason F. McBrayer} suggested agenda export to CSV format.
+@item
+@i{Dmitri Minaev} sent a patch to set priority limits on a per-file
+basis.
+@item
+@i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
+happy.
+@item
+@i{Rick Moynihan} proposed to allow multiple TODO sequences in a file.
+@item
+@i{Todd Neal} provided patches for links to Info files and elisp forms.
+@item
+@i{Tim O'Callaghan} suggested in-file links, search options for general
+file links, and TAGS.
+@item
+@i{Takeshi Okano} translated the manual and David O'Toole's tutorial
+into Japanese.
+@item
+@i{Oliver Oppitz} suggested multi-state TODO items.
+@item
+@i{Scott Otterson} sparked the introduction of descriptive text for
+links, among other things.
+@item
+@i{Pete Phillips} helped during the development of the TAGS feature, and
+provided frequent feedback.
+@item
+@i{T.V. Raman} reported bugs and suggested improvements.
+@item
+@i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
+control.
+@item
+@i{Kevin Rogers} contributed code to access VM files on remote hosts.
+@item
+@i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
+conflict with @file{allout.el}.
+@item
+@i{Jason Riedy} sent a patch to fix a bug with export of TODO keywords.
+@item
+@i{Philip Rooke} created the Org-mode reference card and provided lots
+of feedback.
+@item
+@i{Christian Schlauer} proposed angular brackets around links, among
+other things.
+@item
+Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s
+@file{organizer-mode.el}.
+@item
+@i{Daniel Sinder} came up with the idea of internal archiving by locking
+subtrees.
+@item
+@i{Dale Smith} proposed link abbreviations.
+@item
+@i{Adam Spiers} asked for global linking commands and inspired the link
+extension system. support mairix.
+@item
+@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
+chapter about publishing.
+@item
+@i{J@"urgen Vollmer} contributed code generating the table of contents
+in HTML output.
+@item
+@i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
+keyword.
+@item
+@i{David Wainberg} suggested archiving, and improvements to the linking
+system.
+@item
+@i{John Wiegley} wrote @file{emacs-wiki.el} and @file{planner.el}. The
+development of Org-mode was fully independent, and both systems are
+really different beasts in their basic ideas and implementation details.
+I later looked at John's code, however, and learned from his
+implementation of (i) links where the link itself is hidden and only a
+description is shown, and (ii) popping up a calendar to select a date.
+John has also contributed a number of great ideas directly to Org-mode.
+@item
+@i{Carsten Wimmer} suggested some changes and helped fix a bug in
+linking to GNUS.
+@item
+@i{Roland Winkler} requested additional keybindings to make Org-mode
+work on a tty.
+@item
+@i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
+and contributed various ideas and code snippets.
+@end itemize
+
+
+@node Index, Key Index, History and Acknowledgments, Top
+@unnumbered Index
+
+@printindex cp
+
+@node Key Index, , Index, Top
+@unnumbered Key Index
+
+@printindex ky
+
+@bye
+
+@ignore
+ arch-tag: 7893d1fe-cc57-4d13-b5e5-f494a1bcc7ac
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename ../info/pcl-cvs
+@settitle PCL-CVS --- Emacs Front-End to CVS
+@syncodeindex vr fn
+@c %**end of header
+
+@copying
+Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
+1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software
+Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
+``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* PCL-CVS: (pcl-cvs). Emacs front-end to CVS.
+@end direntry
+
+@c The titlepage section does not appear in the Info file.
+@titlepage
+@sp 4
+@c The title is printed in a large font.
+@center @titlefont{User's Guide}
+@sp
+@center @titlefont{to}
+@sp
+@center @titlefont{PCL-CVS --- The Emacs Front-End to CVS}
+@ignore
+@sp 2
+@center release 2.9
+@c -release-
+@end ignore
+@sp 3
+@center Per Cederqvist
+@center Stefan Monnier
+@c -date-
+
+@c The following two commands start the copyright page
+@c for the printed manual. This will not appear in the Info file.
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@c ================================================================
+@c The real text starts here
+@c ================================================================
+
+@node Top, About PCL-CVS, (dir), (dir)
+@ifnottex
+@top PCL-CVS
+
+This manual describes PCL-CVS, the GNU Emacs front-end to CVS. It
+is nowhere near complete, so you are advised to use @kbd{M-x
+customize-group RET pcl-cvs @key{RET}} and to look at the documentation strings
+of the various commands and major modes for further information.
+@c This manual is updated to release 2.5 of PCL-CVS.
+@end ifnottex
+
+@menu
+* About PCL-CVS:: Credits, history, @dots{}
+
+* Getting started:: An introduction with a walk-through example.
+* Buffer contents:: An explanation of the buffer contents.
+* Selected files:: To which files are commands applied.
+* Commands:: All commands, grouped by type.
+
+* Log Edit Mode:: Major mode to edit log messages.
+* Log View Mode:: Major mode to browse log changes.
+@c * CVS Status Mode:: Major mode to view CVS' status output.
+* Customization:: How you can tailor PCL-CVS to suit your needs.
+* Bugs:: Bugs (known and unknown).
+
+* GNU Free Documentation License:: The license for this documentation.
+* Function and Variable Index:: List of functions and variables.
+* Concept Index:: List of concepts.
+* Key Index:: List of keystrokes.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+About PCL-CVS
+
+* Contributors:: Contributors to PCL-CVS.
+
+Commands
+
+* Entering PCL-CVS:: Commands to invoke PCL-CVS
+* Setting flags:: Setting flags for CVS commands
+* Updating the buffer::
+* Movement commands:: How to move up and down in the buffer
+* Marking files:: How to mark files that other commands
+ will later operate on.
+* Committing changes:: Checking in your modifications to the
+ CVS repository.
+* Editing files:: Loading files into Emacs.
+* Getting info about files:: Display the log and status of files.
+* Adding and removing files:: Adding and removing files
+* Undoing changes:: Undoing changes
+* Removing handled entries:: Uninteresting lines can easily be removed.
+* Ignoring files:: Telling CVS to ignore generated files.
+* Viewing differences:: Commands to @samp{diff} different versions.
+* Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer.
+* Updating files:: Updating files that Need-update.
+* Tagging files:: Tagging files.
+* Miscellaneous commands:: Miscellaneous commands.
+
+Customization
+
+* Customizing Faces::
+
+@end detailmenu
+@end menu
+
+@node About PCL-CVS, Getting started, Top, Top
+@chapter About PCL-CVS
+@cindex About PCL-CVS
+
+PCL-CVS is a front-end to CVS versions 1.9 and later.
+It concisely shows the present status of a checked out module in an
+Emacs buffer and provides single-key access to the most frequently used CVS
+commands.
+For Emacs users accustomed to VC, PCL-CVS can be thought of as a replacement
+for VC-dired (@pxref{VC Dired Mode, , Dired under VC, emacs, The GNU
+Emacs Manual}) specifically designed for CVS.
+
+PCL-CVS was originally written many years ago by Per Cederqvist who
+proudly maintained it until January 1996, at which point he released the
+beta version 2.0b2 and passed on the maintainership to Greg A Woods.
+Development stayed mostly dormant for a few years during which
+version 2.0 never seemed to be able to leave the ``beta'' stage while a
+separate XEmacs version was slowly splitting away. In late 1998,
+Stefan Monnier picked up development again, adding some major new
+functionality and taking over the maintenance.
+
+@menu
+* Contributors:: Contributors to PCL-CVS.
+@end menu
+
+@node Contributors,, About PCL-CVS, About PCL-CVS
+@section Contributors to PCL-CVS
+@cindex Contributors
+@cindex Authors
+
+Contributions to the package are welcome. I have limited time to work
+on this project, but I will gladly add any code that you contribute to
+me to this package (@pxref{Bugs}).
+
+The following persons have made contributions to PCL-CVS.
+
+@itemize @bullet
+@item
+Brian Berliner wrote CVS, together with some other contributors.
+Without his work on CVS this package would be useless@dots{}
+
+@item
+Per Cederqvist wrote most of the otherwise unattributed functions in
+PCL-CVS as well as all the documentation.
+
+@item
+@email{inge@@lysator.liu.se, Inge Wallin} wrote the skeleton of
+@file{pcl-cvs.texi}, and gave useful comments on it. He also wrote
+the files @file{elib-node.el} and @file{compile-all.el}. The file
+@file{cookie.el} was inspired by Inge.@refill
+
+@item
+@email{linus@@lysator.liu.se, Linus Tolke} contributed useful comments
+on both the functionality and the documentation.@refill
+
+@item
+@email{jwz@@jwz.com, Jamie Zawinski} contributed
+@file{pcl-cvs-lucid.el}, which was later renamed to
+@file{pcl-cvs-xemacs.el}.@refill
+
+@item
+Leif Lonnblad contributed RCVS support (since superseded by the new
+remote CVS support).
+
+@item
+@email{jimb@@cyclic.com, Jim Blandy} contributed hooks to automatically
+guess CVS log entries from @file{ChangeLog} contents, and initial support of
+the new Cygnus / Cyclic remote CVS, as well as various sundry bug fixes
+and cleanups.
+
+@item
+@email{kingdon@@cyclic.com, Jim Kingdon} contributed lots of fixes to
+the build and installation procedure.
+
+@item
+@email{woods@@weird.com, Greg A.@: Woods} contributed code to implement
+the use of per-file diff buffers, and vendor join diffs with emerge and
+ediff, as well as various and sundry bug fixes and cleanups.
+
+@item
+@email{greg.klanderman@@alum.mit.edu, Greg Klanderman} implemented
+toggling of marked files, setting of CVS command flags via prefix
+arguments, updated the XEmacs support, updated the manual, and fixed
+numerous bugs.
+
+@item
+@email{monnier@@cs.yale.edu, Stefan Monnier} added a slew of other
+features and introduced even more new bugs. If there's any bug left,
+you can be sure it's his.
+
+@item
+@c wordy to avoid an underfull hbox
+@email{masata-y@@is.aist-nara.ac.jp, Masatake YAMATO} made a gracious
+contribution of his cvstree code to display a tree of tags which was later
+superseded by the new @code{cvs-status-mode}.
+@end itemize
+
+Apart from these, a lot of people have sent us suggestions, ideas,
+requests, bug reports and encouragement. Thanks a lot! Without you
+there would be no new releases of PCL-CVS.
+
+
+@node Getting started, Buffer contents, About PCL-CVS, Top
+@chapter Getting started
+@cindex Introduction
+@cindex Example run
+@cindex Sample session
+
+This document assumes that you know what CVS is, and that you at least
+know the fundamental concepts of CVS. If that is not the case, you
+should read the CVS documentation. Type @kbd{info -f cvs} or @kbd{man
+cvs}.
+
+PCL-CVS is only useful once you have checked out a module. So before
+you invoke it, you must have a copy of a module somewhere in the file
+system.
+
+You can invoke PCL-CVS by typing @kbd{M-x cvs-examine @key{RET}}.
+You can also invoke it via the menu bar, under @samp{Tools}.
+Or, if you prefer, you can also invoke PCL-CVS by simply visiting the
+CVS administrative subdirectory of your module, with a prefix argument.
+For example, to invoke PCL-CVS in a separate frame, type @kbd{C-u C-x 5
+f ~/my/project/CVS @key{RET}}.
+
+The function @code{cvs-examine} will ask for a directory. The command
+@samp{cvs -n update} will be run in that directory. (It should contain
+files that have been checked out from a CVS archive.) The output from
+@code{cvs} will be parsed and presented in a table in a buffer called
+@samp{*cvs*}. It might look something like this:
+
+@example
+Repository : /usr/CVSroot
+Module : test
+Working dir: /users/ceder/FOO/test
+
+
+In directory .:
+ Need-Update bar
+ Need-Update file.txt
+ Modified namechange
+ Need-Update newer
+In directory sub:
+ Modified ChangeLog
+
+--------------------- End ---------------------
+-- last cmd: cvs -f -z6 -n update -d -P --
+@end example
+
+In this example, your repository is in @file{/usr/CVSroot} and CVS has
+been run in the directory @file{/users/ceder/FOO/test}. The three files
+(@file{bar}, @file{file.txt} and
+@file{newer}) that are marked with @samp{Need-Update} have been changed
+by someone else in the CVS repository. Two files (@file{namechange}
+and @file{sub/ChangeLog}) have been modified locally, and need to be
+checked in.
+
+You can move the cursor up and down in the buffer with @kbd{C-n} and
+@kbd{C-p} or @kbd{n} and @kbd{p}. If you press @kbd{c} on one of the
+@samp{Modified} files, that file will be checked in to the CVS
+repository. @xref{Committing changes}. You can also press @kbd{O} to
+update any of the files that are marked @samp{Need-Update}. You can
+also run @kbd{M-x cvs-update @key{RET}} (bound to @kbd{M-u} in the
+@samp{*cvs*} buffer) to update all the files.@refill
+
+You can then press @kbd{=} to easily get a @samp{diff} between your
+modified file and the base version that you started from, or you can
+press @kbd{l} to get the output from @samp{cvs log}. Many more such
+commands are available simply by pressing a key (@pxref{Getting info
+about files}).
+
+@node Buffer contents, Selected files, Getting started, Top
+@chapter Buffer contents
+@cindex Buffer contents
+@cindex @code{*cvs*} buffer contents
+
+The display contains several columns, some of which are optional.
+These columns are, from left to right:
+
+@itemize @bullet
+
+@item
+Optionally, the head revision of the file. This is the latest version
+found in the repository. It might also contain (instead of the head
+revision) a sub status which typically gives further information about
+how we got to the current state, for example @samp{patched},
+@samp{merged}, @dots{}
+
+@item
+An asterisk when the file is @dfn{marked} (@pxref{Selected
+files}).@refill
+
+@item
+The actual status of the file wrt the repository. See below.
+
+@item
+Optionally, the base revision of the file. This is the version
+which the copy in your working directory is based upon.
+
+@item
+The file name.
+
+@end itemize
+
+The @samp{file status} field can have the following values:
+
+@table @samp
+@item Modified
+The file is modified in your working directory, and there was no
+modification to the same file in the repository. This status can have
+the following substatus:
+
+@table @samp
+@item merged
+The file was modified in your working directory, and there were
+modifications in the repository as well, but they were merged
+successfully, without conflict, in your working directory.@refill
+@end table
+
+@item Conflict
+A conflict was detected while trying to merge your changes to @var{file}
+with changes from the repository. @var{file} (the copy in your
+working directory) is now the output of the @code{rcsmerge} command on
+the two versions; an unmodified copy of your file is also in your
+working directory, with the name @file{.#@var{file}.@var{version}},
+where @var{version} is the RCS revision that your modified file started
+from. @xref{Viewing differences}, for more details.@refill
+
+A conflict can also come from a disagreement on the existence of the file
+rather than on its content. This case is indicated by the following
+possible substatus:
+
+@table @samp
+@item removed
+The file is locally removed but a new revision has been committed to
+the repository by someone else.
+
+@item added
+The file is locally added and has also been added to the repository
+by someone else.
+
+@item modified
+The file is locally modified but someone else has removed it from the
+repository.
+@end table
+
+@item Added
+The file has been added by you, but it still needs to be checked in to
+the repository.@refill
+
+@item Removed
+The file has been removed by you, but it still needs to be checked in to
+the repository. You can resurrect it by typing @kbd{a} (@pxref{Adding
+and removing files}).@refill
+
+@item Unknown
+A file that was detected in your directory, but that neither appears in
+the repository, nor is present on the list of files that CVS should
+ignore.@refill
+
+@item Up-to-date
+The file is up to date with respect to the version in the repository.
+This status can have a substatus of:
+
+@table @samp
+@item added
+You have just added the file to the repository.@refill
+
+@item updated
+The file was brought up to date with respect to the repository. This is
+done for any file that exists in the repository but not in your source,
+and for files that you haven't changed but are not the most recent
+versions available in the repository.@refill
+
+@item patched
+The file was brought up to date with respect to the remote repository by
+way of fetching and applying a patch to the file in your source. This
+is equivalent to @samp{updated} except that CVS decided to use a hopefully
+more efficient method.@refill
+
+@item committed
+You just committed the file.@refill
+@end table
+
+@item Need-Update
+Either a newer version than the one in your source is available in the
+repository and you have not modified your checked out version, or the
+file exists in the repository but not in your source. Use
+@samp{cvs-mode-update} bound to @kbd{O} to update the file.@refill
+
+@item Need-Merge
+You have modified the checked out version of the file, and a newer
+version is available in the repository. A merge will take place when
+you run a @samp{cvs-update}.
+
+@item Missing
+The file has been unexpectedly removed from your working directory
+although it has not been @samp{cvs remove}d.
+@end table
+
+@node Selected files, Commands, Buffer contents, Top
+@chapter Selected files
+@cindex Selected files
+@cindex Marked files
+@cindex File selection
+@cindex Active files
+@cindex Applicable
+
+Many of the commands work on the current set of @dfn{selected} files
+which can be either the set of marked files (if any file is marked and
+marks are not ignored) or whichever file or directory the cursor is on.
+
+If a directory is selected but the command cannot be applied to a
+directory, then it will be applied to the set of files under this
+directory which are in the @samp{*cvs*} buffer.
+
+@findex cvs-mode-force-command
+@findex cvs-allow-dir-commit
+Furthermore, each command only operates on a subset of the selected
+files, depending on whether or not the command is @dfn{applicable} to
+each file (based on the file's status). For example,
+@code{cvs-mode-commit} is not applicable to a file whose status is
+@samp{Need-Update}. If it should happen that PCL-CVS guesses the
+applicability wrong, you can override it with the special prefix
+@code{cvs-mode-force-command} normally bound to @kbd{M-f} (and file a
+bug report). The applicability rule can be slightly changed with
+@code{cvs-allow-dir-commit} and @code{cvs-force-dir-tag}.
+
+By default, marks are always in effect (you may change this, however, by
+setting the variable @code{cvs-default-ignore-marks}) except for the
+commands that @samp{tag} or @samp{diff} a file (which can be changed
+with the variable @code{cvs-invert-ignore-marks}).
+
+In addition, you may use the special prefix @code{cvs-mode-toggle-marks}
+normally bound to @key{T} to toggle the use of marks for the following
+command.
+
+This scheme might seem a little complicated, but once one gets used to
+it, it is quite powerful.
+
+For commands to mark and unmark files, see @ref{Marking files}.
+
+@node Commands, Log Edit Mode, Selected files, Top
+@chapter Commands
+
+@iftex
+This chapter describes all the commands that you can use in PCL-CVS.
+@end iftex
+@ifnottex
+The nodes in this menu contains explanations about all the commands that
+you can use in PCL-CVS. They are grouped together by type.
+@end ifnottex
+
+@menu
+* Entering PCL-CVS:: Commands to invoke PCL-CVS
+* Setting flags:: Setting flags for CVS commands
+* Updating the buffer::
+* Movement commands:: How to move up and down in the buffer
+* Marking files:: How to mark files that other commands
+ will later operate on.
+* Committing changes:: Checking in your modifications to the
+ CVS repository.
+* Editing files:: Loading files into Emacs.
+* Getting info about files:: Display the log and status of files.
+* Adding and removing files:: Adding and removing files
+* Undoing changes:: Undoing changes
+* Removing handled entries:: Uninteresting lines can easily be removed.
+* Ignoring files:: Telling CVS to ignore generated files.
+* Viewing differences:: Commands to @samp{diff} different versions.
+* Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer.
+* Updating files:: Updating files that Need-update.
+* Tagging files:: Tagging files.
+* Miscellaneous commands:: Miscellaneous commands.
+@end menu
+
+
+@node Entering PCL-CVS, Setting flags, Commands, Commands
+@section Entering PCL-CVS
+@findex cvs-update
+@findex cvs-examine
+@findex cvs-status
+@findex cvs-checkout
+@findex cvs-quickdir
+@cindex Creating the *cvs* buffer
+
+Most commands in PCL-CVS require that you have a @samp{*cvs*}
+buffer. The commands that you use to get one are listed below.
+For each, a @samp{cvs} process will be run, the output will be parsed by
+PCL-CVS, and the result will be printed in the @samp{*cvs*} buffer (see
+@ref{Buffer contents}, for a description of the buffer's contents).
+
+@table @kbd
+@item M-x cvs-update
+Run a @samp{cvs update} command. You will be asked for the directory
+in which the @samp{cvs update} will be run.
+
+@item M-x cvs-examine
+Run a @samp{cvs -n update} command. This is identical to the previous
+command, except that it will only check what needs to be done but will
+not change anything. You will be asked for the directory in
+which the @samp{cvs -n update} will be run.
+
+@item M-x cvs-status
+Run a @samp{cvs status} command. You will be asked for the directory
+in which the @samp{cvs status} will be run.
+
+@item M-x cvs-checkout
+Run a @samp{cvs checkout} command. You will be asked for the directory
+in which the @samp{cvs update} will be run and the module to be checked
+out.
+
+@item M-x cvs-quickdir
+Populate the @samp{*cvs*} buffer by just looking at the @file{CVS/Entries}
+files. This is very much like @code{cvs-examine} except that it does
+not access the CVS repository, which is a major advantage when the
+repository is far away. But of course, it will not be able to detect
+when a file needs to be updated or merged.
+@end table
+
+@findex cvs-dired-action
+@findex cvs-dired-use-hook
+The first four of
+those commands are also reachable from the menu bar
+under @samp{Tools->PCL-CVS}. Finally, an alternative way is to visit
+the CVS administrative subdirectory in your work area with a simple
+prefix argument. For example @kbd{C-u C-x C-f ~/my/work/CVS @key{RET}}. This
+by default runs @code{cvs-quickdir} but the specific behavior can be
+changed with @code{cvs-dired-action} and @code{cvs-dired-use-hook}.
+
+By default, the commands above will descend recursively into
+subdirectories. You can avoid that behavior by including @samp{-l} in
+the flags for the command. These flags can be set by giving a prefix
+argument to the command (e.g., by typing
+@kbd{C-u M-x cvs-update @key{RET} -l @key{RET}}).
+
+
+@node Setting flags, Updating the buffer, Entering PCL-CVS, Commands
+@section Setting flags for CVS commands
+@cindex Optional switches to CVS
+@cindex Command-line options to CVS
+
+This section describes the convention used by nearly all PCL-CVS
+commands for setting optional flags sent to CVS. A single @kbd{C-u}
+prefix argument is used to cause the command to prompt for flags to be
+used for the current invocation of the command only. Two @kbd{C-u} prefix
+arguments are used to prompt for flags which will be set permanently, for the
+current invocation and all that follow, until the flags are changed, or
+unless temporary flags are set which override them.
+
+Perhaps an example or two is in order. Say you are about to add a
+binary file to the repository, and want to specify the flags @samp{-kb}
+to @samp{cvs add}. You can type @kbd{C-u a -kb @key{RET}},
+and the file will be added. Subsequent @samp{cvs add}
+commands will use the previously prevailing flags.
+
+As a second example, say you are about to perform a diff and want to see
+the result in unified diff format, i.e. you'd like to pass the flag
+@samp{-u} to both @samp{cvs diff} and @samp{diff}. You'd also like all
+subsequent diffs to use this flag. You can type @kbd{C-u C-u = -u @key{RET}}
+and the diff will be performed, and the default flags will be set to
+@code{("-u")}. You can of course override this flag for a single diff
+by using a single @kbd{C-u} prefix argument.
+
+@cindex Special prefix
+In addition to this, some commands can take @dfn{special prefix} arguments.
+These work as follows: When called with a @kbd{C-u} prefix, the user is
+prompted for a new value of the special prefix and the special prefix is
+activated for the next command. When called without the @kbd{C-u}
+prefix, the special prefix is re-activated (with the same value as last
+time) for the next command. Calling the prefix command again when it's
+already activated deactivates it. Calling it with the @kbd{C-u C-u}
+prefix activates it for all subsequent commands until you deactivate it
+explicitly. The special prefixes are:
+
+@table @kbd
+@item T
+Toggles whether or not marks will be active in the next command.@refill
+
+@item b
+Provide the next command with a branch (can be any version
+specifier) to work on.@refill
+
+@item B
+Secondary branch argument. Only meaningful if @kbd{b} is also used.
+It can be used to provide a second branch argument to
+@code{cvs-mode-diff} or to @code{cvs-mode-update}.
+
+@item M-f
+Forces the next command to apply to every selected file rather than only
+to the ones PCL-CVS thinks are relevant.
+@end table
+
+@node Updating the buffer, Movement commands, Setting flags, Commands
+@section Updating the @samp{*cvs*} buffer
+@findex cvs-update
+@findex cvs-examine
+@findex cvs-status
+@findex cvs-mode-update
+@findex cvs-mode-examine
+@findex cvs-mode-status
+
+The following commands can be used from within the @samp{*cvs*} buffer
+to update the display:
+
+@table @kbd
+@item M-u
+Runs the command @samp{cvs-update}.@refill
+
+@item M-e
+Runs the command @samp{cvs-examine}.@refill
+
+@item M-s
+Runs the command @samp{cvs-status}.@refill
+@end table
+
+In addition to the above commands which operate on the whole module,
+you can run the equivalent CVS command on just a subset of the
+files/directories with these keys:
+
+@table @kbd
+@item O
+Runs @code{cvs-mode-update} on the selected files. When run on the
+top-level directory, this is equivalent to @kbd{M-u}.@refill
+
+@item e
+Runs @code{cvs-mode-examine} on the selected files. When run on the
+top-level directory, this is equivalent to @kbd{M-e}.@refill
+
+@findex cvs-status-mode
+@item s
+Runs @code{cvs-mode-status} on the selected files. When run on the
+top-level directory, this is equivalent to @kbd{M-s}, except that
+CVS output will be shown in a @samp{*cvs-info*} buffer that will be
+put in @samp{cvs-status-mode}.@refill
+@end table
+
+
+@node Movement commands, Marking files, Updating the buffer, Commands
+@section Movement Commands
+@cindex Movement Commands
+@findex cvs-mode-next-line
+@findex cvs-mode-previous-line
+@kindex SPC@r{--Move down one file}
+@kindex n@r{--Move down one file}
+@kindex p@r{--Move up one file}
+
+You can use most normal Emacs commands to move forward and backward in
+the buffer. Some keys are rebound to functions that take advantage of
+the fact that the buffer is a PCL-CVS buffer:
+
+
+@table @kbd
+@item @key{SPC}
+@itemx n
+These keys move the cursor one file forward, towards the end of the
+buffer (@code{cvs-mode-next-line}).@refill
+
+@itemx p
+This key moves one file backward, towards the beginning of the buffer
+(@code{cvs-mode-previous-line}).
+@end table
+
+
+@node Marking files, Committing changes, Movement commands, Commands
+@section Marking files
+@cindex Selecting files (commands to mark files)
+@cindex Marking files
+@kindex m@r{--marking a file}
+@kindex M@r{--marking all files}
+@kindex u@r{--unmark a file}
+@kindex ESC DEL@r{--unmark all files}
+@kindex DEL@r{--unmark previous file}
+@kindex %@r{--mark files matching regexp}
+@kindex S@r{--mark files in a particular state}
+@kindex T@r{--toggle marks}
+@findex cvs-mode-mark
+@findex cvs-mode-unmark
+@findex cvs-mode-mark-all-files
+@findex cvs-mode-unmark-all-files
+@findex cvs-mode-unmark-up
+@findex cvs-mode-mark-matching-files
+@findex cvs-mode-mark-on-state
+@findex cvs-mode-toggle-marks
+
+PCL-CVS works on a set of @dfn{selected files} (@pxref{Selected files}).
+You can mark and unmark files with these commands:
+
+@table @kbd
+@item m
+This marks the file that the cursor is positioned on. If the cursor is
+positioned on a directory all files in that directory are marked
+(@code{cvs-mode-mark}).@refill
+
+@item u
+Unmark the file that the cursor is positioned on. If the cursor is on a
+directory, all files in that directory are unmarked
+(@code{cvs-mode-unmark}).@refill
+
+@item M
+Mark @emph{all} files in the buffer (@code{cvs-mode-mark-all-files}).
+
+@item M-@key{DEL}
+Unmark @emph{all} files (@code{cvs-mode-unmark-all-files}).
+
+@item @key{DEL}
+Unmark the file on the previous line, and move point to that line
+(@code{cvs-mode-unmark-up}).
+
+@item %
+Mark all files matching a regular expression
+(@code{cvs-mode-mark-matching-files}).
+
+@item S
+Mark all files in a particular state, such as ``Modified'' or
+``Removed'' (@code{cvs-mode-mark-on-state}).
+
+@item T
+Toggle use of marks for the next command (@code{cvs-mode-toggle-marks}).
+@end table
+
+
+@node Committing changes, Editing files, Marking files, Commands
+@section Committing changes
+@cindex Committing changes
+@findex cvs-mode-commit
+@findex cvs-mode-commit-setup
+@kindex c@r{--commit files}
+@kindex C@r{--commit files with @file{ChangeLog} message}
+@vindex cvs-auto-revert@r{ (variable)}
+@cindex Commit buffer
+@cindex Edit buffer
+@cindex Erasing commit message
+@cindex Reverting buffers after commit
+
+Committing changes basically works as follows:
+
+@enumerate
+@item
+After having selected the files you want to commit, you type either
+@kbd{c} or @kbd{C} which brings up a special buffer
+@samp{*cvs-commit*}.@refill
+
+@item
+You type in the log message describing the changes you're about to
+commit (@pxref{Log Edit Mode}).
+
+@item
+When you're happy with it, you type @kbd{C-c C-c} to do the actual
+commit.@refill
+@end enumerate
+
+There's no hidden state, so you can abort the process or pick it up
+again at any time.
+
+@vindex log-edit-confirm@r{ (variable)}
+The set of files actually committed is really decided only during the
+very last step, which is a mixed blessing. It allows you to go back and
+change your mind about which files to commit, but it also means that you
+might inadvertently change the set of selected files. To reduce the
+risk of error, @kbd{C-c C-c} will ask for confirmation if the set of
+selected files has changed between the first step and the last. You can
+change this last detail with @code{log-edit-confirm}.
+
+As for the difference between @kbd{c} (i.e. @code{cvs-mode-commit}) and
+@kbd{C} (i.e. @code{cvs-mode-commit-setup}) is that the first gets you
+straight to @samp{*cvs-commit*} without erasing it or changing anything
+to its content, while the second first erases @samp{*cvs-commit*}
+and tries to initialize it with a sane default (it does that by either
+using a template provided by the CVS administrator or by extracting a
+relevant log message from a @file{ChangeLog} file).
+
+If you are editing the files in your Emacs, an automatic
+@samp{revert-buffer} will be performed. (If the file contains
+@samp{$@asis{Id}$} keywords, @samp{cvs commit} will write a new file with
+the new values substituted. The auto-revert makes sure that you get
+them into your buffer.) The revert will not occur if you have modified
+your buffer, or if @samp{cvs-auto-revert} is set to
+@samp{nil}.
+
+
+@node Editing files, Getting info about files, Committing changes, Commands
+@section Editing files
+@cindex Editing files
+@cindex Finding files
+@cindex Loading files
+@cindex Dired
+@cindex Invoking dired
+@findex cvs-mode-find-file
+@findex cvs-mode-find-file-other-window
+@findex cvs-mode-add-change-log-entry-other-window
+@kindex f@r{--find file or directory}
+@kindex o@r{--find file in other window}
+@kindex A@r{--add @file{ChangeLog} entry}
+
+There are currently three commands that can be used to find a file (that
+is, load it into a buffer and start editing it there). These commands
+work on the line that the cursor is situated at. They always ignore any marked
+files.
+
+@table @kbd
+@item f
+Find the file that the cursor points to (@code{cvs-mode-find-file}). If
+the cursor points to a directory, run @code{dired} on that directory;
+@inforef{Dired, , emacs}.
+
+@item o
+Like @kbd{f}, but use another window
+(@code{cvs-mode-find-file-other-window}).@refill
+
+@item A
+Invoke @samp{add-change-log-entry-other-window} to edit a
+@file{ChangeLog} file. The @file{ChangeLog} file will be found in the
+directory of the file the cursor points to, or in a parent of that
+directory (@code{cvs-mode-add-change-log-entry-other-window}).@refill
+@end table
+
+
+@node Getting info about files, Adding and removing files, Editing files, Commands
+@section Getting info about files
+@cindex Status (cvs command)
+@cindex Log (RCS/cvs command)
+@cindex Getting status
+@kindex l@r{--run @samp{cvs log}}
+@kindex s@r{--run @samp{cvs status}}
+@findex cvs-mode-log
+@findex cvs-mode-status
+
+@table @kbd
+@item l
+Call the command @code{cvs-mode-log} which runs @samp{cvs log} on all
+selected files, and show the result in a temporary buffer
+@samp{*cvs-info*} (@pxref{Log View Mode}).
+
+@item s
+Call the command @code{cvs-mode-status} which runs @samp{cvs status} on
+all selected files, and show the result in a temporary buffer
+@samp{*cvs-info*}.
+@c Fixme: reinstate when node is written:
+@c (@pxref{CVS Status Mode}).
+@end table
+
+
+@node Adding and removing files, Undoing changes, Getting info about files, Commands
+@section Adding and removing files
+@cindex Adding files
+@cindex Removing files
+@cindex Resurrecting files
+@cindex Deleting files
+@cindex Putting files under CVS control
+@kindex a@r{--add a file}
+@kindex r@r{--remove a file}
+@findex cvs-mode-add
+@findex cvs-mode-remove-file
+
+The following commands are available to make it easy to add files to
+and remove them from the CVS repository.
+
+@table @kbd
+@item a
+Add all selected files. This command can be used on @samp{Unknown}
+files (@pxref{Buffer contents}). The status of the file will change to
+@samp{Added}, and you will have to use @kbd{c} (@samp{cvs-mode-commit}
+@pxref{Committing changes}), to really add the file to the
+repository.@refill
+
+This command can also be used on @samp{Removed} files (before you commit
+them) to resurrect them.
+
+The command that is run is @code{cvs-mode-add}.
+
+@item r
+This command removes the selected files (after prompting for
+confirmation). The files are deleted from your directory and
+(unless the status was @samp{Unknown}; @pxref{Buffer contents}) they will
+also be @samp{cvs remove}d. If the files' status was @samp{Unknown}
+they will disappear from the buffer. Otherwise their status will change to
+@samp{Removed}, and you must use @kbd{c} (@samp{cvs-mode-commit},
+@pxref{Committing changes}) to commit the removal.@refill
+
+The command that is run is @code{cvs-mode-remove-file}.
+@end table
+
+
+@node Undoing changes, Removing handled entries, Adding and removing files, Commands
+@section Undoing changes
+@cindex Undo changes
+@cindex Flush changes
+@kindex U@r{--undo changes}
+@findex cvs-mode-undo-local-changes
+
+@table @kbd
+@item U
+If you have modified a file, and for some reason decide that you don't
+want to keep the changes, you can undo them with this command. It works
+by removing your working copy of the file and then getting the latest
+version from the repository (@code{cvs-mode-undo-local-changes}).
+@end table
+
+
+@node Removing handled entries, Ignoring files, Undoing changes, Commands
+@section Removing handled entries
+@cindex Expunging uninteresting entries
+@cindex Uninteresting entries, getting rid of them
+@cindex Getting rid of uninteresting lines
+@cindex Removing uninteresting (processed) lines
+@cindex Handled lines, removing them
+@kindex x@r{--remove processed entries}
+@kindex C-k@r{--remove selected entries}
+@findex cvs-mode-remove-handled
+@findex cvs-mode-acknowledge
+@findex cvs-mode-ignore
+
+@table @kbd
+@item x
+This command allows you to remove all entries that you have processed.
+More specifically, the lines for @samp{Up-to-date} files (@pxref{Buffer
+contents}) are removed from the buffer. If a directory becomes empty
+the heading for that directory is also removed. This makes it easier to
+get an overview of what needs to be done.
+
+@vindex cvs-mode-remove-handled@r{ (variable)}
+@kbd{x} invokes @code{cvs-mode-remove-handled}. If
+@samp{cvs-auto-remove-handled} is set to non-@code{nil}, this will
+automatically be performed after every commit.@refill
+
+@item C-k
+This command can be used for lines that @samp{cvs-mode-remove-handled} would
+not delete, but that you want to delete (@code{cvs-mode-acknowledge}).
+@end table
+
+
+@node Ignoring files, Viewing differences, Removing handled entries, Commands
+@section Ignoring files
+@cindex Ignoring files
+@kindex i@r{--ignoring files}
+@findex cvs-mode-ignore
+
+@table @kbd
+@item i
+Arrange so that CVS will ignore the selected files. The file names are
+added to the @file{.cvsignore} file in the corresponding directory. If
+the @file{.cvsignore} file doesn't exist, it will be created.
+
+The @file{.cvsignore} file should normally be added to the repository,
+but you could ignore it as well, if you like it better that way.
+
+This runs @code{cvs-mode-ignore}.
+@end table
+
+@node Viewing differences, Invoking Ediff, Ignoring files, Commands
+@section Viewing differences
+@cindex Diff
+@cindex Invoking @code{diff}
+@cindex Conflicts, how to resolve them
+@cindex Viewing differences
+@kindex d=@r{--run @samp{cvs diff}}
+@kindex =@r{--run @samp{cvs diff}}
+@kindex db@r{--diff against base version}
+@kindex dh@r{--diff against head of repository}
+@kindex dr@r{--diff between base and head of repository}
+@kindex dv@r{--diff against vendor branch}
+@kindex dy@r{--diff against yesterday's head}
+@findex cvs-mode-diff
+@findex cvs-mode-diff-backup
+@findex cvs-mode-diff-head
+@findex cvs-mode-diff-repository
+@findex cvs-mode-diff-vendor
+@findex cvs-mode-diff-yesterday
+@vindex cvs-invert-ignore-marks@r{ (variable)}
+
+@table @kbd
+@item =
+@itemx d =
+Display a @samp{cvs diff} between the selected files and the version
+that they are based on (@code{cvs-mode-diff}).@refill
+
+@item d b
+If CVS finds a conflict while merging two versions of a file (during a
+@samp{cvs update}, @pxref{Updating the buffer}) it will save the
+original file in a file called @file{.#@var{file}.@var{version}} where
+@var{file} is the name of the file, and @var{version} is the revision
+number that @var{file} was based on.@refill
+
+With the @kbd{d b} command you can run a @samp{diff} on the files
+@file{.#@var{file}.@var{version}} and @file{@var{file}}.@refill
+
+@item d h
+Display a @samp{cvs diff} between the selected files and the head
+revision (the most recent version on the current
+branch) in the repository (@code{cvs-mode-diff-head}).@refill
+
+@item d r
+Display a @samp{cvs diff} between the base revision of the selected
+files and the head revision in the repository. This displays the
+changes anyone has committed to the repository since you last executed
+a checkout, update or commit operation
+(@code{cvs-mode-diff-repository}).
+
+@item d v
+Display a @samp{cvs diff} between the selected files and the head
+revision of the vendor branch in the repository
+(@code{cvs-mode-diff-vendor}).@refill
+
+@item d y
+Display a @samp{cvs diff} between the selected files and yesterday's
+head revision in the repository
+(@code{cvs-mode-diff-yesterday}).@refill
+@end table
+
+By default, @samp{diff} commands ignore the marks. This can be changed
+with @code{cvs-invert-ignore-marks}.
+
+@node Invoking Ediff, Updating files, Viewing differences, Commands
+@section Running ediff
+@cindex Ediff
+@cindex Invoking ediff
+@cindex Viewing differences
+@cindex Conflicts, how to resolve them
+@cindex Resolving conflicts
+@kindex e@r{--invoke @samp{ediff}}
+@findex cvs-mode-idiff
+@findex cvs-mode-imerge
+
+@table @kbd
+@vindex cvs-idiff-imerge-handlers@r{ (variable)}
+@item d e
+This uses @code{ediff} (or @code{emerge}, depending on
+@samp{cvs-idiff-imerge-handlers}) to allow you to view diffs.
+If a prefix argument is given, PCL-CVS will prompt for a revision against
+which the diff should be made, else the default will be to use the BASE
+revision.
+
+@cindex Merging with @code{ediff} and @code{emerge}
+@item d E
+This command use @code{ediff} (or @code{emerge}, see above) to allow you
+to do an interactive 3-way merge.
+
+@strong{Please note:} when the file status is @samp{Conflict},
+CVS has already performed a merge. The resulting file is not used in
+any way if you use this command. If you use the @kbd{q} command inside
+@samp{ediff} (to successfully terminate a merge) the file that CVS
+created will be overwritten.@refill
+@end table
+
+@node Updating files, Tagging files, Invoking Ediff, Commands
+@section Updating files
+@findex cvs-mode-update
+@cindex Updating files
+@kindex O@r{--update files}
+
+@table @kbd
+@item O
+Update all selected files with status @samp{Need-update} by running
+@samp{cvs update} on them (@code{cvs-mode-update}).
+@end table
+
+
+@node Tagging files, Miscellaneous commands, Updating files, Commands
+@section Tagging files
+@findex cvs-mode-tag
+@findex cvs-mode-untag
+@findex cvs-rtag
+@cindex Tagging files
+@kindex M-t@r{--repository tag files}
+@kindex t@r{--tag files}
+@vindex cvs-invert-ignore-marks@r{ (variable)}
+@vindex cvs-force-dir-tag@r{ (variable)}
+
+@table @kbd
+@item t
+Tag all selected files by running @samp{cvs tag} on
+them (@code{cvs-mode-tag}). It's usually preferable to tag a directory
+at a time. Rather than selecting all files (which too often doesn't
+select all files but only the few that are displayed), clear the
+selection with @kbd{M-DEL} (@code{cvs-mode-unmark-all-files}), position
+the cursor on the directory you want to tag and hit @kbd{t}.
+@end table
+
+By default, @samp{tag} commands ignore the marks. This can be changed
+with @code{cvs-invert-ignore-marks}. Also, by default @samp{tag} can
+only be applied to directories, see @code{cvs-force-dir-tag} if you want
+to change this behavior.
+
+
+@node Miscellaneous commands, , Tagging files, Commands
+@section Miscellaneous commands
+@findex cvs-mode-byte-compile-files
+@cindex Recompiling elisp files
+@cindex Byte compilation
+@findex cvs-mode-delete-lock
+@cindex Getting rid of lock files
+@cindex Lock files
+@kindex q@r{--bury the PCL-CVS buffer}
+@findex cvs-bury-buffer
+@findex cvs-mode-quit
+@cindex Quitting
+@kindex h@r{--help}
+@kindex ?@r{--help}
+@findex cvs-help
+@cindex Help
+
+@table @kbd
+@item M-x cvs-mode-byte-compile-files
+Byte compile all selected files that end in @file{.el}.
+
+@item M-x cvs-mode-delete-lock
+This command deletes the lock files that
+the @samp{*cvs*} buffer informs you about. You should normally never have to
+use this command, since CVS tries very carefully to always remove the
+lock files itself.
+
+You can only use this command when a message in the @samp{*cvs*} buffer tells
+you so. You should wait a while before using this command in case
+someone else is running a @code{cvs} command.
+
+Also note that this only works if the repository is local.
+
+@item ?
+@itemx h
+Show a summary of common command key bindings in the echo
+area (@code{cvs-help}).
+
+@item q
+Bury the PCL-CVS buffer (@code{cvs-bury-buffer}).
+
+@item M-x cvs-mode-quit
+Quit PCL-CVS, killing the @samp{*cvs*} buffer.
+@end table
+
+@node Log Edit Mode, Log View Mode, Commands, Top
+@chapter Editing a Log Message
+
+@cindex Log Edit mode
+@cindex mode, Log Edit
+Buffers for entering/editing log messages for changes which are about
+to be committed are put into Log Edit mode.
+
+Sometimes the log buffer contains default text when you enter it,
+typically the last log message entered. If it does, mark and point
+are set around the entire contents of the buffer so that it is easy to
+kill the contents of the buffer with @kbd{C-w}.
+
+@findex log-edit-insert-changelog
+If you work by writing entries in the @file{ChangeLog}
+(@pxref{(emacs)Change Log}) and then commit the change under revision
+control, you can generate the Log Edit text from the ChangeLog using
+@kbd{C-c C-a} (@kbd{log-edit-insert-changelog}). This looks for
+entries for the file(s) concerned in the top entry in the ChangeLog
+and uses those paragraphs as the log text. This text is only inserted
+if the top entry was made under your user name on the current date.
+@xref{(emacs)Change Logs and VC}, for the opposite way of
+working---generating ChangeLog entries from the revision control log.
+
+In the Log Edit buffer, @kbd{C-c C-f} (@kbd{M-x log-edit-show-files})
+shows the list of files to be committed in case you need to check
+that.
+
+When you have finished editing the log message, type @kbd{C-c C-c} to
+exit the buffer and commit the change.
+
+@c Fixme: customization variables
+
+@node Log View Mode, Customization, Log Edit Mode, Top
+@chapter Browsing a Log of Changes
+
+@cindex Log View mode
+@cindex mode, Log View
+@cindex output, logs
+
+@findex cvs-mode-log
+@findex vc-print-log
+Log View mode provides a few useful commands for navigating revision
+control log output. It is used for the output buffers of both
+@code{cvs-mode-log} and @code{vc-print-log}.
+
+In this mode, @kbd{n} goes to the next message and @kbd{p} goes to the
+previous message and @kbd{N} and @kbd{P} go to the next and previous
+files, respectively, in multi-file output. With a numeric prefix
+argument, these commands move that many messages of files.
+
+@c @node CVS Status Mode
+@c @chapter Viewing CVS' Status output
+
+@node Customization, Bugs, Log View Mode, Top
+@chapter Customization
+@vindex log-edit-changelog-full-paragraphs@r{ (variable)}
+@vindex cvs-auto-remove-handled@r{ (variable)}
+@vindex cvs-auto-remove-directories@r{ (variable)}
+@vindex cvs-update-prog-output-skip-regexp@r{ (variable)}
+@vindex cvs-cvsroot@r{ (variable)}
+@vindex cvs-auto-revert@r{ (variable)}
+@vindex log-edit-require-final-newline@r{ (variable)}
+@vindex cvs-sort-ignore-file@r{ (variable)}
+@cindex Customization
+@cindex Variables, list of all
+@cindex Erasing input buffer
+@cindex Context diff, how to get
+@cindex Unidiff, how to get
+@cindex Automatically remove handled files
+@cindex @samp{-u} option in modules file
+@cindex Modules file (@samp{-u} option)
+@cindex Update program (@samp{-u} option in modules file)
+@cindex Reverting buffers after commit
+@cindex Require final newline
+@cindex Automatically inserting newline
+@cindex Commit message, inserting newline
+@cindex Sorting @file{.cvsignore} file
+@cindex @file{.cvsignore} file, sorting
+@cindex Automatically sorting @file{.cvsignore}
+@cindex @samp{CVSROOT}, overriding
+
+If you have an idea about any customization that would be handy but
+isn't present in this list, please tell us!
+For info on how to reach us, see @ref{Bugs}.@refill
+
+@table @samp
+@item cvs-auto-remove-handled
+If this variable is set to any non-@code{nil} value,
+@samp{cvs-mode-remove-handled} will be called every time you check in
+files, after the check-in is ready. @xref{Removing handled
+entries}.@refill
+
+@item cvs-auto-remove-directories
+If this variable is set to any non-@code{nil} value, directories that do
+not contain any files to be checked in will not be listed in the
+@samp{*cvs*} buffer.@refill
+
+@item cvs-auto-revert
+If this variable is set to any non-@samp{nil} value any buffers you have
+that visit a file that is committed will be automatically reverted.
+This variable defaults to @samp{t}. @xref{Committing changes}.@refill
+
+@item cvs-update-prog-output-skip-regexp
+The @samp{-u} flag in the @file{modules} file can be used to run a command
+whenever a @samp{cvs update} is performed (see @code{cvs(5)}). This regexp
+is used to search for the last line in that output. It is normally set
+to @samp{$}. That setting is only correct if the command outputs
+nothing. Note that PCL-CVS will get very confused if the command
+outputs @emph{anything} to @code{stderr}.
+
+@item cvs-cvsroot
+This variable can be set to override @samp{CVSROOT}. It should be a
+string. If it is set, then every time a @code{cvs} command is run, it
+will be called as @samp{cvs -d @var{cvs-cvsroot}@dots{}}. This can be
+useful if your site has several repositories.
+
+@item log-edit-require-final-newline
+@c wordy to avoid unhderfull hbox
+When you enter a log message by typing into the
+@samp{*cvs-commit-message*} buffer, PCL-CVS normally automatically
+inserts a trailing newline, unless there already is one. This behavior
+can be controlled via @samp{cvs-commit-buffer-require-final-newline}.
+If it is @samp{t} (the default behavior), a newline will always be
+appended. If it is @samp{nil}, newlines will never be appended. Any
+other value causes PCL-CVS to ask the user whenever there is no trailing
+newline in the commit message buffer.
+
+@findex cvs-mode-changelog-commit
+@item log-edit-changelog-full-paragraphs
+If this variable is non-@code{nil}, include full @file{ChangeLog}
+paragraphs in the CVS log created by @samp{cvs-mode-changelog-commit}.
+This may be set in the local variables section of a @file{ChangeLog}
+file, to indicate the policy for that @file{ChangeLog}.
+
+@cindex @file{ChangeLog} paragraphs
+A @dfn{@file{ChangeLog} paragraph} is a bunch of log text containing no
+blank lines; a paragraph usually describes a set of changes with a
+single purpose, but perhaps spanning several functions in several files.
+Changes in different paragraphs are unrelated.
+
+You could argue that the CVS log entry for a file should contain the
+full @file{ChangeLog} paragraph mentioning the change to the file, even though
+it may mention other files, because that gives you the full context you
+need to understand the change. This is the behavior you get when this
+variable is set to @code{t}, the default.
+
+On the other hand, you could argue that the CVS log entry for a change
+should contain only the text for the changes which occurred in that
+file, because the CVS log is per-file. This is the behavior you get
+when this variable is set to @code{nil}.
+
+@findex cvs-mode-ignore@r{, and @file{.cvsignore} sorting}
+@item cvs-sort-ignore-file
+If this variable is set to any non-@samp{nil} value, the
+@file{.cvsignore} file will always be sorted whenever you use
+@samp{cvs-mode-ignore} to add a file to it. This option is on by
+default.
+@end table
+
+
+@menu
+* Customizing Faces::
+@end menu
+
+@node Customizing Faces, , Customization, Customization
+@section Customizing Faces
+@vindex cvs-header (face)
+@vindex cvs-filename (face)
+@vindex cvs-unknown (face)
+@vindex cvs-handled (face)
+@vindex cvs-need-action (face)
+@vindex cvs-marked (face)
+@vindex cvs-msg (face)
+
+PCL-CVS adds a few extra features, including menus, mouse bindings, and
+fontification of the @samp{*cvs*} buffer. The faces defined for
+fontification are listed below:
+
+@table @samp
+@item cvs-header
+used to highlight directory changes.
+
+@item cvs-filename
+Used to highlight file names.
+
+@item cvs-unknown
+Used to highlight the status of files which are @samp{Unknown}.
+
+@item cvs-handled
+Used to highlight the status of files which are handled and
+need no further action.
+
+@item cvs-need-action
+Used to highlight the status of files which still need action.
+
+@item cvs-marked
+Used to highlight the marked file indicator (@samp{*}).
+
+@item cvs-msg
+Used to highlight CVS messages.
+@end table
+
+
+@node Bugs, GNU Free Documentation License, Customization, Top
+@chapter Bugs (known and unknown)
+@cindex Reporting bugs and ideas
+@cindex Bugs, how to report them
+@cindex Author, how to reach
+@cindex Email to the author
+@cindex Known bugs
+@cindex Bugs, known
+@cindex FAQ
+@cindex Problems, list of common
+
+If you find a bug or misfeature, don't hesitate to tell us! Send email
+to @email{bug-gnu-emacs@@gnu.org} which is gatewayed to the newsgroup
+@samp{gnu.emacs.bugs}. Feature requests should also be sent there. We
+prefer discussing one thing at a time. If you find several unrelated
+bugs, please report them separately. If you are running PCL-CVS under
+XEmacs, you should also send a copy of bug reports to
+@email{xemacs-beta@@xemacs.org}.
+
+If you have problems using PCL-CVS or other questions, send them to
+@email{help-gnu-emacs@@gnu.org}, which is gatewayed to the
+@samp{gnu.emacs.help} newsgroup. This is a good place to get help, as
+is @email{cvs-info@@gnu.org}, gatewayed to @samp{gnu.cvs.help}.
+
+If you have ideas for improvements, or if you have written some
+extensions to this package, we would like to hear from you. We hope that
+you find this package useful!
+
+Below is a partial list of currently known problems with PCL-CVS.
+
+@table @asis
+@item Unexpected output from CVS
+Unexpected output from CVS may confuse PCL-CVS. It will create
+warning messages in the @samp{*cvs*} buffer alerting you to any parse errors.
+If you get these messages, please send a bug report to the email
+addresses listed above. Include the contents of the @samp{*cvs*} buffer, the
+output of the CVS process (which should be found in the @samp{ *cvs-tmp*}
+buffer), and the versions of Emacs, PCL-CVS and CVS you are using.
+@end table
+
+@node GNU Free Documentation License, Function and Variable Index, Bugs, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+
+
+@node Function and Variable Index, Concept Index, GNU Free Documentation License, Top
+@unnumbered Function and Variable Index
+
+This is an index of all the functions and variables documented in this
+manual.
+
+@printindex fn
+
+@node Concept Index, Key Index, Function and Variable Index, Top
+@unnumbered Concept Index
+
+This is an index of concepts discussed in this manual.
+
+@printindex cp
+
+@node Key Index, , Concept Index, Top
+@unnumbered Key Index
+
+This index includes an entry for each PCL-CVS key sequence documented in
+this manual.
+
+@printindex ky
+
+@setchapternewpage odd
+@summarycontents
+@contents
+@bye
+
+@ignore
+ arch-tag: 5c7178ce-56fa-40b0-abd7-f4a09758b235
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+
+@setfilename ../info/pgg
+
+@set VERSION 0.1
+
+
+@copying
+This file describes PGG, an Emacs interface to various PGP implementations.
+
+Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007 Free Software
+Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled ``GNU
+Free Documentation License.''
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* PGG: (pgg). Emacs interface to various PGP implementations.
+@end direntry
+
+@settitle PGG @value{VERSION}
+
+
+@titlepage
+@title PGG
+
+@author by Daiki Ueno
+@page
+
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+@page
+
+@node Top
+@top PGG
+This manual describes PGG. PGG is an interface library between Emacs
+and various tools for secure communication. PGG also provides a simple
+user interface to encrypt, decrypt, sign, and verify MIME messages.
+
+@menu
+* Overview:: What PGG is.
+* Prerequisites:: Complicated stuff you may have to do.
+* How to use:: Getting started quickly.
+* Architecture::
+* Parsing OpenPGP packets::
+* GNU Free Documentation License:: The license for this documentation.
+* Function Index::
+* Variable Index::
+@end menu
+
+@node Overview
+@chapter Overview
+
+PGG is an interface library between Emacs and various tools for secure
+communication. Even though Mailcrypt has similar feature, it does not
+deal with detached PGP messages, normally used in PGP/MIME
+infrastructure. This was the main reason why I wrote the new library.
+
+PGP/MIME is an application of MIME Object Security Services (RFC1848).
+The standard is documented in RFC2015.
+
+@node Prerequisites
+@chapter Prerequisites
+
+PGG requires at least one implementation of privacy guard system.
+This document assumes that you have already obtained and installed them
+and that you are familiar with its basic functions.
+
+By default, PGG uses GnuPG. If you are new to such a system, I
+recommend that you should look over the GNU Privacy Handbook (GPH)
+which is available at @uref{http://www.gnupg.org/documentation/}.
+
+When using GnuPG, we recommend the use of the @code{gpg-agent}
+program, which is distributed with versions 2.0 and later of GnuPG.
+This is a daemon to manage private keys independently from any
+protocol, and provides the most secure way to input and cache your
+passphrases (@pxref{Caching passphrase}). By default, PGG will
+attempt to use @code{gpg-agent} if it is running. @xref{Invoking
+GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
+
+PGG also supports Pretty Good Privacy version 2 or version 5.
+
+@node How to use
+@chapter How to use
+
+The toplevel interface of this library is quite simple, and only
+intended to use with public-key cryptographic operation.
+
+To use PGG, evaluate following expression at the beginning of your
+application program.
+
+@lisp
+(require 'pgg)
+@end lisp
+
+If you want to check existence of pgg.el at runtime, instead you can
+list autoload setting for desired functions as follows.
+
+@lisp
+(autoload 'pgg-encrypt-region "pgg"
+ "Encrypt the current region." t)
+(autoload 'pgg-encrypt-symmetric-region "pgg"
+ "Encrypt the current region with symmetric algorithm." t)
+(autoload 'pgg-decrypt-region "pgg"
+ "Decrypt the current region." t)
+(autoload 'pgg-sign-region "pgg"
+ "Sign the current region." t)
+(autoload 'pgg-verify-region "pgg"
+ "Verify the current region." t)
+(autoload 'pgg-insert-key "pgg"
+ "Insert the ASCII armored public key." t)
+(autoload 'pgg-snarf-keys-region "pgg"
+ "Import public keys in the current region." t)
+@end lisp
+
+@menu
+* User Commands::
+* Selecting an implementation::
+* Caching passphrase::
+* Default user identity::
+@end menu
+
+@node User Commands
+@section User Commands
+
+At this time you can use some cryptographic commands. The behavior of
+these commands relies on a fashion of invocation because they are also
+intended to be used as library functions. In case you don't have the
+signer's public key, for example, the function @code{pgg-verify-region}
+fails immediately, but if the function had been called interactively, it
+would ask you to retrieve the signer's public key from the server.
+
+@deffn Command pgg-encrypt-region start end recipients &optional sign passphrase
+Encrypt the current region between @var{start} and @var{end} for
+@var{recipients}. When the function were called interactively, you
+would be asked about the recipients.
+
+If encryption is successful, it replaces the current region contents (in
+the accessible portion) with the resulting data.
+
+If optional argument @var{sign} is non-@code{nil}, the function is
+request to do a combined sign and encrypt. This currently is
+confirmed to work with GnuPG, but might not work with PGP or PGP5.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
+@end deffn
+
+@deffn Command pgg-encrypt-symmetric-region &optional start end passphrase
+Encrypt the current region between @var{start} and @var{end} using a
+symmetric cipher. After invocation you are asked for a passphrase.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
+
+symmetric-cipher encryption is currently only implemented for GnuPG.
+@end deffn
+
+@deffn Command pgg-decrypt-region start end &optional passphrase
+Decrypt the current region between @var{start} and @var{end}. If
+decryption is successful, it replaces the current region contents (in
+the accessible portion) with the resulting data.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
+@end deffn
+
+@deffn Command pgg-sign-region start end &optional cleartext passphrase
+Make the signature from text between @var{start} and @var{end}. If the
+optional third argument @var{cleartext} is non-@code{nil}, or the
+function is called interactively, it does not create a detached
+signature. In such a case, it replaces the current region contents (in
+the accessible portion) with the resulting data.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
+@end deffn
+
+@deffn Command pgg-verify-region start end &optional signature fetch
+Verify the current region between @var{start} and @var{end}. If the
+optional third argument @var{signature} is non-@code{nil}, it is treated
+as the detached signature file of the current region.
+
+If the optional 4th argument @var{fetch} is non-@code{nil}, or the
+function is called interactively, we attempt to fetch the signer's
+public key from the key server.
+@end deffn
+
+@deffn Command pgg-insert-key
+Retrieve the user's public key and insert it as ASCII-armored format.
+@end deffn
+
+@deffn Command pgg-snarf-keys-region start end
+Collect public keys in the current region between @var{start} and
+@var{end}, and add them into the user's keyring.
+@end deffn
+
+@node Selecting an implementation
+@section Selecting an implementation
+
+Since PGP has a long history and there are a number of PGP
+implementations available today, the function which each one has differs
+considerably. For example, if you are using GnuPG, you know you can
+select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
+the other hand the version 2 of PGP only supports IDEA.
+
+Which implementation is used is controlled by the @code{pgg-scheme}
+variable. If it is @code{nil} (the default), the value of the
+@code{pgg-default-scheme} variable will be used instead.
+
+@defvar pgg-scheme
+Force specify the scheme of PGP implementation. The value can be set to
+@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{nil}.
+@end defvar
+
+@defvar pgg-default-scheme
+The default scheme of PGP implementation. The value should be one of
+@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{gpg}.
+@end defvar
+
+@node Caching passphrase
+@section Caching passphrase
+
+When using GnuPG (gpg) as the PGP scheme, we recommend using a program
+called @code{gpg-agent} for entering and caching
+passphrases@footnote{Actually, @code{gpg-agent} does not cache
+passphrases but private keys. On the other hand, from a user's point
+of view, this technical difference isn't visible.}.
+
+@defvar pgg-gpg-use-agent
+If non-@code{nil}, attempt to use @code{gpg-agent} whenever possible.
+The default is @code{t}. If @code{gpg-agent} is not running, or GnuPG
+is not the current PGP scheme, PGG's own passphrase-caching mechanism
+is used (see below).
+@end defvar
+
+To use @code{gpg-agent} with PGG, you must first ensure that
+@code{gpg-agent} is running. For example, if you are running in the X
+Window System, you can do this by putting the following line in your
+@file{.xsession} file:
+
+@smallexample
+eval "$(gpg-agent --daemon)"
+@end smallexample
+
+For more details on invoking @code{gpg-agent}, @xref{Invoking
+GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
+
+Whenever you perform a PGG operation that requires a GnuPG passphrase,
+GnuPG will contact @code{gpg-agent}, which prompts you for the
+passphrase. Furthermore, @code{gpg-agent} ``caches'' the result, so
+that subsequent uses will not require you to enter the passphrase
+again. (This cache usually expires after a certain time has passed;
+you can change this using the @code{--default-cache-ttl} option when
+invoking @code{gpg-agent}.)
+
+If you are running in a X Window System environment, @code{gpg-agent}
+prompts for a passphrase by opening a graphical window. However, if
+you are running Emacs on a text terminal, @code{gpg-agent} has trouble
+receiving input from the terminal, since it is being sent to Emacs.
+One workaround for this problem is to run @code{gpg-agent} on a
+different terminal from Emacs, with the @code{--keep-tty} option; this
+tells @code{gpg-agent} use its own terminal to prompt for passphrases.
+
+When @code{gpg-agent} is not being used, PGG prompts for a passphrase
+through Emacs. It also has its own passphrase caching mechanism,
+which is controlled by the variable @code{pgg-cache-passphrase} (see
+below).
+
+There is a security risk in handling passphrases through PGG rather
+than @code{gpg-agent}. When you enter your passphrase into an Emacs
+prompt, it is temporarily stored as a cleartext string in the memory
+of the Emacs executable. If the executable memory is swapped to disk,
+the root user can, in theory, extract the passphrase from the
+swapfile. Furthermore, the swapfile containing the cleartext
+passphrase might remain on the disk after the system is discarded or
+stolen. @code{gpg-agent} avoids this problem by using certain tricks,
+such as memory locking, which have not been implemented in Emacs.
+
+@defvar pgg-cache-passphrase
+If non-@code{nil}, store passphrases. The default value of this
+variable is @code{t}. If you are worried about security issues,
+however, you could stop the caching of passphrases by setting this
+variable to @code{nil}.
+@end defvar
+
+@defvar pgg-passphrase-cache-expiry
+Elapsed time for expiration in seconds.
+@end defvar
+
+If your passphrase contains non-ASCII characters, you might need to
+specify the coding system to be used to encode your passphrases, since
+GnuPG treats them as a byte sequence, not as a character sequence.
+
+@defvar pgg-passphrase-coding-system
+Coding system used to encode passphrase.
+@end defvar
+
+@node Default user identity
+@section Default user identity
+
+The PGP implementation is usually able to select the proper key to use
+for signing and decryption, but if you have more than one key, you may
+need to specify the key id to use.
+
+@defvar pgg-default-user-id
+User ID of your default identity. It defaults to the value returned
+by @samp{(user-login-name)}. You can customize this variable.
+@end defvar
+
+@defvar pgg-gpg-user-id
+User ID of the GnuPG default identity. It defaults to @samp{nil}.
+This overrides @samp{pgg-default-user-id}. You can customize this
+variable.
+@end defvar
+
+@defvar pgg-pgp-user-id
+User ID of the PGP 2.x/6.x default identity. It defaults to
+@samp{nil}. This overrides @samp{pgg-default-user-id}. You can
+customize this variable.
+@end defvar
+
+@defvar pgg-pgp5-user-id
+User ID of the PGP 5.x default identity. It defaults to @samp{nil}.
+This overrides @samp{pgg-default-user-id}. You can customize this
+variable.
+@end defvar
+
+@node Architecture
+@chapter Architecture
+
+PGG introduces the notion of a "scheme of PGP implementation" (used
+interchangeably with "scheme" in this document). This term refers to a
+singleton object wrapped with the luna object system.
+
+Since PGG was designed for accessing and developing PGP functionality,
+the architecture had to be designed not just for interoperability but
+also for extensiblity. In this chapter we explore the architecture
+while finding out how to write the PGG backend.
+
+@menu
+* Initializing::
+* Backend methods::
+* Getting output::
+@end menu
+
+@node Initializing
+@section Initializing
+
+A scheme must be initialized before it is used.
+It had better guarantee to keep only one instance of a scheme.
+
+The following code is snipped out of @file{pgg-gpg.el}. Once an
+instance of @code{pgg-gpg} scheme is initialized, it's stored to the
+variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
+
+@lisp
+(defvar pgg-scheme-gpg-instance nil)
+
+(defun pgg-make-scheme-gpg ()
+ (or pgg-scheme-gpg-instance
+ (setq pgg-scheme-gpg-instance
+ (luna-make-entity 'pgg-scheme-gpg))))
+@end lisp
+
+The name of the function must follow the
+regulation---@code{pgg-make-scheme-} follows the backend name.
+
+@node Backend methods
+@section Backend methods
+
+In each backend, these methods must be present. The output of these
+methods is stored in special buffers (@ref{Getting output}), so that
+these methods must tell the status of the execution.
+
+@deffn Method pgg-scheme-lookup-key scheme string &optional type
+Return keys associated with @var{string}. If the optional third
+argument @var{type} is non-@code{nil}, it searches from the secret
+keyrings.
+@end deffn
+
+@deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase
+Encrypt the current region between @var{start} and @var{end} for
+@var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign
+and encrypt. If encryption is successful, it returns @code{t},
+otherwise @code{nil}.
+@end deffn
+
+@deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase
+Encrypt the current region between @var{start} and @var{end} using a
+symmetric cipher and a passphrases. If encryption is successful, it
+returns @code{t}, otherwise @code{nil}. This function is currently only
+implemented for GnuPG.
+@end deffn
+
+@deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase
+Decrypt the current region between @var{start} and @var{end}. If
+decryption is successful, it returns @code{t}, otherwise @code{nil}.
+@end deffn
+
+@deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase
+Make the signature from text between @var{start} and @var{end}. If the
+optional third argument @var{cleartext} is non-@code{nil}, it does not
+create a detached signature. If signing is successful, it returns
+@code{t}, otherwise @code{nil}.
+@end deffn
+
+@deffn Method pgg-scheme-verify-region scheme start end &optional signature
+Verify the current region between @var{start} and @var{end}. If the
+optional third argument @var{signature} is non-@code{nil}, it is treated
+as the detached signature of the current region. If the signature is
+successfully verified, it returns @code{t}, otherwise @code{nil}.
+@end deffn
+
+@deffn Method pgg-scheme-insert-key scheme
+Retrieve the user's public key and insert it as ASCII-armored format.
+On success, it returns @code{t}, otherwise @code{nil}.
+@end deffn
+
+@deffn Method pgg-scheme-snarf-keys-region scheme start end
+Collect public keys in the current region between @var{start} and
+@var{end}, and add them into the user's keyring.
+On success, it returns @code{t}, otherwise @code{nil}.
+@end deffn
+
+@node Getting output
+@section Getting output
+
+The output of the backend methods (@ref{Backend methods}) is stored in
+special buffers, so that these methods must tell the status of the
+execution.
+
+@defvar pgg-errors-buffer
+The standard error output of the execution of the PGP command is stored
+here.
+@end defvar
+
+@defvar pgg-output-buffer
+The standard output of the execution of the PGP command is stored here.
+@end defvar
+
+@defvar pgg-status-buffer
+The rest of status information of the execution of the PGP command is
+stored here.
+@end defvar
+
+@node Parsing OpenPGP packets
+@chapter Parsing OpenPGP packets
+
+The format of OpenPGP messages is maintained in order to publish all
+necessary information needed to develop interoperable applications.
+The standard is documented in RFC 2440.
+
+PGG has its own parser for the OpenPGP packets.
+
+@defun pgg-parse-armor string
+List the sequence of packets in @var{string}.
+@end defun
+
+@defun pgg-parse-armor-region start end
+List the sequence of packets in the current region between @var{start}
+and @var{end}.
+@end defun
+
+@defvar pgg-ignore-packet-checksum
+If non-@code{nil}, don't check the checksum of the packets.
+@end defvar
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Function Index
+@unnumbered Function Index
+@printindex fn
+
+@node Variable Index
+@unnumbered Variable Index
+@printindex vr
+
+@summarycontents
+@contents
+@bye
+
+@c End:
+
+@ignore
+ arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85
+@end ignore
--- /dev/null
+\input texinfo
+@c %**start of header
+@setfilename ../info/rcirc
+@settitle rcirc Manual
+@c %**end of header
+
+@copying
+Copyright @copyright{} 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
+and with the Back-Cover Texts as in (a) below. A copy of the license is
+included in the section entitled ``GNU Free Documentation License'' in
+the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Rcirc: (rcirc). Internet Relay Chat (IRC) client.
+@end direntry
+
+@titlepage
+@title rcirc Manual
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnottex
+@node Top, Basics, (dir), (dir)
+@top rcirc Manual
+@end ifnottex
+
+@code{rcirc} is an Emacs IRC client.
+
+IRC (Internet Relay Chat) is a multi-user chat protocol. Users
+communicate with each other in real-time. Communication occurs both in
+topic channels which are collections of many users, or privately, with
+just one other user.
+
+@menu
+* Basics::
+* Reference::
+* Hacking and Tweaking::
+* GNU Free Documentation License::
+* Key Index::
+* Variable Index::
+* Index::
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Basics
+
+* Internet Relay Chat::
+* Getting started with rcirc::
+
+Reference
+
+* rcirc commands::
+* Useful IRC commands::
+* Configuration::
+
+Hacking and Tweaking
+
+* Skipping /away messages using handlers::
+* Using fly spell mode::
+* Scrolling conservatively::
+* Changing the time stamp format::
+* Defining a new command::
+* Reconnecting after you have lost the connection::
+
+@end detailmenu
+@end menu
+
+@node Basics, Reference, Top, Top
+@chapter Basics
+
+This chapter contains a brief introduction to IRC (Internet Relay Chat),
+and a quick tutorial on @code{rcirc}.
+
+@menu
+* Internet Relay Chat::
+* Getting started with rcirc::
+@end menu
+
+@node Internet Relay Chat, Getting started with rcirc, Basics, Basics
+@section Internet Relay Chat
+@cindex internet relay chat
+@cindex irc
+
+@cindex channel
+@dfn{Internet Relay Chat} (IRC) is a form of instant communication over the
+Internet. It is mainly designed for group (many-to-many) communication
+in discussion forums called channels, but also allows one-to-one
+communication.
+
+@cindex instant messaging, comparison
+@cindex server
+@cindex network
+Contrary to most Instant Messenger (IM) systems, users usually don't
+connect to a central server. Instead, users connect to a random server
+in a network, and the servers share information between them.
+
+Here's a typical example:
+
+@cindex redirection to random servers
+When you connect to the Freenode network
+(@code{http://freenode.net/}), you point your IRC client at the
+server @code{irc.freenode.net}. That server will redirect your client
+to a random server on the network, such as @code{zelazny.freenode.net}.
+
+@cindex channel name
+@cindex # starts a channel name
+Once you're connected, you can send messages to all other users
+connected to the same network, and you can join all channels on the same
+network. You might join the @code{#emacs} and the @code{#rcirc}
+channels, for example. (Typically, channel names begin with a hash
+character.)
+
+Once you have joined a channel, anything you type will be broadcast to
+all the other users on the same channel.
+
+@cindex addressing other people
+@cindex other people, addressing them
+@cindex talk to other people
+If you want to address someone specifically, for example as an answer to
+a question, it is customary to prefix the message with the nick followed
+by a colon, like this:
+
+@example
+deego: fsbot rules!
+@end example
+
+@cindex nick completion
+@cindex completion of nicks
+@kindex TAB
+Since this is so common, you can use @key{TAB} to do nick completion.
+
+@node Getting started with rcirc, , Internet Relay Chat, Basics
+@section Getting started with rcirc
+@cindex getting started
+@cindex connecting to a server
+
+@cindex irc command
+Use the command @kbd{M-x irc} to connect using the defaults.
+@xref{Configuration}, if you want to change the defaults.
+
+Use @kbd{C-u M-x irc} if you don't want to use the defaults, eg. if you
+want to connect to a different network, or connect to the same network
+using a different nick. This will prompt you for four things:
+
+@table @asis
+@cindex server, connecting
+@cindex Freenode network
+@item IRC server
+What server do you want to connect to? All the servers in a particular
+network are equivalent. Some networks use a round-robin system where a
+single server redirects new connections to a random server in the
+network. @code{irc.freenode.net} is such a server for the Freenode
+network. Freenode provides the network ``for the Free and Open Source
+Software communities, for not-for-profit organisations and for related
+communities and organizations.''
+
+@cindex port, connecting
+@cindex 6667, default IRC port
+@item IRC port
+All network connections require a port. Just as web servers and clients
+use port 80 per default, IRC uses port 6667 per default. You rarely
+have to use a different port.
+
+@cindex nick, connecting
+@cindex changing nick
+@cindex name changes
+@item IRC nick
+@vindex user-login-name
+Every users needs a handle on-line. You will automatically be assigned
+a slightly different nick if your chosen nick is already in use. If
+your @code{user-login-name} is @code{alex}, and this nick is already
+in use, you might for example get assigned the nick @code{alex`}.
+
+@cindex channels, connecting
+@cindex initial channels
+@cindex startup channels
+@item Channels
+A space separated list of channels you want to join when connecting.
+You don't need to join any channels, if you just want to have one-to-one
+conversations with friends on the same network. If you're new to the
+Freenode network, join @code{#emacs}, the channel about all things
+Emacs, or join @code{#rcirc}, the channel about @code{rcirc}.
+@end table
+
+@cindex server buffer
+When you have answered these questions, @code{rcirc} will create a server
+buffer, which will be named something like @code{*irc.freenode.net*},
+and a channel buffer for each of the channels you wanted to join.
+
+@kindex RET
+@cindex talking
+@cindex communicating
+To talk in a channel, just type in what you want to say in a channel
+buffer, and press @key{RET}.
+
+@kindex C-c C-c
+@cindex multiline messages
+@cindex messages, multiple lines
+@cindex pasting multiple lines
+@cindex edit message before sending
+If you want to paste multiple lines, such as source code, you can use
+@kbd{C-c C-c} to edit your message in a separate buffer. Use @kbd{C-c
+C-c} to finish editing. You still need to press @key{RET} to send it,
+though. Generally, IRC users don't like people pasting more than around
+four lines of code, so use with care.
+
+@node Reference, Hacking and Tweaking, Basics, Top
+@chapter Reference
+@cindex reference
+
+This is the reference section of the manual. It is not complete. For
+complete listings of @code{rcirc} features, use Emacs built-in
+documentation.
+
+@menu
+* rcirc commands::
+* Useful IRC commands::
+* Configuration::
+@end menu
+
+@node rcirc commands, Useful IRC commands, Reference, Reference
+@section rcirc commands
+@cindex rcirc commands
+@cindex commands
+
+@kindex C-h m
+This is a list of commands that you may use in @code{rcirc}. It is not
+complete. For a complete listing, press @kbd{C-h m} in an @code{rcirc}
+buffer.
+
+In addition to using regular Emacs key bindings, you can call them by
+typing them into an @code{rcirc} buffer.
+
+@cindex call commands
+@cindex typing commands
+@cindex commands
+For instance, instead of using the command @kbd{C-c C-j} to join a new
+channel, you may type this in an @code{rcirc} buffer, and press @key{RET}:
+
+@example
+/join #emacs
+@end example
+
+@cindex / starts a command
+@cindex messages starting with a slash disappear
+@cindex disappearing messages if starting with a slash
+@cindex slash hides message
+This is why you cannot start a message with a slash. You will have to
+precede the command with a space, or rewrite your message in order to
+send it to a channel.
+
+@cindex multiple words as parameters
+@cindex string delimiters
+@cindex quotes
+@cindex double-quotes
+Many commands take parameters. IRC commands usually ignore string
+delimiters. Neither quote nor double-quote have special meanings in
+IRC.
+
+@example
+/nick "alex schroeder"
+@end example
+
+This will try to change your nick to @code{"alex}. Usually this will
+fail because the double quote character is not a legal character for
+nicks.
+
+@cindex case insensitive commands
+These commands are case insensitive.
+
+@cindex new command
+@cindex unknown command
+@cindex command unknown
+If a command isn't known by @code{rcirc}, it will simply be sent along to the
+server. There is a list of some useful commands like that in the next
+section.
+
+@table @kbd
+@item C-c C-j
+@kindex C-c C-j
+@cindex /join
+@cindex join channels
+@cindex other channels
+@cindex rooms, joining
+@cindex discussion, joining
+This joins a channel such as @code{#rcirc} or @code{#emacs}. On most
+networks, anybody can create new channels. If you want to talk with
+some friends, for example, all you have to do is agree on a valid
+channel name and join that channel. (Also @code{/join #emacs}.)
+
+@item C-c C-p
+@kindex C-c C-p
+@cindex /part
+@cindex part a channel
+@cindex leave a channel
+@cindex disconnect from a channel
+@cindex stop talking on a channel
+@cindex kill channel buffer
+This leaves the current channel. You can optionally provide a reason
+for parting. When you kill a channel buffer, you automatically part the
+corresponding channel. (Also @code{/part you are too weird!}.)
+
+@item C-c C-r
+@kindex C-c C-r
+@cindex /nick
+@cindex change name
+@cindex nick changing
+@cindex rename yourself
+@cindex other name
+This changes your nick to some other name. Your nick must be unique
+across the network. Most networks don't allow too many nick changes in
+quick succession, and have restrictions on the valid characters in nick
+names. (Also @code{/nick alex-test})
+
+@item C-c C-w
+@kindex C-c C-w
+@cindex /whois
+@cindex who are these people
+@cindex identifying people
+@cindex channels other people are on
+@cindex what channels people are on
+Gives you some basic information about a nick. This often includes what
+other channels people are on. (Also @code{/whois fsbot}.)
+
+@item C-c C-q
+@kindex C-c C-q
+@cindex /query
+@cindex starting a private conversation
+@cindex one-to-one conversation
+@cindex talk privately
+@cindex private conversation
+@cindex contact one person only
+@cindex query a person
+Starts a one-to-one conversation with another person on the same
+network. A new buffer will be created for this conversation. It works
+like a channel with only two members. (Also @code{/query fsbot}.)
+
+@item C-c @key{RET}
+@kindex C-c RET
+@cindex /msg
+@cindex single message
+@cindex message sending
+This sends a single message to a nick. Like with @kbd{C-c C-q}, a new
+buffer is created, where the response from the other party will show
+up. (Also @code{/msg nickserv identify secret}.)
+
+@item C-c C-x
+@kindex C-c C-x
+@cindex /quit
+@cindex quit
+@cindex disconnect
+@cindex kill connection
+@cindex connection end
+@cindex part all channels
+@cindex end connection
+@cindex server buffer killing
+@cindex reason for quitting
+This disconnects from the server and parts all channels. You can
+optionally provide a reason for quitting. When you kill the server
+buffer, you automatically quit the server and part all channels. (Also
+@code{/quit ZZZzzz...}.)
+@end table
+
+Some commands may not have a key binding, but only be available as typed
+commands, such as:
+
+@table @code
+@item /ignore
+@cindex /ignore
+@cindex ignoring other people
+@cindex trolls, ignoring
+@cindex hide some posts
+@cindex idiots online
+This command toggles the ignore status of a nick, if you provide one.
+If you don't provide a nick, the command lists all the nicks you are
+ignoring. All messages by ignored nicks are---you guessed it---ignored.
+Since only ``operators'' can kick people from channels, the
+ignore command is often the only way to deal with some of the more
+obnoxious fellows online. Example: @code{/ignore xah}.
+@end table
+
+@node Useful IRC commands, Configuration, rcirc commands, Reference
+@section Useful IRC commands
+@cindex irc commands
+@cindex commands
+
+As mentioned, if a command isn't known by @code{rcirc}, it will simply be sent
+along to the server. Some such commands are available on nearly all IRC
+servers, such as:
+
+@table @code
+@item /away
+@cindex /away
+@cindex away status
+@cindex pause status
+@cindex unavailable status
+@cindex set away status
+This sets your status as ``being away'' if you provide a reason, or sets
+your status as ``being back'' if you do not. People can use the
+@kbd{C-c C-w} command to check your status. Example: @code{/away food}.
+@end table
+
+@cindex irc resources
+@cindex help about irc
+Typical IRC servers implement many more commands. You can read more
+about the fantastic world of IRC online at
+@uref{http://www.irchelp.org/, the Internet Relay Chat (IRC) help
+archive}.
+
+@node Configuration, , Useful IRC commands, Reference
+@section Configuration
+@cindex configuring rcirc
+
+These are some variables you can change to configure @code{rcirc} to your
+liking.
+
+@table @code
+@item rcirc-default-server
+@vindex rcirc-default-server
+the default server to connect to.
+
+@item rcirc-default-port
+@vindex rcirc-default-port
+the default port to connect to.
+
+@item rcirc-default-nick
+@vindex rcirc-default-nick
+the default nick to use.
+@end table
+
+@example
+(setq rcirc-default-server "irc.mozilla.org"
+ rcirc-default-port 6666
+ rcirc-default-nick "alx")
+@end example
+
+@vindex rcirc-default-user-full-name
+@cindex full name
+@cindex real name
+@cindex surname
+@code{rcirc-default-user-full-name} is used to set your ``real name'' on
+IRC. It defaults to @code{user-full-name}. If you want to hide your
+full name, you might want to set it to some pseudonym.
+
+@example
+(setq rcirc-default-user-full-name "Curious Minds Want To Know")
+@end example
+
+@vindex rcirc-startup-channels-alist
+@cindex channels, configuration
+@cindex initial channels, configuration
+@cindex startup channels, configuration
+@code{rcirc-startup-channels-alist} is the alist of channels to join
+when connecting to a particular network. An alist is a list of lists.
+Each sublist starts with a regular expression that is compared to the
+server address you're connecting to. The remaining sublist items are
+the channels to join.
+
+@example
+(setq rcirc-startup-channels-alist
+ '(("\\.freenode\\.net$" "#emacs" "#rcirc" "#wiki")))
+@end example
+
+Note the subtle problem, here --- IRC clients connect to servers, and
+there is no way of knowing which servers belong to a particular network.
+In the example above we're exploiting a naming convention used by within
+the Freenode network --- all servers within the network have a host in
+the @code{freenode.net} domain.
+
+@vindex rcirc-authinfo
+@cindex authentification
+@cindex identification
+@cindex nickserv
+@cindex login
+@code{rcirc-authinfo} is an alist used to automatically identify
+yourself on networks. Each sublist starts with a regular expression
+that is compared to the server address you're connecting to. The second
+element in the list is a symbol representing the method to use, followed
+by the arguments this method requires.
+
+Here is an example to illustrate how you would set it:
+
+@example
+(setq rcirc-authinfo
+ '(("freenode" nickserv "bob" "p455w0rd")
+ ("freenode" chanserv "bob" "#bobland" "passwd99")
+ ("bitlbee" bitlbee "robert" "sekrit")))
+@end example
+
+And here are the valid method symbols and the arguments they require:
+
+@table @code
+@item nickserv
+@cindex nickserv authentification
+Use this symbol if you need to identify yourself as follows when
+connecting to a network: @code{/msg nickserv identify secret}. The
+necessary arguments are the nickname you want to use this for, and the
+password to use.
+
+Before you can use this method, you will have to register your nick and
+pick a password for it. Contact @code{nickserv} and check out the
+details. (Using @code{/msg nickserv help}, for example.)
+
+@item chanserv
+@cindex chanserv authentification
+Use this symbol if you need to identify yourself as follows if you want
+to join a particular channel: @code{/msg chanserv identify #underground
+secret}. The necessary arguments are the nickname and channel you want
+to use this for, and the password to use.
+
+Before you can use this method, a channel contact must tell you about
+the password to use. Contact @code{chanserv} and check out the details.
+(Using @code{/msg chanserv help}, for example.)
+
+@item bitlbee
+@cindex bitlbee authentification
+Use this symbol if you need to identify yourself in the Bitlbee channel
+as follows: @code{identify secret}. The necessary arguments are the
+nickname you want to use this for, and the password to use.
+
+@cindex gateway to other IM services
+@cindex instant messaging, other services
+@cindex Jabber
+@cindex AIM
+@cindex ICQ
+@cindex MSN
+@cindex Yahoo!
+Bitlbee acts like an IRC server, but in fact it is a gateway to a lot of
+other instant messaging services. You can either install Bitlbee
+locally or use a public Bitlbee server. There, you need to create an
+account with a password. This is the nick and password you need to
+provide for the bitlbee authentification method.
+
+Later, you will tell Bitlbee about your accounts and passwords on all
+the other instant messaging services, and Bitlbee will log you in. All
+@code{rcirc} needs to know, is the login to your Bitlbee account. Don't
+confuse the Bitlbee account with all the other accounts.
+@end table
+
+@kindex C-c C-SPC
+@vindex rcirc-track-minor-mode
+@cindex switching channels
+@cindex tracking activity
+@cindex active channel
+@cindex abbreviated channel names
+@cindex modeline tracks activity
+Most people want a notification when something is said on a channel they
+have joined, particularly if they have been addressed directly. There
+is a global minor mode that will do this kind of tracking for you. All
+you need to do is switch it on using @kbd{M-x rcirc-track-minor-mode}.
+To make this permanent, add the following to your init file:
+
+@example
+(rcirc-track-minor-mode 1)
+@end example
+
+When other people say things in buffers that are currently buried (no
+window is showing them), the mode line will now show you the abbreviated
+channel or nick name. Use @kbd{C-c C-@key{SPC}} to switch to these
+buffers.
+
+@vindex rcirc-mode-hook
+If you prefer not to load @code{rcirc} immediately, you can delay the
+activation of this mode:
+
+@example
+(add-hook 'rcirc-mode-hook
+ (lambda ()
+ (rcirc-track-minor-mode 1)))
+@end example
+
+@node Hacking and Tweaking, GNU Free Documentation License, Reference, Top
+@chapter Hacking and Tweaking
+@cindex hacking and tweaking
+
+Here are some examples of stuff you can do to configure @code{rcirc}.
+
+@menu
+* Skipping /away messages using handlers::
+* Using fly spell mode::
+* Scrolling conservatively::
+* Changing the time stamp format::
+* Defining a new command::
+* Reconnecting after you have lost the connection::
+@end menu
+
+@node Skipping /away messages using handlers, Using fly spell mode, Hacking and Tweaking, Hacking and Tweaking
+@section Skipping @code{/away} messages using handlers
+@cindex /away messages
+
+@cindex handlers
+@cindex status codes
+The IRC protocol specifies how certain events are signaled from server
+to client. These events have numbers and are dealt with using so-called
+handlers. You can override existing handlers by exploiting the naming
+convention adopted for @code{rcirc}.
+
+Here's how to stop @code{rcirc} from printing @code{/away} messages.
+Since @code{rcirc} doesn't define a 301 handler, you don't need to
+require @code{rcirc} before defining the handler:
+
+@example
+(defun rcirc-handler-301 (process cmd sender args)
+ "/away message handler.")
+@end example
+
+@node Using fly spell mode, Scrolling conservatively, Skipping /away messages using handlers, Hacking and Tweaking
+@section Using fly spell mode
+@cindex fly spell
+@cindex spelling
+@cindex spell-checking as you type
+@cindex automatic spelling
+@vindex rcirc-mode-hook
+
+The following code activates Fly Spell Mode
+for @code{rcirc} buffers:
+
+@example
+(add-hook 'rcirc-mode-hook (lambda ()
+ (flyspell-mode 1)))
+@end example
+
+@xref{Spelling, , Flyspell mode, emacs, The GNU Emacs Manual},
+for details.
+
+@node Scrolling conservatively, Changing the time stamp format, Using fly spell mode, Hacking and Tweaking
+@section Scrolling conservatively
+@cindex input line
+@cindex scrolling
+@vindex scroll-conservatively
+@vindex rcirc-mode-hook
+
+IRC buffers are constantly growing. If you want to see as much as
+possible at all times, you would want the prompt at the bottom of the
+window when possible. The following snippet uses a local value for
+@code{scroll-conservatively} to achieve this:
+
+@example
+(add-hook 'rcirc-mode-hook
+ (lambda ()
+ (set (make-local-variable 'scroll-conservatively)
+ 8192)))
+@end example
+
+@xref{Scrolling, , Scrolling conservatively, emacs, The GNU Emacs
+Manual}, for details.
+
+@node Changing the time stamp format, Defining a new command, Scrolling conservatively, Hacking and Tweaking
+@section Changing the time stamp format
+@cindex time stamp
+@cindex date time
+@cindex format time stamp
+@vindex rcirc-time-format
+
+@code{rcirc-time-format} is the format used for the time stamp. Here's
+how to include the date in the time stamp:
+
+@example
+(setq rcirc-time-format "%Y-%m-%d %H:%M ")
+@end example
+
+@node Defining a new command, Reconnecting after you have lost the connection, Changing the time stamp format, Hacking and Tweaking
+@section Defining a new command
+@cindex defining commands
+@cindex commands, defining
+@cindex new commands, defining
+
+Here's a simple new command, @code{/sv}. With it, you can boast about
+your IRC client. It shows how you can use @code{defun-rcirc-command} to
+define new commands.
+
+We're waiting for the definition of this command until @code{rcirc} is loaded
+because @code{defun-rcirc-command} is not yet available, and without
+@code{rcirc} loaded, the command wouldn't do us much good anyway.
+
+@smallexample
+(eval-after-load 'rcirc
+ '(defun-rcirc-command sv (arg)
+ "Boast about rcirc."
+ (interactive "i")
+ (rcirc-send-message process target
+ (concat "I use " rcirc-id-string))))
+@end smallexample
+
+@node Reconnecting after you have lost the connection, , Defining a new command, Hacking and Tweaking
+@section Reconnecting after you have lost the connection
+@cindex reconnecting
+@cindex disconnecting servers, reconnecting
+
+If you're chatting from a laptop, then you might be familiar with this
+problem: When your laptop falls asleep and wakes up later, your IRC
+client doesn't realise that it has been disconnected. It takes several
+minutes until the client decides that the connection has in fact been
+lost. The simple solution is to use @kbd{M-x rcirc}. The problem is
+that this opens an @emph{additional} connection, so you'll have two
+copies of every channel buffer --- one dead and one live.
+
+The real answer, therefore, is a @code{/reconnect} command:
+
+@smallexample
+(eval-after-load 'rcirc
+ '(defun-rcirc-command reconnect (arg)
+ "Reconnect the server process."
+ (interactive "i")
+ (unless process
+ (error "There's no process for this target"))
+ (let* ((server (car (process-contact process)))
+ (port (process-contact process :service))
+ (nick (rcirc-nick process))
+ channels query-buffers)
+ (dolist (buf (buffer-list))
+ (with-current-buffer buf
+ (when (eq process (rcirc-buffer-process))
+ (remove-hook 'change-major-mode-hook
+ 'rcirc-change-major-mode-hook)
+ (if (rcirc-channel-p rcirc-target)
+ (setq channels (cons rcirc-target channels))
+ (setq query-buffers (cons buf query-buffers))))))
+ (delete-process process)
+ (rcirc-connect server port nick
+ rcirc-default-user-name
+ rcirc-default-user-full-name
+ channels))))
+@end smallexample
+
+@node GNU Free Documentation License, Key Index, Hacking and Tweaking, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+
+@node Key Index, Variable Index, GNU Free Documentation License, Top
+@unnumbered Key Index
+@printindex ky
+
+@node Variable Index, Index, Key Index, Top
+@unnumbered Variable Index
+@printindex vr
+
+@node Index, , Variable Index, Top
+@unnumbered Index
+@printindex cp
+
+@bye
+
+@ignore
+ arch-tag: 2589e562-3843-4ffc-8c2f-477cbad57c01
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename ../info/reftex
+@settitle RefTeX User Manual
+@synindex ky cp
+@syncodeindex vr cp
+@syncodeindex fn cp
+
+@c Version and Contact Info
+@set VERSION 4.31
+@set EDITION 4.31
+@set DATE February 2006
+@set AUCTEXSITE @uref{http://www.gnu.org/software/auctex/,AUCTeX distribution site}
+@set MAINTAINERSITE @uref{http://www.gnu.org/software/auctex/reftex.html,Ref@TeX{} web page}
+@set MAINTAINERCONTACT @uref{mailto:auctex-devel@@gnu.org,contact the maintainers}
+@set MAINTAINER the AUC@TeX{} project
+@set SUPPORTADDRESS AUC@TeX{} user mailing list (@email{auctex@@gnu.org})
+@set DEVELADDRESS AUC@TeX{} developer mailing list (@email{auctex-devel@@gnu.org})
+@set BUGADDRESS AUC@TeX{} bug mailing list (@email{bug-auctex@@gnu.org})
+@set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site}
+@c %**end of header
+
+@copying
+This file documents @b{Ref@TeX{}}, a package to do labels, references,
+citations and indices for LaTeX documents with Emacs.
+
+This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for
+@b{Ref@TeX{}} @value{VERSION}
+
+Copyright @copyright{} 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* RefTeX: (reftex). Emacs support for LaTeX cross-references and citations.
+@end direntry
+
+@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
+
+@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
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnottex
+@node Top,,,(dir)
+
+@b{Ref@TeX{}} is a package for managing Labels, References,
+Citations and index entries with GNU Emacs.
+
+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.
+
+@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.
+* Key Bindings:: The default key bindings.
+* 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.
+* GNU Free Documentation License:: The license for this documentation.
+
+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.
+* BibTeX Database Subsets:: Extract parts of a big database.
+
+Index Support
+
+* Creating Index Entries:: Macros and completion of entries.
+* The Index Phrases File:: A special file for global indexing.
+* Displaying and Editing the Index:: The index editor.
+* Builtin Index Macros:: The index macros RefTeX knows about.
+* Defining Index Macros:: ... and macros it doesn't.
+
+The Index Phrases File
+
+* Collecting Phrases:: Collecting from document or external.
+* Consistency Checks:: Check for duplicates etc.
+* Global Indexing:: The interactive indexing process.
+
+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 ifnottex
+
+@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.
+
+@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 @value{XEMACSFTP}. See the XEmacs 21.x
+documentation on package installation for details.
+
+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.
+
+@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:
+
+@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.
+
+@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}).
+
+@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)
+@end itemize
+@noindent
+Which labels are created how is configurable with the variable
+@code{reftex-insert-label-flags}.
+
+@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.
+@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).
+
+@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.
+
+@itemize @bullet
+@item
+@b{Creating Index Entries}@*
+To index the current selection or the word at point, type @kbd{C-c /}
+(@code{reftex-index-selection-or-word}). The default macro
+@code{reftex-index-default-macro} will be used. For a more complex entry
+type @kbd{C-c <} (@code{reftex-index}), select any of the index macros
+and enter the arguments with completion.
+
+@item
+@b{The Index Phrases File (Delayed Indexing)}@*
+Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add
+the current word or selection to a special @emph{index phrase file}.
+@b{Ref@TeX{}} can later search the document for occurrences of these
+phrases and let you interactively index the matches.
+
+@item
+@b{Displaying and Editing 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.
+@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. @*
+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.
+
+@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}).
+
+@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.
+
+@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.
+
+@item
+@b{Useful Settings}@*
+To integrate RefTeX 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
+@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{}}.
+
+@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, of if you are curious what else might be
+available. 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.
+@end enumerate
+
+@node Table of Contents, Labels and References, Introduction, Top
+@chapter Table of Contents
+@cindex @file{*toc*} buffer
+@cindex Structure editing
+@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.
+
+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.
+
+@kindex ?
+Here is a list of special commands in the @file{*toc*} buffer. A
+summary of this information is always available by pressing
+@kbd{?}.
+
+@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.
+
+@item C-c C-p
+Goto previous section heading.
+
+@item N z
+Jump to section N, using the prefix arg. For example, @kbd{3 z} jumps
+to section 3.
+
+@tablesubheading{Access to document locations}
+@item @key{SPC}
+Show the corresponding location in another window. This command does
+@emph{not} select that other window.
+
+@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.
+
+@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)}.
+
+@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}.
+
+@item .
+Show calling point in another window. This is the point from where
+@code{reftex-toc} was last called.
+
+@page
+@tablesubheading{Promotion and Demotion}
+
+@item <
+Promote the current section. This will convert @code{\section} to
+@code{\chapter}, @code{\subsection} to @code{\section} etc. If there is
+an active region, all sections in the region will be promoted, including
+the one at point. To avoid mistakes, @b{Ref@TeX{}} requires a fresh
+document scan before executing this command - if necessary, it will
+automatically do this scan and ask the user to repeat the promotion
+command.
+
+@item >
+Demote the current section. This is the opposite of promotion. It will
+convert @code{\chapter} to @code{\section} etc. If there is an active
+region, all sections in the region will be demoted, including the one at
+point.
+
+@item M-%
+Rename the label at point. While generally not recommended, this can be
+useful when a package like @file{fancyref} is used where the label
+prefix determines the wording of a reference. After a
+promotion/demotion it may be necessary to change a few labels from
+@samp{sec:xyz} to @samp{cha:xyz} or vice versa. This command can be
+used to do this - it launches a query replace to rename the definition
+and all references of a label.
+
+@tablesubheading{Exiting}
+@item q
+Hide the @file{*toc*} buffer, return to the position where
+@code{reftex-toc} was last called.
+
+@item k
+Kill the @file{*toc*} buffer, return to the position where
+@code{reftex-toc} was last called.
+
+@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 t
+@vindex reftex-toc-max-level
+Change the maximum level of toc entries displayed in the @file{*toc*}
+buffer. Without prefix arg, all levels will be included. With prefix
+arg (e.g @kbd{3 t}), ignore all toc entries with level greater than
+@var{arg} (3 in this case). Chapters are level 1, sections are level 2.
+The mode line @samp{T<>} indicator shows the current value. The default
+depth can be configured with the variable
+@code{reftex-toc-max-level}.
+
+@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}.
+
+@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.
+
+@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.
+
+@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}.
+
+@tablesubheading{Updating the buffer}
+
+@item g
+Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the
+document.
+
+@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-@code{nil}, rescan only the file this
+location is defined in, not the entire document.
+
+@item C-u r
+Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*}
+buffer.
+
+@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.
+
+
+@tablesubheading{Automatic recentering}
+
+@item d
+Toggle the display of a dedicated frame displaying just the @file{*toc*}
+buffer. Follow mode and visiting locations will not work that frame,
+but automatic recentering will make this frame always show your current
+editing location in the document (see below).
+
+@item a
+Toggle the automatic recentering of the @file{*toc*} buffer. When this
+option is on, moving around in the document will cause the @file{*toc*}
+to always highlight the current section. By default, this option is
+active while the dedicated @file{*TOC*} frame exists. See also the
+variable @code{reftex-auto-recenter-toc}.
+
+@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.
+
+@findex reftex-toc-recenter
+@vindex reftex-auto-recenter-toc
+@vindex reftex-idle-time
+@cindex @file{*toc*} buffer, recentering
+@cindex Table of contents buffer, recentering
+@kindex C-c -
+If you call @code{reftex-toc} while the @file{*toc*} buffer already
+exists, the cursor will immediately jump to the right place, i.e. the
+section from which @code{reftex-toc} was called will be highlighted.
+The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay
+the @file{*toc*} buffer and highlight the correct line without actually
+selecting the @file{*toc*} window. This can be useful to quickly find
+out where in the document you currently are. You can also automate this
+by asking RefTeX to keep track of your current editing position in the
+TOC. The TOC window will then be updated whenever you stop typing for
+more than @code{reftex-idle-time} seconds. By default this works only
+with the dedicated @file{*TOC*} frame. But you can also force automatic
+recentering of the TOC window on the current frame with
+@lisp
+(setq reftex-auto-recenter-toc t)
+@end lisp
+
+
+@cindex Sectioning commands
+@cindex KOMA-Script, LaTeX classes
+@cindex LaTeX classes, KOMA-Script
+@cindex TOC entries for environments
+@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}. It is also possible to add certain LaTeX
+environments to the table of contents. This is probably only useful for
+theorem-like environments. @xref{Defining Label Environments}, for an
+example.
+
+@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.
+
+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.
+
+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.
+
+@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.
+
+@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
+invalid in labels. @b{Ref@TeX{}} will therefore strip the accent from
+accented Latin-1 characters and remove everything else which is not
+valid 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.
+
+@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}).
+
+@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.
+@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)}).
+
+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
+
+@vindex reftex-trust-label-prefix
+@b{Ref@TeX{}} scans the document in order to find all labels. To make
+referencing labels easier, it assigns to each label a category, the
+@emph{label type} (for example section, table, figure, equation, etc.).
+In order to determine the label type, RefTeX parses around each label
+to see in what kind of environments it is located. You can speed up
+the parsing by using type-specific prefixes for labels and configuring
+the variable @code{reftex-trust-label-prefix}.
+
+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.
+
+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.
+
+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.
+
+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{?}.
+
+
+
+@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.
+
+@item C-c C-n
+Goto next section heading.
+
+@item C-c C-p
+Goto previous section heading.
+
+@item N z
+Jump to section N, using the prefix arg. For example @kbd{3 z} jumps to
+section 3.
+
+@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.
+
+@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}.
+
+@item .
+Show insertion point in another window. This is the point from where you
+called @code{reftex-reference}.
+
+@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.
+
+@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)}.
+
+@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.
+
+@item l
+Use the last referenced label(s) again. This is equivalent to moving to
+that label and pressing @key{RET}.
+
+@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.
+
+@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.
+
+@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.
+
+@item F
+Toggle the display of the file borders of a multifile document in the
+selection buffer.
+
+@item t
+Toggle the display of the table of contents in the selection buffer.
+With prefix @var{arg}, change the maximum level of toc entries displayed
+to @var{arg}. Chapters are level 1, section are level 2.
+
+@item #
+Toggle the display of a label counter in the selection buffer.
+
+@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.
+
+@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}).
+
+@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).
+
+@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.
+
+@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}).
+
+@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.
+
+@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:
+
+@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)
+@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)
+@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})
+@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}).
+
+@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}).
+
+@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}
+
+@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.") -2)
+ ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "th.") -3)))
+@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.
+
+@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 RefTeX to automatically create labels when a new environment
+is inserted into a buffer. Additionally, the following needs to be
+added to one's .emacs file before AUCTeX will automatically create
+labels for the new environments.
+
+@lisp
+(add-hook 'LaTeX-mode-hook
+ (lambda ()
+ (LaTeX-add-environments
+ '("axiom" LaTeX-env-label)
+ '("theorem" LaTeX-env-label))))
+@end lisp
+
+
+@noindent
+The @samp{~\ref@{%s@}} is a format string indicating how to insert
+references to these labels.
+
+@noindent
+The next item indicates how to grab context of the label definition.
+@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.
+@item
+@code{nil} means to use the text right after the label definition.
+@item
+For more complex ways of getting context, see the variable
+@code{reftex-label-alist} (@ref{Options (Defining Label
+Environments)}).
+@end itemize
+
+The following list of strings is 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.
+
+The final item in each entry is the level at which the environment
+should produce entries in the table of context buffer. If the number is
+positive, the environment will produce numbered entries (like
+@code{\section}), if it is negative the entries will be unnumbered (like
+@code{\section*}). Use this only for environments which structure the
+document similar to sectioning commands. For everything else, omit the
+item.
+
+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:
+
+@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]
+ [X] Make TOC entry : [Value Menu] Level: -2
+[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]
+ [X] Make TOC entry : [Value Menu] Level: -3
+@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)}).
+
+
+@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.
+
+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]
+ [ ] Make TOC entry : [Value Menu] No entry
+@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.
+
+@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.
+
+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.
+
+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]
+ [ ] Make TOC entry : [Value Menu] No entry
+@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.
+
+@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.
+
+@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.
+
+@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.
+
+@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 occur inside an equation environment.
+Here is the setup:
+
+@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.
+
+@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.") -2)
+ ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th.") -3)
+ ("\\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 for more than @code{reftex-idle-time} seconds 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.
+
+@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:
+
+@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.
+
+@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.
+
+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}).
+
+@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}).
+
+@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}).
+
+@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.
+
+@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.
+* BibTeX Database Subsets:: Extract parts of a big database.
+@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}).
+
+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. RefTeX also offers a default when prompting for a
+regular expression. This default is the word before the cursor or the
+word before the current @samp{\cite} command. Sometimes this may be a
+good search key.
+
+@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.
+
+@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{?}.
+
+@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.
+
+@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.
+
+@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.
+
+@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)}.
+
+@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.
+
+@item A
+Accept all (marked) entries in the selection buffer and create a
+separate @code{\cite} macro for each of it.
+
+@item e
+Create a new BibTeX database file which contains all @i{marked} entries
+in the selection buffer. If no entries are marked, all entries are
+selected.
+
+@item E
+Create a new BibTeX database file which contains all @i{unmarked}
+entries in the selection buffer. If no entries are marked, all entries
+are selected.
+
+@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}.
+
+@tablesubheading{Exiting}
+@item q
+Exit the selection process without inserting a citation into the
+buffer.
+
+@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}).
+
+@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.
+
+@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.
+
+@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 Citation styles, @code{jurabib}
+@cindex @code{natbib}, citation style
+@cindex @code{harvard}, citation style
+@cindex @code{chicago}, citation style
+@cindex @code{jurabib}, 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},
+@code{jurabib}) 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
+
+@vindex reftex-cite-prompt-optional-args
+If cite formats contain empty paris of square brackets, RefTeX can
+will prompt for values of these optional arguments if you call the
+@code{reftex-citation} command with a @kbd{C-u} prefix.
+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)}).
+
+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.
+
+@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 for more than @code{reftex-idle-time} seconds 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}.
+
+@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, BibTeX Database Subsets, 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}.
+
+@lisp
+(add-hook 'mail-setup-hook
+ (lambda () (define-key mail-mode-map "\C-c["
+ (lambda ()
+ (interactive)
+ (let ((reftex-cite-format 'locally))
+ (reftex-citation))))))
+@end lisp
+
+@node BibTeX Database Subsets, , Citations Outside LaTeX, Citations
+@section Database Subsets
+@cindex BibTeX database subsets
+@findex reftex-create-bibtex-file
+
+@b{Ref@TeX{}} offers two ways to create a new BibTeX database file.
+
+The first option produces a file which contains only the entries
+actually referenced in the current document. This can be useful if
+the database in only meant for a single document and you want to clean
+it of old and unused ballast. It can also be useful while writing a
+document together with collaborators, in order to avoid sending around
+the entire (possibly very large) database. To create the file, use
+@kbd{M-x reftex-create-bibtex-file}, also available from the menu
+under @code{Ref->Global Actions->Create Bibtex File}. The command will
+prompt for a BibTeX file name and write the extracted entries to that
+file.
+
+The second option makes use of the selection process started by the
+command @kbd{C-c [} (@pxref{Creating Citations}). This command uses a
+regular expression to select entries, and lists them in a formatted
+selection buffer. After pressing the @kbd{e} key (mnemonics: Export),
+the command will prompt for the name of a new BibTeX file and write
+the selected entries to that file. You can also first mark some
+entries in the selection buffer with the @kbd{m} key and then export
+either the @i{marked} entries (with the @kbd{e} key) or the
+@i{unmarked} entries (with the @kbd{E} key).
+
+@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}.
+
+Indexing is a very difficult task. It must follow strict conventions to
+make the index consistent and complete. There are basically two
+approaches one can follow, and both have their merits.
+
+@enumerate
+@item
+Part of the indexing should already be done with the markup. The
+document structure should be reflected in the index, so when starting
+new sections, the basic topics of the section should be indexed. If the
+document contains definitions, theorems or the like, these should all
+correspond to appropriate index entries. This part of the index can
+very well be developed along with the document. Often it is worthwhile
+to define special purpose macros which define an item and at the same
+time make an index entry, possibly with special formatting to make the
+reference page in the index bold or underlined. 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}).
+
+@item
+The rest of the index is often just a collection of where in the
+document certain words or phrases are being used. This part is
+difficult to develop along with the document, because consistent entries
+for each occurrence are needed and are best selected when the document
+is ready. @b{Ref@TeX{}} supports this with an @emph{index phrases file}
+which collects phrases and helps indexing the phrases globally.
+@end enumerate
+
+Before you start, 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
+
+@menu
+* Creating Index Entries:: Macros and completion of entries.
+* The Index Phrases File:: A special file for global indexing.
+* Displaying and Editing the Index:: The index editor.
+* Builtin Index Macros:: The index macros RefTeX knows about.
+* Defining Index Macros:: ... and macros it doesn't.
+@end menu
+
+@node Creating Index Entries, The Index Phrases File, , Index Support
+@section Creating Index Entries
+@cindex Creating index entries
+@cindex Index entries, creating
+@kindex C-c <
+@findex reftex-index
+@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.
+
+@node The Index Phrases File, Displaying and Editing the Index, Creating Index Entries, Index Support
+@section The Index Phrases File
+@cindex Index phrase file
+@cindex Phrase file
+@kindex C-c |
+@findex reftex-index-visit-phrases-buffer
+@cindex Macro definition lines, in phrase buffer
+
+@b{Ref@TeX{}} maintains a file in which phrases can be collected for
+later indexing. The file is located in the same directory as the master
+file of the document and has the extension @file{.rip} (@b{R}eftex
+@b{I}ndex @b{P}hrases). You can create or visit the file with @kbd{C-c
+|} (@code{reftex-index-visit-phrases-buffer}). If the file is empty it
+is initialized by inserting a file header which contains the definition
+of the available index macros. This list is initialized from
+@code{reftex-index-macros} (@pxref{Defining Index Macros}). You can
+edit the header as needed, but if you define new LaTeX indexing macros,
+don't forget to add them to @code{reftex-index-macros} as well. Here is
+a phrase file header example:
+
+@example
+% -*- mode: reftex-index-phrases -*-
+% Key Macro Format Repeat
+%----------------------------------------------------------
+>>>INDEX_MACRO_DEFINITION: i \index@{%s@} t
+>>>INDEX_MACRO_DEFINITION: I \index*@{%s@} nil
+>>>INDEX_MACRO_DEFINITION: g \glossary@{%s@} t
+>>>INDEX_MACRO_DEFINITION: n \index*[name]@{%s@} nil
+%----------------------------------------------------------
+@end example
+
+The macro definition lines consist of a unique letter identifying a
+macro, a format string and the @var{repeat} flag, all separated by
+@key{TAB}. The format string shows how the macro is to be applied, the
+@samp{%s} will be replaced with the index entry. The repeat flag
+indicates if @var{word} is indexed by the macro as
+@samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as
+@samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}). In the
+above example it is assumed that the macro @code{\index*@{@var{word}@}}
+already typesets its argument in the text, so that it is unnecessary to
+repeat @var{word} outside the macro.
+
+@menu
+* Collecting Phrases:: Collecting from document or external.
+* Consistency Checks:: Check for duplicates etc.
+* Global Indexing:: The interactive indexing process.
+@end menu
+
+@node Collecting Phrases, Consistency Checks, , The Index Phrases File
+@subsection Collecting Phrases
+@cindex Collecting index phrases
+@cindex Index phrases, collection
+@cindex Phrases, collecting
+
+Phrases for indexing can be collected while writing the document. The
+command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word})
+copies the current selection (if active) or the word near point into the
+phrases buffer. It then selects this buffer, so that the phrase line
+can be edited. To return to the LaTeX document, press @kbd{C-c C-c}
+(@code{reftex-index-phrases-save-and-return}).
+
+You can also prepare the list of index phrases in a different way and
+copy it into the phrases file. For example you might want to start from
+a word list of the document and remove all words which should not be
+indexed.
+
+The phrase lines in the phrase buffer must have a specific format.
+@b{Ref@TeX{}} will use font-lock to indicate if a line has the proper
+format. A phrase line looks like this:
+
+@example
+[@var{key}] <TABs> @var{phrase} [<TABs> @var{arg}[&&@var{arg}]... [ || @var{arg}]...]
+@end example
+
+@code{<TABs>} stands for white space containing at least one @key{TAB}.
+@var{key} must be at the start of the line and is the character
+identifying one of the macros defined in the file header. It is
+optional - when omitted, the first macro definition line in the file
+will be used for this phrase. The @var{phrase} is the phrase to be
+searched for when indexing. It may contain several words separated by
+spaces. By default the search phrase is also the text entered as
+argument of the index macro. If you want the index entry to be
+different from the search phrase, enter another @key{TAB} and the index
+argument @var{arg}. If you want to have each match produce several
+index entries, separate the different index arguments with @samp{ &&
+}@footnote{@samp{&&} with optional spaces, see
+@code{reftex-index-phrases-logical-and-regexp}.}. If you want to be
+able to choose at each match between several different index arguments,
+separate them with @samp{ || }@footnote{@samp{||} with optional spaces,
+see @code{reftex-index-phrases-logical-or-regexp}.}. Here is an
+example:
+
+@example
+%--------------------------------------------------------------------
+I Sun
+i Planet Planets
+i Vega Stars!Vega
+ Jupiter Planets!Jupiter
+i Mars Planets!Mars || Gods!Mars || Chocolate Bars!Mars
+i Pluto Planets!Pluto && Kuiper Belt Objects!Pluto
+@end example
+
+
+So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while
+@samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}.
+@samp{Vega} will be indexed as a subitem of @samp{Stars}. The
+@samp{Jupiter} line will also use the @samp{i} macro as it was the first
+macro definition in the file header (see above example). At each
+occurrence of @samp{Mars} you will be able choose between indexing it as
+a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}.
+Finally, every occurrence of @samp{Pluto} will be indexed as
+@samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto}
+and will therefore create two different index entries.
+
+@node Consistency Checks, Global Indexing, Collecting Phrases, The Index Phrases File
+@subsection Consistency Checks
+@cindex Index phrases, consistency checks
+@cindex Phrases, consistency checks
+@cindex Consistency check for index phrases
+
+@kindex C-c C-s
+Before indexing the phrases in the phrases buffer, they should be
+checked carefully for consistency. A first step is to sort the phrases
+alphabetically - this is done with the command @kbd{C-c C-s}
+(@code{reftex-index-sort-phrases}). It will sort all phrases in the
+buffer alphabetically by search phrase. If you want to group certain
+phrases and only sort within the groups, insert empty lines between the
+groups. Sorting will only change the sequence of phrases within each
+group (see the variable @code{reftex-index-phrases-sort-in-blocks}).
+
+@kindex C-c C-i
+A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info})
+which lists information about the phrase at point, including an example
+of how the index entry will look like and the number of expected matches
+in the document.
+
+@kindex C-c C-t
+Another important check is to find out if there are double or
+overlapping entries in the buffer. For example if you are first
+searching and indexing @samp{Mars} and then @samp{Planet Mars}, the
+second phrase will not match because of the index macro inserted before
+@samp{Mars} earlier. The command @kbd{C-c C-t}
+(@code{reftex-index-find-next-conflict-phrase}) finds the next phrase in
+the buffer which is either duplicate or a subphrase of another phrase.
+In order to check the whole buffer like this, start at the beginning and
+execute this command repeatedly.
+
+@node Global Indexing, , Consistency Checks, The Index Phrases File
+@subsection Global Indexing
+@cindex Global indexing
+@cindex Indexing, global
+@cindex Indexing, from @file{phrases} buffer
+
+Once the index phrases have been collected and organized, you are set
+for global indexing. I recommend to do this only on an otherwise
+finished document. Global indexing starts from the phrases buffer.
+There are several commands which start indexing: @kbd{C-c C-x} acts on
+the current phrase line, @kbd{C-c C-r} on all lines in the current
+region and @kbd{C-c C-a} on all phrase lines in the buffer. It is
+probably good to do indexing in small chunks since your concentration
+may not last long enough to do everything in one go.
+
+@b{Ref@TeX{}} will start at the first phrase line and search the phrase
+globally in the whole document. At each match it will stop, compute the
+replacement string and offer you the following choices@footnote{Windows
+users: Restrict yourself to the described keys during indexing. Pressing
+@key{Help} at the indexing prompt can apparently hang Emacs.}:
+
+@table @kbd
+@item y
+Replace this match with the proposed string.
+@item n
+Skip this match.
+@item !
+Replace this and all further matches in this file.
+@item q
+Skip this match, start with next file.
+@item Q
+Skip this match, start with next phrase.
+@item o
+Select a different indexing macro for this match.
+@item 1-9
+Select one of multiple index keys (those separated with @samp{||}).
+@item e
+Edit the replacement text.
+@item C-r
+Recursive edit. Use @kbd{C-M-c} to return to the indexing process.
+@item s
+Save this buffer and ask again about the current match.
+@item S
+Save all document buffers and ask again about the current match.
+@item C-g
+Abort the indexing process.
+@end table
+
+The @samp{Find and Index in Document} menu in the phrases buffer also
+lists a few options for the indexing process. The options have
+associated customization variables to set the defaults (@pxref{Options
+(Index Support)}). Here is a short explanation of what the options do:
+
+@table @i
+@item Match Whole Words
+When searching for index phrases, make sure whole words are matched.
+This should probably always be on.
+@item Case Sensitive Search
+Search case sensitively for phrases. I recommend to have this setting
+off, in order to match the capitalized words at the beginning of a
+sentence, and even typos. You can always say @emph{no} at a match you
+do not like.
+@item Wrap Long Lines
+Inserting index macros increases the line length. Turn this option on
+to allow @b{Ref@TeX{}} to wrap long lines.
+@item Skip Indexed Matches
+When this is on, @b{Ref@TeX{}} will at each match try to figure out if
+this match is already indexed. A match is considered indexed if it is
+either the argument of an index macro, or if an index macro is directly
+(without whitespace separation) before or after the match. Index macros
+are those configured in @code{reftex-index-macros}. Intended for
+re-indexing a documents after changes have been made.
+@end table
+
+Even though indexing should be the last thing you do to a document, you
+are bound to make changes afterwards. Indexing then has to be applied
+to the changed regions. The command
+@code{reftex-index-phrases-apply-to-region} is designed for this
+purpose. When called from a LaTeX document with active region, it will
+apply @code{reftex-index-all-phrases} to the current region.
+
+@node Displaying and Editing the Index, Builtin Index Macros, The Index Phrases File, 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.
+
+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 by pressing the
+@kbd{<} and @kbd{>} keys.
+
+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.
+
+@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{?}.
+
+@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.
+@item n
+Go to next entry.
+@item p
+Go to previous entry.
+
+@tablesubheading{Access to document locations}
+@item @key{SPC}
+Show the place in the document where this index entry is defined.
+
+@item @key{TAB}
+Go to the definition of the current index entry in another
+window.
+
+@item @key{RET}
+Go to the definition of the current index entry and hide the
+@file{*Index*} buffer window.
+
+@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}.
+
+@tablesubheading{Entry editing}
+@item e
+Edit the current index entry. In the minibuffer, you can edit the
+index macro which defines this entry.
+
+@item C-k
+Kill the index entry. Currently not implemented because I don't know
+how to implement an @code{undo} function for this.
+
+@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.
+
+@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.
+
+@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.
+
+@item (
+Toggle the beginning of page range property @samp{|(} of the
+entry.
+
+@item )
+Toggle the end of page range property @samp{|)} of the entry.
+
+@item _
+Make the current entry a subentry. This command will prompt for the
+superordinate entry and insert it.
+
+@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}).
+
+@tablesubheading{Exiting}
+@item q
+Hide the @file{*Index*} buffer.
+
+@item k
+Kill the @file{*Index*} buffer.
+
+@item C-c =
+Switch to the Table of Contents buffer of this document.
+
+@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}.
+
+@item @}
+Restrict the index to a single document section. The corresponding
+section number will be displayed in the @code{R<>} indicator in the
+mode line and in the header of the @file{*Index*} buffer.
+
+@item @{
+Widen the index to contain all entries of the document.
+
+@item <
+When the index is currently restricted, move the restriction to the
+previous section.
+
+@item >
+When the index is currently restricted, move the restriction to the
+next section.
+
+@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.
+
+@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-@code{nil}, rescan only the file this
+location is defined in, not the entire document.
+
+@item C-u r
+Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*}
+buffer.
+
+@item s
+Switch to a different index (for documents with multiple
+indices).
+@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 @code{\index}
+in 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 nil)
+ ("\\nindex@{*@}" "name" ?n "" nil nil)
+ ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t)))
+@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.
+
+The next entry can be a hook function to exclude certain matches, it
+almost always can be @code{nil}.
+
+The final element in the list indicates if the text being indexed needs
+to be repeated outside the macro. For the normal index macros, this
+should be @code{t}. Only if the macro typesets the entry in the text
+(like @code{\ix} and @code{\nindex} in the example do), this should be
+@code{nil}.
+
+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
+ Repeat Outside : [Toggle] off (nil)
+[INS] [DEL] List:
+ Macro with args: \nindex@{*@}
+ Index Tag : [Value Menu] String: name
+ Access Key : n
+ Key Prefix :
+ Exclusion hook : nil
+ Repeat Outside : [Toggle] off (nil)
+[INS] [DEL] List:
+ Macro with args: \astobj@{*@}
+ Index Tag : [Value Menu] String: idx
+ Access Key : o
+ Key Prefix : Astronomical Objects!
+ Exclusion hook : nil
+ Repeat Outside : [Toggle] on (non-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"))
+@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".
+
+@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.
+
+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:
+
+@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)}).
+
+@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.
+
+@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.
+
+@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.
+
+@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
+&}.
+
+@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.
+@end table
+
+@vindex reftex-view-crossref-extra
+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-extra}.
+
+@iftex
+@chapter All the Rest
+@end iftex
+
+@node RefTeXs Menu, Key Bindings, 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.
+
+@node Key Bindings, Faces, RefTeXs Menu, Top
+@section Default Key Bindings
+@cindex Key Bindings, summary
+
+Here is a summary of the available key bindings.
+
+@kindex C-c =
+@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 |
+@kindex C-c <
+@kindex C-c >
+@example
+@kbd{C-c =} @code{reftex-toc}
+@kbd{C-c -} @code{reftex-toc-recenter}
+@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-phrase-selection-or-word}
+@kbd{C-c |} @code{reftex-index-visit-phrases-buffer}
+@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}.
+
+Personally, I also bind some functions in the users @kbd{C-c} map for
+easier access.
+
+@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 key bindings 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 key bindings 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 key bindings 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, Key Bindings, 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)}.
+
+@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:
+
+@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.
+
+@item
+@vindex tex-main-file
+@vindex TeX-master
+All files belonging to a multifile document should define a File
+Variable (@code{TeX-master} for AUCTeX or @code{tex-main-file} for the
+standard Emacs LaTeX mode) containing the name of the master file. For
+example, to set the file variable @code{TeX-master}, include something
+like the following at the end of each TeX file:
+
+@example
+%%% Local Variables: ***
+%%% mode:latex ***
+%%% TeX-master: "thesis.tex" ***
+%%% End: ***
+@end example
+
+AUCTeX with the setting
+
+@lisp
+(setq-default TeX-master nil)
+@end lisp
+
+will actually ask you for each new file about the master file and insert
+this comment automatically. For more details see the documentation of
+the AUCTeX (@pxref{Multifile,,,auctex, The AUC TeX User Manual}), the
+documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs,
+The GNU Emacs Manual}) and the Emacs documentation on File Variables
+(@pxref{File Variables,,,emacs, The GNU Emacs Manual}).
+
+@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.
+@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 valid 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
+
+@cindex Noweb files
+@vindex reftex-file-extensions
+@vindex TeX-file-extensions
+Some people like to use RefTeX with noweb files, which usually have the
+extension @file{.nw}. In order to deal with such files, the new
+extension must be added to the list of valid extensions in the variable
+@code{reftex-file-extensions}. When working with AUCTeX as major mode,
+the new extension must also be known to AUCTeX via the variable
+@code{TeX-file-extension}. For example:
+
+@lisp
+(setq reftex-file-extensions
+ '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib")))
+(setq TeX-file-extensions
+ '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo"))
+@end lisp
+
+@node Optimizations, Problems and Work-Arounds, Finding Files, Top
+@section Optimizations
+@cindex Optimizations
+
+@b{Note added 2002. Computers have gotten a lot faster, so most of the
+optimizations discussed below will not be necessary on new machines. I
+am leaving this stuff in the manual for people who want to write thick
+books, where some of it still might be useful.}
+
+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.
+
+@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
+
+@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
+@vindex reftex-parse-file-extension
+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}:
+
+@vindex reftex-save-parse-info
+@lisp
+(setq reftex-save-parse-info t)
+@end lisp
+
+@item
+@b{Identifying label types by prefix}@*
+@cindex Parse information, saving to a file
+@vindex reftex-trust-label-prefix
+@b{Ref@TeX{}} normally parses around each label to check in which
+environment this label is located, in order to assign a label type to
+the label. If your document contains thousands of labels, document
+parsing will take considerable time. If you have been using label prefixes
+like tab: and fn: consistently, you can tell @b{Ref@TeX{}} to get the
+label type directly from the prefix, without additional parsing. This
+will be faster and also allow labels to end up in the correct category
+if for some reason it is not possible to derive the correct type from
+context. For example, to enable this feature for footnote and
+equation labels, use
+
+@lisp
+(setq reftex-trust-label-prefix '("fn:" "eq:"))
+@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.
+
+@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
+
+@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
+
+@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
+
+@node AUCTeX, Multifile Documents, Faces, Top
+@section 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 (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}).
+If AUCTeX is not part of your Emacs distribution, you can get
+it@footnote{XEmacs 21.x users may want to install the corresponding
+XEmacs package.} by ftp from the @value{AUCTEXSITE}.
+
+@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
+
+@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.
+
+@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}).
+
+@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 (@pxref{Style Files,,,auctex}). 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.
+
+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{}}.
+
+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.
+
+@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:
+
+@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
+
+@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.") -3))))))
+@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:
+
+@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 nil)
+ ("aindex@{*@}" "author" ?a "" nil 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
+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.
+
+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
+
+@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}, and @code{\section} (etc.) statements
+have to be first on a line (except for white space).
+
+@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.
+
+@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.
+
+@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}.
+
+@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:
+@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).
+@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.
+@item
+Set @code{reftex-initialize-temporary-buffers} to a list of hook
+functions doing a minimal initialization.
+@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.
+
+@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 Key bindings, 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
+
+@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
+
+Ref@TeX{} was written by @i{Carsten Dominik}
+@email{dominik@@science.uva.nl}, with contributions by @i{Stephen
+Eglen}. Ref@TeX{} is currently maintained by @value{MAINTAINER}, see
+the @value{MAINTAINERSITE} for detailed information.
+
+If you have questions about Ref@TeX{}, you can send email to the
+@value{SUPPORTADDRESS}. If you want to contribute code or ideas, write
+to the @value{DEVELADDRESS}. And in the rare case of finding a bug,
+please use @kbd{M-x reftex-report-bug @key{RET}} which will prepare a
+bug report with useful information about your setup. Remember to add
+essential information like a recipe for reproducing the bug, what you
+expected to happen, and what actually happened. Send the bug report to
+the @value{BUGADDRESS}.
+
+There are also several Usenet groups which have competent readers who
+might be able to help: @code{comp.emacs}, @code{gnu.emacs.help},
+@code{comp.emacs.xemacs}, and @code{comp.text.tex}.
+
+@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 @value{XEMACSFTP}. See the XEmacs 21.x
+documentation on package installation for details.
+
+Users of earlier Emacs distributions (including Emacs 19) can get a
+@b{Ref@TeX{}} distribution from the @value{MAINTAINERSITE}. Note that
+the Emacs 19 version supports many but not all features described in
+this manual.
+
+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{Ralf
+Angeli, Fran Burstall, Alastair Burt, Lars Clausen, Soren Dayton,
+Stephen Eglen, Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai
+Grossjohann, Frank Harrell, Till A. Heilmann, Peter Heslin, Stephan
+Heuel, Alan Ho, Lute Kamstra, Dieter Kraft, David Kastrup, Adrian Lanz,
+Juri Linkov, Rory Molinari, Stefan Monnier, Laurent Mugnier, Dan
+Nicolaescu, Sudeep Kumar Palat, Daniel Polani, Alan Shutko, Robin Socha,
+Richard Stanton, Allan Strand, Jan Vroonhof, Christoph Wedler, Alan
+Williams, Roland Winkler, Hans-Christoph Wirth, Eli Zaretskii}.
+
+
+The @code{view-crossref} feature was inspired by @i{Peter Galbraith's}
+@file{bib-cite.el}.
+
+Finally thanks to @i{Uwe Bolick} who first got me interested in
+supporting LaTeX labels and references with an editor (which was
+MicroEmacs at the time).
+
+@node Commands, Options, Imprint, Top
+@chapter Commands
+@cindex Commands, list of
+
+Here is a summary of @b{Ref@TeX{}}'s commands which can be executed from
+LaTeX files. Command which are executed from the special buffers are
+not described here. All commands are available from the @code{Ref}
+menu. See @xref{Key Bindings}.
+
+@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.
+@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
+formatted according to @code{reftex-cite-format} and inserted into the
+buffer. @*
+When called with a @kbd{C-u} prefix, prompt for optional arguments in
+cite macros. 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}. @*
+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.
+@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.
+@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.
+@end deffn
+
+@deffn Command reftex-index-phrase-selection-or-word
+Add current selection or the word at point to the phrases buffer.
+When you are in transient-mark-mode and the region is active, the
+selection will be used - otherwise the word at point.
+You get a chance to edit the entry in the phrases buffer - to save the
+buffer and return to the LaTeX document, finish with @kbd{C-c C-c}.
+@end deffn
+
+@deffn Command reftex-index-visit-phrases-buffer
+Switch to the phrases buffer, initialize if empty.
+@end deffn
+
+@deffn Command reftex-index-phrases-apply-to-region
+Index all index phrases in the current region.
+This works exactly like global indexing from the index phrases buffer,
+but operation is restricted to the current region.
+@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.
+@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 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}.
+@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.
+@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.
+@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.
+@end deffn
+
+@deffn Command reftex-isearch-minor-mode
+Toggle a minor mode which enables incremental search to work globally
+on the entire multifile document. Files will be searched in th
+sequence they appear in the document.
+@end deffn
+
+@deffn Command reftex-goto-label
+Prompt for a label (with completion) and jump to the location of this
+label. Optional prefix argument @var{other-window} goes to the label in
+another window.
+@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.
+@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.
+@end deffn
+
+@deffn Command reftex-find-duplicate-labels
+Produce a list of all duplicate labels in the document.
+@end deffn
+
+@deffn Command reftex-create-bibtex-file
+Create a new BibTeX database file with all entries referenced in document.
+The command prompts for a filename and writes the collected entries to
+that file. Only entries referenced in the current document with
+any @code{\cite}-like macros are used.
+The sequence in the new file is the same as it was in the old database.
+@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.
+
+@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-include-file-commands
+List of LaTeX commands which input another file.
+The file name is expected after the command, either in braces or separated
+by whitespace.
+@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} may also be a function which then has to return the
+level. This list is also used for promotion and demotion of sectioning
+commands. If you are using a document class which has several sets of
+sectioning commands, promotion only works correctly if this list is
+sorted first by set, then within each set by level. The promotion
+commands always select the nearest entry with the correct new level.
+
+@end defopt
+
+@defopt reftex-toc-max-level
+The maximum level of toc entries which will be included in the TOC.
+Section headings with a bigger level will be ignored. In RefTeX,
+chapters are level 1, sections level 2 etc. This variable can be
+changed from within the @file{*toc*} buffer with the @kbd{t} key.
+@end defopt
+
+@defopt reftex-part-resets-chapter
+Non-@code{nil} means, @code{\part} is like any other sectioning command.
+This means, part numbers will be included in the numbering of chapters, and
+chapter counters will be reset for each part.
+When @code{nil} (the default), parts are special, do not reset the
+chapter counter and also do not show up in chapter numbers.
+@end defopt
+
+@defopt reftex-auto-recenter-toc
+Non-@code{nil} means, turn automatic recentering of @file{*TOC*} window on.
+When active, the @file{*TOC*} window will always show the section you
+are currently working in. Recentering happens whenever Emacs is idle for
+more than @code{reftex-idle-time} seconds.
+
+Value @code{t} means, turn on immediately when RefTeX gets started. Then,
+recentering will work for any toc window created during the session.
+
+Value @code{frame} (the default) means, turn automatic recentering on
+only while the dedicated TOC frame does exist, and do the recentering
+only in that frame. So when creating that frame (with @kbd{d} key in an
+ordinary TOC window), the automatic recentering is turned on. When the
+frame gets destroyed, automatic recentering is turned off again.
+
+This feature can be turned on and off from the menu
+(Ref->Options).
+@end defopt
+
+@defopt reftex-toc-split-windows-horizontally
+Non-@code{nil} means, create TOC window by splitting window
+horizontally. The default is to split vertically.
+@end defopt
+
+@defopt reftex-toc-split-windows-fraction
+Fraction of the width or height of the frame to be used for TOC window.
+@end defopt
+
+@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.
+@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.
+@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.
+@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.
+@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.
+@end defopt
+
+@deffn {Normal Hook} reftex-toc-mode-hook
+Normal hook which is run when a @file{*toc*} buffer is
+created.
+@end deffn
+
+@deffn Keymap reftex-toc-map
+The keymap which is active in the @file{*toc*} buffer.
+(@pxref{Table of Contents}).
+@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.
+@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.
+
+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} ... ) @var{toc-level})
+@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:
+
+@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.
+
+Special names: @code{section} for section labels, @code{any} to define a
+group which contains all labels.
+
+This may also be a function to do local parsing and identify point to be
+in 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.
+
+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).
+
+@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.
+
+@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:
+
+@example
+%f Current file name, directory and extension stripped.
+%F Current file name relative to master file directory.
+%m Master file name, directory and extension stripped.
+%M Directory name (without path) where master file is located.
+%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:}.
+
+@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.
+
+@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.
+@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).
+@item
+text after the macro name (starting with the first arg) for
+macros.
+@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.
+@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.
+@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}).
+@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:
+
+@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.
+
+@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.
+
+@item @var{toc-level}
+The integer level at which this environment should be added to the table
+of contents. See also @code{reftex-section-levels}. A positive value
+will number the entries mixed with the sectioning commands of the same
+level. A negative value will make unnumbered entries. Useful only for
+theorem-like environments which structure the document. Will be ignored
+for macros. When omitted or @code{nil}, no TOC entries will be
+made.
+@end table
+
+If the type indicator characters of two or more entries are the same,
+@b{Ref@TeX{}} will use
+@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}.
+@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.
+@end defopt
+
+@defopt reftex-trust-label-prefix
+Non-@code{nil} means, trust the label prefix when determining label type.
+It is customary to use special label prefixes to distinguish different label
+types. The label prefixes have no syntactic meaning in LaTeX (unless
+special packages like fancyref) are being used. RefTeX can and by
+default does parse around each label to detect the correct label type,
+but this process can be slow when a document contains thousands of
+labels. If you use label prefixes consistently, you may speed up
+document parsing by setting this variable to a non-nil value. RefTeX
+will then compare the label prefix with the prefixes found in
+`reftex-label-alist' and derive the correct label type in this way.
+Possible values for this option are:
+
+@example
+t @r{This means to trust any label prefixes found.}
+regexp @r{If a regexp, only prefixes matched by the regexp are trusted.}
+list @r{List of accepted prefixes, as strings. The colon is part of}
+ @r{the prefix, e.g. ("fn:" "eqn:" "item:").}
+nil @r{Never trust a label prefix.}
+@end example
+The only disadvantage of using this feature is that the label context
+displayed in the label selection buffer along with each label is
+simply some text after the label definition. This is no problem if you
+place labels keeping this in mind (e.g. @i{before} the equation, @i{at
+the beginning} of a fig/tab caption ...). Anyway, it is probably best
+to use the regexp or the list value types to fine-tune this feature.
+For example, if your document contains thousands of footnotes with
+labels fn:xxx, you may want to set this variable to the value "^fn:$" or
+("fn:"). Then RefTeX will still do extensive parsing for any
+non-footnote labels.
+@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 valid 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}.
+
+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.
+
+So the combination of @var{derive} and @var{prompt} controls label
+insertion. Here is a table describing all four possibilities:
+
+@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.
+
+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}.
+@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.
+@end deffn
+
+@deffn Hook reftex-string-to-label-function
+Function to turn an arbitrary string into a valid label.
+@b{Ref@TeX{}}'s default function uses the variable
+@code{reftex-derive-label-parameters}.
+@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 valid 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}.
+@end deffn
+
+@defopt reftex-derive-label-parameters
+Parameters for converting a string into a label. This variable is a
+list of the following items:
+@table @asis
+@item @var{nwords}
+Number of words to use.
+@item @var{maxchar}
+Maximum number of characters in a label string.
+@item @var{invalid}
+@code{nil}: Throw away any words containing characters invalid in labels.@*
+@code{t}: Throw away only the invalid 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 valid in labels.
+@end defopt
+
+@defopt reftex-abbrev-parameters
+Parameters for abbreviation of words. A list of four parameters.
+@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.
+@item @var{before}
+Character class before abbrev point in word.
+@item @var{after}
+Character class after abbrev point in word.
+@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.
+@item @var{section-numbers}
+Include section numbers (like 4.1.3) in table of contents.
+@item @var{counters}
+Show counters. This just numbers the labels in the menu.
+@item @var{no-context}
+Non-@code{nil} means do @emph{not} show the short context.
+@item @var{follow}
+Follow full context in other window.
+@item @var{show-commented}
+Show labels from regions which are commented out.
+@item @var{match-everywhere}
+Obsolete flag.
+@item @var{show-files}
+Show begin and end of included files.
+@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.
+
+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}.
+
+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.
+@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}.
+@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.
+@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.
+@end deffn
+
+@defopt reftex-level-indent
+Number of spaces to be used for indentation per section level.
+@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.
+@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.
+@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.
+@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}.
+@end deffn
+
+@deffn Keymap reftex-select-label-map
+The keymap which is active in the labels selection process
+(@pxref{Referencing Labels}).
+@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-bibliography-commands
+LaTeX commands which specify the BibTeX databases to use with the document.
+@end defopt
+
+@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.
+@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.
+@end defopt
+
+@defopt reftex-sort-bibtex-matches
+Sorting of the entries found in BibTeX databases by reftex-citation.
+Possible values:
+@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.
+
+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.
+
+@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).
+@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)}.
+
+@samp{%<} as a special operator kills punctuation and space around it
+after the string has been formatted.
+
+A pair of square brackets indicates an optional argument, and RefTeX
+will prompt for the values of these arguments.
+
+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.
+
+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.
+
+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)}.
+@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.
+@end deffn
+
+@defopt reftex-cite-prompt-optional-args
+Non-@code{nil} means, prompt for empty optional arguments in cite macros.
+When an entry in @code{reftex-cite-format} ist given with square brackets to
+indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can
+prompt for values. Possible values are:
+@example
+nil @r{Never prompt for optional arguments}
+t @r{Always prompt}
+maybe @r{Prompt only if @code{reftex-citation} was called with C-u prefix arg}@end example
+Unnecessary empty optional arguments are removed before insertion into
+the buffer. See @code{reftex-cite-cleanup-optional-args}.
+@end defopt
+
+@defopt reftex-cite-cleanup-optional-args
+Non-@code{nil} means, remove empty optional arguments from cite macros
+if possible.
+@end defopt
+
+@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}.
+@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.
+@end defopt
+
+@defopt reftex-cite-punctuation
+Punctuation for formatting of name lists in citations. This is a list
+of 3 strings.
+@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}.
+@end deffn
+
+@deffn Keymap reftex-select-bib-map
+The keymap which is active in the citation-key selection process
+(@pxref{Creating Citations}).
+@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.
+@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} @var{repeat})
+@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.
+
+@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.
+
+@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.
+
+@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!}.
+
+@var{exclude} can be a function. If this function exists and returns a
+non-@code{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.
+
+@var{repeat}, if 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. Needed for @code{reftex-index-selection-or-word} and for
+indexing from the phrase buffer.
+
+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. Valid values are currently
+@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{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.
+@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. Valid values of this variable are:
+@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.
+@end defopt
+
+@defopt reftex-index-phrase-file-extension
+File extension for the index phrase file. This extension will be added
+to the base name of the master file.
+@end defopt
+
+@defopt reftex-index-phrases-logical-and-regexp
+Regexp matching the @samp{and} operator for index arguments in phrases
+file. When several index arguments in a phrase line are separated by
+this operator, each part will generate an index macro. So each match of
+the search phrase will produce @emph{several} different index entries.
+Make sure this does no match things which are not separators. This
+logical @samp{and} has higher priority than the logical @samp{or}
+specified in @code{reftex-index-phrases-logical-or-regexp}.
+@end defopt
+
+@defopt reftex-index-phrases-logical-or-regexp
+Regexp matching the @samp{or} operator for index arguments in phrases
+file. When several index arguments in a phrase line are separated by
+this operator, the user will be asked to select one of them at each
+match of the search phrase. The first index arg will be the default. A
+number key @kbd{1}--@kbd{9} must be pressed to switch to another. Make
+sure this does no match things which are not separators. The logical
+@samp{and} specified in @code{reftex-index-phrases-logical-or-regexp}
+has higher priority than this logical @samp{or}.
+@end defopt
+
+@defopt reftex-index-phrases-search-whole-words
+Non-@code{nil} means phrases search will look for whole words, not subwords.
+This works by requiring word boundaries at the beginning and end of
+the search string. When the search phrase already has a non-word-char
+at one of these points, no word boundary is required there.
+@end defopt
+
+@defopt reftex-index-phrases-case-fold-search
+Non-@code{nil} means, searching for index phrases will ignore
+case.
+@end defopt
+
+@defopt reftex-index-verify-function
+A function which is called at each match during global indexing.
+If the function returns nil, the current match is skipped.
+@end defopt
+
+@defopt reftex-index-phrases-skip-indexed-matches
+Non-@code{nil} means, skip matches which appear to be indexed already.
+When doing global indexing from the phrases buffer, searches for some
+phrases may match at places where that phrase was already indexed. In
+particular when indexing an already processed document again, this
+will even be the norm. When this variable is non-@code{nil},
+@b{Ref@TeX{}} checks if the match is an index macro argument, or if an
+index macro is directly before or after the phrase. If that is the
+case, that match will be ignored.
+@end defopt
+
+@defopt reftex-index-phrases-wrap-long-lines
+Non-@code{nil} means, when indexing from the phrases buffer, wrap lines.
+Inserting indexing commands in a line makes the line longer - often
+so long that it does not fit onto the screen. When this variable is
+non-@code{nil}, newlines will be added as necessary before and/or after the
+indexing command to keep lines short. However, the matched text
+phrase and its index command will always end up on a single line.
+@end defopt
+
+@defopt reftex-index-phrases-sort-prefers-entry
+Non-@code{nil} means when sorting phrase lines, the explicit index entry
+is used. Phrase lines in the phrases buffer contain a search phrase, and
+sorting is normally based on these. Some phrase lines also have
+an explicit index argument specified. When this variable is
+non-@code{nil}, the index argument will be used for sorting.
+@end defopt
+
+@defopt reftex-index-phrases-sort-in-blocks
+Non-@code{nil} means, empty and comment lines separate phrase buffer
+into blocks. Sorting will then preserve blocks, so that lines are
+re-arranged only within blocks.
+@end defopt
+
+@defopt reftex-index-phrases-map
+Keymap for the Index Phrases buffer.
+@end defopt
+
+@defopt reftex-index-phrases-mode-hook
+Normal hook which is run when a buffer is put into
+@code{reftex-index-phrases-mode}.
+@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, @b{Ref@TeX{}} 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.
+@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}).
+@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 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 idle for more than @code{reftex-idle-time} seconds 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 off from the menu
+(Ref->Options).
+@end defopt
+
+@defopt reftex-idle-time
+Time (secs) Emacs has to be idle before automatic crossref display
+or toc recentering is done.
+@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.
+@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.
+@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.
+@itemize @minus
+@item
+If an element is the name of an environment variable, its content is
+used.
+@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.
+@itemize @minus
+@item
+If an element is the name of an environment variable, its content is
+used.
+@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 valid extensions for this file type.}
+@end example
+When a files is searched and it does not have any of the valid extensions,
+we try the default extension first, and then the naked file name.
+@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.
+@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}.
+@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
+@table @asis
+@item PARSING
+Parts of a multifile document loaded when (re)-parsing the
+document.
+@item LOOKUP
+BibTeX database files and TeX files loaded to find a reference, to
+display label context, etc.
+@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:
+
+@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.
+@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}.
+@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.
+@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.
+@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.
+@item
+exiting Emacs or killing a buffer in reftex-mode will cause a new
+version of the file to be written.
+@end itemize
+@end defopt
+
+@defopt reftex-parse-file-extension
+File extension for the file in which parser information is stored.
+This extension is added to the base name of the master file.
+@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}.
+@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}.
+@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.
+@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.
+
+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.
+@end table
+The option is ignored when @code{reftex-use-fonts} is @code{nil}.
+@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:
+
+@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}).
+@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}.
+@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}.
+@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{Key Bindings}.
+@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
+
+@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.
+@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.
+@end deffn
+
+Furthermore, the 4 modes used for referencing labels, creating
+citations, the table of contents buffer and the phrases 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{}}.
+
+@node Changes, GNU Free Documentation License, Keymaps and Hooks, Top
+@chapter Changes
+@cindex Changes
+
+Here is a list of recent changes to @b{Ref@TeX{}}.
+
+@noindent @b{Version 4.28}
+@itemize @bullet
+@item Support for the Jurabib package.
+@item Improvements when selecting several items in a selection buffer.
+@end itemize
+
+@noindent @b{Version 4.26}
+@itemize @bullet
+@item
+Support for global incremental search.
+@item
+Some improvements for XEmacs compatibility.
+@end itemize
+
+@noindent @b{Version 4.25}
+@itemize @bullet
+@item
+Fixed bug with @samp{%F} in a label prefix. Added new escapes
+@samp{%m} and @samp{%M} for mater file name and master directory.
+@end itemize
+
+@noindent @b{Version 4.24}
+@itemize @bullet
+@item
+Inserting citation commands now prompts for optional arguments
+when called with a prefix argument. Related new options are
+@code{reftex-cite-prompt-optional-args} and
+@code{reftex-cite-cleanup-optional-args}.
+@item
+New option @code{reftex-trust-label-prefix}. Configure this variable
+if you'd like RefTeX to base its classification of labels on prefixes.
+This can speed-up document parsing, but may in some cases reduce the
+quality of the context used by RefTeX to describe a label.
+@item
+Fixed bug in @code{reftex-create-bibtex-file} when @code{reftex-comment-citations}
+is non-nil.
+@item
+Fixed bugs in indexing: Case-sensitive search, quotes before and/or
+after words. Disabled indexing in comment lines.
+@end itemize
+
+@noindent @b{Version 4.22}
+@itemize @bullet
+@item
+New command @code{reftex-create-bibtex-file} to create a new database
+with all entries referenced in the current document.
+@item
+New keys @kbd{e} and @kbd{E} allow to produce a BibTeX database file
+from entries marked in a citation selection buffer.
+@end itemize
+
+@noindent @b{Version 4.21}
+@itemize @bullet
+@item
+Renaming labels from the toc buffer with key @kbd{M-%}.
+@end itemize
+
+@noindent @b{Version 4.20}
+@itemize @bullet
+@item
+Structure editing capabilities. The command keys @kbd{<} and @kbd{>} in
+the TOC buffer promote/demote the section at point or all sections in
+the current region.
+@item
+New option @code{reftex-toc-split-windows-fraction} to set the size of
+the window used by the TOC. This makes the old variable
+@code{reftex-toc-split-windows-horizontally-fraction} obsolete.
+@item
+A dedicated frame can show the TOC with the current section
+always automatically highlighted. The frame is created and
+deleted from the toc buffer with the @kbd{d} key.
+@end itemize
+
+@noindent @b{Version 4.19}
+@itemize @bullet
+@item
+New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current
+section in the TOC buffer without selecting the TOC window.
+@item
+Recentering happens automatically in idle time when the option
+@code{reftex-auto-recenter-toc} is turned on.
+@item
+Fixed several bugs related to automatic cursor positioning in the TOC
+buffer.
+@item
+The highlight in the TOC buffer stays when the focus moves to a
+different window.
+@item
+New command `reftex-goto-label'.
+@item
+Part numbers are no longer included in chapter numbers, and a new
+part does not reset the chapter counter. See new option
+@code{reftex-part-resets-chapter}.
+@end itemize
+
+@noindent @b{Version 4.18}
+@itemize @bullet
+@item
+@code{reftex-citation} uses the word before the cursor as a default
+search string.
+@item
+Simplified several regular expressions for speed.
+@item
+Better support for chapterbib.
+@end itemize
+
+@noindent @b{Version 4.17}
+@itemize @bullet
+@item
+The toc window can be split off horizontally. See new options
+@code{reftex-toc-split-windows-horizontally},
+@code{reftex-toc-split-windows-horizontally-fraction}.
+@item
+It is possible to specify a function which verifies an index match
+during global indexing. See new option @code{reftex-index-verify-function}.
+@item
+The macros which input a file in LaTeX (like \input, \include) can
+be configured. See new option @code{reftex-include-file-commands}.
+@item
+The macros which specify the bibliography file (like \bibliography) can
+be configured. See new option @code{reftex-bibliography-commands}.
+@item
+The regular expression used to search for the \bibliography macro has
+been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by
+chapterbib.
+@item
+Small bug fixes.
+@end itemize
+
+@noindent @b{Version 4.15}
+@itemize @bullet
+@item
+Fixed bug with parsing of BibTeX files, when fields contain quotes or
+unmatched parenthesis.
+@item
+Small bug fixes.
+@item
+Improved interaction with Emacs LaTeX mode.
+@end itemize
+
+@noindent @b{Version 4.12}
+@itemize @bullet
+@item
+Support for @file{bibentry} citation style.
+@end itemize
+
+@noindent @b{Version 4.11}
+@itemize @bullet
+@item
+Fixed bug which would parse @samp{\Section} just like @samp{\section}.
+@end itemize
+
+@noindent @b{Version 4.10}
+@itemize @bullet
+@item
+Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict
+with @file{reftex-vars.el} on DOS machines.
+@item
+New options @code{reftex-parse-file-extension} and
+@code{reftex-index-phrase-file-extension}.
+@end itemize
+
+@noindent [.....]
+@ignore
+@noindent @b{Version 4.09}
+@itemize @bullet
+@item
+New option @code{reftex-toc-max-level} to limit the depth of the toc.
+New key binding @kbd{t} in the @file{*toc*} buffer to change this
+setting.
+@item
+RefTeX maintains an @file{Index Phrases} file in which phrases can be
+collected. When the document is ready, RefTeX can search all
+these phrases and assist indexing all matches.
+@item
+The variables @code{reftex-index-macros} and
+@code{reftex-index-default-macro} have changed their syntax slightly.
+The @var{repeat} parameter has move from the latter to the former.
+Also calls to @code{reftex-add-index-macros} from AUCTeX style files
+need to be adapted.
+@item
+The variable @code{reftex-section-levels} no longer contains the
+default stuff which has been moved to a constant.
+@item
+Environments like theorems can be placed into the TOC by putting
+entries for @samp{"begin@{theorem@}"} in
+@code{reftex-setion-levels}.
+@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
+
+@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.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.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.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 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.
+@item
+New option @code{reftex-view-crossref-extra}.
+@item
+Support for the additional sectioning commands @code{\addchap} and
+@code{\addsec} which are defined in the LaTeX KOMA-Script classes.
+@item
+Files in @code{reftex-default-bibliography} will be searched along
+@code{BIBINPUTS} path.
+@item
+Reading a parse file now checks consistency.
+@end itemize
+
+@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}.
+@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
+
+@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.36}
+@itemize @bullet
+@item
+New value @code{window} for option @code{reftex-auto-view-crossref}.
+@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.
+@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 valid in labels.
+@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.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.28}
+@itemize @bullet
+@item
+Auto view crossref for XEmacs uses @code{post-command-hook} to restart the
+timer, since itimer restart is not reliable.
+@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.27}
+@itemize @bullet
+@item
+Macros can define @emph{neutral} labels, just like @code{\label}
+itself.
+@item
+New option @code{reftex-allow-detached-macro-args}, default @code{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}.
+@item
+Made sure automatic crossref display will not visit/scan files.
+@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}.
+@item
+@kbd{M-x reftex-reset-mode} now also removes the file with parsing
+info.
+@item
+Default of @code{reftex-revisit-to-follow} changed to nil.
+@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.
+@item
+Fixed Bug with parsing "single file" from master file buffer.
+@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.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}.
+@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}.
+@end itemize
+
+@noindent @b{Version 3.19}
+@itemize @bullet
+@item
+Fixed bug with AUCTeX @code{TeX-master}.
+@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.
+@item
+New option @code{reftex-highlight-selection}.
+@item
+@kbd{mouse-2} can be used to select in selection and @file{*toc*}
+buffers.
+@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.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.16}
+@itemize @bullet
+@item
+New hooks @code{reftex-format-label-function},
+@code{reftex-format-ref-function}, @code{reftex-format-cite-function}.
+@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.14}
+@itemize @bullet
+@item
+Selection buffers can be kept between selections: this is faster.
+See new variable @code{reftex-use-multiple-selection-buffers}.
+@item
+Prefix interpretation of reftex-view-crossref changed.
+@item
+Support for the @code{varioref} package (@kbd{v} key in selection
+buffer).
+@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.
+@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.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.07}
+@itemize @bullet
+@item
+@code{Ref} menu improved.
+@end itemize
+
+@noindent @b{Version 3.05}
+@itemize @bullet
+@item
+Compatibility code now first checks for XEmacs feature.
+@end itemize
+
+@noindent @b{Version 3.04}
+@itemize @bullet
+@item
+Fixed BUG in the @emph{xr} support.
+@end itemize
+
+@noindent @b{Version 3.03}
+@itemize @bullet
+@item
+Support for the LaTeX package @code{xr}, for inter-document
+references.
+@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.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}.
+@item
+@b{Ref@TeX{}} should work correctly in combination with buffer-altering
+packages like outline, folding, x-symbol, iso-cvt, isotex, etc.
+@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.
+@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!
+@item
+TEXINPUTS variable recognized when looking for input files.
+@item
+Context can be the nth argument of a macro.
+@item
+Searching in the select buffer is now possible (@kbd{C-s} and
+@kbd{C-r}).
+@item
+Display and derive-label can use two different context methods.
+@item
+AMSmath @code{xalignat} and @code{xxalignat} added.
+@end itemize
+
+@noindent @b{Version 2.14}
+@itemize @bullet
+@item
+Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with
+AUCTeX.
+@end itemize
+
+@noindent @b{Version 2.11}
+@itemize @bullet
+@item
+Submitted for inclusion to Emacs and XEmacs.
+@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.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.03}
+@itemize @bullet
+@item
+@code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to
+default environments.
+@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}.
+@item
+Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is
+required.
+@item
+@code{reftex-add-to-label-alist} (to be called from AUCTeX style
+files).
+@item
+Finding context with a hook function.
+@item
+Sorting BibTeX entries (new variable:
+@code{reftex-sort-bibtex-matches}).
+@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 1.09}
+@itemize @bullet
+@item
+Support for @code{tex-main-file}, an analogue for
+@code{TeX-master}.
+@item
+MS-DOS support.
+@end itemize
+
+@noindent @b{Version 1.07}
+@itemize @bullet
+@item
+@b{Ref@TeX{}} gets its own menu.
+@end itemize
+
+@noindent @b{Version 1.05}
+@itemize @bullet
+@item
+XEmacs port.
+@end itemize
+
+@noindent @b{Version 1.04}
+@itemize @bullet
+@item
+Macros as wrappers, AMSTeX support, delayed context parsing for
+new labels.
+@end itemize
+@end ignore
+
+@noindent @b{Version 1.00}
+@itemize @bullet
+@item
+released on 7 Jan 1997.
+@end itemize
+
+@node GNU Free Documentation License, Index, Changes, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index, , GNU Free Documentation License, Top
+@unnumbered Index
+@printindex cp
+
+@summarycontents
+@contents
+@bye
+
+@ignore
+ arch-tag: 1e055774-0576-4b1b-b47f-550d0961fd43
+@end ignore
--- /dev/null
+\input texinfo @comment -*-texinfo-*-
+@comment 3.48
+@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
+
+@c @setchapternewpage odd % For book style double sided manual.
+@comment %**end of header (This is for running Texinfo on a region.)
+
+@copying
+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, 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@c @smallbook
+
+@dircategory Emacs
+@direntry
+* SC: (sc). Supercite lets you cite parts of messages you're
+ replying to, in flexible ways.
+@end direntry
+
+@titlepage
+@sp 6
+@center @titlefont{Supercite User's Manual}
+@sp 2
+@center @titlefont{Supercite Version 3.1}
+@sp 4
+@center Manual Revision: 3.48
+@center April 2007
+@sp 5
+@center Barry A@. Warsaw
+@center @t{bwarsaw@@cen.com}
+@center @t{@dots{}!uunet!cen.com!bwarsaw}
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnottex
+@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::
+
+* GNU Free Documentation License::
+* Concept Index::
+* Command Index::
+* Key Index::
+* Variable Index::
+@end menu
+@end ifnottex
+
+
+@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
+
+@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 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 key bindings 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 key bindings 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-list} 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
+resetting 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, GNU Free Documentation License, 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 GNU Free Documentation License, Concept Index, The Supercite Mailing List, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Concept Index, Command Index, GNU Free Documentation License, 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
+@setchapternewpage odd
+@summarycontents
+@contents
+@bye
+
+@ignore
+ arch-tag: 0521847a-4680-44b6-ae6e-13ce20e18436
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename ../info/ses
+@settitle SES: Simple Emacs Spreadsheet
+@setchapternewpage off
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex ky cp
+@c %**end of header
+
+@copying
+This file documents SES: the Simple Emacs Spreadsheet.
+
+Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007
+Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* SES: (ses). Simple Emacs Spreadsheet
+@end direntry
+
+@finalout
+
+@titlepage
+@title SES
+@subtitle Simple Emacs Spreadsheet
+@author Jonathan A. Yavner
+@author @email{jyavner@@member.fsf.org}
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@c ===================================================================
+
+@ifnottex
+@node Top, Sales Pitch, (dir), (dir)
+@comment node-name, next, previous, up
+@top SES: Simple Emacs Spreadsheet
+
+@display
+SES is a major mode for GNU Emacs to edit spreadsheet files, which
+contain a rectangular grid of cells. The cells' values are specified
+by formulas that can refer to the values of other cells.
+@end display
+@end ifnottex
+
+To report bugs, send email to @email{jyavner@@member.fsf.org}.
+
+@menu
+* Sales Pitch:: Why use SES?
+* The Basics:: Basic spreadsheet commands
+* Advanced Features:: Want to know more?
+* For Gurus:: Want to know @emph{even more}?
+* Index:: Concept, Function and Variable Index
+* Acknowledgements:: Acknowledgements
+* GNU Free Documentation License:: The license for this documentation.
+@end menu
+
+@c ===================================================================
+
+@node Sales Pitch, The Basics, Top, Top
+@comment node-name, next, previous, up
+@chapter Sales Pitch
+@cindex features
+
+@itemize @bullet
+@item Create and edit simple spreadsheets with a minimum of fuss.
+@item Full undo/redo/autosave.
+@item Immune to viruses in spreadsheet files.
+@item Cell formulas are straight Emacs Lisp.
+@item Printer functions for control of cell appearance.
+@item Intuitive keystroke commands: C-o = insert row, M-o = insert column, etc.
+@item ``Spillover'' of lengthy cell values into following blank cells.
+@item Header line shows column letters or a selected row.
+@item Completing-read for entering symbols as cell values.
+@item Cut, copy, and paste can transfer formulas and printer functions.
+@item Import and export of tab-separated values or tab-separated formulas.
+@item Plaintext, easily-hacked file format.
+@end itemize
+
+@c ===================================================================
+
+@node The Basics, Advanced Features, Sales Pitch, Top
+@comment node-name, next, previous, up
+@chapter The Basics
+@cindex basic commands
+@findex ses-jump
+@findex ses-mark-row
+@findex ses-mark-column
+@findex ses-mark-whole-buffer
+@findex set-mark-command
+@findex keyboard-quit
+
+A @dfn{cell identifier} is a symbol with a column letter and a row
+number. Cell B7 is the 2nd column of the 7th row. For very wide
+spreadsheets, there are two column letters: cell AB7 is the 28th
+column of the 7th row.
+
+@table @kbd
+@item j
+Moves point to cell, specified by identifier (@code{ses-jump}).
+@end table
+
+Point is always at the left edge of a cell, or at the empty endline.
+When mark is inactive, the current cell is underlined. When mark is
+active, the range is the highlighted rectangle of cells (SES always
+uses transient mark mode). Drag the mouse from A1 to A3 to create the
+range A1-A2. Many SES commands operate only on single cells, not
+ranges.
+
+@table @kbd
+@item C-SPC
+@itemx C-@@
+Set mark at point (@code{set-mark-command}).
+
+@item C-g
+Turn off the mark (@code{keyboard-quit}).
+
+@item M-h
+Highlight current row (@code{ses-mark-row}).
+
+@item S-M-h
+Highlight current column (@code{ses-mark-column}).
+
+@item C-x h
+Highlight all cells (@code{mark-whole-buffer}).
+@end table
+
+@menu
+* Formulas::
+* Resizing::
+* Printer functions::
+* Clearing cells::
+* Copy/cut/paste::
+* Customizing SES::
+@end menu
+
+@node Formulas, Resizing, The Basics, The Basics
+@section Cell formulas
+@cindex formulas
+@cindex formulas, entering
+@findex ses-read-cell
+@findex ses-read-symbol
+@findex ses-edit-cell
+@findex ses-recalculate-cell
+@findex ses-recalculate-all
+
+To enter a number into the current cell, just start typing:
+
+@table @kbd
+@item 0..9
+Self-insert a digit (@code{ses-read-cell}).
+
+@item -
+Self-insert a negative number (@code{ses-read-cell}).
+
+@item .
+Self-insert a fractional number (@code{ses-read-cell}).
+
+@item "
+Self-insert a quoted string. The ending double-quote
+is inserted for you (@code{ses-read-cell}).
+
+@item (
+Self-insert an expression. The right-parenthesis is inserted for you
+(@code{ses-read-cell}). To access another cell's value, just use its
+identifier in your expression. Whenever the other cell is changed,
+this cell's formula will be reevaluated. While typing in the
+expression, you can use @kbd{M-@key{TAB}} to complete symbol names.
+
+@item ' @r{(apostrophe)}
+Enter a symbol (ses-read-symbol). SES remembers all symbols that have
+been used as formulas, so you can type just the beginning of a symbol
+and use @kbd{@key{SPC}}, @kbd{@key{TAB}}, and @kbd{?} to complete it.
+@end table
+
+To enter something else (e.g., a vector), begin with a digit, then
+erase the digit and type whatever you want.
+
+@table @kbd
+@item RET
+Edit the existing formula in the current cell (@code{ses-edit-cell}).
+
+@item C-c C-c
+Force recalculation of the current cell or range (@code{ses-recalculate-cell}).
+
+@item C-c C-l
+Recalculate the entire spreadsheet (@code{ses-recalculate-all}).
+@end table
+
+@node Resizing, Printer functions, Formulas, The Basics
+@section Resizing the spreadsheet
+@cindex resizing spreadsheets
+@findex ses-insert-row
+@findex ses-insert-column
+@findex ses-delete-row
+@findex ses-delete-column
+@findex ses-set-column-width
+@findex ses-forward-or-insert
+@findex ses-append-row-jump-first-column
+
+
+Basic commands:
+
+@table @kbd
+@item C-o
+(@code{ses-insert-row})
+
+@item M-o
+(@code{ses-insert-column})
+
+@item C-k
+(@code{ses-delete-row})
+
+@item M-k
+(@code{ses-delete-column})
+
+@item w
+(@code{ses-set-column-width})
+
+@item TAB
+Moves point to the next rightward cell, or inserts a new column if
+already at last cell on line, or inserts a new row if at endline
+(@code{ses-forward-or-insert}).
+
+@item C-j
+Linefeed inserts below the current row and moves to column A
+(@code{ses-append-row-jump-first-column}).
+@end table
+
+Resizing the spreadsheet (unless you're just changing a column width)
+relocates all the cell-references in formulas so they still refer to
+the same cells. If a formula mentioned B1 and you insert a new first
+row, the formula will now mention B2.
+
+If you delete a cell that a formula refers to, the cell-symbol is
+deleted from the formula, so @code{(+ A1 B1 C1)} after deleting the third
+column becomes @code{(+ A1 B1)}. In case this is not what you wanted:
+
+@table @kbd
+@item C-_
+@itemx C-x u
+Undo previous action (@code{(undo)}).
+@end table
+
+
+@node Printer functions, Clearing cells, Resizing, The Basics
+@section Printer functions
+@cindex printer functions
+@findex ses-read-cell-printer
+@findex ses-read-column-printer
+@findex ses-read-default-printer
+@findex ses-center
+@findex ses-center-span
+@findex ses-dashfill
+@findex ses-dashfill-span
+@findex ses-tildefill-span
+
+
+Printer functions convert binary cell values into the print forms that
+Emacs will display on the screen.
+
+A printer can be a format string, like @samp{"$%.2f"}. The result
+string is right-aligned within the print cell. To get left-alignment,
+use parentheses: @samp{("$%.2f")}. A printer can also be a
+one-argument function (a symbol or a lambda), whose result is a string
+(right-aligned) or list of one string (left-aligned). While typing in
+a lambda, you can use @kbd{M-@key{TAB}} to complete the names of symbols.
+
+Each cell has a printer. If @code{nil}, the column-printer for the cell's
+column is used. If that is also @code{nil}, the default-printer for the
+spreadsheet is used.
+
+@table @kbd
+@item p
+Enter a printer for current cell or range (@code{ses-read-cell-printer}).
+
+@item M-p
+Enter a printer for the current column (@code{ses-read-column-printer}).
+
+@item C-c C-p
+Enter the default printer for the spreadsheet
+(@code{ses-read-default-printer}).
+@end table
+
+The @code{ses-read-@r{XXX}-printer} commands have their own minibuffer
+history, which is preloaded with the set of all printers used in this
+spreadsheet, plus the standard printers.
+
+The standard printers are suitable only for cells, not columns or
+default, because they format the value using the column-printer (or
+default-printer if @code{nil}) and then center the result:
+
+@table @code
+@item ses-center
+Just centering.
+
+@item ses-center-span
+Centering with spill-over to following blank cells.
+
+@item ses-dashfill
+Centering using dashes (-) instead of spaces.
+
+@item ses-dashfill-span
+Centering with dashes and spill-over.
+
+@item ses-tildefill-span
+Centering with tildes (~) and spill-over.
+@end table
+
+
+@node Clearing cells, Copy/cut/paste, Printer functions, The Basics
+@section Clearing cells
+@cindex clearing commands
+@findex ses-clear-cell-backward
+@findex ses-clear-cell-forward
+
+These commands set both formula and printer to @code{nil}:
+
+@table @kbd
+@item DEL
+Clear cell and move left (@code{ses-clear-cell-backward}).
+
+@item C-d
+Clear cell and move right (@code{ses-clear-cell-forward}).
+@end table
+
+
+@node Copy/cut/paste, Customizing SES, Clearing cells, The Basics
+@section Copy, cut, and paste
+@cindex copy
+@cindex cut
+@cindex paste
+@findex kill-ring-save
+@findex mouse-set-region
+@findex mouse-set-secondary
+@findex ses-kill-override
+@findex yank
+@findex clipboard-yank
+@findex mouse-yank-at-click
+@findex mouse-yank-at-secondary
+@findex ses-yank-pop
+
+The copy functions work on rectangular regions of cells. You can paste the
+copies into non-SES buffers to export the print text.
+
+@table @kbd
+@item M-w
+@itemx [copy]
+@itemx [C-insert]
+Copy the highlighted cells to kill ring and primary clipboard
+(@code{kill-ring-save}).
+
+@item [drag-mouse-1]
+Mark a region and copy it to kill ring and primary clipboard
+(@code{mouse-set-region}).
+
+@item [M-drag-mouse-1]
+Mark a region and copy it to kill ring and secondary clipboard
+(@code{mouse-set-secondary}).
+
+@item C-w
+@itemx [cut]
+@itemx [S-delete]
+The cut functions do not actually delete rows or columns---they copy
+and then clear (@code{ses-kill-override}).
+
+@item C-y
+@itemx [S-insert]
+Paste from kill ring (@code{yank}). The paste functions behave
+differently depending on the format of the text being inserted:
+@itemize @bullet
+@item
+When pasting cells that were cut from a SES buffer, the print text is
+ignored and only the attached formula and printer are inserted; cell
+references in the formula are relocated unless you use @kbd{C-u}.
+@item
+The pasted text overwrites a rectangle of cells whose top left corner
+is the current cell. If part of the rectangle is beyond the edges of
+the spreadsheet, you must confirm the increase in spreadsheet size.
+@item
+Non-SES text is usually inserted as a replacement formula for the
+current cell. If the formula would be a symbol, it's treated as a
+string unless you use @kbd{C-u}. Pasted formulas with syntax errors
+are always treated as strings.
+@end itemize
+
+@item [paste]
+Paste from primary clipboard or kill ring (@code{clipboard-yank}).
+
+@item [mouse-2]
+Set point and paste from primary clipboard (@code{mouse-yank-at-click}).
+
+@item [M-mouse-2]
+Set point and paste from secondary clipboard (@code{mouse-yank-secondary}).
+
+@item M-y
+Immediately after a paste, you can replace the text with a preceding
+element from the kill ring (@code{ses-yank-pop}). Unlike the standard
+Emacs yank-pop, the SES version uses @code{undo} to delete the old
+yank. This doesn't make any difference?
+@end table
+
+@node Customizing SES, , Copy/cut/paste, The Basics
+@section Customizing SES
+@cindex customizing
+@vindex enable-local-eval
+@vindex ses-mode-hook
+@vindex safe-functions
+@vindex enable-local-eval
+
+
+By default, a newly-created spreadsheet has 1 row and 1 column. The
+column width is 7 and the default printer is @samp{"%.7g"}. Each of these
+can be customized. Look in group ``ses''.
+
+After entering a cell value, point normally moves right to the next
+cell. You can customize @code{ses-after-entry-functions} to move left or
+up or down. For diagonal movement, select two functions from the
+list.
+
+@code{ses-mode-hook} is a normal mode hook (list of functions to
+execute when starting SES mode for a buffer).
+
+The variable @code{safe-functions} is a list of possibly-unsafe
+functions to be treated as safe when analysing formulas and printers.
+@xref{Virus protection}. Before customizing @code{safe-functions},
+think about how much you trust the person who's suggesting this
+change. The value @code{t} turns off all anti-virus protection. A
+list-of-functions value might enable a ``gee whiz'' spreadsheet, but it
+also creates trapdoors in your anti-virus armor. In order for virus
+protection to work, you must always press @kbd{n} when presented with
+a virus warning, unless you understand what the questionable code is
+trying to do. Do not listen to those who tell you to customize
+@code{enable-local-eval}---this variable is for people who don't wear
+safety belts!
+
+
+@c ===================================================================
+
+@node Advanced Features, For Gurus, The Basics, Top
+@chapter Advanced Features
+@cindex advanced features
+@findex ses-read-header-row
+
+
+@table @kbd
+@item C-c M-C-h
+(@code{ses-set-header-row}). The header line at the top of the SES
+window normally shows the column letter for each column. You can set
+it to show a copy of some row, such as a row of column titles, so that
+row will always be visible. Default is to set the current row as the
+header; use C-u to prompt for header row. Set the header to row 0 to
+show column letters again.
+@item [header-line mouse-3]
+Pops up a menu to set the current row as the header, or revert to
+column letters.
+@end table
+
+@menu
+* The print area::
+* Ranges in formulas::
+* Sorting by column::
+* Standard formula functions::
+* More on cell printing::
+* Import and export::
+* Virus protection::
+* Spreadsheets with details and summary::
+@end menu
+
+@node The print area, Ranges in formulas, Advanced Features, Advanced Features
+@section The print area
+@cindex print area
+@findex widen
+@findex ses-renarrow-buffer
+@findex ses-reprint-all
+
+A SES file consists of a print area and a data area. Normally the
+buffer is narrowed to show only the print area. The print area is
+read-only except for special SES commands; it contains cell values
+formatted by printer functions. The data area records the formula and
+printer functions, etc.
+
+@table @kbd
+@item C-x n w
+Show print and data areas (@code{widen}).
+
+@item C-c C-n
+Show only print area (@code{ses-renarrow-buffer}).
+
+@item S-C-l
+@itemx M-C-l
+Recreate print area by reevaluating printer functions for all cells
+(@code{ses-reprint-all}).
+@end table
+
+@node Ranges in formulas, Sorting by column, The print area, Advanced Features
+@section Ranges in formulas
+@cindex ranges
+@findex ses-insert-range-click
+@findex ses-insert-range
+@findex ses-insert-ses-range-click
+@findex ses-insert-ses-range
+@vindex from
+@vindex to
+
+A formula like
+@lisp
+(+ A1 A2 A3)
+@end lisp
+is the sum of three specific cells. If you insert a new second row,
+the formula becomes
+@lisp
+(+ A1 A3 A4)
+@end lisp
+and the new row is not included in the sum.
+
+The macro @code{(ses-range @var{from} @var{to})} evaluates to a list of
+the values in a rectangle of cells. If your formula is
+@lisp
+(apply '+ (ses-range A1 A3))
+@end lisp
+and you insert a new second row, it becomes
+@lisp
+(apply '+ (ses-range A1 A4))
+@end lisp
+and the new row is included in the sum.
+
+While entering or editing a formula in the minibuffer, you can select
+a range in the spreadsheet (using mouse or keyboard), then paste a
+representation of that range into your formula. Suppose you select
+A1-C1:
+
+@table @kbd
+@item [S-mouse-3]
+Inserts "A1 B1 C1" @code{(ses-insert-range-click})
+
+@item C-c C-r
+Keyboard version (@code{ses-insert-range}).
+
+@item [C-S-mouse-3]
+Inserts "(ses-range A1 C1)" (@code{ses-insert-ses-range-click}).
+
+@item C-c C-s
+Keyboard version (@code{ses-insert-ses-range}).
+@end table
+
+If you delete the @var{from} or @var{to} cell for a range, the nearest
+still-existing cell is used instead. If you delete the entire range,
+the formula relocator will delete the ses-range from the formula.
+
+If you insert a new row just beyond the end of a one-column range, or
+a new column just beyond a one-row range, the new cell is included in
+the range. New cells inserted just before a range are not included.
+
+
+@node Sorting by column, Standard formula functions, Ranges in formulas, Advanced Features
+@section Sorting by column
+@cindex sorting
+@findex ses-sort-column
+@findex ses-sort-column-click
+
+@table @kbd
+@item C-c M-C-s
+Sort the cells of a range using one of the columns
+(@code{ses-sort-column}). The rows (or partial rows if the range
+doesn't include all columns) are rearranged so the chosen column will
+be in order.
+
+@item [header-line mouse-2]
+The easiest way to sort is to click mouse-2 on the chosen column's header row
+(@code{ses-sort-column-click}).
+@end table
+
+The sort comparison uses @code{string<}, which works well for
+right-justified numbers and left-justified strings.
+
+With prefix arg, sort is in descending order.
+
+Rows are moved one at a time, with relocation of formulas. This works
+well if formulas refer to other cells in their row, not so well for
+formulas that refer to other rows in the range or to cells outside the
+range.
+
+
+@node Standard formula functions, More on cell printing, Sorting by column, Advanced Features
+@section Standard formula functions
+@cindex standard formula functions
+@cindex *skip*
+@cindex *error*
+@findex ses-delete-blanks
+@findex ses-average
+@findex ses+
+
+Oftentimes you want a calculation to exclude the blank cells. Here
+are some useful functions to call from your formulas:
+
+@table @code
+@item (ses-delete-blanks &rest @var{args})
+Returns a list from which all blank cells (value is either @code{nil} or
+'*skip*) have been deleted.
+
+@item (ses+ &rest @var{args})
+Sum of non-blank arguments.
+
+@item (ses-average @var{list})
+Average of non-blank elements in @var{list}. Here the list is passed
+as a single argument, since you'll probably use it with @code{ses-range}.
+@end table
+
+@node More on cell printing, Import and export, Standard formula functions, Advanced Features
+@section More on cell printing
+@cindex cell printing, more
+@findex ses-truncate-cell
+@findex ses-recalculate-cell
+
+Special cell values:
+@itemize
+@item nil prints the same as "", but allows previous cell to spill over.
+@item '*skip* replaces nil when the previous cell actually does spill over;
+nothing is printed for it.
+@item '*error* indicates that the formula signaled an error instead of
+producing a value: the print cell is filled with hash marks (#).
+@end itemize
+
+If the result from the printer function is too wide for the cell and
+the following cell is @code{nil}, the result will spill over into the
+following cell. Very wide results can spill over several cells. If
+the result is too wide for the available space (up to the end of the
+row or the next non-@code{nil} cell), the result is truncated if the cell's
+value is a string, or replaced with hash marks otherwise.
+
+SES could get confused by printer results that contain newlines or
+tabs, so these are replaced with question marks.
+
+@table @kbd
+@item C-c C-t
+Confine a cell to its own column (@code{ses-truncate-cell}). This
+allows you to move point to a rightward cell that would otherwise be
+covered by a spill-over. If you don't change the rightward cell, the
+confined cell will spill over again the next time it is reprinted.
+
+@item C-c C-c
+When applied to a single cell, this command displays in the echo area any
+formula error or printer error that occurred during
+recalculation/reprinting (@code{ses-recalculate-cell}).
+@end table
+
+When a printer function signals an error, the default printer
+@samp{"%s"} is substituted. This is useful when your column printer
+is numeric-only and you use a string as a cell value.
+
+
+@node Import and export, Virus protection, More on cell printing, Advanced Features
+@section Import and export
+@cindex import and export
+@cindex export, and import
+@findex ses-export-tsv
+@findex ses-export-tsf
+
+@table @kbd
+@item x t
+Export a range of cells as tab-separated values (@code{ses-export-tsv}).
+@item x T
+Export a range of cells as tab-separated formulas (@code{ses-export-tsf}).
+@end table
+
+The exported text goes to the kill ring --- you can paste it into
+another buffer. Columns are separated by tabs, rows by newlines.
+
+To import text, use any of the yank commands where the text to paste
+contains tabs and/or newlines. Imported formulas are not relocated.
+
+@node Virus protection, Spreadsheets with details and summary, Import and export, Advanced Features
+@section Virus protection
+@cindex virus protection
+
+Whenever a formula or printer is read from a file or is pasted into
+the spreadsheet, it receives a ``needs safety check'' marking. Later,
+when the formula or printer is evaluated for the first time, it is
+checked for safety using the @code{unsafep} predicate; if found to be
+``possibly unsafe'', the questionable formula or printer is displayed
+and you must press Y to approve it or N to use a substitute. The
+substitute always signals an error.
+
+Formulas or printers that you type in are checked immediately for
+safety. If found to be possibly unsafe and you press N to disapprove,
+the action is canceled and the old formula or printer will remain.
+
+Besides viruses (which try to copy themselves to other files),
+@code{unsafep} can also detect all other kinds of Trojan horses, such as
+spreadsheets that delete files, send email, flood Web sites, alter
+your Emacs settings, etc.
+
+Generally, spreadsheet formulas and printers are simple things that
+don't need to do any fancy computing, so all potentially-dangerous
+parts of the Emacs Lisp environment can be excluded without cramping
+your style as a formula-writer. See the documentation in @file{unsafep.el}
+for more info on how Lisp forms are classified as safe or unsafe.
+
+@node Spreadsheets with details and summary, , Virus protection, Advanced Features
+@section Spreadsheets with details and summary
+@cindex details and summary
+@cindex summary, and details
+
+A common organization for spreadsheets is to have a bunch of ``detail''
+rows, each perhaps describing a transaction, and then a set of
+``summary'' rows that each show reduced data for some subset of the
+details. SES supports this organization via the @code{ses-select}
+function.
+
+@table @code
+@item (ses-select @var{fromrange} @var{test} @var{torange})
+Returns a subset of @var{torange}. For each member in @var{fromrange}
+that is equal to @var{test}, the corresponding member of @var{torange}
+is included in the result.
+@end table
+
+Example of use:
+@lisp
+(ses-average (ses-select (ses-range A1 A5) 'Smith (ses-range B1 B5)))
+@end lisp
+This computes the average of the B column values for those rows whose
+A column value is the symbol 'Smith.
+
+Arguably one could specify only @var{fromrange} plus
+@var{to-row-offset} and @var{to-column-offset}. The @var{torange} is
+stated explicitly to ensure that the formula will be recalculated if
+any cell in either range is changed.
+
+File @file{etc/ses-example.el} in the Emacs distribution is an example of a
+details-and-summary spreadsheet.
+
+
+@c ===================================================================
+
+@node For Gurus, Index, Advanced Features, Top
+@chapter For Gurus
+@cindex advanced features
+
+@menu
+* Deferred updates::
+* Nonrelocatable references::
+* The data area::
+* Buffer-local variables in spreadsheets::
+* Uses of defadvice in SES::
+@end menu
+
+@node Deferred updates, Nonrelocatable references, For Gurus, For Gurus
+@section Deferred updates
+@cindex deferred updates
+@cindex updates, deferred
+@vindex run-with-idle-timer
+
+To save time by avoiding redundant computations, cells that need
+recalculation due to changes in other cells are added to a set. At
+the end of the command, each cell in the set is recalculated once.
+This can create a new set of cells that need recalculation. The
+process is repeated until either the set is empty or it stops changing
+(due to circular references among the cells). In extreme cases, you
+might see progress messages of the form ``Recalculating... (@var{nnn}
+cells left)''. If you interrupt the calculation using @kbd{C-g}, the
+spreadsheet will be left in an inconsistent state, so use @kbd{C-_} or
+@kbd{C-c C-l} to fix it.
+
+To save even more time by avoiding redundant writes, cells that have
+changes are added to a set instead of being written immediately to the
+data area. Each cell in the set is written once, at the end of the
+command. If you change vast quantities of cells, you might see a
+progress message of the form ``Writing... (@var{nnn} cells left)''.
+These deferred cell-writes cannot be interrupted by @kbd{C-g}, so
+you'll just have to wait.
+
+SES uses @code{run-with-idle-timer} to move the cell underline when
+Emacs will be scrolling the buffer after the end of a command, and
+also to narrow and underline after @kbd{C-x C-v}. This is visible as
+a momentary glitch after C-x C-v and certain scrolling commands. You
+can type ahead without worrying about the glitch.
+
+
+@node Nonrelocatable references, The data area, Deferred updates, For Gurus
+@section Nonrelocatable references
+@cindex nonrelocatable references
+@cindex references, nonrelocatable
+
+@kbd{C-y} relocates all cell-references in a pasted formula, while
+@kbd{C-u C-y} relocates none of the cell-references. What about mixed
+cases?
+
+You can use
+@lisp
+(symbol-value 'B3)
+@end lisp
+to make an @dfn{absolute reference}. The formula relocator skips over
+quoted things, so this will not be relocated when pasted or when
+rows/columns are inserted/deleted. However, B3 will not be recorded
+as a dependency of this cell, so this cell will not be updated
+automatically when B3 is changed.
+
+The variables @code{row} and @code{col} are dynamically bound while a
+cell formula is being evaluated. You can use
+@lisp
+(ses-cell-value row 0)
+@end lisp
+to get the value from the leftmost column in the current row. This
+kind of dependency is also not recorded.
+
+
+@node The data area, Buffer-local variables in spreadsheets, Nonrelocatable references, For Gurus
+@section The data area
+@cindex data area
+@findex ses-reconstruct-all
+
+Begins with an 014 character, followed by sets of cell-definition
+macros for each row, followed by column-widths, column-printers,
+default-printer, and header-row. Then there's the global parameters
+(file-format ID, numrows, numcols) and the local variables (specifying
+SES mode for the buffer, etc.)
+
+When a SES file is loaded, first the numrows and numcols values are
+loaded, then the entire data area is @code{eval}ed, and finally the local
+variables are processed.
+
+You can edit the data area, but don't insert or delete any newlines
+except in the local-variables part, since SES locates things by
+counting newlines. Use @kbd{C-x C-e} at the end of a line to install
+your edits into the spreadsheet data structures (this does not update
+the print area, use e.g. @kbd{C-c C-l} for that).
+
+The data area is maintained as an image of spreadsheet data
+structures that area stored in buffer-local variables. If the data
+area gets messed up, you can try reconstructing the data area from the
+data structures:
+
+@table @kbd
+@item C-c M-C-l
+(@code{ses-reconstruct-all}).
+@end table
+
+
+@node Buffer-local variables in spreadsheets, Uses of defadvice in SES, The data area, For Gurus
+@section Buffer-local variables in spreadsheets
+@cindex buffer-local variables
+@cindex variables, buffer-local
+
+You can add additional local variables to the list at the bottom of
+the data area, such as hidden constants you want to refer to in your
+formulas.
+
+You can override the variable @code{symbolic-formulas} to be a list of
+symbols (as parenthesized strings) to show as completions for the '
+command. This initial completions list is used instead of the actual
+set of symbols-as-formulas in the spreadsheet.
+
+For examples of these, see file @file{etc/ses-example.ses}.
+
+If (for some reason) you want your formulas or printers to save data
+into variables, you must declare these variables as buffer-locals in
+order to avoid a virus warning.
+
+You can define functions by making them values for the fake local
+variable @code{eval}. Such functions can then be used in your
+formulas and printers, but usually each @code{eval} is presented to
+the user during file loading as a potential virus --- this can get
+annoying.
+
+You can define functions in your @file{.emacs} file. Other people can
+still read the print area of your spreadsheet, but they won't be able
+to recalculate or reprint anything that depends on your functions. To
+avoid virus warnings, each function used in a formula needs
+@lisp
+(put 'your-function-name 'safe-function t)
+@end lisp
+
+@node Uses of defadvice in SES, , Buffer-local variables in spreadsheets, For Gurus
+@section Uses of defadvice in SES
+@cindex defadvice
+@cindex undo-more
+@cindex copy-region-as-kill
+@cindex yank
+
+@table @code
+@item undo-more
+Defines a new undo element format (@var{fun} . @var{args}), which
+means ``undo by applying @var{fun} to @var{args}''. For spreadsheet
+buffers, it allows undos in the data area even though that's outside
+the narrowing.
+
+@item copy-region-as-kill
+When copying from the print area of a spreadsheet, treat the region as
+a rectangle and attach each cell's formula and printer as 'ses
+properties.
+
+@item yank
+When yanking into the print area of a spreadsheet, first try to yank
+as cells (if the yank text has 'ses properties), then as tab-separated
+formulas, then (if all else fails) as a single formula for the current
+cell.
+@end table
+
+@c ===================================================================
+@node Index, Acknowledgements, For Gurus, Top
+@unnumbered Index
+
+@printindex cp
+
+@c ===================================================================
+
+@node Acknowledgements, GNU Free Documentation License, Index, Top
+@chapter Acknowledgements
+
+Coding by:
+@quotation
+Jonathan Yavner @email{jyavner@@member.fsf.org}@*
+Stefan Monnier @email{monnier@@gnu.org}
+@end quotation
+
+@noindent
+Texinfo manual by:
+@quotation
+Jonathan Yavner @email{jyavner@@member.fsf.org}@*
+Brad Collins <brad@@chenla.org>
+@end quotation
+
+@noindent
+Ideas from:
+@quotation
+Christoph Conrad @email{christoph.conrad@@gmx.de}@*
+CyberBob @email{cyberbob@@redneck.gacracker.org}@*
+Syver Enstad @email{syver-en@@online.no}@*
+Ami Fischman @email{fischman@@zion.bpnetworks.com}@*
+Thomas Gehrlein @email{Thomas.Gehrlein@@t-online.de}@*
+Chris F.A. Johnson @email{c.f.a.johnson@@rogers.com}@*
+Yusong Li @email{lyusong@@hotmail.com}@*
+Juri Linkov @email{juri@@jurta.org}@*
+Harald Maier @email{maierh@@myself.com}@*
+Alan Nash @email{anash@@san.rr.com}@*
+François Pinard @email{pinard@@iro.umontreal.ca}@*
+Pedro Pinto @email{ppinto@@cs.cmu.edu}@*
+Stefan Reichör @email{xsteve@@riic.at}@*
+Oliver Scholz @email{epameinondas@@gmx.de}@*
+Richard M. Stallman @email{rms@@gnu.org}@*
+Luc Teirlinck @email{teirllm@@dms.auburn.edu}@*
+J. Otto Tennant @email{jotto@@pobox.com}@*
+Jean-Philippe Theberge @email{jphil@@acs.pagesjaunes.fr}
+@end quotation
+
+@c ===================================================================
+
+@node GNU Free Documentation License, , Acknowledgements, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@bye
+
+@ignore
+ arch-tag: 10a4ee1c-7ef4-4c06-8b7a-f975e39f0dec
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+
+@setfilename ../info/sieve
+@settitle Emacs Sieve Manual
+@synindex fn cp
+@synindex vr cp
+@synindex pg cp
+
+@copying
+This file documents the Emacs Sieve package, for server-side mail filtering.
+
+Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007
+Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Sieve: (sieve). Managing Sieve scripts in Emacs.
+@end direntry
+@iftex
+@finalout
+@end iftex
+@setchapternewpage odd
+
+@titlepage
+@title Emacs Sieve Manual
+
+@author by Simon Josefsson
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+
+@node Top
+@top Sieve Support for Emacs
+
+This manual documents the Emacs Sieve package.
+
+It is intended as a users manual for Sieve Mode and Manage Sieve, and
+as a reference manual for the @samp{sieve-manage} protocol Emacs Lisp
+API.
+
+Sieve is a language for server-side filtering of mail. The language
+is documented in RFC 3028. This manual does not attempt to document
+the language, so keep RFC 3028 around.
+
+A good online Sieve resources is @uref{http://www.cyrusoft.com/sieve/}.
+
+@menu
+* Installation:: Getting ready to use the package.
+* Sieve Mode:: Editing Sieve scripts.
+* Managing Sieve:: Managing Sieve scripts on a remote server.
+* Examples :: A few Sieve code snippets.
+* Manage Sieve API :: Interfacing to the Manage Sieve Protocol API.
+* Standards:: A summary of RFCs and working documents used.
+* GNU Free Documentation License:: The license for this documentation.
+* Index:: Function and variable index.
+@end menu
+
+
+@node Installation
+@chapter Installation
+@cindex Install
+@cindex Setup
+
+The Sieve package should come with your Emacs version, and should be
+ready for use directly.
+
+However, to manually set up the package you can put the following
+commands in your @code{~/.emacs}:
+
+@lisp
+(autoload 'sieve-mode "sieve-mode")
+@end lisp
+@lisp
+(setq auto-mode-alist (cons '("\\.s\\(v\\|iv\\|ieve\\)\\'" . sieve-mode)
+ auto-mode-alist))
+@end lisp
+
+
+@node Sieve Mode
+@chapter Sieve Mode
+
+Sieve mode provides syntax-based indentation, font-locking support and
+other handy functions to make editing Sieve scripts easier.
+
+Use @samp{M-x sieve-mode} to switch to this major mode. This command
+runs the hook @code{sieve-mode-hook}.
+
+@vindex sieve-mode-map
+@vindex sieve-mode-syntax-table
+Sieve mode is derived from @code{c-mode}, and is very similar except
+for the syntax of comments. The keymap (@code{sieve-mode-map}) is
+inherited from @code{c-mode}, as are the variables for customizing
+indentation. Sieve mode has its own abbrev table
+(@code{sieve-mode-abbrev-table}) and syntax table
+(@code{sieve-mode-syntax-table}).
+
+In addition to the editing utility functions, Sieve mode also contains
+bindings to manage Sieve scripts remotely. @xref{Managing Sieve}.
+
+@table @kbd
+
+@item C-c RET
+@kindex C-c RET
+@findex sieve-manage
+@cindex manage remote sieve script
+Open a connection to a remote server using the Managesieve protocol.
+
+@item C-c C-l
+@kindex C-c C-l
+@findex sieve-upload
+@cindex upload sieve script
+Upload the Sieve script to the currently open server.
+
+@end table
+
+
+@node Managing Sieve
+@chapter Managing Sieve
+
+Manage Sieve is a special mode used to display Sieve scripts available
+on a remote server. It can be invoked with @kbd{M-x sieve-manage
+RET}, which queries the user for a server and if necessary, user
+credentials to use.
+
+When a server has been successfully contacted, the Manage Sieve buffer
+looks something like:
+
+@example
+Server : mailserver:2000
+
+2 scripts on server, press RET on a script name edits it, or
+press RET on <new script> to create a new script.
+ <new script>
+ ACTIVE .sieve
+ template.siv
+@end example
+
+One of the scripts are highlighted, and standard point navigation
+commands (@kbd{<up>}, @kbd{<down>} etc) can be used to navigate the
+list.
+
+The following commands are available in the Manage Sieve buffer:
+
+@table @kbd
+
+@item m
+@kindex m
+@findex sieve-activate
+Activates the currently highlighted script.
+
+@item u
+@kindex u
+@findex sieve-deactivate
+Deactivates the currently highlighted script.
+
+@item C-M-?
+@kindex C-M-?
+@findex sieve-deactivate-all
+Deactivates all scripts.
+
+@item r
+@kindex r
+@findex sieve-remove
+Remove currently highlighted script.
+
+@item RET
+@item mouse-2
+@item f
+@kindex RET
+@kindex mouse-2
+@kindex f
+@findex sieve-edit-script
+Bury the server buffer and download the currently highlighted script
+into a new buffer for editing in Sieve mode (@pxref{Sieve Mode}).
+
+@item o
+@kindex o
+@findex sieve-edit-script-other-window
+Create a new buffer in another window containing the currently
+highlighted script for editing in Sieve mode (@pxref{Sieve Mode}).
+
+@item q
+@kindex q
+@findex sieve-bury-buffer
+Bury the Manage Sieve buffer without closing the connection.
+
+@item ?
+@item h
+@kindex ?
+@kindex h
+@findex sieve-help
+Displays help in the minibuffer.
+
+@end table
+
+@node Examples
+@chapter Examples
+
+If you are not familiar with Sieve, this chapter contains a few simple
+code snippets that you can cut'n'paste and modify at will, until you
+feel more comfortable with the Sieve language to write the rules from
+scratch.
+
+The following complete Sieve script places all messages with a matching
+@samp{Sender:} header into the given mailbox. Many mailing lists uses
+this format. The first line makes sure your Sieve server understands
+the @code{fileinto} command.
+
+@example
+require "fileinto";
+
+if address "sender" "owner-w3-beta@@xemacs.org" @{
+ fileinto "INBOX.w3-beta";
+@}
+@end example
+
+A few mailing lists do not use the @samp{Sender:} header, but does
+contain some unique identifier in some other header. The following is
+not a complete script, it assumes that @code{fileinto} has already been
+required.
+
+@example
+if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{
+ fileinto "INBOX.auc-tex";
+@}
+@end example
+
+At last, we have the hopeless mailing lists that does not have any
+unique identifier and you are forced to match on the @samp{To:} and
+@samp{Cc} headers. As before, this snippet assumes that @code{fileinto}
+has been required.
+
+@example
+if address ["to", "cc"] "kerberos@@mit.edu" @{
+ fileinto "INBOX.kerberos";
+@}
+@end example
+
+@node Manage Sieve API
+@chapter Manage Sieve API
+
+The @file{sieve-manage.el} library contains low-level functionality
+for talking to a server with the @sc{managesieve} protocol.
+
+A number of user-visible variables exist, which all can be customized
+in the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}):
+
+@table @code
+
+@item sieve-manage-default-user
+@vindex sieve-manage-default-user
+Sets the default username.
+
+@item sieve-manage-default-port
+@vindex sieve-manage-default-port
+Sets the default port to use, the suggested port number is @code{2000}.
+
+@item sieve-manage-log
+@vindex sieve-manage-log
+If non-@code{nil}, should be a string naming a buffer where a protocol trace
+is dumped (for debugging purposes).
+
+@end table
+
+The API functions include:
+
+@table @code
+
+@item sieve-manage-open
+@findex sieve-manage-open
+Open connection to managesieve server, returning a buffer to be used
+by all other API functions.
+
+@item sieve-manage-opened
+@findex sieve-manage-opened
+Check if a server is open or not.
+
+@item sieve-manage-close
+@findex sieve-manage-close
+Close a server connection.
+
+@item sieve-manage-authenticate
+@findex sieve-manage-authenticate
+Authenticate to the server.
+
+@item sieve-manage-capability
+@findex sieve-manage-capability
+Return a list of capabilities the server supports.
+
+@item sieve-manage-listscripts
+@findex sieve-manage-listscripts
+List scripts on the server.
+
+@item sieve-manage-havespace
+@findex sieve-manage-havespace
+Return non-@code{nil} if the server has room for a script of given
+size.
+
+@item sieve-manage-getscript
+@findex sieve-manage-getscript
+Download script from server.
+
+@item sieve-manage-putscript
+@findex sieve-manage-putscript
+Upload script to server.
+
+@item sieve-manage-setactive
+@findex sieve-manage-setactive
+Indicate which script on the server should be active.
+
+@end table
+
+@node Standards
+@chapter Standards
+
+The Emacs Sieve package implements all or parts of a small but
+hopefully growing number of RFCs and drafts documents. This chapter
+lists the relevant ones. They can all be fetched from
+@uref{http://quimby.gnus.org/notes/}.
+
+@table @dfn
+
+@item RFC3028
+Sieve: A Mail Filtering Language.
+
+@item draft-martin-managesieve-03
+A Protocol for Remotely Managing Sieve Scripts
+
+@end table
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index
+@unnumbered Index
+@printindex cp
+
+@summarycontents
+@contents
+@bye
+
+@c End:
+
+@ignore
+ arch-tag: 6e3ad0af-2eaf-4f35-a081-d40f4a683ec3
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@setfilename ../info/smtpmail
+@settitle Emacs SMTP Library
+@syncodeindex vr fn
+@copying
+Copyright @copyright{} 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
+and with the Back-Cover Texts as in (a) below. A copy of the license
+is included in the section entitled ``GNU Free Documentation License''
+in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* SMTP: (smtpmail). Emacs library for sending mail via SMTP.
+@end direntry
+
+@titlepage
+@title{Emacs SMTP Library}
+@subtitle{An Emacs package for sending mail via SMTP}
+@author{Simon Josefsson, Alex Schroeder}
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Emacs SMTP Library
+
+@insertcopying
+@end ifnottex
+
+@menu
+* How Mail Works:: Brief introduction to mail concepts.
+* Emacs Speaks SMTP:: How to use the SMTP library in Emacs.
+* Authentication:: Authenticating yourself to the server.
+* Queued delivery:: Sending mail without an internet connection.
+* Server workarounds:: Mail servers with special requirements.
+* Debugging:: Tracking down problems.
+* GNU Free Documentation License:: The license for this documentation.
+
+Indices
+
+* Index:: Index over variables and functions.
+@end menu
+
+@node How Mail Works
+@chapter How Mail Works
+
+@cindex SMTP
+@cindex MTA
+ On the internet, mail is sent from mail host to mail host using the
+simple mail transfer protocol (SMTP). To send and receive mail, you
+must get it from and send it to a mail host. Every mail host runs a
+mail transfer agent (MTA) such as Exim that accepts mails and passes
+them on. The communication between a mail host and other clients does
+not necessarily involve SMTP, however. Here is short overview of what
+is involved.
+
+@cindex MUA
+ The mail program --- also called a mail user agent (MUA) ---
+usually sends outgoing mail to a mail host. When your computer is
+permanently connected to the internet, it might even be a mail host
+itself. In this case, the MUA will pipe mail to the
+@file{/usr/lib/sendmail} application. It will take care of your mail
+and pass it on to the next mail host.
+
+@cindex ISP
+ When you are only connected to the internet from time to time, your
+internet service provider (ISP) has probably told you which mail host
+to use. You must configure your MUA to use that mail host. Since you
+are reading this manual, you probably want to configure Emacs to use
+SMTP to send mail to that mail host. More on that in the next
+section.
+
+@cindex MDA
+ Things are different when reading mail. The mail host responsible
+for your mail keeps it in a file somewhere. The messages get into the
+file by way of a mail delivery agent (MDA) such as procmail. These
+delivery agents often allow you to filter and munge your mails before
+you get to see it. When your computer is that mail host, this file is
+called a spool, and sometimes located in the directory
+@file{/var/spool/mail/}. All your MUA has to do is read mail from the
+spool, then.
+
+@cindex POP3
+@cindex IMAP
+ When your computer is not always connected to the internet, you
+must get the mail from the remote mail host using a protocol such as
+POP3 or IMAP. POP3 essentially downloads all your mail from the mail
+host to your computer. The mail is stored in some file on your
+computer, and again, all your MUA has to do is read mail from the
+spool.
+
+ When you read mail from various machines, downloading mail from the
+mail host to your current machine is not convenient. In that case,
+you will probably want to use the IMAP protocol. Your mail is kept on
+the mail host, and you can read it while you are connected via IMAP to
+the mail host.
+
+@cindex Webmail
+ So how does reading mail via the web work, you ask. In that case,
+the web interface just allows you to remote-control a MUA on the web
+host. Whether the web host is also a mail host, and how all the
+pieces interact is completely irrelevant. You usually cannot use
+Emacs to read mail via the web, unless you use software that parses
+the ever-changing HTML of the web interface.
+
+@node Emacs Speaks SMTP
+@chapter Emacs Speaks SMTP
+
+ Emacs includes a package for sending your mail to a SMTP server and
+have it take care of delivering it to the final destination, rather
+than letting the MTA on your local system take care of it. This can
+be useful if you don't have a MTA set up on your host, or if your
+machine is often disconnected from the internet.
+
+ Sending mail via SMTP requires configuring your mail user agent
+(@pxref{Mail Methods,,,emacs}) to use the SMTP library. How to do
+this should be described for each mail user agent; for the default
+mail user agent the variable @code{send-mail-function} (@pxref{Mail
+Sending,,,emacs}) is used; for the Message and Gnus user agents the
+variable @code{message-send-mail-function} (@pxref{Mail
+Variables,,,message}) is used.
+
+@example
+;; If you use the default mail user agent.
+(setq send-mail-function 'smtpmail-send-it)
+;; If you use Message or Gnus.
+(setq message-send-mail-function 'smtpmail-send-it)
+@end example
+
+ Before using SMTP you must find out the hostname of the SMTP server
+to use. Your system administrator should provide you with this
+information, but often it is the same as the server you receive mail
+from.
+
+@table @code
+@item smtpmail-smtp-server
+@vindex smtpmail-smtp-server
+@vindex SMTPSERVER
+ The variable @code{smtpmail-smtp-server} controls the hostname of
+the server to use. It is a string with an IP address or hostname. It
+defaults to the contents of the @env{SMTPSERVER} environment
+variable, or, if empty, the contents of
+@code{smtpmail-default-smtp-server}.
+
+@item smtpmail-default-smtp-server
+@vindex smtpmail-default-smtp-server
+ The variable @code{smtpmail-default-smtp-server} controls the
+default hostname of the server to use. It is a string with an IP
+address or hostname. It must be set before the SMTP library is
+loaded. It has no effect if set after the SMTP library has been
+loaded, or if @code{smtpmail-smtp-server} is defined. It is usually
+set by system administrators in a site wide initialization file.
+@end table
+
+The following example illustrates what you could put in
+@file{~/.emacs} to set the SMTP server name.
+
+@example
+;; Send mail using SMTP via mail.example.org.
+(setq smtpmail-smtp-server "mail.example.org")
+@end example
+
+@cindex Mail Submission
+SMTP is normally used on the registered ``smtp'' TCP service port 25.
+Some environments use SMTP in ``Mail Submission'' mode, which uses
+port 587. Using other ports is not uncommon, either for security by
+obscurity purposes, port forwarding, or otherwise.
+
+@table @code
+@item smtpmail-smtp-service
+@vindex smtpmail-smtp-service
+ The variable @code{smtpmail-smtp-service} controls the port on the
+server to contact. It is either a string, in which case it will be
+translated into an integer using system calls, or an integer.
+@end table
+
+The following example illustrates what you could put in
+@file{~/.emacs} to set the SMTP service port.
+
+@example
+;; Send mail using SMTP on the mail submission port 587.
+(setq smtpmail-smtp-service 587)
+@end example
+
+@node Authentication
+@chapter Authentication
+
+@cindex SASL
+@cindex CRAM-MD5
+@cindex LOGIN
+@cindex STARTTLS
+@cindex TLS
+@cindex SSL
+Many environments require SMTP clients to authenticate themselves
+before they are allowed to route mail via a server. The two following
+variables contains the authentication information needed for this.
+
+The first variable, @code{smtpmail-auth-credentials}, instructs the
+SMTP library to use a SASL authentication step, currently only the
+CRAM-MD5 and LOGIN mechanisms are supported and will be selected in
+that order if the server support both.
+
+The second variable, @code{smtpmail-starttls-credentials}, instructs
+the SMTP library to connect to the server using STARTTLS. This means
+the protocol exchange may be integrity protected and confidential by
+using the Transport Layer Security (TLS) protocol, and optionally also
+authentication of the client and server.
+
+TLS is a security protocol that is also known as SSL, although
+strictly speaking, SSL is an older variant of TLS. TLS is backwards
+compatible with SSL. In most mundane situations, the two terms are
+equivalent.
+
+The TLS feature uses the elisp package @file{starttls.el} (see it for
+more information on customization), which in turn require that at
+least one of the following external tools are installed:
+
+@enumerate
+@item
+The GNUTLS command line tool @samp{gnutls-cli}, you can get it from
+@url{http://www.gnu.org/software/gnutls/}. This is the recommended
+tool, mainly because it can verify the server certificates.
+
+@item
+The @samp{starttls} external program, you can get it from
+@file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}.
+@end enumerate
+
+It is not uncommon to use both these mechanisms, e.g., to use STARTTLS
+to achieve integrity and confidentiality and then use SASL for client
+authentication.
+
+@table @code
+@item smtpmail-auth-credentials
+@vindex smtpmail-auth-credentials
+ The variable @code{smtpmail-auth-credentials} contains a list of
+hostname, port, username and password tuples. When the SMTP library
+connects to a host on a certain port, this variable is searched to
+find a matching entry for that hostname and port. If an entry is
+found, the authentication process is invoked and the credentials are
+used.
+
+The hostname field follows the same format as
+@code{smtpmail-smtp-server} (i.e., a string) and the port field the
+same format as @code{smtpmail-smtp-service} (i.e., a string or an
+integer). The username and password fields, which either can be
+@code{nil} to indicate that the user is prompted for the value
+interactively, should be strings with the username and password,
+respectively, information that is normally provided by system
+administrators.
+
+@item smtpmail-starttls-credentials
+@vindex smtpmail-starttls-credentials
+ The variable @code{smtpmail-starttls-credentials} contains a list of
+tuples with hostname, port, name of file containing client key, and
+name of file containing client certificate. The processing is similar
+to the previous variable. The client key and certificate may be
+@code{nil} if you do not wish to use client authentication.
+@end table
+
+The following example illustrates what you could put in
+@file{~/.emacs} to enable both SASL authentication and STARTTLS. The
+server name (@code{smtpmail-smtp-server}) is @var{hostname}, the
+server port (@code{smtpmail-smtp-service}) is @var{port}, and the
+username and password are @var{username} and @var{password}
+respectively.
+
+@example
+;; Authenticate using this username and password against my server.
+(setq smtpmail-auth-credentials
+ '(("@var{hostname}" "@var{port}" "@var{username}" "@var{password}")))
+
+;; Note that if @var{port} is an integer, you must not quote it as a
+;; string. Normally @var{port} should be the integer 25, and the example
+;; become:
+(setq smtpmail-auth-credentials
+ '(("@var{hostname}" 25 "@var{username}" "@var{password}")))
+
+;; Use STARTTLS without authentication against the server.
+(setq smtpmail-starttls-credentials
+ '(("@var{hostname}" "@var{port}" nil nil)))
+@end example
+
+@node Queued delivery
+@chapter Queued delivery
+
+@cindex Dialup connection
+If you connect to the internet via a dialup connection, or for some
+other reason don't have permanent internet connection, sending mail
+will fail when you are not connected. The SMTP library implements
+queued delivery, and the following variable control its behavior.
+
+@table @code
+@item smtpmail-queue-mail
+@vindex smtpmail-queue-mail
+ The variable @code{smtpmail-queue-mail} controls whether a simple
+off line mail sender is active. This variable is a boolean, and
+defaults to @code{nil} (disabled). If this is non-@code{nil}, mail is
+not sent immediately but rather queued in the directory
+@code{smtpmail-queue-dir} and can be later sent manually by invoking
+@code{smtpmail-send-queued-mail} (typically when you connect to the
+internet).
+
+@item smtpmail-queue-dir
+@vindex smtpmail-queue-dir
+ The variable @code{smtpmail-queue-dir} specifies the name of the
+directory to hold queued messages. It defaults to
+@file{~/Mail/queued-mail/}.
+@end table
+
+@findex smtpmail-send-queued-mail
+ The function @code{smtpmail-send-queued-mail} can be used to send
+any queued mail when @code{smtpmail-queue-mail} is enabled. It is
+typically invoked interactively with @kbd{M-x
+smtpmail-send-queued-mail RET} when you are connected to the internet.
+
+@node Server workarounds
+@chapter Server workarounds
+
+Some SMTP servers have special requirements. The following variables
+implement support for common requirements.
+
+@table @code
+
+@item smtpmail-local-domain
+@vindex smtpmail-local-domain
+ The variable @code{smtpmail-local-domain} controls the hostname sent
+in the first @code{EHLO} or @code{HELO} command sent to the server.
+It should only be set if the @code{system-name} function returns a
+name that isn't accepted by the server. Do not set this variable
+unless your server complains.
+
+@item smtpmail-sendto-domain
+@vindex smtpmail-sendto-domain
+ The variable @code{smtpmail-sendto-domain} makes the SMTP library
+add @samp{@@} and the specified value to recipients specified in the
+message when they are sent using the @code{RCPT TO} command. Some
+configurations of sendmail requires this behavior. Don't bother to
+set this unless you have get an error like:
+
+@example
+ Sending failed; SMTP protocol error
+@end example
+
+when sending mail, and the debug buffer (@pxref{Debugging})) contains
+an error such as:
+
+@example
+ RCPT TO: @var{someone}
+ 501 @var{someone}: recipient address must contain a domain
+@end example
+
+@end table
+
+
+@node Debugging
+@chapter Debugging
+
+Sometimes delivery fails, often with the generic error message
+@samp{Sending failed; SMTP protocol error}. Enabling one or both of
+the following variables and inspecting a trace buffer will often give
+clues to the reason for the error.
+
+@table @code
+
+@item smtpmail-debug-info
+@vindex smtpmail-debug-info
+ The variable @code{smtpmail-debug-info} controls whether to print
+the SMTP protocol exchange in the minibuffer, and retain the entire
+exchange in a buffer @samp{*trace of SMTP session to @var{server}*},
+where @var{server} is the name of the mail server to which you send
+mail.
+
+@item smtpmail-debug-verb
+@vindex smtpmail-debug-verb
+ The variable @code{smtpmail-debug-verb} controls whether to send the
+@code{VERB} token to the server. The @code{VERB} server instructs the
+server to be more verbose, and often also to attempt final delivery
+while your SMTP session is still running. It is usually only useful
+together with @code{smtpmail-debug-info}. Note that this may cause
+mail delivery to take considerable time if the final destination
+cannot accept mail.
+
+@end table
+
+@node GNU Free Documentation License
+@chapter GNU Free Documentation License
+@include doclicense.texi
+
+@node Index
+@chapter Index
+
+@section Concept Index
+
+@printindex cp
+
+@section Function and Variable Index
+
+@printindex fn
+
+@contents
+@bye
+
+@ignore
+ arch-tag: 6316abdf-b366-4562-87a2-f37e8f894b6f
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+
+@setfilename ../info/speedbar
+@settitle Speedbar: File/Tag summarizing utility
+@syncodeindex fn cp
+
+@copying
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
+2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
+``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Speedbar: (speedbar). File/Tag summarizing utility.
+@end direntry
+
+@titlepage
+@sp 10
+@center @titlefont{Speedbar}
+@sp 2
+@center Eric Ludlam
+@vskip 0pt plus 1 fill
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@node Top, , , (dir)Top
+@comment node-name, next, previous, up
+
+Speedbar is a program for Emacs which can be used to summarize
+information related to the current buffer. Its original inspiration
+is the `explorer' often used in modern development environments, office
+packages, and web browsers.
+
+Speedbar displays a narrow frame in which a tree view is shown. This
+tree view defaults to containing a list of files and directories. Files
+can be `expanded' to list tags inside. Directories can be expanded to
+list the files within itself. Each file or tag can be jumped to
+immediately.
+
+Speedbar expands upon `explorer' windows by maintaining context with the
+user. For example, when using the file view, the current buffer's file
+is highlighted. Speedbar also mimics the explorer windows by providing
+multiple display modes. These modes come in two flavors. Major display
+modes remain consistent across buffers, and minor display modes appear
+only when a buffer of the applicable type is shown. This allows
+authors of other packages to provide speedbar summaries customized to
+the needs of that mode.
+
+Throughout this manual, activities are defined as `clicking on', or
+`expanding' items. Clicking means using @kbd{Mouse-2} on a
+button. Expanding refers to clicking on an expansion button to display
+an expanded summary of the entry the expansion button is
+on. @xref{Basic Navigation}.
+
+@menu
+* Introduction:: Basics of speedbar.
+* Basic Navigation:: Basics of speedbar common between all modes.
+* File Mode:: Summarizing files.
+* Buffer Mode:: Summarizing buffers.
+* Minor Modes:: Additional minor modes such as Info and RMAIL.
+* Customizing:: Changing speedbar behavior.
+* Extending:: Extend speedbar for your own project.
+* GNU Free Documentation License:: The license for this documentation.
+* Index::
+@end menu
+
+@node Introduction, Basic Navigation, , Top
+@comment node-name, next, previous, up
+@chapter Introduction
+@cindex introduction
+
+To start using speedbar use the command @kbd{M-x speedbar RET} or
+select it from the @samp{Options->Show/Hide} sub-menu. This command
+will open a new frame to summarize the local files. On X Window
+systems or on MS-Windows, speedbar's frame is twenty characters wide,
+and will mimic the height of the frame from which it was started. It
+positions itself to the left or right of the frame you started it
+from.
+
+To use speedbar effectively, it is important to understand its
+relationship with the frame you started it from. This frame is the
+@dfn{attached frame} which speedbar will use as a reference point. Once
+started, speedbar watches the contents of this frame, and attempts to
+make its contents relevant to the buffer loaded into the attached
+frame. In addition, all requests made in speedbar that require the
+display of another buffer will display in the attached frame.
+
+When used in terminal mode, the new frame appears the same size as the
+terminal. Since it is not visible while working in the attached frame,
+speedbar will save time by using the @dfn{slowbar mode}, where no tracking is
+done until speedbar is requested to show itself (i.e., the speedbar's
+frame becomes the selected frame).
+
+@cindex @code{speedbar-get-focus}
+The function to use when switching between frames using the keyboard is
+@code{speedbar-get-focus}. This function will toggle between frames, and
+it's useful to bind it to a key in terminal mode. @xref{Customizing}.
+
+@node Basic Navigation, File Mode, Introduction, Top
+@comment node-name, next, previous, up
+@chapter Basic Navigation
+
+Speedbar can display different types of data, and has several display
+and behavior modes. These modes all have a common behavior, menu
+system, and look. If one mode is learned, then the other modes are easy
+to use.
+
+@menu
+* Basic Key Bindings::
+* Basic Visuals::
+* Mouse Bindings::
+* Displays Submenu::
+@end menu
+
+@node Basic Key Bindings, Basic Visuals, Basic Navigation, Basic Navigation
+@comment node-name, next, previous, up
+@section Basic Key Bindings
+@cindex key bindings
+
+These key bindings are common across all modes:
+
+@table @kbd
+@item Q
+@cindex quitting speedbar
+Quit speedbar, and kill the frame.
+@item q
+Quit speedbar, and hide the frame. This makes it faster to restore the
+speedbar frame, than if you press @kbd{Q}.
+@item g
+@cindex refresh speedbar display
+Refresh whatever contents are in speedbar.
+@item t
+@cindex slowbar mode
+Toggle speedbar to and from slowbar mode. In slowbar mode, frame
+tracking is not done.
+@item n
+@itemx p
+@cindex navigation
+Move, respectively, to the next or previous item. A summary of that
+item will be displayed in the attached frame's minibuffer.
+@item M-n
+@itemx M-p
+Move to the next or previous item in a restricted fashion. If a list is
+open, the cursor will skip over it. If the cursor is in an open list,
+it will not leave it.
+@item C-M-n
+@itemx C-M-n
+Move forwards and backwards across extended groups. This lets you
+quickly skip over all files, directories, or other common sub-items at
+the same current depth.
+@item C-x b
+Switch buffers in the attached frame.
+@end table
+
+Speedbar can handle multiple modes. Two are provided by default.
+These modes are File mode, and Buffers mode. There are accelerators to
+switch into these different modes.
+
+@cindex mode switching hotkeys
+@table @kbd
+@item b
+Switch into Quick Buffers mode (@pxref{Buffer Mode}). After one use, the
+previous display mode is restored.
+@item f
+Switch into File mode.
+@item r
+Switch back to the previous mode.
+@end table
+
+Some modes provide groups, lists and tags. @xref{Basic Visuals}. When
+these are available, some additional common bindings are available.
+
+@cindex common keys
+@table @kbd
+@item RET
+@itemx e
+Edit/Open the current group or tag. This behavior is dependent on the
+mode. In general, files or buffers are opened in the attached frame,
+and directories or group nodes are expanded locally.
+@item +
+@itemx =
+Expand the current group, displaying sub items.
+When used with a prefix argument, any data that may have been cached is
+flushed. This is similar to a power click. @xref{Mouse Bindings}.
+@item -
+Contract the current group, hiding sub items.
+@end table
+
+@node Basic Visuals, Mouse Bindings, Basic Key Bindings, Basic Navigation
+@comment node-name, next, previous, up
+@section Basic Visuals
+@cindex visuals
+
+Speedbar has visual cues for indicating different types of data. These
+cues are used consistently across the different speedbar modes to make
+them easier to interpret.
+
+At a high level, in File mode, there are directory buttons, sub
+directory buttons, file buttons, tag buttons, and expansion buttons.
+This makes it easy to use the mouse to navigate a directory tree, and
+quickly view files, or a summary of those files.
+
+The most basic visual effect used to distinguish between these button
+types is color and mouse highlighting. Anything the mouse highlights
+can be clicked on and is called a button (@pxref{Mouse Bindings}).
+Anything not highlighted by the mouse will not be clickable.
+
+Text in speedbar consists of four different types of data. Knowing how
+to read these textual elements will make it easier to navigate by
+identifying the types of data available.
+
+@subsubsection Groups
+@cindex groups
+
+Groups summarize information in a single line, and provide a high level
+view of more complex systems, like a directory tree, or manual chapters.
+
+Groups appear at different indentation levels, and are prefixed with a
+@samp{+} in some sort of `box'. The group name will summarize the
+information within it, and the expansion box will display that
+information inline. In File mode, directories and files are `groups'
+where the @samp{+} is surrounded by brackets like this:
+
+@example
+<+> include
+<-> src
+ [+] foo.c
+@end example
+
+In this example, we see both open and closed directories, in addition to
+a file. The directories have a box consisting of angle brackets, and a
+file uses square brackets.
+
+In all modes, a group can be `edited' by pressing @kbd{RET}, meaning a
+file will be opened, or a directory explicitly opened in speedbar. A
+group can be expanded or contracted using @kbd{+} or
+@kbd{-}. @xref{Basic Key Bindings}.
+
+Sometimes groups may have a @samp{?} in its indicator box. This means
+that it is a group type, but there are no contents, or no known way of
+extracting contents of that group.
+
+When a group has been expanded, the indicator button changes from
+@samp{+} to @samp{-}. This indicates that the contents are being shown.
+Click the @samp{-} button to contract the group, or hide the contents
+currently displayed.
+
+@subsubsection Tags
+@cindex tags
+
+Tags are the leaf nodes of the tree system. Tags are generally prefixed
+with a simple character, such as @samp{>}. Tags can only be jumped to using
+@kbd{RET} or @kbd{e}.
+
+@subsubsection Boolean Flags
+
+Sometimes a group or tag is given a boolean flag. These flags appear as
+extra text characters at the end of the line. File mode uses boolean
+flags, such as a @samp{*} to indicate that a file has been checked out
+of a versioning system.
+
+For additional flags, see
+@c Note to self, update these to sub-nodes which are more relevant.
+@ref{File Mode}, and @ref{Version Control}.
+
+@subsubsection Unadorned Text
+
+Unadorned text generally starts in column 0, without any special symbols
+prefixing them. In Buffers mode different buffer groups are prefixed
+with a description of what the following buffers are (Files, scratch
+buffers, and invisible buffers.)
+
+Unadorned text will generally be colorless, and not clickable.
+
+@subsubsection Color Cues
+
+Each type of Group, item indicator, and label is given a different
+color. The colors chosen are dependent on whether the background color
+is light or dark.
+Of important note is that the `current item', which may be a buffer or
+file name, is highlighted red, and underlined.
+
+Colors can be customized from the group @code{speedbar-faces}. Some
+modes, such as for Info, will use the Info colors instead of default
+speedbar colors as an indication of what is currently being displayed.
+
+The face naming convention mirrors the File display mode. Modes which
+do not use files will attempt to use the same colors on analogous
+entries.
+
+@node Mouse Bindings, Displays Submenu, Basic Visuals, Basic Navigation
+@comment node-name, next, previous, up
+@section Mouse Bindings
+@cindex mouse bindings
+
+The mouse has become a common information navigation tool. Speedbar
+will use the mouse to navigate file systems, buffer lists, and other
+data. The different textual cues provide buttons which can be clicked
+on (@pxref{Basic Visuals}). Anything that highlights can be clicked on
+with the mouse, or affected by the menu.
+
+The mouse bindings are:
+
+@table @kbd
+@item Mouse-1
+Move cursor to that location.
+@item Mouse-2
+@itemx Double-Mouse-1
+Activate the current button. @kbd{Double-Mouse-1} is called a @dfn{double
+click} on other platforms, and is useful for windows users with two
+button mice.
+@c Isn't it true that with two-button mice, the right button is Mouse-2?
+@c On GNU/Linux, the right button is Mouse-3.
+@item S-Mouse-2
+@itemx S-Double-Mouse-1
+@cindex power click
+This has the same effect as @kbd{Mouse-2}, except it is called a power
+click. This means that if a group with an expansion button @samp{+} is
+clicked, any caches are flushed, and subitems re-read. If it is a name,
+it will be opened in a new frame.
+@item Mouse-3
+Activate the speedbar menu. The item selected affects the line clicked,
+not the line where the cursor was.
+@item Mouse-1 @r{(mode line)}
+Activate the menu. This affects the item the cursor is on before the
+click, since the mouse was not clicked on anything.
+@item C-Mouse-1
+Buffers sub-menu. The buffer in the attached frame is switched.
+@end table
+
+When the mouse moves over buttons in speedbar, details of that item
+should be displayed in the minibuffer of the attached frame. Sometimes
+this can contain extra information such as file permissions, or tag
+location.
+
+@node Displays Submenu, , Mouse Bindings, Basic Navigation
+@comment node-name, next, previous, up
+@section Displays Submenu
+@cindex displays submenu
+
+You can display different data by using different display modes. These
+specialized modes make it easier to navigate the relevant pieces of
+information, such as files and directories, or buffers.
+
+In the main menu, found by clicking @kbd{Mouse-3}, there is a submenu
+labeled @samp{Displays}. This submenu lets you easily choose between
+different display modes.
+
+The contents are modes currently loaded into emacs. By default, this
+would include Files, Quick Buffers, and Buffers. Other major display
+modes such as Info are loaded separately.
+
+@node File Mode, Buffer Mode, Basic Navigation, Top
+@comment node-name, next, previous, up
+@chapter File Mode
+@cindex file mode
+
+File mode displays a summary of your current directory. You can display
+files in the attached frame, or summarize the tags found in files. You
+can even see if a file is checked out of a version control system, or
+has some associated object file.
+
+Advanced behavior, like copying and renaming files, is also provided.
+
+@menu
+* Directory Display:: What the display means.
+* Hidden Files:: How to display hidden files.
+* File Key Bindings:: Performing file operations.
+@end menu
+
+@node Directory Display, Hidden Files, File Mode, File Mode
+@comment node-name, next, previous, up
+@section Directory Display
+@cindex directory display
+
+There are three major sections in the display. The first line or two is
+the root directory speedbar is currently viewing. You can jump to one
+of the parent directories by clicking on the name of the directory you
+wish to jump to.
+
+Next, directories are listed. A directory starts with the group
+indicator button @samp{<+>}. Clicking the directory name makes speedbar
+load that directory as the root directory for its display. Clicking the
+@samp{<+>} button will list all directories and files beneath.
+
+Next, files are listed. Files start with the group indicator @samp{[+]}
+or @samp{[?]}. You can jump to a file in the attached frame by clicking
+on the file name. You can expand a file and look at its tags by
+clicking on the @samp{[+]} symbol near the file name.
+
+A typical session might look like this:
+
+@example
+~/lisp/
+<+> checkdoc
+<+> eieio
+<-> speedbar
+ [+] Makefile
+ [+] rpm.el #
+ [+] sb-gud.el #
+ [+] sb-info.el #
+ [+] sb-rmail.el #
+ [+] sb-w3.el
+ [-] speedbar.el *!
+ @{+@} Types
+ @{+@} Variables
+ @{+@} def (group)
+ @{+@} speedbar-
+ [+] speedbar.texi *
+<+> testme
+[+] align.el
+[+] autoconf.el
+@end example
+
+In this example, you can see several directories. The directory
+@file{speedbar} has been opened inline. Inside the directory
+@file{speedbar}, the file @file{speedbar.el} has its tags exposed.
+These tags are extensive, and they are summarized into tag groups.
+
+Files get additional boolean flags associated with them. Valid flags are:
+
+@cindex file flags
+@table @code
+@item *
+This file has been checked out of a version control
+system. @xref{Version Control}.
+@cindex @code{speedbar-obj-alist}
+@item #
+This file has an up to date object file associated with it. The
+variable @code{speedbar-obj-alist} defines how speedbar determines this
+value.
+@item !
+This file has an out of date object file associated with it.
+@end table
+
+A Tag group is prefixed with the symbol @samp{@{+@}}. Clicking this
+symbol will show all symbols that have been organized into that group.
+Different types of files have unique tagging methods as defined by their
+major mode. Tags are generated with either the @code{imenu} package, or
+through the @code{etags} interface.
+
+Tag groups are defined in multiple ways which make it easier to find the
+tag you are looking for. Imenu keywords explicitly create groups, and
+speedbar will automatically create groups if tag lists are too long.
+
+In our example, Imenu created the groups @samp{Types} and
+@samp{Variables}. All remaining top-level symbols are then regrouped
+based on the variable @code{speedbar-tag-hierarchy-method}. The
+subgroups @samp{def} and @samp{speedbar-} are groupings where the first
+few characters of the given symbols are specified in the group name.
+Some group names may say something like @samp{speedbar-t to speedbar-v},
+indicating that all symbols which alphabetically fall between those
+categories are included in that sub-group. @xref{Tag Hierarchy Methods}.
+
+@node Hidden Files, File Key Bindings, Directory Display, File Mode
+@comment node-name, next, previous, up
+@section Hidden Files
+@cindex hidden files
+
+On GNU and Unix systems, a hidden file is a file whose name starts
+with a period. They are hidden from a regular directory listing
+because the user is not generally interested in them.
+
+In speedbar, a hidden file is a file which isn't very interesting and
+might prove distracting to the user. Any uninteresting files are
+removed from the File display. There are two levels of uninterest in
+speedbar. The first level of uninterest are files which have no
+expansion method, or way of extracting tags. The second level is any
+file that matches the same pattern used for completion in
+@code{find-file}. This is derived from the variable
+@code{completion-ignored-extensions}.
+
+You can toggle the display of uninteresting files from the toggle menu
+item @samp{Show All Files}. This will display all level one hidden files.
+These files will be shown with a @samp{?} indicator. Level 2 hidden
+files will still not be shown.
+
+Object files fall into the category of level 2 hidden files. You can
+determine their presence by the @samp{#} and @samp{!} file indicators.
+@xref{Directory Display}.
+
+@node File Key Bindings, , Hidden Files, File Mode
+@comment node-name, next, previous, up
+@section File Key Bindings
+@cindex file key bindings
+
+File mode has key bindings permitting different file system operations
+such as copy or rename. These commands all operate on the @dfn{current
+file}. In this case, the current file is the file at point, or clicked
+on when pulling up the menu.
+
+@table @kbd
+@item U
+Move the entire speedbar display up one directory.
+@item I
+Display information in the minibuffer about this line. This is the same
+information shown when navigating with @kbd{n} and @kbd{p}, or moving
+the mouse over an item.
+@item B
+Byte compile the Emacs Lisp file on this line.
+@item L
+Load the Emacs Lisp file on this line. If a @file{.elc} file exists,
+optionally load that.
+@item C
+Copy the current file to some other location.
+@item R
+Rename the current file, possibly moving it to some other location.
+@item D
+Delete the current file.
+@item O
+Delete the current file's object file. Use the symbols @samp{#} and
+@samp{!} to determine if there is an object file available.
+@end table
+
+One menu item toggles the display of all available files. By default,
+only files which Emacs understands, and knows how to convert into a tag
+list, are shown. By showing all files, additional files such as text files are
+also displayed, but they are prefixed with the @samp{[?]} symbol. This
+means that it is a file, but Emacs doesn't know how to expand it.
+
+@node Buffer Mode, Minor Modes, File Mode, Top
+@comment node-name, next, previous, up
+@chapter Buffer Mode
+@cindex buffer mode
+
+Buffer mode is very similar to File mode, except that instead of
+tracking the current directory and all files available there, the
+current list of Emacs buffers is shown.
+
+These buffers can have their tags expanded in the same way as files,
+and uses the same unknown file indicator (@pxref{File Mode}).
+
+Buffer mode does not have file operation bindings, but the following
+buffer specific key bindings are available:
+
+@table @kbd
+@item k
+Kill this buffer. Do not touch its file.
+@item r
+Revert this buffer, reloading from disk.
+@end table
+
+In addition to Buffer mode, there is also Quick Buffer mode. In fact,
+Quick Buffers is bound to the @kbd{b} key. The only difference between
+Buffers and Quick Buffers is that after one operation is performed
+which affects the attached frame, the display is immediately reverted to
+the last displayed mode.
+
+Thus, if you are in File mode, and you need quick access to a buffer,
+press @kbd{b}, click on the buffer you want, and speedbar will revert
+back to File mode.
+
+@node Minor Modes, Customizing, Buffer Mode, Top
+@comment node-name, next, previous, up
+@chapter Minor Display Modes
+@cindex minor display modes
+
+For some buffers, a list of files and tags makes no sense. This could
+be because files are not currently in reference (such as web pages), or
+that the files you might be interested have special properties (such as
+email folders.)
+
+In these cases, a minor display mode is needed. A minor display mode
+will override any major display mode currently being displayed for the
+duration of the specialized buffer's use. Minor display modes
+will follow the general rules of their major counterparts in terms of
+key bindings and visuals, but will have specialized behaviors.
+
+@menu
+* RMAIL:: Managing folders.
+* Info:: Browsing topics.
+* GDB:: Watching expressions or managing the current
+ stack trace.
+@end menu
+
+@node RMAIL, Info, Minor Modes, Minor Modes
+@comment node-name, next, previous, up
+@section RMAIL
+@cindex RMAIL
+
+When using RMAIL, speedbar will display two sections. The first is a
+layer one reply button. Clicking here will initialize a reply buffer
+showing only this email address in the @samp{To:} field.
+
+The second section lists all RMAIL folders in the same directory as your
+main RMAIL folder. The general rule is that RMAIL folders always appear
+in all caps, or numbers. It is possible to save mail in folders with
+lower case letters, but there is no clean way of detecting such RMAIL folders
+without opening them all.
+
+Each folder can be visited by clicking the name. You can move mail from
+the current RMAIL folder into a different folder by clicking the
+@samp{<M>} button. The @samp{M} stands for Move.
+
+In this way you can manage your existing RMAIL folders fairly easily
+using the mouse.
+
+@node Info, GDB, RMAIL, Minor Modes
+@comment node-name, next, previous, up
+@section Info
+@cindex Info
+
+When browsing Info files, all local relevant information is displayed in
+the info buffer and a topical high-level view is provided in speedbar.
+All top-level info nodes are shown in the speedbar frame, and can be
+jumped to by clicking the name.
+
+You can open these nodes with the @samp{[+]} button to see what sub-topics
+are available. Since these sub-topics are not examined until you click
+the @samp{[+]} button, sometimes a @samp{[?]} will appear when you click on
+a @samp{[+]}, indicating that there are no sub-topics.
+
+@node GDB, , Info, Minor Modes
+@comment node-name, next, previous, up
+@section GDB
+@cindex gdb
+@cindex gud
+
+You can debug an application with GDB in Emacs using graphical mode or
+text command mode (@pxref{GDB Graphical Interface,,, emacs, The
+extensible self-documenting text editor}).
+
+If you are using graphical mode you can see how selected variables
+change each time your program stops (@pxref{Watch Expressions,,,
+emacs, The extensible self-documenting text editor}).
+
+If you are using text command mode, speedbar can show
+you the current stack when the current buffer is the @file{*gdb*}
+buffer. Usually, it will just report that there is no stack, but when
+the application is stopped, the current stack will be shown.
+
+You can click on any stack element and gdb will move to that stack
+level. You can then check variables local to that level at the GDB
+prompt.
+
+@node Customizing, Extending, Minor Modes, Top
+@comment node-name, next, previous, up
+@chapter Customizing
+@cindex customizing
+
+Speedbar is highly customizable, with a plethora of control elements.
+Since speedbar is so visual and reduces so much information, this is an
+important aspect of its behavior.
+
+In general, there are three custom groups you can use to quickly modify
+speedbar's behavior.
+
+@table @code
+@item speedbar
+Basic speedbar behaviors.
+@item speedbar-vc
+Customizations regarding version control handling.
+@item speedbar-faces
+Customize speedbar's many colors and fonts.
+@end table
+
+@menu
+* Frames and Faces:: Visible behaviors.
+* Tag Hierarchy Methods:: Customizing how tags are displayed.
+* Version Control:: Adding new VC detection modes.
+* Hooks:: The many hooks you can use.
+@end menu
+
+@node Frames and Faces, Tag Hierarchy Methods, Customizing, Customizing
+@comment node-name, next, previous, up
+@section Frames and Faces
+@cindex faces
+@cindex frame parameters
+
+There are several faces speedbar generates to provide a consistent
+color scheme across display types. You can customize these faces using
+your favorite method. They are:
+
+@table @asis
+@cindex @code{speedbar-button-face}
+@item speedbar-button-face
+Face used on expand/contract buttons.
+@cindex @code{speedbar-file-face}
+@item speedbar-file-face
+Face used on Files. Should also be used on non-directory like nodes.
+@cindex @code{speedbar-directory-face}
+@item speedbar-directory-face
+Face used for directories, or nodes which consist of groups of other nodes.
+@cindex @code{speedbar-tag-face}
+@item speedbar-tag-face
+Face used for tags in a file, or for leaf items.
+@cindex @code{speedbar-selected-face}
+@item speedbar-selected-face
+Face used to highlight the selected item. This would be the current
+file being edited.
+@cindex @code{speedbar-highlight-face}
+@item speedbar-highlight-face
+Face used when the mouse passes over a button.
+@end table
+
+You can also customize speedbar's initial frame parameters. How this is
+accomplished is dependent on your platform being Emacs or XEmacs.
+
+@cindex @code{speedbar-frame-parameters}, Emacs
+In Emacs, change the alist @code{speedbar-frame-parameters}. This
+variable is used to set up initial details. Height is also
+automatically added when speedbar is created, though you can override
+it.
+
+@cindex @code{speedbar-frame-plist}, XEmacs
+In XEmacs, change the plist @code{speedbar-frame-plist}. This is the
+XEmacs way of doing the same thing.
+
+@node Tag Hierarchy Methods, Version Control, Frames and Faces, Customizing
+@comment node-name, next, previous, up
+@section Tag Hierarchy Methods
+@cindex tag hierarchy
+@cindex tag groups
+@cindex tag sorting
+
+When listing tags within a file, it is possible to get an annoyingly
+long list of entries. Imenu (which generates the tag list in Emacs)
+will group some classes of items automatically. Even here, however,
+some tag groups can be quite large.
+
+@cindex @code{speedbar-tag-hierarchy-method}
+To solve this problem, tags can be grouped into logical units through a
+hierarchy processor. The specific variable to use is
+@code{speedbar-tag-hierarchy-method}. There are several methods that
+can be applied in any order. They are:
+
+@table @code
+@cindex @code{speedbar-trim-words-tag-hierarchy}
+@item speedbar-trim-words-tag-hierarchy
+Find a common prefix for all elements of a group, and trim it off.
+@cindex @code{speedbar-prefix-group-tag-hierarchy}
+@item speedbar-prefix-group-tag-hierarchy
+If a group is too large, place sets of tags into bins based on common
+prefixes.
+@cindex @code{speedbar-simple-group-tag-hierarchy}
+@item speedbar-simple-group-tag-hierarchy
+Take all items in the top level list not in a group, and stick them into
+a @samp{Tags} group.
+@cindex @code{speedbar-sort-tag-hierarchy}
+@item speedbar-sort-tag-hierarchy
+Sort all items, leaving groups on top.
+@end table
+
+You can also add your own functions to reorganize tags as you see fit.
+
+Some other control variables are:
+
+@table @code
+@cindex @code{speedbar-tag-group-name-minimum-length}
+@item speedbar-tag-group-name-minimum-length
+Default value: 4.
+
+The minimum length of a prefix group name before expanding. Thus, if
+the @code{speedbar-tag-hierarchy-method} includes
+@code{speedbar-prefix-group-tag-hierarchy} and one such group's common
+characters is less than this number of characters, then the group name
+will be changed to the form of:
+
+@example
+worda to wordb
+@end example
+
+instead of just
+
+@example
+word
+@end example
+
+This way we won't get silly looking listings.
+
+@cindex @code{speedbar-tag-split-minimum-length}
+@item speedbar-tag-split-minimum-length
+Default value: 20.
+
+Minimum length before we stop trying to create sub-lists in tags.
+This is used by all tag-hierarchy methods that break large lists into
+sub-lists.
+
+@cindex @code{speedbar-tag-regroup-maximum-length}
+@item speedbar-tag-regroup-maximum-length
+Default value: 10.
+
+Maximum length of submenus that are regrouped.
+If the regrouping option is used, then if two or more short subgroups
+are next to each other, then they are combined until this number of
+items is reached.
+@end table
+
+@node Version Control, Hooks, Tag Hierarchy Methods, Customizing
+@comment node-name, next, previous, up
+@section Version Control
+@cindex version control
+@cindex vc extensions
+
+When using the file mode in speedbar, information regarding a version
+control system adds small details to the display. If a file is in a
+version control system, and is ``checked out'' or ``locked'' locally, an
+asterisk @samp{*} appears at the end of the file name. In addition,
+the directory name for Version Control systems are left out of the
+speedbar display.
+
+@cindex @code{speedbar-directory-unshown-regexp}
+You can easily add new version control systems into speedbar's detection
+scheme. To make a directory ``disappear'' from the list, use the variable
+@code{speedbar-directory-unshown-regexp}.
+
+@cindex @code{speedbar-vc-path-enable-hook}
+Next, you need to write entries for two hooks. The first is
+@code{speedbar-vc-path-enable-hook} which will enable a VC check in the
+current directory for the group of files being checked. Your hook
+function should take one parameter (the directory to check) and return
+@code{t} if your VC method is in control here.
+
+@cindex @code{speedbar-vc-in-control-hook}
+The second function is @code{speedbar-vc-in-control-hook}. This hook
+takes two parameters, the @var{path} of the file to check, and the
+@var{file} name. Return @code{t} if you want to have the asterisk
+placed near this file.
+
+@cindex @code{speedbar-vc-indicator}
+Lastly, you can change the VC indicator using the variable
+@code{speedbar-vc-indicator}, and specify a single character string.
+
+@node Hooks, , Version Control, Customizing
+@comment node-name, next, previous, up
+@section Hooks
+@cindex hooks
+
+There are several hooks in speedbar allowing custom behaviors to be
+added. Available hooks are:
+
+@table @code
+@cindex @code{speedbar-visiting-file-hook}
+@item speedbar-visiting-file-hook
+Hooks run when speedbar visits a file in the selected frame.
+@cindex @code{speedbar-visiting-tag-hook}
+@item speedbar-visiting-tag-hook
+Hooks run when speedbar visits a tag in the selected frame.
+@cindex @code{speedbar-load-hook}
+@item speedbar-load-hook
+Hooks run when speedbar is loaded.
+@cindex @code{speedbar-reconfigure-keymaps-hook}
+@item speedbar-reconfigure-keymaps-hook
+Hooks run when the keymaps are regenerated. Keymaps are reconfigured
+whenever modes change. This will let you add custom key bindings.
+@cindex @code{speedbar-before-popup-hook}
+@item speedbar-before-popup-hook
+Hooks called before popping up the speedbar frame.
+New frames are often popped up when ``power clicking'' on an item to view
+it.
+@cindex @code{speedbar-before-delete-hook}
+@item speedbar-before-delete-hook
+Hooks called before deleting or hiding the speedbar frame.
+@cindex @code{speedbar-mode-hook}
+@item speedbar-mode-hook
+Hooks called after creating a speedbar buffer.
+@cindex @code{speedbar-timer-hook}
+@item speedbar-timer-hook
+Hooks called after running the speedbar timer function.
+@cindex @code{speedbar-scanner-reset-hook}
+@item speedbar-scanner-reset-hook
+Hook called whenever generic scanners are reset.
+Set this to implement your own scanning or rescan safe functions with
+state data.
+@end table
+
+@node Extending, GNU Free Documentation License, Customizing, Top
+@comment node-name, next, previous, up
+@chapter Extending
+@cindex extending
+
+Speedbar can run different types of Major display modes such as Files
+(@pxref{File Mode}), and Buffers (@pxref{Buffer Mode}). It can also manage
+different minor display modes for use with buffers handling specialized
+data.
+
+These major and minor display modes are handled through an extension
+system which permits specialized keymaps and menu extensions, in
+addition to a unique rendering function. You can also specify a wide
+range of tagging functions. The default uses @code{imenu}, but new
+tagging methods can be easily added. In this chapter, you will
+learn how to write your own major or minor display modes, and how to
+create specialized tagging functions.
+
+@menu
+* Minor Display Modes:: How to create a minor display mode.
+* Major Display Modes:: How to create a major display mode.
+* Tagging Extensions:: How to create your own tagging methods.
+* Creating a display:: How to insert buttons and hierarchies.
+@end menu
+
+@node Minor Display Modes, Major Display Modes, Extending, Extending
+@section Minor Display Modes
+@cindex create minor display mode
+
+A @dfn{minor display mode} is a mode useful when using a specific type of
+buffer. This mode might not be useful for any other kind of data or
+mode, or may just be more useful that a files or buffers based mode when
+working with a specialized mode.
+
+Examples that already exist for speedbar include RMAIL, Info, and gdb.
+These modes display information specific to the major mode shown in the
+attached frame.
+
+To enable a minor display mode in your favorite Major mode, follow these
+steps. The string @samp{@var{name}} is the name of the major mode being
+augmented with speedbar.
+
+@enumerate
+@item
+Create the keymap variable @code{@var{name}-speedbar-key-map}.
+
+@item
+Create a function, named whatever you like, which assigns values into your
+keymap. Use this command to create the keymap before assigning
+bindings:
+
+@smallexample
+ (setq @var{name}-speedbar-key-map (speedbar-make-specialized-keymap))
+@end smallexample
+
+This function creates a special keymap for use in speedbar.
+
+@item
+Call your install function, or assign it to a hook like this:
+
+@smallexample
+(if (featurep 'speedbar)
+ (@var{name}-install-speedbar-variables)
+ (add-hook 'speedbar-load-hook '@var{name}-install-speedbar-variables))
+@end smallexample
+
+@item
+Create an easymenu compatible vector named
+@code{@var{name}-speedbar-menu-items}. This will be spliced into
+speedbar's control menu.
+
+@item
+Create a function called @code{@var{name}-speedbar-buttons}. This function
+should take one variable, which is the buffer for which it will create
+buttons. At this time @code{(current-buffer)} will point to the
+uncleared speedbar buffer.
+@end enumerate
+
+When writing @code{@var{name}-speedbar-buttons}, the first thing you will
+want to do is execute a check to see if you need to re-create your
+display. If it needs to be cleared, you need to erase the speedbar
+buffer yourself, and start drawing buttons. @xref{Creating a display}.
+
+@node Major Display Modes, Tagging Extensions, Minor Display Modes, Extending
+@section Major Display Modes
+@cindex create major display mode
+
+Creating a @dfn{Major Display Mode} for speedbar requires authoring a keymap,
+an easy-menu segment, and writing several functions. These items can be
+given any name, and are made the same way as in a minor display mode
+(@pxref{Minor Display Modes}). Once this is done, these items need to be
+registered.
+
+Because this setup activity may or may not have speedbar available when
+it is being loaded, it is necessary to create an install function. This
+function should create and initialize the keymap, and add your
+expansions into the customization tables.
+
+@cindex @code{speedbar-make-specialized-keymap}
+When creating the keymap, use the function
+@code{speedbar-make-specialized-keymap} instead of other keymap making
+functions. This will provide you with the initial bindings needed.
+Some common speedbar functions you might want to bind are:
+
+@table @code
+@cindex @code{speedbar-edit-line}
+@item speedbar-edit-line
+Edit the item on the current line.
+@cindex @code{speedbar-expand-line}
+@item speedbar-expand-line
+Expand the item under the cursor.
+With a numeric argument (@kbd{C-u}), flush cached data before expanding.
+@cindex @code{speedbar-contract-line}
+@item speedbar-contract-line
+Contract the item under the cursor.
+@end table
+
+@cindex @code{speedbar-line-path}
+These function require that function @code{speedbar-line-path} be
+correctly overloaded to work.
+
+Next, register your extension like this;
+
+@example
+ (speedbar-add-expansion-list '("MyExtension"
+ MyExtension-speedbar-menu-items
+ MyExtension-speedbar-key-map
+ MyExtension-speedbar-buttons))
+@end example
+
+There are no limitations to the names you use.
+
+The first parameter is the string representing your display mode.
+The second parameter is a variable name containing an easymenu compatible
+menu definition. This will be stuck in the middle of speedbar's menu.
+The third parameter is the variable name containing the keymap we
+discussed earlier.
+The last parameter is a function which draws buttons for your mode.
+This function must take two parameters. The directory currently being
+displayed, and the depth at which you should start rendering buttons.
+The function will then draw (starting at the current cursor position)
+any buttons deemed necessary based on the input parameters.
+@xref{Creating a display}.
+
+Next, you need to register function overrides. This may look something
+like this:
+
+@example
+(speedbar-add-mode-functions-list
+ '("MYEXTENSION"
+ (speedbar-item-info . MyExtension-speedbar-item-info)
+ (speedbar-line-path . MyExtension-speedbar-line-path)))
+@end example
+
+The first element in the list is the name of you extension. The second
+is an alist of functions to overload. The function to overload is
+first, followed by what you want called instead.
+
+For @code{speedbar-line-path} your function should take an optional DEPTH
+parameter. This is the starting depth for heavily indented lines. If
+it is not provided, you can derive it like this:
+
+@example
+(save-match-data
+ (if (not depth)
+ (progn
+ (beginning-of-line)
+ (looking-at "^\\([0-9]+\\):")
+ (setq depth (string-to-int (match-string 1)))))
+@end example
+
+@noindent
+where the depth is stored as invisible text at the beginning of each
+line.
+
+The path returned should be the full path name of the file associated
+with that line. If the cursor is on a tag, then the file containing
+that tag should be returned. This is critical for built in file based
+functions to work (meaning less code for you to write). If your display
+does not deal in files, you do not need to overload this function.
+
+@cindex @code{speedbar-item-info}
+The function @code{speedbar-item-info}, however, is very likely to need
+overloading. This function takes no parameters and must derive a text
+summary to display in the minibuffer.
+
+There are several helper functions you can use if you are going to use
+built in tagging. These functions can be @code{or}ed since each one
+returns non-@code{nil} if it displays a message. They are:
+
+@table @code
+@cindex @code{speedbar-item-info-file-helper}
+@item speedbar-item-info-file-helper
+This takes an optional @var{filename} parameter. You can derive your own
+filename, or it will derive it using a (possibly overloaded) function
+@code{speedbar-line-file}. It shows details about a file.
+@cindex @code{speedbar-item-info-tag-helper}
+@item speedbar-item-info-tag-helper
+If the current line is a tag, then display information about that tag,
+such as its parent file, and location.
+@end table
+
+Your custom function might look like this:
+
+@example
+(defun MyExtension-item-info ()
+ "Display information about the current line."
+ (or (speedbar-item-info-tag-helper)
+ (message "Interesting detail.")))
+@end example
+
+Once you have done all this, speedbar will show an entry in the
+@samp{Displays} menu declaring that your extension is available.
+
+@node Tagging Extensions, Creating a display, Major Display Modes, Extending
+@section Tagging Extensions
+
+It is possible to create new methods for tagging files in speedbar.
+To do this, you need two basic functions, one function to fetch the
+tags from a buffer, the other to insert them below the filename.
+
+@defun my-fetch-dynamic-tags file
+Parse @var{file} for a list of tags. Return the list, or @code{t} if there was
+an error.
+@end defun
+
+The non-error return value can be anything, as long as it can be
+inserted by its paired function:
+
+@defun my-insert-tag-list level lst
+Insert a list of tags @var{lst} started at indentation level
+@var{level}. Creates buttons for each tag, and provides any other
+display information required.
+@end defun
+
+@cindex @code{speedbar-create-tag-hierarchy}
+It is often useful to use @code{speedbar-create-tag-hierarchy} on your
+token list. See that function's documentation for details on what it
+requires.
+
+@cindex @code{speedbar-dynamic-tags-function-list}
+Once these two functions are written, modify the variable
+@code{speedbar-dynamic-tags-function-list} to include your parser at the
+beginning, like this:
+
+@example
+(add-to-list 'speedbar-dynamic-tags-function-list
+ '(my-fetch-dynamic-tags . my-insert-tag-list))
+@end example
+
+If your parser is only good for a few types of files, make sure that it
+is either a buffer local modification, or that the tag generator returns
+@code{t} for non valid buffers.
+
+@node Creating a display, , Tagging Extensions, Extending
+@section Creating a display
+@cindex creating a display
+
+Rendering a display in speedbar is completely flexible. When your
+button function is called, see @ref{Minor Display Modes}, and @ref{Major
+Display Modes}, you have control to @code{insert} anything you want.
+
+The conventions allow almost anything to be inserted, but several helper
+functions are provided to make it easy to create the standardized
+buttons.
+
+To understand the built in functions, each `button' in speedbar consists
+of four important pieces of data. The text to be displayed, token
+data to be associated with the text, a function to call, and some face to
+display it in.
+
+When a function is provided, then that text becomes mouse activated,
+meaning the mouse will highlight the text.
+
+Additionally, for data which can form deep trees, each line is given a
+depth which indicates how far down the tree it is. This information is
+stored in invisible text at the beginning of each line, and is used by
+the navigation commands.
+
+@defun speedbar-insert-button text face mouse function &optional token prevline
+This function inserts one button into the current location.
+@var{text} is the text to insert. @var{face} is the face in which it
+will be displayed. @var{mouse} is the face to display over the text
+when the mouse passes over it. @var{function} is called whenever the
+user clicks on the text.
+
+The optional argument @var{token} is extra data to associated with the
+text. Lastly @var{prevline} should be non-@code{nil} if you want this line to
+appear directly after the last button which was created instead of on
+the next line.
+@end defun
+
+@defun speedbar-make-tag-line exp-button-type exp-button-char exp-button-function exp-button-data tag-button tag-button-function tag-button-data tag-button-face depth
+
+Create a tag line with @var{exp-button-type} for the small expansion
+button. This is the button that expands or contracts a node (if
+applicable), and @var{exp-button-char} the character in it (@samp{+},
+@samp{-}, @samp{?}, etc). @var{exp-button-function} is the function
+to call if it's clicked on. Button types are @code{bracket},
+@code{angle}, @code{curly}, @code{expandtag}, @code{statictag}, and
+@code{nil}. @var{exp-button-data} is extra data attached to the text
+forming the expansion button.
+
+Next, @var{tag-button} is the text of the tag.
+@var{tag-button-function} is the function to call if clicked on, and
+@var{tag-button-data} is the data to attach to the text field (such a
+tag positioning, etc). @var{tag-button-face} is a face used for this
+type of tag.
+
+Lastly, @var{depth} shows the depth of expansion.
+
+This function assumes that the cursor is in the speedbar window at the
+position to insert a new item, and that the new item will end with a CR.
+@end defun
+
+@defun speedbar-insert-generic-list level list expand-fun find-fun
+
+At @var{level}, (the current indentation level desired) insert a generic
+multi-level alist @var{list}. Associations with lists get @samp{@{+@}}
+tags (to expand into more nodes) and those with positions or other data
+just get a @samp{>} as the indicator. @samp{@{+@}} buttons will have the
+function @var{expand-fun} and the token is the @code{cdr} list. The
+token name will have the function @var{find-fun} and not token.
+
+Each element of the list can have one of these forms:
+
+@table @code
+@item (@var{name} . marker-or-number)
+One tag at this level.
+@item (@var{name} (@var{name} . marker-or-number) (@var{name} . marker-or-number) ... )
+One group of tags.
+@item (@var{name} marker-or-number (@var{name} . marker-or-number) ... )
+One Group of tags where the group has a starting position.
+@end table
+
+When you use @code{speedbar-insert-generic-list}, there are some
+variables you can set buffer-locally to change the behavior. The most
+obvious is @code{speedbar-tag-hierarchy-method}.
+@xref{Tag Hierarchy Methods}.
+
+@defvar speedbar-generic-list-group-expand-button-type
+This is the button type used for groups of tags, whether expanded
+or added in via a hierarchy method. Two good values are
+@code{curly} and @code{expandtag}. Curly is the default button, and
+@code{expandtag} is useful if the groups also has a position.
+@end defvar
+
+@defvar speedbar-generic-list-tag-button-type
+This is the button type used for a single tag.
+Two good values are @code{nil} and @code{statictag}.
+@code{nil} is the default, and @code{statictag} has the same width as
+@code{expandtag}.
+@end defvar
+
+@end defun
+
+@node GNU Free Documentation License, Index, Extending, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+
+@node Index, , GNU Free Documentation License, Top
+@comment node-name, next, previous, up
+@unnumbered Concept Index
+@printindex cp
+
+@bye
+@c LocalWords: speedbar's xref slowbar kbd subsubsection
+@c LocalWords: keybindings
+
+@ignore
+ arch-tag: e1fc85f0-1eeb-489f-a8d4-a2bfe711fa02
+@end ignore
--- /dev/null
+% texinfo.tex -- TeX macros to handle Texinfo files.
+%
+% Load plain if necessary, i.e., if running under initex.
+\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
+%
+\def\texinfoversion{2007-07-09.21}
+%
+% Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
+% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
+% 2007 Free Software Foundation, Inc.
+%
+% This texinfo.tex file 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, or (at
+% your option) any later version.
+%
+% This texinfo.tex file 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 texinfo.tex file; see the file COPYING. If not, write
+% to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+% Boston, MA 02110-1301, USA.
+%
+% As a special exception, when this file is read by TeX when processing
+% a Texinfo source document, you may use the result without
+% restriction. (This has been our intent since Texinfo was invented.)
+%
+% Please try the latest version of texinfo.tex before submitting bug
+% reports; you can get the latest version from:
+% http://www.gnu.org/software/texinfo/ (the Texinfo home page), or
+% ftp://tug.org/tex/texinfo.tex
+% (and all CTAN mirrors, see http://www.ctan.org).
+% The texinfo.tex in any given distribution could well be out
+% of date, so if that's what you're using, please check.
+%
+% Send bug reports to bug-texinfo@gnu.org. Please include including a
+% complete document in each bug report with which we can reproduce the
+% problem. Patches are, of course, greatly appreciated.
+%
+% To process a Texinfo manual with TeX, it's most reliable to use the
+% texi2dvi shell script that comes with the distribution. For a simple
+% manual foo.texi, however, you can get away with this:
+% tex foo.texi
+% texindex foo.??
+% tex foo.texi
+% tex foo.texi
+% dvips foo.dvi -o # or whatever; this makes foo.ps.
+% The extra TeX runs get the cross-reference information correct.
+% Sometimes one run after texindex suffices, and sometimes you need more
+% than two; texi2dvi does it as many times as necessary.
+%
+% It is possible to adapt texinfo.tex for other languages, to some
+% extent. You can get the existing language-specific files from the
+% full Texinfo distribution.
+%
+% The GNU Texinfo home page is http://www.gnu.org/software/texinfo.
+
+
+\message{Loading texinfo [version \texinfoversion]:}
+
+% If in a .fmt file, print the version number
+% and turn on active characters that we couldn't do earlier because
+% they might have appeared in the input file name.
+\everyjob{\message{[Texinfo version \texinfoversion]}%
+ \catcode`+=\active \catcode`\_=\active}
+
+
+\chardef\other=12
+
+% We never want plain's \outer definition of \+ in Texinfo.
+% For @tex, we can use \tabalign.
+\let\+ = \relax
+
+% Save some plain tex macros whose names we will redefine.
+\let\ptexb=\b
+\let\ptexbullet=\bullet
+\let\ptexc=\c
+\let\ptexcomma=\,
+\let\ptexdot=\.
+\let\ptexdots=\dots
+\let\ptexend=\end
+\let\ptexequiv=\equiv
+\let\ptexexclam=\!
+\let\ptexfootnote=\footnote
+\let\ptexgtr=>
+\let\ptexhat=^
+\let\ptexi=\i
+\let\ptexindent=\indent
+\let\ptexinsert=\insert
+\let\ptexlbrace=\{
+\let\ptexless=<
+\let\ptexnewwrite\newwrite
+\let\ptexnoindent=\noindent
+\let\ptexplus=+
+\let\ptexrbrace=\}
+\let\ptexslash=\/
+\let\ptexstar=\*
+\let\ptext=\t
+
+% If this character appears in an error message or help string, it
+% starts a new line in the output.
+\newlinechar = `^^J
+
+% Use TeX 3.0's \inputlineno to get the line number, for better error
+% messages, but if we're using an old version of TeX, don't do anything.
+%
+\ifx\inputlineno\thisisundefined
+ \let\linenumber = \empty % Pre-3.0.
+\else
+ \def\linenumber{l.\the\inputlineno:\space}
+\fi
+
+% Set up fixed words for English if not already set.
+\ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendix}\fi
+\ifx\putwordChapter\undefined \gdef\putwordChapter{Chapter}\fi
+\ifx\putwordfile\undefined \gdef\putwordfile{file}\fi
+\ifx\putwordin\undefined \gdef\putwordin{in}\fi
+\ifx\putwordIndexIsEmpty\undefined \gdef\putwordIndexIsEmpty{(Index is empty)}\fi
+\ifx\putwordIndexNonexistent\undefined \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi
+\ifx\putwordInfo\undefined \gdef\putwordInfo{Info}\fi
+\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi
+\ifx\putwordMethodon\undefined \gdef\putwordMethodon{Method on}\fi
+\ifx\putwordNoTitle\undefined \gdef\putwordNoTitle{No Title}\fi
+\ifx\putwordof\undefined \gdef\putwordof{of}\fi
+\ifx\putwordon\undefined \gdef\putwordon{on}\fi
+\ifx\putwordpage\undefined \gdef\putwordpage{page}\fi
+\ifx\putwordsection\undefined \gdef\putwordsection{section}\fi
+\ifx\putwordSection\undefined \gdef\putwordSection{Section}\fi
+\ifx\putwordsee\undefined \gdef\putwordsee{see}\fi
+\ifx\putwordSee\undefined \gdef\putwordSee{See}\fi
+\ifx\putwordShortTOC\undefined \gdef\putwordShortTOC{Short Contents}\fi
+\ifx\putwordTOC\undefined \gdef\putwordTOC{Table of Contents}\fi
+%
+\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi
+\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi
+\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi
+\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi
+\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi
+\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi
+\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi
+\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi
+\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi
+\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi
+\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi
+\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi
+%
+\ifx\putwordDefmac\undefined \gdef\putwordDefmac{Macro}\fi
+\ifx\putwordDefspec\undefined \gdef\putwordDefspec{Special Form}\fi
+\ifx\putwordDefvar\undefined \gdef\putwordDefvar{Variable}\fi
+\ifx\putwordDefopt\undefined \gdef\putwordDefopt{User Option}\fi
+\ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi
+
+% Since the category of space is not known, we have to be careful.
+\chardef\spacecat = 10
+\def\spaceisspace{\catcode`\ =\spacecat}
+
+% sometimes characters are active, so we need control sequences.
+\chardef\colonChar = `\:
+\chardef\commaChar = `\,
+\chardef\dashChar = `\-
+\chardef\dotChar = `\.
+\chardef\exclamChar= `\!
+\chardef\lquoteChar= `\`
+\chardef\questChar = `\?
+\chardef\rquoteChar= `\'
+\chardef\semiChar = `\;
+\chardef\underChar = `\_
+
+% Ignore a token.
+%
+\def\gobble#1{}
+
+% The following is used inside several \edef's.
+\def\makecsname#1{\expandafter\noexpand\csname#1\endcsname}
+
+% Hyphenation fixes.
+\hyphenation{
+ Flor-i-da Ghost-script Ghost-view Mac-OS Post-Script
+ ap-pen-dix bit-map bit-maps
+ data-base data-bases eshell fall-ing half-way long-est man-u-script
+ man-u-scripts mini-buf-fer mini-buf-fers over-view par-a-digm
+ par-a-digms rath-er rec-tan-gu-lar ro-bot-ics se-vere-ly set-up spa-ces
+ spell-ing spell-ings
+ stand-alone strong-est time-stamp time-stamps which-ever white-space
+ wide-spread wrap-around
+}
+
+% Margin to add to right of even pages, to left of odd pages.
+\newdimen\bindingoffset
+\newdimen\normaloffset
+\newdimen\pagewidth \newdimen\pageheight
+
+% For a final copy, take out the rectangles
+% that mark overfull boxes (in case you have decided
+% that the text looks ok even though it passes the margin).
+%
+\def\finalout{\overfullrule=0pt}
+
+% @| inserts a changebar to the left of the current line. It should
+% surround any changed text. This approach does *not* work if the
+% change spans more than two lines of output. To handle that, we would
+% have adopt a much more difficult approach (putting marks into the main
+% vertical list for the beginning and end of each change).
+%
+\def\|{%
+ % \vadjust can only be used in horizontal mode.
+ \leavevmode
+ %
+ % Append this vertical mode material after the current line in the output.
+ \vadjust{%
+ % We want to insert a rule with the height and depth of the current
+ % leading; that is exactly what \strutbox is supposed to record.
+ \vskip-\baselineskip
+ %
+ % \vadjust-items are inserted at the left edge of the type. So
+ % the \llap here moves out into the left-hand margin.
+ \llap{%
+ %
+ % For a thicker or thinner bar, change the `1pt'.
+ \vrule height\baselineskip width1pt
+ %
+ % This is the space between the bar and the text.
+ \hskip 12pt
+ }%
+ }%
+}
+
+% Sometimes it is convenient to have everything in the transcript file
+% and nothing on the terminal. We don't just call \tracingall here,
+% since that produces some useless output on the terminal. We also make
+% some effort to order the tracing commands to reduce output in the log
+% file; cf. trace.sty in LaTeX.
+%
+\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}%
+\def\loggingall{%
+ \tracingstats2
+ \tracingpages1
+ \tracinglostchars2 % 2 gives us more in etex
+ \tracingparagraphs1
+ \tracingoutput1
+ \tracingmacros2
+ \tracingrestores1
+ \showboxbreadth\maxdimen \showboxdepth\maxdimen
+ \ifx\eTeXversion\undefined\else % etex gives us more logging
+ \tracingscantokens1
+ \tracingifs1
+ \tracinggroups1
+ \tracingnesting2
+ \tracingassigns1
+ \fi
+ \tracingcommands3 % 3 gives us more in etex
+ \errorcontextlines16
+}%
+
+% add check for \lastpenalty to plain's definitions. If the last thing
+% we did was a \nobreak, we don't want to insert more space.
+%
+\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount
+ \removelastskip\penalty-50\smallskip\fi\fi}
+\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount
+ \removelastskip\penalty-100\medskip\fi\fi}
+\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount
+ \removelastskip\penalty-200\bigskip\fi\fi}
+
+% For @cropmarks command.
+% Do @cropmarks to get crop marks.
+%
+\newif\ifcropmarks
+\let\cropmarks = \cropmarkstrue
+%
+% Dimensions to add cropmarks at corners.
+% Added by P. A. MacKay, 12 Nov. 1986
+%
+\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines
+\newdimen\cornerlong \cornerlong=1pc
+\newdimen\cornerthick \cornerthick=.3pt
+\newdimen\topandbottommargin \topandbottommargin=.75in
+
+% Main output routine.
+\chardef\PAGE = 255
+\output = {\onepageout{\pagecontents\PAGE}}
+
+\newbox\headlinebox
+\newbox\footlinebox
+
+% \onepageout takes a vbox as an argument. Note that \pagecontents
+% does insertions, but you have to call it yourself.
+\def\onepageout#1{%
+ \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi
+ %
+ \ifodd\pageno \advance\hoffset by \bindingoffset
+ \else \advance\hoffset by -\bindingoffset\fi
+ %
+ % Do this outside of the \shipout so @code etc. will be expanded in
+ % the headline as they should be, not taken literally (outputting ''code).
+ \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}%
+ \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}%
+ %
+ {%
+ % Have to do this stuff outside the \shipout because we want it to
+ % take effect in \write's, yet the group defined by the \vbox ends
+ % before the \shipout runs.
+ %
+ \indexdummies % don't expand commands in the output.
+ \normalturnoffactive % \ in index entries must not stay \, e.g., if
+ % the page break happens to be in the middle of an example.
+ % We don't want .vr (or whatever) entries like this:
+ % \entry{{\tt \indexbackslash }acronym}{32}{\code {\acronym}}
+ % "\acronym" won't work when it's read back in;
+ % it needs to be
+ % {\code {{\tt \backslashcurfont }acronym}
+ \shipout\vbox{%
+ % Do this early so pdf references go to the beginning of the page.
+ \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi
+ %
+ \ifcropmarks \vbox to \outervsize\bgroup
+ \hsize = \outerhsize
+ \vskip-\topandbottommargin
+ \vtop to0pt{%
+ \line{\ewtop\hfil\ewtop}%
+ \nointerlineskip
+ \line{%
+ \vbox{\moveleft\cornerthick\nstop}%
+ \hfill
+ \vbox{\moveright\cornerthick\nstop}%
+ }%
+ \vss}%
+ \vskip\topandbottommargin
+ \line\bgroup
+ \hfil % center the page within the outer (page) hsize.
+ \ifodd\pageno\hskip\bindingoffset\fi
+ \vbox\bgroup
+ \fi
+ %
+ \unvbox\headlinebox
+ \pagebody{#1}%
+ \ifdim\ht\footlinebox > 0pt
+ % Only leave this space if the footline is nonempty.
+ % (We lessened \vsize for it in \oddfootingyyy.)
+ % The \baselineskip=24pt in plain's \makefootline has no effect.
+ \vskip 24pt
+ \unvbox\footlinebox
+ \fi
+ %
+ \ifcropmarks
+ \egroup % end of \vbox\bgroup
+ \hfil\egroup % end of (centering) \line\bgroup
+ \vskip\topandbottommargin plus1fill minus1fill
+ \boxmaxdepth = \cornerthick
+ \vbox to0pt{\vss
+ \line{%
+ \vbox{\moveleft\cornerthick\nsbot}%
+ \hfill
+ \vbox{\moveright\cornerthick\nsbot}%
+ }%
+ \nointerlineskip
+ \line{\ewbot\hfil\ewbot}%
+ }%
+ \egroup % \vbox from first cropmarks clause
+ \fi
+ }% end of \shipout\vbox
+ }% end of group with \indexdummies
+ \advancepageno
+ \ifnum\outputpenalty>-20000 \else\dosupereject\fi
+}
+
+\newinsert\margin \dimen\margin=\maxdimen
+
+\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}}
+{\catcode`\@ =11
+\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi
+% marginal hacks, juha@viisa.uucp (Juha Takala)
+\ifvoid\margin\else % marginal info is present
+ \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi
+\dimen@=\dp#1 \unvbox#1
+\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi
+\ifr@ggedbottom \kern-\dimen@ \vfil \fi}
+}
+
+% Here are the rules for the cropmarks. Note that they are
+% offset so that the space between them is truly \outerhsize or \outervsize
+% (P. A. MacKay, 12 November, 1986)
+%
+\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong}
+\def\nstop{\vbox
+ {\hrule height\cornerthick depth\cornerlong width\cornerthick}}
+\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong}
+\def\nsbot{\vbox
+ {\hrule height\cornerlong depth\cornerthick width\cornerthick}}
+
+% Parse an argument, then pass it to #1. The argument is the rest of
+% the input line (except we remove a trailing comment). #1 should be a
+% macro which expects an ordinary undelimited TeX argument.
+%
+\def\parsearg{\parseargusing{}}
+\def\parseargusing#1#2{%
+ \def\argtorun{#2}%
+ \begingroup
+ \obeylines
+ \spaceisspace
+ #1%
+ \parseargline\empty% Insert the \empty token, see \finishparsearg below.
+}
+
+{\obeylines %
+ \gdef\parseargline#1^^M{%
+ \endgroup % End of the group started in \parsearg.
+ \argremovecomment #1\comment\ArgTerm%
+ }%
+}
+
+% First remove any @comment, then any @c comment.
+\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm}
+\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm}
+
+% Each occurence of `\^^M' or `<space>\^^M' is replaced by a single space.
+%
+% \argremovec might leave us with trailing space, e.g.,
+% @end itemize @c foo
+% This space token undergoes the same procedure and is eventually removed
+% by \finishparsearg.
+%
+\def\argcheckspaces#1\^^M{\argcheckspacesX#1\^^M \^^M}
+\def\argcheckspacesX#1 \^^M{\argcheckspacesY#1\^^M}
+\def\argcheckspacesY#1\^^M#2\^^M#3\ArgTerm{%
+ \def\temp{#3}%
+ \ifx\temp\empty
+ % Do not use \next, perhaps the caller of \parsearg uses it; reuse \temp:
+ \let\temp\finishparsearg
+ \else
+ \let\temp\argcheckspaces
+ \fi
+ % Put the space token in:
+ \temp#1 #3\ArgTerm
+}
+
+% If a _delimited_ argument is enclosed in braces, they get stripped; so
+% to get _exactly_ the rest of the line, we had to prevent such situation.
+% We prepended an \empty token at the very beginning and we expand it now,
+% just before passing the control to \argtorun.
+% (Similarily, we have to think about #3 of \argcheckspacesY above: it is
+% either the null string, or it ends with \^^M---thus there is no danger
+% that a pair of braces would be stripped.
+%
+% But first, we have to remove the trailing space token.
+%
+\def\finishparsearg#1 \ArgTerm{\expandafter\argtorun\expandafter{#1}}
+
+% \parseargdef\foo{...}
+% is roughly equivalent to
+% \def\foo{\parsearg\Xfoo}
+% \def\Xfoo#1{...}
+%
+% Actually, I use \csname\string\foo\endcsname, ie. \\foo, as it is my
+% favourite TeX trick. --kasal, 16nov03
+
+\def\parseargdef#1{%
+ \expandafter \doparseargdef \csname\string#1\endcsname #1%
+}
+\def\doparseargdef#1#2{%
+ \def#2{\parsearg#1}%
+ \def#1##1%
+}
+
+% Several utility definitions with active space:
+{
+ \obeyspaces
+ \gdef\obeyedspace{ }
+
+ % Make each space character in the input produce a normal interword
+ % space in the output. Don't allow a line break at this space, as this
+ % is used only in environments like @example, where each line of input
+ % should produce a line of output anyway.
+ %
+ \gdef\sepspaces{\obeyspaces\let =\tie}
+
+ % If an index command is used in an @example environment, any spaces
+ % therein should become regular spaces in the raw index file, not the
+ % expansion of \tie (\leavevmode \penalty \@M \ ).
+ \gdef\unsepspaces{\let =\space}
+}
+
+
+\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next}
+
+% Define the framework for environments in texinfo.tex. It's used like this:
+%
+% \envdef\foo{...}
+% \def\Efoo{...}
+%
+% It's the responsibility of \envdef to insert \begingroup before the
+% actual body; @end closes the group after calling \Efoo. \envdef also
+% defines \thisenv, so the current environment is known; @end checks
+% whether the environment name matches. The \checkenv macro can also be
+% used to check whether the current environment is the one expected.
+%
+% Non-false conditionals (@iftex, @ifset) don't fit into this, so they
+% are not treated as enviroments; they don't open a group. (The
+% implementation of @end takes care not to call \endgroup in this
+% special case.)
+
+
+% At runtime, environments start with this:
+\def\startenvironment#1{\begingroup\def\thisenv{#1}}
+% initialize
+\let\thisenv\empty
+
+% ... but they get defined via ``\envdef\foo{...}'':
+\long\def\envdef#1#2{\def#1{\startenvironment#1#2}}
+\def\envparseargdef#1#2{\parseargdef#1{\startenvironment#1#2}}
+
+% Check whether we're in the right environment:
+\def\checkenv#1{%
+ \def\temp{#1}%
+ \ifx\thisenv\temp
+ \else
+ \badenverr
+ \fi
+}
+
+% Evironment mismatch, #1 expected:
+\def\badenverr{%
+ \errhelp = \EMsimple
+ \errmessage{This command can appear only \inenvironment\temp,
+ not \inenvironment\thisenv}%
+}
+\def\inenvironment#1{%
+ \ifx#1\empty
+ out of any environment%
+ \else
+ in environment \expandafter\string#1%
+ \fi
+}
+
+% @end foo executes the definition of \Efoo.
+% But first, it executes a specialized version of \checkenv
+%
+\parseargdef\end{%
+ \if 1\csname iscond.#1\endcsname
+ \else
+ % The general wording of \badenverr may not be ideal, but... --kasal, 06nov03
+ \expandafter\checkenv\csname#1\endcsname
+ \csname E#1\endcsname
+ \endgroup
+ \fi
+}
+
+\newhelp\EMsimple{Press RETURN to continue.}
+
+
+%% Simple single-character @ commands
+
+% @@ prints an @
+% Kludge this until the fonts are right (grr).
+\def\@{{\tt\char64}}
+
+% This is turned off because it was never documented
+% and you can use @w{...} around a quote to suppress ligatures.
+%% Define @` and @' to be the same as ` and '
+%% but suppressing ligatures.
+%\def\`{{`}}
+%\def\'{{'}}
+
+% Used to generate quoted braces.
+\def\mylbrace {{\tt\char123}}
+\def\myrbrace {{\tt\char125}}
+\let\{=\mylbrace
+\let\}=\myrbrace
+\begingroup
+ % Definitions to produce \{ and \} commands for indices,
+ % and @{ and @} for the aux/toc files.
+ \catcode`\{ = \other \catcode`\} = \other
+ \catcode`\[ = 1 \catcode`\] = 2
+ \catcode`\! = 0 \catcode`\\ = \other
+ !gdef!lbracecmd[\{]%
+ !gdef!rbracecmd[\}]%
+ !gdef!lbraceatcmd[@{]%
+ !gdef!rbraceatcmd[@}]%
+!endgroup
+
+% @comma{} to avoid , parsing problems.
+\let\comma = ,
+
+% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent
+% Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H.
+\let\, = \c
+\let\dotaccent = \.
+\def\ringaccent#1{{\accent23 #1}}
+\let\tieaccent = \t
+\let\ubaraccent = \b
+\let\udotaccent = \d
+
+% Other special characters: @questiondown @exclamdown @ordf @ordm
+% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss.
+\def\questiondown{?`}
+\def\exclamdown{!`}
+\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}}
+\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}}
+
+% Dotless i and dotless j, used for accents.
+\def\imacro{i}
+\def\jmacro{j}
+\def\dotless#1{%
+ \def\temp{#1}%
+ \ifx\temp\imacro \ptexi
+ \else\ifx\temp\jmacro \j
+ \else \errmessage{@dotless can be used only with i or j}%
+ \fi\fi
+}
+
+% The \TeX{} logo, as in plain, but resetting the spacing so that a
+% period following counts as ending a sentence. (Idea found in latex.)
+%
+\edef\TeX{\TeX \spacefactor=1000 }
+
+% @LaTeX{} logo. Not quite the same results as the definition in
+% latex.ltx, since we use a different font for the raised A; it's most
+% convenient for us to use an explicitly smaller font, rather than using
+% the \scriptstyle font (since we don't reset \scriptstyle and
+% \scriptscriptstyle).
+%
+\def\LaTeX{%
+ L\kern-.36em
+ {\setbox0=\hbox{T}%
+ \vbox to \ht0{\hbox{\selectfonts\lllsize A}\vss}}%
+ \kern-.15em
+ \TeX
+}
+
+% Be sure we're in horizontal mode when doing a tie, since we make space
+% equivalent to this in @example-like environments. Otherwise, a space
+% at the beginning of a line will start with \penalty -- and
+% since \penalty is valid in vertical mode, we'd end up putting the
+% penalty on the vertical list instead of in the new paragraph.
+{\catcode`@ = 11
+ % Avoid using \@M directly, because that causes trouble
+ % if the definition is written into an index file.
+ \global\let\tiepenalty = \@M
+ \gdef\tie{\leavevmode\penalty\tiepenalty\ }
+}
+
+% @: forces normal size whitespace following.
+\def\:{\spacefactor=1000 }
+
+% @* forces a line break.
+\def\*{\hfil\break\hbox{}\ignorespaces}
+
+% @/ allows a line break.
+\let\/=\allowbreak
+
+% @. is an end-of-sentence period.
+\def\.{.\spacefactor=\endofsentencespacefactor\space}
+
+% @! is an end-of-sentence bang.
+\def\!{!\spacefactor=\endofsentencespacefactor\space}
+
+% @? is an end-of-sentence query.
+\def\?{?\spacefactor=\endofsentencespacefactor\space}
+
+% @frenchspacing on|off says whether to put extra space after punctuation.
+%
+\def\onword{on}
+\def\offword{off}
+%
+\parseargdef\frenchspacing{%
+ \def\temp{#1}%
+ \ifx\temp\onword \plainfrenchspacing
+ \else\ifx\temp\offword \plainnonfrenchspacing
+ \else
+ \errhelp = \EMsimple
+ \errmessage{Unknown @frenchspacing option `\temp', must be on/off}%
+ \fi\fi
+}
+
+% @w prevents a word break. Without the \leavevmode, @w at the
+% beginning of a paragraph, when TeX is still in vertical mode, would
+% produce a whole line of output instead of starting the paragraph.
+\def\w#1{\leavevmode\hbox{#1}}
+
+% @group ... @end group forces ... to be all on one page, by enclosing
+% it in a TeX vbox. We use \vtop instead of \vbox to construct the box
+% to keep its height that of a normal line. According to the rules for
+% \topskip (p.114 of the TeXbook), the glue inserted is
+% max (\topskip - \ht (first item), 0). If that height is large,
+% therefore, no glue is inserted, and the space between the headline and
+% the text is small, which looks bad.
+%
+% Another complication is that the group might be very large. This can
+% cause the glue on the previous page to be unduly stretched, because it
+% does not have much material. In this case, it's better to add an
+% explicit \vfill so that the extra space is at the bottom. The
+% threshold for doing this is if the group is more than \vfilllimit
+% percent of a page (\vfilllimit can be changed inside of @tex).
+%
+\newbox\groupbox
+\def\vfilllimit{0.7}
+%
+\envdef\group{%
+ \ifnum\catcode`\^^M=\active \else
+ \errhelp = \groupinvalidhelp
+ \errmessage{@group invalid in context where filling is enabled}%
+ \fi
+ \startsavinginserts
+ %
+ \setbox\groupbox = \vtop\bgroup
+ % Do @comment since we are called inside an environment such as
+ % @example, where each end-of-line in the input causes an
+ % end-of-line in the output. We don't want the end-of-line after
+ % the `@group' to put extra space in the output. Since @group
+ % should appear on a line by itself (according to the Texinfo
+ % manual), we don't worry about eating any user text.
+ \comment
+}
+%
+% The \vtop produces a box with normal height and large depth; thus, TeX puts
+% \baselineskip glue before it, and (when the next line of text is done)
+% \lineskip glue after it. Thus, space below is not quite equal to space
+% above. But it's pretty close.
+\def\Egroup{%
+ % To get correct interline space between the last line of the group
+ % and the first line afterwards, we have to propagate \prevdepth.
+ \endgraf % Not \par, as it may have been set to \lisppar.
+ \global\dimen1 = \prevdepth
+ \egroup % End the \vtop.
+ % \dimen0 is the vertical size of the group's box.
+ \dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox
+ % \dimen2 is how much space is left on the page (more or less).
+ \dimen2 = \pageheight \advance\dimen2 by -\pagetotal
+ % if the group doesn't fit on the current page, and it's a big big
+ % group, force a page break.
+ \ifdim \dimen0 > \dimen2
+ \ifdim \pagetotal < \vfilllimit\pageheight
+ \page
+ \fi
+ \fi
+ \box\groupbox
+ \prevdepth = \dimen1
+ \checkinserts
+}
+%
+% TeX puts in an \escapechar (i.e., `@') at the beginning of the help
+% message, so this ends up printing `@group can only ...'.
+%
+\newhelp\groupinvalidhelp{%
+group can only be used in environments such as @example,^^J%
+where each line of input produces a line of output.}
+
+% @need space-in-mils
+% forces a page break if there is not space-in-mils remaining.
+
+\newdimen\mil \mil=0.001in
+
+% Old definition--didn't work.
+%\parseargdef\need{\par %
+%% This method tries to make TeX break the page naturally
+%% if the depth of the box does not fit.
+%{\baselineskip=0pt%
+%\vtop to #1\mil{\vfil}\kern -#1\mil\nobreak
+%\prevdepth=-1000pt
+%}}
+
+\parseargdef\need{%
+ % Ensure vertical mode, so we don't make a big box in the middle of a
+ % paragraph.
+ \par
+ %
+ % If the @need value is less than one line space, it's useless.
+ \dimen0 = #1\mil
+ \dimen2 = \ht\strutbox
+ \advance\dimen2 by \dp\strutbox
+ \ifdim\dimen0 > \dimen2
+ %
+ % Do a \strut just to make the height of this box be normal, so the
+ % normal leading is inserted relative to the preceding line.
+ % And a page break here is fine.
+ \vtop to #1\mil{\strut\vfil}%
+ %
+ % TeX does not even consider page breaks if a penalty added to the
+ % main vertical list is 10000 or more. But in order to see if the
+ % empty box we just added fits on the page, we must make it consider
+ % page breaks. On the other hand, we don't want to actually break the
+ % page after the empty box. So we use a penalty of 9999.
+ %
+ % There is an extremely small chance that TeX will actually break the
+ % page at this \penalty, if there are no other feasible breakpoints in
+ % sight. (If the user is using lots of big @group commands, which
+ % almost-but-not-quite fill up a page, TeX will have a hard time doing
+ % good page breaking, for example.) However, I could not construct an
+ % example where a page broke at this \penalty; if it happens in a real
+ % document, then we can reconsider our strategy.
+ \penalty9999
+ %
+ % Back up by the size of the box, whether we did a page break or not.
+ \kern -#1\mil
+ %
+ % Do not allow a page break right after this kern.
+ \nobreak
+ \fi
+}
+
+% @br forces paragraph break (and is undocumented).
+
+\let\br = \par
+
+% @page forces the start of a new page.
+%
+\def\page{\par\vfill\supereject}
+
+% @exdent text....
+% outputs text on separate line in roman font, starting at standard page margin
+
+% This records the amount of indent in the innermost environment.
+% That's how much \exdent should take out.
+\newskip\exdentamount
+
+% This defn is used inside fill environments such as @defun.
+\parseargdef\exdent{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}
+
+% This defn is used inside nofill environments such as @example.
+\parseargdef\nofillexdent{{\advance \leftskip by -\exdentamount
+ \leftline{\hskip\leftskip{\rm#1}}}}
+
+% @inmargin{WHICH}{TEXT} puts TEXT in the WHICH margin next to the current
+% paragraph. For more general purposes, use the \margin insertion
+% class. WHICH is `l' or `r'.
+%
+\newskip\inmarginspacing \inmarginspacing=1cm
+\def\strutdepth{\dp\strutbox}
+%
+\def\doinmargin#1#2{\strut\vadjust{%
+ \nobreak
+ \kern-\strutdepth
+ \vtop to \strutdepth{%
+ \baselineskip=\strutdepth
+ \vss
+ % if you have multiple lines of stuff to put here, you'll need to
+ % make the vbox yourself of the appropriate size.
+ \ifx#1l%
+ \llap{\ignorespaces #2\hskip\inmarginspacing}%
+ \else
+ \rlap{\hskip\hsize \hskip\inmarginspacing \ignorespaces #2}%
+ \fi
+ \null
+ }%
+}}
+\def\inleftmargin{\doinmargin l}
+\def\inrightmargin{\doinmargin r}
+%
+% @inmargin{TEXT [, RIGHT-TEXT]}
+% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right;
+% else use TEXT for both).
+%
+\def\inmargin#1{\parseinmargin #1,,\finish}
+\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing.
+ \setbox0 = \hbox{\ignorespaces #2}%
+ \ifdim\wd0 > 0pt
+ \def\lefttext{#1}% have both texts
+ \def\righttext{#2}%
+ \else
+ \def\lefttext{#1}% have only one text
+ \def\righttext{#1}%
+ \fi
+ %
+ \ifodd\pageno
+ \def\temp{\inrightmargin\righttext}% odd page -> outside is right margin
+ \else
+ \def\temp{\inleftmargin\lefttext}%
+ \fi
+ \temp
+}
+
+% @include file insert text of that file as input.
+%
+\def\include{\parseargusing\filenamecatcodes\includezzz}
+\def\includezzz#1{%
+ \pushthisfilestack
+ \def\thisfile{#1}%
+ {%
+ \makevalueexpandable
+ \def\temp{\input #1 }%
+ \expandafter
+ }\temp
+ \popthisfilestack
+}
+\def\filenamecatcodes{%
+ \catcode`\\=\other
+ \catcode`~=\other
+ \catcode`^=\other
+ \catcode`_=\other
+ \catcode`|=\other
+ \catcode`<=\other
+ \catcode`>=\other
+ \catcode`+=\other
+ \catcode`-=\other
+}
+
+\def\pushthisfilestack{%
+ \expandafter\pushthisfilestackX\popthisfilestack\StackTerm
+}
+\def\pushthisfilestackX{%
+ \expandafter\pushthisfilestackY\thisfile\StackTerm
+}
+\def\pushthisfilestackY #1\StackTerm #2\StackTerm {%
+ \gdef\popthisfilestack{\gdef\thisfile{#1}\gdef\popthisfilestack{#2}}%
+}
+
+\def\popthisfilestack{\errthisfilestackempty}
+\def\errthisfilestackempty{\errmessage{Internal error:
+ the stack of filenames is empty.}}
+
+\def\thisfile{}
+
+% @center line
+% outputs that line, centered.
+%
+\parseargdef\center{%
+ \ifhmode
+ \let\next\centerH
+ \else
+ \let\next\centerV
+ \fi
+ \next{\hfil \ignorespaces#1\unskip \hfil}%
+}
+\def\centerH#1{%
+ {%
+ \hfil\break
+ \advance\hsize by -\leftskip
+ \advance\hsize by -\rightskip
+ \line{#1}%
+ \break
+ }%
+}
+\def\centerV#1{\line{\kern\leftskip #1\kern\rightskip}}
+
+% @sp n outputs n lines of vertical space
+
+\parseargdef\sp{\vskip #1\baselineskip}
+
+% @comment ...line which is ignored...
+% @c is the same as @comment
+% @ignore ... @end ignore is another way to write a comment
+
+\def\comment{\begingroup \catcode`\^^M=\other%
+\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other%
+\commentxxx}
+{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}}
+
+\let\c=\comment
+
+% @paragraphindent NCHARS
+% We'll use ems for NCHARS, close enough.
+% NCHARS can also be the word `asis' or `none'.
+% We cannot feasibly implement @paragraphindent asis, though.
+%
+\def\asisword{asis} % no translation, these are keywords
+\def\noneword{none}
+%
+\parseargdef\paragraphindent{%
+ \def\temp{#1}%
+ \ifx\temp\asisword
+ \else
+ \ifx\temp\noneword
+ \defaultparindent = 0pt
+ \else
+ \defaultparindent = #1em
+ \fi
+ \fi
+ \parindent = \defaultparindent
+}
+
+% @exampleindent NCHARS
+% We'll use ems for NCHARS like @paragraphindent.
+% It seems @exampleindent asis isn't necessary, but
+% I preserve it to make it similar to @paragraphindent.
+\parseargdef\exampleindent{%
+ \def\temp{#1}%
+ \ifx\temp\asisword
+ \else
+ \ifx\temp\noneword
+ \lispnarrowing = 0pt
+ \else
+ \lispnarrowing = #1em
+ \fi
+ \fi
+}
+
+% @firstparagraphindent WORD
+% If WORD is `none', then suppress indentation of the first paragraph
+% after a section heading. If WORD is `insert', then do indent at such
+% paragraphs.
+%
+% The paragraph indentation is suppressed or not by calling
+% \suppressfirstparagraphindent, which the sectioning commands do.
+% We switch the definition of this back and forth according to WORD.
+% By default, we suppress indentation.
+%
+\def\suppressfirstparagraphindent{\dosuppressfirstparagraphindent}
+\def\insertword{insert}
+%
+\parseargdef\firstparagraphindent{%
+ \def\temp{#1}%
+ \ifx\temp\noneword
+ \let\suppressfirstparagraphindent = \dosuppressfirstparagraphindent
+ \else\ifx\temp\insertword
+ \let\suppressfirstparagraphindent = \relax
+ \else
+ \errhelp = \EMsimple
+ \errmessage{Unknown @firstparagraphindent option `\temp'}%
+ \fi\fi
+}
+
+% Here is how we actually suppress indentation. Redefine \everypar to
+% \kern backwards by \parindent, and then reset itself to empty.
+%
+% We also make \indent itself not actually do anything until the next
+% paragraph.
+%
+\gdef\dosuppressfirstparagraphindent{%
+ \gdef\indent{%
+ \restorefirstparagraphindent
+ \indent
+ }%
+ \gdef\noindent{%
+ \restorefirstparagraphindent
+ \noindent
+ }%
+ \global\everypar = {%
+ \kern -\parindent
+ \restorefirstparagraphindent
+ }%
+}
+
+\gdef\restorefirstparagraphindent{%
+ \global \let \indent = \ptexindent
+ \global \let \noindent = \ptexnoindent
+ \global \everypar = {}%
+}
+
+
+% @asis just yields its argument. Used with @table, for example.
+%
+\def\asis#1{#1}
+
+% @math outputs its argument in math mode.
+%
+% One complication: _ usually means subscripts, but it could also mean
+% an actual _ character, as in @math{@var{some_variable} + 1}. So make
+% _ active, and distinguish by seeing if the current family is \slfam,
+% which is what @var uses.
+{
+ \catcode`\_ = \active
+ \gdef\mathunderscore{%
+ \catcode`\_=\active
+ \def_{\ifnum\fam=\slfam \_\else\sb\fi}%
+ }
+}
+% Another complication: we want \\ (and @\) to output a \ character.
+% FYI, plain.tex uses \\ as a temporary control sequence (why?), but
+% this is not advertised and we don't care. Texinfo does not
+% otherwise define @\.
+%
+% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\.
+\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi}
+%
+\def\math{%
+ \tex
+ \mathunderscore
+ \let\\ = \mathbackslash
+ \mathactive
+ $\finishmath
+}
+\def\finishmath#1{#1$\endgroup} % Close the group opened by \tex.
+
+% Some active characters (such as <) are spaced differently in math.
+% We have to reset their definitions in case the @math was an argument
+% to a command which sets the catcodes (such as @item or @section).
+%
+{
+ \catcode`^ = \active
+ \catcode`< = \active
+ \catcode`> = \active
+ \catcode`+ = \active
+ \gdef\mathactive{%
+ \let^ = \ptexhat
+ \let< = \ptexless
+ \let> = \ptexgtr
+ \let+ = \ptexplus
+ }
+}
+
+% @bullet and @minus need the same treatment as @math, just above.
+\def\bullet{$\ptexbullet$}
+\def\minus{$-$}
+
+% @dots{} outputs an ellipsis using the current font.
+% We do .5em per period so that it has the same spacing in the cm
+% typewriter fonts as three actual period characters; on the other hand,
+% in other typewriter fonts three periods are wider than 1.5em. So do
+% whichever is larger.
+%
+\def\dots{%
+ \leavevmode
+ \setbox0=\hbox{...}% get width of three periods
+ \ifdim\wd0 > 1.5em
+ \dimen0 = \wd0
+ \else
+ \dimen0 = 1.5em
+ \fi
+ \hbox to \dimen0{%
+ \hskip 0pt plus.25fil
+ .\hskip 0pt plus1fil
+ .\hskip 0pt plus1fil
+ .\hskip 0pt plus.5fil
+ }%
+}
+
+% @enddots{} is an end-of-sentence ellipsis.
+%
+\def\enddots{%
+ \dots
+ \spacefactor=\endofsentencespacefactor
+}
+
+% @comma{} is so commas can be inserted into text without messing up
+% Texinfo's parsing.
+%
+\let\comma = ,
+
+% @refill is a no-op.
+\let\refill=\relax
+
+% If working on a large document in chapters, it is convenient to
+% be able to disable indexing, cross-referencing, and contents, for test runs.
+% This is done with @novalidate (before @setfilename).
+%
+\newif\iflinks \linkstrue % by default we want the aux files.
+\let\novalidate = \linksfalse
+
+% @setfilename is done at the beginning of every texinfo file.
+% So open here the files we need to have open while reading the input.
+% This makes it possible to make a .fmt file for texinfo.
+\def\setfilename{%
+ \fixbackslash % Turn off hack to swallow `\input texinfo'.
+ \iflinks
+ \tryauxfile
+ % Open the new aux file. TeX will close it automatically at exit.
+ \immediate\openout\auxfile=\jobname.aux
+ \fi % \openindices needs to do some work in any case.
+ \openindices
+ \let\setfilename=\comment % Ignore extra @setfilename cmds.
+ %
+ % If texinfo.cnf is present on the system, read it.
+ % Useful for site-wide @afourpaper, etc.
+ \openin 1 texinfo.cnf
+ \ifeof 1 \else \input texinfo.cnf \fi
+ \closein 1
+ %
+ \comment % Ignore the actual filename.
+}
+
+% Called from \setfilename.
+%
+\def\openindices{%
+ \newindex{cp}%
+ \newcodeindex{fn}%
+ \newcodeindex{vr}%
+ \newcodeindex{tp}%
+ \newcodeindex{ky}%
+ \newcodeindex{pg}%
+}
+
+% @bye.
+\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend}
+
+
+\message{pdf,}
+% adobe `portable' document format
+\newcount\tempnum
+\newcount\lnkcount
+\newtoks\filename
+\newcount\filenamelength
+\newcount\pgn
+\newtoks\toksA
+\newtoks\toksB
+\newtoks\toksC
+\newtoks\toksD
+\newbox\boxA
+\newcount\countA
+\newif\ifpdf
+\newif\ifpdfmakepagedest
+
+% when pdftex is run in dvi mode, \pdfoutput is defined (so \pdfoutput=1
+% can be set). So we test for \relax and 0 as well as \undefined,
+% borrowed from ifpdf.sty.
+\ifx\pdfoutput\undefined
+\else
+ \ifx\pdfoutput\relax
+ \else
+ \ifcase\pdfoutput
+ \else
+ \pdftrue
+ \fi
+ \fi
+\fi
+
+% PDF uses PostScript string constants for the names of xref targets,
+% for display in the outlines, and in other places. Thus, we have to
+% double any backslashes. Otherwise, a name like "\node" will be
+% interpreted as a newline (\n), followed by o, d, e. Not good.
+% http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html
+% (and related messages, the final outcome is that it is up to the TeX
+% user to double the backslashes and otherwise make the string valid, so
+% that's what we do).
+
+% double active backslashes.
+%
+{\catcode`\@=0 \catcode`\\=\active
+ @gdef@activebackslashdouble{%
+ @catcode`@\=@active
+ @let\=@doublebackslash}
+}
+
+% To handle parens, we must adopt a different approach, since parens are
+% not active characters. hyperref.dtx (which has the same problem as
+% us) handles it with this amazing macro to replace tokens, with minor
+% changes for Texinfo. It is included here under the GPL by permission
+% from the author, Heiko Oberdiek.
+%
+% #1 is the tokens to replace.
+% #2 is the replacement.
+% #3 is the control sequence with the string.
+%
+\def\HyPsdSubst#1#2#3{%
+ \def\HyPsdReplace##1#1##2\END{%
+ ##1%
+ \ifx\\##2\\%
+ \else
+ #2%
+ \HyReturnAfterFi{%
+ \HyPsdReplace##2\END
+ }%
+ \fi
+ }%
+ \xdef#3{\expandafter\HyPsdReplace#3#1\END}%
+}
+\long\def\HyReturnAfterFi#1\fi{\fi#1}
+
+% #1 is a control sequence in which to do the replacements.
+\def\backslashparens#1{%
+ \xdef#1{#1}% redefine it as its expansion; the definition is simply
+ % \lastnode when called from \setref -> \pdfmkdest.
+ \HyPsdSubst{(}{\realbackslash(}{#1}%
+ \HyPsdSubst{)}{\realbackslash)}{#1}%
+}
+
+\newhelp\nopdfimagehelp{Texinfo supports .png, .jpg, .jpeg, and .pdf images
+with PDF output, and none of those formats could be found. (.eps cannot
+be supported due to the design of the PDF format; use regular TeX (DVI
+output) for that.)}
+
+\ifpdf
+ \input pdfcolor
+ \pdfcatalog{/PageMode /UseOutlines}
+ %
+ % #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto).
+ \def\dopdfimage#1#2#3{%
+ \def\imagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}%
+ \def\imageheight{#3}\setbox2 = \hbox{\ignorespaces #3}%
+ %
+ % pdftex (and the PDF format) support .png, .jpg, .pdf (among
+ % others). Let's try in that order.
+ \let\pdfimgext=\empty
+ \begingroup
+ \openin 1 #1.png \ifeof 1
+ \openin 1 #1.jpg \ifeof 1
+ \openin 1 #1.jpeg \ifeof 1
+ \openin 1 #1.JPG \ifeof 1
+ \openin 1 #1.pdf \ifeof 1
+ \errhelp = \nopdfimagehelp
+ \errmessage{Could not find image file #1 for pdf}%
+ \else \gdef\pdfimgext{pdf}%
+ \fi
+ \else \gdef\pdfimgext{JPG}%
+ \fi
+ \else \gdef\pdfimgext{jpeg}%
+ \fi
+ \else \gdef\pdfimgext{jpg}%
+ \fi
+ \else \gdef\pdfimgext{png}%
+ \fi
+ \closein 1
+ \endgroup
+ %
+ % without \immediate, pdftex seg faults when the same image is
+ % included twice. (Version 3.14159-pre-1.0-unofficial-20010704.)
+ \ifnum\pdftexversion < 14
+ \immediate\pdfimage
+ \else
+ \immediate\pdfximage
+ \fi
+ \ifdim \wd0 >0pt width \imagewidth \fi
+ \ifdim \wd2 >0pt height \imageheight \fi
+ \ifnum\pdftexversion<13
+ #1.\pdfimgext
+ \else
+ {#1.\pdfimgext}%
+ \fi
+ \ifnum\pdftexversion < 14 \else
+ \pdfrefximage \pdflastximage
+ \fi}
+ %
+ \def\pdfmkdest#1{{%
+ % We have to set dummies so commands such as @code, and characters
+ % such as \, aren't expanded when present in a section title.
+ \indexnofonts
+ \turnoffactive
+ \activebackslashdouble
+ \makevalueexpandable
+ \def\pdfdestname{#1}%
+ \backslashparens\pdfdestname
+ \safewhatsit{\pdfdest name{\pdfdestname} xyz}%
+ }}
+ %
+ % used to mark target names; must be expandable.
+ \def\pdfmkpgn#1{#1}
+ %
+ % by default, use a color that is dark enough to print on paper as
+ % nearly black, but still distinguishable for online viewing.
+ % (Defined in pdfcolor.tex.)
+ \let\urlcolor = \BrickRed
+ \let\linkcolor = \BrickRed
+ \def\endlink{\Black\pdfendlink}
+ %
+ % Adding outlines to PDF; macros for calculating structure of outlines
+ % come from Petr Olsak
+ \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0%
+ \else \csname#1\endcsname \fi}
+ \def\advancenumber#1{\tempnum=\expnumber{#1}\relax
+ \advance\tempnum by 1
+ \expandafter\xdef\csname#1\endcsname{\the\tempnum}}
+ %
+ % #1 is the section text, which is what will be displayed in the
+ % outline by the pdf viewer. #2 is the pdf expression for the number
+ % of subentries (or empty, for subsubsections). #3 is the node text,
+ % which might be empty if this toc entry had no corresponding node.
+ % #4 is the page number
+ %
+ \def\dopdfoutline#1#2#3#4{%
+ % Generate a link to the node text if that exists; else, use the
+ % page number. We could generate a destination for the section
+ % text in the case where a section has no node, but it doesn't
+ % seem worth the trouble, since most documents are normally structured.
+ \def\pdfoutlinedest{#3}%
+ \ifx\pdfoutlinedest\empty
+ \def\pdfoutlinedest{#4}%
+ \else
+ % Doubled backslashes in the name.
+ {\activebackslashdouble \xdef\pdfoutlinedest{#3}%
+ \backslashparens\pdfoutlinedest}%
+ \fi
+ %
+ % Also double the backslashes in the display string.
+ {\activebackslashdouble \xdef\pdfoutlinetext{#1}%
+ \backslashparens\pdfoutlinetext}%
+ %
+ \pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{\pdfoutlinetext}%
+ }
+ %
+ \def\pdfmakeoutlines{%
+ \begingroup
+ % Thanh's hack / proper braces in bookmarks
+ \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace
+ \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace
+ %
+ % Read toc silently, to get counts of subentries for \pdfoutline.
+ \def\numchapentry##1##2##3##4{%
+ \def\thischapnum{##2}%
+ \def\thissecnum{0}%
+ \def\thissubsecnum{0}%
+ }%
+ \def\numsecentry##1##2##3##4{%
+ \advancenumber{chap\thischapnum}%
+ \def\thissecnum{##2}%
+ \def\thissubsecnum{0}%
+ }%
+ \def\numsubsecentry##1##2##3##4{%
+ \advancenumber{sec\thissecnum}%
+ \def\thissubsecnum{##2}%
+ }%
+ \def\numsubsubsecentry##1##2##3##4{%
+ \advancenumber{subsec\thissubsecnum}%
+ }%
+ \def\thischapnum{0}%
+ \def\thissecnum{0}%
+ \def\thissubsecnum{0}%
+ %
+ % use \def rather than \let here because we redefine \chapentry et
+ % al. a second time, below.
+ \def\appentry{\numchapentry}%
+ \def\appsecentry{\numsecentry}%
+ \def\appsubsecentry{\numsubsecentry}%
+ \def\appsubsubsecentry{\numsubsubsecentry}%
+ \def\unnchapentry{\numchapentry}%
+ \def\unnsecentry{\numsecentry}%
+ \def\unnsubsecentry{\numsubsecentry}%
+ \def\unnsubsubsecentry{\numsubsubsecentry}%
+ \readdatafile{toc}%
+ %
+ % Read toc second time, this time actually producing the outlines.
+ % The `-' means take the \expnumber as the absolute number of
+ % subentries, which we calculated on our first read of the .toc above.
+ %
+ % We use the node names as the destinations.
+ \def\numchapentry##1##2##3##4{%
+ \dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}%
+ \def\numsecentry##1##2##3##4{%
+ \dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}%
+ \def\numsubsecentry##1##2##3##4{%
+ \dopdfoutline{##1}{count-\expnumber{subsec##2}}{##3}{##4}}%
+ \def\numsubsubsecentry##1##2##3##4{% count is always zero
+ \dopdfoutline{##1}{}{##3}{##4}}%
+ %
+ % PDF outlines are displayed using system fonts, instead of
+ % document fonts. Therefore we cannot use special characters,
+ % since the encoding is unknown. For example, the eogonek from
+ % Latin 2 (0xea) gets translated to a | character. Info from
+ % Staszek Wawrykiewicz, 19 Jan 2004 04:09:24 +0100.
+ %
+ % xx to do this right, we have to translate 8-bit characters to
+ % their "best" equivalent, based on the @documentencoding. Right
+ % now, I guess we'll just let the pdf reader have its way.
+ \indexnofonts
+ \setupdatafile
+ \catcode`\\=\active \otherbackslash
+ \input \tocreadfilename
+ \endgroup
+ }
+ %
+ \def\skipspaces#1{\def\PP{#1}\def\D{|}%
+ \ifx\PP\D\let\nextsp\relax
+ \else\let\nextsp\skipspaces
+ \ifx\p\space\else\addtokens{\filename}{\PP}%
+ \advance\filenamelength by 1
+ \fi
+ \fi
+ \nextsp}
+ \def\getfilename#1{\filenamelength=0\expandafter\skipspaces#1|\relax}
+ \ifnum\pdftexversion < 14
+ \let \startlink \pdfannotlink
+ \else
+ \let \startlink \pdfstartlink
+ \fi
+ % make a live url in pdf output.
+ \def\pdfurl#1{%
+ \begingroup
+ % it seems we really need yet another set of dummies; have not
+ % tried to figure out what each command should do in the context
+ % of @url. for now, just make @/ a no-op, that's the only one
+ % people have actually reported a problem with.
+ %
+ \normalturnoffactive
+ \def\@{@}%
+ \let\/=\empty
+ \makevalueexpandable
+ \leavevmode\urlcolor
+ \startlink attr{/Border [0 0 0]}%
+ user{/Subtype /Link /A << /S /URI /URI (#1) >>}%
+ \endgroup}
+ \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}}
+ \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks}
+ \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks}
+ \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}}
+ \def\maketoks{%
+ \expandafter\poptoks\the\toksA|ENDTOKS|\relax
+ \ifx\first0\adn0
+ \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3
+ \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6
+ \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9
+ \else
+ \ifnum0=\countA\else\makelink\fi
+ \ifx\first.\let\next=\done\else
+ \let\next=\maketoks
+ \addtokens{\toksB}{\the\toksD}
+ \ifx\first,\addtokens{\toksB}{\space}\fi
+ \fi
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
+ \next}
+ \def\makelink{\addtokens{\toksB}%
+ {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0}
+ \def\pdflink#1{%
+ \startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{#1}}
+ \linkcolor #1\endlink}
+ \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st}
+\else
+ \let\pdfmkdest = \gobble
+ \let\pdfurl = \gobble
+ \let\endlink = \relax
+ \let\linkcolor = \relax
+ \let\pdfmakeoutlines = \relax
+\fi % \ifx\pdfoutput
+
+
+\message{fonts,}
+
+% Change the current font style to #1, remembering it in \curfontstyle.
+% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in
+% italics, not bold italics.
+%
+\def\setfontstyle#1{%
+ \def\curfontstyle{#1}% not as a control sequence, because we are \edef'd.
+ \csname ten#1\endcsname % change the current font
+}
+
+% Select #1 fonts with the current style.
+%
+\def\selectfonts#1{\csname #1fonts\endcsname \csname\curfontstyle\endcsname}
+
+\def\rm{\fam=0 \setfontstyle{rm}}
+\def\it{\fam=\itfam \setfontstyle{it}}
+\def\sl{\fam=\slfam \setfontstyle{sl}}
+\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf}
+\def\tt{\fam=\ttfam \setfontstyle{tt}}
+
+% Texinfo sort of supports the sans serif font style, which plain TeX does not.
+% So we set up a \sf.
+\newfam\sffam
+\def\sf{\fam=\sffam \setfontstyle{sf}}
+\let\li = \sf % Sometimes we call it \li, not \sf.
+
+% We don't need math for this font style.
+\def\ttsl{\setfontstyle{ttsl}}
+
+
+% Default leading.
+\newdimen\textleading \textleading = 13.2pt
+
+% Set the baselineskip to #1, and the lineskip and strut size
+% correspondingly. There is no deep meaning behind these magic numbers
+% used as factors; they just match (closely enough) what Knuth defined.
+%
+\def\lineskipfactor{.08333}
+\def\strutheightpercent{.70833}
+\def\strutdepthpercent {.29167}
+%
+\def\setleading#1{%
+ \normalbaselineskip = #1\relax
+ \normallineskip = \lineskipfactor\normalbaselineskip
+ \normalbaselines
+ \setbox\strutbox =\hbox{%
+ \vrule width0pt height\strutheightpercent\baselineskip
+ depth \strutdepthpercent \baselineskip
+ }%
+}
+
+%
+% PDF CMaps. See also LaTeX's t1.cmap.
+%
+% \cmapOT1
+\ifpdf
+ \begingroup
+ \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
+ \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
+%%DocumentNeededResources: ProcSet (CIDInit)
+%%IncludeResource: ProcSet (CIDInit)
+%%BeginResource: CMap (TeX-OT1-0)
+%%Title: (TeX-OT1-0 TeX OT1 0)
+%%Version: 1.000
+%%EndComments
+/CIDInit /ProcSet findresource begin
+12 dict begin
+begincmap
+/CIDSystemInfo
+<< /Registry (TeX)
+/Ordering (OT1)
+/Supplement 0
+>> def
+/CMapName /TeX-OT1-0 def
+/CMapType 2 def
+1 begincodespacerange
+<00> <7F>
+endcodespacerange
+8 beginbfrange
+<00> <01> <0393>
+<09> <0A> <03A8>
+<23> <26> <0023>
+<28> <3B> <0028>
+<3F> <5B> <003F>
+<5D> <5E> <005D>
+<61> <7A> <0061>
+<7B> <7C> <2013>
+endbfrange
+40 beginbfchar
+<02> <0398>
+<03> <039B>
+<04> <039E>
+<05> <03A0>
+<06> <03A3>
+<07> <03D2>
+<08> <03A6>
+<0B> <00660066>
+<0C> <00660069>
+<0D> <0066006C>
+<0E> <006600660069>
+<0F> <00660066006C>
+<10> <0131>
+<11> <0237>
+<12> <0060>
+<13> <00B4>
+<14> <02C7>
+<15> <02D8>
+<16> <00AF>
+<17> <02DA>
+<18> <00B8>
+<19> <00DF>
+<1A> <00E6>
+<1B> <0153>
+<1C> <00F8>
+<1D> <00C6>
+<1E> <0152>
+<1F> <00D8>
+<21> <0021>
+<22> <201D>
+<27> <2019>
+<3C> <00A1>
+<3D> <003D>
+<3E> <00BF>
+<5C> <201C>
+<5F> <02D9>
+<60> <2018>
+<7D> <02DD>
+<7E> <007E>
+<7F> <00A8>
+endbfchar
+endcmap
+CMapName currentdict /CMap defineresource pop
+end
+end
+%%EndResource
+%%EOF
+ }\endgroup
+ \expandafter\edef\csname cmapOT1\endcsname#1{%
+ \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
+ }%
+%
+% \cmapOT1IT
+ \begingroup
+ \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
+ \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
+%%DocumentNeededResources: ProcSet (CIDInit)
+%%IncludeResource: ProcSet (CIDInit)
+%%BeginResource: CMap (TeX-OT1IT-0)
+%%Title: (TeX-OT1IT-0 TeX OT1IT 0)
+%%Version: 1.000
+%%EndComments
+/CIDInit /ProcSet findresource begin
+12 dict begin
+begincmap
+/CIDSystemInfo
+<< /Registry (TeX)
+/Ordering (OT1IT)
+/Supplement 0
+>> def
+/CMapName /TeX-OT1IT-0 def
+/CMapType 2 def
+1 begincodespacerange
+<00> <7F>
+endcodespacerange
+8 beginbfrange
+<00> <01> <0393>
+<09> <0A> <03A8>
+<25> <26> <0025>
+<28> <3B> <0028>
+<3F> <5B> <003F>
+<5D> <5E> <005D>
+<61> <7A> <0061>
+<7B> <7C> <2013>
+endbfrange
+42 beginbfchar
+<02> <0398>
+<03> <039B>
+<04> <039E>
+<05> <03A0>
+<06> <03A3>
+<07> <03D2>
+<08> <03A6>
+<0B> <00660066>
+<0C> <00660069>
+<0D> <0066006C>
+<0E> <006600660069>
+<0F> <00660066006C>
+<10> <0131>
+<11> <0237>
+<12> <0060>
+<13> <00B4>
+<14> <02C7>
+<15> <02D8>
+<16> <00AF>
+<17> <02DA>
+<18> <00B8>
+<19> <00DF>
+<1A> <00E6>
+<1B> <0153>
+<1C> <00F8>
+<1D> <00C6>
+<1E> <0152>
+<1F> <00D8>
+<21> <0021>
+<22> <201D>
+<23> <0023>
+<24> <00A3>
+<27> <2019>
+<3C> <00A1>
+<3D> <003D>
+<3E> <00BF>
+<5C> <201C>
+<5F> <02D9>
+<60> <2018>
+<7D> <02DD>
+<7E> <007E>
+<7F> <00A8>
+endbfchar
+endcmap
+CMapName currentdict /CMap defineresource pop
+end
+end
+%%EndResource
+%%EOF
+ }\endgroup
+ \expandafter\edef\csname cmapOT1IT\endcsname#1{%
+ \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
+ }%
+%
+% \cmapOT1TT
+ \begingroup
+ \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
+ \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
+%%DocumentNeededResources: ProcSet (CIDInit)
+%%IncludeResource: ProcSet (CIDInit)
+%%BeginResource: CMap (TeX-OT1TT-0)
+%%Title: (TeX-OT1TT-0 TeX OT1TT 0)
+%%Version: 1.000
+%%EndComments
+/CIDInit /ProcSet findresource begin
+12 dict begin
+begincmap
+/CIDSystemInfo
+<< /Registry (TeX)
+/Ordering (OT1TT)
+/Supplement 0
+>> def
+/CMapName /TeX-OT1TT-0 def
+/CMapType 2 def
+1 begincodespacerange
+<00> <7F>
+endcodespacerange
+5 beginbfrange
+<00> <01> <0393>
+<09> <0A> <03A8>
+<21> <26> <0021>
+<28> <5F> <0028>
+<61> <7E> <0061>
+endbfrange
+32 beginbfchar
+<02> <0398>
+<03> <039B>
+<04> <039E>
+<05> <03A0>
+<06> <03A3>
+<07> <03D2>
+<08> <03A6>
+<0B> <2191>
+<0C> <2193>
+<0D> <0027>
+<0E> <00A1>
+<0F> <00BF>
+<10> <0131>
+<11> <0237>
+<12> <0060>
+<13> <00B4>
+<14> <02C7>
+<15> <02D8>
+<16> <00AF>
+<17> <02DA>
+<18> <00B8>
+<19> <00DF>
+<1A> <00E6>
+<1B> <0153>
+<1C> <00F8>
+<1D> <00C6>
+<1E> <0152>
+<1F> <00D8>
+<20> <2423>
+<27> <2019>
+<60> <2018>
+<7F> <00A8>
+endbfchar
+endcmap
+CMapName currentdict /CMap defineresource pop
+end
+end
+%%EndResource
+%%EOF
+ }\endgroup
+ \expandafter\edef\csname cmapOT1TT\endcsname#1{%
+ \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
+ }%
+\else
+ \expandafter\let\csname cmapOT1\endcsname\gobble
+ \expandafter\let\csname cmapOT1IT\endcsname\gobble
+ \expandafter\let\csname cmapOT1TT\endcsname\gobble
+\fi
+
+
+% Set the font macro #1 to the font named #2, adding on the
+% specified font prefix (normally `cm').
+% #3 is the font's design size, #4 is a scale factor, #5 is the CMap
+% encoding (currently only OT1, OT1IT and OT1TT are allowed, pass
+% empty to omit).
+\def\setfont#1#2#3#4#5{%
+ \font#1=\fontprefix#2#3 scaled #4
+ \csname cmap#5\endcsname#1%
+}
+% This is what gets called when #5 of \setfont is empty.
+\let\cmap\gobble
+
+
+% Use cm as the default font prefix.
+% To specify the font prefix, you must define \fontprefix
+% before you read in texinfo.tex.
+\ifx\fontprefix\undefined
+\def\fontprefix{cm}
+\fi
+% Support font families that don't use the same naming scheme as CM.
+\def\rmshape{r}
+\def\rmbshape{bx} %where the normal face is bold
+\def\bfshape{b}
+\def\bxshape{bx}
+\def\ttshape{tt}
+\def\ttbshape{tt}
+\def\ttslshape{sltt}
+\def\itshape{ti}
+\def\itbshape{bxti}
+\def\slshape{sl}
+\def\slbshape{bxsl}
+\def\sfshape{ss}
+\def\sfbshape{ss}
+\def\scshape{csc}
+\def\scbshape{csc}
+
+% Definitions for a main text size of 11pt. This is the default in
+% Texinfo.
+%
+\def\definetextfontsizexi{%
+% Text fonts (11.2pt, magstep1).
+\def\textnominalsize{11pt}
+\edef\mainmagstep{\magstephalf}
+\setfont\textrm\rmshape{10}{\mainmagstep}{OT1}
+\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT}
+\setfont\textbf\bfshape{10}{\mainmagstep}{OT1}
+\setfont\textit\itshape{10}{\mainmagstep}{OT1IT}
+\setfont\textsl\slshape{10}{\mainmagstep}{OT1}
+\setfont\textsf\sfshape{10}{\mainmagstep}{OT1}
+\setfont\textsc\scshape{10}{\mainmagstep}{OT1}
+\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT}
+\font\texti=cmmi10 scaled \mainmagstep
+\font\textsy=cmsy10 scaled \mainmagstep
+
+% A few fonts for @defun names and args.
+\setfont\defbf\bfshape{10}{\magstep1}{OT1}
+\setfont\deftt\ttshape{10}{\magstep1}{OT1TT}
+\setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT}
+\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf}
+
+% Fonts for indices, footnotes, small examples (9pt).
+\def\smallnominalsize{9pt}
+\setfont\smallrm\rmshape{9}{1000}{OT1}
+\setfont\smalltt\ttshape{9}{1000}{OT1TT}
+\setfont\smallbf\bfshape{10}{900}{OT1}
+\setfont\smallit\itshape{9}{1000}{OT1IT}
+\setfont\smallsl\slshape{9}{1000}{OT1}
+\setfont\smallsf\sfshape{9}{1000}{OT1}
+\setfont\smallsc\scshape{10}{900}{OT1}
+\setfont\smallttsl\ttslshape{10}{900}{OT1TT}
+\font\smalli=cmmi9
+\font\smallsy=cmsy9
+
+% Fonts for small examples (8pt).
+\def\smallernominalsize{8pt}
+\setfont\smallerrm\rmshape{8}{1000}{OT1}
+\setfont\smallertt\ttshape{8}{1000}{OT1TT}
+\setfont\smallerbf\bfshape{10}{800}{OT1}
+\setfont\smallerit\itshape{8}{1000}{OT1IT}
+\setfont\smallersl\slshape{8}{1000}{OT1}
+\setfont\smallersf\sfshape{8}{1000}{OT1}
+\setfont\smallersc\scshape{10}{800}{OT1}
+\setfont\smallerttsl\ttslshape{10}{800}{OT1TT}
+\font\smalleri=cmmi8
+\font\smallersy=cmsy8
+
+% Fonts for title page (20.4pt):
+\def\titlenominalsize{20pt}
+\setfont\titlerm\rmbshape{12}{\magstep3}{OT1}
+\setfont\titleit\itbshape{10}{\magstep4}{OT1IT}
+\setfont\titlesl\slbshape{10}{\magstep4}{OT1}
+\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT}
+\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT}
+\setfont\titlesf\sfbshape{17}{\magstep1}{OT1}
+\let\titlebf=\titlerm
+\setfont\titlesc\scbshape{10}{\magstep4}{OT1}
+\font\titlei=cmmi12 scaled \magstep3
+\font\titlesy=cmsy10 scaled \magstep4
+\def\authorrm{\secrm}
+\def\authortt{\sectt}
+
+% Chapter (and unnumbered) fonts (17.28pt).
+\def\chapnominalsize{17pt}
+\setfont\chaprm\rmbshape{12}{\magstep2}{OT1}
+\setfont\chapit\itbshape{10}{\magstep3}{OT1IT}
+\setfont\chapsl\slbshape{10}{\magstep3}{OT1}
+\setfont\chaptt\ttbshape{12}{\magstep2}{OT1TT}
+\setfont\chapttsl\ttslshape{10}{\magstep3}{OT1TT}
+\setfont\chapsf\sfbshape{17}{1000}{OT1}
+\let\chapbf=\chaprm
+\setfont\chapsc\scbshape{10}{\magstep3}{OT1}
+\font\chapi=cmmi12 scaled \magstep2
+\font\chapsy=cmsy10 scaled \magstep3
+
+% Section fonts (14.4pt).
+\def\secnominalsize{14pt}
+\setfont\secrm\rmbshape{12}{\magstep1}{OT1}
+\setfont\secit\itbshape{10}{\magstep2}{OT1IT}
+\setfont\secsl\slbshape{10}{\magstep2}{OT1}
+\setfont\sectt\ttbshape{12}{\magstep1}{OT1TT}
+\setfont\secttsl\ttslshape{10}{\magstep2}{OT1TT}
+\setfont\secsf\sfbshape{12}{\magstep1}{OT1}
+\let\secbf\secrm
+\setfont\secsc\scbshape{10}{\magstep2}{OT1}
+\font\seci=cmmi12 scaled \magstep1
+\font\secsy=cmsy10 scaled \magstep2
+
+% Subsection fonts (13.15pt).
+\def\ssecnominalsize{13pt}
+\setfont\ssecrm\rmbshape{12}{\magstephalf}{OT1}
+\setfont\ssecit\itbshape{10}{1315}{OT1IT}
+\setfont\ssecsl\slbshape{10}{1315}{OT1}
+\setfont\ssectt\ttbshape{12}{\magstephalf}{OT1TT}
+\setfont\ssecttsl\ttslshape{10}{1315}{OT1TT}
+\setfont\ssecsf\sfbshape{12}{\magstephalf}{OT1}
+\let\ssecbf\ssecrm
+\setfont\ssecsc\scbshape{10}{1315}{OT1}
+\font\sseci=cmmi12 scaled \magstephalf
+\font\ssecsy=cmsy10 scaled 1315
+
+% Reduced fonts for @acro in text (10pt).
+\def\reducednominalsize{10pt}
+\setfont\reducedrm\rmshape{10}{1000}{OT1}
+\setfont\reducedtt\ttshape{10}{1000}{OT1TT}
+\setfont\reducedbf\bfshape{10}{1000}{OT1}
+\setfont\reducedit\itshape{10}{1000}{OT1IT}
+\setfont\reducedsl\slshape{10}{1000}{OT1}
+\setfont\reducedsf\sfshape{10}{1000}{OT1}
+\setfont\reducedsc\scshape{10}{1000}{OT1}
+\setfont\reducedttsl\ttslshape{10}{1000}{OT1TT}
+\font\reducedi=cmmi10
+\font\reducedsy=cmsy10
+
+% reset the current fonts
+\textfonts
+\rm
+} % end of 11pt text font size definitions
+
+
+% Definitions to make the main text be 10pt Computer Modern, with
+% section, chapter, etc., sizes following suit. This is for the GNU
+% Press printing of the Emacs 22 manual. Maybe other manuals in the
+% future. Used with @smallbook, which sets the leading to 12pt.
+%
+\def\definetextfontsizex{%
+% Text fonts (10pt).
+\def\textnominalsize{10pt}
+\edef\mainmagstep{1000}
+\setfont\textrm\rmshape{10}{\mainmagstep}{OT1}
+\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT}
+\setfont\textbf\bfshape{10}{\mainmagstep}{OT1}
+\setfont\textit\itshape{10}{\mainmagstep}{OT1IT}
+\setfont\textsl\slshape{10}{\mainmagstep}{OT1}
+\setfont\textsf\sfshape{10}{\mainmagstep}{OT1}
+\setfont\textsc\scshape{10}{\mainmagstep}{OT1}
+\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT}
+\font\texti=cmmi10 scaled \mainmagstep
+\font\textsy=cmsy10 scaled \mainmagstep
+
+% A few fonts for @defun names and args.
+\setfont\defbf\bfshape{10}{\magstephalf}{OT1}
+\setfont\deftt\ttshape{10}{\magstephalf}{OT1TT}
+\setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT}
+\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf}
+
+% Fonts for indices, footnotes, small examples (9pt).
+\def\smallnominalsize{9pt}
+\setfont\smallrm\rmshape{9}{1000}{OT1}
+\setfont\smalltt\ttshape{9}{1000}{OT1TT}
+\setfont\smallbf\bfshape{10}{900}{OT1}
+\setfont\smallit\itshape{9}{1000}{OT1IT}
+\setfont\smallsl\slshape{9}{1000}{OT1}
+\setfont\smallsf\sfshape{9}{1000}{OT1}
+\setfont\smallsc\scshape{10}{900}{OT1}
+\setfont\smallttsl\ttslshape{10}{900}{OT1TT}
+\font\smalli=cmmi9
+\font\smallsy=cmsy9
+
+% Fonts for small examples (8pt).
+\def\smallernominalsize{8pt}
+\setfont\smallerrm\rmshape{8}{1000}{OT1}
+\setfont\smallertt\ttshape{8}{1000}{OT1TT}
+\setfont\smallerbf\bfshape{10}{800}{OT1}
+\setfont\smallerit\itshape{8}{1000}{OT1IT}
+\setfont\smallersl\slshape{8}{1000}{OT1}
+\setfont\smallersf\sfshape{8}{1000}{OT1}
+\setfont\smallersc\scshape{10}{800}{OT1}
+\setfont\smallerttsl\ttslshape{10}{800}{OT1TT}
+\font\smalleri=cmmi8
+\font\smallersy=cmsy8
+
+% Fonts for title page (20.4pt):
+\def\titlenominalsize{20pt}
+\setfont\titlerm\rmbshape{12}{\magstep3}{OT1}
+\setfont\titleit\itbshape{10}{\magstep4}{OT1IT}
+\setfont\titlesl\slbshape{10}{\magstep4}{OT1}
+\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT}
+\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT}
+\setfont\titlesf\sfbshape{17}{\magstep1}{OT1}
+\let\titlebf=\titlerm
+\setfont\titlesc\scbshape{10}{\magstep4}{OT1}
+\font\titlei=cmmi12 scaled \magstep3
+\font\titlesy=cmsy10 scaled \magstep4
+\def\authorrm{\secrm}
+\def\authortt{\sectt}
+
+% Chapter fonts (14.4pt).
+\def\chapnominalsize{14pt}
+\setfont\chaprm\rmbshape{12}{\magstep1}{OT1}
+\setfont\chapit\itbshape{10}{\magstep2}{OT1IT}
+\setfont\chapsl\slbshape{10}{\magstep2}{OT1}
+\setfont\chaptt\ttbshape{12}{\magstep1}{OT1TT}
+\setfont\chapttsl\ttslshape{10}{\magstep2}{OT1TT}
+\setfont\chapsf\sfbshape{12}{\magstep1}{OT1}
+\let\chapbf\chaprm
+\setfont\chapsc\scbshape{10}{\magstep2}{OT1}
+\font\chapi=cmmi12 scaled \magstep1
+\font\chapsy=cmsy10 scaled \magstep2
+
+% Section fonts (12pt).
+\def\secnominalsize{12pt}
+\setfont\secrm\rmbshape{12}{1000}{OT1}
+\setfont\secit\itbshape{10}{\magstep1}{OT1IT}
+\setfont\secsl\slbshape{10}{\magstep1}{OT1}
+\setfont\sectt\ttbshape{12}{1000}{OT1TT}
+\setfont\secttsl\ttslshape{10}{\magstep1}{OT1TT}
+\setfont\secsf\sfbshape{12}{1000}{OT1}
+\let\secbf\secrm
+\setfont\secsc\scbshape{10}{\magstep1}{OT1}
+\font\seci=cmmi12
+\font\secsy=cmsy10 scaled \magstep1
+
+% Subsection fonts (10pt).
+\def\ssecnominalsize{10pt}
+\setfont\ssecrm\rmbshape{10}{1000}{OT1}
+\setfont\ssecit\itbshape{10}{1000}{OT1IT}
+\setfont\ssecsl\slbshape{10}{1000}{OT1}
+\setfont\ssectt\ttbshape{10}{1000}{OT1TT}
+\setfont\ssecttsl\ttslshape{10}{1000}{OT1TT}
+\setfont\ssecsf\sfbshape{10}{1000}{OT1}
+\let\ssecbf\ssecrm
+\setfont\ssecsc\scbshape{10}{1000}{OT1}
+\font\sseci=cmmi10
+\font\ssecsy=cmsy10
+
+% Reduced fonts for @acro in text (9pt).
+\def\reducednominalsize{9pt}
+\setfont\reducedrm\rmshape{9}{1000}{OT1}
+\setfont\reducedtt\ttshape{9}{1000}{OT1TT}
+\setfont\reducedbf\bfshape{10}{900}{OT1}
+\setfont\reducedit\itshape{9}{1000}{OT1IT}
+\setfont\reducedsl\slshape{9}{1000}{OT1}
+\setfont\reducedsf\sfshape{9}{1000}{OT1}
+\setfont\reducedsc\scshape{10}{900}{OT1}
+\setfont\reducedttsl\ttslshape{10}{900}{OT1TT}
+\font\reducedi=cmmi9
+\font\reducedsy=cmsy9
+
+% reduce space between paragraphs
+\divide\parskip by 2
+
+% reset the current fonts
+\textfonts
+\rm
+} % end of 10pt text font size definitions
+
+
+% We provide the user-level command
+% @fonttextsize 10
+% (or 11) to redefine the text font size. pt is assumed.
+%
+\def\xword{10}
+\def\xiword{11}
+%
+\parseargdef\fonttextsize{%
+ \def\textsizearg{#1}%
+ \wlog{doing @fonttextsize \textsizearg}%
+ %
+ % Set \globaldefs so that documents can use this inside @tex, since
+ % makeinfo 4.8 does not support it, but we need it nonetheless.
+ %
+ \begingroup \globaldefs=1
+ \ifx\textsizearg\xword \definetextfontsizex
+ \else \ifx\textsizearg\xiword \definetextfontsizexi
+ \else
+ \errhelp=\EMsimple
+ \errmessage{@fonttextsize only supports `10' or `11', not `\textsizearg'}
+ \fi\fi
+ \endgroup
+}
+
+
+% In order for the font changes to affect most math symbols and letters,
+% we have to define the \textfont of the standard families. Since
+% texinfo doesn't allow for producing subscripts and superscripts except
+% in the main text, we don't bother to reset \scriptfont and
+% \scriptscriptfont (which would also require loading a lot more fonts).
+%
+\def\resetmathfonts{%
+ \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy
+ \textfont\itfam=\tenit \textfont\slfam=\tensl \textfont\bffam=\tenbf
+ \textfont\ttfam=\tentt \textfont\sffam=\tensf
+}
+
+% The font-changing commands redefine the meanings of \tenSTYLE, instead
+% of just \STYLE. We do this because \STYLE needs to also set the
+% current \fam for math mode. Our \STYLE (e.g., \rm) commands hardwire
+% \tenSTYLE to set the current font.
+%
+% Each font-changing command also sets the names \lsize (one size lower)
+% and \lllsize (three sizes lower). These relative commands are used in
+% the LaTeX logo and acronyms.
+%
+% This all needs generalizing, badly.
+%
+\def\textfonts{%
+ \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl
+ \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc
+ \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy
+ \let\tenttsl=\textttsl
+ \def\curfontsize{text}%
+ \def\lsize{reduced}\def\lllsize{smaller}%
+ \resetmathfonts \setleading{\textleading}}
+\def\titlefonts{%
+ \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl
+ \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc
+ \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy
+ \let\tenttsl=\titlettsl
+ \def\curfontsize{title}%
+ \def\lsize{chap}\def\lllsize{subsec}%
+ \resetmathfonts \setleading{25pt}}
+\def\titlefont#1{{\titlefonts\rm #1}}
+\def\chapfonts{%
+ \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl
+ \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc
+ \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy
+ \let\tenttsl=\chapttsl
+ \def\curfontsize{chap}%
+ \def\lsize{sec}\def\lllsize{text}%
+ \resetmathfonts \setleading{19pt}}
+\def\secfonts{%
+ \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl
+ \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc
+ \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy
+ \let\tenttsl=\secttsl
+ \def\curfontsize{sec}%
+ \def\lsize{subsec}\def\lllsize{reduced}%
+ \resetmathfonts \setleading{16pt}}
+\def\subsecfonts{%
+ \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl
+ \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc
+ \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy
+ \let\tenttsl=\ssecttsl
+ \def\curfontsize{ssec}%
+ \def\lsize{text}\def\lllsize{small}%
+ \resetmathfonts \setleading{15pt}}
+\let\subsubsecfonts = \subsecfonts
+\def\reducedfonts{%
+ \let\tenrm=\reducedrm \let\tenit=\reducedit \let\tensl=\reducedsl
+ \let\tenbf=\reducedbf \let\tentt=\reducedtt \let\reducedcaps=\reducedsc
+ \let\tensf=\reducedsf \let\teni=\reducedi \let\tensy=\reducedsy
+ \let\tenttsl=\reducedttsl
+ \def\curfontsize{reduced}%
+ \def\lsize{small}\def\lllsize{smaller}%
+ \resetmathfonts \setleading{10.5pt}}
+\def\smallfonts{%
+ \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl
+ \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc
+ \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy
+ \let\tenttsl=\smallttsl
+ \def\curfontsize{small}%
+ \def\lsize{smaller}\def\lllsize{smaller}%
+ \resetmathfonts \setleading{10.5pt}}
+\def\smallerfonts{%
+ \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl
+ \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc
+ \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy
+ \let\tenttsl=\smallerttsl
+ \def\curfontsize{smaller}%
+ \def\lsize{smaller}\def\lllsize{smaller}%
+ \resetmathfonts \setleading{9.5pt}}
+
+% Set the fonts to use with the @small... environments.
+\let\smallexamplefonts = \smallfonts
+
+% About \smallexamplefonts. If we use \smallfonts (9pt), @smallexample
+% can fit this many characters:
+% 8.5x11=86 smallbook=72 a4=90 a5=69
+% If we use \scriptfonts (8pt), then we can fit this many characters:
+% 8.5x11=90+ smallbook=80 a4=90+ a5=77
+% For me, subjectively, the few extra characters that fit aren't worth
+% the additional smallness of 8pt. So I'm making the default 9pt.
+%
+% By the way, for comparison, here's what fits with @example (10pt):
+% 8.5x11=71 smallbook=60 a4=75 a5=58
+%
+% I wish the USA used A4 paper.
+% --karl, 24jan03.
+
+
+% Set up the default fonts, so we can use them for creating boxes.
+%
+\definetextfontsizexi
+
+% Define these so they can be easily changed for other fonts.
+\def\angleleft{$\langle$}
+\def\angleright{$\rangle$}
+
+% Count depth in font-changes, for error checks
+\newcount\fontdepth \fontdepth=0
+
+% Fonts for short table of contents.
+\setfont\shortcontrm\rmshape{12}{1000}{OT1}
+\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1} % no cmb12
+\setfont\shortcontsl\slshape{12}{1000}{OT1}
+\setfont\shortconttt\ttshape{12}{1000}{OT1TT}
+
+%% Add scribe-like font environments, plus @l for inline lisp (usually sans
+%% serif) and @ii for TeX italic
+
+% \smartitalic{ARG} outputs arg in italics, followed by an italic correction
+% unless the following character is such as not to need one.
+\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else
+ \ptexslash\fi\fi\fi}
+\def\smartslanted#1{{\ifusingtt\ttsl\sl #1}\futurelet\next\smartitalicx}
+\def\smartitalic#1{{\ifusingtt\ttsl\it #1}\futurelet\next\smartitalicx}
+
+% like \smartslanted except unconditionally uses \ttsl.
+% @var is set to this for defun arguments.
+\def\ttslanted#1{{\ttsl #1}\futurelet\next\smartitalicx}
+
+% like \smartslanted except unconditionally use \sl. We never want
+% ttsl for book titles, do we?
+\def\cite#1{{\sl #1}\futurelet\next\smartitalicx}
+
+\let\i=\smartitalic
+\let\slanted=\smartslanted
+\let\var=\smartslanted
+\let\dfn=\smartslanted
+\let\emph=\smartitalic
+
+% @b, explicit bold.
+\def\b#1{{\bf #1}}
+\let\strong=\b
+
+% @sansserif, explicit sans.
+\def\sansserif#1{{\sf #1}}
+
+% We can't just use \exhyphenpenalty, because that only has effect at
+% the end of a paragraph. Restore normal hyphenation at the end of the
+% group within which \nohyphenation is presumably called.
+%
+\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation}
+\def\restorehyphenation{\hyphenchar\font = `- }
+
+% Set sfcode to normal for the chars that usually have another value.
+% Can't use plain's \frenchspacing because it uses the `\x notation, and
+% sometimes \x has an active definition that messes things up.
+%
+\catcode`@=11
+ \def\plainfrenchspacing{%
+ \sfcode\dotChar =\@m \sfcode\questChar=\@m \sfcode\exclamChar=\@m
+ \sfcode\colonChar=\@m \sfcode\semiChar =\@m \sfcode\commaChar =\@m
+ \def\endofsentencespacefactor{1000}% for @. and friends
+ }
+ \def\plainnonfrenchspacing{%
+ \sfcode`\.3000\sfcode`\?3000\sfcode`\!3000
+ \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250
+ \def\endofsentencespacefactor{3000}% for @. and friends
+ }
+\catcode`@=\other
+\def\endofsentencespacefactor{3000}% default
+
+\def\t#1{%
+ {\tt \rawbackslash \plainfrenchspacing #1}%
+ \null
+}
+\def\samp#1{`\tclose{#1}'\null}
+\setfont\keyrm\rmshape{8}{1000}{OT1}
+\font\keysy=cmsy9
+\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{%
+ \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{%
+ \vbox{\hrule\kern-0.4pt
+ \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}%
+ \kern-0.4pt\hrule}%
+ \kern-.06em\raise0.4pt\hbox{\angleright}}}}
+\def\key #1{{\nohyphenation \uppercase{#1}}\null}
+% The old definition, with no lozenge:
+%\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null}
+\def\ctrl #1{{\tt \rawbackslash \hat}#1}
+
+% @file, @option are the same as @samp.
+\let\file=\samp
+\let\option=\samp
+
+% @code is a modification of @t,
+% which makes spaces the same size as normal in the surrounding text.
+\def\tclose#1{%
+ {%
+ % Change normal interword space to be same as for the current font.
+ \spaceskip = \fontdimen2\font
+ %
+ % Switch to typewriter.
+ \tt
+ %
+ % But `\ ' produces the large typewriter interword space.
+ \def\ {{\spaceskip = 0pt{} }}%
+ %
+ % Turn off hyphenation.
+ \nohyphenation
+ %
+ \rawbackslash
+ \plainfrenchspacing
+ #1%
+ }%
+ \null
+}
+
+% We *must* turn on hyphenation at `-' and `_' in @code.
+% Otherwise, it is too hard to avoid overfull hboxes
+% in the Emacs manual, the Library manual, etc.
+
+% Unfortunately, TeX uses one parameter (\hyphenchar) to control
+% both hyphenation at - and hyphenation within words.
+% We must therefore turn them both off (\tclose does that)
+% and arrange explicitly to hyphenate at a dash.
+% -- rms.
+{
+ \catcode`\-=\active \catcode`\_=\active
+ \catcode`\'=\active \catcode`\`=\active
+ %
+ \global\def\code{\begingroup
+ \catcode\rquoteChar=\active \catcode\lquoteChar=\active
+ \let'\codequoteright \let`\codequoteleft
+ %
+ \catcode\dashChar=\active \catcode\underChar=\active
+ \ifallowcodebreaks
+ \let-\codedash
+ \let_\codeunder
+ \else
+ \let-\realdash
+ \let_\realunder
+ \fi
+ \codex
+ }
+}
+
+\def\realdash{-}
+\def\codedash{-\discretionary{}{}{}}
+\def\codeunder{%
+ % this is all so @math{@code{var_name}+1} can work. In math mode, _
+ % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.)
+ % will therefore expand the active definition of _, which is us
+ % (inside @code that is), therefore an endless loop.
+ \ifusingtt{\ifmmode
+ \mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_.
+ \else\normalunderscore \fi
+ \discretionary{}{}{}}%
+ {\_}%
+}
+\def\codex #1{\tclose{#1}\endgroup}
+
+% An additional complication: the above will allow breaks after, e.g.,
+% each of the four underscores in __typeof__. This is undesirable in
+% some manuals, especially if they don't have long identifiers in
+% general. @allowcodebreaks provides a way to control this.
+%
+\newif\ifallowcodebreaks \allowcodebreakstrue
+
+\def\keywordtrue{true}
+\def\keywordfalse{false}
+
+\parseargdef\allowcodebreaks{%
+ \def\txiarg{#1}%
+ \ifx\txiarg\keywordtrue
+ \allowcodebreakstrue
+ \else\ifx\txiarg\keywordfalse
+ \allowcodebreaksfalse
+ \else
+ \errhelp = \EMsimple
+ \errmessage{Unknown @allowcodebreaks option `\txiarg'}%
+ \fi\fi
+}
+
+% @kbd is like @code, except that if the argument is just one @key command,
+% then @kbd has no effect.
+
+% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always),
+% `example' (@kbd uses ttsl only inside of @example and friends),
+% or `code' (@kbd uses normal tty font always).
+\parseargdef\kbdinputstyle{%
+ \def\txiarg{#1}%
+ \ifx\txiarg\worddistinct
+ \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}%
+ \else\ifx\txiarg\wordexample
+ \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}%
+ \else\ifx\txiarg\wordcode
+ \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}%
+ \else
+ \errhelp = \EMsimple
+ \errmessage{Unknown @kbdinputstyle option `\txiarg'}%
+ \fi\fi\fi
+}
+\def\worddistinct{distinct}
+\def\wordexample{example}
+\def\wordcode{code}
+
+% Default is `distinct.'
+\kbdinputstyle distinct
+
+\def\xkey{\key}
+\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}%
+\ifx\one\xkey\ifx\threex\three \key{#2}%
+\else{\tclose{\kbdfont\look}}\fi
+\else{\tclose{\kbdfont\look}}\fi}
+
+% For @indicateurl, @env, @command quotes seem unnecessary, so use \code.
+\let\indicateurl=\code
+\let\env=\code
+\let\command=\code
+
+% @uref (abbreviation for `urlref') takes an optional (comma-separated)
+% second argument specifying the text to display and an optional third
+% arg as text to display instead of (rather than in addition to) the url
+% itself. First (mandatory) arg is the url. Perhaps eventually put in
+% a hypertex \special here.
+%
+\def\uref#1{\douref #1,,,\finish}
+\def\douref#1,#2,#3,#4\finish{\begingroup
+ \unsepspaces
+ \pdfurl{#1}%
+ \setbox0 = \hbox{\ignorespaces #3}%
+ \ifdim\wd0 > 0pt
+ \unhbox0 % third arg given, show only that
+ \else
+ \setbox0 = \hbox{\ignorespaces #2}%
+ \ifdim\wd0 > 0pt
+ \ifpdf
+ \unhbox0 % PDF: 2nd arg given, show only it
+ \else
+ \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url
+ \fi
+ \else
+ \code{#1}% only url given, so show it
+ \fi
+ \fi
+ \endlink
+\endgroup}
+
+% @url synonym for @uref, since that's how everyone uses it.
+%
+\let\url=\uref
+
+% rms does not like angle brackets --karl, 17may97.
+% So now @email is just like @uref, unless we are pdf.
+%
+%\def\email#1{\angleleft{\tt #1}\angleright}
+\ifpdf
+ \def\email#1{\doemail#1,,\finish}
+ \def\doemail#1,#2,#3\finish{\begingroup
+ \unsepspaces
+ \pdfurl{mailto:#1}%
+ \setbox0 = \hbox{\ignorespaces #2}%
+ \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi
+ \endlink
+ \endgroup}
+\else
+ \let\email=\uref
+\fi
+
+% Check if we are currently using a typewriter font. Since all the
+% Computer Modern typewriter fonts have zero interword stretch (and
+% shrink), and it is reasonable to expect all typewriter fonts to have
+% this property, we can check that font parameter.
+%
+\def\ifmonospace{\ifdim\fontdimen3\font=0pt }
+
+% Typeset a dimension, e.g., `in' or `pt'. The only reason for the
+% argument is to make the input look right: @dmn{pt} instead of @dmn{}pt.
+%
+\def\dmn#1{\thinspace #1}
+
+\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par}
+
+% @l was never documented to mean ``switch to the Lisp font'',
+% and it is not used as such in any manual I can find. We need it for
+% Polish suppressed-l. --karl, 22sep96.
+%\def\l#1{{\li #1}\null}
+
+% Explicit font changes: @r, @sc, undocumented @ii.
+\def\r#1{{\rm #1}} % roman font
+\def\sc#1{{\smallcaps#1}} % smallcaps font
+\def\ii#1{{\it #1}} % italic font
+
+% @acronym for "FBI", "NATO", and the like.
+% We print this one point size smaller, since it's intended for
+% all-uppercase.
+%
+\def\acronym#1{\doacronym #1,,\finish}
+\def\doacronym#1,#2,#3\finish{%
+ {\selectfonts\lsize #1}%
+ \def\temp{#2}%
+ \ifx\temp\empty \else
+ \space ({\unsepspaces \ignorespaces \temp \unskip})%
+ \fi
+}
+
+% @abbr for "Comput. J." and the like.
+% No font change, but don't do end-of-sentence spacing.
+%
+\def\abbr#1{\doabbr #1,,\finish}
+\def\doabbr#1,#2,#3\finish{%
+ {\plainfrenchspacing #1}%
+ \def\temp{#2}%
+ \ifx\temp\empty \else
+ \space ({\unsepspaces \ignorespaces \temp \unskip})%
+ \fi
+}
+
+% @pounds{} is a sterling sign, which Knuth put in the CM italic font.
+%
+\def\pounds{{\it\$}}
+
+% @euro{} comes from a separate font, depending on the current style.
+% We use the free feym* fonts from the eurosym package by Henrik
+% Theiling, which support regular, slanted, bold and bold slanted (and
+% "outlined" (blackboard board, sort of) versions, which we don't need).
+% It is available from http://www.ctan.org/tex-archive/fonts/eurosym.
+%
+% Although only regular is the truly official Euro symbol, we ignore
+% that. The Euro is designed to be slightly taller than the regular
+% font height.
+%
+% feymr - regular
+% feymo - slanted
+% feybr - bold
+% feybo - bold slanted
+%
+% There is no good (free) typewriter version, to my knowledge.
+% A feymr10 euro is ~7.3pt wide, while a normal cmtt10 char is ~5.25pt wide.
+% Hmm.
+%
+% Also doesn't work in math. Do we need to do math with euro symbols?
+% Hope not.
+%
+%
+\def\euro{{\eurofont e}}
+\def\eurofont{%
+ % We set the font at each command, rather than predefining it in
+ % \textfonts and the other font-switching commands, so that
+ % installations which never need the symbol don't have to have the
+ % font installed.
+ %
+ % There is only one designed size (nominal 10pt), so we always scale
+ % that to the current nominal size.
+ %
+ % By the way, simply using "at 1em" works for cmr10 and the like, but
+ % does not work for cmbx10 and other extended/shrunken fonts.
+ %
+ \def\eurosize{\csname\curfontsize nominalsize\endcsname}%
+ %
+ \ifx\curfontstyle\bfstylename
+ % bold:
+ \font\thiseurofont = \ifusingit{feybo10}{feybr10} at \eurosize
+ \else
+ % regular:
+ \font\thiseurofont = \ifusingit{feymo10}{feymr10} at \eurosize
+ \fi
+ \thiseurofont
+}
+
+% @registeredsymbol - R in a circle. The font for the R should really
+% be smaller yet, but lllsize is the best we can do for now.
+% Adapted from the plain.tex definition of \copyright.
+%
+\def\registeredsymbol{%
+ $^{{\ooalign{\hfil\raise.07ex\hbox{\selectfonts\lllsize R}%
+ \hfil\crcr\Orb}}%
+ }$%
+}
+
+% @textdegree - the normal degrees sign.
+%
+\def\textdegree{$^\circ$}
+
+% Laurent Siebenmann reports \Orb undefined with:
+% Textures 1.7.7 (preloaded format=plain 93.10.14) (68K) 16 APR 2004 02:38
+% so we'll define it if necessary.
+%
+\ifx\Orb\undefined
+\def\Orb{\mathhexbox20D}
+\fi
+
+
+\message{page headings,}
+
+\newskip\titlepagetopglue \titlepagetopglue = 1.5in
+\newskip\titlepagebottomglue \titlepagebottomglue = 2pc
+
+% First the title page. Must do @settitle before @titlepage.
+\newif\ifseenauthor
+\newif\iffinishedtitlepage
+
+% Do an implicit @contents or @shortcontents after @end titlepage if the
+% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage.
+%
+\newif\ifsetcontentsaftertitlepage
+ \let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue
+\newif\ifsetshortcontentsaftertitlepage
+ \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue
+
+\parseargdef\shorttitlepage{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}%
+ \endgroup\page\hbox{}\page}
+
+\envdef\titlepage{%
+ % Open one extra group, as we want to close it in the middle of \Etitlepage.
+ \begingroup
+ \parindent=0pt \textfonts
+ % Leave some space at the very top of the page.
+ \vglue\titlepagetopglue
+ % No rule at page bottom unless we print one at the top with @title.
+ \finishedtitlepagetrue
+ %
+ % Most title ``pages'' are actually two pages long, with space
+ % at the top of the second. We don't want the ragged left on the second.
+ \let\oldpage = \page
+ \def\page{%
+ \iffinishedtitlepage\else
+ \finishtitlepage
+ \fi
+ \let\page = \oldpage
+ \page
+ \null
+ }%
+}
+
+\def\Etitlepage{%
+ \iffinishedtitlepage\else
+ \finishtitlepage
+ \fi
+ % It is important to do the page break before ending the group,
+ % because the headline and footline are only empty inside the group.
+ % If we use the new definition of \page, we always get a blank page
+ % after the title page, which we certainly don't want.
+ \oldpage
+ \endgroup
+ %
+ % Need this before the \...aftertitlepage checks so that if they are
+ % in effect the toc pages will come out with page numbers.
+ \HEADINGSon
+ %
+ % If they want short, they certainly want long too.
+ \ifsetshortcontentsaftertitlepage
+ \shortcontents
+ \contents
+ \global\let\shortcontents = \relax
+ \global\let\contents = \relax
+ \fi
+ %
+ \ifsetcontentsaftertitlepage
+ \contents
+ \global\let\contents = \relax
+ \global\let\shortcontents = \relax
+ \fi
+}
+
+\def\finishtitlepage{%
+ \vskip4pt \hrule height 2pt width \hsize
+ \vskip\titlepagebottomglue
+ \finishedtitlepagetrue
+}
+
+%%% Macros to be used within @titlepage:
+
+\let\subtitlerm=\tenrm
+\def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}
+
+\def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines
+ \let\tt=\authortt}
+
+\parseargdef\title{%
+ \checkenv\titlepage
+ \leftline{\titlefonts\rm #1}
+ % print a rule at the page bottom also.
+ \finishedtitlepagefalse
+ \vskip4pt \hrule height 4pt width \hsize \vskip4pt
+}
+
+\parseargdef\subtitle{%
+ \checkenv\titlepage
+ {\subtitlefont \rightline{#1}}%
+}
+
+% @author should come last, but may come many times.
+% It can also be used inside @quotation.
+%
+\parseargdef\author{%
+ \def\temp{\quotation}%
+ \ifx\thisenv\temp
+ \def\quotationauthor{#1}% printed in \Equotation.
+ \else
+ \checkenv\titlepage
+ \ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi
+ {\authorfont \leftline{#1}}%
+ \fi
+}
+
+
+%%% Set up page headings and footings.
+
+\let\thispage=\folio
+
+\newtoks\evenheadline % headline on even pages
+\newtoks\oddheadline % headline on odd pages
+\newtoks\evenfootline % footline on even pages
+\newtoks\oddfootline % footline on odd pages
+
+% Now make TeX use those variables
+\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline
+ \else \the\evenheadline \fi}}
+\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline
+ \else \the\evenfootline \fi}\HEADINGShook}
+\let\HEADINGShook=\relax
+
+% Commands to set those variables.
+% For example, this is what @headings on does
+% @evenheading @thistitle|@thispage|@thischapter
+% @oddheading @thischapter|@thispage|@thistitle
+% @evenfooting @thisfile||
+% @oddfooting ||@thisfile
+
+
+\def\evenheading{\parsearg\evenheadingxxx}
+\def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish}
+\def\evenheadingyyy #1\|#2\|#3\|#4\finish{%
+\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+
+\def\oddheading{\parsearg\oddheadingxxx}
+\def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish}
+\def\oddheadingyyy #1\|#2\|#3\|#4\finish{%
+\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+
+\parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}%
+
+\def\evenfooting{\parsearg\evenfootingxxx}
+\def\evenfootingxxx #1{\evenfootingyyy #1\|\|\|\|\finish}
+\def\evenfootingyyy #1\|#2\|#3\|#4\finish{%
+\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+
+\def\oddfooting{\parsearg\oddfootingxxx}
+\def\oddfootingxxx #1{\oddfootingyyy #1\|\|\|\|\finish}
+\def\oddfootingyyy #1\|#2\|#3\|#4\finish{%
+ \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}%
+ %
+ % Leave some space for the footline. Hopefully ok to assume
+ % @evenfooting will not be used by itself.
+ \global\advance\pageheight by -12pt
+ \global\advance\vsize by -12pt
+}
+
+\parseargdef\everyfooting{\oddfootingxxx{#1}\evenfootingxxx{#1}}
+
+
+% @headings double turns headings on for double-sided printing.
+% @headings single turns headings on for single-sided printing.
+% @headings off turns them off.
+% @headings on same as @headings double, retained for compatibility.
+% @headings after turns on double-sided headings after this page.
+% @headings doubleafter turns on double-sided headings after this page.
+% @headings singleafter turns on single-sided headings after this page.
+% By default, they are off at the start of a document,
+% and turned `on' after @end titlepage.
+
+\def\headings #1 {\csname HEADINGS#1\endcsname}
+
+\def\HEADINGSoff{%
+\global\evenheadline={\hfil} \global\evenfootline={\hfil}
+\global\oddheadline={\hfil} \global\oddfootline={\hfil}}
+\HEADINGSoff
+% When we turn headings on, set the page number to 1.
+% For double-sided printing, put current file name in lower left corner,
+% chapter name on inside top of right hand pages, document
+% title on inside top of left hand pages, and page numbers on outside top
+% edge of all pages.
+\def\HEADINGSdouble{%
+\global\pageno=1
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\folio\hfil\thistitle}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\let\contentsalignmacro = \chapoddpage
+}
+\let\contentsalignmacro = \chappager
+
+% For single-sided printing, chapter title goes across top left of page,
+% page number on top right.
+\def\HEADINGSsingle{%
+\global\pageno=1
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\thischapter\hfil\folio}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\let\contentsalignmacro = \chappager
+}
+\def\HEADINGSon{\HEADINGSdouble}
+
+\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex}
+\let\HEADINGSdoubleafter=\HEADINGSafter
+\def\HEADINGSdoublex{%
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\folio\hfil\thistitle}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\let\contentsalignmacro = \chapoddpage
+}
+
+\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex}
+\def\HEADINGSsinglex{%
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\thischapter\hfil\folio}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\let\contentsalignmacro = \chappager
+}
+
+% Subroutines used in generating headings
+% This produces Day Month Year style of output.
+% Only define if not already defined, in case a txi-??.tex file has set
+% up a different format (e.g., txi-cs.tex does this).
+\ifx\today\undefined
+\def\today{%
+ \number\day\space
+ \ifcase\month
+ \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr
+ \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug
+ \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec
+ \fi
+ \space\number\year}
+\fi
+
+% @settitle line... specifies the title of the document, for headings.
+% It generates no output of its own.
+\def\thistitle{\putwordNoTitle}
+\def\settitle{\parsearg{\gdef\thistitle}}
+
+
+\message{tables,}
+% Tables -- @table, @ftable, @vtable, @item(x).
+
+% default indentation of table text
+\newdimen\tableindent \tableindent=.8in
+% default indentation of @itemize and @enumerate text
+\newdimen\itemindent \itemindent=.3in
+% margin between end of table item and start of table text.
+\newdimen\itemmargin \itemmargin=.1in
+
+% used internally for \itemindent minus \itemmargin
+\newdimen\itemmax
+
+% Note @table, @ftable, and @vtable define @item, @itemx, etc., with
+% these defs.
+% They also define \itemindex
+% to index the item name in whatever manner is desired (perhaps none).
+
+\newif\ifitemxneedsnegativevskip
+
+\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi}
+
+\def\internalBitem{\smallbreak \parsearg\itemzzz}
+\def\internalBitemx{\itemxpar \parsearg\itemzzz}
+
+\def\itemzzz #1{\begingroup %
+ \advance\hsize by -\rightskip
+ \advance\hsize by -\tableindent
+ \setbox0=\hbox{\itemindicate{#1}}%
+ \itemindex{#1}%
+ \nobreak % This prevents a break before @itemx.
+ %
+ % If the item text does not fit in the space we have, put it on a line
+ % by itself, and do not allow a page break either before or after that
+ % line. We do not start a paragraph here because then if the next
+ % command is, e.g., @kindex, the whatsit would get put into the
+ % horizontal list on a line by itself, resulting in extra blank space.
+ \ifdim \wd0>\itemmax
+ %
+ % Make this a paragraph so we get the \parskip glue and wrapping,
+ % but leave it ragged-right.
+ \begingroup
+ \advance\leftskip by-\tableindent
+ \advance\hsize by\tableindent
+ \advance\rightskip by0pt plus1fil
+ \leavevmode\unhbox0\par
+ \endgroup
+ %
+ % We're going to be starting a paragraph, but we don't want the
+ % \parskip glue -- logically it's part of the @item we just started.
+ \nobreak \vskip-\parskip
+ %
+ % Stop a page break at the \parskip glue coming up. However, if
+ % what follows is an environment such as @example, there will be no
+ % \parskip glue; then the negative vskip we just inserted would
+ % cause the example and the item to crash together. So we use this
+ % bizarre value of 10001 as a signal to \aboveenvbreak to insert
+ % \parskip glue after all. Section titles are handled this way also.
+ %
+ \penalty 10001
+ \endgroup
+ \itemxneedsnegativevskipfalse
+ \else
+ % The item text fits into the space. Start a paragraph, so that the
+ % following text (if any) will end up on the same line.
+ \noindent
+ % Do this with kerns and \unhbox so that if there is a footnote in
+ % the item text, it can migrate to the main vertical list and
+ % eventually be printed.
+ \nobreak\kern-\tableindent
+ \dimen0 = \itemmax \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0
+ \unhbox0
+ \nobreak\kern\dimen0
+ \endgroup
+ \itemxneedsnegativevskiptrue
+ \fi
+}
+
+\def\item{\errmessage{@item while not in a list environment}}
+\def\itemx{\errmessage{@itemx while not in a list environment}}
+
+% @table, @ftable, @vtable.
+\envdef\table{%
+ \let\itemindex\gobble
+ \tablecheck{table}%
+}
+\envdef\ftable{%
+ \def\itemindex ##1{\doind {fn}{\code{##1}}}%
+ \tablecheck{ftable}%
+}
+\envdef\vtable{%
+ \def\itemindex ##1{\doind {vr}{\code{##1}}}%
+ \tablecheck{vtable}%
+}
+\def\tablecheck#1{%
+ \ifnum \the\catcode`\^^M=\active
+ \endgroup
+ \errmessage{This command won't work in this context; perhaps the problem is
+ that we are \inenvironment\thisenv}%
+ \def\next{\doignore{#1}}%
+ \else
+ \let\next\tablex
+ \fi
+ \next
+}
+\def\tablex#1{%
+ \def\itemindicate{#1}%
+ \parsearg\tabley
+}
+\def\tabley#1{%
+ {%
+ \makevalueexpandable
+ \edef\temp{\noexpand\tablez #1\space\space\space}%
+ \expandafter
+ }\temp \endtablez
+}
+\def\tablez #1 #2 #3 #4\endtablez{%
+ \aboveenvbreak
+ \ifnum 0#1>0 \advance \leftskip by #1\mil \fi
+ \ifnum 0#2>0 \tableindent=#2\mil \fi
+ \ifnum 0#3>0 \advance \rightskip by #3\mil \fi
+ \itemmax=\tableindent
+ \advance \itemmax by -\itemmargin
+ \advance \leftskip by \tableindent
+ \exdentamount=\tableindent
+ \parindent = 0pt
+ \parskip = \smallskipamount
+ \ifdim \parskip=0pt \parskip=2pt \fi
+ \let\item = \internalBitem
+ \let\itemx = \internalBitemx
+}
+\def\Etable{\endgraf\afterenvbreak}
+\let\Eftable\Etable
+\let\Evtable\Etable
+\let\Eitemize\Etable
+\let\Eenumerate\Etable
+
+% This is the counter used by @enumerate, which is really @itemize
+
+\newcount \itemno
+
+\envdef\itemize{\parsearg\doitemize}
+
+\def\doitemize#1{%
+ \aboveenvbreak
+ \itemmax=\itemindent
+ \advance\itemmax by -\itemmargin
+ \advance\leftskip by \itemindent
+ \exdentamount=\itemindent
+ \parindent=0pt
+ \parskip=\smallskipamount
+ \ifdim\parskip=0pt \parskip=2pt \fi
+ \def\itemcontents{#1}%
+ % @itemize with no arg is equivalent to @itemize @bullet.
+ \ifx\itemcontents\empty\def\itemcontents{\bullet}\fi
+ \let\item=\itemizeitem
+}
+
+% Definition of @item while inside @itemize and @enumerate.
+%
+\def\itemizeitem{%
+ \advance\itemno by 1 % for enumerations
+ {\let\par=\endgraf \smallbreak}% reasonable place to break
+ {%
+ % If the document has an @itemize directly after a section title, a
+ % \nobreak will be last on the list, and \sectionheading will have
+ % done a \vskip-\parskip. In that case, we don't want to zero
+ % parskip, or the item text will crash with the heading. On the
+ % other hand, when there is normal text preceding the item (as there
+ % usually is), we do want to zero parskip, or there would be too much
+ % space. In that case, we won't have a \nobreak before. At least
+ % that's the theory.
+ \ifnum\lastpenalty<10000 \parskip=0in \fi
+ \noindent
+ \hbox to 0pt{\hss \itemcontents \kern\itemmargin}%
+ \vadjust{\penalty 1200}}% not good to break after first line of item.
+ \flushcr
+}
+
+% \splitoff TOKENS\endmark defines \first to be the first token in
+% TOKENS, and \rest to be the remainder.
+%
+\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}%
+
+% Allow an optional argument of an uppercase letter, lowercase letter,
+% or number, to specify the first label in the enumerated list. No
+% argument is the same as `1'.
+%
+\envparseargdef\enumerate{\enumeratey #1 \endenumeratey}
+\def\enumeratey #1 #2\endenumeratey{%
+ % If we were given no argument, pretend we were given `1'.
+ \def\thearg{#1}%
+ \ifx\thearg\empty \def\thearg{1}\fi
+ %
+ % Detect if the argument is a single token. If so, it might be a
+ % letter. Otherwise, the only valid thing it can be is a number.
+ % (We will always have one token, because of the test we just made.
+ % This is a good thing, since \splitoff doesn't work given nothing at
+ % all -- the first parameter is undelimited.)
+ \expandafter\splitoff\thearg\endmark
+ \ifx\rest\empty
+ % Only one token in the argument. It could still be anything.
+ % A ``lowercase letter'' is one whose \lccode is nonzero.
+ % An ``uppercase letter'' is one whose \lccode is both nonzero, and
+ % not equal to itself.
+ % Otherwise, we assume it's a number.
+ %
+ % We need the \relax at the end of the \ifnum lines to stop TeX from
+ % continuing to look for a <number>.
+ %
+ \ifnum\lccode\expandafter`\thearg=0\relax
+ \numericenumerate % a number (we hope)
+ \else
+ % It's a letter.
+ \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax
+ \lowercaseenumerate % lowercase letter
+ \else
+ \uppercaseenumerate % uppercase letter
+ \fi
+ \fi
+ \else
+ % Multiple tokens in the argument. We hope it's a number.
+ \numericenumerate
+ \fi
+}
+
+% An @enumerate whose labels are integers. The starting integer is
+% given in \thearg.
+%
+\def\numericenumerate{%
+ \itemno = \thearg
+ \startenumeration{\the\itemno}%
+}
+
+% The starting (lowercase) letter is in \thearg.
+\def\lowercaseenumerate{%
+ \itemno = \expandafter`\thearg
+ \startenumeration{%
+ % Be sure we're not beyond the end of the alphabet.
+ \ifnum\itemno=0
+ \errmessage{No more lowercase letters in @enumerate; get a bigger
+ alphabet}%
+ \fi
+ \char\lccode\itemno
+ }%
+}
+
+% The starting (uppercase) letter is in \thearg.
+\def\uppercaseenumerate{%
+ \itemno = \expandafter`\thearg
+ \startenumeration{%
+ % Be sure we're not beyond the end of the alphabet.
+ \ifnum\itemno=0
+ \errmessage{No more uppercase letters in @enumerate; get a bigger
+ alphabet}
+ \fi
+ \char\uccode\itemno
+ }%
+}
+
+% Call \doitemize, adding a period to the first argument and supplying the
+% common last two arguments. Also subtract one from the initial value in
+% \itemno, since @item increments \itemno.
+%
+\def\startenumeration#1{%
+ \advance\itemno by -1
+ \doitemize{#1.}\flushcr
+}
+
+% @alphaenumerate and @capsenumerate are abbreviations for giving an arg
+% to @enumerate.
+%
+\def\alphaenumerate{\enumerate{a}}
+\def\capsenumerate{\enumerate{A}}
+\def\Ealphaenumerate{\Eenumerate}
+\def\Ecapsenumerate{\Eenumerate}
+
+
+% @multitable macros
+% Amy Hendrickson, 8/18/94, 3/6/96
+%
+% @multitable ... @end multitable will make as many columns as desired.
+% Contents of each column will wrap at width given in preamble. Width
+% can be specified either with sample text given in a template line,
+% or in percent of \hsize, the current width of text on page.
+
+% Table can continue over pages but will only break between lines.
+
+% To make preamble:
+%
+% Either define widths of columns in terms of percent of \hsize:
+% @multitable @columnfractions .25 .3 .45
+% @item ...
+%
+% Numbers following @columnfractions are the percent of the total
+% current hsize to be used for each column. You may use as many
+% columns as desired.
+
+
+% Or use a template:
+% @multitable {Column 1 template} {Column 2 template} {Column 3 template}
+% @item ...
+% using the widest term desired in each column.
+
+% Each new table line starts with @item, each subsequent new column
+% starts with @tab. Empty columns may be produced by supplying @tab's
+% with nothing between them for as many times as empty columns are needed,
+% ie, @tab@tab@tab will produce two empty columns.
+
+% @item, @tab do not need to be on their own lines, but it will not hurt
+% if they are.
+
+% Sample multitable:
+
+% @multitable {Column 1 template} {Column 2 template} {Column 3 template}
+% @item first col stuff @tab second col stuff @tab third col
+% @item
+% first col stuff
+% @tab
+% second col stuff
+% @tab
+% third col
+% @item first col stuff @tab second col stuff
+% @tab Many paragraphs of text may be used in any column.
+%
+% They will wrap at the width determined by the template.
+% @item@tab@tab This will be in third column.
+% @end multitable
+
+% Default dimensions may be reset by user.
+% @multitableparskip is vertical space between paragraphs in table.
+% @multitableparindent is paragraph indent in table.
+% @multitablecolmargin is horizontal space to be left between columns.
+% @multitablelinespace is space to leave between table items, baseline
+% to baseline.
+% 0pt means it depends on current normal line spacing.
+%
+\newskip\multitableparskip
+\newskip\multitableparindent
+\newdimen\multitablecolspace
+\newskip\multitablelinespace
+\multitableparskip=0pt
+\multitableparindent=6pt
+\multitablecolspace=12pt
+\multitablelinespace=0pt
+
+% Macros used to set up halign preamble:
+%
+\let\endsetuptable\relax
+\def\xendsetuptable{\endsetuptable}
+\let\columnfractions\relax
+\def\xcolumnfractions{\columnfractions}
+\newif\ifsetpercent
+
+% #1 is the @columnfraction, usually a decimal number like .5, but might
+% be just 1. We just use it, whatever it is.
+%
+\def\pickupwholefraction#1 {%
+ \global\advance\colcount by 1
+ \expandafter\xdef\csname col\the\colcount\endcsname{#1\hsize}%
+ \setuptable
+}
+
+\newcount\colcount
+\def\setuptable#1{%
+ \def\firstarg{#1}%
+ \ifx\firstarg\xendsetuptable
+ \let\go = \relax
+ \else
+ \ifx\firstarg\xcolumnfractions
+ \global\setpercenttrue
+ \else
+ \ifsetpercent
+ \let\go\pickupwholefraction
+ \else
+ \global\advance\colcount by 1
+ \setbox0=\hbox{#1\unskip\space}% Add a normal word space as a
+ % separator; typically that is always in the input, anyway.
+ \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}%
+ \fi
+ \fi
+ \ifx\go\pickupwholefraction
+ % Put the argument back for the \pickupwholefraction call, so
+ % we'll always have a period there to be parsed.
+ \def\go{\pickupwholefraction#1}%
+ \else
+ \let\go = \setuptable
+ \fi%
+ \fi
+ \go
+}
+
+% multitable-only commands.
+%
+% @headitem starts a heading row, which we typeset in bold.
+% Assignments have to be global since we are inside the implicit group
+% of an alignment entry. Note that \everycr resets \everytab.
+\def\headitem{\checkenv\multitable \crcr \global\everytab={\bf}\the\everytab}%
+%
+% A \tab used to include \hskip1sp. But then the space in a template
+% line is not enough. That is bad. So let's go back to just `&' until
+% we encounter the problem it was intended to solve again.
+% --karl, nathan@acm.org, 20apr99.
+\def\tab{\checkenv\multitable &\the\everytab}%
+
+% @multitable ... @end multitable definitions:
+%
+\newtoks\everytab % insert after every tab.
+%
+\envdef\multitable{%
+ \vskip\parskip
+ \startsavinginserts
+ %
+ % @item within a multitable starts a normal row.
+ % We use \def instead of \let so that if one of the multitable entries
+ % contains an @itemize, we don't choke on the \item (seen as \crcr aka
+ % \endtemplate) expanding \doitemize.
+ \def\item{\crcr}%
+ %
+ \tolerance=9500
+ \hbadness=9500
+ \setmultitablespacing
+ \parskip=\multitableparskip
+ \parindent=\multitableparindent
+ \overfullrule=0pt
+ \global\colcount=0
+ %
+ \everycr = {%
+ \noalign{%
+ \global\everytab={}%
+ \global\colcount=0 % Reset the column counter.
+ % Check for saved footnotes, etc.
+ \checkinserts
+ % Keeps underfull box messages off when table breaks over pages.
+ %\filbreak
+ % Maybe so, but it also creates really weird page breaks when the
+ % table breaks over pages. Wouldn't \vfil be better? Wait until the
+ % problem manifests itself, so it can be fixed for real --karl.
+ }%
+ }%
+ %
+ \parsearg\domultitable
+}
+\def\domultitable#1{%
+ % To parse everything between @multitable and @item:
+ \setuptable#1 \endsetuptable
+ %
+ % This preamble sets up a generic column definition, which will
+ % be used as many times as user calls for columns.
+ % \vtop will set a single line and will also let text wrap and
+ % continue for many paragraphs if desired.
+ \halign\bgroup &%
+ \global\advance\colcount by 1
+ \multistrut
+ \vtop{%
+ % Use the current \colcount to find the correct column width:
+ \hsize=\expandafter\csname col\the\colcount\endcsname
+ %
+ % In order to keep entries from bumping into each other
+ % we will add a \leftskip of \multitablecolspace to all columns after
+ % the first one.
+ %
+ % If a template has been used, we will add \multitablecolspace
+ % to the width of each template entry.
+ %
+ % If the user has set preamble in terms of percent of \hsize we will
+ % use that dimension as the width of the column, and the \leftskip
+ % will keep entries from bumping into each other. Table will start at
+ % left margin and final column will justify at right margin.
+ %
+ % Make sure we don't inherit \rightskip from the outer environment.
+ \rightskip=0pt
+ \ifnum\colcount=1
+ % The first column will be indented with the surrounding text.
+ \advance\hsize by\leftskip
+ \else
+ \ifsetpercent \else
+ % If user has not set preamble in terms of percent of \hsize
+ % we will advance \hsize by \multitablecolspace.
+ \advance\hsize by \multitablecolspace
+ \fi
+ % In either case we will make \leftskip=\multitablecolspace:
+ \leftskip=\multitablecolspace
+ \fi
+ % Ignoring space at the beginning and end avoids an occasional spurious
+ % blank line, when TeX decides to break the line at the space before the
+ % box from the multistrut, so the strut ends up on a line by itself.
+ % For example:
+ % @multitable @columnfractions .11 .89
+ % @item @code{#}
+ % @tab Legal holiday which is valid in major parts of the whole country.
+ % Is automatically provided with highlighting sequences respectively
+ % marking characters.
+ \noindent\ignorespaces##\unskip\multistrut
+ }\cr
+}
+\def\Emultitable{%
+ \crcr
+ \egroup % end the \halign
+ \global\setpercentfalse
+}
+
+\def\setmultitablespacing{%
+ \def\multistrut{\strut}% just use the standard line spacing
+ %
+ % Compute \multitablelinespace (if not defined by user) for use in
+ % \multitableparskip calculation. We used define \multistrut based on
+ % this, but (ironically) that caused the spacing to be off.
+ % See bug-texinfo report from Werner Lemberg, 31 Oct 2004 12:52:20 +0100.
+\ifdim\multitablelinespace=0pt
+\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip
+\global\advance\multitablelinespace by-\ht0
+\fi
+%% Test to see if parskip is larger than space between lines of
+%% table. If not, do nothing.
+%% If so, set to same dimension as multitablelinespace.
+\ifdim\multitableparskip>\multitablelinespace
+\global\multitableparskip=\multitablelinespace
+\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller
+ %% than skip between lines in the table.
+\fi%
+\ifdim\multitableparskip=0pt
+\global\multitableparskip=\multitablelinespace
+\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller
+ %% than skip between lines in the table.
+\fi}
+
+
+\message{conditionals,}
+
+% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotplaintext,
+% @ifnotxml always succeed. They currently do nothing; we don't
+% attempt to check whether the conditionals are properly nested. But we
+% have to remember that they are conditionals, so that @end doesn't
+% attempt to close an environment group.
+%
+\def\makecond#1{%
+ \expandafter\let\csname #1\endcsname = \relax
+ \expandafter\let\csname iscond.#1\endcsname = 1
+}
+\makecond{iftex}
+\makecond{ifnotdocbook}
+\makecond{ifnothtml}
+\makecond{ifnotinfo}
+\makecond{ifnotplaintext}
+\makecond{ifnotxml}
+
+% Ignore @ignore, @ifhtml, @ifinfo, and the like.
+%
+\def\direntry{\doignore{direntry}}
+\def\documentdescription{\doignore{documentdescription}}
+\def\docbook{\doignore{docbook}}
+\def\html{\doignore{html}}
+\def\ifdocbook{\doignore{ifdocbook}}
+\def\ifhtml{\doignore{ifhtml}}
+\def\ifinfo{\doignore{ifinfo}}
+\def\ifnottex{\doignore{ifnottex}}
+\def\ifplaintext{\doignore{ifplaintext}}
+\def\ifxml{\doignore{ifxml}}
+\def\ignore{\doignore{ignore}}
+\def\menu{\doignore{menu}}
+\def\xml{\doignore{xml}}
+
+% Ignore text until a line `@end #1', keeping track of nested conditionals.
+%
+% A count to remember the depth of nesting.
+\newcount\doignorecount
+
+\def\doignore#1{\begingroup
+ % Scan in ``verbatim'' mode:
+ \obeylines
+ \catcode`\@ = \other
+ \catcode`\{ = \other
+ \catcode`\} = \other
+ %
+ % Make sure that spaces turn into tokens that match what \doignoretext wants.
+ \spaceisspace
+ %
+ % Count number of #1's that we've seen.
+ \doignorecount = 0
+ %
+ % Swallow text until we reach the matching `@end #1'.
+ \dodoignore{#1}%
+}
+
+{ \catcode`_=11 % We want to use \_STOP_ which cannot appear in texinfo source.
+ \obeylines %
+ %
+ \gdef\dodoignore#1{%
+ % #1 contains the command name as a string, e.g., `ifinfo'.
+ %
+ % Define a command to find the next `@end #1'.
+ \long\def\doignoretext##1^^M@end #1{%
+ \doignoretextyyy##1^^M@#1\_STOP_}%
+ %
+ % And this command to find another #1 command, at the beginning of a
+ % line. (Otherwise, we would consider a line `@c @ifset', for
+ % example, to count as an @ifset for nesting.)
+ \long\def\doignoretextyyy##1^^M@#1##2\_STOP_{\doignoreyyy{##2}\_STOP_}%
+ %
+ % And now expand that command.
+ \doignoretext ^^M%
+ }%
+}
+
+\def\doignoreyyy#1{%
+ \def\temp{#1}%
+ \ifx\temp\empty % Nothing found.
+ \let\next\doignoretextzzz
+ \else % Found a nested condition, ...
+ \advance\doignorecount by 1
+ \let\next\doignoretextyyy % ..., look for another.
+ % If we're here, #1 ends with ^^M\ifinfo (for example).
+ \fi
+ \next #1% the token \_STOP_ is present just after this macro.
+}
+
+% We have to swallow the remaining "\_STOP_".
+%
+\def\doignoretextzzz#1{%
+ \ifnum\doignorecount = 0 % We have just found the outermost @end.
+ \let\next\enddoignore
+ \else % Still inside a nested condition.
+ \advance\doignorecount by -1
+ \let\next\doignoretext % Look for the next @end.
+ \fi
+ \next
+}
+
+% Finish off ignored text.
+{ \obeylines%
+ % Ignore anything after the last `@end #1'; this matters in verbatim
+ % environments, where otherwise the newline after an ignored conditional
+ % would result in a blank line in the output.
+ \gdef\enddoignore#1^^M{\endgroup\ignorespaces}%
+}
+
+
+% @set VAR sets the variable VAR to an empty value.
+% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE.
+%
+% Since we want to separate VAR from REST-OF-LINE (which might be
+% empty), we can't just use \parsearg; we have to insert a space of our
+% own to delimit the rest of the line, and then take it out again if we
+% didn't need it.
+% We rely on the fact that \parsearg sets \catcode`\ =10.
+%
+\parseargdef\set{\setyyy#1 \endsetyyy}
+\def\setyyy#1 #2\endsetyyy{%
+ {%
+ \makevalueexpandable
+ \def\temp{#2}%
+ \edef\next{\gdef\makecsname{SET#1}}%
+ \ifx\temp\empty
+ \next{}%
+ \else
+ \setzzz#2\endsetzzz
+ \fi
+ }%
+}
+% Remove the trailing space \setxxx inserted.
+\def\setzzz#1 \endsetzzz{\next{#1}}
+
+% @clear VAR clears (i.e., unsets) the variable VAR.
+%
+\parseargdef\clear{%
+ {%
+ \makevalueexpandable
+ \global\expandafter\let\csname SET#1\endcsname=\relax
+ }%
+}
+
+% @value{foo} gets the text saved in variable foo.
+\def\value{\begingroup\makevalueexpandable\valuexxx}
+\def\valuexxx#1{\expandablevalue{#1}\endgroup}
+{
+ \catcode`\- = \active \catcode`\_ = \active
+ %
+ \gdef\makevalueexpandable{%
+ \let\value = \expandablevalue
+ % We don't want these characters active, ...
+ \catcode`\-=\other \catcode`\_=\other
+ % ..., but we might end up with active ones in the argument if
+ % we're called from @code, as @code{@value{foo-bar_}}, though.
+ % So \let them to their normal equivalents.
+ \let-\realdash \let_\normalunderscore
+ }
+}
+
+% We have this subroutine so that we can handle at least some @value's
+% properly in indexes (we call \makevalueexpandable in \indexdummies).
+% The command has to be fully expandable (if the variable is set), since
+% the result winds up in the index file. This means that if the
+% variable's value contains other Texinfo commands, it's almost certain
+% it will fail (although perhaps we could fix that with sufficient work
+% to do a one-level expansion on the result, instead of complete).
+%
+\def\expandablevalue#1{%
+ \expandafter\ifx\csname SET#1\endcsname\relax
+ {[No value for ``#1'']}%
+ \message{Variable `#1', used in @value, is not set.}%
+ \else
+ \csname SET#1\endcsname
+ \fi
+}
+
+% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined
+% with @set.
+%
+% To get special treatment of `@end ifset,' call \makeond and the redefine.
+%
+\makecond{ifset}
+\def\ifset{\parsearg{\doifset{\let\next=\ifsetfail}}}
+\def\doifset#1#2{%
+ {%
+ \makevalueexpandable
+ \let\next=\empty
+ \expandafter\ifx\csname SET#2\endcsname\relax
+ #1% If not set, redefine \next.
+ \fi
+ \expandafter
+ }\next
+}
+\def\ifsetfail{\doignore{ifset}}
+
+% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been
+% defined with @set, or has been undefined with @clear.
+%
+% The `\else' inside the `\doifset' parameter is a trick to reuse the
+% above code: if the variable is not set, do nothing, if it is set,
+% then redefine \next to \ifclearfail.
+%
+\makecond{ifclear}
+\def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}}
+\def\ifclearfail{\doignore{ifclear}}
+
+% @dircategory CATEGORY -- specify a category of the dir file
+% which this file should belong to. Ignore this in TeX.
+\let\dircategory=\comment
+
+% @defininfoenclose.
+\let\definfoenclose=\comment
+
+
+\message{indexing,}
+% Index generation facilities
+
+% Define \newwrite to be identical to plain tex's \newwrite
+% except not \outer, so it can be used within macros and \if's.
+\edef\newwrite{\makecsname{ptexnewwrite}}
+
+% \newindex {foo} defines an index named foo.
+% It automatically defines \fooindex such that
+% \fooindex ...rest of line... puts an entry in the index foo.
+% It also defines \fooindfile to be the number of the output channel for
+% the file that accumulates this index. The file's extension is foo.
+% The name of an index should be no more than 2 characters long
+% for the sake of vms.
+%
+\def\newindex#1{%
+ \iflinks
+ \expandafter\newwrite \csname#1indfile\endcsname
+ \openout \csname#1indfile\endcsname \jobname.#1 % Open the file
+ \fi
+ \expandafter\xdef\csname#1index\endcsname{% % Define @#1index
+ \noexpand\doindex{#1}}
+}
+
+% @defindex foo == \newindex{foo}
+%
+\def\defindex{\parsearg\newindex}
+
+% Define @defcodeindex, like @defindex except put all entries in @code.
+%
+\def\defcodeindex{\parsearg\newcodeindex}
+%
+\def\newcodeindex#1{%
+ \iflinks
+ \expandafter\newwrite \csname#1indfile\endcsname
+ \openout \csname#1indfile\endcsname \jobname.#1
+ \fi
+ \expandafter\xdef\csname#1index\endcsname{%
+ \noexpand\docodeindex{#1}}%
+}
+
+
+% @synindex foo bar makes index foo feed into index bar.
+% Do this instead of @defindex foo if you don't want it as a separate index.
+%
+% @syncodeindex foo bar similar, but put all entries made for index foo
+% inside @code.
+%
+\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}}
+\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}}
+
+% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo),
+% #3 the target index (bar).
+\def\dosynindex#1#2#3{%
+ % Only do \closeout if we haven't already done it, else we'll end up
+ % closing the target index.
+ \expandafter \ifx\csname donesynindex#2\endcsname \undefined
+ % The \closeout helps reduce unnecessary open files; the limit on the
+ % Acorn RISC OS is a mere 16 files.
+ \expandafter\closeout\csname#2indfile\endcsname
+ \expandafter\let\csname\donesynindex#2\endcsname = 1
+ \fi
+ % redefine \fooindfile:
+ \expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname
+ \expandafter\let\csname#2indfile\endcsname=\temp
+ % redefine \fooindex:
+ \expandafter\xdef\csname#2index\endcsname{\noexpand#1{#3}}%
+}
+
+% Define \doindex, the driver for all \fooindex macros.
+% Argument #1 is generated by the calling \fooindex macro,
+% and it is "foo", the name of the index.
+
+% \doindex just uses \parsearg; it calls \doind for the actual work.
+% This is because \doind is more useful to call from other macros.
+
+% There is also \dosubind {index}{topic}{subtopic}
+% which makes an entry in a two-level index such as the operation index.
+
+\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer}
+\def\singleindexer #1{\doind{\indexname}{#1}}
+
+% like the previous two, but they put @code around the argument.
+\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer}
+\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}}
+
+% Take care of Texinfo commands that can appear in an index entry.
+% Since there are some commands we want to expand, and others we don't,
+% we have to laboriously prevent expansion for those that we don't.
+%
+\def\indexdummies{%
+ \escapechar = `\\ % use backslash in output files.
+ \def\@{@}% change to @@ when we switch to @ as escape char in index files.
+ \def\ {\realbackslash\space }%
+ %
+ % Need these in case \tex is in effect and \{ is a \delimiter again.
+ % But can't use \lbracecmd and \rbracecmd because texindex assumes
+ % braces and backslashes are used only as delimiters.
+ \let\{ = \mylbrace
+ \let\} = \myrbrace
+ %
+ % I don't entirely understand this, but when an index entry is
+ % generated from a macro call, the \endinput which \scanmacro inserts
+ % causes processing to be prematurely terminated. This is,
+ % apparently, because \indexsorttmp is fully expanded, and \endinput
+ % is an expandable command. The redefinition below makes \endinput
+ % disappear altogether for that purpose -- although logging shows that
+ % processing continues to some further point. On the other hand, it
+ % seems \endinput does not hurt in the printed index arg, since that
+ % is still getting written without apparent harm.
+ %
+ % Sample source (mac-idx3.tex, reported by Graham Percival to
+ % help-texinfo, 22may06):
+ % @macro funindex {WORD}
+ % @findex xyz
+ % @end macro
+ % ...
+ % @funindex commtest
+ %
+ % The above is not enough to reproduce the bug, but it gives the flavor.
+ %
+ % Sample whatsit resulting:
+ % .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}}
+ %
+ % So:
+ \let\endinput = \empty
+ %
+ % Do the redefinitions.
+ \commondummies
+}
+
+% For the aux and toc files, @ is the escape character. So we want to
+% redefine everything using @ as the escape character (instead of
+% \realbackslash, still used for index files). When everything uses @,
+% this will be simpler.
+%
+\def\atdummies{%
+ \def\@{@@}%
+ \def\ {@ }%
+ \let\{ = \lbraceatcmd
+ \let\} = \rbraceatcmd
+ %
+ % Do the redefinitions.
+ \commondummies
+ \otherbackslash
+}
+
+% Called from \indexdummies and \atdummies.
+%
+\def\commondummies{%
+ %
+ % \definedummyword defines \#1 as \string\#1\space, thus effectively
+ % preventing its expansion. This is used only for control% words,
+ % not control letters, because the \space would be incorrect for
+ % control characters, but is needed to separate the control word
+ % from whatever follows.
+ %
+ % For control letters, we have \definedummyletter, which omits the
+ % space.
+ %
+ % These can be used both for control words that take an argument and
+ % those that do not. If it is followed by {arg} in the input, then
+ % that will dutifully get written to the index (or wherever).
+ %
+ \def\definedummyword ##1{\def##1{\string##1\space}}%
+ \def\definedummyletter##1{\def##1{\string##1}}%
+ \let\definedummyaccent\definedummyletter
+ %
+ \commondummiesnofonts
+ %
+ \definedummyletter\_%
+ %
+ % Non-English letters.
+ \definedummyword\AA
+ \definedummyword\AE
+ \definedummyword\L
+ \definedummyword\OE
+ \definedummyword\O
+ \definedummyword\aa
+ \definedummyword\ae
+ \definedummyword\l
+ \definedummyword\oe
+ \definedummyword\o
+ \definedummyword\ss
+ \definedummyword\exclamdown
+ \definedummyword\questiondown
+ \definedummyword\ordf
+ \definedummyword\ordm
+ %
+ % Although these internal commands shouldn't show up, sometimes they do.
+ \definedummyword\bf
+ \definedummyword\gtr
+ \definedummyword\hat
+ \definedummyword\less
+ \definedummyword\sf
+ \definedummyword\sl
+ \definedummyword\tclose
+ \definedummyword\tt
+ %
+ \definedummyword\LaTeX
+ \definedummyword\TeX
+ %
+ % Assorted special characters.
+ \definedummyword\bullet
+ \definedummyword\comma
+ \definedummyword\copyright
+ \definedummyword\registeredsymbol
+ \definedummyword\dots
+ \definedummyword\enddots
+ \definedummyword\equiv
+ \definedummyword\error
+ \definedummyword\euro
+ \definedummyword\expansion
+ \definedummyword\minus
+ \definedummyword\pounds
+ \definedummyword\point
+ \definedummyword\print
+ \definedummyword\result
+ \definedummyword\textdegree
+ %
+ % We want to disable all macros so that they are not expanded by \write.
+ \macrolist
+ %
+ \normalturnoffactive
+ %
+ % Handle some cases of @value -- where it does not contain any
+ % (non-fully-expandable) commands.
+ \makevalueexpandable
+}
+
+% \commondummiesnofonts: common to \commondummies and \indexnofonts.
+%
+\def\commondummiesnofonts{%
+ % Control letters and accents.
+ \definedummyletter\!%
+ \definedummyaccent\"%
+ \definedummyaccent\'%
+ \definedummyletter\*%
+ \definedummyaccent\,%
+ \definedummyletter\.%
+ \definedummyletter\/%
+ \definedummyletter\:%
+ \definedummyaccent\=%
+ \definedummyletter\?%
+ \definedummyaccent\^%
+ \definedummyaccent\`%
+ \definedummyaccent\~%
+ \definedummyword\u
+ \definedummyword\v
+ \definedummyword\H
+ \definedummyword\dotaccent
+ \definedummyword\ringaccent
+ \definedummyword\tieaccent
+ \definedummyword\ubaraccent
+ \definedummyword\udotaccent
+ \definedummyword\dotless
+ %
+ % Texinfo font commands.
+ \definedummyword\b
+ \definedummyword\i
+ \definedummyword\r
+ \definedummyword\sc
+ \definedummyword\t
+ %
+ % Commands that take arguments.
+ \definedummyword\acronym
+ \definedummyword\cite
+ \definedummyword\code
+ \definedummyword\command
+ \definedummyword\dfn
+ \definedummyword\emph
+ \definedummyword\env
+ \definedummyword\file
+ \definedummyword\kbd
+ \definedummyword\key
+ \definedummyword\math
+ \definedummyword\option
+ \definedummyword\pxref
+ \definedummyword\ref
+ \definedummyword\samp
+ \definedummyword\strong
+ \definedummyword\tie
+ \definedummyword\uref
+ \definedummyword\url
+ \definedummyword\var
+ \definedummyword\verb
+ \definedummyword\w
+ \definedummyword\xref
+}
+
+% \indexnofonts is used when outputting the strings to sort the index
+% by, and when constructing control sequence names. It eliminates all
+% control sequences and just writes whatever the best ASCII sort string
+% would be for a given command (usually its argument).
+%
+\def\indexnofonts{%
+ % Accent commands should become @asis.
+ \def\definedummyaccent##1{\let##1\asis}%
+ % We can just ignore other control letters.
+ \def\definedummyletter##1{\let##1\empty}%
+ % Hopefully, all control words can become @asis.
+ \let\definedummyword\definedummyaccent
+ %
+ \commondummiesnofonts
+ %
+ % Don't no-op \tt, since it isn't a user-level command
+ % and is used in the definitions of the active chars like <, >, |, etc.
+ % Likewise with the other plain tex font commands.
+ %\let\tt=\asis
+ %
+ \def\ { }%
+ \def\@{@}%
+ % how to handle braces?
+ \def\_{\normalunderscore}%
+ %
+ % Non-English letters.
+ \def\AA{AA}%
+ \def\AE{AE}%
+ \def\L{L}%
+ \def\OE{OE}%
+ \def\O{O}%
+ \def\aa{aa}%
+ \def\ae{ae}%
+ \def\l{l}%
+ \def\oe{oe}%
+ \def\o{o}%
+ \def\ss{ss}%
+ \def\exclamdown{!}%
+ \def\questiondown{?}%
+ \def\ordf{a}%
+ \def\ordm{o}%
+ %
+ \def\LaTeX{LaTeX}%
+ \def\TeX{TeX}%
+ %
+ % Assorted special characters.
+ % (The following {} will end up in the sort string, but that's ok.)
+ \def\bullet{bullet}%
+ \def\comma{,}%
+ \def\copyright{copyright}%
+ \def\registeredsymbol{R}%
+ \def\dots{...}%
+ \def\enddots{...}%
+ \def\equiv{==}%
+ \def\error{error}%
+ \def\euro{euro}%
+ \def\expansion{==>}%
+ \def\minus{-}%
+ \def\pounds{pounds}%
+ \def\point{.}%
+ \def\print{-|}%
+ \def\result{=>}%
+ \def\textdegree{degrees}%
+ %
+ % We need to get rid of all macros, leaving only the arguments (if present).
+ % Of course this is not nearly correct, but it is the best we can do for now.
+ % makeinfo does not expand macros in the argument to @deffn, which ends up
+ % writing an index entry, and texindex isn't prepared for an index sort entry
+ % that starts with \.
+ %
+ % Since macro invocations are followed by braces, we can just redefine them
+ % to take a single TeX argument. The case of a macro invocation that
+ % goes to end-of-line is not handled.
+ %
+ \macrolist
+}
+
+\let\indexbackslash=0 %overridden during \printindex.
+\let\SETmarginindex=\relax % put index entries in margin (undocumented)?
+
+% Most index entries go through here, but \dosubind is the general case.
+% #1 is the index name, #2 is the entry text.
+\def\doind#1#2{\dosubind{#1}{#2}{}}
+
+% Workhorse for all \fooindexes.
+% #1 is name of index, #2 is stuff to put there, #3 is subentry --
+% empty if called from \doind, as we usually are (the main exception
+% is with most defuns, which call us directly).
+%
+\def\dosubind#1#2#3{%
+ \iflinks
+ {%
+ % Store the main index entry text (including the third arg).
+ \toks0 = {#2}%
+ % If third arg is present, precede it with a space.
+ \def\thirdarg{#3}%
+ \ifx\thirdarg\empty \else
+ \toks0 = \expandafter{\the\toks0 \space #3}%
+ \fi
+ %
+ \edef\writeto{\csname#1indfile\endcsname}%
+ %
+ \safewhatsit\dosubindwrite
+ }%
+ \fi
+}
+
+% Write the entry in \toks0 to the index file:
+%
+\def\dosubindwrite{%
+ % Put the index entry in the margin if desired.
+ \ifx\SETmarginindex\relax\else
+ \insert\margin{\hbox{\vrule height8pt depth3pt width0pt \the\toks0}}%
+ \fi
+ %
+ % Remember, we are within a group.
+ \indexdummies % Must do this here, since \bf, etc expand at this stage
+ \def\backslashcurfont{\indexbackslash}% \indexbackslash isn't defined now
+ % so it will be output as is; and it will print as backslash.
+ %
+ % Process the index entry with all font commands turned off, to
+ % get the string to sort by.
+ {\indexnofonts
+ \edef\temp{\the\toks0}% need full expansion
+ \xdef\indexsorttmp{\temp}%
+ }%
+ %
+ % Set up the complete index entry, with both the sort key and
+ % the original text, including any font commands. We write
+ % three arguments to \entry to the .?? file (four in the
+ % subentry case), texindex reduces to two when writing the .??s
+ % sorted result.
+ \edef\temp{%
+ \write\writeto{%
+ \string\entry{\indexsorttmp}{\noexpand\folio}{\the\toks0}}%
+ }%
+ \temp
+}
+
+% Take care of unwanted page breaks/skips around a whatsit:
+%
+% If a skip is the last thing on the list now, preserve it
+% by backing up by \lastskip, doing the \write, then inserting
+% the skip again. Otherwise, the whatsit generated by the
+% \write or \pdfdest will make \lastskip zero. The result is that
+% sequences like this:
+% @end defun
+% @tindex whatever
+% @defun ...
+% will have extra space inserted, because the \medbreak in the
+% start of the @defun won't see the skip inserted by the @end of
+% the previous defun.
+%
+% But don't do any of this if we're not in vertical mode. We
+% don't want to do a \vskip and prematurely end a paragraph.
+%
+% Avoid page breaks due to these extra skips, too.
+%
+% But wait, there is a catch there:
+% We'll have to check whether \lastskip is zero skip. \ifdim is not
+% sufficient for this purpose, as it ignores stretch and shrink parts
+% of the skip. The only way seems to be to check the textual
+% representation of the skip.
+%
+% The following is almost like \def\zeroskipmacro{0.0pt} except that
+% the ``p'' and ``t'' characters have catcode \other, not 11 (letter).
+%
+\edef\zeroskipmacro{\expandafter\the\csname z@skip\endcsname}
+%
+\newskip\whatsitskip
+\newcount\whatsitpenalty
+%
+% ..., ready, GO:
+%
+\def\safewhatsit#1{%
+\ifhmode
+ #1%
+\else
+ % \lastskip and \lastpenalty cannot both be nonzero simultaneously.
+ \whatsitskip = \lastskip
+ \edef\lastskipmacro{\the\lastskip}%
+ \whatsitpenalty = \lastpenalty
+ %
+ % If \lastskip is nonzero, that means the last item was a
+ % skip. And since a skip is discardable, that means this
+ % -\skip0 glue we're inserting is preceded by a
+ % non-discardable item, therefore it is not a potential
+ % breakpoint, therefore no \nobreak needed.
+ \ifx\lastskipmacro\zeroskipmacro
+ \else
+ \vskip-\whatsitskip
+ \fi
+ %
+ #1%
+ %
+ \ifx\lastskipmacro\zeroskipmacro
+ % If \lastskip was zero, perhaps the last item was a penalty, and
+ % perhaps it was >=10000, e.g., a \nobreak. In that case, we want
+ % to re-insert the same penalty (values >10000 are used for various
+ % signals); since we just inserted a non-discardable item, any
+ % following glue (such as a \parskip) would be a breakpoint. For example:
+ %
+ % @deffn deffn-whatever
+ % @vindex index-whatever
+ % Description.
+ % would allow a break between the index-whatever whatsit
+ % and the "Description." paragraph.
+ \ifnum\whatsitpenalty>9999 \penalty\whatsitpenalty \fi
+ \else
+ % On the other hand, if we had a nonzero \lastskip,
+ % this make-up glue would be preceded by a non-discardable item
+ % (the whatsit from the \write), so we must insert a \nobreak.
+ \nobreak\vskip\whatsitskip
+ \fi
+\fi
+}
+
+% The index entry written in the file actually looks like
+% \entry {sortstring}{page}{topic}
+% or
+% \entry {sortstring}{page}{topic}{subtopic}
+% The texindex program reads in these files and writes files
+% containing these kinds of lines:
+% \initial {c}
+% before the first topic whose initial is c
+% \entry {topic}{pagelist}
+% for a topic that is used without subtopics
+% \primary {topic}
+% for the beginning of a topic that is used with subtopics
+% \secondary {subtopic}{pagelist}
+% for each subtopic.
+
+% Define the user-accessible indexing commands
+% @findex, @vindex, @kindex, @cindex.
+
+\def\findex {\fnindex}
+\def\kindex {\kyindex}
+\def\cindex {\cpindex}
+\def\vindex {\vrindex}
+\def\tindex {\tpindex}
+\def\pindex {\pgindex}
+
+\def\cindexsub {\begingroup\obeylines\cindexsub}
+{\obeylines %
+\gdef\cindexsub "#1" #2^^M{\endgroup %
+\dosubind{cp}{#2}{#1}}}
+
+% Define the macros used in formatting output of the sorted index material.
+
+% @printindex causes a particular index (the ??s file) to get printed.
+% It does not print any chapter heading (usually an @unnumbered).
+%
+\parseargdef\printindex{\begingroup
+ \dobreak \chapheadingskip{10000}%
+ %
+ \smallfonts \rm
+ \tolerance = 9500
+ \plainfrenchspacing
+ \everypar = {}% don't want the \kern\-parindent from indentation suppression.
+ %
+ % See if the index file exists and is nonempty.
+ % Change catcode of @ here so that if the index file contains
+ % \initial {@}
+ % as its first line, TeX doesn't complain about mismatched braces
+ % (because it thinks @} is a control sequence).
+ \catcode`\@ = 11
+ \openin 1 \jobname.#1s
+ \ifeof 1
+ % \enddoublecolumns gets confused if there is no text in the index,
+ % and it loses the chapter title and the aux file entries for the
+ % index. The easiest way to prevent this problem is to make sure
+ % there is some text.
+ \putwordIndexNonexistent
+ \else
+ %
+ % If the index file exists but is empty, then \openin leaves \ifeof
+ % false. We have to make TeX try to read something from the file, so
+ % it can discover if there is anything in it.
+ \read 1 to \temp
+ \ifeof 1
+ \putwordIndexIsEmpty
+ \else
+ % Index files are almost Texinfo source, but we use \ as the escape
+ % character. It would be better to use @, but that's too big a change
+ % to make right now.
+ \def\indexbackslash{\backslashcurfont}%
+ \catcode`\\ = 0
+ \escapechar = `\\
+ \begindoublecolumns
+ \input \jobname.#1s
+ \enddoublecolumns
+ \fi
+ \fi
+ \closein 1
+\endgroup}
+
+% These macros are used by the sorted index file itself.
+% Change them to control the appearance of the index.
+
+\def\initial#1{{%
+ % Some minor font changes for the special characters.
+ \let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt
+ %
+ % Remove any glue we may have, we'll be inserting our own.
+ \removelastskip
+ %
+ % We like breaks before the index initials, so insert a bonus.
+ \nobreak
+ \vskip 0pt plus 3\baselineskip
+ \penalty 0
+ \vskip 0pt plus -3\baselineskip
+ %
+ % Typeset the initial. Making this add up to a whole number of
+ % baselineskips increases the chance of the dots lining up from column
+ % to column. It still won't often be perfect, because of the stretch
+ % we need before each entry, but it's better.
+ %
+ % No shrink because it confuses \balancecolumns.
+ \vskip 1.67\baselineskip plus .5\baselineskip
+ \leftline{\secbf #1}%
+ % Do our best not to break after the initial.
+ \nobreak
+ \vskip .33\baselineskip plus .1\baselineskip
+}}
+
+% \entry typesets a paragraph consisting of the text (#1), dot leaders, and
+% then page number (#2) flushed to the right margin. It is used for index
+% and table of contents entries. The paragraph is indented by \leftskip.
+%
+% A straightforward implementation would start like this:
+% \def\entry#1#2{...
+% But this frozes the catcodes in the argument, and can cause problems to
+% @code, which sets - active. This problem was fixed by a kludge---
+% ``-'' was active throughout whole index, but this isn't really right.
+%
+% The right solution is to prevent \entry from swallowing the whole text.
+% --kasal, 21nov03
+\def\entry{%
+ \begingroup
+ %
+ % Start a new paragraph if necessary, so our assignments below can't
+ % affect previous text.
+ \par
+ %
+ % Do not fill out the last line with white space.
+ \parfillskip = 0in
+ %
+ % No extra space above this paragraph.
+ \parskip = 0in
+ %
+ % Do not prefer a separate line ending with a hyphen to fewer lines.
+ \finalhyphendemerits = 0
+ %
+ % \hangindent is only relevant when the entry text and page number
+ % don't both fit on one line. In that case, bob suggests starting the
+ % dots pretty far over on the line. Unfortunately, a large
+ % indentation looks wrong when the entry text itself is broken across
+ % lines. So we use a small indentation and put up with long leaders.
+ %
+ % \hangafter is reset to 1 (which is the value we want) at the start
+ % of each paragraph, so we need not do anything with that.
+ \hangindent = 2em
+ %
+ % When the entry text needs to be broken, just fill out the first line
+ % with blank space.
+ \rightskip = 0pt plus1fil
+ %
+ % A bit of stretch before each entry for the benefit of balancing
+ % columns.
+ \vskip 0pt plus1pt
+ %
+ % Swallow the left brace of the text (first parameter):
+ \afterassignment\doentry
+ \let\temp =
+}
+\def\doentry{%
+ \bgroup % Instead of the swallowed brace.
+ \noindent
+ \aftergroup\finishentry
+ % And now comes the text of the entry.
+}
+\def\finishentry#1{%
+ % #1 is the page number.
+ %
+ % The following is kludged to not output a line of dots in the index if
+ % there are no page numbers. The next person who breaks this will be
+ % cursed by a Unix daemon.
+ \setbox\boxA = \hbox{#1}%
+ \ifdim\wd\boxA = 0pt
+ \ %
+ \else
+ %
+ % If we must, put the page number on a line of its own, and fill out
+ % this line with blank space. (The \hfil is overwhelmed with the
+ % fill leaders glue in \indexdotfill if the page number does fit.)
+ \hfil\penalty50
+ \null\nobreak\indexdotfill % Have leaders before the page number.
+ %
+ % The `\ ' here is removed by the implicit \unskip that TeX does as
+ % part of (the primitive) \par. Without it, a spurious underfull
+ % \hbox ensues.
+ \ifpdf
+ \pdfgettoks#1.%
+ \ \the\toksA
+ \else
+ \ #1%
+ \fi
+ \fi
+ \par
+ \endgroup
+}
+
+% Like plain.tex's \dotfill, except uses up at least 1 em.
+\def\indexdotfill{\cleaders
+ \hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1fill}
+
+\def\primary #1{\line{#1\hfil}}
+
+\newskip\secondaryindent \secondaryindent=0.5cm
+\def\secondary#1#2{{%
+ \parfillskip=0in
+ \parskip=0in
+ \hangindent=1in
+ \hangafter=1
+ \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill
+ \ifpdf
+ \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph.
+ \else
+ #2
+ \fi
+ \par
+}}
+
+% Define two-column mode, which we use to typeset indexes.
+% Adapted from the TeXbook, page 416, which is to say,
+% the manmac.tex format used to print the TeXbook itself.
+\catcode`\@=11
+
+\newbox\partialpage
+\newdimen\doublecolumnhsize
+
+\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns
+ % Grab any single-column material above us.
+ \output = {%
+ %
+ % Here is a possibility not foreseen in manmac: if we accumulate a
+ % whole lot of material, we might end up calling this \output
+ % routine twice in a row (see the doublecol-lose test, which is
+ % essentially a couple of indexes with @setchapternewpage off). In
+ % that case we just ship out what is in \partialpage with the normal
+ % output routine. Generally, \partialpage will be empty when this
+ % runs and this will be a no-op. See the indexspread.tex test case.
+ \ifvoid\partialpage \else
+ \onepageout{\pagecontents\partialpage}%
+ \fi
+ %
+ \global\setbox\partialpage = \vbox{%
+ % Unvbox the main output page.
+ \unvbox\PAGE
+ \kern-\topskip \kern\baselineskip
+ }%
+ }%
+ \eject % run that output routine to set \partialpage
+ %
+ % Use the double-column output routine for subsequent pages.
+ \output = {\doublecolumnout}%
+ %
+ % Change the page size parameters. We could do this once outside this
+ % routine, in each of @smallbook, @afourpaper, and the default 8.5x11
+ % format, but then we repeat the same computation. Repeating a couple
+ % of assignments once per index is clearly meaningless for the
+ % execution time, so we may as well do it in one place.
+ %
+ % First we halve the line length, less a little for the gutter between
+ % the columns. We compute the gutter based on the line length, so it
+ % changes automatically with the paper format. The magic constant
+ % below is chosen so that the gutter has the same value (well, +-<1pt)
+ % as it did when we hard-coded it.
+ %
+ % We put the result in a separate register, \doublecolumhsize, so we
+ % can restore it in \pagesofar, after \hsize itself has (potentially)
+ % been clobbered.
+ %
+ \doublecolumnhsize = \hsize
+ \advance\doublecolumnhsize by -.04154\hsize
+ \divide\doublecolumnhsize by 2
+ \hsize = \doublecolumnhsize
+ %
+ % Double the \vsize as well. (We don't need a separate register here,
+ % since nobody clobbers \vsize.)
+ \vsize = 2\vsize
+}
+
+% The double-column output routine for all double-column pages except
+% the last.
+%
+\def\doublecolumnout{%
+ \splittopskip=\topskip \splitmaxdepth=\maxdepth
+ % Get the available space for the double columns -- the normal
+ % (undoubled) page height minus any material left over from the
+ % previous page.
+ \dimen@ = \vsize
+ \divide\dimen@ by 2
+ \advance\dimen@ by -\ht\partialpage
+ %
+ % box0 will be the left-hand column, box2 the right.
+ \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@
+ \onepageout\pagesofar
+ \unvbox255
+ \penalty\outputpenalty
+}
+%
+% Re-output the contents of the output page -- any previous material,
+% followed by the two boxes we just split, in box0 and box2.
+\def\pagesofar{%
+ \unvbox\partialpage
+ %
+ \hsize = \doublecolumnhsize
+ \wd0=\hsize \wd2=\hsize
+ \hbox to\pagewidth{\box0\hfil\box2}%
+}
+%
+% All done with double columns.
+\def\enddoublecolumns{%
+ % The following penalty ensures that the page builder is exercised
+ % _before_ we change the output routine. This is necessary in the
+ % following situation:
+ %
+ % The last section of the index consists only of a single entry.
+ % Before this section, \pagetotal is less than \pagegoal, so no
+ % break occurs before the last section starts. However, the last
+ % section, consisting of \initial and the single \entry, does not
+ % fit on the page and has to be broken off. Without the following
+ % penalty the page builder will not be exercised until \eject
+ % below, and by that time we'll already have changed the output
+ % routine to the \balancecolumns version, so the next-to-last
+ % double-column page will be processed with \balancecolumns, which
+ % is wrong: The two columns will go to the main vertical list, with
+ % the broken-off section in the recent contributions. As soon as
+ % the output routine finishes, TeX starts reconsidering the page
+ % break. The two columns and the broken-off section both fit on the
+ % page, because the two columns now take up only half of the page
+ % goal. When TeX sees \eject from below which follows the final
+ % section, it invokes the new output routine that we've set after
+ % \balancecolumns below; \onepageout will try to fit the two columns
+ % and the final section into the vbox of \pageheight (see
+ % \pagebody), causing an overfull box.
+ %
+ % Note that glue won't work here, because glue does not exercise the
+ % page builder, unlike penalties (see The TeXbook, pp. 280-281).
+ \penalty0
+ %
+ \output = {%
+ % Split the last of the double-column material. Leave it on the
+ % current page, no automatic page break.
+ \balancecolumns
+ %
+ % If we end up splitting too much material for the current page,
+ % though, there will be another page break right after this \output
+ % invocation ends. Having called \balancecolumns once, we do not
+ % want to call it again. Therefore, reset \output to its normal
+ % definition right away. (We hope \balancecolumns will never be
+ % called on to balance too much material, but if it is, this makes
+ % the output somewhat more palatable.)
+ \global\output = {\onepageout{\pagecontents\PAGE}}%
+ }%
+ \eject
+ \endgroup % started in \begindoublecolumns
+ %
+ % \pagegoal was set to the doubled \vsize above, since we restarted
+ % the current page. We're now back to normal single-column
+ % typesetting, so reset \pagegoal to the normal \vsize (after the
+ % \endgroup where \vsize got restored).
+ \pagegoal = \vsize
+}
+%
+% Called at the end of the double column material.
+\def\balancecolumns{%
+ \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120.
+ \dimen@ = \ht0
+ \advance\dimen@ by \topskip
+ \advance\dimen@ by-\baselineskip
+ \divide\dimen@ by 2 % target to split to
+ %debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}%
+ \splittopskip = \topskip
+ % Loop until we get a decent breakpoint.
+ {%
+ \vbadness = 10000
+ \loop
+ \global\setbox3 = \copy0
+ \global\setbox1 = \vsplit3 to \dimen@
+ \ifdim\ht3>\dimen@
+ \global\advance\dimen@ by 1pt
+ \repeat
+ }%
+ %debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}%
+ \setbox0=\vbox to\dimen@{\unvbox1}%
+ \setbox2=\vbox to\dimen@{\unvbox3}%
+ %
+ \pagesofar
+}
+\catcode`\@ = \other
+
+
+\message{sectioning,}
+% Chapters, sections, etc.
+
+% \unnumberedno is an oxymoron, of course. But we count the unnumbered
+% sections so that we can refer to them unambiguously in the pdf
+% outlines by their "section number". We avoid collisions with chapter
+% numbers by starting them at 10000. (If a document ever has 10000
+% chapters, we're in trouble anyway, I'm sure.)
+\newcount\unnumberedno \unnumberedno = 10000
+\newcount\chapno
+\newcount\secno \secno=0
+\newcount\subsecno \subsecno=0
+\newcount\subsubsecno \subsubsecno=0
+
+% This counter is funny since it counts through charcodes of letters A, B, ...
+\newcount\appendixno \appendixno = `\@
+%
+% \def\appendixletter{\char\the\appendixno}
+% We do the following ugly conditional instead of the above simple
+% construct for the sake of pdftex, which needs the actual
+% letter in the expansion, not just typeset.
+%
+\def\appendixletter{%
+ \ifnum\appendixno=`A A%
+ \else\ifnum\appendixno=`B B%
+ \else\ifnum\appendixno=`C C%
+ \else\ifnum\appendixno=`D D%
+ \else\ifnum\appendixno=`E E%
+ \else\ifnum\appendixno=`F F%
+ \else\ifnum\appendixno=`G G%
+ \else\ifnum\appendixno=`H H%
+ \else\ifnum\appendixno=`I I%
+ \else\ifnum\appendixno=`J J%
+ \else\ifnum\appendixno=`K K%
+ \else\ifnum\appendixno=`L L%
+ \else\ifnum\appendixno=`M M%
+ \else\ifnum\appendixno=`N N%
+ \else\ifnum\appendixno=`O O%
+ \else\ifnum\appendixno=`P P%
+ \else\ifnum\appendixno=`Q Q%
+ \else\ifnum\appendixno=`R R%
+ \else\ifnum\appendixno=`S S%
+ \else\ifnum\appendixno=`T T%
+ \else\ifnum\appendixno=`U U%
+ \else\ifnum\appendixno=`V V%
+ \else\ifnum\appendixno=`W W%
+ \else\ifnum\appendixno=`X X%
+ \else\ifnum\appendixno=`Y Y%
+ \else\ifnum\appendixno=`Z Z%
+ % The \the is necessary, despite appearances, because \appendixletter is
+ % expanded while writing the .toc file. \char\appendixno is not
+ % expandable, thus it is written literally, thus all appendixes come out
+ % with the same letter (or @) in the toc without it.
+ \else\char\the\appendixno
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi}
+
+% Each @chapter defines this as the name of the chapter.
+% page headings and footings can use it. @section does likewise.
+% However, they are not reliable, because we don't use marks.
+\def\thischapter{}
+\def\thissection{}
+
+\newcount\absseclevel % used to calculate proper heading level
+\newcount\secbase\secbase=0 % @raisesections/@lowersections modify this count
+
+% @raisesections: treat @section as chapter, @subsection as section, etc.
+\def\raisesections{\global\advance\secbase by -1}
+\let\up=\raisesections % original BFox name
+
+% @lowersections: treat @chapter as section, @section as subsection, etc.
+\def\lowersections{\global\advance\secbase by 1}
+\let\down=\lowersections % original BFox name
+
+% we only have subsub.
+\chardef\maxseclevel = 3
+%
+% A numbered section within an unnumbered changes to unnumbered too.
+% To achive this, remember the "biggest" unnum. sec. we are currently in:
+\chardef\unmlevel = \maxseclevel
+%
+% Trace whether the current chapter is an appendix or not:
+% \chapheadtype is "N" or "A", unnumbered chapters are ignored.
+\def\chapheadtype{N}
+
+% Choose a heading macro
+% #1 is heading type
+% #2 is heading level
+% #3 is text for heading
+\def\genhead#1#2#3{%
+ % Compute the abs. sec. level:
+ \absseclevel=#2
+ \advance\absseclevel by \secbase
+ % Make sure \absseclevel doesn't fall outside the range:
+ \ifnum \absseclevel < 0
+ \absseclevel = 0
+ \else
+ \ifnum \absseclevel > 3
+ \absseclevel = 3
+ \fi
+ \fi
+ % The heading type:
+ \def\headtype{#1}%
+ \if \headtype U%
+ \ifnum \absseclevel < \unmlevel
+ \chardef\unmlevel = \absseclevel
+ \fi
+ \else
+ % Check for appendix sections:
+ \ifnum \absseclevel = 0
+ \edef\chapheadtype{\headtype}%
+ \else
+ \if \headtype A\if \chapheadtype N%
+ \errmessage{@appendix... within a non-appendix chapter}%
+ \fi\fi
+ \fi
+ % Check for numbered within unnumbered:
+ \ifnum \absseclevel > \unmlevel
+ \def\headtype{U}%
+ \else
+ \chardef\unmlevel = 3
+ \fi
+ \fi
+ % Now print the heading:
+ \if \headtype U%
+ \ifcase\absseclevel
+ \unnumberedzzz{#3}%
+ \or \unnumberedseczzz{#3}%
+ \or \unnumberedsubseczzz{#3}%
+ \or \unnumberedsubsubseczzz{#3}%
+ \fi
+ \else
+ \if \headtype A%
+ \ifcase\absseclevel
+ \appendixzzz{#3}%
+ \or \appendixsectionzzz{#3}%
+ \or \appendixsubseczzz{#3}%
+ \or \appendixsubsubseczzz{#3}%
+ \fi
+ \else
+ \ifcase\absseclevel
+ \chapterzzz{#3}%
+ \or \seczzz{#3}%
+ \or \numberedsubseczzz{#3}%
+ \or \numberedsubsubseczzz{#3}%
+ \fi
+ \fi
+ \fi
+ \suppressfirstparagraphindent
+}
+
+% an interface:
+\def\numhead{\genhead N}
+\def\apphead{\genhead A}
+\def\unnmhead{\genhead U}
+
+% @chapter, @appendix, @unnumbered. Increment top-level counter, reset
+% all lower-level sectioning counters to zero.
+%
+% Also set \chaplevelprefix, which we prepend to @float sequence numbers
+% (e.g., figures), q.v. By default (before any chapter), that is empty.
+\let\chaplevelprefix = \empty
+%
+\outer\parseargdef\chapter{\numhead0{#1}} % normally numhead0 calls chapterzzz
+\def\chapterzzz#1{%
+ % section resetting is \global in case the chapter is in a group, such
+ % as an @include file.
+ \global\secno=0 \global\subsecno=0 \global\subsubsecno=0
+ \global\advance\chapno by 1
+ %
+ % Used for \float.
+ \gdef\chaplevelprefix{\the\chapno.}%
+ \resetallfloatnos
+ %
+ \message{\putwordChapter\space \the\chapno}%
+ %
+ % Write the actual heading.
+ \chapmacro{#1}{Ynumbered}{\the\chapno}%
+ %
+ % So @section and the like are numbered underneath this chapter.
+ \global\let\section = \numberedsec
+ \global\let\subsection = \numberedsubsec
+ \global\let\subsubsection = \numberedsubsubsec
+}
+
+\outer\parseargdef\appendix{\apphead0{#1}} % normally apphead0 calls appendixzzz
+\def\appendixzzz#1{%
+ \global\secno=0 \global\subsecno=0 \global\subsubsecno=0
+ \global\advance\appendixno by 1
+ \gdef\chaplevelprefix{\appendixletter.}%
+ \resetallfloatnos
+ %
+ \def\appendixnum{\putwordAppendix\space \appendixletter}%
+ \message{\appendixnum}%
+ %
+ \chapmacro{#1}{Yappendix}{\appendixletter}%
+ %
+ \global\let\section = \appendixsec
+ \global\let\subsection = \appendixsubsec
+ \global\let\subsubsection = \appendixsubsubsec
+}
+
+\outer\parseargdef\unnumbered{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz
+\def\unnumberedzzz#1{%
+ \global\secno=0 \global\subsecno=0 \global\subsubsecno=0
+ \global\advance\unnumberedno by 1
+ %
+ % Since an unnumbered has no number, no prefix for figures.
+ \global\let\chaplevelprefix = \empty
+ \resetallfloatnos
+ %
+ % This used to be simply \message{#1}, but TeX fully expands the
+ % argument to \message. Therefore, if #1 contained @-commands, TeX
+ % expanded them. For example, in `@unnumbered The @cite{Book}', TeX
+ % expanded @cite (which turns out to cause errors because \cite is meant
+ % to be executed, not expanded).
+ %
+ % Anyway, we don't want the fully-expanded definition of @cite to appear
+ % as a result of the \message, we just want `@cite' itself. We use
+ % \the<toks register> to achieve this: TeX expands \the<toks> only once,
+ % simply yielding the contents of <toks register>. (We also do this for
+ % the toc entries.)
+ \toks0 = {#1}%
+ \message{(\the\toks0)}%
+ %
+ \chapmacro{#1}{Ynothing}{\the\unnumberedno}%
+ %
+ \global\let\section = \unnumberedsec
+ \global\let\subsection = \unnumberedsubsec
+ \global\let\subsubsection = \unnumberedsubsubsec
+}
+
+% @centerchap is like @unnumbered, but the heading is centered.
+\outer\parseargdef\centerchap{%
+ % Well, we could do the following in a group, but that would break
+ % an assumption that \chapmacro is called at the outermost level.
+ % Thus we are safer this way: --kasal, 24feb04
+ \let\centerparametersmaybe = \centerparameters
+ \unnmhead0{#1}%
+ \let\centerparametersmaybe = \relax
+}
+
+% @top is like @unnumbered.
+\let\top\unnumbered
+
+% Sections.
+\outer\parseargdef\numberedsec{\numhead1{#1}} % normally calls seczzz
+\def\seczzz#1{%
+ \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1
+ \sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}%
+}
+
+\outer\parseargdef\appendixsection{\apphead1{#1}} % normally calls appendixsectionzzz
+\def\appendixsectionzzz#1{%
+ \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1
+ \sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}%
+}
+\let\appendixsec\appendixsection
+
+\outer\parseargdef\unnumberedsec{\unnmhead1{#1}} % normally calls unnumberedseczzz
+\def\unnumberedseczzz#1{%
+ \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1
+ \sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}%
+}
+
+% Subsections.
+\outer\parseargdef\numberedsubsec{\numhead2{#1}} % normally calls numberedsubseczzz
+\def\numberedsubseczzz#1{%
+ \global\subsubsecno=0 \global\advance\subsecno by 1
+ \sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}%
+}
+
+\outer\parseargdef\appendixsubsec{\apphead2{#1}} % normally calls appendixsubseczzz
+\def\appendixsubseczzz#1{%
+ \global\subsubsecno=0 \global\advance\subsecno by 1
+ \sectionheading{#1}{subsec}{Yappendix}%
+ {\appendixletter.\the\secno.\the\subsecno}%
+}
+
+\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}} %normally calls unnumberedsubseczzz
+\def\unnumberedsubseczzz#1{%
+ \global\subsubsecno=0 \global\advance\subsecno by 1
+ \sectionheading{#1}{subsec}{Ynothing}%
+ {\the\unnumberedno.\the\secno.\the\subsecno}%
+}
+
+% Subsubsections.
+\outer\parseargdef\numberedsubsubsec{\numhead3{#1}} % normally numberedsubsubseczzz
+\def\numberedsubsubseczzz#1{%
+ \global\advance\subsubsecno by 1
+ \sectionheading{#1}{subsubsec}{Ynumbered}%
+ {\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno}%
+}
+
+\outer\parseargdef\appendixsubsubsec{\apphead3{#1}} % normally appendixsubsubseczzz
+\def\appendixsubsubseczzz#1{%
+ \global\advance\subsubsecno by 1
+ \sectionheading{#1}{subsubsec}{Yappendix}%
+ {\appendixletter.\the\secno.\the\subsecno.\the\subsubsecno}%
+}
+
+\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}} %normally unnumberedsubsubseczzz
+\def\unnumberedsubsubseczzz#1{%
+ \global\advance\subsubsecno by 1
+ \sectionheading{#1}{subsubsec}{Ynothing}%
+ {\the\unnumberedno.\the\secno.\the\subsecno.\the\subsubsecno}%
+}
+
+% These macros control what the section commands do, according
+% to what kind of chapter we are in (ordinary, appendix, or unnumbered).
+% Define them by default for a numbered chapter.
+\let\section = \numberedsec
+\let\subsection = \numberedsubsec
+\let\subsubsection = \numberedsubsubsec
+
+% Define @majorheading, @heading and @subheading
+
+% NOTE on use of \vbox for chapter headings, section headings, and such:
+% 1) We use \vbox rather than the earlier \line to permit
+% overlong headings to fold.
+% 2) \hyphenpenalty is set to 10000 because hyphenation in a
+% heading is obnoxious; this forbids it.
+% 3) Likewise, headings look best if no \parindent is used, and
+% if justification is not attempted. Hence \raggedright.
+
+
+\def\majorheading{%
+ {\advance\chapheadingskip by 10pt \chapbreak }%
+ \parsearg\chapheadingzzz
+}
+
+\def\chapheading{\chapbreak \parsearg\chapheadingzzz}
+\def\chapheadingzzz#1{%
+ {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
+ \parindent=0pt\raggedright
+ \rm #1\hfill}}%
+ \bigskip \par\penalty 200\relax
+ \suppressfirstparagraphindent
+}
+
+% @heading, @subheading, @subsubheading.
+\parseargdef\heading{\sectionheading{#1}{sec}{Yomitfromtoc}{}
+ \suppressfirstparagraphindent}
+\parseargdef\subheading{\sectionheading{#1}{subsec}{Yomitfromtoc}{}
+ \suppressfirstparagraphindent}
+\parseargdef\subsubheading{\sectionheading{#1}{subsubsec}{Yomitfromtoc}{}
+ \suppressfirstparagraphindent}
+
+% These macros generate a chapter, section, etc. heading only
+% (including whitespace, linebreaking, etc. around it),
+% given all the information in convenient, parsed form.
+
+%%% Args are the skip and penalty (usually negative)
+\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi}
+
+%%% Define plain chapter starts, and page on/off switching for it
+% Parameter controlling skip before chapter headings (if needed)
+
+\newskip\chapheadingskip
+
+\def\chapbreak{\dobreak \chapheadingskip {-4000}}
+\def\chappager{\par\vfill\supereject}
+\def\chapoddpage{\chappager \ifodd\pageno \else \hbox to 0pt{} \chappager\fi}
+
+\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname}
+
+\def\CHAPPAGoff{%
+\global\let\contentsalignmacro = \chappager
+\global\let\pchapsepmacro=\chapbreak
+\global\let\pagealignmacro=\chappager}
+
+\def\CHAPPAGon{%
+\global\let\contentsalignmacro = \chappager
+\global\let\pchapsepmacro=\chappager
+\global\let\pagealignmacro=\chappager
+\global\def\HEADINGSon{\HEADINGSsingle}}
+
+\def\CHAPPAGodd{%
+\global\let\contentsalignmacro = \chapoddpage
+\global\let\pchapsepmacro=\chapoddpage
+\global\let\pagealignmacro=\chapoddpage
+\global\def\HEADINGSon{\HEADINGSdouble}}
+
+\CHAPPAGon
+
+% Chapter opening.
+%
+% #1 is the text, #2 is the section type (Ynumbered, Ynothing,
+% Yappendix, Yomitfromtoc), #3 the chapter number.
+%
+% To test against our argument.
+\def\Ynothingkeyword{Ynothing}
+\def\Yomitfromtockeyword{Yomitfromtoc}
+\def\Yappendixkeyword{Yappendix}
+%
+\def\chapmacro#1#2#3{%
+ \pchapsepmacro
+ {%
+ \chapfonts \rm
+ %
+ % Have to define \thissection before calling \donoderef, because the
+ % xref code eventually uses it. On the other hand, it has to be called
+ % after \pchapsepmacro, or the headline will change too soon.
+ \gdef\thissection{#1}%
+ \gdef\thischaptername{#1}%
+ %
+ % Only insert the separating space if we have a chapter/appendix
+ % number, and don't print the unnumbered ``number''.
+ \def\temptype{#2}%
+ \ifx\temptype\Ynothingkeyword
+ \setbox0 = \hbox{}%
+ \def\toctype{unnchap}%
+ \gdef\thischapternum{}%
+ \gdef\thischapter{#1}%
+ \else\ifx\temptype\Yomitfromtockeyword
+ \setbox0 = \hbox{}% contents like unnumbered, but no toc entry
+ \def\toctype{omit}%
+ \gdef\thischapternum{}%
+ \gdef\thischapter{}%
+ \else\ifx\temptype\Yappendixkeyword
+ \setbox0 = \hbox{\putwordAppendix{} #3\enspace}%
+ \def\toctype{app}%
+ \xdef\thischapternum{\appendixletter}%
+ % We don't substitute the actual chapter name into \thischapter
+ % because we don't want its macros evaluated now. And we don't
+ % use \thissection because that changes with each section.
+ %
+ \xdef\thischapter{\putwordAppendix{} \appendixletter:
+ \noexpand\thischaptername}%
+ \else
+ \setbox0 = \hbox{#3\enspace}%
+ \def\toctype{numchap}%
+ \xdef\thischapternum{\the\chapno}%
+ \xdef\thischapter{\putwordChapter{} \the\chapno:
+ \noexpand\thischaptername}%
+ \fi\fi\fi
+ %
+ % Write the toc entry for this chapter. Must come before the
+ % \donoderef, because we include the current node name in the toc
+ % entry, and \donoderef resets it to empty.
+ \writetocentry{\toctype}{#1}{#3}%
+ %
+ % For pdftex, we have to write out the node definition (aka, make
+ % the pdfdest) after any page break, but before the actual text has
+ % been typeset. If the destination for the pdf outline is after the
+ % text, then jumping from the outline may wind up with the text not
+ % being visible, for instance under high magnification.
+ \donoderef{#2}%
+ %
+ % Typeset the actual heading.
+ \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright
+ \hangindent=\wd0 \centerparametersmaybe
+ \unhbox0 #1\par}%
+ }%
+ \nobreak\bigskip % no page break after a chapter title
+ \nobreak
+}
+
+% @centerchap -- centered and unnumbered.
+\let\centerparametersmaybe = \relax
+\def\centerparameters{%
+ \advance\rightskip by 3\rightskip
+ \leftskip = \rightskip
+ \parfillskip = 0pt
+}
+
+
+% I don't think this chapter style is supported any more, so I'm not
+% updating it with the new noderef stuff. We'll see. --karl, 11aug03.
+%
+\def\setchapterstyle #1 {\csname CHAPF#1\endcsname}
+%
+\def\unnchfopen #1{%
+\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
+ \parindent=0pt\raggedright
+ \rm #1\hfill}}\bigskip \par\nobreak
+}
+\def\chfopen #1#2{\chapoddpage {\chapfonts
+\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}%
+\par\penalty 5000 %
+}
+\def\centerchfopen #1{%
+\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
+ \parindent=0pt
+ \hfill {\rm #1}\hfill}}\bigskip \par\nobreak
+}
+\def\CHAPFopen{%
+ \global\let\chapmacro=\chfopen
+ \global\let\centerchapmacro=\centerchfopen}
+
+
+% Section titles. These macros combine the section number parts and
+% call the generic \sectionheading to do the printing.
+%
+\newskip\secheadingskip
+\def\secheadingbreak{\dobreak \secheadingskip{-1000}}
+
+% Subsection titles.
+\newskip\subsecheadingskip
+\def\subsecheadingbreak{\dobreak \subsecheadingskip{-500}}
+
+% Subsubsection titles.
+\def\subsubsecheadingskip{\subsecheadingskip}
+\def\subsubsecheadingbreak{\subsecheadingbreak}
+
+
+% Print any size, any type, section title.
+%
+% #1 is the text, #2 is the section level (sec/subsec/subsubsec), #3 is
+% the section type for xrefs (Ynumbered, Ynothing, Yappendix), #4 is the
+% section number.
+%
+\def\sectionheading#1#2#3#4{%
+ {%
+ % Switch to the right set of fonts.
+ \csname #2fonts\endcsname \rm
+ %
+ % Insert space above the heading.
+ \csname #2headingbreak\endcsname
+ %
+ % Only insert the space after the number if we have a section number.
+ \def\sectionlevel{#2}%
+ \def\temptype{#3}%
+ %
+ \ifx\temptype\Ynothingkeyword
+ \setbox0 = \hbox{}%
+ \def\toctype{unn}%
+ \gdef\thissection{#1}%
+ \else\ifx\temptype\Yomitfromtockeyword
+ % for @headings -- no section number, don't include in toc,
+ % and don't redefine \thissection.
+ \setbox0 = \hbox{}%
+ \def\toctype{omit}%
+ \let\sectionlevel=\empty
+ \else\ifx\temptype\Yappendixkeyword
+ \setbox0 = \hbox{#4\enspace}%
+ \def\toctype{app}%
+ \gdef\thissection{#1}%
+ \else
+ \setbox0 = \hbox{#4\enspace}%
+ \def\toctype{num}%
+ \gdef\thissection{#1}%
+ \fi\fi\fi
+ %
+ % Write the toc entry (before \donoderef). See comments in \chapmacro.
+ \writetocentry{\toctype\sectionlevel}{#1}{#4}%
+ %
+ % Write the node reference (= pdf destination for pdftex).
+ % Again, see comments in \chapmacro.
+ \donoderef{#3}%
+ %
+ % Interline glue will be inserted when the vbox is completed.
+ % That glue will be a valid breakpoint for the page, since it'll be
+ % preceded by a whatsit (usually from the \donoderef, or from the
+ % \writetocentry if there was no node). We don't want to allow that
+ % break, since then the whatsits could end up on page n while the
+ % section is on page n+1, thus toc/etc. are wrong. Debian bug 276000.
+ \nobreak
+ %
+ % Output the actual section heading.
+ \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright
+ \hangindent=\wd0 % zero if no section number
+ \unhbox0 #1}%
+ }%
+ % Add extra space after the heading -- half of whatever came above it.
+ % Don't allow stretch, though.
+ \kern .5 \csname #2headingskip\endcsname
+ %
+ % Do not let the kern be a potential breakpoint, as it would be if it
+ % was followed by glue.
+ \nobreak
+ %
+ % We'll almost certainly start a paragraph next, so don't let that
+ % glue accumulate. (Not a breakpoint because it's preceded by a
+ % discardable item.)
+ \vskip-\parskip
+ %
+ % This is purely so the last item on the list is a known \penalty >
+ % 10000. This is so \startdefun can avoid allowing breakpoints after
+ % section headings. Otherwise, it would insert a valid breakpoint between:
+ %
+ % @section sec-whatever
+ % @deffn def-whatever
+ \penalty 10001
+}
+
+
+\message{toc,}
+% Table of contents.
+\newwrite\tocfile
+
+% Write an entry to the toc file, opening it if necessary.
+% Called from @chapter, etc.
+%
+% Example usage: \writetocentry{sec}{Section Name}{\the\chapno.\the\secno}
+% We append the current node name (if any) and page number as additional
+% arguments for the \{chap,sec,...}entry macros which will eventually
+% read this. The node name is used in the pdf outlines as the
+% destination to jump to.
+%
+% We open the .toc file for writing here instead of at @setfilename (or
+% any other fixed time) so that @contents can be anywhere in the document.
+% But if #1 is `omit', then we don't do anything. This is used for the
+% table of contents chapter openings themselves.
+%
+\newif\iftocfileopened
+\def\omitkeyword{omit}%
+%
+\def\writetocentry#1#2#3{%
+ \edef\writetoctype{#1}%
+ \ifx\writetoctype\omitkeyword \else
+ \iftocfileopened\else
+ \immediate\openout\tocfile = \jobname.toc
+ \global\tocfileopenedtrue
+ \fi
+ %
+ \iflinks
+ {\atdummies
+ \edef\temp{%
+ \write\tocfile{@#1entry{#2}{#3}{\lastnode}{\noexpand\folio}}}%
+ \temp
+ }%
+ \fi
+ \fi
+ %
+ % Tell \shipout to create a pdf destination on each page, if we're
+ % writing pdf. These are used in the table of contents. We can't
+ % just write one on every page because the title pages are numbered
+ % 1 and 2 (the page numbers aren't printed), and so are the first
+ % two pages of the document. Thus, we'd have two destinations named
+ % `1', and two named `2'.
+ \ifpdf \global\pdfmakepagedesttrue \fi
+}
+
+
+% These characters do not print properly in the Computer Modern roman
+% fonts, so we must take special care. This is more or less redundant
+% with the Texinfo input format setup at the end of this file.
+%
+\def\activecatcodes{%
+ \catcode`\"=\active
+ \catcode`\$=\active
+ \catcode`\<=\active
+ \catcode`\>=\active
+ \catcode`\\=\active
+ \catcode`\^=\active
+ \catcode`\_=\active
+ \catcode`\|=\active
+ \catcode`\~=\active
+}
+
+
+% Read the toc file, which is essentially Texinfo input.
+\def\readtocfile{%
+ \setupdatafile
+ \activecatcodes
+ \input \tocreadfilename
+}
+
+\newskip\contentsrightmargin \contentsrightmargin=1in
+\newcount\savepageno
+\newcount\lastnegativepageno \lastnegativepageno = -1
+
+% Prepare to read what we've written to \tocfile.
+%
+\def\startcontents#1{%
+ % If @setchapternewpage on, and @headings double, the contents should
+ % start on an odd page, unlike chapters. Thus, we maintain
+ % \contentsalignmacro in parallel with \pagealignmacro.
+ % From: Torbjorn Granlund <tege@matematik.su.se>
+ \contentsalignmacro
+ \immediate\closeout\tocfile
+ %
+ % Don't need to put `Contents' or `Short Contents' in the headline.
+ % It is abundantly clear what they are.
+ \def\thischapter{}%
+ \chapmacro{#1}{Yomitfromtoc}{}%
+ %
+ \savepageno = \pageno
+ \begingroup % Set up to handle contents files properly.
+ \raggedbottom % Worry more about breakpoints than the bottom.
+ \advance\hsize by -\contentsrightmargin % Don't use the full line length.
+ %
+ % Roman numerals for page numbers.
+ \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi
+}
+
+% redefined for the two-volume lispref. We always output on
+% \jobname.toc even if this is redefined.
+%
+\def\tocreadfilename{\jobname.toc}
+
+% Normal (long) toc.
+%
+\def\contents{%
+ \startcontents{\putwordTOC}%
+ \openin 1 \tocreadfilename\space
+ \ifeof 1 \else
+ \readtocfile
+ \fi
+ \vfill \eject
+ \contentsalignmacro % in case @setchapternewpage odd is in effect
+ \ifeof 1 \else
+ \pdfmakeoutlines
+ \fi
+ \closein 1
+ \endgroup
+ \lastnegativepageno = \pageno
+ \global\pageno = \savepageno
+}
+
+% And just the chapters.
+\def\summarycontents{%
+ \startcontents{\putwordShortTOC}%
+ %
+ \let\numchapentry = \shortchapentry
+ \let\appentry = \shortchapentry
+ \let\unnchapentry = \shortunnchapentry
+ % We want a true roman here for the page numbers.
+ \secfonts
+ \let\rm=\shortcontrm \let\bf=\shortcontbf
+ \let\sl=\shortcontsl \let\tt=\shortconttt
+ \rm
+ \hyphenpenalty = 10000
+ \advance\baselineskip by 1pt % Open it up a little.
+ \def\numsecentry##1##2##3##4{}
+ \let\appsecentry = \numsecentry
+ \let\unnsecentry = \numsecentry
+ \let\numsubsecentry = \numsecentry
+ \let\appsubsecentry = \numsecentry
+ \let\unnsubsecentry = \numsecentry
+ \let\numsubsubsecentry = \numsecentry
+ \let\appsubsubsecentry = \numsecentry
+ \let\unnsubsubsecentry = \numsecentry
+ \openin 1 \tocreadfilename\space
+ \ifeof 1 \else
+ \readtocfile
+ \fi
+ \closein 1
+ \vfill \eject
+ \contentsalignmacro % in case @setchapternewpage odd is in effect
+ \endgroup
+ \lastnegativepageno = \pageno
+ \global\pageno = \savepageno
+}
+\let\shortcontents = \summarycontents
+
+% Typeset the label for a chapter or appendix for the short contents.
+% The arg is, e.g., `A' for an appendix, or `3' for a chapter.
+%
+\def\shortchaplabel#1{%
+ % This space should be enough, since a single number is .5em, and the
+ % widest letter (M) is 1em, at least in the Computer Modern fonts.
+ % But use \hss just in case.
+ % (This space doesn't include the extra space that gets added after
+ % the label; that gets put in by \shortchapentry above.)
+ %
+ % We'd like to right-justify chapter numbers, but that looks strange
+ % with appendix letters. And right-justifying numbers and
+ % left-justifying letters looks strange when there is less than 10
+ % chapters. Have to read the whole toc once to know how many chapters
+ % there are before deciding ...
+ \hbox to 1em{#1\hss}%
+}
+
+% These macros generate individual entries in the table of contents.
+% The first argument is the chapter or section name.
+% The last argument is the page number.
+% The arguments in between are the chapter number, section number, ...
+
+% Chapters, in the main contents.
+\def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}}
+%
+% Chapters, in the short toc.
+% See comments in \dochapentry re vbox and related settings.
+\def\shortchapentry#1#2#3#4{%
+ \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#4\egroup}%
+}
+
+% Appendices, in the main contents.
+% Need the word Appendix, and a fixed-size box.
+%
+\def\appendixbox#1{%
+ % We use M since it's probably the widest letter.
+ \setbox0 = \hbox{\putwordAppendix{} M}%
+ \hbox to \wd0{\putwordAppendix{} #1\hss}}
+%
+\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\labelspace#1}{#4}}
+
+% Unnumbered chapters.
+\def\unnchapentry#1#2#3#4{\dochapentry{#1}{#4}}
+\def\shortunnchapentry#1#2#3#4{\tocentry{#1}{\doshortpageno\bgroup#4\egroup}}
+
+% Sections.
+\def\numsecentry#1#2#3#4{\dosecentry{#2\labelspace#1}{#4}}
+\let\appsecentry=\numsecentry
+\def\unnsecentry#1#2#3#4{\dosecentry{#1}{#4}}
+
+% Subsections.
+\def\numsubsecentry#1#2#3#4{\dosubsecentry{#2\labelspace#1}{#4}}
+\let\appsubsecentry=\numsubsecentry
+\def\unnsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}}
+
+% And subsubsections.
+\def\numsubsubsecentry#1#2#3#4{\dosubsubsecentry{#2\labelspace#1}{#4}}
+\let\appsubsubsecentry=\numsubsubsecentry
+\def\unnsubsubsecentry#1#2#3#4{\dosubsubsecentry{#1}{#4}}
+
+% This parameter controls the indentation of the various levels.
+% Same as \defaultparindent.
+\newdimen\tocindent \tocindent = 15pt
+
+% Now for the actual typesetting. In all these, #1 is the text and #2 is the
+% page number.
+%
+% If the toc has to be broken over pages, we want it to be at chapters
+% if at all possible; hence the \penalty.
+\def\dochapentry#1#2{%
+ \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip
+ \begingroup
+ \chapentryfonts
+ \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+ \endgroup
+ \nobreak\vskip .25\baselineskip plus.1\baselineskip
+}
+
+\def\dosecentry#1#2{\begingroup
+ \secentryfonts \leftskip=\tocindent
+ \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+\endgroup}
+
+\def\dosubsecentry#1#2{\begingroup
+ \subsecentryfonts \leftskip=2\tocindent
+ \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+\endgroup}
+
+\def\dosubsubsecentry#1#2{\begingroup
+ \subsubsecentryfonts \leftskip=3\tocindent
+ \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+\endgroup}
+
+% We use the same \entry macro as for the index entries.
+\let\tocentry = \entry
+
+% Space between chapter (or whatever) number and the title.
+\def\labelspace{\hskip1em \relax}
+
+\def\dopageno#1{{\rm #1}}
+\def\doshortpageno#1{{\rm #1}}
+
+\def\chapentryfonts{\secfonts \rm}
+\def\secentryfonts{\textfonts}
+\def\subsecentryfonts{\textfonts}
+\def\subsubsecentryfonts{\textfonts}
+
+
+\message{environments,}
+% @foo ... @end foo.
+
+% @point{}, @result{}, @expansion{}, @print{}, @equiv{}.
+%
+% Since these characters are used in examples, it should be an even number of
+% \tt widths. Each \tt character is 1en, so two makes it 1em.
+%
+\def\point{$\star$}
+\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}}
+\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}}
+\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}}
+\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}}
+
+% The @error{} command.
+% Adapted from the TeXbook's \boxit.
+%
+\newbox\errorbox
+%
+{\tentt \global\dimen0 = 3em}% Width of the box.
+\dimen2 = .55pt % Thickness of rules
+% The text. (`r' is open on the right, `e' somewhat less so on the left.)
+\setbox0 = \hbox{\kern-.75pt \reducedsf error\kern-1.5pt}
+%
+\setbox\errorbox=\hbox to \dimen0{\hfil
+ \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right.
+ \advance\hsize by -2\dimen2 % Rules.
+ \vbox{%
+ \hrule height\dimen2
+ \hbox{\vrule width\dimen2 \kern3pt % Space to left of text.
+ \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below.
+ \kern3pt\vrule width\dimen2}% Space to right.
+ \hrule height\dimen2}
+ \hfil}
+%
+\def\error{\leavevmode\lower.7ex\copy\errorbox}
+
+% @tex ... @end tex escapes into raw Tex temporarily.
+% One exception: @ is still an escape character, so that @end tex works.
+% But \@ or @@ will get a plain tex @ character.
+
+\envdef\tex{%
+ \catcode `\\=0 \catcode `\{=1 \catcode `\}=2
+ \catcode `\$=3 \catcode `\&=4 \catcode `\#=6
+ \catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie
+ \catcode `\%=14
+ \catcode `\+=\other
+ \catcode `\"=\other
+ \catcode `\|=\other
+ \catcode `\<=\other
+ \catcode `\>=\other
+ \escapechar=`\\
+ %
+ \let\b=\ptexb
+ \let\bullet=\ptexbullet
+ \let\c=\ptexc
+ \let\,=\ptexcomma
+ \let\.=\ptexdot
+ \let\dots=\ptexdots
+ \let\equiv=\ptexequiv
+ \let\!=\ptexexclam
+ \let\i=\ptexi
+ \let\indent=\ptexindent
+ \let\noindent=\ptexnoindent
+ \let\{=\ptexlbrace
+ \let\+=\tabalign
+ \let\}=\ptexrbrace
+ \let\/=\ptexslash
+ \let\*=\ptexstar
+ \let\t=\ptext
+ \let\frenchspacing=\plainfrenchspacing
+ %
+ \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}%
+ \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}%
+ \def\@{@}%
+}
+% There is no need to define \Etex.
+
+% Define @lisp ... @end lisp.
+% @lisp environment forms a group so it can rebind things,
+% including the definition of @end lisp (which normally is erroneous).
+
+% Amount to narrow the margins by for @lisp.
+\newskip\lispnarrowing \lispnarrowing=0.4in
+
+% This is the definition that ^^M gets inside @lisp, @example, and other
+% such environments. \null is better than a space, since it doesn't
+% have any width.
+\def\lisppar{\null\endgraf}
+
+% This space is always present above and below environments.
+\newskip\envskipamount \envskipamount = 0pt
+
+% Make spacing and below environment symmetrical. We use \parskip here
+% to help in doing that, since in @example-like environments \parskip
+% is reset to zero; thus the \afterenvbreak inserts no space -- but the
+% start of the next paragraph will insert \parskip.
+%
+\def\aboveenvbreak{{%
+ % =10000 instead of <10000 because of a special case in \itemzzz and
+ % \sectionheading, q.v.
+ \ifnum \lastpenalty=10000 \else
+ \advance\envskipamount by \parskip
+ \endgraf
+ \ifdim\lastskip<\envskipamount
+ \removelastskip
+ % it's not a good place to break if the last penalty was \nobreak
+ % or better ...
+ \ifnum\lastpenalty<10000 \penalty-50 \fi
+ \vskip\envskipamount
+ \fi
+ \fi
+}}
+
+\let\afterenvbreak = \aboveenvbreak
+
+% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins; it will
+% also clear it, so that its embedded environments do the narrowing again.
+\let\nonarrowing=\relax
+
+% @cartouche ... @end cartouche: draw rectangle w/rounded corners around
+% environment contents.
+\font\circle=lcircle10
+\newdimen\circthick
+\newdimen\cartouter\newdimen\cartinner
+\newskip\normbskip\newskip\normpskip\newskip\normlskip
+\circthick=\fontdimen8\circle
+%
+\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth
+\def\ctr{{\hskip 6pt\circle\char'010}}
+\def\cbl{{\circle\char'012\hskip -6pt}}
+\def\cbr{{\hskip 6pt\circle\char'011}}
+\def\carttop{\hbox to \cartouter{\hskip\lskip
+ \ctl\leaders\hrule height\circthick\hfil\ctr
+ \hskip\rskip}}
+\def\cartbot{\hbox to \cartouter{\hskip\lskip
+ \cbl\leaders\hrule height\circthick\hfil\cbr
+ \hskip\rskip}}
+%
+\newskip\lskip\newskip\rskip
+
+\envdef\cartouche{%
+ \ifhmode\par\fi % can't be in the midst of a paragraph.
+ \startsavinginserts
+ \lskip=\leftskip \rskip=\rightskip
+ \leftskip=0pt\rightskip=0pt % we want these *outside*.
+ \cartinner=\hsize \advance\cartinner by-\lskip
+ \advance\cartinner by-\rskip
+ \cartouter=\hsize
+ \advance\cartouter by 18.4pt % allow for 3pt kerns on either
+ % side, and for 6pt waste from
+ % each corner char, and rule thickness
+ \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip
+ % Flag to tell @lisp, etc., not to narrow margin.
+ \let\nonarrowing = t%
+ \vbox\bgroup
+ \baselineskip=0pt\parskip=0pt\lineskip=0pt
+ \carttop
+ \hbox\bgroup
+ \hskip\lskip
+ \vrule\kern3pt
+ \vbox\bgroup
+ \kern3pt
+ \hsize=\cartinner
+ \baselineskip=\normbskip
+ \lineskip=\normlskip
+ \parskip=\normpskip
+ \vskip -\parskip
+ \comment % For explanation, see the end of \def\group.
+}
+\def\Ecartouche{%
+ \ifhmode\par\fi
+ \kern3pt
+ \egroup
+ \kern3pt\vrule
+ \hskip\rskip
+ \egroup
+ \cartbot
+ \egroup
+ \checkinserts
+}
+
+
+% This macro is called at the beginning of all the @example variants,
+% inside a group.
+\def\nonfillstart{%
+ \aboveenvbreak
+ \hfuzz = 12pt % Don't be fussy
+ \sepspaces % Make spaces be word-separators rather than space tokens.
+ \let\par = \lisppar % don't ignore blank lines
+ \obeylines % each line of input is a line of output
+ \parskip = 0pt
+ \parindent = 0pt
+ \emergencystretch = 0pt % don't try to avoid overfull boxes
+ \ifx\nonarrowing\relax
+ \advance \leftskip by \lispnarrowing
+ \exdentamount=\lispnarrowing
+ \else
+ \let\nonarrowing = \relax
+ \fi
+ \let\exdent=\nofillexdent
+}
+
+% If you want all examples etc. small: @set dispenvsize small.
+% If you want even small examples the full size: @set dispenvsize nosmall.
+% This affects the following displayed environments:
+% @example, @display, @format, @lisp
+%
+\def\smallword{small}
+\def\nosmallword{nosmall}
+\let\SETdispenvsize\relax
+\def\setnormaldispenv{%
+ \ifx\SETdispenvsize\smallword
+ % end paragraph for sake of leading, in case document has no blank
+ % line. This is redundant with what happens in \aboveenvbreak, but
+ % we need to do it before changing the fonts, and it's inconvenient
+ % to change the fonts afterward.
+ \ifnum \lastpenalty=10000 \else \endgraf \fi
+ \smallexamplefonts \rm
+ \fi
+}
+\def\setsmalldispenv{%
+ \ifx\SETdispenvsize\nosmallword
+ \else
+ \ifnum \lastpenalty=10000 \else \endgraf \fi
+ \smallexamplefonts \rm
+ \fi
+}
+
+% We often define two environments, @foo and @smallfoo.
+% Let's do it by one command:
+\def\makedispenv #1#2{
+ \expandafter\envdef\csname#1\endcsname {\setnormaldispenv #2}
+ \expandafter\envdef\csname small#1\endcsname {\setsmalldispenv #2}
+ \expandafter\let\csname E#1\endcsname \afterenvbreak
+ \expandafter\let\csname Esmall#1\endcsname \afterenvbreak
+}
+
+% Define two synonyms:
+\def\maketwodispenvs #1#2#3{
+ \makedispenv{#1}{#3}
+ \makedispenv{#2}{#3}
+}
+
+% @lisp: indented, narrowed, typewriter font; @example: same as @lisp.
+%
+% @smallexample and @smalllisp: use smaller fonts.
+% Originally contributed by Pavel@xerox.
+%
+\maketwodispenvs {lisp}{example}{%
+ \nonfillstart
+ \tt\quoteexpand
+ \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special.
+ \gobble % eat return
+}
+% @display/@smalldisplay: same as @lisp except keep current font.
+%
+\makedispenv {display}{%
+ \nonfillstart
+ \gobble
+}
+
+% @format/@smallformat: same as @display except don't narrow margins.
+%
+\makedispenv{format}{%
+ \let\nonarrowing = t%
+ \nonfillstart
+ \gobble
+}
+
+% @flushleft: same as @format, but doesn't obey \SETdispenvsize.
+\envdef\flushleft{%
+ \let\nonarrowing = t%
+ \nonfillstart
+ \gobble
+}
+\let\Eflushleft = \afterenvbreak
+
+% @flushright.
+%
+\envdef\flushright{%
+ \let\nonarrowing = t%
+ \nonfillstart
+ \advance\leftskip by 0pt plus 1fill
+ \gobble
+}
+\let\Eflushright = \afterenvbreak
+
+
+% @quotation does normal linebreaking (hence we can't use \nonfillstart)
+% and narrows the margins. We keep \parskip nonzero in general, since
+% we're doing normal filling. So, when using \aboveenvbreak and
+% \afterenvbreak, temporarily make \parskip 0.
+%
+\envdef\quotation{%
+ {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip
+ \parindent=0pt
+ %
+ % @cartouche defines \nonarrowing to inhibit narrowing at next level down.
+ \ifx\nonarrowing\relax
+ \advance\leftskip by \lispnarrowing
+ \advance\rightskip by \lispnarrowing
+ \exdentamount = \lispnarrowing
+ \else
+ \let\nonarrowing = \relax
+ \fi
+ \parsearg\quotationlabel
+}
+
+% We have retained a nonzero parskip for the environment, since we're
+% doing normal filling.
+%
+\def\Equotation{%
+ \par
+ \ifx\quotationauthor\undefined\else
+ % indent a bit.
+ \leftline{\kern 2\leftskip \sl ---\quotationauthor}%
+ \fi
+ {\parskip=0pt \afterenvbreak}%
+}
+
+% If we're given an argument, typeset it in bold with a colon after.
+\def\quotationlabel#1{%
+ \def\temp{#1}%
+ \ifx\temp\empty \else
+ {\bf #1: }%
+ \fi
+}
+
+
+% LaTeX-like @verbatim...@end verbatim and @verb{<char>...<char>}
+% If we want to allow any <char> as delimiter,
+% we need the curly braces so that makeinfo sees the @verb command, eg:
+% `@verbx...x' would look like the '@verbx' command. --janneke@gnu.org
+%
+% [Knuth]: Donald Ervin Knuth, 1996. The TeXbook.
+%
+% [Knuth] p.344; only we need to do the other characters Texinfo sets
+% active too. Otherwise, they get lost as the first character on a
+% verbatim line.
+\def\dospecials{%
+ \do\ \do\\\do\{\do\}\do\$\do\&%
+ \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~%
+ \do\<\do\>\do\|\do\@\do+\do\"%
+}
+%
+% [Knuth] p. 380
+\def\uncatcodespecials{%
+ \def\do##1{\catcode`##1=\other}\dospecials}
+%
+% [Knuth] pp. 380,381,391
+% Disable Spanish ligatures ?` and !` of \tt font
+\begingroup
+ \catcode`\`=\active\gdef`{\relax\lq}
+\endgroup
+%
+% Setup for the @verb command.
+%
+% Eight spaces for a tab
+\begingroup
+ \catcode`\^^I=\active
+ \gdef\tabeightspaces{\catcode`\^^I=\active\def^^I{\ \ \ \ \ \ \ \ }}
+\endgroup
+%
+\def\setupverb{%
+ \tt % easiest (and conventionally used) font for verbatim
+ \def\par{\leavevmode\endgraf}%
+ \catcode`\`=\active
+ \tabeightspaces
+ % Respect line breaks,
+ % print special symbols as themselves, and
+ % make each space count
+ % must do in this order:
+ \obeylines \uncatcodespecials \sepspaces
+}
+
+% Setup for the @verbatim environment
+%
+% Real tab expansion
+\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount
+%
+\def\starttabbox{\setbox0=\hbox\bgroup}
+
+% Allow an option to not replace quotes with a regular directed right
+% quote/apostrophe (char 0x27), but instead use the undirected quote
+% from cmtt (char 0x0d). The undirected quote is ugly, so don't make it
+% the default, but it works for pasting with more pdf viewers (at least
+% evince), the lilypond developers report. xpdf does work with the
+% regular 0x27.
+%
+\def\codequoteright{%
+ \expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax
+ \expandafter\ifx\csname SETcodequoteundirected\endcsname\relax
+ '%
+ \else \char'15 \fi
+ \else \char'15 \fi
+}
+%
+% and a similar option for the left quote char vs. a grave accent.
+% Modern fonts display ASCII 0x60 as a grave accent, so some people like
+% the code environments to do likewise.
+%
+\def\codequoteleft{%
+ \expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax
+ \expandafter\ifx\csname SETcodequotebacktick\endcsname\relax
+ `%
+ \else \char'22 \fi
+ \else \char'22 \fi
+}
+%
+\begingroup
+ \catcode`\^^I=\active
+ \gdef\tabexpand{%
+ \catcode`\^^I=\active
+ \def^^I{\leavevmode\egroup
+ \dimen0=\wd0 % the width so far, or since the previous tab
+ \divide\dimen0 by\tabw
+ \multiply\dimen0 by\tabw % compute previous multiple of \tabw
+ \advance\dimen0 by\tabw % advance to next multiple of \tabw
+ \wd0=\dimen0 \box0 \starttabbox
+ }%
+ }
+ \catcode`\'=\active
+ \gdef\rquoteexpand{\catcode\rquoteChar=\active \def'{\codequoteright}}%
+ %
+ \catcode`\`=\active
+ \gdef\lquoteexpand{\catcode\lquoteChar=\active \def`{\codequoteleft}}%
+ %
+ \gdef\quoteexpand{\rquoteexpand \lquoteexpand}%
+\endgroup
+
+% start the verbatim environment.
+\def\setupverbatim{%
+ \let\nonarrowing = t%
+ \nonfillstart
+ % Easiest (and conventionally used) font for verbatim
+ \tt
+ \def\par{\leavevmode\egroup\box0\endgraf}%
+ \catcode`\`=\active
+ \tabexpand
+ \quoteexpand
+ % Respect line breaks,
+ % print special symbols as themselves, and
+ % make each space count
+ % must do in this order:
+ \obeylines \uncatcodespecials \sepspaces
+ \everypar{\starttabbox}%
+}
+
+% Do the @verb magic: verbatim text is quoted by unique
+% delimiter characters. Before first delimiter expect a
+% right brace, after last delimiter expect closing brace:
+%
+% \def\doverb'{'<char>#1<char>'}'{#1}
+%
+% [Knuth] p. 382; only eat outer {}
+\begingroup
+ \catcode`[=1\catcode`]=2\catcode`\{=\other\catcode`\}=\other
+ \gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next]
+\endgroup
+%
+\def\verb{\begingroup\setupverb\doverb}
+%
+%
+% Do the @verbatim magic: define the macro \doverbatim so that
+% the (first) argument ends when '@end verbatim' is reached, ie:
+%
+% \def\doverbatim#1@end verbatim{#1}
+%
+% For Texinfo it's a lot easier than for LaTeX,
+% because texinfo's \verbatim doesn't stop at '\end{verbatim}':
+% we need not redefine '\', '{' and '}'.
+%
+% Inspired by LaTeX's verbatim command set [latex.ltx]
+%
+\begingroup
+ \catcode`\ =\active
+ \obeylines %
+ % ignore everything up to the first ^^M, that's the newline at the end
+ % of the @verbatim input line itself. Otherwise we get an extra blank
+ % line in the output.
+ \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}%
+ % We really want {...\end verbatim} in the body of the macro, but
+ % without the active space; thus we have to use \xdef and \gobble.
+\endgroup
+%
+\envdef\verbatim{%
+ \setupverbatim\doverbatim
+}
+\let\Everbatim = \afterenvbreak
+
+
+% @verbatiminclude FILE - insert text of file in verbatim environment.
+%
+\def\verbatiminclude{\parseargusing\filenamecatcodes\doverbatiminclude}
+%
+\def\doverbatiminclude#1{%
+ {%
+ \makevalueexpandable
+ \setupverbatim
+ \input #1
+ \afterenvbreak
+ }%
+}
+
+% @copying ... @end copying.
+% Save the text away for @insertcopying later.
+%
+% We save the uninterpreted tokens, rather than creating a box.
+% Saving the text in a box would be much easier, but then all the
+% typesetting commands (@smallbook, font changes, etc.) have to be done
+% beforehand -- and a) we want @copying to be done first in the source
+% file; b) letting users define the frontmatter in as flexible order as
+% possible is very desirable.
+%
+\def\copying{\checkenv{}\begingroup\scanargctxt\docopying}
+\def\docopying#1@end copying{\endgroup\def\copyingtext{#1}}
+%
+\def\insertcopying{%
+ \begingroup
+ \parindent = 0pt % paragraph indentation looks wrong on title page
+ \scanexp\copyingtext
+ \endgroup
+}
+
+
+\message{defuns,}
+% @defun etc.
+
+\newskip\defbodyindent \defbodyindent=.4in
+\newskip\defargsindent \defargsindent=50pt
+\newskip\deflastargmargin \deflastargmargin=18pt
+\newcount\defunpenalty
+
+% Start the processing of @deffn:
+\def\startdefun{%
+ \ifnum\lastpenalty<10000
+ \medbreak
+ \defunpenalty=10003 % Will keep this @deffn together with the
+ % following @def command, see below.
+ \else
+ % If there are two @def commands in a row, we'll have a \nobreak,
+ % which is there to keep the function description together with its
+ % header. But if there's nothing but headers, we need to allow a
+ % break somewhere. Check specifically for penalty 10002, inserted
+ % by \printdefunline, instead of 10000, since the sectioning
+ % commands also insert a nobreak penalty, and we don't want to allow
+ % a break between a section heading and a defun.
+ %
+ % As a minor refinement, we avoid "club" headers by signalling
+ % with penalty of 10003 after the very first @deffn in the
+ % sequence (see above), and penalty of 10002 after any following
+ % @def command.
+ \ifnum\lastpenalty=10002 \penalty2000 \else \defunpenalty=10002 \fi
+ %
+ % Similarly, after a section heading, do not allow a break.
+ % But do insert the glue.
+ \medskip % preceded by discardable penalty, so not a breakpoint
+ \fi
+ %
+ \parindent=0in
+ \advance\leftskip by \defbodyindent
+ \exdentamount=\defbodyindent
+}
+
+\def\dodefunx#1{%
+ % First, check whether we are in the right environment:
+ \checkenv#1%
+ %
+ % As above, allow line break if we have multiple x headers in a row.
+ % It's not a great place, though.
+ \ifnum\lastpenalty=10002 \penalty3000 \else \defunpenalty=10002 \fi
+ %
+ % And now, it's time to reuse the body of the original defun:
+ \expandafter\gobbledefun#1%
+}
+\def\gobbledefun#1\startdefun{}
+
+% \printdefunline \deffnheader{text}
+%
+\def\printdefunline#1#2{%
+ \begingroup
+ % call \deffnheader:
+ #1#2 \endheader
+ % common ending:
+ \interlinepenalty = 10000
+ \advance\rightskip by 0pt plus 1fil
+ \endgraf
+ \nobreak\vskip -\parskip
+ \penalty\defunpenalty % signal to \startdefun and \dodefunx
+ % Some of the @defun-type tags do not enable magic parentheses,
+ % rendering the following check redundant. But we don't optimize.
+ \checkparencounts
+ \endgroup
+}
+
+\def\Edefun{\endgraf\medbreak}
+
+% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn;
+% the only thing remainnig is to define \deffnheader.
+%
+\def\makedefun#1{%
+ \expandafter\let\csname E#1\endcsname = \Edefun
+ \edef\temp{\noexpand\domakedefun
+ \makecsname{#1}\makecsname{#1x}\makecsname{#1header}}%
+ \temp
+}
+
+% \domakedefun \deffn \deffnx \deffnheader
+%
+% Define \deffn and \deffnx, without parameters.
+% \deffnheader has to be defined explicitly.
+%
+\def\domakedefun#1#2#3{%
+ \envdef#1{%
+ \startdefun
+ \parseargusing\activeparens{\printdefunline#3}%
+ }%
+ \def#2{\dodefunx#1}%
+ \def#3%
+}
+
+%%% Untyped functions:
+
+% @deffn category name args
+\makedefun{deffn}{\deffngeneral{}}
+
+% @deffn category class name args
+\makedefun{defop}#1 {\defopon{#1\ \putwordon}}
+
+% \defopon {category on}class name args
+\def\defopon#1#2 {\deffngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} }
+
+% \deffngeneral {subind}category name args
+%
+\def\deffngeneral#1#2 #3 #4\endheader{%
+ % Remember that \dosubind{fn}{foo}{} is equivalent to \doind{fn}{foo}.
+ \dosubind{fn}{\code{#3}}{#1}%
+ \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}%
+}
+
+%%% Typed functions:
+
+% @deftypefn category type name args
+\makedefun{deftypefn}{\deftypefngeneral{}}
+
+% @deftypeop category class type name args
+\makedefun{deftypeop}#1 {\deftypeopon{#1\ \putwordon}}
+
+% \deftypeopon {category on}class type name args
+\def\deftypeopon#1#2 {\deftypefngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} }
+
+% \deftypefngeneral {subind}category type name args
+%
+\def\deftypefngeneral#1#2 #3 #4 #5\endheader{%
+ \dosubind{fn}{\code{#4}}{#1}%
+ \defname{#2}{#3}{#4}\defunargs{#5\unskip}%
+}
+
+%%% Typed variables:
+
+% @deftypevr category type var args
+\makedefun{deftypevr}{\deftypecvgeneral{}}
+
+% @deftypecv category class type var args
+\makedefun{deftypecv}#1 {\deftypecvof{#1\ \putwordof}}
+
+% \deftypecvof {category of}class type var args
+\def\deftypecvof#1#2 {\deftypecvgeneral{\putwordof\ \code{#2}}{#1\ \code{#2}} }
+
+% \deftypecvgeneral {subind}category type var args
+%
+\def\deftypecvgeneral#1#2 #3 #4 #5\endheader{%
+ \dosubind{vr}{\code{#4}}{#1}%
+ \defname{#2}{#3}{#4}\defunargs{#5\unskip}%
+}
+
+%%% Untyped variables:
+
+% @defvr category var args
+\makedefun{defvr}#1 {\deftypevrheader{#1} {} }
+
+% @defcv category class var args
+\makedefun{defcv}#1 {\defcvof{#1\ \putwordof}}
+
+% \defcvof {category of}class var args
+\def\defcvof#1#2 {\deftypecvof{#1}#2 {} }
+
+%%% Type:
+% @deftp category name args
+\makedefun{deftp}#1 #2 #3\endheader{%
+ \doind{tp}{\code{#2}}%
+ \defname{#1}{}{#2}\defunargs{#3\unskip}%
+}
+
+% Remaining @defun-like shortcuts:
+\makedefun{defun}{\deffnheader{\putwordDeffunc} }
+\makedefun{defmac}{\deffnheader{\putwordDefmac} }
+\makedefun{defspec}{\deffnheader{\putwordDefspec} }
+\makedefun{deftypefun}{\deftypefnheader{\putwordDeffunc} }
+\makedefun{defvar}{\defvrheader{\putwordDefvar} }
+\makedefun{defopt}{\defvrheader{\putwordDefopt} }
+\makedefun{deftypevar}{\deftypevrheader{\putwordDefvar} }
+\makedefun{defmethod}{\defopon\putwordMethodon}
+\makedefun{deftypemethod}{\deftypeopon\putwordMethodon}
+\makedefun{defivar}{\defcvof\putwordInstanceVariableof}
+\makedefun{deftypeivar}{\deftypecvof\putwordInstanceVariableof}
+
+% \defname, which formats the name of the @def (not the args).
+% #1 is the category, such as "Function".
+% #2 is the return type, if any.
+% #3 is the function name.
+%
+% We are followed by (but not passed) the arguments, if any.
+%
+\def\defname#1#2#3{%
+ % Get the values of \leftskip and \rightskip as they were outside the @def...
+ \advance\leftskip by -\defbodyindent
+ %
+ % How we'll format the type name. Putting it in brackets helps
+ % distinguish it from the body text that may end up on the next line
+ % just below it.
+ \def\temp{#1}%
+ \setbox0=\hbox{\kern\deflastargmargin \ifx\temp\empty\else [\rm\temp]\fi}
+ %
+ % Figure out line sizes for the paragraph shape.
+ % The first line needs space for \box0; but if \rightskip is nonzero,
+ % we need only space for the part of \box0 which exceeds it:
+ \dimen0=\hsize \advance\dimen0 by -\wd0 \advance\dimen0 by \rightskip
+ % The continuations:
+ \dimen2=\hsize \advance\dimen2 by -\defargsindent
+ % (plain.tex says that \dimen1 should be used only as global.)
+ \parshape 2 0in \dimen0 \defargsindent \dimen2
+ %
+ % Put the type name to the right margin.
+ \noindent
+ \hbox to 0pt{%
+ \hfil\box0 \kern-\hsize
+ % \hsize has to be shortened this way:
+ \kern\leftskip
+ % Intentionally do not respect \rightskip, since we need the space.
+ }%
+ %
+ % Allow all lines to be underfull without complaint:
+ \tolerance=10000 \hbadness=10000
+ \exdentamount=\defbodyindent
+ {%
+ % defun fonts. We use typewriter by default (used to be bold) because:
+ % . we're printing identifiers, they should be in tt in principle.
+ % . in languages with many accents, such as Czech or French, it's
+ % common to leave accents off identifiers. The result looks ok in
+ % tt, but exceedingly strange in rm.
+ % . we don't want -- and --- to be treated as ligatures.
+ % . this still does not fix the ?` and !` ligatures, but so far no
+ % one has made identifiers using them :).
+ \df \tt
+ \def\temp{#2}% return value type
+ \ifx\temp\empty\else \tclose{\temp} \fi
+ #3% output function name
+ }%
+ {\rm\enskip}% hskip 0.5 em of \tenrm
+ %
+ \boldbrax
+ % arguments will be output next, if any.
+}
+
+% Print arguments in slanted roman (not ttsl), inconsistently with using
+% tt for the name. This is because literal text is sometimes needed in
+% the argument list (groff manual), and ttsl and tt are not very
+% distinguishable. Prevent hyphenation at `-' chars.
+%
+\def\defunargs#1{%
+ % use sl by default (not ttsl),
+ % tt for the names.
+ \df \sl \hyphenchar\font=0
+ %
+ % On the other hand, if an argument has two dashes (for instance), we
+ % want a way to get ttsl. Let's try @var for that.
+ \let\var=\ttslanted
+ #1%
+ \sl\hyphenchar\font=45
+}
+
+% We want ()&[] to print specially on the defun line.
+%
+\def\activeparens{%
+ \catcode`\(=\active \catcode`\)=\active
+ \catcode`\[=\active \catcode`\]=\active
+ \catcode`\&=\active
+}
+
+% Make control sequences which act like normal parenthesis chars.
+\let\lparen = ( \let\rparen = )
+
+% Be sure that we always have a definition for `(', etc. For example,
+% if the fn name has parens in it, \boldbrax will not be in effect yet,
+% so TeX would otherwise complain about undefined control sequence.
+{
+ \activeparens
+ \global\let(=\lparen \global\let)=\rparen
+ \global\let[=\lbrack \global\let]=\rbrack
+ \global\let& = \&
+
+ \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb}
+ \gdef\magicamp{\let&=\amprm}
+}
+
+\newcount\parencount
+
+% If we encounter &foo, then turn on ()-hacking afterwards
+\newif\ifampseen
+\def\amprm#1 {\ampseentrue{\bf\ }}
+
+\def\parenfont{%
+ \ifampseen
+ % At the first level, print parens in roman,
+ % otherwise use the default font.
+ \ifnum \parencount=1 \rm \fi
+ \else
+ % The \sf parens (in \boldbrax) actually are a little bolder than
+ % the contained text. This is especially needed for [ and ] .
+ \sf
+ \fi
+}
+\def\infirstlevel#1{%
+ \ifampseen
+ \ifnum\parencount=1
+ #1%
+ \fi
+ \fi
+}
+\def\bfafterword#1 {#1 \bf}
+
+\def\opnr{%
+ \global\advance\parencount by 1
+ {\parenfont(}%
+ \infirstlevel \bfafterword
+}
+\def\clnr{%
+ {\parenfont)}%
+ \infirstlevel \sl
+ \global\advance\parencount by -1
+}
+
+\newcount\brackcount
+\def\lbrb{%
+ \global\advance\brackcount by 1
+ {\bf[}%
+}
+\def\rbrb{%
+ {\bf]}%
+ \global\advance\brackcount by -1
+}
+
+\def\checkparencounts{%
+ \ifnum\parencount=0 \else \badparencount \fi
+ \ifnum\brackcount=0 \else \badbrackcount \fi
+}
+\def\badparencount{%
+ \errmessage{Unbalanced parentheses in @def}%
+ \global\parencount=0
+}
+\def\badbrackcount{%
+ \errmessage{Unbalanced square braces in @def}%
+ \global\brackcount=0
+}
+
+
+\message{macros,}
+% @macro.
+
+% To do this right we need a feature of e-TeX, \scantokens,
+% which we arrange to emulate with a temporary file in ordinary TeX.
+\ifx\eTeXversion\undefined
+ \newwrite\macscribble
+ \def\scantokens#1{%
+ \toks0={#1}%
+ \immediate\openout\macscribble=\jobname.tmp
+ \immediate\write\macscribble{\the\toks0}%
+ \immediate\closeout\macscribble
+ \input \jobname.tmp
+ }
+\fi
+
+\def\scanmacro#1{%
+ \begingroup
+ \newlinechar`\^^M
+ \let\xeatspaces\eatspaces
+ % Undo catcode changes of \startcontents and \doprintindex
+ % When called from @insertcopying or (short)caption, we need active
+ % backslash to get it printed correctly. Previously, we had
+ % \catcode`\\=\other instead. We'll see whether a problem appears
+ % with macro expansion. --kasal, 19aug04
+ \catcode`\@=0 \catcode`\\=\active \escapechar=`\@
+ % ... and \example
+ \spaceisspace
+ %
+ % Append \endinput to make sure that TeX does not see the ending newline.
+ % I've verified that it is necessary both for e-TeX and for ordinary TeX
+ % --kasal, 29nov03
+ \scantokens{#1\endinput}%
+ \endgroup
+}
+
+\def\scanexp#1{%
+ \edef\temp{\noexpand\scanmacro{#1}}%
+ \temp
+}
+
+\newcount\paramno % Count of parameters
+\newtoks\macname % Macro name
+\newif\ifrecursive % Is it recursive?
+
+% List of all defined macros in the form
+% \definedummyword\macro1\definedummyword\macro2...
+% Currently is also contains all @aliases; the list can be split
+% if there is a need.
+\def\macrolist{}
+
+% Add the macro to \macrolist
+\def\addtomacrolist#1{\expandafter \addtomacrolistxxx \csname#1\endcsname}
+\def\addtomacrolistxxx#1{%
+ \toks0 = \expandafter{\macrolist\definedummyword#1}%
+ \xdef\macrolist{\the\toks0}%
+}
+
+% Utility routines.
+% This does \let #1 = #2, with \csnames; that is,
+% \let \csname#1\endcsname = \csname#2\endcsname
+% (except of course we have to play expansion games).
+%
+\def\cslet#1#2{%
+ \expandafter\let
+ \csname#1\expandafter\endcsname
+ \csname#2\endcsname
+}
+
+% Trim leading and trailing spaces off a string.
+% Concepts from aro-bend problem 15 (see CTAN).
+{\catcode`\@=11
+\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }}
+\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@}
+\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @}
+\def\unbrace#1{#1}
+\unbrace{\gdef\trim@@@ #1 } #2@{#1}
+}
+
+% Trim a single trailing ^^M off a string.
+{\catcode`\^^M=\other \catcode`\Q=3%
+\gdef\eatcr #1{\eatcra #1Q^^MQ}%
+\gdef\eatcra#1^^MQ{\eatcrb#1Q}%
+\gdef\eatcrb#1Q#2Q{#1}%
+}
+
+% Macro bodies are absorbed as an argument in a context where
+% all characters are catcode 10, 11 or 12, except \ which is active
+% (as in normal texinfo). It is necessary to change the definition of \.
+
+% It's necessary to have hard CRs when the macro is executed. This is
+% done by making ^^M (\endlinechar) catcode 12 when reading the macro
+% body, and then making it the \newlinechar in \scanmacro.
+
+\def\scanctxt{%
+ \catcode`\"=\other
+ \catcode`\+=\other
+ \catcode`\<=\other
+ \catcode`\>=\other
+ \catcode`\@=\other
+ \catcode`\^=\other
+ \catcode`\_=\other
+ \catcode`\|=\other
+ \catcode`\~=\other
+}
+
+\def\scanargctxt{%
+ \scanctxt
+ \catcode`\\=\other
+ \catcode`\^^M=\other
+}
+
+\def\macrobodyctxt{%
+ \scanctxt
+ \catcode`\{=\other
+ \catcode`\}=\other
+ \catcode`\^^M=\other
+ \usembodybackslash
+}
+
+\def\macroargctxt{%
+ \scanctxt
+ \catcode`\\=\other
+}
+
+% \mbodybackslash is the definition of \ in @macro bodies.
+% It maps \foo\ => \csname macarg.foo\endcsname => #N
+% where N is the macro parameter number.
+% We define \csname macarg.\endcsname to be \realbackslash, so
+% \\ in macro replacement text gets you a backslash.
+
+{\catcode`@=0 @catcode`@\=@active
+ @gdef@usembodybackslash{@let\=@mbodybackslash}
+ @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname}
+}
+\expandafter\def\csname macarg.\endcsname{\realbackslash}
+
+\def\macro{\recursivefalse\parsearg\macroxxx}
+\def\rmacro{\recursivetrue\parsearg\macroxxx}
+
+\def\macroxxx#1{%
+ \getargs{#1}% now \macname is the macname and \argl the arglist
+ \ifx\argl\empty % no arguments
+ \paramno=0%
+ \else
+ \expandafter\parsemargdef \argl;%
+ \fi
+ \if1\csname ismacro.\the\macname\endcsname
+ \message{Warning: redefining \the\macname}%
+ \else
+ \expandafter\ifx\csname \the\macname\endcsname \relax
+ \else \errmessage{Macro name \the\macname\space already defined}\fi
+ \global\cslet{macsave.\the\macname}{\the\macname}%
+ \global\expandafter\let\csname ismacro.\the\macname\endcsname=1%
+ \addtomacrolist{\the\macname}%
+ \fi
+ \begingroup \macrobodyctxt
+ \ifrecursive \expandafter\parsermacbody
+ \else \expandafter\parsemacbody
+ \fi}
+
+\parseargdef\unmacro{%
+ \if1\csname ismacro.#1\endcsname
+ \global\cslet{#1}{macsave.#1}%
+ \global\expandafter\let \csname ismacro.#1\endcsname=0%
+ % Remove the macro name from \macrolist:
+ \begingroup
+ \expandafter\let\csname#1\endcsname \relax
+ \let\definedummyword\unmacrodo
+ \xdef\macrolist{\macrolist}%
+ \endgroup
+ \else
+ \errmessage{Macro #1 not defined}%
+ \fi
+}
+
+% Called by \do from \dounmacro on each macro. The idea is to omit any
+% macro definitions that have been changed to \relax.
+%
+\def\unmacrodo#1{%
+ \ifx #1\relax
+ % remove this
+ \else
+ \noexpand\definedummyword \noexpand#1%
+ \fi
+}
+
+% This makes use of the obscure feature that if the last token of a
+% <parameter list> is #, then the preceding argument is delimited by
+% an opening brace, and that opening brace is not consumed.
+\def\getargs#1{\getargsxxx#1{}}
+\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs}
+\def\getmacname #1 #2\relax{\macname={#1}}
+\def\getmacargs#1{\def\argl{#1}}
+
+% Parse the optional {params} list. Set up \paramno and \paramlist
+% so \defmacro knows what to do. Define \macarg.blah for each blah
+% in the params list, to be ##N where N is the position in that list.
+% That gets used by \mbodybackslash (above).
+
+% We need to get `macro parameter char #' into several definitions.
+% The technique used is stolen from LaTeX: let \hash be something
+% unexpandable, insert that wherever you need a #, and then redefine
+% it to # just before using the token list produced.
+%
+% The same technique is used to protect \eatspaces till just before
+% the macro is used.
+
+\def\parsemargdef#1;{\paramno=0\def\paramlist{}%
+ \let\hash\relax\let\xeatspaces\relax\parsemargdefxxx#1,;,}
+\def\parsemargdefxxx#1,{%
+ \if#1;\let\next=\relax
+ \else \let\next=\parsemargdefxxx
+ \advance\paramno by 1%
+ \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname
+ {\xeatspaces{\hash\the\paramno}}%
+ \edef\paramlist{\paramlist\hash\the\paramno,}%
+ \fi\next}
+
+% These two commands read recursive and nonrecursive macro bodies.
+% (They're different since rec and nonrec macros end differently.)
+
+\long\def\parsemacbody#1@end macro%
+{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%
+\long\def\parsermacbody#1@end rmacro%
+{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%
+
+% This defines the macro itself. There are six cases: recursive and
+% nonrecursive macros of zero, one, and many arguments.
+% Much magic with \expandafter here.
+% \xdef is used so that macro definitions will survive the file
+% they're defined in; @include reads the file inside a group.
+\def\defmacro{%
+ \let\hash=##% convert placeholders to macro parameter chars
+ \ifrecursive
+ \ifcase\paramno
+ % 0
+ \expandafter\xdef\csname\the\macname\endcsname{%
+ \noexpand\scanmacro{\temp}}%
+ \or % 1
+ \expandafter\xdef\csname\the\macname\endcsname{%
+ \bgroup\noexpand\macroargctxt
+ \noexpand\braceorline
+ \expandafter\noexpand\csname\the\macname xxx\endcsname}%
+ \expandafter\xdef\csname\the\macname xxx\endcsname##1{%
+ \egroup\noexpand\scanmacro{\temp}}%
+ \else % many
+ \expandafter\xdef\csname\the\macname\endcsname{%
+ \bgroup\noexpand\macroargctxt
+ \noexpand\csname\the\macname xx\endcsname}%
+ \expandafter\xdef\csname\the\macname xx\endcsname##1{%
+ \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
+ \expandafter\expandafter
+ \expandafter\xdef
+ \expandafter\expandafter
+ \csname\the\macname xxx\endcsname
+ \paramlist{\egroup\noexpand\scanmacro{\temp}}%
+ \fi
+ \else
+ \ifcase\paramno
+ % 0
+ \expandafter\xdef\csname\the\macname\endcsname{%
+ \noexpand\norecurse{\the\macname}%
+ \noexpand\scanmacro{\temp}\egroup}%
+ \or % 1
+ \expandafter\xdef\csname\the\macname\endcsname{%
+ \bgroup\noexpand\macroargctxt
+ \noexpand\braceorline
+ \expandafter\noexpand\csname\the\macname xxx\endcsname}%
+ \expandafter\xdef\csname\the\macname xxx\endcsname##1{%
+ \egroup
+ \noexpand\norecurse{\the\macname}%
+ \noexpand\scanmacro{\temp}\egroup}%
+ \else % many
+ \expandafter\xdef\csname\the\macname\endcsname{%
+ \bgroup\noexpand\macroargctxt
+ \expandafter\noexpand\csname\the\macname xx\endcsname}%
+ \expandafter\xdef\csname\the\macname xx\endcsname##1{%
+ \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
+ \expandafter\expandafter
+ \expandafter\xdef
+ \expandafter\expandafter
+ \csname\the\macname xxx\endcsname
+ \paramlist{%
+ \egroup
+ \noexpand\norecurse{\the\macname}%
+ \noexpand\scanmacro{\temp}\egroup}%
+ \fi
+ \fi}
+
+\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}}
+
+% \braceorline decides whether the next nonwhitespace character is a
+% {. If so it reads up to the closing }, if not, it reads the whole
+% line. Whatever was read is then fed to the next control sequence
+% as an argument (by \parsebrace or \parsearg)
+\def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx}
+\def\braceorlinexxx{%
+ \ifx\nchar\bgroup\else
+ \expandafter\parsearg
+ \fi \macnamexxx}
+
+
+% @alias.
+% We need some trickery to remove the optional spaces around the equal
+% sign. Just make them active and then expand them all to nothing.
+\def\alias{\parseargusing\obeyspaces\aliasxxx}
+\def\aliasxxx #1{\aliasyyy#1\relax}
+\def\aliasyyy #1=#2\relax{%
+ {%
+ \expandafter\let\obeyedspace=\empty
+ \addtomacrolist{#1}%
+ \xdef\next{\global\let\makecsname{#1}=\makecsname{#2}}%
+ }%
+ \next
+}
+
+
+\message{cross references,}
+
+\newwrite\auxfile
+\newif\ifhavexrefs % True if xref values are known.
+\newif\ifwarnedxrefs % True if we warned once that they aren't known.
+
+% @inforef is relatively simple.
+\def\inforef #1{\inforefzzz #1,,,,**}
+\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}},
+ node \samp{\ignorespaces#1{}}}
+
+% @node's only job in TeX is to define \lastnode, which is used in
+% cross-references. The @node line might or might not have commas, and
+% might or might not have spaces before the first comma, like:
+% @node foo , bar , ...
+% We don't want such trailing spaces in the node name.
+%
+\parseargdef\node{\checkenv{}\donode #1 ,\finishnodeparse}
+%
+% also remove a trailing comma, in case of something like this:
+% @node Help-Cross, , , Cross-refs
+\def\donode#1 ,#2\finishnodeparse{\dodonode #1,\finishnodeparse}
+\def\dodonode#1,#2\finishnodeparse{\gdef\lastnode{#1}}
+
+\let\nwnode=\node
+\let\lastnode=\empty
+
+% Write a cross-reference definition for the current node. #1 is the
+% type (Ynumbered, Yappendix, Ynothing).
+%
+\def\donoderef#1{%
+ \ifx\lastnode\empty\else
+ \setref{\lastnode}{#1}%
+ \global\let\lastnode=\empty
+ \fi
+}
+
+% @anchor{NAME} -- define xref target at arbitrary point.
+%
+\newcount\savesfregister
+%
+\def\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi}
+\def\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi}
+\def\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces}
+
+% \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an
+% anchor), which consists of three parts:
+% 1) NAME-title - the current sectioning name taken from \thissection,
+% or the anchor name.
+% 2) NAME-snt - section number and type, passed as the SNT arg, or
+% empty for anchors.
+% 3) NAME-pg - the page number.
+%
+% This is called from \donoderef, \anchor, and \dofloat. In the case of
+% floats, there is an additional part, which is not written here:
+% 4) NAME-lof - the text as it should appear in a @listoffloats.
+%
+\def\setref#1#2{%
+ \pdfmkdest{#1}%
+ \iflinks
+ {%
+ \atdummies % preserve commands, but don't expand them
+ \edef\writexrdef##1##2{%
+ \write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef
+ ##1}{##2}}% these are parameters of \writexrdef
+ }%
+ \toks0 = \expandafter{\thissection}%
+ \immediate \writexrdef{title}{\the\toks0 }%
+ \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc.
+ \safewhatsit{\writexrdef{pg}{\folio}}% will be written later, during \shipout
+ }%
+ \fi
+}
+
+% @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is
+% the node name, #2 the name of the Info cross-reference, #3 the printed
+% node name, #4 the name of the Info file, #5 the name of the printed
+% manual. All but the node name can be omitted.
+%
+\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]}
+\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]}
+\def\ref#1{\xrefX[#1,,,,,,,]}
+\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup
+ \unsepspaces
+ \def\printedmanual{\ignorespaces #5}%
+ \def\printedrefname{\ignorespaces #3}%
+ \setbox1=\hbox{\printedmanual\unskip}%
+ \setbox0=\hbox{\printedrefname\unskip}%
+ \ifdim \wd0 = 0pt
+ % No printed node name was explicitly given.
+ \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax
+ % Use the node name inside the square brackets.
+ \def\printedrefname{\ignorespaces #1}%
+ \else
+ % Use the actual chapter/section title appear inside
+ % the square brackets. Use the real section title if we have it.
+ \ifdim \wd1 > 0pt
+ % It is in another manual, so we don't have it.
+ \def\printedrefname{\ignorespaces #1}%
+ \else
+ \ifhavexrefs
+ % We know the real title if we have the xref values.
+ \def\printedrefname{\refx{#1-title}{}}%
+ \else
+ % Otherwise just copy the Info node name.
+ \def\printedrefname{\ignorespaces #1}%
+ \fi%
+ \fi
+ \fi
+ \fi
+ %
+ % Make link in pdf output.
+ \ifpdf
+ \leavevmode
+ \getfilename{#4}%
+ {\indexnofonts
+ \turnoffactive
+ % See comments at \activebackslashdouble.
+ {\activebackslashdouble \xdef\pdfxrefdest{#1}%
+ \backslashparens\pdfxrefdest}%
+ %
+ \ifnum\filenamelength>0
+ \startlink attr{/Border [0 0 0]}%
+ goto file{\the\filename.pdf} name{\pdfxrefdest}%
+ \else
+ \startlink attr{/Border [0 0 0]}%
+ goto name{\pdfmkpgn{\pdfxrefdest}}%
+ \fi
+ }%
+ \linkcolor
+ \fi
+ %
+ % Float references are printed completely differently: "Figure 1.2"
+ % instead of "[somenode], p.3". We distinguish them by the
+ % LABEL-title being set to a magic string.
+ {%
+ % Have to otherify everything special to allow the \csname to
+ % include an _ in the xref name, etc.
+ \indexnofonts
+ \turnoffactive
+ \expandafter\global\expandafter\let\expandafter\Xthisreftitle
+ \csname XR#1-title\endcsname
+ }%
+ \iffloat\Xthisreftitle
+ % If the user specified the print name (third arg) to the ref,
+ % print it instead of our usual "Figure 1.2".
+ \ifdim\wd0 = 0pt
+ \refx{#1-snt}{}%
+ \else
+ \printedrefname
+ \fi
+ %
+ % if the user also gave the printed manual name (fifth arg), append
+ % "in MANUALNAME".
+ \ifdim \wd1 > 0pt
+ \space \putwordin{} \cite{\printedmanual}%
+ \fi
+ \else
+ % node/anchor (non-float) references.
+ %
+ % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not
+ % insert empty discretionaries after hyphens, which means that it will
+ % not find a line break at a hyphen in a node names. Since some manuals
+ % are best written with fairly long node names, containing hyphens, this
+ % is a loss. Therefore, we give the text of the node name again, so it
+ % is as if TeX is seeing it for the first time.
+ \ifdim \wd1 > 0pt
+ \putwordsection{} ``\printedrefname'' \putwordin{} \cite{\printedmanual}%
+ \else
+ % _ (for example) has to be the character _ for the purposes of the
+ % control sequence corresponding to the node, but it has to expand
+ % into the usual \leavevmode...\vrule stuff for purposes of
+ % printing. So we \turnoffactive for the \refx-snt, back on for the
+ % printing, back off for the \refx-pg.
+ {\turnoffactive
+ % Only output a following space if the -snt ref is nonempty; for
+ % @unnumbered and @anchor, it won't be.
+ \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}%
+ \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi
+ }%
+ % output the `[mynode]' via a macro so it can be overridden.
+ \xrefprintnodename\printedrefname
+ %
+ % But we always want a comma and a space:
+ ,\space
+ %
+ % output the `page 3'.
+ \turnoffactive \putwordpage\tie\refx{#1-pg}{}%
+ \fi
+ \fi
+ \endlink
+\endgroup}
+
+% This macro is called from \xrefX for the `[nodename]' part of xref
+% output. It's a separate macro only so it can be changed more easily,
+% since square brackets don't work well in some documents. Particularly
+% one that Bob is working on :).
+%
+\def\xrefprintnodename#1{[#1]}
+
+% Things referred to by \setref.
+%
+\def\Ynothing{}
+\def\Yomitfromtoc{}
+\def\Ynumbered{%
+ \ifnum\secno=0
+ \putwordChapter@tie \the\chapno
+ \else \ifnum\subsecno=0
+ \putwordSection@tie \the\chapno.\the\secno
+ \else \ifnum\subsubsecno=0
+ \putwordSection@tie \the\chapno.\the\secno.\the\subsecno
+ \else
+ \putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno
+ \fi\fi\fi
+}
+\def\Yappendix{%
+ \ifnum\secno=0
+ \putwordAppendix@tie @char\the\appendixno{}%
+ \else \ifnum\subsecno=0
+ \putwordSection@tie @char\the\appendixno.\the\secno
+ \else \ifnum\subsubsecno=0
+ \putwordSection@tie @char\the\appendixno.\the\secno.\the\subsecno
+ \else
+ \putwordSection@tie
+ @char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno
+ \fi\fi\fi
+}
+
+% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME.
+% If its value is nonempty, SUFFIX is output afterward.
+%
+\def\refx#1#2{%
+ {%
+ \indexnofonts
+ \otherbackslash
+ \expandafter\global\expandafter\let\expandafter\thisrefX
+ \csname XR#1\endcsname
+ }%
+ \ifx\thisrefX\relax
+ % If not defined, say something at least.
+ \angleleft un\-de\-fined\angleright
+ \iflinks
+ \ifhavexrefs
+ \message{\linenumber Undefined cross reference `#1'.}%
+ \else
+ \ifwarnedxrefs\else
+ \global\warnedxrefstrue
+ \message{Cross reference values unknown; you must run TeX again.}%
+ \fi
+ \fi
+ \fi
+ \else
+ % It's defined, so just use it.
+ \thisrefX
+ \fi
+ #2% Output the suffix in any case.
+}
+
+% This is the macro invoked by entries in the aux file. Usually it's
+% just a \def (we prepend XR to the control sequence name to avoid
+% collisions). But if this is a float type, we have more work to do.
+%
+\def\xrdef#1#2{%
+ {% The node name might contain 8-bit characters, which in our current
+ % implementation are changed to commands like @'e. Don't let these
+ % mess up the control sequence name.
+ \indexnofonts
+ \turnoffactive
+ \xdef\safexrefname{#1}%
+ }%
+ %
+ \expandafter\gdef\csname XR\safexrefname\endcsname{#2}% remember this xref
+ %
+ % Was that xref control sequence that we just defined for a float?
+ \expandafter\iffloat\csname XR\safexrefname\endcsname
+ % it was a float, and we have the (safe) float type in \iffloattype.
+ \expandafter\let\expandafter\floatlist
+ \csname floatlist\iffloattype\endcsname
+ %
+ % Is this the first time we've seen this float type?
+ \expandafter\ifx\floatlist\relax
+ \toks0 = {\do}% yes, so just \do
+ \else
+ % had it before, so preserve previous elements in list.
+ \toks0 = \expandafter{\floatlist\do}%
+ \fi
+ %
+ % Remember this xref in the control sequence \floatlistFLOATTYPE,
+ % for later use in \listoffloats.
+ \expandafter\xdef\csname floatlist\iffloattype\endcsname{\the\toks0
+ {\safexrefname}}%
+ \fi
+}
+
+% Read the last existing aux file, if any. No error if none exists.
+%
+\def\tryauxfile{%
+ \openin 1 \jobname.aux
+ \ifeof 1 \else
+ \readdatafile{aux}%
+ \global\havexrefstrue
+ \fi
+ \closein 1
+}
+
+\def\setupdatafile{%
+ \catcode`\^^@=\other
+ \catcode`\^^A=\other
+ \catcode`\^^B=\other
+ \catcode`\^^C=\other
+ \catcode`\^^D=\other
+ \catcode`\^^E=\other
+ \catcode`\^^F=\other
+ \catcode`\^^G=\other
+ \catcode`\^^H=\other
+ \catcode`\^^K=\other
+ \catcode`\^^L=\other
+ \catcode`\^^N=\other
+ \catcode`\^^P=\other
+ \catcode`\^^Q=\other
+ \catcode`\^^R=\other
+ \catcode`\^^S=\other
+ \catcode`\^^T=\other
+ \catcode`\^^U=\other
+ \catcode`\^^V=\other
+ \catcode`\^^W=\other
+ \catcode`\^^X=\other
+ \catcode`\^^Z=\other
+ \catcode`\^^[=\other
+ \catcode`\^^\=\other
+ \catcode`\^^]=\other
+ \catcode`\^^^=\other
+ \catcode`\^^_=\other
+ % It was suggested to set the catcode of ^ to 7, which would allow ^^e4 etc.
+ % in xref tags, i.e., node names. But since ^^e4 notation isn't
+ % supported in the main text, it doesn't seem desirable. Furthermore,
+ % that is not enough: for node names that actually contain a ^
+ % character, we would end up writing a line like this: 'xrdef {'hat
+ % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first
+ % argument, and \hat is not an expandable control sequence. It could
+ % all be worked out, but why? Either we support ^^ or we don't.
+ %
+ % The other change necessary for this was to define \auxhat:
+ % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter
+ % and then to call \auxhat in \setq.
+ %
+ \catcode`\^=\other
+ %
+ % Special characters. Should be turned off anyway, but...
+ \catcode`\~=\other
+ \catcode`\[=\other
+ \catcode`\]=\other
+ \catcode`\"=\other
+ \catcode`\_=\other
+ \catcode`\|=\other
+ \catcode`\<=\other
+ \catcode`\>=\other
+ \catcode`\$=\other
+ \catcode`\#=\other
+ \catcode`\&=\other
+ \catcode`\%=\other
+ \catcode`+=\other % avoid \+ for paranoia even though we've turned it off
+ %
+ % This is to support \ in node names and titles, since the \
+ % characters end up in a \csname. It's easier than
+ % leaving it active and making its active definition an actual \
+ % character. What I don't understand is why it works in the *value*
+ % of the xrdef. Seems like it should be a catcode12 \, and that
+ % should not typeset properly. But it works, so I'm moving on for
+ % now. --karl, 15jan04.
+ \catcode`\\=\other
+ %
+ % Make the characters 128-255 be printing characters.
+ {%
+ \count1=128
+ \def\loop{%
+ \catcode\count1=\other
+ \advance\count1 by 1
+ \ifnum \count1<256 \loop \fi
+ }%
+ }%
+ %
+ % @ is our escape character in .aux files, and we need braces.
+ \catcode`\{=1
+ \catcode`\}=2
+ \catcode`\@=0
+}
+
+\def\readdatafile#1{%
+\begingroup
+ \setupdatafile
+ \input\jobname.#1
+\endgroup}
+
+
+\message{insertions,}
+% including footnotes.
+
+\newcount \footnoteno
+
+% The trailing space in the following definition for supereject is
+% vital for proper filling; pages come out unaligned when you do a
+% pagealignmacro call if that space before the closing brace is
+% removed. (Generally, numeric constants should always be followed by a
+% space to prevent strange expansion errors.)
+\def\supereject{\par\penalty -20000\footnoteno =0 }
+
+% @footnotestyle is meaningful for info output only.
+\let\footnotestyle=\comment
+
+{\catcode `\@=11
+%
+% Auto-number footnotes. Otherwise like plain.
+\gdef\footnote{%
+ \let\indent=\ptexindent
+ \let\noindent=\ptexnoindent
+ \global\advance\footnoteno by \@ne
+ \edef\thisfootno{$^{\the\footnoteno}$}%
+ %
+ % In case the footnote comes at the end of a sentence, preserve the
+ % extra spacing after we do the footnote number.
+ \let\@sf\empty
+ \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\ptexslash\fi
+ %
+ % Remove inadvertent blank space before typesetting the footnote number.
+ \unskip
+ \thisfootno\@sf
+ \dofootnote
+}%
+
+% Don't bother with the trickery in plain.tex to not require the
+% footnote text as a parameter. Our footnotes don't need to be so general.
+%
+% Oh yes, they do; otherwise, @ifset (and anything else that uses
+% \parseargline) fails inside footnotes because the tokens are fixed when
+% the footnote is read. --karl, 16nov96.
+%
+\gdef\dofootnote{%
+ \insert\footins\bgroup
+ % We want to typeset this text as a normal paragraph, even if the
+ % footnote reference occurs in (for example) a display environment.
+ % So reset some parameters.
+ \hsize=\pagewidth
+ \interlinepenalty\interfootnotelinepenalty
+ \splittopskip\ht\strutbox % top baseline for broken footnotes
+ \splitmaxdepth\dp\strutbox
+ \floatingpenalty\@MM
+ \leftskip\z@skip
+ \rightskip\z@skip
+ \spaceskip\z@skip
+ \xspaceskip\z@skip
+ \parindent\defaultparindent
+ %
+ \smallfonts \rm
+ %
+ % Because we use hanging indentation in footnotes, a @noindent appears
+ % to exdent this text, so make it be a no-op. makeinfo does not use
+ % hanging indentation so @noindent can still be needed within footnote
+ % text after an @example or the like (not that this is good style).
+ \let\noindent = \relax
+ %
+ % Hang the footnote text off the number. Use \everypar in case the
+ % footnote extends for more than one paragraph.
+ \everypar = {\hang}%
+ \textindent{\thisfootno}%
+ %
+ % Don't crash into the line above the footnote text. Since this
+ % expands into a box, it must come within the paragraph, lest it
+ % provide a place where TeX can split the footnote.
+ \footstrut
+ \futurelet\next\fo@t
+}
+}%end \catcode `\@=11
+
+% In case a @footnote appears in a vbox, save the footnote text and create
+% the real \insert just after the vbox finished. Otherwise, the insertion
+% would be lost.
+% Similarily, if a @footnote appears inside an alignment, save the footnote
+% text to a box and make the \insert when a row of the table is finished.
+% And the same can be done for other insert classes. --kasal, 16nov03.
+
+% Replace the \insert primitive by a cheating macro.
+% Deeper inside, just make sure that the saved insertions are not spilled
+% out prematurely.
+%
+\def\startsavinginserts{%
+ \ifx \insert\ptexinsert
+ \let\insert\saveinsert
+ \else
+ \let\checkinserts\relax
+ \fi
+}
+
+% This \insert replacement works for both \insert\footins{foo} and
+% \insert\footins\bgroup foo\egroup, but it doesn't work for \insert27{foo}.
+%
+\def\saveinsert#1{%
+ \edef\next{\noexpand\savetobox \makeSAVEname#1}%
+ \afterassignment\next
+ % swallow the left brace
+ \let\temp =
+}
+\def\makeSAVEname#1{\makecsname{SAVE\expandafter\gobble\string#1}}
+\def\savetobox#1{\global\setbox#1 = \vbox\bgroup \unvbox#1}
+
+\def\checksaveins#1{\ifvoid#1\else \placesaveins#1\fi}
+
+\def\placesaveins#1{%
+ \ptexinsert \csname\expandafter\gobblesave\string#1\endcsname
+ {\box#1}%
+}
+
+% eat @SAVE -- beware, all of them have catcode \other:
+{
+ \def\dospecials{\do S\do A\do V\do E} \uncatcodespecials % ;-)
+ \gdef\gobblesave @SAVE{}
+}
+
+% initialization:
+\def\newsaveins #1{%
+ \edef\next{\noexpand\newsaveinsX \makeSAVEname#1}%
+ \next
+}
+\def\newsaveinsX #1{%
+ \csname newbox\endcsname #1%
+ \expandafter\def\expandafter\checkinserts\expandafter{\checkinserts
+ \checksaveins #1}%
+}
+
+% initialize:
+\let\checkinserts\empty
+\newsaveins\footins
+\newsaveins\margin
+
+
+% @image. We use the macros from epsf.tex to support this.
+% If epsf.tex is not installed and @image is used, we complain.
+%
+% Check for and read epsf.tex up front. If we read it only at @image
+% time, we might be inside a group, and then its definitions would get
+% undone and the next image would fail.
+\openin 1 = epsf.tex
+\ifeof 1 \else
+ % Do not bother showing banner with epsf.tex v2.7k (available in
+ % doc/epsf.tex and on ctan).
+ \def\epsfannounce{\toks0 = }%
+ \input epsf.tex
+\fi
+\closein 1
+%
+% We will only complain once about lack of epsf.tex.
+\newif\ifwarnednoepsf
+\newhelp\noepsfhelp{epsf.tex must be installed for images to
+ work. It is also included in the Texinfo distribution, or you can get
+ it from ftp://tug.org/tex/epsf.tex.}
+%
+\def\image#1{%
+ \ifx\epsfbox\undefined
+ \ifwarnednoepsf \else
+ \errhelp = \noepsfhelp
+ \errmessage{epsf.tex not found, images will be ignored}%
+ \global\warnednoepsftrue
+ \fi
+ \else
+ \imagexxx #1,,,,,\finish
+ \fi
+}
+%
+% Arguments to @image:
+% #1 is (mandatory) image filename; we tack on .eps extension.
+% #2 is (optional) width, #3 is (optional) height.
+% #4 is (ignored optional) html alt text.
+% #5 is (ignored optional) extension.
+% #6 is just the usual extra ignored arg for parsing this stuff.
+\newif\ifimagevmode
+\def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup
+ \catcode`\^^M = 5 % in case we're inside an example
+ \normalturnoffactive % allow _ et al. in names
+ % If the image is by itself, center it.
+ \ifvmode
+ \imagevmodetrue
+ \nobreak\bigskip
+ % Usually we'll have text after the image which will insert
+ % \parskip glue, so insert it here too to equalize the space
+ % above and below.
+ \nobreak\vskip\parskip
+ \nobreak
+ \line\bgroup
+ \fi
+ %
+ % Output the image.
+ \ifpdf
+ \dopdfimage{#1}{#2}{#3}%
+ \else
+ % \epsfbox itself resets \epsf?size at each figure.
+ \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi
+ \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi
+ \epsfbox{#1.eps}%
+ \fi
+ %
+ \ifimagevmode \egroup \bigbreak \fi % space after the image
+\endgroup}
+
+
+% @float FLOATTYPE,LABEL,LOC ... @end float for displayed figures, tables,
+% etc. We don't actually implement floating yet, we always include the
+% float "here". But it seemed the best name for the future.
+%
+\envparseargdef\float{\eatcommaspace\eatcommaspace\dofloat#1, , ,\finish}
+
+% There may be a space before second and/or third parameter; delete it.
+\def\eatcommaspace#1, {#1,}
+
+% #1 is the optional FLOATTYPE, the text label for this float, typically
+% "Figure", "Table", "Example", etc. Can't contain commas. If omitted,
+% this float will not be numbered and cannot be referred to.
+%
+% #2 is the optional xref label. Also must be present for the float to
+% be referable.
+%
+% #3 is the optional positioning argument; for now, it is ignored. It
+% will somehow specify the positions allowed to float to (here, top, bottom).
+%
+% We keep a separate counter for each FLOATTYPE, which we reset at each
+% chapter-level command.
+\let\resetallfloatnos=\empty
+%
+\def\dofloat#1,#2,#3,#4\finish{%
+ \let\thiscaption=\empty
+ \let\thisshortcaption=\empty
+ %
+ % don't lose footnotes inside @float.
+ %
+ % BEWARE: when the floats start float, we have to issue warning whenever an
+ % insert appears inside a float which could possibly float. --kasal, 26may04
+ %
+ \startsavinginserts
+ %
+ % We can't be used inside a paragraph.
+ \par
+ %
+ \vtop\bgroup
+ \def\floattype{#1}%
+ \def\floatlabel{#2}%
+ \def\floatloc{#3}% we do nothing with this yet.
+ %
+ \ifx\floattype\empty
+ \let\safefloattype=\empty
+ \else
+ {%
+ % the floattype might have accents or other special characters,
+ % but we need to use it in a control sequence name.
+ \indexnofonts
+ \turnoffactive
+ \xdef\safefloattype{\floattype}%
+ }%
+ \fi
+ %
+ % If label is given but no type, we handle that as the empty type.
+ \ifx\floatlabel\empty \else
+ % We want each FLOATTYPE to be numbered separately (Figure 1,
+ % Table 1, Figure 2, ...). (And if no label, no number.)
+ %
+ \expandafter\getfloatno\csname\safefloattype floatno\endcsname
+ \global\advance\floatno by 1
+ %
+ {%
+ % This magic value for \thissection is output by \setref as the
+ % XREFLABEL-title value. \xrefX uses it to distinguish float
+ % labels (which have a completely different output format) from
+ % node and anchor labels. And \xrdef uses it to construct the
+ % lists of floats.
+ %
+ \edef\thissection{\floatmagic=\safefloattype}%
+ \setref{\floatlabel}{Yfloat}%
+ }%
+ \fi
+ %
+ % start with \parskip glue, I guess.
+ \vskip\parskip
+ %
+ % Don't suppress indentation if a float happens to start a section.
+ \restorefirstparagraphindent
+}
+
+% we have these possibilities:
+% @float Foo,lbl & @caption{Cap}: Foo 1.1: Cap
+% @float Foo,lbl & no caption: Foo 1.1
+% @float Foo & @caption{Cap}: Foo: Cap
+% @float Foo & no caption: Foo
+% @float ,lbl & Caption{Cap}: 1.1: Cap
+% @float ,lbl & no caption: 1.1
+% @float & @caption{Cap}: Cap
+% @float & no caption:
+%
+\def\Efloat{%
+ \let\floatident = \empty
+ %
+ % In all cases, if we have a float type, it comes first.
+ \ifx\floattype\empty \else \def\floatident{\floattype}\fi
+ %
+ % If we have an xref label, the number comes next.
+ \ifx\floatlabel\empty \else
+ \ifx\floattype\empty \else % if also had float type, need tie first.
+ \appendtomacro\floatident{\tie}%
+ \fi
+ % the number.
+ \appendtomacro\floatident{\chaplevelprefix\the\floatno}%
+ \fi
+ %
+ % Start the printed caption with what we've constructed in
+ % \floatident, but keep it separate; we need \floatident again.
+ \let\captionline = \floatident
+ %
+ \ifx\thiscaption\empty \else
+ \ifx\floatident\empty \else
+ \appendtomacro\captionline{: }% had ident, so need a colon between
+ \fi
+ %
+ % caption text.
+ \appendtomacro\captionline{\scanexp\thiscaption}%
+ \fi
+ %
+ % If we have anything to print, print it, with space before.
+ % Eventually this needs to become an \insert.
+ \ifx\captionline\empty \else
+ \vskip.5\parskip
+ \captionline
+ %
+ % Space below caption.
+ \vskip\parskip
+ \fi
+ %
+ % If have an xref label, write the list of floats info. Do this
+ % after the caption, to avoid chance of it being a breakpoint.
+ \ifx\floatlabel\empty \else
+ % Write the text that goes in the lof to the aux file as
+ % \floatlabel-lof. Besides \floatident, we include the short
+ % caption if specified, else the full caption if specified, else nothing.
+ {%
+ \atdummies
+ %
+ % since we read the caption text in the macro world, where ^^M
+ % is turned into a normal character, we have to scan it back, so
+ % we don't write the literal three characters "^^M" into the aux file.
+ \scanexp{%
+ \xdef\noexpand\gtemp{%
+ \ifx\thisshortcaption\empty
+ \thiscaption
+ \else
+ \thisshortcaption
+ \fi
+ }%
+ }%
+ \immediate\write\auxfile{@xrdef{\floatlabel-lof}{\floatident
+ \ifx\gtemp\empty \else : \gtemp \fi}}%
+ }%
+ \fi
+ \egroup % end of \vtop
+ %
+ % place the captured inserts
+ %
+ % BEWARE: when the floats start floating, we have to issue warning
+ % whenever an insert appears inside a float which could possibly
+ % float. --kasal, 26may04
+ %
+ \checkinserts
+}
+
+% Append the tokens #2 to the definition of macro #1, not expanding either.
+%
+\def\appendtomacro#1#2{%
+ \expandafter\def\expandafter#1\expandafter{#1#2}%
+}
+
+% @caption, @shortcaption
+%
+\def\caption{\docaption\thiscaption}
+\def\shortcaption{\docaption\thisshortcaption}
+\def\docaption{\checkenv\float \bgroup\scanargctxt\defcaption}
+\def\defcaption#1#2{\egroup \def#1{#2}}
+
+% The parameter is the control sequence identifying the counter we are
+% going to use. Create it if it doesn't exist and assign it to \floatno.
+\def\getfloatno#1{%
+ \ifx#1\relax
+ % Haven't seen this figure type before.
+ \csname newcount\endcsname #1%
+ %
+ % Remember to reset this floatno at the next chap.
+ \expandafter\gdef\expandafter\resetallfloatnos
+ \expandafter{\resetallfloatnos #1=0 }%
+ \fi
+ \let\floatno#1%
+}
+
+% \setref calls this to get the XREFLABEL-snt value. We want an @xref
+% to the FLOATLABEL to expand to "Figure 3.1". We call \setref when we
+% first read the @float command.
+%
+\def\Yfloat{\floattype@tie \chaplevelprefix\the\floatno}%
+
+% Magic string used for the XREFLABEL-title value, so \xrefX can
+% distinguish floats from other xref types.
+\def\floatmagic{!!float!!}
+
+% #1 is the control sequence we are passed; we expand into a conditional
+% which is true if #1 represents a float ref. That is, the magic
+% \thissection value which we \setref above.
+%
+\def\iffloat#1{\expandafter\doiffloat#1==\finish}
+%
+% #1 is (maybe) the \floatmagic string. If so, #2 will be the
+% (safe) float type for this float. We set \iffloattype to #2.
+%
+\def\doiffloat#1=#2=#3\finish{%
+ \def\temp{#1}%
+ \def\iffloattype{#2}%
+ \ifx\temp\floatmagic
+}
+
+% @listoffloats FLOATTYPE - print a list of floats like a table of contents.
+%
+\parseargdef\listoffloats{%
+ \def\floattype{#1}% floattype
+ {%
+ % the floattype might have accents or other special characters,
+ % but we need to use it in a control sequence name.
+ \indexnofonts
+ \turnoffactive
+ \xdef\safefloattype{\floattype}%
+ }%
+ %
+ % \xrdef saves the floats as a \do-list in \floatlistSAFEFLOATTYPE.
+ \expandafter\ifx\csname floatlist\safefloattype\endcsname \relax
+ \ifhavexrefs
+ % if the user said @listoffloats foo but never @float foo.
+ \message{\linenumber No `\safefloattype' floats to list.}%
+ \fi
+ \else
+ \begingroup
+ \leftskip=\tocindent % indent these entries like a toc
+ \let\do=\listoffloatsdo
+ \csname floatlist\safefloattype\endcsname
+ \endgroup
+ \fi
+}
+
+% This is called on each entry in a list of floats. We're passed the
+% xref label, in the form LABEL-title, which is how we save it in the
+% aux file. We strip off the -title and look up \XRLABEL-lof, which
+% has the text we're supposed to typeset here.
+%
+% Figures without xref labels will not be included in the list (since
+% they won't appear in the aux file).
+%
+\def\listoffloatsdo#1{\listoffloatsdoentry#1\finish}
+\def\listoffloatsdoentry#1-title\finish{{%
+ % Can't fully expand XR#1-lof because it can contain anything. Just
+ % pass the control sequence. On the other hand, XR#1-pg is just the
+ % page number, and we want to fully expand that so we can get a link
+ % in pdf output.
+ \toksA = \expandafter{\csname XR#1-lof\endcsname}%
+ %
+ % use the same \entry macro we use to generate the TOC and index.
+ \edef\writeentry{\noexpand\entry{\the\toksA}{\csname XR#1-pg\endcsname}}%
+ \writeentry
+}}
+
+
+\message{localization,}
+
+% @documentlanguage is usually given very early, just after
+% @setfilename. If done too late, it may not override everything
+% properly. Single argument is the language (de) or locale (de_DE)
+% abbreviation. It would be nice if we could set up a hyphenation file.
+%
+{
+ \catcode`\_ = \active
+ \globaldefs=1
+\parseargdef\documentlanguage{\begingroup
+ \let_=\normalunderscore % normal _ character for filenames
+ \tex % read txi-??.tex file in plain TeX.
+ % Read the file by the name they passed if it exists.
+ \openin 1 txi-#1.tex
+ \ifeof 1
+ \documentlanguagetrywithoutunderscore{#1_\finish}%
+ \else
+ \input txi-#1.tex
+ \fi
+ \closein 1
+ \endgroup
+\endgroup}
+}
+%
+% If they passed de_DE, and txi-de_DE.tex doesn't exist,
+% try txi-de.tex.
+%
+\def\documentlanguagetrywithoutunderscore#1_#2\finish{%
+ \openin 1 txi-#1.tex
+ \ifeof 1
+ \errhelp = \nolanghelp
+ \errmessage{Cannot read language file txi-#1.tex}%
+ \else
+ \input txi-#1.tex
+ \fi
+ \closein 1
+}
+%
+\newhelp\nolanghelp{The given language definition file cannot be found or
+is empty. Maybe you need to install it? In the current directory
+should work if nowhere else does.}
+
+% Set the catcode of characters 128 through 255 to the specified number.
+%
+\def\setnonasciicharscatcode#1{%
+ \count255=128
+ \loop\ifnum\count255<256
+ \global\catcode\count255=#1
+ \advance\count255 by 1
+ \repeat
+}
+
+% @documentencoding sets the definition of non-ASCII characters
+% according to the specified encoding.
+%
+\parseargdef\documentencoding{%
+ % Encoding being declared for the document.
+ \def\declaredencoding{\csname #1.enc\endcsname}%
+ %
+ % Supported encodings: names converted to tokens in order to be able
+ % to compare them with \ifx.
+ \def\ascii{\csname US-ASCII.enc\endcsname}%
+ \def\latnine{\csname ISO-8859-15.enc\endcsname}%
+ \def\latone{\csname ISO-8859-1.enc\endcsname}%
+ \def\lattwo{\csname ISO-8859-2.enc\endcsname}%
+ \def\utfeight{\csname UTF-8.enc\endcsname}%
+ %
+ \ifx \declaredencoding \ascii
+ \asciichardefs
+ %
+ \else \ifx \declaredencoding \lattwo
+ \setnonasciicharscatcode\active
+ \lattwochardefs
+ %
+ \else \ifx \declaredencoding \latone
+ \setnonasciicharscatcode\active
+ \latonechardefs
+ %
+ \else \ifx \declaredencoding \latnine
+ \setnonasciicharscatcode\active
+ \latninechardefs
+ %
+ \else \ifx \declaredencoding \utfeight
+ \setnonasciicharscatcode\active
+ \utfeightchardefs
+ %
+ \else
+ \message{Unknown document encoding #1, ignoring.}%
+ %
+ \fi % utfeight
+ \fi % latnine
+ \fi % latone
+ \fi % lattwo
+ \fi % ascii
+}
+
+% A message to be logged when using a character that isn't available
+% the default font encoding (OT1).
+%
+\def\missingcharmsg#1{\message{Character missing in OT1 encoding: #1.}}
+
+% Take account of \c (plain) vs. \, (Texinfo) difference.
+\def\cedilla#1{\ifx\c\ptexc\c{#1}\else\,{#1}\fi}
+
+% First, make active non-ASCII characters in order for them to be
+% correctly categorized when TeX reads the replacement text of
+% macros containing the character definitions.
+\setnonasciicharscatcode\active
+%
+% Latin1 (ISO-8859-1) character definitions.
+\def\latonechardefs{%
+ \gdef^^a0{~}
+ \gdef^^a1{\exclamdown}
+ \gdef^^a2{\missingcharmsg{CENT SIGN}}
+ \gdef^^a3{{\pounds}}
+ \gdef^^a4{\missingcharmsg{CURRENCY SIGN}}
+ \gdef^^a5{\missingcharmsg{YEN SIGN}}
+ \gdef^^a6{\missingcharmsg{BROKEN BAR}}
+ \gdef^^a7{\S}
+ \gdef^^a8{\"{}}
+ \gdef^^a9{\copyright}
+ \gdef^^aa{\ordf}
+ \gdef^^ab{\missingcharmsg{LEFT-POINTING DOUBLE ANGLE QUOTATION MARK}}
+ \gdef^^ac{$\lnot$}
+ \gdef^^ad{\-}
+ \gdef^^ae{\registeredsymbol}
+ \gdef^^af{\={}}
+ %
+ \gdef^^b0{\textdegree}
+ \gdef^^b1{$\pm$}
+ \gdef^^b2{$^2$}
+ \gdef^^b3{$^3$}
+ \gdef^^b4{\'{}}
+ \gdef^^b5{$\mu$}
+ \gdef^^b6{\P}
+ %
+ \gdef^^b7{$^.$}
+ \gdef^^b8{\cedilla\ }
+ \gdef^^b9{$^1$}
+ \gdef^^ba{\ordm}
+ %
+ \gdef^^bb{\missingcharmsg{RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK}}
+ \gdef^^bc{$1\over4$}
+ \gdef^^bd{$1\over2$}
+ \gdef^^be{$3\over4$}
+ \gdef^^bf{\questiondown}
+ %
+ \gdef^^c0{\`A}
+ \gdef^^c1{\'A}
+ \gdef^^c2{\^A}
+ \gdef^^c3{\~A}
+ \gdef^^c4{\"A}
+ \gdef^^c5{\ringaccent A}
+ \gdef^^c6{\AE}
+ \gdef^^c7{\cedilla C}
+ \gdef^^c8{\`E}
+ \gdef^^c9{\'E}
+ \gdef^^ca{\^E}
+ \gdef^^cb{\"E}
+ \gdef^^cc{\`I}
+ \gdef^^cd{\'I}
+ \gdef^^ce{\^I}
+ \gdef^^cf{\"I}
+ %
+ \gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER ETH}}
+ \gdef^^d1{\~N}
+ \gdef^^d2{\`O}
+ \gdef^^d3{\'O}
+ \gdef^^d4{\^O}
+ \gdef^^d5{\~O}
+ \gdef^^d6{\"O}
+ \gdef^^d7{$\times$}
+ \gdef^^d8{\O}
+ \gdef^^d9{\`U}
+ \gdef^^da{\'U}
+ \gdef^^db{\^U}
+ \gdef^^dc{\"U}
+ \gdef^^dd{\'Y}
+ \gdef^^de{\missingcharmsg{LATIN CAPITAL LETTER THORN}}
+ \gdef^^df{\ss}
+ %
+ \gdef^^e0{\`a}
+ \gdef^^e1{\'a}
+ \gdef^^e2{\^a}
+ \gdef^^e3{\~a}
+ \gdef^^e4{\"a}
+ \gdef^^e5{\ringaccent a}
+ \gdef^^e6{\ae}
+ \gdef^^e7{\cedilla c}
+ \gdef^^e8{\`e}
+ \gdef^^e9{\'e}
+ \gdef^^ea{\^e}
+ \gdef^^eb{\"e}
+ \gdef^^ec{\`{\dotless i}}
+ \gdef^^ed{\'{\dotless i}}
+ \gdef^^ee{\^{\dotless i}}
+ \gdef^^ef{\"{\dotless i}}
+ %
+ \gdef^^f0{\missingcharmsg{LATIN SMALL LETTER ETH}}
+ \gdef^^f1{\~n}
+ \gdef^^f2{\`o}
+ \gdef^^f3{\'o}
+ \gdef^^f4{\^o}
+ \gdef^^f5{\~o}
+ \gdef^^f6{\"o}
+ \gdef^^f7{$\div$}
+ \gdef^^f8{\o}
+ \gdef^^f9{\`u}
+ \gdef^^fa{\'u}
+ \gdef^^fb{\^u}
+ \gdef^^fc{\"u}
+ \gdef^^fd{\'y}
+ \gdef^^fe{\missingcharmsg{LATIN SMALL LETTER THORN}}
+ \gdef^^ff{\"y}
+}
+
+% Latin9 (ISO-8859-15) encoding character definitions.
+\def\latninechardefs{%
+ % Encoding is almost identical to Latin1.
+ \latonechardefs
+ %
+ \gdef^^a4{\euro}
+ \gdef^^a6{\v S}
+ \gdef^^a8{\v s}
+ \gdef^^b4{\v Z}
+ \gdef^^b8{\v z}
+ \gdef^^bc{\OE}
+ \gdef^^bd{\oe}
+ \gdef^^be{\"Y}
+}
+
+% Latin2 (ISO-8859-2) character definitions.
+\def\lattwochardefs{%
+ \gdef^^a0{~}
+ \gdef^^a1{\missingcharmsg{LATIN CAPITAL LETTER A WITH OGONEK}}
+ \gdef^^a2{\u{}}
+ \gdef^^a3{\L}
+ \gdef^^a4{\missingcharmsg{CURRENCY SIGN}}
+ \gdef^^a5{\v L}
+ \gdef^^a6{\'S}
+ \gdef^^a7{\S}
+ \gdef^^a8{\"{}}
+ \gdef^^a9{\v S}
+ \gdef^^aa{\cedilla S}
+ \gdef^^ab{\v T}
+ \gdef^^ac{\'Z}
+ \gdef^^ad{\-}
+ \gdef^^ae{\v Z}
+ \gdef^^af{\dotaccent Z}
+ %
+ \gdef^^b0{\textdegree}
+ \gdef^^b1{\missingcharmsg{LATIN SMALL LETTER A WITH OGONEK}}
+ \gdef^^b2{\missingcharmsg{OGONEK}}
+ \gdef^^b3{\l}
+ \gdef^^b4{\'{}}
+ \gdef^^b5{\v l}
+ \gdef^^b6{\'s}
+ \gdef^^b7{\v{}}
+ \gdef^^b8{\cedilla\ }
+ \gdef^^b9{\v s}
+ \gdef^^ba{\cedilla s}
+ \gdef^^bb{\v t}
+ \gdef^^bc{\'z}
+ \gdef^^bd{\H{}}
+ \gdef^^be{\v z}
+ \gdef^^bf{\dotaccent z}
+ %
+ \gdef^^c0{\'R}
+ \gdef^^c1{\'A}
+ \gdef^^c2{\^A}
+ \gdef^^c3{\u A}
+ \gdef^^c4{\"A}
+ \gdef^^c5{\'L}
+ \gdef^^c6{\'C}
+ \gdef^^c7{\cedilla C}
+ \gdef^^c8{\v C}
+ \gdef^^c9{\'E}
+ \gdef^^ca{\missingcharmsg{LATIN CAPITAL LETTER E WITH OGONEK}}
+ \gdef^^cb{\"E}
+ \gdef^^cc{\v E}
+ \gdef^^cd{\'I}
+ \gdef^^ce{\^I}
+ \gdef^^cf{\v D}
+ %
+ \gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER D WITH STROKE}}
+ \gdef^^d1{\'N}
+ \gdef^^d2{\v N}
+ \gdef^^d3{\'O}
+ \gdef^^d4{\^O}
+ \gdef^^d5{\H O}
+ \gdef^^d6{\"O}
+ \gdef^^d7{$\times$}
+ \gdef^^d8{\v R}
+ \gdef^^d9{\ringaccent U}
+ \gdef^^da{\'U}
+ \gdef^^db{\H U}
+ \gdef^^dc{\"U}
+ \gdef^^dd{\'Y}
+ \gdef^^de{\cedilla T}
+ \gdef^^df{\ss}
+ %
+ \gdef^^e0{\'r}
+ \gdef^^e1{\'a}
+ \gdef^^e2{\^a}
+ \gdef^^e3{\u a}
+ \gdef^^e4{\"a}
+ \gdef^^e5{\'l}
+ \gdef^^e6{\'c}
+ \gdef^^e7{\cedilla c}
+ \gdef^^e8{\v c}
+ \gdef^^e9{\'e}
+ \gdef^^ea{\missingcharmsg{LATIN SMALL LETTER E WITH OGONEK}}
+ \gdef^^eb{\"e}
+ \gdef^^ec{\v e}
+ \gdef^^ed{\'\i}
+ \gdef^^ee{\^\i}
+ \gdef^^ef{\v d}
+ %
+ \gdef^^f0{\missingcharmsg{LATIN SMALL LETTER D WITH STROKE}}
+ \gdef^^f1{\'n}
+ \gdef^^f2{\v n}
+ \gdef^^f3{\'o}
+ \gdef^^f4{\^o}
+ \gdef^^f5{\H o}
+ \gdef^^f6{\"o}
+ \gdef^^f7{$\div$}
+ \gdef^^f8{\v r}
+ \gdef^^f9{\ringaccent u}
+ \gdef^^fa{\'u}
+ \gdef^^fb{\H u}
+ \gdef^^fc{\"u}
+ \gdef^^fd{\'y}
+ \gdef^^fe{\cedilla t}
+ \gdef^^ff{\dotaccent{}}
+}
+
+% UTF-8 character definitions.
+%
+% This code to support UTF-8 is based on LaTeX's utf8.def, with some
+% changes for Texinfo conventions. It is included here under the GPL by
+% permission from Frank Mittelbach and the LaTeX team.
+%
+\newcount\countUTFx
+\newcount\countUTFy
+\newcount\countUTFz
+
+\gdef\UTFviiiTwoOctets#1#2{\expandafter
+ \UTFviiiDefined\csname u8:#1\string #2\endcsname}
+%
+\gdef\UTFviiiThreeOctets#1#2#3{\expandafter
+ \UTFviiiDefined\csname u8:#1\string #2\string #3\endcsname}
+%
+\gdef\UTFviiiFourOctets#1#2#3#4{\expandafter
+ \UTFviiiDefined\csname u8:#1\string #2\string #3\string #4\endcsname}
+
+\gdef\UTFviiiDefined#1{%
+ \ifx #1\relax
+ \message{\linenumber Unicode char \string #1 not defined for Texinfo}%
+ \else
+ \expandafter #1%
+ \fi
+}
+
+\begingroup
+ \catcode`\~13
+ \catcode`\"12
+
+ \def\UTFviiiLoop{%
+ \global\catcode\countUTFx\active
+ \uccode`\~\countUTFx
+ \uppercase\expandafter{\UTFviiiTmp}%
+ \advance\countUTFx by 1
+ \ifnum\countUTFx < \countUTFy
+ \expandafter\UTFviiiLoop
+ \fi}
+
+ \countUTFx = "C2
+ \countUTFy = "E0
+ \def\UTFviiiTmp{%
+ \xdef~{\noexpand\UTFviiiTwoOctets\string~}}
+ \UTFviiiLoop
+
+ \countUTFx = "E0
+ \countUTFy = "F0
+ \def\UTFviiiTmp{%
+ \xdef~{\noexpand\UTFviiiThreeOctets\string~}}
+ \UTFviiiLoop
+
+ \countUTFx = "F0
+ \countUTFy = "F4
+ \def\UTFviiiTmp{%
+ \xdef~{\noexpand\UTFviiiFourOctets\string~}}
+ \UTFviiiLoop
+\endgroup
+
+\begingroup
+ \catcode`\"=12
+ \catcode`\<=12
+ \catcode`\.=12
+ \catcode`\,=12
+ \catcode`\;=12
+ \catcode`\!=12
+ \catcode`\~=13
+
+ \gdef\DeclareUnicodeCharacter#1#2{%
+ \countUTFz = "#1\relax
+ \wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}%
+ \begingroup
+ \parseXMLCharref
+ \def\UTFviiiTwoOctets##1##2{%
+ \csname u8:##1\string ##2\endcsname}%
+ \def\UTFviiiThreeOctets##1##2##3{%
+ \csname u8:##1\string ##2\string ##3\endcsname}%
+ \def\UTFviiiFourOctets##1##2##3##4{%
+ \csname u8:##1\string ##2\string ##3\string ##4\endcsname}%
+ \expandafter\expandafter\expandafter\expandafter
+ \expandafter\expandafter\expandafter
+ \gdef\UTFviiiTmp{#2}%
+ \endgroup}
+
+ \gdef\parseXMLCharref{%
+ \ifnum\countUTFz < "A0\relax
+ \errhelp = \EMsimple
+ \errmessage{Cannot define Unicode char value < 00A0}%
+ \else\ifnum\countUTFz < "800\relax
+ \parseUTFviiiA,%
+ \parseUTFviiiB C\UTFviiiTwoOctets.,%
+ \else\ifnum\countUTFz < "10000\relax
+ \parseUTFviiiA;%
+ \parseUTFviiiA,%
+ \parseUTFviiiB E\UTFviiiThreeOctets.{,;}%
+ \else
+ \parseUTFviiiA;%
+ \parseUTFviiiA,%
+ \parseUTFviiiA!%
+ \parseUTFviiiB F\UTFviiiFourOctets.{!,;}%
+ \fi\fi\fi
+ }
+
+ \gdef\parseUTFviiiA#1{%
+ \countUTFx = \countUTFz
+ \divide\countUTFz by 64
+ \countUTFy = \countUTFz
+ \multiply\countUTFz by 64
+ \advance\countUTFx by -\countUTFz
+ \advance\countUTFx by 128
+ \uccode `#1\countUTFx
+ \countUTFz = \countUTFy}
+
+ \gdef\parseUTFviiiB#1#2#3#4{%
+ \advance\countUTFz by "#10\relax
+ \uccode `#3\countUTFz
+ \uppercase{\gdef\UTFviiiTmp{#2#3#4}}}
+\endgroup
+
+\def\utfeightchardefs{%
+ \DeclareUnicodeCharacter{00A0}{\tie}
+ \DeclareUnicodeCharacter{00A1}{\exclamdown}
+ \DeclareUnicodeCharacter{00A3}{\pounds}
+ \DeclareUnicodeCharacter{00A8}{\"{ }}
+ \DeclareUnicodeCharacter{00A9}{\copyright}
+ \DeclareUnicodeCharacter{00AA}{\ordf}
+ \DeclareUnicodeCharacter{00AD}{\-}
+ \DeclareUnicodeCharacter{00AE}{\registeredsymbol}
+ \DeclareUnicodeCharacter{00AF}{\={ }}
+
+ \DeclareUnicodeCharacter{00B0}{\ringaccent{ }}
+ \DeclareUnicodeCharacter{00B4}{\'{ }}
+ \DeclareUnicodeCharacter{00B8}{\cedilla{ }}
+ \DeclareUnicodeCharacter{00BA}{\ordm}
+ \DeclareUnicodeCharacter{00BF}{\questiondown}
+
+ \DeclareUnicodeCharacter{00C0}{\`A}
+ \DeclareUnicodeCharacter{00C1}{\'A}
+ \DeclareUnicodeCharacter{00C2}{\^A}
+ \DeclareUnicodeCharacter{00C3}{\~A}
+ \DeclareUnicodeCharacter{00C4}{\"A}
+ \DeclareUnicodeCharacter{00C5}{\AA}
+ \DeclareUnicodeCharacter{00C6}{\AE}
+ \DeclareUnicodeCharacter{00C7}{\cedilla{C}}
+ \DeclareUnicodeCharacter{00C8}{\`E}
+ \DeclareUnicodeCharacter{00C9}{\'E}
+ \DeclareUnicodeCharacter{00CA}{\^E}
+ \DeclareUnicodeCharacter{00CB}{\"E}
+ \DeclareUnicodeCharacter{00CC}{\`I}
+ \DeclareUnicodeCharacter{00CD}{\'I}
+ \DeclareUnicodeCharacter{00CE}{\^I}
+ \DeclareUnicodeCharacter{00CF}{\"I}
+
+ \DeclareUnicodeCharacter{00D1}{\~N}
+ \DeclareUnicodeCharacter{00D2}{\`O}
+ \DeclareUnicodeCharacter{00D3}{\'O}
+ \DeclareUnicodeCharacter{00D4}{\^O}
+ \DeclareUnicodeCharacter{00D5}{\~O}
+ \DeclareUnicodeCharacter{00D6}{\"O}
+ \DeclareUnicodeCharacter{00D8}{\O}
+ \DeclareUnicodeCharacter{00D9}{\`U}
+ \DeclareUnicodeCharacter{00DA}{\'U}
+ \DeclareUnicodeCharacter{00DB}{\^U}
+ \DeclareUnicodeCharacter{00DC}{\"U}
+ \DeclareUnicodeCharacter{00DD}{\'Y}
+ \DeclareUnicodeCharacter{00DF}{\ss}
+
+ \DeclareUnicodeCharacter{00E0}{\`a}
+ \DeclareUnicodeCharacter{00E1}{\'a}
+ \DeclareUnicodeCharacter{00E2}{\^a}
+ \DeclareUnicodeCharacter{00E3}{\~a}
+ \DeclareUnicodeCharacter{00E4}{\"a}
+ \DeclareUnicodeCharacter{00E5}{\aa}
+ \DeclareUnicodeCharacter{00E6}{\ae}
+ \DeclareUnicodeCharacter{00E7}{\cedilla{c}}
+ \DeclareUnicodeCharacter{00E8}{\`e}
+ \DeclareUnicodeCharacter{00E9}{\'e}
+ \DeclareUnicodeCharacter{00EA}{\^e}
+ \DeclareUnicodeCharacter{00EB}{\"e}
+ \DeclareUnicodeCharacter{00EC}{\`{\dotless{i}}}
+ \DeclareUnicodeCharacter{00ED}{\'{\dotless{i}}}
+ \DeclareUnicodeCharacter{00EE}{\^{\dotless{i}}}
+ \DeclareUnicodeCharacter{00EF}{\"{\dotless{i}}}
+
+ \DeclareUnicodeCharacter{00F1}{\~n}
+ \DeclareUnicodeCharacter{00F2}{\`o}
+ \DeclareUnicodeCharacter{00F3}{\'o}
+ \DeclareUnicodeCharacter{00F4}{\^o}
+ \DeclareUnicodeCharacter{00F5}{\~o}
+ \DeclareUnicodeCharacter{00F6}{\"o}
+ \DeclareUnicodeCharacter{00F8}{\o}
+ \DeclareUnicodeCharacter{00F9}{\`u}
+ \DeclareUnicodeCharacter{00FA}{\'u}
+ \DeclareUnicodeCharacter{00FB}{\^u}
+ \DeclareUnicodeCharacter{00FC}{\"u}
+ \DeclareUnicodeCharacter{00FD}{\'y}
+ \DeclareUnicodeCharacter{00FF}{\"y}
+
+ \DeclareUnicodeCharacter{0100}{\=A}
+ \DeclareUnicodeCharacter{0101}{\=a}
+ \DeclareUnicodeCharacter{0102}{\u{A}}
+ \DeclareUnicodeCharacter{0103}{\u{a}}
+ \DeclareUnicodeCharacter{0106}{\'C}
+ \DeclareUnicodeCharacter{0107}{\'c}
+ \DeclareUnicodeCharacter{0108}{\^C}
+ \DeclareUnicodeCharacter{0109}{\^c}
+ \DeclareUnicodeCharacter{010A}{\dotaccent{C}}
+ \DeclareUnicodeCharacter{010B}{\dotaccent{c}}
+ \DeclareUnicodeCharacter{010C}{\v{C}}
+ \DeclareUnicodeCharacter{010D}{\v{c}}
+ \DeclareUnicodeCharacter{010E}{\v{D}}
+
+ \DeclareUnicodeCharacter{0112}{\=E}
+ \DeclareUnicodeCharacter{0113}{\=e}
+ \DeclareUnicodeCharacter{0114}{\u{E}}
+ \DeclareUnicodeCharacter{0115}{\u{e}}
+ \DeclareUnicodeCharacter{0116}{\dotaccent{E}}
+ \DeclareUnicodeCharacter{0117}{\dotaccent{e}}
+ \DeclareUnicodeCharacter{011A}{\v{E}}
+ \DeclareUnicodeCharacter{011B}{\v{e}}
+ \DeclareUnicodeCharacter{011C}{\^G}
+ \DeclareUnicodeCharacter{011D}{\^g}
+ \DeclareUnicodeCharacter{011E}{\u{G}}
+ \DeclareUnicodeCharacter{011F}{\u{g}}
+
+ \DeclareUnicodeCharacter{0120}{\dotaccent{G}}
+ \DeclareUnicodeCharacter{0121}{\dotaccent{g}}
+ \DeclareUnicodeCharacter{0124}{\^H}
+ \DeclareUnicodeCharacter{0125}{\^h}
+ \DeclareUnicodeCharacter{0128}{\~I}
+ \DeclareUnicodeCharacter{0129}{\~{\dotless{i}}}
+ \DeclareUnicodeCharacter{012A}{\=I}
+ \DeclareUnicodeCharacter{012B}{\={\dotless{i}}}
+ \DeclareUnicodeCharacter{012C}{\u{I}}
+ \DeclareUnicodeCharacter{012D}{\u{\dotless{i}}}
+
+ \DeclareUnicodeCharacter{0130}{\dotaccent{I}}
+ \DeclareUnicodeCharacter{0131}{\dotless{i}}
+ \DeclareUnicodeCharacter{0132}{IJ}
+ \DeclareUnicodeCharacter{0133}{ij}
+ \DeclareUnicodeCharacter{0134}{\^J}
+ \DeclareUnicodeCharacter{0135}{\^{\dotless{j}}}
+ \DeclareUnicodeCharacter{0139}{\'L}
+ \DeclareUnicodeCharacter{013A}{\'l}
+
+ \DeclareUnicodeCharacter{0141}{\L}
+ \DeclareUnicodeCharacter{0142}{\l}
+ \DeclareUnicodeCharacter{0143}{\'N}
+ \DeclareUnicodeCharacter{0144}{\'n}
+ \DeclareUnicodeCharacter{0147}{\v{N}}
+ \DeclareUnicodeCharacter{0148}{\v{n}}
+ \DeclareUnicodeCharacter{014C}{\=O}
+ \DeclareUnicodeCharacter{014D}{\=o}
+ \DeclareUnicodeCharacter{014E}{\u{O}}
+ \DeclareUnicodeCharacter{014F}{\u{o}}
+
+ \DeclareUnicodeCharacter{0150}{\H{O}}
+ \DeclareUnicodeCharacter{0151}{\H{o}}
+ \DeclareUnicodeCharacter{0152}{\OE}
+ \DeclareUnicodeCharacter{0153}{\oe}
+ \DeclareUnicodeCharacter{0154}{\'R}
+ \DeclareUnicodeCharacter{0155}{\'r}
+ \DeclareUnicodeCharacter{0158}{\v{R}}
+ \DeclareUnicodeCharacter{0159}{\v{r}}
+ \DeclareUnicodeCharacter{015A}{\'S}
+ \DeclareUnicodeCharacter{015B}{\'s}
+ \DeclareUnicodeCharacter{015C}{\^S}
+ \DeclareUnicodeCharacter{015D}{\^s}
+ \DeclareUnicodeCharacter{015E}{\cedilla{S}}
+ \DeclareUnicodeCharacter{015F}{\cedilla{s}}
+
+ \DeclareUnicodeCharacter{0160}{\v{S}}
+ \DeclareUnicodeCharacter{0161}{\v{s}}
+ \DeclareUnicodeCharacter{0162}{\cedilla{t}}
+ \DeclareUnicodeCharacter{0163}{\cedilla{T}}
+ \DeclareUnicodeCharacter{0164}{\v{T}}
+
+ \DeclareUnicodeCharacter{0168}{\~U}
+ \DeclareUnicodeCharacter{0169}{\~u}
+ \DeclareUnicodeCharacter{016A}{\=U}
+ \DeclareUnicodeCharacter{016B}{\=u}
+ \DeclareUnicodeCharacter{016C}{\u{U}}
+ \DeclareUnicodeCharacter{016D}{\u{u}}
+ \DeclareUnicodeCharacter{016E}{\ringaccent{U}}
+ \DeclareUnicodeCharacter{016F}{\ringaccent{u}}
+
+ \DeclareUnicodeCharacter{0170}{\H{U}}
+ \DeclareUnicodeCharacter{0171}{\H{u}}
+ \DeclareUnicodeCharacter{0174}{\^W}
+ \DeclareUnicodeCharacter{0175}{\^w}
+ \DeclareUnicodeCharacter{0176}{\^Y}
+ \DeclareUnicodeCharacter{0177}{\^y}
+ \DeclareUnicodeCharacter{0178}{\"Y}
+ \DeclareUnicodeCharacter{0179}{\'Z}
+ \DeclareUnicodeCharacter{017A}{\'z}
+ \DeclareUnicodeCharacter{017B}{\dotaccent{Z}}
+ \DeclareUnicodeCharacter{017C}{\dotaccent{z}}
+ \DeclareUnicodeCharacter{017D}{\v{Z}}
+ \DeclareUnicodeCharacter{017E}{\v{z}}
+
+ \DeclareUnicodeCharacter{01C4}{D\v{Z}}
+ \DeclareUnicodeCharacter{01C5}{D\v{z}}
+ \DeclareUnicodeCharacter{01C6}{d\v{z}}
+ \DeclareUnicodeCharacter{01C7}{LJ}
+ \DeclareUnicodeCharacter{01C8}{Lj}
+ \DeclareUnicodeCharacter{01C9}{lj}
+ \DeclareUnicodeCharacter{01CA}{NJ}
+ \DeclareUnicodeCharacter{01CB}{Nj}
+ \DeclareUnicodeCharacter{01CC}{nj}
+ \DeclareUnicodeCharacter{01CD}{\v{A}}
+ \DeclareUnicodeCharacter{01CE}{\v{a}}
+ \DeclareUnicodeCharacter{01CF}{\v{I}}
+
+ \DeclareUnicodeCharacter{01D0}{\v{\dotless{i}}}
+ \DeclareUnicodeCharacter{01D1}{\v{O}}
+ \DeclareUnicodeCharacter{01D2}{\v{o}}
+ \DeclareUnicodeCharacter{01D3}{\v{U}}
+ \DeclareUnicodeCharacter{01D4}{\v{u}}
+
+ \DeclareUnicodeCharacter{01E2}{\={\AE}}
+ \DeclareUnicodeCharacter{01E3}{\={\ae}}
+ \DeclareUnicodeCharacter{01E6}{\v{G}}
+ \DeclareUnicodeCharacter{01E7}{\v{g}}
+ \DeclareUnicodeCharacter{01E8}{\v{K}}
+ \DeclareUnicodeCharacter{01E9}{\v{k}}
+
+ \DeclareUnicodeCharacter{01F0}{\v{\dotless{j}}}
+ \DeclareUnicodeCharacter{01F1}{DZ}
+ \DeclareUnicodeCharacter{01F2}{Dz}
+ \DeclareUnicodeCharacter{01F3}{dz}
+ \DeclareUnicodeCharacter{01F4}{\'G}
+ \DeclareUnicodeCharacter{01F5}{\'g}
+ \DeclareUnicodeCharacter{01F8}{\`N}
+ \DeclareUnicodeCharacter{01F9}{\`n}
+ \DeclareUnicodeCharacter{01FC}{\'{\AE}}
+ \DeclareUnicodeCharacter{01FD}{\'{\ae}}
+ \DeclareUnicodeCharacter{01FE}{\'{\O}}
+ \DeclareUnicodeCharacter{01FF}{\'{\o}}
+
+ \DeclareUnicodeCharacter{021E}{\v{H}}
+ \DeclareUnicodeCharacter{021F}{\v{h}}
+
+ \DeclareUnicodeCharacter{0226}{\dotaccent{A}}
+ \DeclareUnicodeCharacter{0227}{\dotaccent{a}}
+ \DeclareUnicodeCharacter{0228}{\cedilla{E}}
+ \DeclareUnicodeCharacter{0229}{\cedilla{e}}
+ \DeclareUnicodeCharacter{022E}{\dotaccent{O}}
+ \DeclareUnicodeCharacter{022F}{\dotaccent{o}}
+
+ \DeclareUnicodeCharacter{0232}{\=Y}
+ \DeclareUnicodeCharacter{0233}{\=y}
+ \DeclareUnicodeCharacter{0237}{\dotless{j}}
+
+ \DeclareUnicodeCharacter{1E02}{\dotaccent{B}}
+ \DeclareUnicodeCharacter{1E03}{\dotaccent{b}}
+ \DeclareUnicodeCharacter{1E04}{\udotaccent{B}}
+ \DeclareUnicodeCharacter{1E05}{\udotaccent{b}}
+ \DeclareUnicodeCharacter{1E06}{\ubaraccent{B}}
+ \DeclareUnicodeCharacter{1E07}{\ubaraccent{b}}
+ \DeclareUnicodeCharacter{1E0A}{\dotaccent{D}}
+ \DeclareUnicodeCharacter{1E0B}{\dotaccent{d}}
+ \DeclareUnicodeCharacter{1E0C}{\udotaccent{D}}
+ \DeclareUnicodeCharacter{1E0D}{\udotaccent{d}}
+ \DeclareUnicodeCharacter{1E0E}{\ubaraccent{D}}
+ \DeclareUnicodeCharacter{1E0F}{\ubaraccent{d}}
+
+ \DeclareUnicodeCharacter{1E1E}{\dotaccent{F}}
+ \DeclareUnicodeCharacter{1E1F}{\dotaccent{f}}
+
+ \DeclareUnicodeCharacter{1E20}{\=G}
+ \DeclareUnicodeCharacter{1E21}{\=g}
+ \DeclareUnicodeCharacter{1E22}{\dotaccent{H}}
+ \DeclareUnicodeCharacter{1E23}{\dotaccent{h}}
+ \DeclareUnicodeCharacter{1E24}{\udotaccent{H}}
+ \DeclareUnicodeCharacter{1E25}{\udotaccent{h}}
+ \DeclareUnicodeCharacter{1E26}{\"H}
+ \DeclareUnicodeCharacter{1E27}{\"h}
+
+ \DeclareUnicodeCharacter{1E30}{\'K}
+ \DeclareUnicodeCharacter{1E31}{\'k}
+ \DeclareUnicodeCharacter{1E32}{\udotaccent{K}}
+ \DeclareUnicodeCharacter{1E33}{\udotaccent{k}}
+ \DeclareUnicodeCharacter{1E34}{\ubaraccent{K}}
+ \DeclareUnicodeCharacter{1E35}{\ubaraccent{k}}
+ \DeclareUnicodeCharacter{1E36}{\udotaccent{L}}
+ \DeclareUnicodeCharacter{1E37}{\udotaccent{l}}
+ \DeclareUnicodeCharacter{1E3A}{\ubaraccent{L}}
+ \DeclareUnicodeCharacter{1E3B}{\ubaraccent{l}}
+ \DeclareUnicodeCharacter{1E3E}{\'M}
+ \DeclareUnicodeCharacter{1E3F}{\'m}
+
+ \DeclareUnicodeCharacter{1E40}{\dotaccent{M}}
+ \DeclareUnicodeCharacter{1E41}{\dotaccent{m}}
+ \DeclareUnicodeCharacter{1E42}{\udotaccent{M}}
+ \DeclareUnicodeCharacter{1E43}{\udotaccent{m}}
+ \DeclareUnicodeCharacter{1E44}{\dotaccent{N}}
+ \DeclareUnicodeCharacter{1E45}{\dotaccent{n}}
+ \DeclareUnicodeCharacter{1E46}{\udotaccent{N}}
+ \DeclareUnicodeCharacter{1E47}{\udotaccent{n}}
+ \DeclareUnicodeCharacter{1E48}{\ubaraccent{N}}
+ \DeclareUnicodeCharacter{1E49}{\ubaraccent{n}}
+
+ \DeclareUnicodeCharacter{1E54}{\'P}
+ \DeclareUnicodeCharacter{1E55}{\'p}
+ \DeclareUnicodeCharacter{1E56}{\dotaccent{P}}
+ \DeclareUnicodeCharacter{1E57}{\dotaccent{p}}
+ \DeclareUnicodeCharacter{1E58}{\dotaccent{R}}
+ \DeclareUnicodeCharacter{1E59}{\dotaccent{r}}
+ \DeclareUnicodeCharacter{1E5A}{\udotaccent{R}}
+ \DeclareUnicodeCharacter{1E5B}{\udotaccent{r}}
+ \DeclareUnicodeCharacter{1E5E}{\ubaraccent{R}}
+ \DeclareUnicodeCharacter{1E5F}{\ubaraccent{r}}
+
+ \DeclareUnicodeCharacter{1E60}{\dotaccent{S}}
+ \DeclareUnicodeCharacter{1E61}{\dotaccent{s}}
+ \DeclareUnicodeCharacter{1E62}{\udotaccent{S}}
+ \DeclareUnicodeCharacter{1E63}{\udotaccent{s}}
+ \DeclareUnicodeCharacter{1E6A}{\dotaccent{T}}
+ \DeclareUnicodeCharacter{1E6B}{\dotaccent{t}}
+ \DeclareUnicodeCharacter{1E6C}{\udotaccent{T}}
+ \DeclareUnicodeCharacter{1E6D}{\udotaccent{t}}
+ \DeclareUnicodeCharacter{1E6E}{\ubaraccent{T}}
+ \DeclareUnicodeCharacter{1E6F}{\ubaraccent{t}}
+
+ \DeclareUnicodeCharacter{1E7C}{\~V}
+ \DeclareUnicodeCharacter{1E7D}{\~v}
+ \DeclareUnicodeCharacter{1E7E}{\udotaccent{V}}
+ \DeclareUnicodeCharacter{1E7F}{\udotaccent{v}}
+
+ \DeclareUnicodeCharacter{1E80}{\`W}
+ \DeclareUnicodeCharacter{1E81}{\`w}
+ \DeclareUnicodeCharacter{1E82}{\'W}
+ \DeclareUnicodeCharacter{1E83}{\'w}
+ \DeclareUnicodeCharacter{1E84}{\"W}
+ \DeclareUnicodeCharacter{1E85}{\"w}
+ \DeclareUnicodeCharacter{1E86}{\dotaccent{W}}
+ \DeclareUnicodeCharacter{1E87}{\dotaccent{w}}
+ \DeclareUnicodeCharacter{1E88}{\udotaccent{W}}
+ \DeclareUnicodeCharacter{1E89}{\udotaccent{w}}
+ \DeclareUnicodeCharacter{1E8A}{\dotaccent{X}}
+ \DeclareUnicodeCharacter{1E8B}{\dotaccent{x}}
+ \DeclareUnicodeCharacter{1E8C}{\"X}
+ \DeclareUnicodeCharacter{1E8D}{\"x}
+ \DeclareUnicodeCharacter{1E8E}{\dotaccent{Y}}
+ \DeclareUnicodeCharacter{1E8F}{\dotaccent{y}}
+
+ \DeclareUnicodeCharacter{1E90}{\^Z}
+ \DeclareUnicodeCharacter{1E91}{\^z}
+ \DeclareUnicodeCharacter{1E92}{\udotaccent{Z}}
+ \DeclareUnicodeCharacter{1E93}{\udotaccent{z}}
+ \DeclareUnicodeCharacter{1E94}{\ubaraccent{Z}}
+ \DeclareUnicodeCharacter{1E95}{\ubaraccent{z}}
+ \DeclareUnicodeCharacter{1E96}{\ubaraccent{h}}
+ \DeclareUnicodeCharacter{1E97}{\"t}
+ \DeclareUnicodeCharacter{1E98}{\ringaccent{w}}
+ \DeclareUnicodeCharacter{1E99}{\ringaccent{y}}
+
+ \DeclareUnicodeCharacter{1EA0}{\udotaccent{A}}
+ \DeclareUnicodeCharacter{1EA1}{\udotaccent{a}}
+
+ \DeclareUnicodeCharacter{1EB8}{\udotaccent{E}}
+ \DeclareUnicodeCharacter{1EB9}{\udotaccent{e}}
+ \DeclareUnicodeCharacter{1EBC}{\~E}
+ \DeclareUnicodeCharacter{1EBD}{\~e}
+
+ \DeclareUnicodeCharacter{1ECA}{\udotaccent{I}}
+ \DeclareUnicodeCharacter{1ECB}{\udotaccent{i}}
+ \DeclareUnicodeCharacter{1ECC}{\udotaccent{O}}
+ \DeclareUnicodeCharacter{1ECD}{\udotaccent{o}}
+
+ \DeclareUnicodeCharacter{1EE4}{\udotaccent{U}}
+ \DeclareUnicodeCharacter{1EE5}{\udotaccent{u}}
+
+ \DeclareUnicodeCharacter{1EF2}{\`Y}
+ \DeclareUnicodeCharacter{1EF3}{\`y}
+ \DeclareUnicodeCharacter{1EF4}{\udotaccent{Y}}
+
+ \DeclareUnicodeCharacter{1EF8}{\~Y}
+ \DeclareUnicodeCharacter{1EF9}{\~y}
+
+ \DeclareUnicodeCharacter{2013}{--}
+ \DeclareUnicodeCharacter{2014}{---}
+ \DeclareUnicodeCharacter{2022}{\bullet}
+ \DeclareUnicodeCharacter{2026}{\dots}
+ \DeclareUnicodeCharacter{20AC}{\euro}
+
+ \DeclareUnicodeCharacter{2192}{\expansion}
+ \DeclareUnicodeCharacter{21D2}{\result}
+
+ \DeclareUnicodeCharacter{2212}{\minus}
+ \DeclareUnicodeCharacter{2217}{\point}
+ \DeclareUnicodeCharacter{2261}{\equiv}
+}% end of \utfeightchardefs
+
+
+% US-ASCII character definitions.
+\def\asciichardefs{% nothing need be done
+ \relax
+}
+
+% Make non-ASCII characters printable again for compatibility with
+% existing Texinfo documents that may use them, even without declaring a
+% document encoding.
+%
+\setnonasciicharscatcode \other
+
+
+\message{formatting,}
+
+\newdimen\defaultparindent \defaultparindent = 15pt
+
+\chapheadingskip = 15pt plus 4pt minus 2pt
+\secheadingskip = 12pt plus 3pt minus 2pt
+\subsecheadingskip = 9pt plus 2pt minus 2pt
+
+% Prevent underfull vbox error messages.
+\vbadness = 10000
+
+% Don't be so finicky about underfull hboxes, either.
+\hbadness = 2000
+
+% Following George Bush, just get rid of widows and orphans.
+\widowpenalty=10000
+\clubpenalty=10000
+
+% Use TeX 3.0's \emergencystretch to help line breaking, but if we're
+% using an old version of TeX, don't do anything. We want the amount of
+% stretch added to depend on the line length, hence the dependence on
+% \hsize. We call this whenever the paper size is set.
+%
+\def\setemergencystretch{%
+ \ifx\emergencystretch\thisisundefined
+ % Allow us to assign to \emergencystretch anyway.
+ \def\emergencystretch{\dimen0}%
+ \else
+ \emergencystretch = .15\hsize
+ \fi
+}
+
+% Parameters in order: 1) textheight; 2) textwidth;
+% 3) voffset; 4) hoffset; 5) binding offset; 6) topskip;
+% 7) physical page height; 8) physical page width.
+%
+% We also call \setleading{\textleading}, so the caller should define
+% \textleading. The caller should also set \parskip.
+%
+\def\internalpagesizes#1#2#3#4#5#6#7#8{%
+ \voffset = #3\relax
+ \topskip = #6\relax
+ \splittopskip = \topskip
+ %
+ \vsize = #1\relax
+ \advance\vsize by \topskip
+ \outervsize = \vsize
+ \advance\outervsize by 2\topandbottommargin
+ \pageheight = \vsize
+ %
+ \hsize = #2\relax
+ \outerhsize = \hsize
+ \advance\outerhsize by 0.5in
+ \pagewidth = \hsize
+ %
+ \normaloffset = #4\relax
+ \bindingoffset = #5\relax
+ %
+ \ifpdf
+ \pdfpageheight #7\relax
+ \pdfpagewidth #8\relax
+ \pdfhorigin = 1 true in
+ \pdfvorigin = 1 true in
+ \fi
+ %
+ \setleading{\textleading}
+ %
+ \parindent = \defaultparindent
+ \setemergencystretch
+}
+
+% @letterpaper (the default).
+\def\letterpaper{{\globaldefs = 1
+ \parskip = 3pt plus 2pt minus 1pt
+ \textleading = 13.2pt
+ %
+ % If page is nothing but text, make it come out even.
+ \internalpagesizes{46\baselineskip}{6in}%
+ {\voffset}{.25in}%
+ {\bindingoffset}{36pt}%
+ {11in}{8.5in}%
+}}
+
+% Use @smallbook to reset parameters for 7x9.25 trim size.
+\def\smallbook{{\globaldefs = 1
+ \parskip = 2pt plus 1pt
+ \textleading = 12pt
+ %
+ \internalpagesizes{7.5in}{5in}%
+ {-.2in}{0in}%
+ {\bindingoffset}{16pt}%
+ {9.25in}{7in}%
+ %
+ \lispnarrowing = 0.3in
+ \tolerance = 700
+ \hfuzz = 1pt
+ \contentsrightmargin = 0pt
+ \defbodyindent = .5cm
+}}
+
+% Use @smallerbook to reset parameters for 6x9 trim size.
+% (Just testing, parameters still in flux.)
+\def\smallerbook{{\globaldefs = 1
+ \parskip = 1.5pt plus 1pt
+ \textleading = 12pt
+ %
+ \internalpagesizes{7.4in}{4.8in}%
+ {-.2in}{-.4in}%
+ {0pt}{14pt}%
+ {9in}{6in}%
+ %
+ \lispnarrowing = 0.25in
+ \tolerance = 700
+ \hfuzz = 1pt
+ \contentsrightmargin = 0pt
+ \defbodyindent = .4cm
+}}
+
+% Use @afourpaper to print on European A4 paper.
+\def\afourpaper{{\globaldefs = 1
+ \parskip = 3pt plus 2pt minus 1pt
+ \textleading = 13.2pt
+ %
+ % Double-side printing via postscript on Laserjet 4050
+ % prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm.
+ % To change the settings for a different printer or situation, adjust
+ % \normaloffset until the front-side and back-side texts align. Then
+ % do the same for \bindingoffset. You can set these for testing in
+ % your texinfo source file like this:
+ % @tex
+ % \global\normaloffset = -6mm
+ % \global\bindingoffset = 10mm
+ % @end tex
+ \internalpagesizes{51\baselineskip}{160mm}
+ {\voffset}{\hoffset}%
+ {\bindingoffset}{44pt}%
+ {297mm}{210mm}%
+ %
+ \tolerance = 700
+ \hfuzz = 1pt
+ \contentsrightmargin = 0pt
+ \defbodyindent = 5mm
+}}
+
+% Use @afivepaper to print on European A5 paper.
+% From romildo@urano.iceb.ufop.br, 2 July 2000.
+% He also recommends making @example and @lisp be small.
+\def\afivepaper{{\globaldefs = 1
+ \parskip = 2pt plus 1pt minus 0.1pt
+ \textleading = 12.5pt
+ %
+ \internalpagesizes{160mm}{120mm}%
+ {\voffset}{\hoffset}%
+ {\bindingoffset}{8pt}%
+ {210mm}{148mm}%
+ %
+ \lispnarrowing = 0.2in
+ \tolerance = 800
+ \hfuzz = 1.2pt
+ \contentsrightmargin = 0pt
+ \defbodyindent = 2mm
+ \tableindent = 12mm
+}}
+
+% A specific text layout, 24x15cm overall, intended for A4 paper.
+\def\afourlatex{{\globaldefs = 1
+ \afourpaper
+ \internalpagesizes{237mm}{150mm}%
+ {\voffset}{4.6mm}%
+ {\bindingoffset}{7mm}%
+ {297mm}{210mm}%
+ %
+ % Must explicitly reset to 0 because we call \afourpaper.
+ \globaldefs = 0
+}}
+
+% Use @afourwide to print on A4 paper in landscape format.
+\def\afourwide{{\globaldefs = 1
+ \afourpaper
+ \internalpagesizes{241mm}{165mm}%
+ {\voffset}{-2.95mm}%
+ {\bindingoffset}{7mm}%
+ {297mm}{210mm}%
+ \globaldefs = 0
+}}
+
+% @pagesizes TEXTHEIGHT[,TEXTWIDTH]
+% Perhaps we should allow setting the margins, \topskip, \parskip,
+% and/or leading, also. Or perhaps we should compute them somehow.
+%
+\parseargdef\pagesizes{\pagesizesyyy #1,,\finish}
+\def\pagesizesyyy#1,#2,#3\finish{{%
+ \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi
+ \globaldefs = 1
+ %
+ \parskip = 3pt plus 2pt minus 1pt
+ \setleading{\textleading}%
+ %
+ \dimen0 = #1
+ \advance\dimen0 by \voffset
+ %
+ \dimen2 = \hsize
+ \advance\dimen2 by \normaloffset
+ %
+ \internalpagesizes{#1}{\hsize}%
+ {\voffset}{\normaloffset}%
+ {\bindingoffset}{44pt}%
+ {\dimen0}{\dimen2}%
+}}
+
+% Set default to letter.
+%
+\letterpaper
+
+
+\message{and turning on texinfo input format.}
+
+% Define macros to output various characters with catcode for normal text.
+\catcode`\"=\other
+\catcode`\~=\other
+\catcode`\^=\other
+\catcode`\_=\other
+\catcode`\|=\other
+\catcode`\<=\other
+\catcode`\>=\other
+\catcode`\+=\other
+\catcode`\$=\other
+\def\normaldoublequote{"}
+\def\normaltilde{~}
+\def\normalcaret{^}
+\def\normalunderscore{_}
+\def\normalverticalbar{|}
+\def\normalless{<}
+\def\normalgreater{>}
+\def\normalplus{+}
+\def\normaldollar{$}%$ font-lock fix
+
+% This macro is used to make a character print one way in \tt
+% (where it can probably be output as-is), and another way in other fonts,
+% where something hairier probably needs to be done.
+%
+% #1 is what to print if we are indeed using \tt; #2 is what to print
+% otherwise. Since all the Computer Modern typewriter fonts have zero
+% interword stretch (and shrink), and it is reasonable to expect all
+% typewriter fonts to have this, we can check that font parameter.
+%
+\def\ifusingtt#1#2{\ifdim \fontdimen3\font=0pt #1\else #2\fi}
+
+% Same as above, but check for italic font. Actually this also catches
+% non-italic slanted fonts since it is impossible to distinguish them from
+% italic fonts. But since this is only used by $ and it uses \sl anyway
+% this is not a problem.
+\def\ifusingit#1#2{\ifdim \fontdimen1\font>0pt #1\else #2\fi}
+
+% Turn off all special characters except @
+% (and those which the user can use as if they were ordinary).
+% Most of these we simply print from the \tt font, but for some, we can
+% use math or other variants that look better in normal text.
+
+\catcode`\"=\active
+\def\activedoublequote{{\tt\char34}}
+\let"=\activedoublequote
+\catcode`\~=\active
+\def~{{\tt\char126}}
+\chardef\hat=`\^
+\catcode`\^=\active
+\def^{{\tt \hat}}
+
+\catcode`\_=\active
+\def_{\ifusingtt\normalunderscore\_}
+\let\realunder=_
+% Subroutine for the previous macro.
+\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em }
+
+\catcode`\|=\active
+\def|{{\tt\char124}}
+\chardef \less=`\<
+\catcode`\<=\active
+\def<{{\tt \less}}
+\chardef \gtr=`\>
+\catcode`\>=\active
+\def>{{\tt \gtr}}
+\catcode`\+=\active
+\def+{{\tt \char 43}}
+\catcode`\$=\active
+\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix
+
+% If a .fmt file is being used, characters that might appear in a file
+% name cannot be active until we have parsed the command line.
+% So turn them off again, and have \everyjob (or @setfilename) turn them on.
+% \otherifyactive is called near the end of this file.
+\def\otherifyactive{\catcode`+=\other \catcode`\_=\other}
+
+% Used sometimes to turn off (effectively) the active characters even after
+% parsing them.
+\def\turnoffactive{%
+ \normalturnoffactive
+ \otherbackslash
+}
+
+\catcode`\@=0
+
+% \backslashcurfont outputs one backslash character in current font,
+% as in \char`\\.
+\global\chardef\backslashcurfont=`\\
+\global\let\rawbackslashxx=\backslashcurfont % let existing .??s files work
+
+% \realbackslash is an actual character `\' with catcode other, and
+% \doublebackslash is two of them (for the pdf outlines).
+{\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}}
+
+% In texinfo, backslash is an active character; it prints the backslash
+% in fixed width font.
+\catcode`\\=\active
+@def@normalbackslash{{@tt@backslashcurfont}}
+% On startup, @fixbackslash assigns:
+% @let \ = @normalbackslash
+
+% \rawbackslash defines an active \ to do \backslashcurfont.
+% \otherbackslash defines an active \ to be a literal `\' character with
+% catcode other.
+@gdef@rawbackslash{@let\=@backslashcurfont}
+@gdef@otherbackslash{@let\=@realbackslash}
+
+% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of
+% the literal character `\'.
+%
+@def@normalturnoffactive{%
+ @let\=@normalbackslash
+ @let"=@normaldoublequote
+ @let~=@normaltilde
+ @let^=@normalcaret
+ @let_=@normalunderscore
+ @let|=@normalverticalbar
+ @let<=@normalless
+ @let>=@normalgreater
+ @let+=@normalplus
+ @let$=@normaldollar %$ font-lock fix
+ @unsepspaces
+}
+
+% Make _ and + \other characters, temporarily.
+% This is canceled by @fixbackslash.
+@otherifyactive
+
+% If a .fmt file is being used, we don't want the `\input texinfo' to show up.
+% That is what \eatinput is for; after that, the `\' should revert to printing
+% a backslash.
+%
+@gdef@eatinput input texinfo{@fixbackslash}
+@global@let\ = @eatinput
+
+% On the other hand, perhaps the file did not have a `\input texinfo'. Then
+% the first `\' in the file would cause an error. This macro tries to fix
+% that, assuming it is called before the first `\' could plausibly occur.
+% Also turn back on active characters that might appear in the input
+% file name, in case not using a pre-dumped format.
+%
+@gdef@fixbackslash{%
+ @ifx\@eatinput @let\ = @normalbackslash @fi
+ @catcode`+=@active
+ @catcode`@_=@active
+}
+
+% Say @foo, not \foo, in error messages.
+@escapechar = `@@
+
+% These look ok in all fonts, so just make them not special.
+@catcode`@& = @other
+@catcode`@# = @other
+@catcode`@% = @other
+
+
+@c Local variables:
+@c eval: (add-hook 'write-file-hooks 'time-stamp)
+@c page-delimiter: "^\\\\message"
+@c time-stamp-start: "def\\\\texinfoversion{"
+@c time-stamp-format: "%:y-%02m-%02d.%02H"
+@c time-stamp-end: "}"
+@c End:
+
+@c vim:sw=2:
+
+@ignore
+ arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@setfilename ../info/tramp
+@c %**start of header
+@settitle TRAMP User Manual
+@setchapternewpage odd
+@c %**end of header
+
+@c This is *so* much nicer :)
+@footnotestyle end
+
+@c In the Tramp CVS, the version number is auto-frobbed from
+@c configure.ac, so you should edit that file and run
+@c "autoconf && ./configure" to change the version number.
+
+@c Additionally, flags are set with respect to the Emacs flavor; and
+@c depending whether Tramp is packaged into (X)Emacs, or standalone.
+
+@include trampver.texi
+
+@c Macro for formatting a filename according to the repective syntax.
+@c xxx and yyy are auxiliary macros in order to omit leading and
+@c trailing whitespace. Not very elegant, but I don't know it better.
+
+@macro xxx {one}@c
+@set \one\@c
+@end macro
+
+@macro yyy {one, two}@c
+@xxx{x\one\}@c
+@ifclear x@c
+\one\@w{}\two\@c
+@end ifclear
+@clear x\one\@c
+@end macro
+
+@macro trampfn {method, user, host, localname}@c
+@value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c
+@end macro
+
+@copying
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
+2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@c Entries for @command{install-info} to use
+@dircategory @value{emacsname}
+@direntry
+* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol
+ @value{emacsname} remote file access via rsh and rcp.
+@end direntry
+
+@tex
+
+@titlepage
+@title @value{tramp} version @value{trampver} User Manual
+
+@author by Daniel Pittman
+@author based on documentation by Kai Gro@ss{}johann
+
+@page
+@insertcopying
+
+@end titlepage
+@page
+
+@end tex
+
+@ifnottex
+@node Top, Overview, (dir), (dir)
+@top @value{tramp} version @value{trampver} User Manual
+
+This file documents @value{tramp} version @value{trampver}, a remote file
+editing package for @value{emacsname}.
+
+@value{tramp} stands for `Transparent Remote (file) Access, Multiple
+Protocol'. This package provides remote file editing, similar to
+@value{ftppackagename}.
+
+The difference is that @value{ftppackagename} uses FTP to transfer
+files between the local and the remote host, whereas @value{tramp} uses a
+combination of @command{rsh} and @command{rcp} or other work-alike
+programs, such as @command{ssh}/@command{scp}.
+
+You can find the latest version of this document on the web at
+@uref{http://www.gnu.org/software/tramp/}.
+
+@c Pointer to the other Emacs flavor is necessary only in case of
+@c standalone installation.
+@ifset installchapter
+The manual has been generated for @value{emacsname}.
+@ifinfo
+If you want to read the info pages for @value{emacsothername}, you
+should read in @ref{Installation} how to create them.
+@end ifinfo
+@ifhtml
+If you're using the other Emacs flavor, you should read the
+@uref{@value{emacsotherfilename}, @value{emacsothername}} pages.
+@end ifhtml
+@end ifset
+
+@ifhtml
+@ifset jamanual
+This manual is also available as a @uref{@value{japanesemanual},
+Japanese translation}.
+@end ifset
+
+The latest release of @value{tramp} is available for
+@uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see
+@ref{Obtaining Tramp} for more details, including the CVS server
+details.
+
+@value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/,
+Savannah Project Page}.
+@end ifhtml
+
+There is a mailing list for @value{tramp}, available at
+@email{tramp-devel@@gnu.org}, and archived at
+@uref{http://lists.gnu.org/archive/html/tramp-devel/, the
+@value{tramp} Mail Archive}.
+@ifhtml
+Older archives are located at
+@uref{http://sourceforge.net/mailarchive/forum.php?forum=tramp-devel,
+SourceForge Mail Archive} and
+@uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/,
+The Mail Archive}.
+@c in HTML output, there's no new paragraph.
+@*@*
+@end ifhtml
+
+@insertcopying
+
+@end ifnottex
+
+@menu
+* Overview:: What @value{tramp} can and cannot do.
+
+For the end user:
+
+* Obtaining Tramp:: How to obtain @value{tramp}.
+* History:: History of @value{tramp}.
+@ifset installchapter
+* Installation:: Installing @value{tramp} with your @value{emacsname}.
+@end ifset
+* Configuration:: Configuring @value{tramp} for use.
+* Usage:: An overview of the operation of @value{tramp}.
+* Bug Reports:: Reporting Bugs and Problems.
+* Frequently Asked Questions:: Questions and answers from the mailing list.
+* Concept Index:: An item for each concept.
+
+For the developer:
+
+* Version Control:: The inner workings of remote version control.
+* Files directories and localnames:: How file names, directories and localnames are mangled and managed.
+* Traces and Profiles:: How to Customize Traces.
+* Issues:: Debatable Issues and What Was Decided.
+
+* GNU Free Documentation License:: The license for this documentation.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+@c
+@ifset installchapter
+Installing @value{tramp} with your @value{emacsname}
+
+* Installation parameters:: Parameters in order to control installation.
+* Load paths:: How to plug-in @value{tramp} into your environment.
+* Japanese manual:: Japanese manual.
+
+@end ifset
+
+Configuring @value{tramp} for use
+
+* Connection types:: Types of connections made to remote machines.
+* Inline methods:: Inline methods.
+* External transfer methods:: External transfer methods.
+@ifset emacsgw
+* Gateway methods:: Gateway methods.
+@end ifset
+* Default Method:: Selecting a default method.
+* Default User:: Selecting a default user.
+* Default Host:: Selecting a default host.
+* Multi-hops:: Connecting to a remote host using multiple hops.
+* Customizing Methods:: Using Non-Standard Methods.
+* Customizing Completion:: Selecting config files for user/host name completion.
+* Password caching:: Reusing passwords for several connections.
+* Connection caching:: Reusing connection related information.
+* Remote Programs:: How @value{tramp} finds and uses programs on the remote machine.
+* Remote shell setup:: Remote shell setup hints.
+* Windows setup hints:: Issues with Cygwin ssh.
+* Auto-save and Backup:: Auto-save and Backup.
+
+Using @value{tramp}
+
+* Filename Syntax:: @value{tramp} filename conventions.
+* Alternative Syntax:: URL-like filename syntax.
+* Filename completion:: Filename completion.
+* Remote processes:: Integration with other @value{emacsname} packages.
+
+The inner workings of remote version control
+
+* Version Controlled Files:: Determining if a file is under version control.
+* Remote Commands:: Executing the version control commands on the remote machine.
+* Changed workfiles:: Detecting if the working file has changed.
+* Checking out files:: Bringing the workfile out of the repository.
+* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere.
+
+Things related to Version Control that don't fit elsewhere
+
+* Remote File Ownership:: How VC determines who owns a workfile.
+* Back-end Versions:: How VC determines what release your RCS is.
+
+How file names, directories and localnames are mangled and managed
+
+* Localname deconstruction:: Breaking a localname into its components.
+
+@end detailmenu
+@end menu
+
+@node Overview
+@chapter An overview of @value{tramp}
+@cindex overview
+
+After the installation of @value{tramp} into your @value{emacsname}, you
+will be able to access files on remote machines as though they were
+local. Access to the remote file system for editing files, version
+control, and @code{dired} are transparently enabled.
+
+Your access to the remote machine can be with the @command{rsh},
+@command{rlogin}, @command{telnet} programs or with any similar
+connection method. This connection must pass @acronym{ASCII}
+successfully to be usable but need not be 8-bit clean.
+
+The package provides support for @command{ssh} connections out of the
+box, one of the more common uses of the package. This allows
+relatively secure access to machines, especially if @command{ftp}
+access is disabled.
+
+The majority of activity carried out by @value{tramp} requires only that
+the remote login is possible and is carried out at the terminal. In
+order to access remote files @value{tramp} needs to transfer their content
+to the local machine temporarily.
+
+@value{tramp} can transfer files between the machines in a variety of ways.
+The details are easy to select, depending on your needs and the
+machines in question.
+
+The fastest transfer methods (for large files) rely on a remote file
+transfer package such as @command{rcp}, @command{scp} or
+@command{rsync}.
+
+If the remote copy methods are not suitable for you, @value{tramp} also
+supports the use of encoded transfers directly through the shell.
+This requires that the @command{mimencode} or @command{uuencode} tools
+are available on the remote machine. These methods are generally
+faster for small files.
+
+Within these limitations, @value{tramp} is quite powerful. It is worth
+noting that, as of the time of writing, it is far from a polished
+end-user product. For a while yet you should expect to run into rough
+edges and problems with the code now and then.
+
+It is finished enough that the developers use it for day to day work but
+the installation and setup can be a little difficult to master, as can
+the terminology.
+
+@value{tramp} is still under active development and any problems you encounter,
+trivial or major, should be reported to the @value{tramp} developers.
+@xref{Bug Reports}.
+
+
+@subsubheading Behind the scenes
+@cindex behind the scenes
+@cindex details of operation
+@cindex how it works
+
+This section tries to explain what goes on behind the scenes when you
+access a remote file through @value{tramp}.
+
+Suppose you type @kbd{C-x C-f} and enter part of an @value{tramp} file name,
+then hit @kbd{@key{TAB}} for completion. Suppose further that this is
+the first time that @value{tramp} is invoked for the host in question. Here's
+what happens:
+
+@itemize
+@item
+@value{tramp} discovers that it needs a connection to the host. So it
+invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l
+@var{user}} or a similar tool to connect to the remote host.
+Communication with this process happens through an
+@value{emacsname} buffer, that is, the output from the remote end
+goes into a buffer.
+
+@item
+The remote host may prompt for a login name (for @command{telnet}).
+The login name is given in the file name, so @value{tramp} sends the
+login name and a newline.
+
+@item
+The remote host may prompt for a password or pass phrase (for
+@command{rsh} or for @command{telnet} after sending the login name).
+@value{tramp} displays the prompt in the minibuffer, asking you for the
+password or pass phrase.
+
+You enter the password or pass phrase. @value{tramp} sends it to the remote
+host, followed by a newline.
+
+@item
+@value{tramp} now waits for the shell prompt or for a message that the login
+failed.
+
+If @value{tramp} sees neither of them after a certain period of time (a minute,
+say), then it issues an error message saying that it couldn't find the
+remote shell prompt and shows you what the remote host has sent.
+
+If @value{tramp} sees a @samp{login failed} message, it tells you so,
+aborts the login attempt and allows you to try again.
+
+@item
+Suppose that the login was successful and @value{tramp} sees the shell prompt
+from the remote host. Now @value{tramp} invokes @command{/bin/sh} because
+Bourne shells and C shells have different command
+syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login
+shell doesn't recognize @samp{exec /bin/sh} as a valid command.
+Maybe you use the Scheme shell @command{scsh}@dots{}}
+
+After the Bourne shell has come up, @value{tramp} sends a few commands to
+ensure a good working environment. It turns off echoing, it sets the
+shell prompt, and a few other things.
+
+@item
+Now the remote shell is up and it good working order. Remember, what
+was supposed to happen is that @value{tramp} tries to find out what files exist
+on the remote host so that it can do filename completion.
+
+So, @value{tramp} basically issues @command{cd} and @command{ls} commands and
+also sometimes @command{echo} with globbing. Another command that is
+often used is @command{test} to find out whether a file is writable or a
+directory or the like. The output of each command is parsed for the
+necessary operation.
+
+@item
+Suppose you are finished with filename completion, have entered @kbd{C-x
+C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to
+transfer the file contents from the remote host to the local host so
+that you can edit them.
+
+See above for an explanation of how @value{tramp} transfers the file contents.
+
+For inline transfers, @value{tramp} issues a command like @samp{mimencode -b
+/path/to/remote/file}, waits until the output has accumulated in the
+buffer that's used for communication, then decodes that output to
+produce the file contents.
+
+For out-of-band transfers, @value{tramp} issues a command like the following:
+@example
+rcp user@@host:/path/to/remote/file /tmp/tramp.4711
+@end example
+It then reads the local temporary file @file{/tmp/tramp.4711} into a
+buffer and deletes the temporary file.
+
+@item
+You now edit the buffer contents, blithely unaware of what has happened
+behind the scenes. (Unless you have read this section, that is.) When
+you are finished, you type @kbd{C-x C-s} to save the buffer.
+
+@item
+Again, @value{tramp} transfers the file contents to the remote host either
+inline or out-of-band. This is the reverse of what happens when reading
+the file.
+@end itemize
+
+I hope this has provided you with a basic overview of what happens
+behind the scenes when you open a file with @value{tramp}.
+
+
+@c For the end user
+@node Obtaining Tramp
+@chapter Obtaining Tramp.
+@cindex obtaining Tramp
+
+@value{tramp} is freely available on the Internet and the latest
+release may be downloaded from
+@uref{ftp://ftp.gnu.org/gnu/tramp/}. This release includes the full
+documentation and code for @value{tramp}, suitable for installation.
+But GNU Emacs (22 or later) includes @value{tramp} already, and there
+is a @value{tramp} package for XEmacs, as well. So maybe it is easier
+to just use those. But if you want the bleeding edge, read
+on@dots{...}
+
+For the especially brave, @value{tramp} is available from CVS. The CVS
+version is the latest version of the code and may contain incomplete
+features or new issues. Use these versions at your own risk.
+
+Instructions for obtaining the latest development version of @value{tramp}
+from CVS can be found by going to the Savannah project page at the
+following URL and then clicking on the CVS link in the navigation bar
+at the top.
+
+@noindent
+@uref{http://savannah.gnu.org/projects/tramp/}
+
+@noindent
+Or follow the example session below:
+
+@example
+] @strong{cd ~/@value{emacsdir}}
+] @strong{export CVS_RSH="ssh"}
+] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp}
+@end example
+
+@noindent
+You should now have a directory @file{~/@value{emacsdir}/tramp}
+containing the latest version of @value{tramp}. You can fetch the latest
+updates from the repository by issuing the command:
+
+@example
+] @strong{cd ~/@value{emacsdir}/tramp}
+] @strong{export CVS_RSH="ssh"}
+] @strong{cvs update -d}
+@end example
+
+@noindent
+Once you've got updated files from the CVS repository, you need to run
+@command{autoconf} in order to get an up-to-date @file{configure}
+script:
+
+@example
+] @strong{cd ~/@value{emacsdir}/tramp}
+] @strong{autoconf}
+@end example
+
+People who have no direct CVS access (maybe because sitting behind a
+blocking firewall), can try the
+@uref{http://savannah.gnu.org/cvs-backup/tramp-sources.tar.gz, Nightly
+CVS Tree Tarball} instead of.
+
+
+@node History
+@chapter History of @value{tramp}
+@cindex history
+@cindex development history
+
+Development was started end of November 1998. The package was called
+@file{rssh.el}, back then. It only provided one method to access a
+file, using @command{ssh} to log in to a remote host and using
+@command{scp} to transfer the file contents. After a while, the name
+was changed to @file{rcp.el}, and now it's @value{tramp}. Along the way,
+many more methods for getting a remote shell and for transferring the
+file contents were added. Support for VC was added.
+
+The most recent addition of major features were the multi-hop methods
+added in April 2000 and the unification of @value{tramp} and Ange-FTP
+filenames in July 2002. In July 2004, multi-hop methods have been
+replaced by proxy hosts. Running commands on remote hosts was
+introduced in December 2005.
+@ifset emacsgw
+Support of gateways exists since April 2007.
+@end ifset
+
+In December 2001, @value{tramp} has been added to the XEmacs package
+repository. Being part of the GNU Emacs repository happened in June
+2002, the first release including @value{tramp} was GNU Emacs 22.1.
+
+@value{tramp} is also a GNU/Linux Debian package since February 2001.
+
+
+@c Installation chapter is necessary only in case of standalone
+@c installation. Text taken from trampinst.texi.
+@ifset installchapter
+@include trampinst.texi
+@end ifset
+
+@node Configuration
+@chapter Configuring @value{tramp} for use
+@cindex configuration
+
+@cindex default configuration
+@value{tramp} is (normally) fully functional when it is initially
+installed. It is initially configured to use the @command{scp}
+program to connect to the remote host. So in the easiest case, you
+just type @kbd{C-x C-f} and then enter the filename
+@file{@trampfn{, user, machine, /path/to.file}}.
+
+On some hosts, there are problems with opening a connection. These are
+related to the behavior of the remote shell. See @xref{Remote shell
+setup}, for details on this.
+
+If you do not wish to use these commands to connect to the remote
+host, you should change the default connection and transfer method
+that @value{tramp} uses. There are several different methods that @value{tramp}
+can use to connect to remote machines and transfer files
+(@pxref{Connection types}).
+
+If you don't know which method is right for you, see @xref{Default
+Method}.
+
+
+@menu
+* Connection types:: Types of connections made to remote machines.
+* Inline methods:: Inline methods.
+* External transfer methods:: External transfer methods.
+@ifset emacsgw
+* Gateway methods:: Gateway methods.
+@end ifset
+* Default Method:: Selecting a default method.
+ Here we also try to help those who
+ don't have the foggiest which method
+ is right for them.
+* Default User:: Selecting a default user.
+* Default Host:: Selecting a default host.
+* Multi-hops:: Connecting to a remote host using multiple hops.
+* Customizing Methods:: Using Non-Standard Methods.
+* Customizing Completion:: Selecting config files for user/host name completion.
+* Password caching:: Reusing passwords for several connections.
+* Connection caching:: Reusing connection related information.
+* Remote Programs:: How @value{tramp} finds and uses programs on the remote machine.
+* Remote shell setup:: Remote shell setup hints.
+* Windows setup hints:: Issues with Cygwin ssh.
+* Auto-save and Backup:: Auto-save and Backup.
+@end menu
+
+
+@node Connection types
+@section Types of connections made to remote machines.
+@cindex connection types, overview
+
+There are two basic types of transfer methods, each with its own
+advantages and limitations. Both types of connection make use of a
+remote shell access program such as @command{rsh}, @command{ssh} or
+@command{telnet} to connect to the remote machine.
+
+This connection is used to perform many of the operations that @value{tramp}
+requires to make the remote file system transparently accessible from
+the local machine. It is only when visiting files that the methods
+differ.
+
+@cindex inline methods
+@cindex external transfer methods
+@cindex external methods
+@cindex out-of-band methods
+@cindex methods, inline
+@cindex methods, external transfer
+@cindex methods, out-of-band
+Loading or saving a remote file requires that the content of the file
+be transfered between the two machines. The content of the file can be
+transfered over the same connection used to log in to the remote
+machine or the file can be transfered through another connection using
+a remote copy program such as @command{rcp}, @command{scp} or
+@command{rsync}. The former are called @dfn{inline methods}, the
+latter are called @dfn{out-of-band methods} or @dfn{external transfer
+methods} (@dfn{external methods} for short).
+
+The performance of the external transfer methods is generally better
+than that of the inline methods, at least for large files. This is
+caused by the need to encode and decode the data when transferring
+inline.
+
+The one exception to this rule are the @command{scp} based transfer
+methods. While these methods do see better performance when actually
+transferring files, the overhead of the cryptographic negotiation at
+startup may drown out the improvement in file transfer times.
+
+External transfer methods should be configured such a way that they
+don't require a password (with @command{ssh-agent}, or such alike).
+Modern @command{scp} implementations offer options to reuse existing
+@command{ssh} connections, see method @command{scpc}. If it isn't
+possible, you should consider @ref{Password caching}, otherwise you
+will be prompted for a password every copy action.
+
+
+@node Inline methods
+@section Inline methods
+@cindex inline methods
+@cindex methods, inline
+
+The inline methods in @value{tramp} are quite powerful and can work in
+situations where you cannot use an external transfer program to connect.
+Inline methods are the only methods that work when connecting to the
+remote machine via telnet. (There are also strange inline methods which
+allow you to transfer files between @emph{user identities} rather than
+hosts, see below.)
+
+These methods depend on the existence of a suitable encoding and
+decoding command on remote machine. Locally, @value{tramp} may be able to
+use features of @value{emacsname} to decode and encode the files or
+it may require access to external commands to perform that task.
+
+@cindex uuencode
+@cindex mimencode
+@cindex base-64 encoding
+@value{tramp} checks the availability and usability of commands like
+@command{mimencode} (part of the @command{metamail} package) or
+@command{uuencode} on the remote host. The first reliable command
+will be used. The search path can be customized, see @ref{Remote
+Programs}.
+
+If both commands aren't available on the remote host, @value{tramp}
+transfers a small piece of Perl code to the remote host, and tries to
+apply it for encoding and decoding.
+
+
+@table @asis
+@item @option{rsh}
+@cindex method rsh
+@cindex rsh method
+
+Connect to the remote host with @command{rsh}. Due to the unsecure
+connection it is recommended for very local host topology only.
+
+On operating systems which provide the command @command{remsh} instead
+of @command{rsh}, you can use the method @option{remsh}. This is true
+for HP-UX or Cray UNICOS, for example.
+
+
+@item @option{ssh}
+@cindex method ssh
+@cindex ssh method
+
+Connect to the remote host with @command{ssh}. This is identical to
+the previous option except that the @command{ssh} package is used,
+making the connection more secure.
+
+There are also two variants, @option{ssh1} and @option{ssh2}, that
+call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
+explicitly select whether you want to use the SSH protocol version 1
+or 2 to connect to the remote host. (You can also specify in
+@file{~/.ssh/config}, the SSH configuration file, which protocol
+should be used, and use the regular @option{ssh} method.)
+
+Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the
+@command{ssh1} and @command{ssh2} commands explicitly. If you don't
+know what these are, you do not need these options.
+
+All the methods based on @command{ssh} have an additional kludgy
+feature: you can specify a host name which looks like @file{host#42}
+(the real host name, then a hash sign, then a port number). This
+means to connect to the given host but to also pass @code{-p 42} as
+arguments to the @command{ssh} command.
+
+
+@item @option{telnet}
+@cindex method telnet
+@cindex telnet method
+
+Connect to the remote host with @command{telnet}. This is as unsecure
+as the @option{rsh} method.
+
+
+@item @option{su}
+@cindex method su
+@cindex su method
+
+This method does not connect to a remote host at all, rather it uses
+the @command{su} program to allow you to edit files as another user.
+With other words, a specified host name in the file name is silently
+ignored.
+
+
+@item @option{sudo}
+@cindex method sudo
+@cindex sudo method
+
+This is similar to the @option{su} method, but it uses @command{sudo}
+rather than @command{su} to become a different user.
+
+Note that @command{sudo} must be configured to allow you to start a
+shell as the user. It would be nice if it was sufficient if
+@command{ls} and @command{mimencode} were allowed, but that is not
+easy to implement, so I haven't got around to it, yet.
+
+
+@item @option{sshx}
+@cindex method sshx
+@cindex sshx method
+
+As you would expect, this is similar to @option{ssh}, only a little
+different. Whereas @option{ssh} opens a normal interactive shell on
+the remote host, this option uses @samp{ssh -t -t @var{host} -l
+@var{user} /bin/sh} to open a connection. This is useful for users
+where the normal login shell is set up to ask them a number of
+questions when logging in. This procedure avoids these questions, and
+just gives @value{tramp} a more-or-less `standard' login shell to work
+with.
+
+Note that this procedure does not eliminate questions asked by
+@command{ssh} itself. For example, @command{ssh} might ask ``Are you
+sure you want to continue connecting?'' if the host key of the remote
+host is not known. @value{tramp} does not know how to deal with such a
+question (yet), therefore you will need to make sure that you can log
+in without such questions.
+
+This is also useful for Windows users where @command{ssh}, when
+invoked from an @value{emacsname} buffer, tells them that it is not
+allocating a pseudo tty. When this happens, the login shell is wont
+to not print any shell prompt, which confuses @value{tramp} mightily.
+For reasons unknown, some Windows ports for @command{ssh} require the
+doubled @samp{-t} option.
+
+This supports the @samp{-p} kludge.
+
+
+@item @option{krlogin}
+@cindex method krlogin
+@cindex krlogin method
+@cindex Kerberos (with krlogin method)
+
+This method is also similar to @option{ssh}. It only uses the
+@command{krlogin -x} command to log in to the remote host.
+
+
+@item @option{plink}
+@cindex method plink
+@cindex plink method
+
+This method is mostly interesting for Windows users using the PuTTY
+implementation of SSH. It uses @samp{plink -ssh} to log in to the
+remote host.
+
+This supports the @samp{-P} kludge.
+
+Additionally, the methods @option{plink1} and @option{plink2} are
+provided, which call @samp{plink -1 -ssh} or @samp{plink -2 -ssh} in
+order to use SSH protocol version 1 or 2 explicitly.
+
+CCC: Do we have to connect to the remote host once from the command
+line to accept the SSH key? Maybe this can be made automatic?
+
+CCC: Say something about the first shell command failing. This might
+be due to a wrong setting of @code{tramp-rsh-end-of-line}.
+
+
+@item @option{plinkx}
+@cindex method plinkx
+@cindex plinkx method
+
+Another method using PuTTY on Windows. Instead of host names, it
+expects PuTTY session names, calling @samp{plink -load @var{session}
+-t"}. User names are relevant only in case the corresponding session
+hasn't defined a user name. Different port numbers must be defined in
+the session.
+
+
+@item @option{fish}
+@cindex method fish
+@cindex fish method
+
+This is an experimental implementation of the fish protocol, known from
+the GNU Midnight Commander or the KDE Konqueror. @value{tramp} expects
+the fish server implementation from the KDE kioslave. That means, the
+file @file{~/.fishsrv.pl} is expected to reside on the remote host.
+
+The implementation lacks good performance. The code is offered anyway,
+maybe somebody can improve the performance.
+
+@end table
+
+
+@node External transfer methods
+@section External transfer methods
+@cindex methods, external transfer
+@cindex methods, out-of-band
+@cindex external transfer methods
+@cindex out-of-band methods
+
+The external transfer methods operate through multiple channels, using
+the remote shell connection for many actions while delegating file
+transfers to an external transfer utility.
+
+This saves the overhead of encoding and decoding that multiplexing the
+transfer through the one connection has with the inline methods.
+
+Since external transfer methods need their own overhead opening a new
+channel, all files which are smaller than @var{tramp-copy-size-limit}
+are still transferred with the corresponding inline method. It should
+provide a fair trade-off between both approaches.
+
+@table @asis
+@item @option{rcp} --- @command{rsh} and @command{rcp}
+@cindex method rcp
+@cindex rcp method
+@cindex rcp (with rcp method)
+@cindex rsh (with rcp method)
+
+This method uses the @command{rsh} and @command{rcp} commands to connect
+to the remote machine and transfer files. This is probably the fastest
+connection method available.
+
+The alternative method @option{remcp} uses the @command{remsh} and
+@command{rcp} commands. It should be applied on machines where
+@command{remsh} is used instead of @command{rsh}.
+
+
+@item @option{scp} --- @command{ssh} and @command{scp}
+@cindex method scp
+@cindex scp method
+@cindex scp (with scp method)
+@cindex ssh (with scp method)
+
+Using @command{ssh} to connect to the remote host and @command{scp} to
+transfer files between the machines is the best method for securely
+connecting to a remote machine and accessing files.
+
+The performance of this option is also quite good. It may be slower than
+the inline methods when you often open and close small files however.
+The cost of the cryptographic handshake at the start of an @command{scp}
+session can begin to absorb the advantage that the lack of encoding and
+decoding presents.
+
+There are also two variants, @option{scp1} and @option{scp2}, that
+call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can
+explicitly select whether you want to use the SSH protocol version 1
+or 2 to connect to the remote host. (You can also specify in
+@file{~/.ssh/config}, the SSH configuration file, which protocol
+should be used, and use the regular @option{scp} method.)
+
+Two other variants, @option{scp1_old} and @option{scp2_old}, use the
+@command{ssh1} and @command{ssh2} commands explicitly. If you don't
+know what these are, you do not need these options.
+
+All the @command{ssh} based methods support the kludgy @samp{-p}
+feature where you can specify a port number to connect to in the host
+name. For example, the host name @file{host#42} tells @value{tramp} to
+specify @samp{-p 42} in the argument list for @command{ssh}, and to
+specify @samp{-P 42} in the argument list for @command{scp}.
+
+
+@item @option{sftp} --- @command{ssh} and @command{sftp}
+@cindex method sftp
+@cindex sftp method
+@cindex sftp (with sftp method)
+@cindex ssh (with sftp method)
+
+That is mostly the same method as @option{scp}, but using
+@command{sftp} as transfer command. So the same remarks are valid.
+
+This command does not work like @value{ftppackagename}, where
+@command{ftp} is called interactively, and all commands are send from
+within this session. Instead of, @command{ssh} is used for login.
+
+This method supports the @samp{-p} hack.
+
+
+@item @option{rsync} --- @command{ssh} and @command{rsync}
+@cindex method rsync
+@cindex rsync method
+@cindex rsync (with rsync method)
+@cindex ssh (with rsync method)
+
+Using the @command{ssh} command to connect securely to the remote
+machine and the @command{rsync} command to transfer files is almost
+identical to the @option{scp} method.
+
+While @command{rsync} performs much better than @command{scp} when
+transferring files that exist on both hosts, this advantage is lost if
+the file exists only on one side of the connection.
+
+The @command{rsync} based method may be considerably faster than the
+@command{rcp} based methods when writing to the remote system. Reading
+files to the local machine is no faster than with a direct copy.
+
+This method supports the @samp{-p} hack.
+
+
+@item @option{scpx} --- @command{ssh} and @command{scp}
+@cindex method scpx
+@cindex scpx method
+@cindex scp (with scpx method)
+@cindex ssh (with scpx method)
+
+As you would expect, this is similar to @option{scp}, only a little
+different. Whereas @option{scp} opens a normal interactive shell on
+the remote host, this option uses @samp{ssh -t -t @var{host} -l
+@var{user} /bin/sh} to open a connection. This is useful for users
+where the normal login shell is set up to ask them a number of
+questions when logging in. This procedure avoids these questions, and
+just gives @value{tramp} a more-or-less `standard' login shell to work
+with.
+
+This is also useful for Windows users where @command{ssh}, when
+invoked from an @value{emacsname} buffer, tells them that it is not
+allocating a pseudo tty. When this happens, the login shell is wont
+to not print any shell prompt, which confuses @value{tramp} mightily.
+
+This method supports the @samp{-p} hack.
+
+
+@item @option{scpc} --- @command{ssh} and @command{scp}
+@cindex method scpx
+@cindex scpx method
+@cindex scp (with scpx method)
+@cindex ssh (with scpx method)
+
+Newer versions of @option{ssh} (for example OpenSSH 4) offer an option
+@option{ControlMaster}. This allows @option{scp} to reuse an existing
+@option{ssh} channel, which increases performance.
+
+Before you use this method, you shall check whether your @option{ssh}
+implementation does support this option. Try from the command line
+
+@example
+ssh localhost -o ControlMaster=yes
+@end example
+
+This method supports the @samp{-p} hack.
+
+
+@item @option{pscp} --- @command{plink} and @command{pscp}
+@cindex method pscp
+@cindex pscp method
+@cindex pscp (with pscp method)
+@cindex plink (with pscp method)
+@cindex PuTTY (with pscp method)
+
+This method is similar to @option{scp}, but it uses the
+@command{plink} command to connect to the remote host, and it uses
+@command{pscp} for transferring the files. These programs are part
+of PuTTY, an SSH implementation for Windows.
+
+This method supports the @samp{-P} hack.
+
+
+@item @option{psftp} --- @command{plink} and @command{psftp}
+@cindex method psftp
+@cindex psftp method
+@cindex psftp (with psftp method)
+@cindex plink (with psftp method)
+@cindex PuTTY (with psftp method)
+
+As you would expect, this method is similar to @option{sftp}, but it
+uses the @command{plink} command to connect to the remote host, and it
+uses @command{psftp} for transferring the files. These programs are
+part of PuTTY, an SSH implementation for Windows.
+
+This method supports the @samp{-P} hack.
+
+
+@item @option{fcp} --- @command{fsh} and @command{fcp}
+@cindex method fcp
+@cindex fcp method
+@cindex fsh (with fcp method)
+@cindex fcp (with fcp method)
+
+This method is similar to @option{scp}, but it uses the @command{fsh}
+command to connect to the remote host, and it uses @command{fcp} for
+transferring the files. @command{fsh/fcp} are a front-end for
+@command{ssh} which allow for reusing the same @command{ssh} session
+for submitting several commands. This avoids the startup overhead of
+@command{scp} (which has to establish a secure connection whenever it
+is called). Note, however, that you can also use one of the inline
+methods to achieve a similar effect.
+
+This method uses the command @samp{fsh @var{host} -l @var{user}
+/bin/sh -i} to establish the connection, it does not work to just say
+@command{fsh @var{host} -l @var{user}}.
+
+@cindex method fsh
+@cindex fsh method
+
+There is no inline method using @command{fsh} as the multiplexing
+provided by the program is not very useful in our context. @value{tramp}
+opens just one connection to the remote host and then keeps it open,
+anyway.
+
+
+@item @option{ftp}
+@cindex method ftp
+@cindex ftp method
+
+This is not a native @value{tramp} method. Instead of, it forwards all
+requests to @value{ftppackagename}.
+@ifset xemacs
+This works only for unified filenames, see @ref{Issues}.
+@end ifset
+
+
+@item @option{smb} --- @command{smbclient}
+@cindex method smb
+@cindex smb method
+
+This is another not natural @value{tramp} method. It uses the
+@command{smbclient} command on different Unices in order to connect to
+an SMB server. An SMB server might be a Samba (or CIFS) server on
+another UNIX host or, more interesting, a host running MS Windows. So
+far, it is tested towards MS Windows NT, MS Windows 2000, and MS
+Windows XP.
+
+The first directory in the localname must be a share name on the remote
+host. Remember, that the @code{$} character in which default shares
+usually end, must be written @code{$$} due to environment variable
+substitution in file names. If no share name is given (i.e. remote
+directory @code{/}), all available shares are listed.
+
+Since authorization is done on share level, you will be prompted
+always for a password if you access another share on the same host.
+This can be suppressed by @ref{Password caching}.
+
+MS Windows uses for authorization both a user name and a domain name.
+Because of this, the @value{tramp} syntax has been extended: you can
+specify a user name which looks like @code{user%domain} (the real user
+name, then a percent sign, then the domain name). So, to connect to
+the machine @code{melancholia} as user @code{daniel} of the domain
+@code{BIZARRE}, and edit @file{.emacs} in the home directory (share
+@code{daniel$}) I would specify the filename @file{@trampfn{smb,
+daniel%BIZARRE, melancholia, /daniel$$/.emacs}}.
+
+Depending on the Windows domain configuration, a Windows user might be
+considered as domain user per default. In order to connect as local
+user, the WINS name of that machine must be given as domain name.
+Usually, it is the machine name in capital letters. In the example
+above, the local user @code{daniel} would be specified as
+@file{@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}}.
+
+The domain name as well as the user name are optional. If no user
+name is specified at all, the anonymous user (without password
+prompting) is assumed. This is different from all other @value{tramp}
+methods, where in such a case the local user name is taken.
+
+The @option{smb} method supports the @samp{-p} hack.
+
+@strong{Please note:} If @value{emacsname} runs locally under MS
+Windows, this method isn't available. Instead of, you can use UNC
+file names like @file{//melancholia/daniel$$/.emacs}. The only
+disadvantage is that there's no possibility to specify another user
+name.
+
+@end table
+
+
+@ifset emacsgw
+@node Gateway methods
+@section Gateway methods
+@cindex methods, gateway
+@cindex gateway methods
+
+Gateway methods are not methods to access a remote host directly.
+These methods are intended to pass firewalls or proxy servers.
+Therefore, they can be used for proxy host declarations
+(@pxref{Multi-hops}) only.
+
+A gateway method must come always along with a method who supports
+port setting (referred to as @samp{-p} kludge). This is because
+@value{tramp} targets the accompanied method to
+@file{localhost#random_port}, from where the firewall or proxy server
+is accessed to.
+
+Gateway methods support user name and password declarations. These
+are used to authenticate towards the corresponding firewall or proxy
+server. They can be passed only if your friendly administrator has
+granted your access.
+
+@table @asis
+@item @option{tunnel}
+@cindex method tunnel
+@cindex tunnel method
+
+This method implements an HTTP tunnel via the @command{CONNECT}
+command (see RFC 2616, 2817). Any HTTP 1.1 compliant (proxy) server
+shall support this command.
+
+As authentication method, only @option{Basic Authentication} (see RFC
+2617) is implemented so far. If no port number is given in the
+declaration, port @option{8080} is used for the proxy server.
+
+
+@item @option{socks}
+@cindex method socks
+@cindex socks method
+
+The @command{socks} method provides access to SOCKSv5 servers (see
+RFC 1928). @option{Username/Password Authentication} according to RFC
+1929 is supported.
+
+The default port number of the socks server is @option{1080}, if not
+specified otherwise.
+
+@end table
+@end ifset
+
+
+@node Default Method
+@section Selecting a default method
+@cindex default method
+
+@vindex tramp-default-method
+When you select an appropriate transfer method for your typical usage
+you should set the variable @code{tramp-default-method} to reflect that
+choice. This variable controls which method will be used when a method
+is not specified in the @value{tramp} file name. For example:
+
+@lisp
+(setq tramp-default-method "ssh")
+@end lisp
+
+@vindex tramp-default-method-alist
+You can also specify different methods for certain user/host
+combinations, via the variable @code{tramp-default-method-alist}. For
+example, the following two lines specify to use the @option{ssh}
+method for all user names matching @samp{john} and the @option{rsync}
+method for all host names matching @samp{lily}. The third line
+specifies to use the @option{su} method for the user @samp{root} on
+the machine @samp{localhost}.
+
+@lisp
+(add-to-list 'tramp-default-method-alist '("" "john" "ssh"))
+(add-to-list 'tramp-default-method-alist '("lily" "" "rsync"))
+(add-to-list 'tramp-default-method-alist
+ '("\\`localhost\\'" "\\`root\\'" "su"))
+@end lisp
+
+@noindent
+See the documentation for the variable
+@code{tramp-default-method-alist} for more details.
+
+External transfer methods are normally preferable to inline transfer
+methods, giving better performance.
+
+@xref{Inline methods}.
+@xref{External transfer methods}.
+
+Another consideration with the selection of transfer methods is the
+environment you will use them in and, especially when used over the
+Internet, the security implications of your preferred method.
+
+The @option{rsh} and @option{telnet} methods send your password as
+plain text as you log in to the remote machine, as well as
+transferring the files in such a way that the content can easily be
+read from other machines.
+
+If you need to connect to remote systems that are accessible from the
+Internet, you should give serious thought to using @option{ssh} based
+methods to connect. These provide a much higher level of security,
+making it a non-trivial exercise for someone to obtain your password
+or read the content of the files you are editing.
+
+
+@subsection Which method is the right one for me?
+@cindex choosing the right method
+
+Given all of the above, you are probably thinking that this is all fine
+and good, but it's not helping you to choose a method! Right you are.
+As a developer, we don't want to boss our users around but give them
+maximum freedom instead. However, the reality is that some users would
+like to have some guidance, so here I'll try to give you this guidance
+without bossing you around. You tell me whether it works @dots{}
+
+My suggestion is to use an inline method. For large files, out-of-band
+methods might be more efficient, but I guess that most people will want
+to edit mostly small files.
+
+I guess that these days, most people can access a remote machine by
+using @command{ssh}. So I suggest that you use the @option{ssh}
+method. So, type @kbd{C-x C-f @trampfn{ssh, root, otherhost,
+/etc/motd} @key{RET}} to edit the @file{/etc/motd} file on the other
+host.
+
+If you can't use @option{ssh} to log in to the remote host, then
+select a method that uses a program that works. For instance, Windows
+users might like the @option{plink} method which uses the PuTTY
+implementation of @command{ssh}. Or you use Kerberos and thus like
+@option{krlogin}.
+
+For the special case of editing files on the local host as another
+user, see the @option{su} or @option{sudo} methods. They offer
+shortened syntax for the @samp{root} account, like
+@file{@trampfn{su, , , /etc/motd}}.
+
+People who edit large files may want to consider @option{scpc} instead
+of @option{ssh}, or @option{pscp} instead of @option{plink}. These
+out-of-band methods are faster than inline methods for large files.
+Note, however, that out-of-band methods suffer from some limitations.
+Please try first whether you really get a noticeable speed advantage
+from using an out-of-band method! Maybe even for large files, inline
+methods are fast enough.
+
+
+@node Default User
+@section Selecting a default user
+@cindex default user
+
+The user part of a @value{tramp} file name can be omitted. Usually,
+it is replaced by the user name you are logged in. Often, this is not
+what you want. A typical use of @value{tramp} might be to edit some
+files with root permissions on the local host. This case, you should
+set the variable @code{tramp-default-user} to reflect that choice.
+For example:
+
+@lisp
+(setq tramp-default-user "root")
+@end lisp
+
+@code{tramp-default-user} is regarded as obsolete, and will be removed
+soon.
+
+@vindex tramp-default-user-alist
+You can also specify different users for certain method/host
+combinations, via the variable @code{tramp-default-user-alist}. For
+example, if you always have to use the user @samp{john} in the domain
+@samp{somewhere.else}, you can specify the following:
+
+@lisp
+(add-to-list 'tramp-default-user-alist
+ '("ssh" ".*\\.somewhere\\.else\\'" "john"))
+@end lisp
+
+@noindent
+See the documentation for the variable
+@code{tramp-default-user-alist} for more details.
+
+One trap to fall in must be known. If @value{tramp} finds a default
+user, this user will be passed always to the connection command as
+parameter (for example @samp{ssh here.somewhere.else -l john}. If you
+have specified another user for your command in its configuration
+files, @value{tramp} cannot know it, and the remote access will fail.
+If you have specified in the given example in @file{~/.ssh/config} the
+lines
+
+@example
+Host here.somewhere.else
+ User lily
+@end example
+
+@noindent
+than you must discard selecting a default user by @value{tramp}. This
+will be done by setting it to @code{nil} (or @samp{lily}, likewise):
+
+@lisp
+(add-to-list 'tramp-default-user-alist
+ '("ssh" "\\`here\\.somewhere\\.else\\'" nil))
+@end lisp
+
+The last entry in @code{tramp-default-user-alist} could be your
+default user you'll apply predominantly. You shall @emph{append} it
+to that list at the end:
+
+@lisp
+(add-to-list 'tramp-default-user-alist '(nil nil "jonas") t)
+@end lisp
+
+
+@node Default Host
+@section Selecting a default host
+@cindex default host
+
+@vindex tramp-default-host
+Finally, it is even possible to omit the host name part of a
+@value{tramp} file name. This case, the value of the variable
+@code{tramp-default-host} is used. Per default, it is initialized
+with the host name your local @value{emacsname} is running.
+
+If you, for example, use @value{tramp} mainly to contact the host
+@samp{target} as user @samp{john}, you can specify:
+
+@lisp
+(setq tramp-default-user "john"
+ tramp-default-host "target")
+@end lisp
+
+Then the simple file name @samp{@trampfn{ssh, , ,}} will connect you
+to John's home directory on target.
+@ifset emacs
+Note, however, that the most simplification @samp{/::} won't work,
+because @samp{/:} is the prefix for quoted file names.
+@end ifset
+
+
+@node Multi-hops
+@section Connecting to a remote host using multiple hops
+@cindex multi-hop
+@cindex proxy hosts
+
+Sometimes, the methods described before are not sufficient. Sometimes,
+it is not possible to connect to a remote host using a simple command.
+For example, if you are in a secured network, you might have to log in
+to a `bastion host' first before you can connect to the outside world.
+Of course, the target host may also require a bastion host.
+
+@vindex tramp-default-proxies-alist
+In order to specify such multiple hops, it is possible to define a proxy
+host to pass through, via the variable
+@code{tramp-default-proxies-alist}. This variable keeps a list of
+triples (@var{host} @var{user} @var{proxy}).
+
+ The first matching item specifies the proxy host to be passed for a
+file name located on a remote target matching @var{user}@@@var{host}.
+@var{host} and @var{user} are regular expressions or @code{nil}, which
+is interpreted as a regular expression which always matches.
+
+@var{proxy} must be a Tramp filename which localname part is ignored.
+Method and user name on @var{proxy} are optional, which is interpreted
+with the default values.
+@ifset emacsgw
+The method must be an inline or gateway method (@pxref{Inline
+methods}, @pxref{Gateway methods}).
+@end ifset
+@ifclear emacsgw
+The method must be an inline method (@pxref{Inline methods}).
+@end ifclear
+If @var{proxy} is @code{nil}, no additional hop is required reaching
+@var{user}@@@var{host}.
+
+If you, for example, must pass the host @samp{bastion.your.domain} as
+user @samp{bird} for any remote host which is not located in your local
+domain, you can set
+
+@lisp
+(add-to-list 'tramp-default-proxies-alist
+ '("\\." nil "@trampfn{ssh, bird, bastion.your.domain,}"))
+(add-to-list 'tramp-default-proxies-alist
+ '("\\.your\\.domain\\'" nil nil))
+@end lisp
+
+Please note the order of the code. @code{add-to-list} adds elements at the
+beginning of a list. Therefore, most relevant rules must be added last.
+
+Proxy hosts can be cascaded. If there is another host called
+@samp{jump.your.domain}, which is the only one in your local domain who
+is allowed connecting @samp{bastion.your.domain}, you can add another
+rule:
+
+@lisp
+(add-to-list 'tramp-default-proxies-alist
+ '("\\`bastion\\.your\\.domain\\'"
+ "\\`bird\\'"
+ "@trampfn{ssh, , jump.your.domain,}"))
+@end lisp
+
+@var{proxy} can contain the patterns @code{%h} or @code{%u}. These
+patterns are replaced by the strings matching @var{host} or
+@var{user}, respectively.
+
+If you, for example, wants to work as @samp{root} on hosts in the
+domain @samp{your.domain}, but login as @samp{root} is disabled for
+non-local access, you might add the following rule:
+
+@lisp
+(add-to-list 'tramp-default-proxies-alist
+ '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}"))
+@end lisp
+
+Opening @file{@trampfn{sudo, , randomhost.your.domain,}} would connect
+first @samp{randomhost.your.domain} via @code{ssh} under your account
+name, and perform @code{sudo -u root} on that host afterwards. It is
+important to know that the given method is applied on the host which
+has been reached so far. @code{sudo -u root}, applied on your local
+host, wouldn't be useful here.
+
+This is the recommended configuration to work as @samp{root} on remote
+Ubuntu hosts.
+
+@ifset emacsgw
+Finally, @code{tramp-default-proxies-alist} can be used to pass
+firewalls or proxy servers. Imagine your local network has a host
+@samp{proxy.your.domain} which is used on port 3128 as HTTP proxy to
+the outer world. Your friendly administrator has granted you access
+under your user name to @samp{host.other.domain} on that proxy
+server.@footnote{HTTP tunnels are intended for secure SSL/TLS
+communication. Therefore, many proxy server restrict the tunnels to
+related target ports. You might need to run your ssh server on your
+target host @samp{host.other.domain} on such a port, like 443 (https).
+See @uref{http://savannah.gnu.org/maintenance/CvsFromBehindFirewall}
+for discussion of ethical issues.} You would need to add the
+following rule:
+
+@lisp
+(add-to-list 'tramp-default-proxies-alist
+ '("\\`host\\.other\\.domain\\'" nil
+ "@trampfn{tunnel, , proxy.your.domain#3128,}"))
+@end lisp
+
+Gateway methods can be declared as first hop only in a multiple hop
+chain.
+@end ifset
+
+
+@node Customizing Methods
+@section Using Non-Standard Methods
+@cindex customizing methods
+@cindex using non-standard methods
+@cindex create your own methods
+
+There is a variable @code{tramp-methods} which you can change if the
+predefined methods don't seem right.
+
+For the time being, I'll refer you to the Lisp documentation of that
+variable, accessible with @kbd{C-h v tramp-methods @key{RET}}.
+
+
+@node Customizing Completion
+@section Selecting config files for user/host name completion
+@cindex customizing completion
+@cindex selecting config files
+@vindex tramp-completion-function-alist
+
+The variable @code{tramp-completion-function-alist} is intended to
+customize which files are taken into account for user and host name
+completion (@pxref{Filename completion}). For every method, it keeps
+a set of configuration files, accompanied by a Lisp function able to
+parse that file. Entries in @code{tramp-completion-function-alist}
+have the form (@var{method} @var{pair1} @var{pair2} ...).
+
+Each @var{pair} is composed of (@var{function} @var{file}).
+@var{function} is responsible to extract user names and host names
+from @var{file} for completion. There are two functions which access
+this variable:
+
+@defun tramp-get-completion-function method
+This function returns the list of completion functions for @var{method}.
+
+Example:
+@example
+(tramp-get-completion-function "rsh")
+
+ @result{} ((tramp-parse-rhosts "/etc/hosts.equiv")
+ (tramp-parse-rhosts "~/.rhosts"))
+@end example
+@end defun
+
+@defun tramp-set-completion-function method function-list
+This function sets @var{function-list} as list of completion functions
+for @var{method}.
+
+Example:
+@example
+(tramp-set-completion-function "ssh"
+ '((tramp-parse-sconfig "/etc/ssh_config")
+ (tramp-parse-sconfig "~/.ssh/config")))
+
+ @result{} ((tramp-parse-sconfig "/etc/ssh_config")
+ (tramp-parse-sconfig "~/.ssh/config"))
+@end example
+@end defun
+
+The following predefined functions parsing configuration files exist:
+
+@table @asis
+@item @code{tramp-parse-rhosts}
+@findex tramp-parse-rhosts
+
+This function parses files which are syntactical equivalent to
+@file{~/.rhosts}. It returns both host names and user names, if
+specified.
+
+@item @code{tramp-parse-shosts}
+@findex tramp-parse-shosts
+
+This function parses files which are syntactical equivalent to
+@file{~/.ssh/known_hosts}. Since there are no user names specified
+in such files, it can return host names only.
+
+@item @code{tramp-parse-sconfig}
+@findex tramp-parse-shosts
+
+This function returns the host nicknames defined by @code{Host} entries
+in @file{~/.ssh/config} style files.
+
+@item @code{tramp-parse-shostkeys}
+@findex tramp-parse-shostkeys
+
+SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and
+@file{~/ssh2/hostkeys/*}. Hosts are coded in file names
+@file{hostkey_@var{portnumber}_@var{host-name}.pub}. User names
+are always @code{nil}.
+
+@item @code{tramp-parse-sknownhosts}
+@findex tramp-parse-shostkeys
+
+Another SSH2 style parsing of directories like
+@file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This
+case, hosts names are coded in file names
+@file{@var{host-name}.@var{algorithm}.pub}. User names are always @code{nil}.
+
+@item @code{tramp-parse-hosts}
+@findex tramp-parse-hosts
+
+A function dedicated to @file{/etc/hosts} style files. It returns
+host names only.
+
+@item @code{tramp-parse-passwd}
+@findex tramp-parse-passwd
+
+A function which parses @file{/etc/passwd} like files. Obviously, it
+can return user names only.
+
+@item @code{tramp-parse-netrc}
+@findex tramp-parse-netrc
+
+Finally, a function which parses @file{~/.netrc} like files.
+@end table
+
+If you want to keep your own data in a file, with your own structure,
+you might provide such a function as well. This function must meet
+the following conventions:
+
+@defun my-tramp-parse file
+@var{file} must be either a file name on your host, or @code{nil}.
+The function must return a list of (@var{user} @var{host}), which are
+taken as candidates for user and host name completion.
+
+Example:
+@example
+(my-tramp-parse "~/.my-tramp-hosts")
+
+ @result{} ((nil "toto") ("daniel" "melancholia"))
+@end example
+@end defun
+
+
+@node Password caching
+@section Reusing passwords for several connections.
+@cindex passwords
+
+Sometimes it is necessary to connect to the same remote host several
+times. Reentering passwords again and again would be annoying, when
+the chosen method does not support access without password prompt
+through own configuration.
+
+By default, @value{tramp} caches the passwords entered by you. They will
+be reused next time if a connection needs them for the same user name
+and host name, independently of the connection method.
+
+@vindex password-cache-expiry
+Passwords are not saved permanently, that means the password caching
+is limited to the lifetime of your @value{emacsname} session. You
+can influence the lifetime of password caching by customizing the
+variable @code{password-cache-expiry}. The value is the number of
+seconds how long passwords are cached. Setting it to @code{nil}
+disables the expiration.
+
+@findex tramp-clear-passwd
+A password is removed from the cache if a connection isn't established
+successfully. You can remove a password from the cache also by
+executing @kbd{M-x tramp-clear-passwd} in a buffer containing a
+related remote file or directory.
+
+@vindex password-cache
+If you don't like this feature for security reasons, password caching
+can be disabled totally by customizing the variable
+@code{password-cache} (setting it to @code{nil}).
+
+Implementation Note: password caching is based on the package
+@file{password.el} in No Gnus. For the time being, it is activated
+only when this package is seen in the @code{load-path} while loading
+@value{tramp}.
+@ifset installchapter
+If you don't use No Gnus, you can take @file{password.el} from the
+@value{tramp} @file{contrib} directory, see @ref{Installation
+parameters}.
+@end ifset
+It will be activated mandatory once No Gnus has found its way into
+@value{emacsname}.
+
+
+@node Connection caching
+@section Reusing connection related information.
+@cindex caching
+
+@vindex tramp-persistency-file-name
+In order to reduce initial connection time, @value{tramp} stores
+connection related information persistently. The variable
+@code{tramp-persistency-file-name} keeps the file name where these
+information are written. Its default value is
+@ifset emacs
+@file{~/.emacs.d/tramp}.
+@end ifset
+@ifset xemacs
+@file{~/.xemacs/tramp}.
+@end ifset
+It is recommended to choose a local file name.
+
+@value{tramp} reads this file during startup, and writes it when
+exiting @value{emacsname}. You can simply remove this file if
+@value{tramp} shall be urged to recompute these information next
+@value{emacsname} startup time.
+
+Using such persistent information can be disabled by setting
+@code{tramp-persistency-file-name} to @code{nil}.
+
+
+@node Remote Programs
+@section How @value{tramp} finds and uses programs on the remote machine.
+
+@value{tramp} depends on a number of programs on the remote host in order to
+function, including @command{ls}, @command{test}, @command{find} and
+@command{cat}.
+
+In addition to these required tools, there are various tools that may be
+required based on the connection method. See @ref{Inline methods} and
+@ref{External transfer methods} for details on these.
+
+Certain other tools, such as @command{perl} (or @command{perl5}) and
+@command{grep} will be used if they can be found. When they are
+available, they are used to improve the performance and accuracy of
+remote file access.
+
+@vindex tramp-remote-path
+When @value{tramp} connects to the remote machine, it searches for the
+programs that it can use. The variable @code{tramp-remote-path}
+controls the directories searched on the remote machine.
+
+By default, this is set to a reasonable set of defaults for most
+machines. The symbol @code{tramp-default-remote-path} is a place
+holder, it is replaced by the list of directories received via the
+command @command{getconf PATH} on your remote machine. For example,
+on GNU Debian this is @file{/bin:/usr/bin}, whereas on Solaris this is
+@file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}. It is
+recommended to apply this symbol on top of @code{tramp-remote-path}.
+
+It is possible, however, that your local (or remote ;) system
+administrator has put the tools you want in some obscure local
+directory.
+
+In this case, you can still use them with @value{tramp}. You simply
+need to add code to your @file{.emacs} to add the directory to the
+remote path. This will then be searched by @value{tramp} when you
+connect and the software found.
+
+To add a directory to the remote search path, you could use code such
+as:
+
+@lisp
+@i{;; We load @value{tramp} to define the variable.}
+(require 'tramp)
+@i{;; We have @command{perl} in "/usr/local/perl/bin"}
+(add-to-list 'tramp-remote-path "/usr/local/perl/bin")
+@end lisp
+
+@value{tramp} caches several information, like the Perl binary
+location. The changed remote search path wouldn't affect these
+settings. In order to force @value{tramp} to recompute these values,
+you must exit @value{emacsname}, remove your persistency file
+(@pxref{Connection caching}), and restart @value{emacsname}.
+
+
+@node Remote shell setup
+@comment node-name, next, previous, up
+@section Remote shell setup hints
+@cindex remote shell setup
+@cindex @file{.profile} file
+@cindex @file{.login} file
+@cindex shell init files
+
+As explained in the @ref{Overview} section, @value{tramp} connects to the
+remote host and talks to the shell it finds there. Of course, when you
+log in, the shell executes its init files. Suppose your init file
+requires you to enter the birth date of your mother; clearly @value{tramp}
+does not know this and hence fails to log you in to that host.
+
+There are different possible strategies for pursuing this problem. One
+strategy is to enable @value{tramp} to deal with all possible situations.
+This is a losing battle, since it is not possible to deal with
+@emph{all} situations. The other strategy is to require you to set up
+the remote host such that it behaves like @value{tramp} expects. This might
+be inconvenient because you have to invest a lot of effort into shell
+setup before you can begin to use @value{tramp}.
+
+The package, therefore, pursues a combined approach. It tries to
+figure out some of the more common setups, and only requires you to
+avoid really exotic stuff. For example, it looks through a list of
+directories to find some programs on the remote host. And also, it
+knows that it is not obvious how to check whether a file exists, and
+therefore it tries different possibilities. (On some hosts and
+shells, the command @command{test -e} does the trick, on some hosts
+the shell builtin doesn't work but the program @command{/usr/bin/test
+-e} or @command{/bin/test -e} works. And on still other hosts,
+@command{ls -d} is the right way to do this.)
+
+Below you find a discussion of a few things that @value{tramp} does not deal
+with, and that you therefore have to set up correctly.
+
+@table @asis
+@item @var{shell-prompt-pattern}
+@vindex shell-prompt-pattern
+
+After logging in to the remote host, @value{tramp} has to wait for the remote
+shell startup to finish before it can send commands to the remote
+shell. The strategy here is to wait for the shell prompt. In order to
+recognize the shell prompt, the variable @code{shell-prompt-pattern} has
+to be set correctly to recognize the shell prompt on the remote host.
+
+Note that @value{tramp} requires the match for @code{shell-prompt-pattern}
+to be at the end of the buffer. Many people have something like the
+following as the value for the variable: @code{"^[^>$][>$] *"}. Now
+suppose your shell prompt is @code{a <b> c $ }. In this case,
+@value{tramp} recognizes the @code{>} character as the end of the prompt,
+but it is not at the end of the buffer.
+
+@item @var{tramp-shell-prompt-pattern}
+@vindex tramp-shell-prompt-pattern
+
+This regular expression is used by @value{tramp} in the same way as
+@code{shell-prompt-pattern}, to match prompts from the remote shell.
+This second variable exists because the prompt from the remote shell
+might be different from the prompt from a local shell --- after all,
+the whole point of @value{tramp} is to log in to remote hosts as a
+different user. The default value of
+@code{tramp-shell-prompt-pattern} is the same as the default value of
+@code{shell-prompt-pattern}, which is reported to work well in many
+circumstances.
+
+@item @command{tset} and other questions
+@cindex Unix command tset
+@cindex tset Unix command
+
+Some people invoke the @command{tset} program from their shell startup
+scripts which asks the user about the terminal type of the shell.
+Maybe some shells ask other questions when they are started.
+@value{tramp} does not know how to answer these questions. There are
+two approaches for dealing with this problem. One approach is to take
+care that the shell does not ask any questions when invoked from
+@value{tramp}. You can do this by checking the @code{TERM}
+environment variable, it will be set to @code{dumb} when connecting.
+
+@vindex tramp-terminal-type
+The variable @code{tramp-terminal-type} can be used to change this value
+to @code{dumb}.
+
+@vindex tramp-actions-before-shell
+The other approach is to teach @value{tramp} about these questions. See
+the variable @code{tramp-actions-before-shell}. Example:
+
+@lisp
+(defconst my-tramp-prompt-regexp
+ (concat (regexp-opt '("Enter the birth date of your mother:") t)
+ "\\s-*")
+ "Regular expression matching my login prompt question.")
+
+(defun my-tramp-action (proc vec)
+ "Enter \"19000101\" in order to give a correct answer."
+ (save-window-excursion
+ (with-current-buffer (tramp-get-connection-buffer vec)
+ (tramp-message vec 6 "\n%s" (buffer-string))
+ (tramp-send-string vec "19000101"))))
+
+(add-to-list 'tramp-actions-before-shell
+ '(my-tramp-prompt-regexp my-tramp-action))
+@end lisp
+
+
+@item Environment variables named like users in @file{.profile}
+
+If you have a user named frumple and set the variable @code{FRUMPLE} in
+your shell environment, then this might cause trouble. Maybe rename
+the variable to @code{FRUMPLE_DIR} or the like.
+
+This weird effect was actually reported by a @value{tramp} user!
+
+
+@item Non-Bourne commands in @file{.profile}
+
+After logging in to the remote host, @value{tramp} issues the command
+@command{exec /bin/sh}. (Actually, the command is slightly
+different.) When @command{/bin/sh} is executed, it reads some init
+files, such as @file{~/.shrc} or @file{~/.profile}.
+
+Now, some people have a login shell which is not @code{/bin/sh} but a
+Bourne-ish shell such as bash or ksh. Some of these people might put
+their shell setup into the files @file{~/.shrc} or @file{~/.profile}.
+This way, it is possible for non-Bourne constructs to end up in those
+files. Then, @command{exec /bin/sh} might cause the Bourne shell to
+barf on those constructs.
+
+As an example, imagine somebody putting @command{export FOO=bar} into
+the file @file{~/.profile}. The standard Bourne shell does not
+understand this syntax and will emit a syntax error when it reaches
+this line.
+
+Another example is the tilde (@code{~}) character, say when adding
+@file{~/bin} to @code{$PATH}. Many Bourne shells will not expand this
+character, and since there is usually no directory whose name consists
+of the single character tilde, strange things will happen.
+
+What can you do about this?
+
+Well, one possibility is to make sure that everything in
+@file{~/.shrc} and @file{~/.profile} on all remote hosts is
+Bourne-compatible. In the above example, instead of @command{export
+FOO=bar}, you might use @command{FOO=bar; export FOO} instead.
+
+The other possibility is to put your non-Bourne shell setup into some
+other files. For example, bash reads the file @file{~/.bash_profile}
+instead of @file{~/.profile}, if the former exists. So bash
+aficionados just rename their @file{~/.profile} to
+@file{~/.bash_profile} on all remote hosts, and Bob's your uncle.
+
+The @value{tramp} developers would like to circumvent this problem, so
+if you have an idea about it, please tell us. However, we are afraid
+it is not that simple: before saying @command{exec /bin/sh},
+@value{tramp} does not know which kind of shell it might be talking
+to. It could be a Bourne-ish shell like ksh or bash, or it could be a
+csh derivative like tcsh, or it could be zsh, or even rc. If the
+shell is Bourne-ish already, then it might be prudent to omit the
+@command{exec /bin/sh} step. But how to find out if the shell is
+Bourne-ish?
+
+@end table
+
+
+@node Auto-save and Backup
+@section Auto-save and Backup configuration
+@cindex auto-save
+@cindex backup
+@ifset emacs
+@vindex backup-directory-alist
+@end ifset
+@ifset xemacs
+@vindex bkup-backup-directory-info
+@end ifset
+
+Normally, @value{emacsname} writes backup files to the same directory
+as the original files, but this behavior can be changed via the
+variable
+@ifset emacs
+@code{backup-directory-alist}.
+@end ifset
+@ifset xemacs
+@code{bkup-backup-directory-info}.
+@end ifset
+In connection with @value{tramp}, this can have unexpected side
+effects. Suppose that you specify that all backups should go to the
+directory @file{~/.emacs.d/backups/}, and then you edit the file
+@file{@trampfn{su, root, localhost, /etc/secretfile}}. The effect is
+that the backup file will be owned by you and not by root, thus
+possibly enabling others to see it even if they were not intended to
+see it.
+
+When
+@ifset emacs
+@code{backup-directory-alist}
+@end ifset
+@ifset xemacs
+@code{bkup-backup-directory-info}
+@end ifset
+is @code{nil} (the default), such problems do not occur.
+
+Therefore, it is useful to set special values for @value{tramp}
+files. For example, the following statement effectively `turns off'
+the effect of
+@ifset emacs
+@code{backup-directory-alist}
+@end ifset
+@ifset xemacs
+@code{bkup-backup-directory-info}
+@end ifset
+for @value{tramp} files:
+
+@ifset emacs
+@lisp
+(add-to-list 'backup-directory-alist
+ (cons tramp-file-name-regexp nil))
+@end lisp
+@end ifset
+@ifset xemacs
+@lisp
+(require 'backup-dir)
+(add-to-list 'bkup-backup-directory-info
+ (list tramp-file-name-regexp ""))
+@end lisp
+@end ifset
+
+Another possibility is to use the @value{tramp} variable
+@ifset emacs
+@code{tramp-backup-directory-alist}.
+@end ifset
+@ifset xemacs
+@code{tramp-bkup-backup-directory-info}.
+@end ifset
+This variable has the same meaning like
+@ifset emacs
+@code{backup-directory-alist}.
+@end ifset
+@ifset xemacs
+@code{bkup-backup-directory-info}.
+@end ifset
+If a @value{tramp} file is backed up, and DIRECTORY is an absolute
+local file name, DIRECTORY is prepended with the @value{tramp} file
+name prefix of the file to be backed up.
+
+@noindent
+Example:
+
+@ifset emacs
+@lisp
+(add-to-list 'backup-directory-alist
+ (cons "." "~/.emacs.d/backups/"))
+(setq tramp-backup-directory-alist backup-directory-alist)
+@end lisp
+@end ifset
+@ifset xemacs
+@lisp
+(require 'backup-dir)
+(add-to-list 'bkup-backup-directory-info
+ (list "." "~/.emacs.d/backups/" 'full-path))
+(setq tramp-bkup-backup-directory-info bkup-backup-directory-info)
+@end lisp
+@end ifset
+
+@noindent
+The backup file name of @file{@trampfn{su, root, localhost,
+/etc/secretfile}} would be
+@ifset emacs
+@file{@trampfn{su, root, localhost,
+~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}
+@end ifset
+@ifset xemacs
+@file{@trampfn{su, root, localhost,
+~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}}
+@end ifset
+
+The same problem can happen with auto-saving files.
+@ifset emacs
+Since @value{emacsname} 21, the variable
+@code{auto-save-file-name-transforms} keeps information, on which
+directory an auto-saved file should go. By default, it is initialized
+for @value{tramp} files to the local temporary directory.
+
+On some versions of @value{emacsname}, namely the version built for
+Debian GNU/Linux, the variable @code{auto-save-file-name-transforms}
+contains the directory where @value{emacsname} was built. A
+workaround is to manually set the variable to a sane value.
+
+If auto-saved files should go into the same directory as the original
+files, @code{auto-save-file-name-transforms} should be set to @code{nil}.
+
+Another possibility is to set the variable
+@code{tramp-auto-save-directory} to a proper value.
+@end ifset
+@ifset xemacs
+For this purpose you can set the variable @code{auto-save-directory}
+to a proper value.
+@end ifset
+
+
+@node Windows setup hints
+@section Issues with Cygwin ssh
+@cindex Cygwin, issues
+
+This section needs a lot of work! Please help.
+
+@cindex method sshx with Cygwin
+@cindex sshx method with Cygwin
+The recent Cygwin installation of @command{ssh} works only with a
+Cygwinized @value{emacsname}. You can check it by typing @kbd{M-x
+eshell}, and starting @kbd{ssh test.machine}. The problem is evident
+if you see a message like this:
+
+@example
+Pseudo-terminal will not be allocated because stdin is not a terminal.
+@end example
+
+Older @command{ssh} versions of Cygwin are told to cooperate with
+@value{tramp} selecting @option{sshx} as the connection method. You
+can find information about setting up Cygwin in their FAQ at
+@uref{http://cygwin.com/faq/}.
+
+@cindex method scpx with Cygwin
+@cindex scpx method with Cygwin
+If you wish to use the @option{scpx} connection method, then you might
+have the problem that @value{emacsname} calls @command{scp} with a
+Windows filename such as @code{c:/foo}. The Cygwin version of
+@command{scp} does not know about Windows filenames and interprets
+this as a remote filename on the host @code{c}.
+
+One possible workaround is to write a wrapper script for @option{scp}
+which converts the Windows filename to a Cygwinized filename.
+
+@cindex Cygwin and ssh-agent
+@cindex SSH_AUTH_SOCK and @value{emacsname} on Windows
+If you want to use either @option{ssh} based method on Windows, then
+you might encounter problems with @command{ssh-agent}. Using this
+program, you can avoid typing the pass-phrase every time you log in.
+However, if you start @value{emacsname} from a desktop shortcut, then
+the environment variable @code{SSH_AUTH_SOCK} is not set and so
+@value{emacsname} and thus @value{tramp} and thus @command{ssh} and
+@command{scp} started from @value{tramp} cannot communicate with
+@command{ssh-agent}. It works better to start @value{emacsname} from
+the shell.
+
+If anyone knows how to start @command{ssh-agent} under Windows in such a
+way that desktop shortcuts can profit, please holler. I don't really
+know anything at all about Windows@dots{}
+
+
+@node Usage
+@chapter Using @value{tramp}
+@cindex using @value{tramp}
+
+Once you have installed @value{tramp} it will operate fairly
+transparently. You will be able to access files on any remote machine
+that you can log in to as though they were local.
+
+Files are specified to @value{tramp} using a formalized syntax specifying the
+details of the system to connect to. This is similar to the syntax used
+by the @value{ftppackagename} package.
+
+@cindex type-ahead
+Something that might happen which surprises you is that
+@value{emacsname} remembers all your keystrokes, so if you see a
+password prompt from @value{emacsname}, say, and hit @kbd{@key{RET}}
+twice instead of once, then the second keystroke will be processed by
+@value{emacsname} after @value{tramp} has done its thing. Why, this
+type-ahead is normal behavior, you say. Right you are, but be aware
+that opening a remote file might take quite a while, maybe half a
+minute when a connection needs to be opened. Maybe after half a
+minute you have already forgotten that you hit that key!
+
+@menu
+* Filename Syntax:: @value{tramp} filename conventions.
+* Alternative Syntax:: URL-like filename syntax.
+* Filename completion:: Filename completion.
+* Remote processes:: Integration with other @value{emacsname} packages.
+@end menu
+
+
+@node Filename Syntax
+@section @value{tramp} filename conventions
+@cindex filename syntax
+@cindex filename examples
+
+To access the file @var{localname} on the remote machine @var{machine}
+you would specify the filename @file{@trampfn{, , machine,
+localname}}. This will connect to @var{machine} and transfer the file
+using the default method. @xref{Default Method}.
+
+Some examples of @value{tramp} filenames are shown below.
+
+@table @file
+@item @trampfn{, , melancholia, .emacs}
+Edit the file @file{.emacs} in your home directory on the machine
+@code{melancholia}.
+
+@item @trampfn{, , melancholia.danann.net, .emacs}
+This edits the same file, using the fully qualified domain name of
+the machine.
+
+@item @trampfn{, , melancholia, ~/.emacs}
+This also edits the same file --- the @file{~} is expanded to your
+home directory on the remote machine, just like it is locally.
+
+@item @trampfn{, , melancholia, ~daniel/.emacs}
+This edits the file @file{.emacs} in the home directory of the user
+@code{daniel} on the machine @code{melancholia}. The @file{~<user>}
+construct is expanded to the home directory of that user on the remote
+machine.
+
+@item @trampfn{, , melancholia, /etc/squid.conf}
+This edits the file @file{/etc/squid.conf} on the machine
+@code{melancholia}.
+
+@end table
+
+Unless you specify a different name to use, @value{tramp} will use the
+current local user name as the remote user name to log in with. If you
+need to log in as a different user, you can specify the user name as
+part of the filename.
+
+To log in to the remote machine as a specific user, you use the syntax
+@file{@trampfn{, user, machine, path/to.file}}. That means that
+connecting to @code{melancholia} as @code{daniel} and editing
+@file{.emacs} in your home directory you would specify
+@file{@trampfn{, daniel, melancholia, .emacs}}.
+
+It is also possible to specify other file transfer methods
+(@pxref{Default Method}) as part of the filename.
+@ifset emacs
+This is done by putting the method before the user and host name, as
+in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the
+trailing colon).
+@end ifset
+@ifset xemacs
+This is done by replacing the initial @file{@value{prefix}} with
+@file{@value{prefix}<method>@value{postfixhop}}. (Note the trailing
+slash!).
+@end ifset
+The user, machine and file specification remain the same.
+
+So, to connect to the machine @code{melancholia} as @code{daniel},
+using the @option{ssh} method to transfer files, and edit
+@file{.emacs} in my home directory I would specify the filename
+@file{@trampfn{ssh, daniel, melancholia, .emacs}}.
+
+
+@node Alternative Syntax
+@section URL-like filename syntax
+@cindex filename syntax
+@cindex filename examples
+
+Additionally to the syntax described in the previous chapter, it is
+possible to use a URL-like syntax for @value{tramp}. This can be
+switched on by customizing the variable @code{tramp-syntax}. Please
+note that this feature is experimental for the time being.
+
+The variable @code{tramp-syntax} must be set before requiring @value{tramp}:
+
+@lisp
+(setq tramp-syntax 'url)
+(require 'tramp)
+@end lisp
+
+Then, a @value{tramp} filename would look like this:
+@file{/@var{method}://@var{user}@@@var{machine}:@var{port}/@var{path/to.file}}.
+@file{/@var{method}://} is mandatory, all other parts are optional.
+@file{:@var{port}} is useful for methods only who support this.
+
+The last example from the previous section would look like this:
+@file{/ssh://daniel@@melancholia/.emacs}.
+
+For the time being, @code{tramp-syntax} can have the following values:
+
+@itemize @w{}
+@ifset emacs
+@item @code{ftp} -- That is the default syntax
+@item @code{url} -- URL-like syntax
+@end ifset
+@ifset xemacs
+@item @code{sep} -- That is the default syntax
+@item @code{url} -- URL-like syntax
+@item @code{ftp} -- EFS-like syntax
+@end ifset
+@end itemize
+
+
+@node Filename completion
+@section Filename completion
+@cindex filename completion
+
+Filename completion works with @value{tramp} for completion of method
+names, of user names and of machine names as well as for completion of
+file names on remote machines.
+@ifset emacs
+In order to enable this, Partial Completion mode must be set
+on@footnote{If you don't use Partial Completion mode, but want to
+keep full completion, load @value{tramp} like this in your
+@file{.emacs}:
+
+@lisp
+;; Preserve Tramp's completion features.
+(let ((partial-completion-mode t))
+ (require 'tramp))
+@end lisp
+}.
+@ifinfo
+@xref{Completion Options, , , @value{emacsdir}}.
+@end ifinfo
+@end ifset
+
+If you, for example, type @kbd{C-x C-f @value{prefix}t
+@key{TAB}}, @value{tramp} might give you as result the choice for
+
+@example
+@ifset emacs
+@value{prefixhop}telnet@value{postfixhop} tmp/
+@value{prefixhop}toto@value{postfix}
+@end ifset
+@ifset xemacs
+@value{prefixhop}telnet@value{postfixhop} @value{prefixhop}toto@value{postfix}
+@end ifset
+@end example
+
+@samp{@value{prefixhop}telnet@value{postfixhop}}
+is a possible completion for the respective method,
+@ifset emacs
+@samp{tmp/} stands for the directory @file{/tmp} on your local
+machine,
+@end ifset
+and @samp{@value{prefixhop}toto@value{postfix}}
+might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts}
+file (given you're using default method @option{ssh}).
+
+If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to
+@samp{@value{prefix}telnet@value{postfixhop}}.
+Next @kbd{@key{TAB}} brings you all machine names @value{tramp} detects in
+your @file{/etc/hosts} file, let's say
+
+@example
+@trampfn{telnet, , 127.0.0.1,} @trampfn{telnet, , 192.168.0.1,}
+@trampfn{telnet, , localhost,} @trampfn{telnet, , melancholia.danann.net,}
+@trampfn{telnet, , melancholia,}
+@end example
+
+Now you can choose the desired machine, and you can continue to
+complete file names on that machine.
+
+If the configuration files (@pxref{Customizing Completion}), which
+@value{tramp} uses for analysis of completion, offer user names, those user
+names will be taken into account as well.
+
+Remote machines, which have been visited in the past and kept
+persistently (@pxref{Connection caching}), will be offered too.
+
+Once the remote machine identification is completed, it comes to
+filename completion on the remote host. This works pretty much like
+for files on the local host, with the exception that minibuffer
+killing via a double-slash works only on the filename part, except
+that filename part starts with @file{//}.
+@ifinfo
+@xref{Minibuffer File, , , @value{emacsdir}}.
+@end ifinfo
+
+@ifset emacs
+As example, @kbd{@trampfn{telnet, , melancholia, /usr/local/bin//etc}
+@key{TAB}} would result in
+@file{@trampfn{telnet, , melancholia, /etc}}, whereas
+@kbd{@trampfn{telnet, , melancholia, //etc} @key{TAB}} reduces the
+minibuffer contents to @file{/etc}. A triple-slash stands for the
+default behaviour,
+i.e. @kbd{@trampfn{telnet, , melancholia, /usr/local/bin///etc}
+@key{TAB}} expands directly to @file{/etc}.
+@end ifset
+
+@ifset xemacs
+As example, @kbd{@trampfn{telnet, , melancholia, /usr/local/bin//}}
+would result in @file{@trampfn{telnet, , melancholia, /}}, whereas
+@kbd{@trampfn{telnet, , melancholia, //}} expands the minibuffer
+contents to @file{/}.
+@end ifset
+
+
+@node Remote processes
+@section Integration with other @value{emacsname} packages.
+@cindex compile
+@cindex recompile
+
+@value{tramp} supports running processes on a remote host. This
+allows to exploit @value{emacsname} packages without modification for
+remote file names. It does not work for the @option{ftp} and
+@option{smb} methods.
+
+Remote processes are started when a corresponding command is executed
+from a buffer belonging to a remote file or directory. Up to now, the
+packages @file{compile.el} (commands like @code{compile} and
+@code{grep}) and @file{gud.el} (@code{gdb} or @code{perldb}) have been
+integrated. Integration of further packages is planned, any help for
+this is welcome!
+
+When your program is not found in the default search path
+@value{tramp} sets on the remote machine, you should either use an
+absolute path, or extend @code{tramp-remote-path} (see @ref{Remote
+Programs}):
+
+@lisp
+(add-to-list 'tramp-remote-path "~/bin")
+(add-to-list 'tramp-remote-path "/appli/pub/bin")
+@end lisp
+
+The environment for your program can be adapted by customizing
+@code{tramp-remote-process-environment}. This variable is a list of
+strings. It is structured like @code{process-environment}. Each
+element is a string of the form ENVVARNAME=VALUE. An entry
+ENVVARNAME= disables the corresponding environment variable, which
+might have been set in your init file like @file{~/.profile}.
+
+@noindent
+Adding an entry can be performed via @code{add-to-list}:
+
+@lisp
+(add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java")
+@end lisp
+
+Changing or removing an existing entry is not encouraged. The default
+values are chosen for proper @value{tramp} work. Nevertheless, if for
+example a paranoid system administrator disallows changing the
+@var{$HISTORY} environment variable, you can customize
+@code{tramp-remote-process-environment}, or you can apply the
+following code in your @file{.emacs}:
+
+@lisp
+(let ((process-environment tramp-remote-process-environment))
+ (setenv "HISTORY" nil)
+ (setq tramp-remote-process-environment process-environment))
+@end lisp
+
+If you use other @value{emacsname} packages which do not run
+out-of-the-box on a remote host, please let us know. We will try to
+integrate them as well. @xref{Bug Reports}.
+
+
+@subsection Running eshell on a remote host
+@cindex eshell
+
+@value{tramp} is integrated into @file{eshell.el}. That is, you can
+open an interactive shell on your remote host, and run commands there.
+After you have started @code{eshell}, you could perform commands like
+this:
+
+@example
+@b{~ $} cd @trampfn{sudo, , , /etc} @key{RET}
+@b{@trampfn{sudo, root, host, /etc} $} hostname @key{RET}
+host
+@b{@trampfn{sudo, root, host, /etc} $} id @key{RET}
+uid=0(root) gid=0(root) groups=0(root)
+@b{@trampfn{sudo, root, host, /etc} $} find-file shadow @key{RET}
+#<buffer shadow>
+@b{@trampfn{sudo, root, host, /etc} $}
+@end example
+
+
+@anchor{Running a debugger on a remote host}
+@subsection Running a debugger on a remote host
+@cindex gud
+@cindex gdb
+@cindex perldb
+
+@file{gud.el} offers an unified interface to several symbolic
+debuggers
+@ifset emacs
+@ifinfo
+(@ref{Debuggers, , , @value{emacsdir}}).
+@end ifinfo
+@end ifset
+With @value{tramp}, it is possible to debug programs on
+remote hosts. You can call @code{gdb} with a remote file name:
+
+@example
+@kbd{M-x gdb @key{RET}}
+@b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh, , host, ~/myprog} @key{RET}
+@end example
+
+The file name can also be relative to a remote default directory.
+Given you are in a buffer that belongs to the remote directory
+@trampfn{ssh, , host, /home/user}, you could call
+
+@example
+@kbd{M-x perldb @key{RET}}
+@b{Run perldb (like this):} perl -d myprog.pl @key{RET}
+@end example
+
+It is not possible to use just the absolute local part of a remote
+file name as program to debug, like @kbd{perl -d
+/home/user/myprog.pl}, though.
+
+Arguments of the program to be debugged are taken literally. That
+means file names as arguments must be given as ordinary relative or
+absolute file names, without any remote specification.
+
+
+@node Bug Reports
+@chapter Reporting Bugs and Problems
+@cindex bug reports
+
+Bugs and problems with @value{tramp} are actively worked on by the
+development team. Feature requests and suggestions are also more than
+welcome.
+
+The @value{tramp} mailing list is a great place to get information on
+working with @value{tramp}, solving problems and general discussion
+and advice on topics relating to the package. It is moderated so
+non-subscribers can post but messages will be delayed, possibly up to
+48 hours (or longer in case of holidays), until the moderator approves
+your message.
+
+The mailing list is at @email{tramp-devel@@gnu.org}. Messages sent to
+this address go to all the subscribers. This is @emph{not} the address
+to send subscription requests to.
+
+Subscribing to the list is performed via
+@uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/,
+the @value{tramp} Mail Subscription Page}.
+
+To report a bug in @value{tramp}, you should execute @kbd{M-x
+tramp-bug}. This will automatically generate a buffer with the details
+of your system and @value{tramp} version.
+
+When submitting a bug report, please try to describe in excruciating
+detail the steps required to reproduce the problem, the setup of the
+remote machine and any special conditions that exist. You should also
+check that your problem is not described already in @xref{Frequently
+Asked Questions}.
+
+If you can identify a minimal test case that reproduces the problem,
+include that with your bug report. This will make it much easier for
+the development team to analyze and correct the problem.
+
+Before reporting the bug, you should set the verbosity level to 6
+(@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file and
+repeat the bug. Then, include the contents of the @file{*tramp/foo*}
+and @file{*debug tramp/foo*} buffers in your bug report. A verbosity
+level greater than 6 will produce a very huge debug buffer, which is
+mostly not necessary for the analysis.
+
+Please be aware that, with a verbosity level of 6 or greater, the
+contents of files and directories will be included in the debug
+buffer. Passwords you've typed will never be included there.
+
+
+@node Frequently Asked Questions
+@chapter Frequently Asked Questions
+@cindex frequently asked questions
+@cindex FAQ
+
+@itemize @bullet
+@item
+Where can I get the latest @value{tramp}?
+
+@value{tramp} is available under the URL below.
+
+@noindent
+@uref{ftp://ftp.gnu.org/gnu/tramp/}
+
+@noindent
+There is also a Savannah project page.
+
+@noindent
+@uref{http://savannah.gnu.org/projects/tramp/}
+
+
+@item
+Which systems does it work on?
+
+The package has been used successfully on GNU Emacs 21, GNU Emacs 22
+and XEmacs 21 (starting with 21.4). Gateway methods are supported for
+GNU Emacs 22 only.
+
+The package was intended to work on Unix, and it really expects a
+Unix-like system on the remote end (except the @option{smb} method),
+but some people seemed to have some success getting it to work on MS
+Windows NT/2000/XP @value{emacsname}.
+
+There is some informations on @value{tramp} on NT at the following URL;
+many thanks to Joe Stoy for providing the information:
+@uref{ftp://ftp.comlab.ox.ac.uk/tmp/Joe.Stoy/}
+
+@c The link is broken. I've contacted Tom for clarification. Michael.
+@ignore
+The above mostly contains patches to old ssh versions; Tom Roche has a
+Web page with instructions:
+@uref{http://www4.ncsu.edu/~tlroche/plinkTramp.html}
+@end ignore
+
+@item
+How could I speed up @value{tramp}?
+
+In the backstage, @value{tramp} needs a lot of operations on the
+remote host. The time for transferring data from and to the remote
+host as well as the time needed to perform the operations there count.
+In order to speed up @value{tramp}, one could either try to avoid some
+of the operations, or one could try to improve their performance.
+
+Use an external transfer method, like @option{scpc}.
+
+Use caching. This is already enabled by default. Information about
+the remote host as well as the remote files are cached for reuse. The
+information about remote hosts is kept in the file specified in
+@code{tramp-persistency-file-name}. Keep this file.
+
+Disable version control. If you access remote files which are not
+under version control, a lot of check operations can be avoided by
+disabling VC. This can be achieved by
+
+@lisp
+(setq vc-handled-backends nil)
+@end lisp
+
+Disable excessive traces. The default trace level of @value{tramp},
+defined in the variable @code{tramp-verbose}, is 3. You should
+increase this level only temporarily, hunting bugs.
+
+
+@item
+@value{tramp} does not connect to the remote host
+
+When @value{tramp} does not connect to the remote host, there are two
+reasons heading the bug mailing list:
+
+@itemize @minus
+
+@item
+Unknown characters in the prompt
+
+@value{tramp} needs to recognize the prompt on the remote machine
+after execution any command. This is not possible, when the prompt
+contains unknown characters like escape sequences for coloring. This
+should be avoided on the remote side. @xref{Remote shell setup}. for
+setting the regular expression detecting the prompt.
+
+You can check your settings after an unsuccessful connection by
+switching to the @value{tramp} connection buffer @file{*tramp/foo*},
+setting the cursor at the top of the buffer, and applying the expression
+
+@example
+@kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))}
+@end example
+
+If it fails, or the cursor is not moved at the end of the buffer, your
+prompt is not recognised correctly.
+
+A special problem is the zsh, which uses left-hand side and right-hand
+side prompts in parallel. Therefore, it is necessary to disable the
+zsh line editor on the remote host. You shall add to @file{~/.zshrc}
+the following command:
+
+@example
+[ $TERM = "dumb" ] && unsetopt zle && PS1='$ '
+@end example
+
+
+@item
+@value{tramp} doesn't transfer strings with more than 500 characters
+correctly
+
+On some few systems, the implementation of @code{process-send-string}
+seems to be broken for longer strings. It is reported for HP-UX,
+FreeBSD and Tru64 Unix, for example. This case, you should customize
+the variable @code{tramp-chunksize} to 500. For a description how to
+determine whether this is necessary see the documentation of
+@code{tramp-chunksize}.
+
+Additionally, it will be useful to set @code{file-precious-flag} to
+@code{t} for @value{tramp} files. Then the file contents will be
+written into a temporary file first, which is checked for correct
+checksum.
+@ifinfo
+@pxref{Saving Buffers, , , elisp}
+@end ifinfo
+
+@lisp
+(add-hook
+ 'find-file-hooks
+ '(lambda ()
+ (when (file-remote-p default-directory)
+ (set (make-local-variable 'file-precious-flag) t))))
+@end lisp
+
+@end itemize
+
+
+@item
+File name completion does not work with @value{tramp}
+
+When you log in to the remote machine, do you see the output of
+@command{ls} in color? If so, this may be the cause of your problems.
+
+@command{ls} outputs @acronym{ANSI} escape sequences that your terminal
+emulator interprets to set the colors. These escape sequences will
+confuse @value{tramp} however.
+
+In your @file{.bashrc}, @file{.profile} or equivalent on the remote
+machine you probably have an alias configured that adds the option
+@option{--color=yes} or @option{--color=auto}.
+
+You should remove that alias and ensure that a new login @emph{does not}
+display the output of @command{ls} in color. If you still cannot use
+filename completion, report a bug to the @value{tramp} developers.
+
+
+@item
+File name completion does not work in large directories
+
+@value{tramp} uses globbing for some operations. (Globbing means to use the
+shell to expand wildcards such as `*.c'.) This might create long
+command lines, especially in directories with many files. Some shells
+choke on long command lines, or don't cope well with the globbing
+itself.
+
+If you have a large directory on the remote end, you may wish to execute
+a command like @samp{ls -d * ..?* > /dev/null} and see if it hangs.
+Note that you must first start the right shell, which might be
+@command{/bin/sh}, @command{ksh} or @command{bash}, depending on which
+of those supports tilde expansion.
+
+
+@item
+How can I get notified when @value{tramp} file transfers are complete?
+
+The following snippet can be put in your @file{~/.emacs} file. It
+makes @value{emacsname} beep after reading from or writing to the
+remote host.
+
+@lisp
+(defadvice tramp-handle-write-region
+ (after tramp-write-beep-advice activate)
+ " make tramp beep after writing a file."
+ (interactive)
+ (beep))
+
+(defadvice tramp-handle-do-copy-or-rename-file
+ (after tramp-copy-beep-advice activate)
+ " make tramp beep after copying a file."
+ (interactive)
+ (beep))
+
+(defadvice tramp-handle-insert-file-contents
+ (after tramp-copy-beep-advice activate)
+ " make tramp beep after copying a file."
+ (interactive)
+ (beep))
+@end lisp
+
+
+@ifset emacs
+@item
+I'ld like to see a host indication in the mode line when I'm remote
+
+The following code has been tested with @value{emacsname} 22.1. You
+should put it into your @file{~/.emacs}:
+
+@lisp
+(defconst my-mode-line-buffer-identification
+ (list
+ '(:eval
+ (let ((host-name
+ (if (file-remote-p default-directory)
+ (tramp-file-name-host
+ (tramp-dissect-file-name default-directory))
+ (system-name))))
+ (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
+ (substring host-name 0 (match-beginning 1))
+ host-name)))
+ ": %12b"))
+
+(setq-default
+ mode-line-buffer-identification
+ my-mode-line-buffer-identification)
+
+(add-hook
+ 'dired-mode-hook
+ '(lambda ()
+ (setq
+ mode-line-buffer-identification
+ my-mode-line-buffer-identification)))
+@end lisp
+
+Since @value{emacsname} 23.1, the mode line contains an indication if
+@code{default-directory} for the current buffer is on a remote host.
+The corresponding tooltip includes the name of that host. If you
+still want the host name as part of the mode line, you can use the
+example above, but the @code{:eval} clause can be simplified:
+
+@lisp
+ '(:eval
+ (let ((host-name
+ (or (file-remote-p default-directory 'host)
+ (system-name))))
+ (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name)
+ (substring host-name 0 (match-beginning 1))
+ host-name)))
+@end lisp
+@end ifset
+
+
+@ifset emacs
+@item
+My remote host does not understand default directory listing options
+
+@value{emacsname} computes the @command{dired} options depending on
+the local host you are working. If your @command{ls} command on the
+remote host does not understand those options, you can change them
+like this:
+
+@lisp
+(add-hook
+ 'dired-before-readin-hook
+ '(lambda ()
+ (when (file-remote-p default-directory)
+ (setq dired-actual-switches "-al"))))
+@end lisp
+@end ifset
+
+
+@item
+There's this @file{~/.sh_history} file on the remote host which keeps
+growing and growing. What's that?
+
+Sometimes, @value{tramp} starts @command{ksh} on the remote host for
+tilde expansion. Maybe @command{ksh} saves the history by default.
+@value{tramp} tries to turn off saving the history, but maybe you have
+to help. For example, you could put this in your @file{.kshrc}:
+
+@example
+if [ -f $HOME/.sh_history ] ; then
+ /bin/rm $HOME/.sh_history
+fi
+if [ "$@{HISTFILE-unset@}" != "unset" ] ; then
+ unset HISTFILE
+fi
+if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then
+ unset HISTSIZE
+fi
+@end example
+
+
+@item There are longish file names to type. How to shorten this?
+
+Let's say you need regularly access to @file{@trampfn{ssh, news,
+news.my.domain, /opt/news/etc}}, which is boring to type again and
+again. The following approaches can be mixed:
+
+@enumerate
+
+@item Use default values for method and user name:
+
+You can define default methods and user names for hosts,
+(@pxref{Default Method}, @pxref{Default User}):
+
+@lisp
+(setq tramp-default-method "ssh"
+ tramp-default-user "news")
+@end lisp
+
+The file name left to type would be
+@kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}.
+
+Note, that there are some useful settings already. Accessing your
+local host as @samp{root} user, is possible just by @kbd{C-x C-f
+@trampfn{su, , ,}}.
+
+@item Use configuration possibilities of your method:
+
+Several connection methods (i.e. the programs used) offer powerful
+configuration possibilities (@pxref{Customizing Completion}). In the
+given case, this could be @file{~/.ssh/config}:
+
+@example
+Host xy
+ HostName news.my.domain
+ User news
+@end example
+
+The file name left to type would be @kbd{C-x C-f @trampfn{ssh, , xy,
+/opt/news/etc}}. Depending on files in your directories, it is even
+possible to complete the hostname with @kbd{C-x C-f
+@value{prefix}ssh@value{postfixhop}x @key{TAB}}.
+
+@item Use environment variables:
+
+File names typed in the minibuffer can be expanded by environment
+variables. You can set them outside @value{emacsname}, or even with
+Lisp:
+
+@lisp
+(setenv "xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")
+@end lisp
+
+Then you need simply to type @kbd{C-x C-f $xy @key{RET}}, and here you
+are. The disadvantage is, that you cannot edit the file name, because
+environment variables are not expanded during editing in the
+minibuffer.
+
+@item Define own keys:
+
+You can define your own key sequences in @value{emacsname}, which can
+be used instead of @kbd{C-x C-f}:
+
+@lisp
+(global-set-key
+ [(control x) (control y)]
+ (lambda ()
+ (interactive)
+ (find-file
+ (read-file-name
+ "Find Tramp file: "
+ "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))))
+@end lisp
+
+Simply typing @kbd{C-x C-y} would initialize the minibuffer for
+editing with your beloved file name.
+
+See also @uref{http://www.emacswiki.org/cgi-bin/wiki/TrampMode, the
+Emacs Wiki} for a more comprehensive example.
+
+@item Define own abbreviation (1):
+
+It is possible to define an own abbreviation list for expanding file
+names:
+
+@lisp
+(add-to-list
+ 'directory-abbrev-alist
+ '("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
+@end lisp
+
+This shortens the file openening command to @kbd{C-x C-f /xy
+@key{RET}}. The disadvantage is, again, that you cannot edit the file
+name, because the expansion happens after entering the file name only.
+
+@item Define own abbreviation (2):
+
+The @code{abbrev-mode} gives more flexibility for editing the
+minibuffer:
+
+@lisp
+(define-abbrev-table 'my-tramp-abbrev-table
+ '(("xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")))
+
+(add-hook
+ 'minibuffer-setup-hook
+ '(lambda ()
+ (abbrev-mode 1)
+ (setq local-abbrev-table my-tramp-abbrev-table)))
+
+(defadvice minibuffer-complete
+ (before my-minibuffer-complete activate)
+ (expand-abbrev))
+
+;; If you use partial-completion-mode
+(defadvice PC-do-completion
+ (before my-PC-do-completion activate)
+ (expand-abbrev))
+@end lisp
+
+After entering @kbd{C-x C-f xy @key{TAB}}, the minibuffer is
+expanded, and you can continue editing.
+
+@item Use bookmarks:
+
+Bookmarks can be used to visit Tramp files or directories.
+@ifinfo
+@pxref{Bookmarks, , , @value{emacsdir}}
+@end ifinfo
+
+When you have opened @file{@trampfn{ssh, news, news.my.domain,
+/opt/news/etc/}}, you should save the bookmark via
+@ifset emacs
+@kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{set}}.
+@end ifset
+@ifset xemacs
+@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{set}}.
+@end ifset
+
+Later on, you can always navigate to that bookmark via
+@ifset emacs
+@kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{jump}}.
+@end ifset
+@ifset xemacs
+@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{jump}}.
+@end ifset
+
+@item Use recent files:
+
+@ifset emacs
+@file{recentf}
+@end ifset
+@ifset xemacs
+@file{recent-files}
+@end ifset
+remembers visited places.
+@ifinfo
+@ifset emacs
+@pxref{File Conveniences, , , @value{emacsdir}}
+@end ifset
+@ifset xemacs
+@pxref{recent-files, , , edit-utils}
+@end ifset
+@end ifinfo
+
+You could keep remote file names in the recent list without checking
+their readability through a remote access:
+
+@lisp
+@ifset emacs
+(recentf-mode 1)
+@end ifset
+@ifset xemacs
+(recent-files-initialize)
+(add-hook
+ 'find-file-hooks
+ (lambda ()
+ (when (file-remote-p (buffer-file-name))
+ (recent-files-make-permanent)))
+ 'append)
+@end ifset
+@end lisp
+
+The list of files opened recently is reachable via
+@ifset emacs
+@kbd{@key{menu-bar} @key{file} @key{Open Recent}}.
+@end ifset
+@ifset xemacs
+@kbd{@key{menu-bar} @key{Recent Files}}.
+@end ifset
+
+@ifset emacs
+@item Use filecache:
+
+@file{filecache} remembers visited places. Add the directory into
+the cache:
+
+@lisp
+(eval-after-load "filecache"
+ '(file-cache-add-directory
+ "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))
+@end lisp
+
+Whenever you want to load a file, you can enter @kbd{C-x C-f
+C-@key{TAB}} in the minibuffer. The completion is done for the given
+directory.
+@end ifset
+
+@ifset emacs
+@item Use bbdb:
+
+@file{bbdb} has a built-in feature for @value{ftppackagename} files,
+which works also for @value{tramp}.
+@ifinfo
+@pxref{bbdb-ftp, Storing FTP sites in the BBDB, , bbdb}
+@end ifinfo
+
+You need to load @file{bbdb}:
+
+@lisp
+(require 'bbdb)
+(bbdb-initialize)
+@end lisp
+
+Then you can create a BBDB entry via @kbd{M-x bbdb-create-ftp-site}.
+Because BBDB is not prepared for @value{tramp} syntax, you must
+specify a method together with the user name, when needed. Example:
+
+@example
+@kbd{M-x bbdb-create-ftp-site @key{RET}}
+@b{Ftp Site:} news.my.domain @key{RET}
+@b{Ftp Directory:} /opt/news/etc/ @key{RET}
+@b{Ftp Username:} ssh@value{postfixhop}news @key{RET}
+@b{Company:} @key{RET}
+@b{Additional Comments:} @key{RET}
+@end example
+
+When you have opened your BBDB buffer, you can access such an entry by
+pressing the key @key{F}.
+@end ifset
+
+@end enumerate
+
+I would like to thank all @value{tramp} users, who have contributed to
+the different recipes!
+
+
+@item
+How can I disable @value{tramp}?
+
+Shame on you, why did you read until now?
+
+@ifset emacs
+If you just want to have @value{ftppackagename} as default remote
+files access package, you should apply the following code:
+
+@lisp
+(setq tramp-default-method "ftp")
+@end lisp
+@end ifset
+
+Unloading @value{tramp} can be achieved by applying @kbd{M-x
+tramp-unload-tramp}.
+@ifset emacs
+This resets also the @value{ftppackagename} plugins.
+@end ifset
+@end itemize
+
+
+@c For the developer
+@node Version Control
+@chapter The inner workings of remote version control
+@cindex Version Control
+
+Unlike @value{ftppackagename}, @value{tramp} has full shell access to the
+remote machine. This makes it possible to provide version control for
+files accessed under @value{tramp}.
+
+The actual version control binaries must be installed on the remote
+machine, accessible in the directories specified in
+@code{tramp-remote-path}.
+
+This transparent integration with the version control systems is one of
+the most valuable features provided by @value{tramp}, but it is far from perfect.
+Work is ongoing to improve the transparency of the system.
+
+@menu
+* Version Controlled Files:: Determining if a file is under version control.
+* Remote Commands:: Executing the version control commands on the remote machine.
+* Changed workfiles:: Detecting if the working file has changed.
+* Checking out files:: Bringing the workfile out of the repository.
+* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere.
+@end menu
+
+
+@node Version Controlled Files
+@section Determining if a file is under version control
+
+The VC package uses the existence of on-disk revision control master
+files to determine if a given file is under revision control. These file
+tests happen on the remote machine through the standard @value{tramp} mechanisms.
+
+
+@node Remote Commands
+@section Executing the version control commands on the remote machine
+
+There are no hooks provided by VC to allow intercepting of the version
+control command execution. The calls occur through the
+@code{call-process} mechanism, a function that is somewhat more
+efficient than the @code{shell-command} function but that does not
+provide hooks for remote execution of commands.
+
+To work around this, the functions @code{vc-do-command} and
+@code{vc-simple-command} have been advised to intercept requests for
+operations on files accessed via @value{tramp}.
+
+In the case of a remote file, the @code{shell-command} interface is
+used, with some wrapper code, to provide the same functionality on the
+remote machine as would be seen on the local machine.
+
+
+@node Changed workfiles
+@section Detecting if the working file has changed
+
+As there is currently no way to get access to the mtime of a file on a
+remote machine in a portable way, the @code{vc-workfile-unchanged-p}
+function is advised to call an @value{tramp} specific function for remote files.
+
+The @code{tramp-vc-workfile-unchanged-p} function uses the functioning VC
+diff functionality to determine if any changes have occurred between the
+workfile and the version control master.
+
+This requires that a shell command be executed remotely, a process that
+is notably heavier-weight than the mtime comparison used for local
+files. Unfortunately, unless a portable solution to the issue is found,
+this will remain the cost of remote version control.
+
+
+@node Checking out files
+@section Bringing the workfile out of the repository
+
+VC will, by default, check for remote files and refuse to act on them
+when checking out files from the repository. To work around this
+problem, the function @code{vc-checkout} knows about @value{tramp} files and
+allows version control to occur.
+
+
+@node Miscellaneous Version Control
+@section Things related to Version Control that don't fit elsewhere
+
+Minor implementation details, &c.
+
+@menu
+* Remote File Ownership:: How VC determines who owns a workfile.
+* Back-end Versions:: How VC determines what release your RCS is.
+@end menu
+
+
+@node Remote File Ownership
+@subsection How VC determines who owns a workfile
+
+@value{emacsname} provides the @code{user-login-name} function to
+return the login name of the current user as well as mapping from
+arbitrary user id values back to login names. The VC code uses this
+functionality to map from the uid of the owner of a workfile to the
+login name in some circumstances.
+
+This will not, for obvious reasons, work if the remote system has a
+different set of logins. As such, it is necessary to delegate to the
+remote machine the job of determining the login name associated with a
+uid.
+
+Unfortunately, with the profusion of distributed management systems such
+as @code{NIS}, @code{NIS+} and @code{NetInfo}, there is no simple,
+reliable and portable method for performing this mapping.
+
+Thankfully, the only place in the VC code that depends on the mapping of
+a uid to a login name is the @code{vc-file-owner} function. This returns
+the login of the owner of the file as a string.
+
+This function has been advised to use the output of @command{ls} on the
+remote machine to determine the login name, delegating the problem of
+mapping the uid to the login to the remote system which should know more
+about it than I do.
+
+
+@node Back-end Versions
+@subsection How VC determines what release your RCS is
+
+VC needs to know what release your revision control binaries you are
+running as not all features VC supports are available with older
+versions of @command{rcs(1)}, @command{cvs(1)} or @command{sccs(1)}.
+
+The default implementation of VC determines this value the first time it
+is needed and then stores the value globally to avoid the overhead of
+executing a process and parsing its output each time the information is
+needed.
+
+Unfortunately, life is not quite so easy when remote version control
+comes into the picture. Each remote machine may have a different version
+of the version control tools and, while this is painful, we need to
+ensure that unavailable features are not used remotely.
+
+To resolve this issue, @value{tramp} currently takes the sledgehammer
+approach of making the release values of the revision control tools
+local to each @value{tramp} buffer, forcing VC to determine these values
+again each time a new file is visited.
+
+This has, quite obviously, some performance implications. Thankfully,
+most of the common operations performed by VC do not actually require
+that the remote version be known. This makes the problem far less
+apparent.
+
+Eventually these values will be captured by @value{tramp} on a system by
+system basis and the results cached to improve performance.
+
+
+@node Files directories and localnames
+@chapter How file names, directories and localnames are mangled and managed.
+
+@menu
+* Localname deconstruction:: Breaking a localname into its components.
+@end menu
+
+
+@node Localname deconstruction
+@section Breaking a localname into its components.
+
+@value{tramp} file names are somewhat different, obviously, to ordinary file
+names. As such, the lisp functions @code{file-name-directory} and
+@code{file-name-nondirectory} are overridden within the @value{tramp}
+package.
+
+Their replacements are reasonably simplistic in their approach. They
+dissect the filename, call the original handler on the localname and
+then rebuild the @value{tramp} file name with the result.
+
+This allows the platform specific hacks in the original handlers to take
+effect while preserving the @value{tramp} file name information.
+
+
+@node Traces and Profiles
+@chapter How to Customize Traces
+
+All @value{tramp} messages are raised with a verbosity level. The
+verbosity level can be any number between 0 and 10. Only messages with
+a verbosity level less than or equal to @code{tramp-verbose} are
+displayed.
+
+The verbosity levels are
+
+ @w{ 0} silent (no @value{tramp} messages at all)
+@*@indent @w{ 1} errors
+@*@indent @w{ 2} warnings
+@*@indent @w{ 3} connection to remote hosts (default verbosity)
+@*@indent @w{ 4} activities
+@*@indent @w{ 5} internal
+@*@indent @w{ 6} sent and received strings
+@*@indent @w{ 7} file caching
+@*@indent @w{ 8} connection properties
+@*@indent @w{10} traces (huge)
+
+When @code{tramp-verbose} is greater than or equal to 4, the messages
+are also written into a @value{tramp} debug buffer. This debug buffer
+is useful for analysing problems; sending a @value{tramp} bug report
+should be done with @code{tramp-verbose} set to a verbosity level of at
+least 6 (@pxref{Bug Reports}).
+
+The debug buffer is in
+@ifinfo
+@ref{Outline Mode, , , @value{emacsdir}}.
+@end ifinfo
+@ifnotinfo
+Outline Mode.
+@end ifnotinfo
+That means, you can change the level of messages to be viewed. If you
+want, for example, see only messages up to verbosity level 5, you must
+enter @kbd{C-u 6 C-c C-q}.
+@ifinfo
+Other keys for navigating are described in
+@ref{Outline Visibility, , , @value{emacsdir}}.
+@end ifinfo
+
+@value{tramp} errors are handled internally in order to raise the
+verbosity level 1 messages. When you want to get a Lisp backtrace in
+case of an error, you need to set both
+
+@lisp
+(setq debug-on-error t
+ debug-on-signal t)
+@end lisp
+
+Sometimes, it might be even necessary to step through @value{tramp}
+function call traces. Such traces are enabled by the following code:
+
+@lisp
+(require 'tramp)
+(require 'trace)
+(mapcar 'trace-function-background
+ (mapcar 'intern
+ (all-completions "tramp-" obarray 'functionp)))
+(untrace-function 'tramp-read-passwd)
+(untrace-function 'tramp-gw-basic-authentication)
+@end lisp
+
+The function call traces are inserted in the buffer
+@file{*trace-output*}. @code{tramp-read-passwd} and
+@code{tramp-gw-basic-authentication} shall be disabled when the
+function call traces are added to @value{tramp}, because both
+functions return password strings, which should not be distributed.
+
+
+@node Issues
+@chapter Debatable Issues and What Was Decided
+
+@itemize @bullet
+@item The uuencode method does not always work.
+
+Due to the design of @value{tramp}, the encoding and decoding programs
+need to read from stdin and write to stdout. On some systems,
+@command{uudecode -o -} will read stdin and write the decoded file to
+stdout, on other systems @command{uudecode -p} does the same thing.
+But some systems have uudecode implementations which cannot do this at
+all---it is not possible to call these uudecode implementations with
+suitable parameters so that they write to stdout.
+
+Of course, this could be circumvented: the @code{begin foo 644} line
+could be rewritten to put in some temporary file name, then
+@command{uudecode} could be called, then the temp file could be
+printed and deleted.
+
+But I have decided that this is too fragile to reliably work, so on some
+systems you'll have to do without the uuencode methods.
+
+@item The @value{tramp} filename syntax differs between GNU Emacs and XEmacs.
+
+The GNU Emacs maintainers wish to use a unified filename syntax for
+Ange-FTP and @value{tramp} so that users don't have to learn a new
+syntax. It is sufficient to learn some extensions to the old syntax.
+
+For the XEmacs maintainers, the problems caused from using a unified
+filename syntax are greater than the gains. The XEmacs package system
+uses EFS for downloading new packages. So, obviously, EFS has to be
+installed from the start. If the filenames were unified, @value{tramp}
+would have to be installed from the start, too.
+
+@ifset xemacs
+@strong{Note:} If you'd like to use a similar syntax like
+@value{ftppackagename}, you need the following settings in your init
+file:
+
+@lisp
+(setq tramp-unified-filenames t)
+(require 'tramp)
+@end lisp
+
+The autoload of the @value{emacsname} @value{tramp} package must be
+disabled. This can be achieved by setting file permissions @code{000}
+to the files @file{.../xemacs-packages/lisp/tramp/auto-autoloads.el*}.
+
+In case of unified filenames, all @value{emacsname} download sites are
+added to @code{tramp-default-method-alist} with default method
+@option{ftp} @xref{Default Method}. These settings shouldn't be
+touched for proper working of the @value{emacsname} package system.
+
+The syntax for unified filenames is described in the @value{tramp} manual
+for @value{emacsothername}.
+@end ifset
+@end itemize
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Concept Index
+@comment node-name, next, previous, up
+@unnumbered Concept Index
+@printindex cp
+@contents
+@c End of tramp.texi - the TRAMP User Manual
+@bye
+
+@c TODO
+@c
+@c * Say something about the .login and .profile files of the remote
+@c shells.
+@c * Explain how tramp.el works in principle: open a shell on a remote
+@c host and then send commands to it.
+@c * Make terminology "inline" vs "out-of-band" consistent.
+@c It seems that "external" is also used instead of "out-of-band".
+
+@c * M. Albinus
+@c ** Use `filename' resp. `file name' consistently.
+@c ** Use `host' resp. `machine' consistently.
+@c ** Consistent small or capitalized words especially in menues.
+
+@ignore
+ arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808
+@end ignore
--- /dev/null
+@c -*-texinfo-*-
+@c texi/trampver.texi. Generated from trampver.texi.in by configure.
+
+@c In the Tramp CVS, the version number is auto-frobbed from
+@c configure.ac, so you should edit that file and run
+@c "autoconf && ./configure" to change the version number.
+@set trampver 2.1.11-pre
+
+@c Other flags from configuration
+@set instprefix /usr/local
+@set lispdir /usr/local/share/emacs/site-lisp
+@set infodir /usr/local/info
+
+@c Formatting of the tramp program name consistent.
+@set tramp @sc{tramp}
+
+@c Whether or not describe gateway methods.
+@ifclear noemacsgw
+@set emacsgw
+@end ifclear
+
+@c Some flags which make the text independent on the (X)Emacs flavor.
+@c "emacs" resp "xemacs" are set in the Makefile. Default is "emacs".
+@ifclear emacs
+@ifclear xemacs
+@set emacs
+@end ifclear
+@end ifclear
+
+@c Emacs values.
+@ifset emacs
+@set emacsname GNU Emacs
+@set emacsdir emacs
+@set ftppackagename Ange-FTP
+@set prefix /
+@set prefixhop
+@set postfix :
+@set postfixhop :
+@set emacsothername XEmacs
+@set emacsotherdir xemacs
+@set emacsotherfilename tramp-xemacs.html
+@set japanesemanual tramp_ja-emacs.html
+@end ifset
+
+@c XEmacs counterparts.
+@ifset xemacs
+@set emacsname XEmacs
+@set emacsdir xemacs
+@set ftppackagename EFS
+@set prefix /[
+@set prefixhop [
+@set postfix ]
+@set postfixhop /
+@set emacsothername GNU Emacs
+@set emacsotherdir emacs
+@set emacsotherfilename tramp-emacs.html
+@set japanesemanual tramp_ja-xemacs.html
+@end ifset
+
+@ignore
+ arch-tag: e0fe322c-e06b-46eb-bb5b-d091b521f41c
+@end ignore
--- /dev/null
+\input texinfo
+@setfilename ../info/url
+@settitle URL Programmer's Manual
+
+@iftex
+@c @finalout
+@end iftex
+@c @setchapternewpage odd
+@c @smallbook
+
+@tex
+\overfullrule=0pt
+%\global\baselineskip 30pt % for printing in double space
+@end tex
+@dircategory World Wide Web
+@dircategory GNU Emacs Lisp
+@direntry
+* URL: (url). URL loading package.
+@end direntry
+
+@ifnottex
+This file documents the URL loading package.
+
+Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2002,
+2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being
+``GNU GENERAL PUBLIC LICENSE''. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License.''
+@end ifnottex
+
+@c
+@titlepage
+@sp 6
+@center @titlefont{URL}
+@center @titlefont{Programmer's Manual}
+@sp 4
+@center First Edition, URL Version 2.0
+@sp 1
+@c @center December 1999
+@sp 5
+@center William M. Perry
+@center @email{wmperry@@gnu.org}
+@center David Love
+@center @email{fx@@gnu.org}
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2002,
+2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being
+``GNU GENERAL PUBLIC LICENSE''. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License.''
+@end titlepage
+@page
+@node Top
+@top URL
+
+
+
+@menu
+* Getting Started:: Preparing your program to use URLs.
+* Retrieving URLs:: How to use this package to retrieve a URL.
+* Supported URL Types:: Descriptions of URL types currently supported.
+* Defining New URLs:: How to define a URL loader for a new protocol.
+* General Facilities:: URLs can be cached, accessed via a gateway
+ and tracked in a history list.
+* Customization:: Variables you can alter.
+* GNU Free Documentation License:: The license for this documentation.
+* Function Index::
+* Variable Index::
+* Concept Index::
+@end menu
+
+@node Getting Started
+@chapter Getting Started
+@cindex URLs, definition
+@cindex URIs
+
+@dfn{Uniform Resource Locators} (URLs) are a specific form of
+@dfn{Uniform Resource Identifiers} (URI) described in RFC 2396 which
+updates RFC 1738 and RFC 1808. RFC 2016 defines uniform resource
+agents.
+
+URIs have the form @var{scheme}:@var{scheme-specific-part}, where the
+@var{scheme}s supported by this library are described below.
+@xref{Supported URL Types}.
+
+FTP, NFS, HTTP, HTTPS, @code{rlogin}, @code{telnet}, tn3270,
+IRC and gopher URLs all have the form
+
+@example
+@var{scheme}://@r{[}@var{userinfo}@@@r{]}@var{hostname}@r{[}:@var{port}@r{]}@r{[}/@var{path}@r{]}
+@end example
+@noindent
+where @samp{@r{[}} and @samp{@r{]}} delimit optional parts.
+@var{userinfo} sometimes takes the form @var{username}:@var{password}
+but you should beware of the security risks of sending cleartext
+passwords. @var{hostname} may be a domain name or a dotted decimal
+address. If the @samp{:@var{port}} is omitted then the library will
+use the `well known' port for that service when accessing URLs. With
+the possible exception of @code{telnet}, it is rare for ports to be
+specified, and it is possible using a non-standard port may have
+undesired consequences if a different service is listening on that
+port (e.g., an HTTP URL specifying the SMTP port can cause mail to be
+sent). @c , but @xref{Other Variables, url-bad-port-list}.
+The meaning of the @var{path} component depends on the service.
+
+@menu
+* Configuration::
+* Parsed URLs:: URLs are parsed into vector structures.
+@end menu
+
+@node Configuration
+@section Configuration
+
+@defvar url-configuration-directory
+@cindex @file{~/.url}
+@cindex configuration files
+The directory in which URL configuration files, the cache etc.,
+reside. Default @file{~/.url}.
+@end defvar
+
+@node Parsed URLs
+@section Parsed URLs
+@cindex parsed URLs
+The library functions typically operate on @dfn{parsed} versions of
+URLs. These are actually vectors of the form:
+
+@example
+[@var{type} @var{user} @var{password} @var{host} @var{port} @var{file} @var{target} @var{attributes} @var{full}]
+@end example
+
+@noindent where
+@table @var
+@item type
+is the type of the URL scheme, e.g., @code{http}
+@item user
+is the username associated with it, or @code{nil};
+@item password
+is the user password associated with it, or @code{nil};
+@item host
+is the host name associated with it, or @code{nil};
+@item port
+is the port number associated with it, or @code{nil};
+@item file
+is the `file' part of it, or @code{nil}. This doesn't necessarily
+actually refer to a file;
+@item target
+is the target part, or @code{nil};
+@item attributes
+is the attributes associated with it, or @code{nil};
+@item full
+is @code{t} for a fully-specified URL, with a host part indicated by
+@samp{//} after the scheme part.
+@end table
+
+@findex url-type
+@findex url-user
+@findex url-password
+@findex url-host
+@findex url-port
+@findex url-file
+@findex url-target
+@findex url-attributes
+@findex url-full
+@findex url-set-type
+@findex url-set-user
+@findex url-set-password
+@findex url-set-host
+@findex url-set-port
+@findex url-set-file
+@findex url-set-target
+@findex url-set-attributes
+@findex url-set-full
+These attributes have accessors named @code{url-@var{part}}, where
+@var{part} is the name of one of the elements above, e.g.,
+@code{url-host}. Similarly, there are setters of the form
+@code{url-set-@var{part}}.
+
+There are functions for parsing and unparsing between the string and
+vector forms.
+
+@defun url-generic-parse-url url
+Return a parsed version of the string @var{url}.
+@end defun
+
+@defun url-recreate-url url
+@cindex unparsing URLs
+Recreates a URL string from the parsed @var{url}.
+@end defun
+
+@node Retrieving URLs
+@chapter Retrieving URLs
+
+@defun url-retrieve-synchronously url
+Retrieve @var{url} synchronously and return a buffer containing the
+data. @var{url} is either a string or a parsed URL structure. Return
+@code{nil} if there are no data associated with it (the case for dired,
+info, or mailto URLs that need no further processing).
+@end defun
+
+@defun url-retrieve url callback &optional cbargs
+Retrieve @var{url} asynchronously and call @var{callback} with args
+@var{cbargs} when finished. The callback is called when the object
+has been completely retrieved, with the current buffer containing the
+object and any MIME headers associated with it. @var{url} is either a
+string or a parsed URL structure. Returns the buffer @var{url} will
+load into, or @code{nil} if the process has already completed.
+@end defun
+
+@node Supported URL Types
+@chapter Supported URL Types
+
+@menu
+* http/https:: Hypertext Transfer Protocol.
+* file/ftp:: Local files and FTP archives.
+* info:: Emacs `Info' pages.
+* mailto:: Sending email.
+* news/nntp/snews:: Usenet news.
+* rlogin/telnet/tn3270:: Remote host connectivity.
+* irc:: Internet Relay Chat.
+* data:: Embedded data URLs.
+* nfs:: Networked File System
+@c * finger::
+@c * gopher::
+@c * netrek::
+@c * prospero::
+* cid:: Content-ID.
+* about::
+* ldap:: Lightweight Directory Access Protocol
+* imap:: IMAP mailboxes.
+* man:: Unix man pages.
+@end menu
+
+@node http/https
+@section @code{http} and @code{https}
+
+The scheme @code{http} is Hypertext Transfer Protocol. The library
+supports version 1.1, specified in RFC 2616. (This supersedes 1.0,
+defined in RFC 1945) HTTP URLs have the following form, where most of
+the parts are optional:
+@example
+http://@var{user}:@var{password}@@@var{host}:@var{port}/@var{path}?@var{searchpart}#@var{fragment}
+@end example
+@c The @code{:@var{port}} part is optional, and @var{port} defaults to
+@c 80. The @code{/@var{path}} part, if present, is a slash-separated
+@c series elements. The @code{?@var{searchpart}}, if present, is the
+@c query for a search or the content of a form submission. The
+@c @code{#fragment} part, if present, is a location in the document.
+
+The scheme @code{https} is a secure version of @code{http}, with
+transmission via SSL. It is defined in RFC 2069. Its default port is
+443. This scheme depends on SSL support in Emacs via the
+@file{ssl.el} library and is actually implemented by forcing the
+@code{ssl} gateway method to be used. @xref{Gateways in general}.
+
+@defopt url-honor-refresh-requests
+This controls honouring of HTTP @samp{Refresh} headers by which
+servers can direct clients to reload documents from the same URL or a
+or different one. @code{nil} means they will not be honoured,
+@code{t} (the default) means they will always be honoured, and
+otherwise the user will be asked on each request.
+@end defopt
+
+
+@menu
+* Cookies::
+* HTTP language/coding::
+* HTTP URL Options::
+* Dealing with HTTP documents::
+@end menu
+
+@node Cookies
+@subsection Cookies
+
+@defopt url-cookie-file
+The file in which cookies are stored, defaulting to @file{cookies} in
+the directory specified by @code{url-configuration-directory}.
+@end defopt
+
+@defopt url-cookie-confirmation
+Specifies whether confirmation is require to accept cookies.
+@end defopt
+
+@defopt url-cookie-multiple-line
+Specifies whether to put all cookies for the server on one line in the
+HTTP request to satisfy broken servers like
+@url{http://www.hotmail.com}.
+@end defopt
+
+@defopt url-cookie-trusted-urls
+A list of regular expressions matching URLs from which to accept
+cookies always.
+@end defopt
+
+@defopt url-cookie-untrusted-urls
+A list of regular expressions matching URLs from which to reject
+cookies always.
+@end defopt
+
+@defopt url-cookie-save-interval
+The number of seconds between automatic saves of cookies to disk.
+Default is one hour.
+@end defopt
+
+
+@node HTTP language/coding
+@subsection Language and Encoding Preferences
+
+HTTP allows clients to express preferences for the language and
+encoding of documents which servers may honour. For each of these
+variables, the value is a string; it can specify a single choice, or
+it can be a comma-separated list.
+
+Normally this list ordered by descending preference. However, each
+element can be followed by @samp{;q=@var{priority}} to specify its
+preference level, a decimal number from 0 to 1; e.g., for
+@code{url-mime-language-string}, @w{@code{"de, en-gb;q=0.8,
+en;q=0.7"}}. An element that has no @samp{;q} specification has
+preference level 1.
+
+@defopt url-mime-charset-string
+@cindex character sets
+@cindex coding systems
+This variable specifies a preference for character sets when documents
+can be served in more than one encoding.
+
+HTTP allows specifying a series of MIME charsets which indicate your
+preferred character set encodings, e.g., Latin-9 or Big5, and these
+can be weighted. The default series is generated automatically from
+the associated MIME types of all defined coding systems, sorted by the
+coding system priority specified in Emacs. @xref{Recognize Coding, ,
+Recognizing Coding Systems, emacs, The GNU Emacs Manual}.
+@end defopt
+
+@defopt url-mime-language-string
+@cindex language preferences
+A string specifying the preferred language when servers can serve
+files in several languages. Use RFC 1766 abbreviations, e.g.,
+@samp{en} for English, @samp{de} for German.
+
+The string can be @code{"*"} to get the first available language (as
+opposed to the default).
+@end defopt
+
+@node HTTP URL Options
+@subsection HTTP URL Options
+
+HTTP supports an @samp{OPTIONS} method describing things supported by
+the URL@.
+
+@defun url-http-options url
+Returns a property list describing options available for URL. The
+property list members are:
+
+@table @code
+@item methods
+A list of symbols specifying what HTTP methods the resource
+supports.
+
+@item dav
+@cindex DAV
+A list of numbers specifying what DAV protocol/schema versions are
+supported.
+
+@item dasl
+@cindex DASL
+A list of supported DASL search types supported (string form).
+
+@item ranges
+A list of the units available for use in partial document fetches.
+
+@item p3p
+@cindex P3P
+The @dfn{Platform For Privacy Protection} description for the resource.
+Currently this is just the raw header contents.
+@end table
+
+@end defun
+
+@node Dealing with HTTP documents
+@subsection Dealing with HTTP documents
+
+HTTP URLs are retrieved into a buffer containing the HTTP headers
+followed by the body. Since the headers are quasi-MIME, they may be
+processed using the MIME library. @xref{Top,, Emacs MIME,
+emacs-mime, The Emacs MIME Manual}. The URL package provides a
+function to do this in general:
+
+@defun url-decode-text-part handle &optional coding
+This function decodes charset-encoded text in the current buffer. In
+Emacs, the buffer is expected to be unibyte initially and is set to
+multibyte after decoding.
+HANDLE is the MIME handle of the original part. CODING is an explicit
+coding to use, overriding what the MIME headers specify.
+The coding system used for the decoding is returned.
+
+Note that this function doesn't deal with @samp{http-equiv} charset
+specifications in HTML @samp{<meta>} elements.
+@end defun
+
+@node file/ftp
+@section file and ftp
+@cindex files
+@cindex FTP
+@cindex File Transfer Protocol
+@cindex compressed files
+@cindex dired
+
+@example
+ftp://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
+file://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
+@end example
+
+These schemes are defined in RFC 1808.
+@samp{ftp:} and @samp{file:} are synonymous in this library. They
+allow reading arbitrary files from hosts. Either @samp{ange-ftp}
+(Emacs) or @samp{efs} (XEmacs) is used to retrieve them from remote
+hosts. Local files are accessed directly.
+
+Compressed files are handled, but support is hard-coded so that
+@code{jka-compr-compression-info-list} and so on have no affect.
+Suffixes recognized are @samp{.z}, @samp{.gz}, @samp{.Z} and
+@samp{.bz2}.
+
+@defopt url-directory-index-file
+The filename to look for when indexing a directory, default
+@samp{"index.html"}. If this file exists, and is readable, then it
+will be viewed instead of using @code{dired} to view the directory.
+@end defopt
+
+@node info
+@section info
+@cindex Info
+@cindex Texinfo
+@findex Info-goto-node
+
+@example
+info:@var{file}#@var{node}
+@end example
+
+Info URLs are not officially defined. They invoke
+@code{Info-goto-node} with argument @samp{(@var{file})@var{node}}.
+@samp{#@var{node}} is optional, defaulting to @samp{Top}.
+
+@node mailto
+@section mailto
+
+@cindex mailto
+@cindex email
+A mailto URL will send an email message to the address in the
+URL, for example @samp{mailto:foo@@bar.com} would compose a
+message to @samp{foo@@bar.com}.
+
+@defopt url-mail-command
+@vindex mail-user-agent
+The function called whenever url needs to send mail. This should
+normally be left to default from @var{mail-user-agent}. @xref{Mail
+Methods, , Mail-Composition Methods, emacs, The GNU Emacs Manual}.
+@end defopt
+
+An @samp{X-Url-From} header field containing the URL of the document
+that contained the mailto URL is added if that URL is known.
+
+RFC 2368 extends the definition of mailto URLs in RFC 1738.
+The form of a mailto URL is
+@example
+@samp{mailto:@var{mailbox}[?@var{header}=@var{contents}[&@var{header}=@var{contents}]]}
+@end example
+@noindent where an arbitrary number of @var{header}s can be added. If the
+@var{header} is @samp{body}, then @var{contents} is put in the body
+otherwise a @var{header} header field is created with @var{contents}
+as its contents. Note that the URL library does not consider any
+headers `dangerous' so you should check them before sending the
+message.
+
+@c Fixme: update
+Email messages are defined in @sc{rfc}822.
+
+@node news/nntp/snews
+@section @code{news}, @code{nntp} and @code{snews}
+@cindex news
+@cindex network news
+@cindex usenet
+@cindex NNTP
+@cindex snews
+
+@c draft-gilman-news-url-01
+The network news URL scheme take the following forms following RFC
+1738 except that for compatibility with other clients, host and port
+fields may be included in news URLs though they are properly only
+allowed for nntp an snews.
+
+@table @samp
+@item news:@var{newsgroup}
+Retrieves a list of messages in @var{newsgroup};
+@item news:@var{message-id}
+Retrieves the message with the given @var{message-id};
+@item news:*
+Retrieves a list of all available newsgroups;
+@item nntp://@var{host}:@var{port}/@var{newsgroup}
+@itemx nntp://@var{host}:@var{port}/@var{message-id}
+@itemx nntp://@var{host}:@var{port}/*
+Similar to the @samp{news} versions.
+@end table
+
+@samp{:@var{port}} is optional and defaults to :119.
+
+@samp{snews} is the same as @samp{nntp} except that the default port
+is :563.
+@cindex SSL
+(It is tunneled through SSL.)
+
+An @samp{nntp} URL is the same as a news URL, except that the URL may
+specify an article by its number.
+
+@defopt url-news-server
+This variable can be used to override the default news server.
+Usually this will be set by the Gnus package, which is used to fetch
+news.
+@cindex environment variable
+@vindex NNTPSERVER
+It may be set from the conventional environment variable
+@code{NNTPSERVER}.
+@end defopt
+
+@node rlogin/telnet/tn3270
+@section rlogin, telnet and tn3270
+@cindex rlogin
+@cindex telnet
+@cindex tn3270
+@cindex terminal emulation
+@findex terminal-emulator
+
+These URL schemes from RFC 1738 for logon via a terminal emulator have
+the form
+@example
+telnet://@var{user}:@var{password}@@@var{host}:@var{port}
+@end example
+but the @code{:@var{password}} component is ignored.
+
+To handle rlogin, telnet and tn3270 URLs, a @code{rlogin},
+@code{telnet} or @code{tn3270} (the program names and arguments are
+hardcoded) session is run in a @code{terminal-emulator} buffer.
+Well-known ports are used if the URL does not specify a port.
+
+@node irc
+@section irc
+@cindex IRC
+@cindex Internet Relay Chat
+@cindex ZEN IRC
+@cindex ERC
+@cindex rcirc
+@c Fixme: reference (was http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt)
+@dfn{Internet Relay Chat} (IRC) is handled by handing off the @sc{irc}
+session to a function named in @code{url-irc-function}.
+
+@defopt url-irc-function
+A function to actually open an IRC connection.
+This function
+must take five arguments, @var{host}, @var{port}, @var{channel},
+@var{user} and @var{password}. The @var{channel} argument specifies the
+channel to join immediately, this can be @code{nil}. By default this is
+@code{url-irc-rcirc}.
+@end defopt
+@defun url-irc-rcirc host port channel user password
+Processes the arguments and lets @code{rcirc} handle the session.
+@end defun
+@defun url-irc-erc host port channel user password
+Processes the arguments and lets @code{ERC} handle the session.
+@end defun
+@defun url-irc-zenirc host port channel user password
+Processes the arguments and lets @code{zenirc} handle the session.
+@end defun
+
+@node data
+@section data
+@cindex data URLs
+
+@example
+data:@r{[}@var{media-type}@r{]}@r{[};@var{base64}@r{]},@var{data}
+@end example
+
+Data URLs contain MIME data in the URL itself. They are defined in
+RFC 2397.
+
+@var{media-type} is a MIME @samp{Content-Type} string, possibly
+including parameters. It defaults to
+@samp{text/plain;charset=US-ASCII}. The @samp{text/plain} can be
+omitted but the charset parameter supplied. If @samp{;base64} is
+present, the @var{data} are base64-encoded.
+
+@node nfs
+@section nfs
+@cindex NFS
+@cindex Network File System
+@cindex automounter
+
+@example
+nfs://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
+@end example
+
+The @samp{nfs:} scheme is defined in RFC 2224. It is similar to
+@samp{ftp:} except that it points to a file on a remote host that is
+handled by the automounter on the local host.
+
+@defvar url-nfs-automounter-directory-spec
+@end defvar
+A string saying how to invoke the NFS automounter. Certain @samp{%}
+sequences are recognized:
+
+@table @samp
+@item %h
+The hostname of the NFS server;
+@item %n
+The port number of the NFS server;
+@item %u
+The username to use to authenticate;
+@item %p
+The password to use to authenticate;
+@item %f
+The filename on the remote server;
+@item %%
+A literal @samp{%}.
+@end table
+
+Each can be used any number of times.
+
+@node cid
+@section cid
+@cindex Content-ID
+
+RFC 2111
+
+@node about
+@section about
+
+@node ldap
+@section ldap
+@cindex LDAP
+@cindex Lightweight Directory Access Protocol
+
+The LDAP scheme is defined in RFC 2255.
+
+@node imap
+@section imap
+@cindex IMAP
+
+RFC 2192
+
+@node man
+@section man
+@cindex @command{man}
+@cindex Unix man pages
+@findex man
+
+@example
+@samp{man:@var{page-spec}}
+@end example
+
+This is a non-standard scheme. @var{page-spec} is passed directly to
+the Lisp @code{man} function.
+
+@node Defining New URLs
+@chapter Defining New URLs
+
+@menu
+* Naming conventions::
+* Required functions::
+* Optional functions::
+* Asynchronous fetching::
+* Supporting file-name-handlers::
+@end menu
+
+@node Naming conventions
+@section Naming conventions
+
+@node Required functions
+@section Required functions
+
+@node Optional functions
+@section Optional functions
+
+@node Asynchronous fetching
+@section Asynchronous fetching
+
+@node Supporting file-name-handlers
+@section Supporting file-name-handlers
+
+@node General Facilities
+@chapter General Facilities
+
+@menu
+* Disk Caching::
+* Proxies::
+* Gateways in general::
+* History::
+@end menu
+
+@node Disk Caching
+@section Disk Caching
+@cindex Caching
+@cindex Persistent Cache
+@cindex Disk Cache
+
+The disk cache stores retrieved documents locally, whence they can be
+retrieved more quickly. When requesting a URL that is in the cache,
+the library checks to see if the page has changed since it was last
+retrieved from the remote machine. If not, the local copy is used,
+saving the transmission over the network.
+@cindex Cleaning the cache
+@cindex Clearing the cache
+@cindex Cache cleaning
+Currently the cache isn't cleared automatically.
+@c Running the @code{clean-cache} shell script
+@c fist is recommended, to allow for future cleaning of the cache. This
+@c shell script will remove all files that have not been accessed since it
+@c was last run. To keep the cache pared down, it is recommended that this
+@c script be run from @i{at} or @i{cron} (see the manual pages for
+@c crontab(5) or at(1) for more information)
+
+@defopt url-automatic-caching
+Setting this variable non-@code{nil} causes documents to be cached
+automatically.
+@end defopt
+
+@defopt url-cache-directory
+This variable specifies the
+directory to store the cache files. It defaults to sub-directory
+@file{cache} of @code{url-configuration-directory}.
+@end defopt
+
+@c Fixme: function v. option, but neither used.
+@c @findex url-cache-expired
+@c @defopt url-cache-expired
+@c This is a function to decide whether or not a cache entry has expired.
+@c It takes two times as it parameters and returns non-@code{nil} if the
+@c second time is ``too old'' when compared with the first time.
+@c @end defopt
+
+@defopt url-cache-creation-function
+The cache relies on a scheme for mapping URLs to files in the cache.
+This variable names a function which sets the type of cache to use.
+It takes a URL as argument and returns the absolute file name of the
+corresponding cache file. The two supplied possibilities are
+@code{url-cache-create-filename-using-md5} and
+@code{url-cache-create-filename-human-readable}.
+@end defopt
+
+@defun url-cache-create-filename-using-md5 url
+Creates a cache file name from @var{url} using MD5 hashing.
+This is creates entries with very few cache collisions and is fast.
+@cindex MD5
+@smallexample
+(url-cache-create-filename-using-md5 "http://www.example.com/foo/bar")
+ @result{} "/home/fx/.url/cache/fx/http/com/example/www/b8a35774ad20db71c7c3409a5410e74f"
+@end smallexample
+@end defun
+
+@defun url-cache-create-filename-human-readable url
+Creates a cache file name from @var{url} more obviously connected to
+@var{url} than for @code{url-cache-create-filename-using-md5}, but
+more likely to conflict with other files.
+@smallexample
+(url-cache-create-filename-human-readable "http://www.example.com/foo/bar")
+ @result{} "/home/fx/.url/cache/fx/http/com/example/www/foo/bar"
+@end smallexample
+@end defun
+
+@c Fixme: never actually used currently?
+@c @defopt url-standalone-mode
+@c @cindex Relying on cache
+@c @cindex Cache only mode
+@c @cindex Standalone mode
+@c If this variable is non-@code{nil}, the library relies solely on the
+@c cache for fetching documents and avoids checking if they have changed
+@c on remote servers.
+@c @end defopt
+
+@c With a large cache of documents on the local disk, it can be very handy
+@c when traveling, or any other time the network connection is not active
+@c (a laptop with a dial-on-demand PPP connection, etc). Emacs/W3 can rely
+@c solely on its cache, and avoid checking to see if the page has changed
+@c on the remote server. In the case of a dial-on-demand PPP connection,
+@c this will keep the phone line free as long as possible, only bringing up
+@c the PPP connection when asking for a page that is not located in the
+@c cache. This is very useful for demonstrations as well.
+
+@node Proxies
+@section Proxies and Gatewaying
+
+@c fixme: check/document url-ns stuff
+@cindex proxy servers
+@cindex proxies
+@cindex environment variables
+@vindex HTTP_PROXY
+Proxy servers are commonly used to provide gateways through firewalls
+or as caches serving some more-or-less local network. Each protocol
+(HTTP, FTP, etc.)@: can have a different gateway server. Proxying is
+conventionally configured commonly amongst different programs through
+environment variables of the form @code{@var{protocol}_proxy}, where
+@var{protocol} is one of the supported network protocols (@code{http},
+@code{ftp} etc.). The library recognizes such variables in either
+upper or lower case. Their values are of one of the forms:
+@itemize @bullet
+@item @code{@var{host}:@var{port}}
+@item A full URL;
+@item Simply a host name.
+@end itemize
+
+@vindex NO_PROXY
+The @code{NO_PROXY} environment variable specifies URLs that should be
+excluded from proxying (on servers that should be contacted directly).
+This should be a comma-separated list of hostnames, domain names, or a
+mixture of both. Asterisks can be used as wildcards, but other
+clients may not support that. Domain names may be indicated by a
+leading dot. For example:
+@example
+NO_PROXY="*.aventail.com,home.com,.seanet.com"
+@end example
+@noindent says to contact all machines in the @samp{aventail.com} and
+@samp{seanet.com} domains directly, as well as the machine named
+@samp{home.com}. If @code{NO_PROXY} isn't defined, @code{no_PROXY}
+and @code{no_proxy} are also tried, in that order.
+
+Proxies may also be specified directly in Lisp.
+
+@defopt url-proxy-services
+This variable is an alist of URL schemes and proxy servers that
+gateway them. The items are of the form @w{@code{(@var{scheme}
+. @var{host}:@var{portnumber})}}, says that the URL @var{scheme} is
+gatewayed through @var{portnumber} on the specified @var{host}. An
+exception is the pseudo scheme @code{"no_proxy"}, which is paired with
+a regexp matching host names not to be proxied. This variable is
+initialized from the environment as above.
+
+@example
+(setq url-proxy-services
+ '(("http" . "proxy.aventail.com:80")
+ ("no_proxy" . "^.*\\(aventail\\|seanet\\)\\.com")))
+@end example
+@end defopt
+
+@node Gateways in general
+@section Gateways in General
+@cindex gateways
+@cindex firewalls
+
+The library provides a general gateway layer through which all
+networking passes. It can both control access to the network and
+provide access through gateways in firewalls. This may make direct
+connections in some cases and pass through some sort of gateway in
+others.@footnote{Proxies (which only operate over HTTP) are
+implemented using this.} The library's basic function responsible for
+making connections is @code{url-open-stream}.
+
+@defun url-open-stream name buffer host service
+@cindex opening a stream
+@cindex stream, opening
+Open a stream to @var{host}, possibly via a gateway. The other
+arguments are as for @code{open-network-stream}. This will not make a
+connection if @code{url-gateway-unplugged} is non-@code{nil}.
+@end defun
+
+@defvar url-gateway-local-host-regexp
+This is a regular expression that matches local hosts that do not
+require the use of a gateway. If @code{nil}, all connections are made
+through the gateway.
+@end defvar
+
+@defvar url-gateway-method
+This variable controls which gateway method is used. It may be useful
+to bind it temporarily in some applications. It has values taken from
+a list of symbols. Possible values are:
+
+@table @code
+@item telnet
+@cindex @command{telnet}
+Use this method if you must first telnet and log into a gateway host,
+and then run telnet from that host to connect to outside machines.
+
+@item rlogin
+@cindex @command{rlogin}
+This method is identical to @code{telnet}, but uses @command{rlogin}
+to log into the remote machine without having to send the username and
+password over the wire every time.
+
+@item socks
+@cindex @sc{socks}
+Use if the firewall has a @sc{socks} gateway running on it. The
+@sc{socks} v5 protocol is defined in RFC 1928.
+
+@c @item ssl
+@c This probably shouldn't be documented
+@c Fixme: why not? -- fx
+
+@item native
+This method uses Emacs's builtin networking directly. This is the
+default. It can be used only if there is no firewall blocking access.
+@end table
+@end defvar
+
+The following variables control the gateway methods.
+
+@defopt url-gateway-telnet-host
+The gateway host to telnet to. Once logged in there, you then telnet
+out to the hosts you want to connect to.
+@end defopt
+@defopt url-gateway-telnet-parameters
+This should be a list of parameters to pass to the @command{telnet} program.
+@end defopt
+@defopt url-gateway-telnet-password-prompt
+This is a regular expression that matches the password prompt when
+logging in.
+@end defopt
+@defopt url-gateway-telnet-login-prompt
+This is a regular expression that matches the username prompt when
+logging in.
+@end defopt
+@defopt url-gateway-telnet-user-name
+The username to log in with.
+@end defopt
+@defopt url-gateway-telnet-password
+The password to send when logging in.
+@end defopt
+@defopt url-gateway-prompt-pattern
+This is a regular expression that matches the shell prompt.
+@end defopt
+
+@defopt url-gateway-rlogin-host
+Host to @samp{rlogin} to before telnetting out.
+@end defopt
+@defopt url-gateway-rlogin-parameters
+Parameters to pass to @samp{rsh}.
+@end defopt
+@defopt url-gateway-rlogin-user-name
+User name to use when logging in to the gateway.
+@end defopt
+@defopt url-gateway-prompt-pattern
+This is a regular expression that matches the shell prompt.
+@end defopt
+
+@defopt socks-server
+This specifies the default server, it takes the form
+@w{@code{("Default server" @var{server} @var{port} @var{version})}}
+where @var{version} can be either 4 or 5.
+@end defopt
+@defvar socks-password
+If this is @code{nil} then you will be asked for the password,
+otherwise it will be used as the password for authenticating you to
+the @sc{socks} server.
+@end defvar
+@defvar socks-username
+This is the username to use when authenticating yourself to the
+@sc{socks} server. By default this is your login name.
+@end defvar
+@defvar socks-timeout
+This controls how long, in seconds, to wait for responses from the
+@sc{socks} server; it is 5 by default.
+@end defvar
+@c fixme: these have been effectively commented-out in the code
+@c @defopt socks-server-aliases
+@c This a list of server aliases. It is a list of aliases of the form
+@c @var{(alias hostname port version)}.
+@c @end defopt
+@c @defopt socks-network-aliases
+@c This a list of network aliases. Each entry in the list takes the form
+@c @var{(alias (network))} where @var{alias} is a string that names the
+@c @var{network}. The networks can contain a pair (not a dotted pair) of
+@c @sc{ip} addresses which specify a range of @sc{ip} addresses, an @sc{ip}
+@c address and a netmask, a domain name or a unique hostname or @sc{ip}
+@c address.
+@c @end defopt
+@c @defopt socks-redirection-rules
+@c This a list of redirection rules. Each rule take the form
+@c @var{(Destination network Connection type)} where @var{Destination
+@c network} is a network alias from @code{socks-network-aliases} and
+@c @var{Connection type} can be @code{nil} in which case a direct
+@c connection is used, or it can be an alias from
+@c @code{socks-server-aliases} in which case that server is used as a
+@c proxy.
+@c @end defopt
+@defopt socks-nslookup-program
+@cindex @command{nslookup}
+This the @samp{nslookup} program. It is @code{"nslookup"} by default.
+@end defopt
+
+@menu
+* Suppressing network connections::
+@end menu
+@c * Broken hostname resolution::
+
+@node Suppressing network connections
+@subsection Suppressing Network Connections
+
+@cindex network connections, suppressing
+@cindex suppressing network connections
+@cindex bugs, HTML
+@cindex HTML `bugs'
+In some circumstances it is desirable to suppress making network
+connections. A typical case is when rendering HTML in a mail user
+agent, when external URLs should not be activated, particularly to
+avoid `bugs' which `call home' by fetch single-pixel images and the
+like. To arrange this, bind the following variable for the duration
+of such processing.
+
+@defvar url-gateway-unplugged
+If this variable is non-@code{nil} new network connections are never
+opened by the URL library.
+@end defvar
+
+@c @node Broken hostname resolution
+@c @subsection Broken Hostname Resolution
+
+@c @cindex hostname resolver
+@c @cindex resolver, hostname
+@c Some C libraries do not include the hostname resolver routines in
+@c their static libraries. If Emacs was linked statically, and was not
+@c linked with the resolver libraries, it will not be able to get to any
+@c machines off the local network. This is characterized by being able
+@c to reach someplace with a raw ip number, but not its hostname
+@c (@url{http://129.79.254.191/} works, but
+@c @url{http://www.cs.indiana.edu/} doesn't). This used to happen on
+@c SunOS4 and Ultrix, but is now probably now rare. If Emacs can't be
+@c rebuilt linked against the resolver library, it can use the external
+@c @command{nslookup} program instead.
+
+@c @defopt url-gateway-broken-resolution
+@c @cindex @code{nslookup} program
+@c @cindex program, @code{nslookup}
+@c If non-@code{nil}, this variable says to use the program specified by
+@c @code{url-gateway-nslookup-program} program to do hostname resolution.
+@c @end defopt
+
+@c @defopt url-gateway-nslookup-program
+@c The name of the program to do hostname lookup if Emacs can't do it
+@c directly. This program should expect a single argument on the command
+@c line---the hostname to resolve---and should produce output similar to
+@c the standard Unix @command{nslookup} program:
+@c @example
+@c Name: www.cs.indiana.edu
+@c Address: 129.79.254.191
+@c @end example
+@c @end defopt
+
+@node History
+@section History
+
+@findex url-do-setup
+The library can maintain a global history list tracking URLs accessed.
+URL completion can be done from it. The history mechanism is set up
+automatically via @code{url-do-setup} when it is configured to be on.
+Note that the size of the history list is currently not limited.
+
+@vindex url-history-hash-table
+The history `list' is actually a hash table,
+@code{url-history-hash-table}. It contains access times keyed by URL
+strings. The times are in the format returned by @code{current-time}.
+
+@defun url-history-update-url url time
+This function updates the history table with an entry for @var{url}
+accessed at the given @var{time}.
+@end defun
+
+@defopt url-history-track
+If non-@code{nil}, the library will keep track of all the URLs
+accessed. If it is @code{t}, the list is saved to disk at the end of
+each Emacs session. The default is @code{nil}.
+@end defopt
+
+@defopt url-history-file
+The file storing the history list between sessions. It defaults to
+@file{history} in @code{url-configuration-directory}.
+@end defopt
+
+@defopt url-history-save-interval
+@findex url-history-setup-save-timer
+The number of seconds between automatic saves of the history list.
+Default is one hour. Note that if you change this variable directly,
+rather than using Custom, after @code{url-do-setup} has been run, you
+need to run the function @code{url-history-setup-save-timer}.
+@end defopt
+
+@defun url-history-parse-history &optional fname
+Parses the history file @var{fname} (default @code{url-history-file})
+and sets up the history list.
+@end defun
+
+@defun url-history-save-history &optional fname
+Saves the current history to file @var{fname} (default
+@code{url-history-file}).
+@end defun
+
+@defun url-completion-function string predicate function
+You can use this function to do completion of URLs from the history.
+@end defun
+
+@node Customization
+@chapter Customization
+
+@section Environment Variables
+
+@cindex environment variables
+The following environment variables affect the library's operation at
+startup.
+
+@table @code
+@item TMPDIR
+@vindex TMPDIR
+@vindex url-temporary-directory
+If this is defined, @var{url-temporary-directory} is initialized from
+it.
+@end table
+
+@section General User Options
+
+The following user options, settable with Customize, affect the
+general operation of the package.
+
+@defopt url-debug
+@cindex debugging
+Specifies the types of debug messages the library which are logged to
+the @code{*URL-DEBUG*} buffer.
+@code{t} means log all messages.
+A number means log all messages and show them with @code{message}.
+If may also be a list of the types of messages to be logged.
+@end defopt
+@defopt url-personal-mail-address
+@end defopt
+@defopt url-privacy-level
+@end defopt
+@defopt url-uncompressor-alist
+@end defopt
+@defopt url-passwd-entry-func
+@end defopt
+@defopt url-standalone-mode
+@end defopt
+@defopt url-bad-port-list
+@end defopt
+@defopt url-max-password-attempts
+@end defopt
+@defopt url-temporary-directory
+@end defopt
+@defopt url-show-status
+@end defopt
+@defopt url-confirmation-func
+The function to use for asking yes or no functions. This is normally
+either @code{y-or-n-p} or @code{yes-or-no-p}, but could be another
+function taking a single argument (the prompt) and returning @code{t}
+only if an affirmative answer is given.
+@end defopt
+@defopt url-gateway-method
+@c fixme: describe gatewaying
+A symbol specifying the type of gateway support to use for connections
+from the local machine. The supported methods are:
+
+@table @code
+@item telnet
+Run telnet in a subprocess to connect;
+@item rlogin
+Rlogin to another machine to connect;
+@item socks
+Connect through a socks server;
+@item ssl
+Connect with SSL;
+@item native
+Connect directly.
+@end table
+@end defopt
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Function Index
+@unnumbered Command and Function Index
+@printindex fn
+
+@node Variable Index
+@unnumbered Variable Index
+@printindex vr
+
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
+
+@setchapternewpage odd
+@contents
+@bye
+
+@ignore
+ arch-tag: c96be356-7e2d-4196-bcda-b13246c5c3f0
+@end ignore
--- /dev/null
+\input texinfo
+
+@setfilename ../info/vip
+@settitle VIP
+
+@copying
+Copyright @copyright{} 1987, 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@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
+@page
+@vskip 0pt plus1filll
+@insertcopying
+@end titlepage
+
+@dircategory Emacs
+@direntry
+* VIP: (vip). An older VI-emulation for Emacs.
+@end direntry
+
+@finalout
+
+@ifnottex
+@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 ifnottex
+
+@menu
+* Survey:: A survey of VIP.
+* Vi Commands:: Details of Vi commands.
+* Ex Commands:: Details of Ex commands.
+* Customization:: How to customize VIP.
+* GNU Free Documentation License:: The license for this documentation.
+
+@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 @acronym{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{current}
+buffer, also called the @dfn{selected 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 information 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 @acronym{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 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 is 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
+
+@node GNU Free Documentation License,,, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+
+@unnumbered Key Index
+
+@printindex ky
+
+@unnumbered Concept Index
+@printindex cp
+
+@setchapternewpage odd
+@contents
+@bye
+
+@ignore
+ arch-tag: 7c5d17b9-1d21-4261-a88a-b9fdbbf1020b
+@end ignore
--- /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
+
+@copying
+Copyright @copyright{} 1995, 1996, 1997, 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* VIPER: (viper). The newest Emacs VI-emulation mode.
+ (also, A VI Plan for Emacs Rescue
+ or the VI PERil.)
+@end direntry
+
+@finalout
+
+@titlepage
+@title Viper Is a Package for Emacs Rebels
+@subtitle a Vi emulator for Emacs
+@subtitle April 2007, Viper Version 3.13.1
+
+@author Michael Kifer (Viper)
+@author Aamod Sane (VIP 4.4)
+@author Masahiko Sato (VIP 3.5)
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnottex
+@node Top, Overview,, (DIR)
+
+@unnumbered Viper
+
+We believe that one or more of the following statements are adequate
+descriptions of Viper:
+
+@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.
+About 15% of the code still comes from those older 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 is 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.stonybrook.edu} is the current address for Viper bug reports.
+Please use the Ex command @kbd{:submitReport} for this purpose.@refill
+
+@end ifnottex
+
+@menu
+* Overview:: Read for a smoother start
+* 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::
+* GNU Free Documentation License:: The license for this documentation.
+
+@end menu
+@iftex
+@unnumbered Introduction
+
+We believe that one or more of the following statements are adequate
+descriptions of Viper:
+
+@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. About 15% of the code
+still comes from those older 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 is 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.stonybrook.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.
+
+This manual is written with the assumption that you are an experienced Vi
+user who wants to switch to Emacs while retaining the ability to edit files
+Vi style. Incredible as it might seem, there are experienced Emacs users
+who use Viper as a backdoor into the superior (as every Vi user already knows)
+world of Vi! These users are well familiar with Emacs bindings and prefer them
+in some cases, especially in the Vi Insert state. John Hawkins
+<jshawkin@@eecs.umich.edu> has provided a set of customizations, which
+enables additional Emacs bindings under Viper. These customizations can be
+included in your @file{~/.viper} file and are found at the following URL:
+@file{http://traeki.freeshell.org/files/viper-sample}.
+
+@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 prompt 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.
+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.
+
+The latest versions of Emacs have an interactive customization facility,
+which allows you to (mostly) bypass the use of the @file{.emacs} and
+@file{.viper} files. You can reach this customization
+facility from within Viper's VI state by executing the Ex command
+@kbd{:customize}.
+
+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} file does not invoke Viper automatically,
+you can still load Viper and enter the 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 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) 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 prompt 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 key bindings 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 key bindings 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 unsupported. @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 the Insert state: typing @kbd{C-z} will let you execute a
+single Vi command while staying in Viper's Insert state.
+
+
+@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
+functions 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,
+which is rare these days).
+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{Regexps,,Syntax of 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 file names, Emacs uses a convention that
+is slightly different from other programs. It is designed to minimize the
+need for deleting file names that Emacs provides in its prompts. (This is
+usually convenient, but occasionally the prompt may suggest a wrong file
+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 in 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 file names
+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 file names that Emacs suggests in its
+prompts, if a suggested file 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. For example, use `:n3' to move to the third file in that list.
+
+@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, since
+@kbd{:ab} is considered obsolete, since Emacs has much
+more powerful facilities for defining 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 file names. Once you type a wildcard, the completer will
+no longer work for that file name. 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 ?g)
+@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 (or simply by typing @kbd{:customize}). 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 @code{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 C-g
+@kindex @kbd{C-c C-g}
+Hitting @kbd{C-c} followed by @kbd{C-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 recommended for experts only.
+@item
+@cindex .emacs
+Elisp code in your @file{.emacs} file before and after the @code{(require
+'viper)} line. This method is @emph{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 (i.e., prior to @code{(require 'viper)} command.@refill
+@item
+@cindex :customize
+By executing the @kbd{:customize} Ex command. This takes you to the Emacs
+customization widget, which lets you change the values of Viper
+customizable variables easily. This method is good for novice and
+experts alike. The customization code in the form of Lisp commands will be
+placed in @file{~/.emacs} or some other customization file depending on the
+version of Emacs that you use. Still, it is recommended to separate
+Viper-related customization produced by the Emacs customization widget
+and keep it in the @file{.viper} file.
+
+Some advanced customization cannot be accomplished this way, however, and
+has to be done in Emacs Lisp in the @file{.viper} file. For the common
+cases, examples are provided that you can use directly.
+@end itemize
+
+
+@menu
+* Rudimentary Changes:: Simple constant definitions.
+* Key Bindings:: 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,Key Bindings,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-translate-all-ESC-keysequences @code{t} on tty, @code{nil} on windowing display
+Normally, Viper lets Emacs translate only those ESC key sequences that are
+defined in the low-level key-translation-map or function-key-map, such as those
+emitted by the arrow and function keys. Other sequences, e.g., @kbd{\\e/}, are
+treated as @kbd{ESC} command followed by a @kbd{/}. This is good for people
+who type fast and tend to hit other characters right after they hit
+ESC. Other people like Emacs to translate @kbd{ESC} sequences all the time.
+The default is to translate all sequences only when using a dumb terminal.
+This permits you to use @kbd{ESC} as a meta key in insert mode. For instance,
+hitting @kbd{ESC x} fast would have the effect of typing @kbd{M-x}.
+If your dumb terminal is not so dumb and understands the meta key, then you
+probably will be better off setting this variable to @code{nil}. Try and see which
+way suits you best.
+@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 @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 @code{t}, cursor moves back 1 character when switching from insert state to vi
+state. If @code{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 viper-glob-function
+The value of this variable is the function symbol used to expand wildcard
+symbols. This is platform-dependent. The default tries to set this variable
+to work with most shells, MS Windows, OS/2, etc. However, if it
+doesn't work the way you expect, you should write your own.
+Use @code{viper-glob-unix-files} and @code{viper-glob-mswindows-files} in
+@file{viper-util.el} as examples.
+
+This feature is used to expand wildcards in the Ex command @kbd{:e}.
+Note that Viper doesn't support wildcards in the @kbd{:r} and @kbd{:w}
+commands, because file completion is a better mechanism.
+@findex @code{viper-glob-function}
+
+@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-emacs-state-cursor-color nil
+@vindex @code{viper-emacs-state-cursor-color}
+If set to a valid color, this will be the cursor color when Viper is in
+emacs 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-@code{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-@code{nil}.
+@item viper-use-replace-region-delimiters
+If non-@code{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-@code{nil} only on TTYs or monochrome displays.
+@item viper-allow-multiline-replace-regions t
+If non-@code{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 Key Bindings, Packages that Change Keymaps, Rudimentary Changes,Customization
+@section Key Bindings
+
+@cindex key bindings
+@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 the X Window System, 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 (a key that exists on some SUN workstations) 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-insert-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).
+
+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
+did not set @code{viper-always} to @code{nil}, 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,Key Bindings,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} (which is the default), 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 the 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 problem 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} 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 @file{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.
+
+It is recommended to harness even those minor modes that don't override
+Viper keys, but still have their own keymaps. A general way to
+make a minor mode, @code{my-mode},
+compatible with Viper is to have the file @file{my-mode.el} include the following code:
+
+@lisp
+(when (fboundp 'viper-harness-minor-mode)
+ (let ((lib (file-name-sans-extension
+ (file-name-nondirectory load-file-name))))
+ (viper-harness-minor-mode lib)))
+@end lisp
+
+@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}
+
+If you don't like this feature as a default, but would still like to have
+it in some major modes, you can do so by first unsetting it globally, as
+shown above, and then setting it in the desired major modes as follows:
+@example
+(viper-set-searchstyle-toggling-macros nil 'c-mode)
+(viper-set-searchstyle-toggling-macros nil 'lisp-mode)
+@end example
+
+@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{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-@code{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" "file4")
+;; End:
+@end lisp
+@noindent
+where @code{file1} to @code{file4} 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 4 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 @kbd{Meta-Shift-Mouse-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 (type @kbd{:customize}).
+
+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 taken 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} in Emacs and to
+@code{mouse-track-multi-click-time} milliseconds in XEmacs.
+@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 it requires typing
+too many keys (to a Vi user's taste, anyway).
+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 Vi-style keyboard macros through the usual Ex commands,
+@kbd{:map} and
+@kbd{:map!}. These 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{Keyboard 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{Key Bindings}, 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 @kbd{f 6}. When entering keys, Viper
+displays them as strings or vectors (e.g., @code{"abc"} or @code{[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 @samp{"},
+@samp{[}, or @samp{]} 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 @kbd{:e} and @kbd{:r <shell-cmd>}
+to mean current file. If you want a @samp{%} in your command, it must be
+escaped as @samp{\%}. Note that @kbd{:w} and the regular @kbd{:r <file>}
+command doesn't support the meta symbols @samp{%} and @samp{#}, because
+file history is a better mechanism.
+@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
+@acronym{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 with a sequence of 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 prompt 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 @code{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 (@pxref{Emacs Preliminaries}) back to where it was last
+set with the @kbd{m.} command. This is useful when you set the mark with
+@kbd{m.}, but then some other command (such as @kbd{L} or @kbd{G}) changes
+it in a way that you didn't like.
+@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,}
+@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.
+
+Viper does not parse search patterns and does not expand special symbols
+found there (e.g., @samp{~} is not expanded to the result of the previous
+substitution).
+
+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 :x,yp
+@itemx :g/Pat/p
+@itemx :v/Pat/p
+The above commands display certain buffer lines in a
+temporary buffer. The first form above displays the buffer lines between
+@kbd{x} and @kbd{y}. The second displays the lines of the buffer, which
+match a given pattern. The third form displays the lines that do @emph{not}
+match the given pattern.
+@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 C-c /
+Toggle case-sensitive search. With prefix argument, toggle vanilla/regular
+expression search.
+@item <count> /<string>
+To the <count>th occurrence of <string>.
+
+Viper does not parse search patterns and does not expand special symbols
+found there (e.g., @samp{~} is not expanded to the result of the previous
+substitution).
+
+@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.
+
+Note that many Ex commands, e.g., @kbd{:w}, accept command arguments. The
+effect is that the command would start acting on the current region. For
+instance, if the current region spans the lines 11 through 22, then if you
+type @kbd{1:w} you would see @samp{:11,22w} in the minibuffer.
+
+@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 [<file>]
+without the argument, prints file name and character/line information afout
+the currently visited file. With an argument, sets the currently visited
+filename to @file{file}.
+@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.
+The variable @var{viper-read-buffer-function} controls which function is
+actually used to read the buffer name. The default is @code{read-buffer},
+but better alternatives are also available in Emacs (e.g.,
+@code{iswitchb-read-buffer}).
+@vindex @var{viper-read-buffer-function}
+@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 key bindings
+@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)
+
+The symbol @samp{%} is used in Ex shell commands to mean current file. If
+you want a @samp{%} in your command, it must be escaped as @samp{\%}.
+@cindex @samp{%} (Ex address)
+However if @samp{%} is the first character, it stands as the address for
+the whole file.
+@cindex @samp{#} (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
+
+Symbols @samp{%} and @samp{#} are also used in the Ex commands @kbd{:e} and
+@kbd{:r <shell-cmd>}. The commands @kbd{:w} and the regular @kbd{:r
+<file>} command don't support these meta symbols, because file history is a
+better mechanism.
+
+@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).
+@item :make
+Run the make command in the current directory.
+@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}
+@findex @kbd{:make}
+
+@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 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. Scott Bronson and Samuel Padgett contributed patches that
+were incorporated in this code. Here is a hopefully complete list of
+contributors:
+
+@example
+aaronl@@vitelus.com (Aaron Lehmann),
+ahg@@panix.com (Al Gelders),
+amade@@diagram.fr (Paul-Bernard Amade),
+ascott@@fws214.intel.com (Andy Scott),
+bronson@@trestle.com (Scott Bronson),
+cook@@biostat.wisc.edu (Tom Cook),
+csdayton@@midway.uchicago.edu (Soren Dayton),
+dave@@hellgate.utah.edu,
+dm@@scs.cs.nyu.edu (David Mazieres),
+dominik@@strw.LeidenUniv.nl (Carsten Dominik),
+dwallach@@cs.princeton.edu (Dan Wallach),
+dwight@@toolucky.llnl.gov (Dwight Shih),
+dxc@@xprt.net (David X Callaway),
+edmonds@@edmonds.home.cs.ubc.ca (Brian Edmonds),
+gin@@mo.msk.ru (Golubev I.N.),
+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),
+irie@@t.email.ne.jp (Irie Tetsuya),
+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),
+lektu@@terra.es (Juanma Barranquero),
+lennart.borgman.073@@student.lu.se (Lennart Borgman),
+minakaji@@osaka.email.ne.jp (Mikio Nakajima),
+Mark.Bordas@@East.Sun.COM (Mark Bordas),
+meyering@@comco.com (Jim Meyering),
+martin@@xemacs.org (Martin Buchholz),
+mbutler@@redfernnetworks.com (Malcolm Butler),
+mveiga@@dit.upm.es (Marcelino Veiga Tuimil),
+paulk@@summit.esg.apertus.com (Paul Keusemann),
+pfister@@cs.stonybrook.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),
+spadgett1@@nc.rr.com (Samuel Padgett),
+stephen@@farrell.org (Stephen Farrell),
+storm@@cua.dk (Kim F. Storm),
+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 GNU Free Documentation License,,, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@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
+
+@setchapternewpage odd
+@contents
+@bye
+
+@ignore
+ arch-tag: f53e866a-15cf-4b1e-aead-77da9da1e864
+@end ignore
--- /dev/null
+\input texinfo.tex
+
+@c %**start of header
+@setfilename ../info/widget
+@settitle The Emacs Widget Library
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex ky cp
+@afourpaper
+@c %**end of header
+
+@copying
+Copyright @copyright{} 2000, 2001, 2002, 2003, 2004, 2005,
+2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
+``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Widget: (widget). The "widget" package used by the Emacs Customization
+ facility.
+@end direntry
+
+@node Top, Introduction, (dir), (dir)
+@comment node-name, next, previous, up
+@top The Emacs Widget Library
+
+@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::
+* GNU Free Documentation License::
+* Index::
+@end menu
+
+@node Introduction, User Interface, Top, Top
+@comment node-name, next, previous, up
+@section Introduction
+
+Most graphical user interface toolkits 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
+incredibly 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.
+
+@cindex basic widgets
+@cindex widgets, basic types
+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
+A 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 @acronym{HTML} form support in the @file{w3} browser.
+
+@cindex widget library, why use it
+The advantages for a programmer of using the @code{widget} package to
+implement forms are:
+
+@enumerate
+@item
+More complex fields than just editable text are supported.
+@item
+You can give the users immediate feedback if they enter invalid data in a
+text field, and sometimes prevent entering invalid data.
+@item
+You can have fixed sized fields, thus allowing multiple fields to be
+lined up in columns.
+@item
+It is simple to query or set the value of a field.
+@item
+Editing happens in the 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 be
+extended to use the GUI features. This means that your code using the
+widget library will also use the new graphic features automatically.
+@end enumerate
+
+In order to minimize the code that is loaded by users who do not
+create any widgets, the code has been split in two files:
+
+@cindex widget library, files
+@table @file
+@item widget.el
+This will declare the user variables, define the function
+@code{define-widget}, 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 consists of read only text for documentation and some fields,
+where each field contains two parts, a tag and a value. The tags are
+used to identify the fields, so the documentation can refer to the
+@samp{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 this 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 things 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.
+
+Editable text fields are created by the @code{editable-field} widget.
+
+@strong{Warning:} In an @code{editable-field} widget, the editable
+field must not be adjacent to another widget---that won't work.
+You must put some text in between. Either make this text part of
+the @code{editable-field} widget itself, or insert it with
+@code{widget-insert}.
+
+The @code{:format} keyword is useful for generating the necessary
+text; for instance, if you give it a value of @code{"Name: %v "},
+the @samp{Name: } part will provide the necessary separating text
+before the field and the trailing space will provide the
+separating text after the field. If you don't include the
+@code{:size} keyword, the field will extend to the end of the
+line, and the terminating newline will provide separation after.
+
+@strong{Warning:} In an @code{editable-field} widget, the @samp{%v} escape
+must be preceded by some other text in the @code{:format} string
+(if specified).
+
+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
+
+@cindex widget buttons
+@cindex button widgets
+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
+
+@kindex Mouse-2 @r{(on button widgets})
+@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
+@cindex option field tag
+@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 an editable list.
+The list is created by the @code{editable-list} widget.
+@cindex embedded buttons
+@item Embedded Buttons
+The @samp{@b{_other work_}} is an example of an embedded
+button. Embedded buttons are not associated with any 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 them with the
+@code{checkbox} widget.
+@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]}} and @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 will be
+displayed as GUI buttons when possible.
+@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 highlighting a button when the mouse pointer moves across
+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 @kbd{M-@key{TAB}}
+@itemx @kbd{S-@key{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
+
+@cindex widgets, programming example
+@cindex example of using widgets
+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))
+ (remove-overlays)
+ (widget-insert "Here is some documentation.\n\n")
+ (widget-create 'editable-field
+ :size 13
+ :format "Name: %v " ; Text after the field!
+ "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-create 'editable-field
+ :format "Address: %v"
+ "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
+Set up 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.
+
+@findex widget-button-press
+@findex widget-button-click
+@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. @key{RET} and @kbd{Mouse-2}
+are bound to @code{widget-button-press} and
+@code{widget-button-click}.@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
+
+This is the general syntax of a type specification:
+
+@example
+@var{name} ::= (@var{name} [@var{keyword} @var{argument}]... @var{args})
+ | @var{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.
+
+@cindex keyword arguments
+The following keyword arguments apply to all widgets:
+
+@table @code
+@vindex value@r{ keyword}
+@item :value
+The initial value for widgets of this type.
+
+@vindex format@r{ keyword}
+@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 replaced with the buffer representation of the widget's
+value. What this is depends on the widget type.
+
+@strong{Warning:} In an @code{editable-field} widget, the @samp{%v} escape
+must be preceded by some other text in the format string (if specified).
+
+@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
+
+@vindex button-face@r{ keyword}
+@item :button-face
+Face used to highlight text inside %[ %] in the format.
+
+@vindex button-prefix@r{ keyword}
+@vindex button-suffix@r{ keyword}
+@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
+
+@vindex doc@r{ keyword}
+@item :doc
+The string inserted by the @samp{%d} escape in the format
+string.
+
+@vindex tag@r{ keyword}
+@item :tag
+The string inserted by the @samp{%t} escape in the format
+string.
+
+@vindex tag-glyph@r{ keyword}
+@item :tag-glyph
+Name of image to use instead of the string specified by @code{:tag} on
+Emacsen that supports it.
+
+@vindex help-echo@r{ keyword}
+@item :help-echo
+Specifies how to display a message whenever you move to the widget with
+either @code{widget-forward} or @code{widget-backward} or move the mouse
+over it (using the standard @code{help-echo} mechanism). The argument
+is either a string to display, a function of one argument, the widget,
+which should return a string to display, or a form that evaluates to
+such a string.
+
+@vindex follow-link@r{ keyword}
+@item :follow-link
+Specifies how to interpret a @key{mouse-1} click on the widget.
+@xref{Links and Mouse-1,,, elisp, the Emacs Lisp Reference Manual}.
+
+@vindex indent@r{ keyword}
+@item :indent
+An integer indicating the absolute number of spaces to indent children
+of this widget.
+
+@vindex offset@r{ keyword}
+@item :offset
+An integer indicating how many extra spaces to add to the widget's
+grandchildren compared to this widget.
+
+@vindex extra-offset@r{ keyword}
+@item :extra-offset
+An integer indicating how many extra spaces to add to the widget's
+children compared to this widget.
+
+@vindex notify@r{ keyword}
+@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.
+
+@vindex menu-tag@r{ keyword}
+@item :menu-tag
+Tag used in the menu when the widget is used as an option in a
+@code{menu-choice} widget.
+
+@vindex menu-tag-get@r{ keyword}
+@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.
+
+@vindex match@r{ keyword}
+@item :match
+Should be a function called with two arguments, the widget and a value,
+and returning non-@code{nil} if the widget can represent the specified value.
+
+@vindex validate@r{ keyword}
+@item :validate
+A function which takes a widget as an argument, and returns @code{nil}
+if the widget's current value is valid for the widget. Otherwise it
+should return the widget containing the invalid data, and set that
+widget's @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
+
+@vindex tab-order@r{ keyword}
+@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
+
+@vindex parent@r{ keyword}
+@item :parent
+The parent of a nested widget (e.g.@: a @code{menu-choice} item or an
+element of a @code{editable-list} widget).
+
+@vindex sibling-args@r{ keyword}
+@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 @file{.xpm} (if supported) or @file{.xbm} extension.
+@end deffn
+
+@deffn{User Option} widget-glyph-enable
+If non-@code{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
+@findex link@r{ widget}
+
+Syntax:
+
+@example
+@var{type} ::= (link [@var{keyword} @var{argument}]... [ @var{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
+@findex url-link@r{ widget}
+
+Syntax:
+
+@example
+@var{type} ::= (url-link [@var{keyword} @var{argument}]... @var{url})
+@end example
+
+@findex browse-url-browser-function@r{, and @code{url-link} widget}
+When this link is invoked, the @acronym{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
+@findex info-link@r{ widget}
+
+Syntax:
+
+@example
+@var{type} ::= (info-link [@var{keyword} @var{argument}]... @var{address})
+@end example
+
+When this link is invoked, the built-in Info reader 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
+@findex push-button@r{ widget}
+
+Syntax:
+
+@example
+@var{type} ::= (push-button [@var{keyword} @var{argument}]... [ @var{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
+@findex editable-field@r{ widget}
+
+Syntax:
+
+@example
+@var{type} ::= (editable-field [@var{keyword} @var{argument}]... [ @var{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
+field. This widget will match all string values.
+
+The following extra properties are recognized:
+
+@table @code
+@vindex size@r{ keyword}
+@item :size
+The width of the editable field.@*
+By default the field will reach to the end of the line.
+
+@vindex value-face@r{ keyword}
+@item :value-face
+Face used for highlighting the editable field. Default is
+@code{widget-field-face}, see @ref{User Interface}.
+
+@vindex secret@r{ keyword}
+@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, this is @code{nil}, and the value is not secret.
+
+@vindex valid-regexp@r{ keyword}
+@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.
+
+@vindex keymap@r{ keyword}
+@vindex widget-field-keymap
+@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 buffer's major mode suppresses some of
+them. Pressing @key{RET} 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
+@findex text@r{ widget}
+
+@vindex widget-text-keymap
+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 @key{RET} key.
+
+@node menu-choice, radio-button-choice, text, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{menu-choice} Widget
+@findex menu-choice@r{ widget}
+
+Syntax:
+
+@example
+@var{type} ::= (menu-choice [@var{keyword} @var{argument}]... @var{type} ... )
+@end example
+
+The @var{type} argument represents each possible choice. The widget's
+value will be that of the chosen @var{type} argument. This widget will
+match any value matching at least one of the specified @var{type}
+arguments.
+
+@table @code
+@vindex void@r{ keyword}
+@item :void
+Widget type used as a fallback when the value does not match any of the
+specified @var{type} arguments.
+
+@vindex case-fold@r{ keyword}
+@item :case-fold
+Set this to @code{nil} if you don't want to ignore case when prompting for a
+choice through the minibuffer.
+
+@vindex children@r{ keyword}
+@item :children
+A list whose @sc{car} is the widget representing the currently chosen
+type in the buffer.
+
+@vindex choice@r{ keyword}
+@item :choice
+The current chosen type.
+
+@vindex args@r{ keyword}
+@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
+@findex radio-button-choice@r{ widget}
+
+Syntax:
+
+@example
+@var{type} ::= (radio-button-choice [@var{keyword} @var{argument}]... @var{type} ... )
+@end example
+
+The component types specify the choices, with one radio button for
+each. The widget's value will be that of the chosen @var{type}
+argument. This widget matches any value that matches at least one of
+the specified @var{type} arguments.
+
+The following extra properties are recognized.
+
+@table @code
+@vindex entry-format@r{ keyword}
+@item :entry-format
+This string will be inserted for each entry in the list.
+The following @samp{%} escapes are available:
+@table @samp
+@item %v
+Replace with the buffer representation of the @var{type} widget.
+@item %b
+Replace with the radio button.
+@item %%
+Insert a literal @samp{%}.
+@end table
+
+@vindex button-args@r{ keyword}
+@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.
+
+@vindex buttons@r{ keyword}
+@item :buttons
+The widgets representing the radio buttons.
+
+@vindex children@r{ keyword}
+@item :children
+The widgets representing each type.
+
+@vindex choice@r{ keyword}
+@item :choice
+The current chosen type
+
+@vindex args@r{ keyword}
+@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
+@findex item@r{ widget}
+
+Syntax:
+
+@example
+@var{item} ::= (item [@var{keyword} @var{argument}]... @var{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
+@findex choice-item@r{ widget}
+
+Syntax:
+
+@example
+@var{item} ::= (choice-item [@var{keyword} @var{argument}]... @var{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
+@findex toggle@r{ widget}
+
+Syntax:
+
+@example
+@var{type} ::= (toggle [@var{keyword} @var{argument}]...)
+@end example
+
+The widget has two possible states, @samp{on} and @samp{off}, which
+correspond to a @code{t} or @code{nil} value, respectively.
+
+The following extra properties are recognized:
+
+@table @code
+@item :on
+A string representing the @samp{on} state. By default the string
+@samp{on}.
+@item :off
+A string representing the @samp{off} state. By default the string
+@samp{off}.
+@vindex on-glyph@r{ keyword}
+@item :on-glyph
+Name of a glyph to be used instead of the @samp{:on} text string, on
+emacsen that supports this.
+@vindex off-glyph@r{ keyword}
+@item :off-glyph
+Name of a glyph to be used instead of the @samp{:off} text string, on
+emacsen that supports this.
+@end table
+
+@node checkbox, checklist, toggle, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{checkbox} Widget
+@findex checkbox@r{ widget}
+
+This widget has two possible states, @samp{selected} and
+@samp{unselected}, which corresponds to a @code{t} or @code{nil} value.
+
+Syntax:
+
+@example
+@var{type} ::= (checkbox [@var{keyword} @var{argument}]...)
+@end example
+
+@node checklist, editable-list, checkbox, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{checklist} Widget
+@findex checklist@r{ widget}
+
+Syntax:
+
+@example
+@var{type} ::= (checklist [@var{keyword} @var{argument}]... @var{type} ... )
+@end example
+
+The @var{type} arguments represent each checklist item. The widget's
+value will be a list containing the values of all checked @var{type}
+arguments. The checklist widget will match a list whose elements all
+match at least one of the specified @var{type} arguments.
+
+The following extra properties are recognized:
+
+@table @code
+@vindex entry-format@r{ keyword}
+@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
+
+@vindex greedy@r{ keyword}
+@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-@code{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.
+
+@vindex button-args@r{ keyword}
+@item :button-args
+A list of keywords to pass to the checkboxes. Useful for setting
+e.g.@: the @samp{:help-echo} for each checkbox.
+
+@vindex buttons@r{ keyword}
+@item :buttons
+The widgets representing the checkboxes.
+
+@vindex children@r{ keyword}
+@item :children
+The widgets representing each type.
+
+@vindex args@r{ keyword}
+@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
+@findex editable-list@r{ widget}
+
+Syntax:
+
+@example
+@var{type} ::= (editable-list [@var{keyword} @var{argument}]... @var{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
+@vindex entry-format@r{ keyword}
+@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
+
+@vindex insert-button-args@r{ keyword}
+@item :insert-button-args
+A list of keyword arguments to pass to the insert buttons.
+
+@vindex delete-button-args@r{ keyword}
+@item :delete-button-args
+A list of keyword arguments to pass to the delete buttons.
+
+@vindex append-button-args@r{ keyword}
+@item :append-button-args
+A list of keyword arguments to pass to the trailing insert button.
+
+@vindex buttons@r{ keyword}
+@item :buttons
+The widgets representing the insert and delete buttons.
+
+@vindex children@r{ keyword}
+@item :children
+The widgets representing the elements of the list.
+
+@vindex args@r{ keyword}
+@item :args
+List whose @sc{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
+@findex group@r{ widget}
+
+This widget simply group other widgets together.
+
+Syntax:
+
+@example
+@var{type} ::= (group [@var{keyword} @var{argument}]... @var{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
+@cindex sexp types
+
+A number of widgets for editing @dfn{s-expressions} (Lisp types), sexp
+for short, are also available. These basically fall in several
+categories described in this section.
+
+@menu
+* constants::
+* generic::
+* atoms::
+* composite::
+@end menu
+
+@node constants, generic, Sexp Types, Sexp Types
+@comment node-name, next, previous, up
+@subsection The Constant Widgets
+@cindex constant widgets
+
+The @code{const} widget can contain any Lisp expression, but the user is
+prohibited from editing it, which is mainly useful as a component of one
+of the composite widgets.
+
+The syntax for the @code{const} widget is:
+
+@example
+@var{type} ::= (const [@var{keyword} @var{argument}]... [ @var{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
+@cindex 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
+@var{type} ::= (sexp [@var{keyword} @var{argument}]... [ @var{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. @xref{editable-field}.
+@end deffn
+
+@node atoms, composite, generic, Sexp Types
+@comment node-name, next, previous, up
+@subsection Atomic Sexp Widgets
+@cindex atomic sexp widget
+
+The atoms are s-expressions that do not consist of other s-expressions.
+For example, a string, a file name, or a symbol are atoms, 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
+@var{type} ::= (@var{construct} [@var{keyword} @var{argument}]... [ @var{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.
+That is, 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. @xref{editable-field}.
+
+@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.
+
+Keywords:
+@table @code
+@vindex must-match@r{ keyword}
+@item :must-match
+If this is set to non-@code{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 @code{nil} meaning false, or non-@code{nil} meaning true.
+@end deffn
+
+
+@node composite, , atoms, Sexp Types
+@comment node-name, next, previous, up
+@subsection Composite Sexp Widgets
+@cindex composite sexp widgets
+
+The syntax for the composite widget construct is:
+
+@example
+@var{type} ::= (@var{construct} [@var{keyword} @var{argument}]... @var{component}...)
+@end example
+
+@noindent
+where each @var{component} must be a widget type. Each component widget
+will be displayed in the buffer, and will be editable by the user.
+
+@deffn Widget cons
+The value of a @code{cons} widget must be a cons-cell whose @sc{car}
+and @sc{cdr} have two specified types. It uses this syntax:
+
+@example
+@var{type} ::= (cons [@var{keyword} @var{argument}]... @var{car-type} @var{cdr-type})
+@end example
+@end deffn
+
+@deffn Widget choice
+The value matched by a @code{choice} widget must have one of a fixed
+set of types. The widget's syntax is as follows:
+
+@example
+@var{type} ::= (choice [@var{keyword} @var{argument}]... @var{type} ... )
+@end example
+
+The value of a @code{choice} widget can be anything that matches any of the
+@var{types}.
+@end deffn
+
+@deffn Widget list
+The value of a @code{list} widget must be a list whose element types
+match the specified component types:
+
+@example
+@var{type} ::= (list [@var{keyword} @var{argument}]... @var{component-type}...)
+@end example
+
+Thus, @code{(list string number)} matches lists of two elements,
+the first being a string and the second being a number.
+@end deffn
+
+@deffn Widget vector
+The @code{vector} widget is like the @code{list} widget but matches
+vectors instead of lists. Thus, @code{(vector string number)} matches
+vectors of two elements, the first being a string and the second being
+a number.
+@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} widget together with the @code{:inline}
+keyword. 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 elements should
+either be the symbol @code{t} or two strings (file names), 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
+@code{(file t)} or @code{(file @var{string} @var{string})}.
+
+This concept of @code{:inline} may be hard to understand. It was
+certainly hard to implement, so instead of confusing you more by
+trying to explain it here, I'll just suggest you meditate over it for
+a while.
+
+@deffn Widget set
+Specifies a type whose values are the lists whose elements all belong
+to a given set. The order of elements of the list is not significant.
+Here's the syntax:
+
+@example
+@var{type} ::= (set [@var{keyword} @var{argument}]... @var{permitted-element} ... )
+@end example
+
+Use @code{const} to specify each permitted element, like this:
+@code{(set (const a) (const b))}.
+@end deffn
+
+@deffn Widget repeat
+Specifies a list of any number of elements that fit a certain type.
+
+@example
+@var{type} ::= (repeat [@var{keyword} @var{argument}]... @var{type})
+@end example
+@end deffn
+
+@node Widget Properties, Defining New Widgets, Sexp Types, Top
+@comment node-name, next, previous, up
+@section Properties
+@cindex properties of widgets
+@cindex widget 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-@code{nil} if @var{widget} has a value (even @code{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
+
+@cindex active widget
+@cindex inactive widget
+@cindex activate a widget
+@cindex deactivate a widget
+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 it, 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 it 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 the @code{:inactive} keyword. If this is non-@code{nil}, the widget itself
+has been deactivated. This is different from using the @code{:active}
+keyword, in that the latter tells 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{:deactivate} keywords instead.
+
+
+@node Defining New Widgets, Widget Browser, Widget Properties, Top
+@comment node-name, next, previous, up
+@section Defining New Widgets
+@cindex new widgets
+@cindex 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 new default values for the keyword
+arguments.
+
+@defun define-widget 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{define-widget} just stores the definition of the widget type
+in the @code{widget-type} property of @var{name}, which is what
+@code{widget-create} uses.
+
+If you only 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
+@vindex convert-widget@r{ keyword}
+@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 widget's 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
+
+@vindex copy@r{ keyword}
+@item :copy
+Function to deep copy a widget type. It takes a shallow copy of the
+widget type as an argument (made by @code{copy-sequence}), and returns a
+deep copy. The purpose of this is to avoid having different instances
+of combined widgets share nested attributes.
+
+The following predefined functions can be used here:
+
+@defun widget-types-copy widget
+Copy @code{:args} as widget types in @var{widget}.
+@end defun
+
+@vindex value-to-internal@r{ keyword}
+@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}.
+
+@vindex value-to-external@r{ keyword}
+@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
+external 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}.
+
+@vindex create@r{ keyword}
+@item :create
+Function to create a widget from scratch. The function takes one
+argument, a widget type, and creates a widget of that type, inserts it
+in the buffer, and returns a widget object.
+
+@vindex delete@r{ keyword}
+@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.
+
+The default value is:
+
+@defun widget-default-delete widget
+Remove @var{widget} from the buffer.
+Delete all @code{:children} and @code{:buttons} in @var{widget}.
+@end defun
+
+In most cases you should not change this value, but instead use
+@code{:value-delete} to make any additional cleanup.
+
+@vindex value-create@r{ keyword}
+@item :value-create
+Function to expand the @samp{%v} escape in the format string. It will
+be called with the widget as its argument and should insert a
+representation of the widget's value in the buffer.
+
+Nested widgets should be listed in @code{:children} or @code{:buttons}
+to make sure they are automatically deleted.
+
+@vindex value-delete@r{ keyword}
+@item :value-delete
+Should remove the representation of the widget's 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 these are not listed in @code{:children} or @code{:buttons}.
+
+@vindex value-get@r{ keyword}
+@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
+
+@vindex format-handler@r{ keyword}
+@item :format-handler
+Function to handle unknown @samp{%} escapes in the format string. It
+will be called with the widget and the character that follows the
+@samp{%} as arguments. You can set this to allow your widget to handle
+non-standard escapes.
+
+@findex widget-default-format-handler
+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.
+
+@vindex action@r{ keyword}
+@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
+
+@vindex prompt-value@r{ keyword}
+@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-@code{nil}, in which case there is 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
+@cindex 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 @samp{:parent}, which avoids printing cyclic structures.
+
+@deffn Command widget-browse @var{widget}
+Create a widget browser for @var{widget}.
+When called interactively, prompt for @var{widget}.
+@end deffn
+
+@deffn Command widget-browse-other-window @var{widget}
+Create a widget browser for @var{widget} and show it in another window.
+When called interactively, prompt for @var{widget}.
+@end deffn
+
+@deffn Command widget-browse-at @var{pos}
+Create a widget browser for the widget at @var{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
+@cindex widget minor mode
+
+There is a minor mode for manipulating widgets in major modes that
+don'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.
+@cindex utility functions for widgets
+
+@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-@code{nil}.@refill
+@end defun
+
+@defun widget-get-sibling widget
+Get the item which @var{widget} is assumed to toggle.
+This is only meaningful for radio buttons or checkboxes in a list.
+@end defun
+
+@node Widget Wishlist, GNU Free Documentation License, Utilities, Top
+@comment node-name, next, previous, up
+@section Wishlist
+@cindex todo
+
+@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, asks
+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
+Add a @code{mailto} widget.
+@end itemize
+
+@node GNU Free Documentation License, Index, Widget Wishlist, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index, , GNU Free Documentation License, Top
+@comment node-name, next, previous, up
+@unnumbered Index
+
+This is an alphabetical listing of all concepts, functions, commands,
+variables, and widgets described in this manual.
+@printindex cp
+
+@setchapternewpage odd
+@contents
+@bye
+
+@ignore
+ arch-tag: 2b427731-4c61-4e72-85de-5ccec9c623f0
+@end ignore
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename ../info/woman
+@settitle WoMan: Browse Unix Manual Pages ``W.O. (without) Man''
+@c Manual last updated:
+@set UPDATED Time-stamp: <2006-03-25 14:59:03 karl>
+@c Software version:
+@set VERSION 0.54 (beta)
+@afourpaper
+@c With different size paper the printed page breaks will need attention!
+@c Look for @page and @need commands.
+@setchapternewpage off
+@paragraphindent 0
+@c %**end of header
+
+@copying
+This file documents WoMan: A program to browse Unix manual pages `W.O.
+(without) man'.
+
+Copyright @copyright{} 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* WoMan: (woman). Browse UN*X Manual Pages "W.O. (without) Man".
+@end direntry
+
+@finalout
+
+@titlepage
+@title WoMan
+@subtitle Browse Unix Manual Pages ``W.O. (without) Man''
+@subtitle Software Version @value{VERSION}
+@author Francis J. Wright
+@sp 2
+@author School of Mathematical Sciences
+@author Queen Mary and Westfield College
+@author (University of London)
+@author Mile End Road, London E1 4NS, UK
+@author @email{F.J.Wright@@qmul.ac.uk}
+@author @uref{http://centaur.maths.qmw.ac.uk/}
+@c He no longer maintains this manual.
+@sp 2
+@author Manual Last Updated @value{UPDATED}
+
+@comment The following two commands start the copyright page.
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@c ===================================================================
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@comment node-name, next, previous, up
+@top WoMan: Browse Unix Manual Pages ``W.O. (without) Man''
+
+@display
+Software Version @value{VERSION}
+Manual Last Updated @value{UPDATED}
+
+@email{F.J.Wright@@qmw.ac.uk, Francis J. Wright}
+@uref{http://centaur.maths.qmw.ac.uk/, School of Mathematical Sciences}
+Queen Mary and Westfield College (University of London)
+Mile End Road, London E1 4NS, UK
+@end display
+@end ifnottex
+
+@menu
+* Introduction:: Introduction
+* Background:: Background
+* Finding:: Finding and Formatting Man Pages
+* Browsing:: Browsing Man Pages
+* Customization:: Customization
+* Log:: The *WoMan-Log* Buffer
+* Technical:: Technical Details
+* Bugs:: Reporting Bugs
+* Acknowledgements:: Acknowledgements
+* GNU Free Documentation License:: The license for this documentation.
+* Command Index:: Command Index
+* Variable Index:: Variable Index
+* Keystroke Index:: Keystroke Index
+* Concept Index:: Concept Index
+@end menu
+
+@c ===================================================================
+
+@node Introduction, Background, Top, Top
+@comment node-name, next, previous, up
+@chapter Introduction
+@cindex introduction
+
+This version of WoMan should run with GNU Emacs 20.3 or later on any
+platform. It has not been tested, and may not run, with any other
+version of Emacs. It was developed primarily on various versions of
+Microsoft Windows, but has also been tested on MS-DOS, and various
+versions of UNIX and GNU/Linux.
+
+WoMan is distributed with GNU Emacs. In addition, the current source
+code and documentation files are available from
+@uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/, the WoMan web
+server}.
+
+WoMan implements a subset of the formatting performed by the Emacs
+@code{man} (or @code{manual-entry}) command to format a Unix-style
+@dfn{manual page} (usually abbreviated to @dfn{man page}) for display,
+but without calling any external programs. It is intended to emulate
+the whole of the @code{roff -man} macro package, plus those @code{roff}
+requests (@pxref{Background, , Background}) that are most commonly used
+in man pages. However, the emulation is modified to include the
+reformatting done by the Emacs @code{man} command. No hyphenation is
+performed.
+
+@table @b
+@item Advantages
+Much more direct, does not require any external programs. Supports
+completion on man page names.
+@item Disadvantages
+Not a complete emulation. Currently no support for @code{eqn} or
+@code{tbl}. Slightly slower for large man pages (but usually faster for
+small- and medium-size pages).
+@end table
+
+This browser works quite well on simple well-written man files. It
+works less well on idiosyncratic files that ``break the rules'' or use
+the more obscure @code{roff} requests directly. Current test results
+are available in the file
+@uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/files/woman.status,
+@file{woman.status}}.
+
+WoMan supports the use of compressed man files via
+@code{auto-compression-mode} by turning it on if necessary. But you may
+need to adjust the user option @code{woman-file-compression-regexp}.
+@xref{Interface Options, , Interface Options}.
+
+Brief help on the WoMan interactive commands and user options, all of
+which begin with the prefix @code{woman-} (or occasionally
+@code{WoMan-}), is available most easily by loading WoMan and then
+either running the command @code{woman-mini-help} or selecting the WoMan
+menu option @samp{Mini Help}.
+
+WoMan is (of course) still under development! Please
+@email{F.J.Wright@@qmw.ac.uk, let me know} what doesn't work---I am
+adding and improving functionality as testing shows that it is
+necessary. Guidance on reporting bugs is given below. @xref{Bugs, ,
+Reporting Bugs}.
+
+@c ===================================================================
+
+@node Background, Finding, Introduction, Top
+@comment node-name, next, previous, up
+@chapter Background
+@cindex background
+
+WoMan is a browser for traditional Unix-style manual page documentation.
+Each such document is conventionally referred to as a @dfn{manual page},
+or @dfn{man page} for short, even though some are very much longer than
+one page. A man page is a document written using the Unix ``man''
+macros, which are themselves written in the nroff/troff text processing
+markup language. @code{nroff} and @code{troff} are text processors
+originally written for the UNIX operating system by Joseph F. Ossanna at
+Bell Laboratories, Murray Hill, New Jersey, USA@. They are closely
+related, and except in the few cases where the distinction between them
+is important I will refer to them both ambiguously as @code{roff}.
+
+@code{roff} markup consists of @dfn{requests} and @dfn{escape
+sequences}. A request occupies a complete line and begins with either a
+period or a single forward quote. An escape sequences is embedded
+within the input text and begins (by default) with a backslash. The
+original man macro package defines 20 new @code{roff} requests
+implemented as macros, which were considered to be sufficient for
+writing man pages. But whilst in principle man pages use only the man
+macros, in practice a significant number use many other @code{roff}
+requests.
+
+The distinction between @code{troff} and @code{nroff} is that
+@code{troff} was designed to drive a phototypesetter whereas
+@code{nroff} was designed to produce essentially @acronym{ASCII} output for a
+character-based device similar to a teletypewriter (usually abbreviated
+to ``teletype'' or ``tty''). Hence, @code{troff} supports much finer
+control over output positioning than does @code{nroff} and can be seen
+as a forerunner of @TeX{}. Traditionally, man pages are either
+formatted by @code{troff} for typesetting or by @code{nroff} for
+printing on a character printer or displaying on a screen. Of course,
+over the last 25 years or so, the distinction between typeset output on
+paper and characters on a screen has become blurred by the fact that
+most screens now support bit-mapped displays, so that any information
+that can be printed can also be rendered on screen, the only difference
+being the resolution.
+
+Nevertheless, Unix-style manual page documentation is still normally
+browsed on screen by running a program called @code{man}. This program
+looks in a predefined set of directories for the man page matching a
+specified topic, then either formats the source file by running
+@code{nroff} or recovers a pre-formatted file, and displays it via a
+pager such as @code{more}. @code{nroff} normally formats for a printer,
+so it paginates the output, numbers the pages, etc., most of which is
+irrelevant when the document is browsed as a continuous scrollable
+document on screen. The only concession to on-screen browsing normally
+implemented by the @code{man} program is to squeeze consecutive blank
+lines into a single blank line.
+
+For some time, Emacs has offered an improved interface for browsing man
+pages in the form of the Emacs @code{man} (or @code{manual-entry})
+command, see @ref{Documentation, man, Documentation Commands, emacs, GNU
+Emacs Manual}.
+This command runs @code{man} as described above, perhaps in
+the background, and then post-processes the output to remove much of the
+@code{nroff} pagination such as page headers and footers, and places the
+result into an Emacs buffer. It puts this buffer into a special major
+mode, which is tailored for man page browsing, and provides a number of
+useful navigation commands, support for following references, etc. It
+provides some support for special display faces (fonts), but no special
+menu or mouse support. The Emacs man package appears to have been
+developed over about 10 years, from the late 1980s to the late 1990s.
+
+There is considerable inefficiency in having @code{nroff} paginate a
+document and then removing most of the pagination!
+
+WoMan is an Emacs Lisp library that provides an emulation of the
+functionality of the Emacs @code{man} command, the main difference being
+that WoMan does not use any external programs. The only situation in
+which WoMan might use an external program is when the source file is
+compressed, when WoMan will use the standard Emacs automatic
+decompression facility, which does call an external program.
+
+I began developing WoMan in the Spring of 1997 and the first version was
+released in May 1997. The original motivation for WoMan was the fact
+that many GNU and Unix programs are ported to other platforms and come
+with Unix-style manual page documentation. This may be difficult to
+read because ports of the Unix-style @code{man} program can be a little
+awkward to set up. I decided that it should not be too hard to emulate
+the 20 @code{man} macros directly, without treating them as macros and
+largely ignoring the underlying @code{roff} requests, given the text
+processing capabilities of Emacs. This proved to be essentially true,
+and it did not take a great deal of work to be able to format simple man
+pages acceptably.
+
+One problem arose with the significant number of man pages that use
+@code{roff} requests in addition to the @code{man} macros, and since
+releasing the first version of WoMan I have been continually extending
+it to support more @code{roff} requests. WoMan can now format a
+significant proportion of the man pages that I have tested, either well
+or at least readably. However, I have added capabilities partly by
+making additional passes through the document, a design that is
+fundamentally flawed. This can only be solved by a major re-design of
+WoMan to handle the major formatting within a single recursive pass,
+rather than the present multiple passes without any significant
+recursion. There are some @code{roff} requests that cannot be handled
+satisfactorily within the present design. Some of these are currently
+handled by kludges that ``usually more or less work.''
+
+The principle advantage of WoMan is that it does not require @code{man},
+and indeed the name WoMan is a contraction of ``without man.'' But it
+has other advantages. It does not paginate the document, so it does not
+need to un-paginate it again, thereby saving time. It could take full
+advantage of the display capabilities available to it, and I hope to
+develop WoMan to take advantage of developments in Emacs itself. At
+present, WoMan uses several display faces to support bold and italic
+text, to indicate other fonts, etc. The default faces are also
+colored, but the choice of faces is customizable. WoMan provides menu
+support for navigation and mouse support for following references, in
+addition to the navigation facilities provided by @code{man} mode.
+WoMan has (this) texinfo documentation!
+
+WoMan @emph{does not} replace @code{man}, although it does use a number
+of the facilities implemented in the Emacs @code{man} library. WoMan
+and man can happily co-exist, which is very useful for comparison and
+debugging purposes.
+
+@code{nroff} simulates non-@acronym{ASCII} characters by using one or more
+@acronym{ASCII} characters. WoMan should be able to do much better than
+this. I have recently begun to add support for WoMan to use more of the
+characters in its default font and to use a symbol font, and it is an
+aspect that I intend to develop further in the near future. It should
+be possible to move WoMan from an emulation of @code{nroff} to an
+emulation of @code{troff} as GNU Emacs moves to providing bit-mapped
+display facilities.
+
+@node Finding, Browsing, Background, Top
+@comment node-name, next, previous, up
+@chapter Finding and Formatting Man Pages
+@cindex using, finding man pages
+@cindex using, formatting man pages
+@cindex finding man pages
+@cindex formatting man pages
+@cindex man pages, finding
+@cindex man pages, formatting
+
+WoMan provides three user interfaces for finding and formatting man pages:
+
+@itemize @bullet
+@item
+a topic interface similar to that provided by the standard Emacs
+@code{man} command;
+
+@item
+a family of filename interfaces analogous to the standard Emacs
+@code{view-file} command;
+
+@item
+an automatic interface that detects the file type from its contents.
+(This is currently neither well tested, well supported nor recommended!)
+@end itemize
+
+The topic and filename interfaces support completion in the usual way.
+
+The topic interface is generally the most convenient for regular use,
+although it may require some special setup, especially if your machine
+does not already have a conventional @code{man} installation (which
+WoMan tries to detect).
+
+The simplest filename interface command @code{woman-find-file} can
+always be used with no setup at all (provided WoMan is installed and
+loaded or set up to autoload).
+
+The automatic interface always requires special setup.
+
+
+@heading Case-Dependence of Filenames
+
+@cindex case-sensitivity
+@vindex w32-downcase-file-names
+By default, WoMan ignores case in file pathnames only when it seems
+appropriate. Microsoft Windows users who want complete case
+independence should set the special NTEmacs variable
+@code{w32-downcase-file-names} to @code{t} and use all lower case when
+setting WoMan file paths.
+
+
+@menu
+* Topic:: Topic Interface
+* Filename:: Filename Interface
+* Automatic:: Automatic Interface
+@end menu
+
+@node Topic, Filename, Finding, Finding
+@comment node-name, next, previous, up
+@section Topic Interface
+@cindex topic interface
+
+The topic interface is accessed principally via the command
+@code{woman}. The same command can be accessed via the menu item
+@samp{Help->Manuals->Read Man Page (WoMan)...} once WoMan has been
+loaded. The command reads a manual topic in the minibuffer, which can
+be the @dfn{basename} of a man file anywhere in the man file
+structure. The ``basename'' in this context means the filename
+without any directory component and without any extension or suffix
+components that relate to the file type. So, for example, if there is
+a compressed source file in Chapter 5 of the UNIX Programmer's Manual
+with the full pathname @file{/usr/local/man/man5/man.conf.5.gz} then
+the topic is @code{man.conf}. Provided WoMan is configured correctly,
+this topic will appear among the completions offered by @code{woman}.
+If more than one file has the same topic name then WoMan will prompt
+for which file to format. Completion of topics is case insensitive.
+
+Clearly, @code{woman} has to know where to look for man files and there
+are two customizable user options that store this information:
+@code{woman-manpath} and @code{woman-path}. @xref{Interface Options, ,
+Interface Options}. If @code{woman-manpath} is not set explicitly then
+WoMan tries to pick up the information that would be used by the
+@code{man} command, as follows. If the environment variable
+@code{MANPATH} is set, which seems to be the standard mechanism under
+UNIX, then WoMan parses that. Otherwise, if WoMan can find a
+configuration file named (by default) @file{man.conf} (or something very
+similar), which seems to be the standard mechanism under GNU/Linux, then
+it parses that. To be precise, ``something very similar'' means
+starting with @samp{man} and ending with @samp{.conf} and possibly more
+lowercase letters, e.g.@: @file{manual.configuration}.
+The search path and/or precise full path name for this file are set by
+the value of the customizable user option @code{woman-man.conf-path}.
+If all else fails, WoMan uses a plausible default man search path.
+
+If the above default configuration does not work correctly for any
+reason then simply customize the value of @code{woman-manpath}. To
+access man files that are not in a conventional man file hierarchy,
+customize the value of @code{woman-path} to include the directories
+containing the files. In this way, @code{woman} can access manual files
+@emph{anywhere} in the entire file system.
+
+There are two differences between @code{woman-manpath} and
+@code{woman-path}. Firstly, the elements of @code{woman-manpath} must
+be directories that contain @emph{directories of} man files, whereas the
+elements of @code{woman-path} must be directories that contain man files
+@emph{directly}. Secondly, the last directory component of each element
+of @code{woman-path} is treated as a regular (Emacs) match expression
+rather than a fixed name, which allows collections of related
+directories to be specified succinctly. Also, elements of
+@code{woman-manpath} can be conses, indicating a mapping from
+@samp{PATH} environment variable components to man directory
+hierarchies.
+
+For topic completion to work, WoMan must build a list of all the manual
+files that it can access, which can be very slow, especially if a
+network is involved. For this reason, it caches various amounts of
+information, after which retrieving it from the cache is very fast. If
+the cache ever gets out of synchronism with reality, running the
+@code{woman} command with a prefix argument (e.g.@: @kbd{C-u M-x woman})
+will force it to rebuild its cache. This is necessary only if the names
+or locations of any man files change; it is not necessary if only their
+contents change. It would always be necessary if such a change occurred
+whilst Emacs were running and after WoMan has been loaded. It may be
+necessary if such a change occurs between Emacs sessions and persistent
+caching is used, although WoMan can detect some changes that invalidate
+its cache and rebuild it automatically.
+
+Customize the variable @code{woman-cache-filename} to save the cache
+between Emacs sessions. This is recommended only if the @code{woman}
+command is too slow the first time it is run in an Emacs session, while
+it builds its cache in main memory, which @emph{may} be @emph{very}
+slow. @xref{Cache, , The WoMan Topic Cache}, for further details.
+
+
+@menu
+* Cache:: The WoMan Topic Cache
+* Word at point:: Using the ``Word at Point'' as a Topic Suggestion
+@end menu
+
+@node Cache, Word at point, Topic, Topic
+@comment node-name, next, previous, up
+@subsection The WoMan Topic Cache
+@cindex topic cache
+@cindex cache, topic
+
+The amount of information that WoMan caches (in main memory and,
+optionally, saved to disc) is controlled by the user option
+@code{woman-cache-level}. There is a trade-off between the speed with
+which WoMan can find a file and the size of the cache, and the default
+setting gives a reasonable compromise.
+
+The @code{woman} command always performs a certain amount of caching in
+main memory, but it can also write its cache to the filestore as a
+persistent cache under control of the user option
+@code{woman-cache-filename}. If persistent caching is turned on then
+WoMan re-loads its internal cache from the cache file almost
+instantaneously, so that there is never any perceptible start-up delay
+@emph{except} when WoMan rebuilds its cache. Persistent caching is
+currently turned off by default. This is because users with persistent
+caching turned on may overlook the need to force WoMan to rebuild its
+cache the first time they run it after they have installed new man
+files; with persistent caching turned off, WoMan automatically rebuilds
+its cache every time it is run in a new Emacs session.
+
+A prefix argument always causes the @code{woman} command (only) to
+rebuild its topic cache, and to re-save it to
+@code{woman-cache-filename} if this variable has a non-@code{nil} value. This
+is necessary if the @emph{names} of any of the directories or files in
+the paths specified by @code{woman-manpath} or @code{woman-path} change.
+If WoMan user options that affect the cache are changed then WoMan will
+automatically update its cache file on disc (if one is in use) the next
+time it is run in a new Emacs session.
+
+
+@node Word at point, , Cache, Topic
+@comment node-name, next, previous, up
+@subsection Using the ``Word at Point'' as a Topic Suggestion
+@cindex word at point
+@cindex point, word at
+
+By default, the @code{woman} command uses the word nearest to point in
+the current buffer as a suggestion for the topic to look up, if it
+exists as a valid topic. The topic can be confirmed or edited in the
+minibuffer.
+
+You can also bind the variable @code{woman-use-topic-at-point} locally
+to a non-@code{nil} value (using @code{let}), in which case
+@code{woman} will can use the suggested topic without confirmation if
+possible. This may be useful to provide special private key bindings,
+e.g.@: this key binding for @kbd{C-c w} runs WoMan on the topic at
+point without seeking confirmation:
+
+@lisp
+(global-set-key "\C-cw"
+ (lambda ()
+ (interactive)
+ (let ((woman-use-topic-at-point t))
+ (woman))))
+@end lisp
+
+
+@node Filename, Automatic, Topic, Finding
+@comment node-name, next, previous, up
+@section Filename Interface
+@cindex filename interface
+
+The commands in this family are completely independent of the topic
+interface, caching mechanism, etc.
+
+@findex woman-find-file
+The filename interface is accessed principally via the extended command
+@code{woman-find-file}, which is available without any configuration at
+all (provided WoMan is installed and loaded or set up to autoload).
+This command can be used to browse any accessible man file, regardless
+of its filename or location. If the file is compressed then automatic
+file decompression must already be turned on (e.g.@: see the
+@samp{Help->Options} submenu)---it is turned on automatically only by
+the @code{woman} topic interface.
+
+@findex woman-dired-find-file
+Once WoMan is loaded (or if specially set up), various additional
+commands in this family are available. In a dired buffer, the command
+@code{woman-dired-find-file} allows the file on the same line as point
+to be formatted and browsed by WoMan. It is bound to the key @kbd{W} in
+the dired mode map and added to the dired major mode menu. It may also
+be bound to @kbd{w}, unless this key is bound by another library, which
+it is by @code{dired-x}, for example. Because it is quite likely that
+other libraries will extend the capabilities of such a commonly used
+mode as dired, the precise key bindings added by WoMan to the dired mode
+map are controlled by the user option @code{woman-dired-keys}.
+
+@findex woman-tar-extract-file
+When a tar (Tape ARchive) file is visited in Emacs, it is opened in tar
+mode, which parses the tar file and shows a dired-like view of its
+contents. The WoMan command @code{woman-tar-extract-file} allows the
+file on the same line as point to be formatted and browsed by WoMan. It
+is bound to the key @kbd{w} in the tar mode map and added to the tar
+major mode menu.
+
+The command @code{woman-reformat-last-file}, which is bound to the key
+@kbd{R} in WoMan mode and available on the major mode menu, reformats
+the last file formatted by WoMan. This may occasionally be useful if
+formatting parameters, such as the fill column, are changed, or perhaps
+if the buffer is somehow corrupted.
+
+@findex woman-decode-buffer
+The command @code{woman-decode-buffer} can be used to decode and browse
+the current buffer if it is visiting a man file, although it is
+primarily used internally by WoMan.
+
+
+@node Automatic, , Filename, Finding
+@comment node-name, next, previous, up
+@section Automatic Interface
+@cindex automatic interface
+
+Emacs provides an interface to detect automatically the format of a file
+and decode it when it is visited. It is used primarily by the
+facilities for editing rich (i.e.@: formatted) text, as a way to store
+formatting information transparently as @acronym{ASCII} markup. WoMan can in
+principle use this interface, but it must be configured explicitly.
+
+This use of WoMan does not seem to be particularly advantageous, so it
+is not really supported. It originated during early experiments on how
+best to implement WoMan, before I implemented the current topic
+interface, and I subsequently stopped using it. I might revive it as a
+mechanism for storing pre-formatted WoMan files, somewhat analogous to
+the standard Unix @code{catman} facility. In the meantime, it exists
+for anyone who wants to experiment with it. Once it is set up it is
+simply a question of visiting the file and there is no WoMan-specific
+user interface!
+
+To use it, put something like this in your @file{.emacs} file. [The
+call to @code{set-visited-file-name} is to avoid font-locking triggered
+by automatic major mode selection.]
+
+@lisp
+(autoload 'woman-decode-region "woman")
+
+(add-to-list 'format-alist
+ '(man "Unix man-page source format" "\\.\\(TH\\|ig\\) "
+ woman-decode-region nil nil
+ (lambda (arg)
+ set-visited-file-name
+ (file-name-sans-extension buffer-file-name))))
+@end lisp
+
+@c ===================================================================
+
+@node Browsing, Customization, Finding, Top
+@comment node-name, next, previous, up
+@chapter Browsing Man Pages
+@cindex using, browsing man pages
+@cindex browsing man pages
+@cindex man pages, browsing
+
+Once a man page has been found and formatted, WoMan provides a browsing
+interface that is essentially the same as that provided by the standard
+Emacs @code{man} command (and much of the code is inherited from the
+@code{man} library, which WoMan currently requires). Many WoMan
+facilities can be accessed from the WoMan major mode menu as well as via
+key bindings, etc.
+
+WoMan does not produce any page breaks or page numbers, and in fact does
+not paginate the man page at all, since this is not appropriate for
+continuous online browsing. It produces a document header line that is
+constructed from the standard man page header and footer. Apart from
+that, the appearance of the formatted man page should be almost
+identical to what would be produced by @code{man}, with consecutive
+blank lines squeezed to a single blank line.
+
+@menu
+* Fonts:: Fonts and Faces
+* Navigation:: Navigation
+* References:: Following References
+* Changing:: Changing the Current Man Page
+* Convenience:: Convenience Key Bindings
+* Imenu:: Imenu Support; Contents Menu
+@end menu
+
+@node Fonts, Navigation, Browsing, Browsing
+@comment node-name, next, previous, up
+@section Fonts and Faces
+@cindex fonts
+@cindex faces
+
+Fonts used by @code{roff} are handled by WoMan as faces, the details of
+which are customizable. @xref{Faces, , Faces}. WoMan supports both the
+italic and bold fonts normally used in man pages, together with a single
+face to represent all unknown fonts (which are occasionally used in
+``non-standard'' man pages, usually to represent a ``typewriter'' font)
+and a face to indicate additional symbols introduced by WoMan. This
+currently means the characters ^ and _ used to indicate super- and
+sub-scripts, which are not displayed well by WoMan.
+
+
+@node Navigation, References, Fonts, Browsing
+@comment node-name, next, previous, up
+@section Navigation
+@cindex navigation
+
+Man (and hence WoMan) mode can be thought of as a superset of view mode.
+The buffer cannot be edited, so keys that would normally self-insert are
+used for navigation. The WoMan key bindings are a minor modification of
+the @code{man} key bindings.
+
+@table @kbd
+@item @key{SPC}
+@kindex SPC
+@findex scroll-up
+Scroll the man page up the window (@code{scroll-up}).
+
+@item @key{DEL}
+@kindex DEL
+@findex scroll-down
+Scroll the man page down the window (@code{scroll-down}).
+
+@item n
+@kindex n
+@findex Man-next-section
+Move point to the Nth next section---default 1 (@code{Man-next-section}).
+
+@item p
+@kindex p
+@findex Man-previous-section
+Move point to Nth previous section---default 1
+(@code{Man-previous-section}).
+
+@item g
+@kindex g
+@findex Man-goto-section
+Move point to the specified section (@code{Man-goto-section}).
+
+@item s
+@kindex s
+@findex Man-goto-see-also-section
+Move point to the ``SEE ALSO'' section
+(@code{Man-goto-see-also-section}). Actually the section moved to is
+described by @code{Man-see-also-regexp}.
+@end table
+
+
+@node References, Changing, Navigation, Browsing
+@comment node-name, next, previous, up
+@section Following References
+@cindex following references
+@cindex references
+
+Man pages usually contain a ``SEE ALSO'' section containing references
+to other man pages. If these man pages are installed then WoMan can
+easily be directed to follow the reference, i.e.@: to find and format the
+man page. When the mouse is passed over a correctly formatted reference
+it is highlighted, in which case clicking the middle button
+@kbd{Mouse-2} will cause WoMan to follow the reference. Alternatively,
+when point is over such a reference the key @key{RET} will follow the
+reference.
+
+Any word in the buffer can be used as a reference by clicking
+@kbd{Mouse-2} over it provided the Meta key is also used (although in
+general such a ``reference'' will not lead to a man page).
+Alternatively, the key @kbd{r} allows completion to be used to select a
+reference to follow, based on the word at point as default.
+
+@table @kbd
+@item @kbd{Mouse-2}
+@kindex Mouse-2
+@findex woman-mouse-2
+Run WoMan with word under mouse as topic (@code{woman-mouse-2}). The
+word must be mouse-highlighted unless @code{woman-mouse-2} is used with
+the Meta key.
+
+@item @key{RET}
+@kindex RET
+@findex man-follow
+Get the man page for the topic under (or nearest to) point
+(@code{man-follow}).
+
+@item r
+@kindex r
+@findex Man-follow-manual-reference
+Get one of the man pages referred to in the ``SEE ALSO'' section
+(@code{Man-follow-manual-reference}). Specify which reference to use;
+default is based on word at point.
+@end table
+
+
+@node Changing, Convenience, References, Browsing
+@comment node-name, next, previous, up
+@section Changing the Current Man Page
+@cindex changing current man page
+@cindex current man page, changing
+
+The man page currently being browsed by WoMan can be changed in several
+ways. The command @code{woman} can be invoked to format another man
+page, or the current WoMan buffer can be buried or killed. WoMan
+maintains a ring of formatted man pages, and it is possible to move
+forwards and backwards in this ring by moving to the next or previous
+man page. It is sometimes useful to reformat the current page, for
+example after the right margin (the wrap column) or some other
+formatting parameter has been changed.
+
+Buffers formatted by Man and WoMan are completely unrelated, even though
+some of the commands to manipulate them are superficially the same (and
+share code).
+
+@table @kbd
+@item m
+@kindex m
+@findex man
+Run the command @code{man} to get a Un*x manual page and put it in a
+buffer. This command is the top-level command in the man package. It
+runs a Un*x command to retrieve and clean a man page in the background
+and places the results in a Man mode (man page browsing) buffer. If a
+man buffer already exists for this man page, it will display
+immediately. This works exactly the same if WoMan is loaded, except
+that the formatting time is displayed in the mini-buffer.
+
+@item w
+@kindex w
+@findex woman
+Run the command @code{woman} exactly as if the extended command or menu
+item had been used.
+
+@item q
+@kindex q
+@findex Man-quit
+Bury the buffer containing the current man page (@code{Man-quit}),
+i.e.@: move it to the bottom of the buffer stack.
+
+@item k
+@kindex k
+@findex Man-kill
+Kill the buffer containing the current man page (@code{Man-kill}),
+i.e.@: delete it completely so that it can be retrieved only by formatting
+the page again.
+
+@item M-p
+@kindex M-p
+@findex WoMan-previous-manpage
+Find the previous WoMan buffer (@code{WoMan-previous-manpage}).
+
+@item M-n
+@kindex M-n
+@findex WoMan-next-manpage
+Find the next WoMan buffer (@code{WoMan-next-manpage}).
+
+@item R
+@kindex R
+@findex woman-reformat-last-file
+Call WoMan to reformat the last man page formatted by WoMan
+(@code{woman-reformat-last-file}), e.g.@: after changing the fill column.
+@end table
+
+
+@node Convenience, Imenu, Changing, Browsing
+@comment node-name, next, previous, up
+@section Convenience Key Bindings
+@cindex convenience key bindings
+@cindex key bindings, convenience
+
+@table @kbd
+@item -
+@kindex -
+@findex negative-argument
+Begin a negative numeric argument for the next command
+(@code{negative-argument}).
+
+@item 0 .. 9
+@kindex 0 .. 9
+@findex digit-argument
+Part of the numeric argument for the next command
+(@code{digit-argument}).
+
+@item <
+@kindex <
+@itemx .
+@kindex .
+@findex beginning-of-buffer
+Move point to the beginning of the buffer; leave mark at previous
+position (@code{beginning-of-buffer}).
+
+@item >
+@kindex >
+@findex end-of-buffer
+Move point to the end of the buffer; leave mark at previous position
+(@code{end-of-buffer}).
+
+@item ?
+@kindex ?
+@findex describe-mode
+Display documentation of current major mode and minor modes
+(@code{describe-mode}). The major mode description comes first,
+followed by the minor modes, each on a separate page.
+@end table
+
+
+@node Imenu, , Convenience, Browsing
+@comment node-name, next, previous, up
+@section Imenu Support; Contents Menu
+@cindex imenu support
+@cindex contents menu
+
+The WoMan menu provides an option to make a contents menu for the
+current man page (using @code{imenu}). Alternatively, if you customize
+the option @code{woman-imenu} to @code{t} then WoMan will do it
+automatically for every man page. The menu title is set by the option
+@code{woman-imenu-title}, which is ``CONTENTS'' by default. The menu
+shows manual sections and subsections by default, but you can change
+this by customizing @code{woman-imenu-generic-expression}.
+
+WoMan is configured not to replace spaces in an imenu
+@code{*Completion*} buffer. For further documentation on the use of
+imenu, such as menu sorting, see the source file @file{imenu.el}, which
+is distributed with GNU Emacs.
+
+@c ===================================================================
+
+@node Customization, Log, Browsing, Top
+@comment node-name, next, previous, up
+@chapter Customization
+@cindex customization
+
+All WoMan user options are customizable, and it is recommended to
+change them only via the standard Emacs customization facilities.
+WoMan defines a top-level customization group called @code{WoMan}
+under the parent group @code{Help}. It can be accessed either via the
+standard Emacs facilities, e.g.@: via the @samp{Help->Customize}
+submenu, or via the WoMan major mode menu.
+
+The top-level WoMan group contains only a few general options and three
+subgroups. The hooks are provided only for special purposes that, for
+example, require code to be executed, and should be changed only via
+@code{Customization} or the function @code{add-hook}. Most
+customization should be possible via existing user options.
+
+@vtable @code
+@item woman-show-log
+A boolean value that defaults to @code{nil}. If non-@code{nil} then show the
+@code{*WoMan-Log*} buffer if appropriate, i.e.@: if any warning messages
+are written to it. @xref{Log, , The *WoMan-Log* Buffer}.
+
+@item woman-pre-format-hook
+A hook run immediately before formatting a buffer. It might, for
+example, be used for face customization. @xref{Faces, , Faces},
+however.
+
+@item woman-post-format-hook
+A hook run immediately after formatting a buffer. It might, for
+example, be used for installing a dynamic menu using @code{imenu}.
+(However. in this case it is better to use the built-in WoMan
+@code{imenu} support. @xref{Imenu, , Imenu Support; Contents Menu}.)
+@end vtable
+
+@heading Customization Subgroups
+
+@table @code
+@item WoMan Interface
+These options control the process of locating the appropriate file to
+browse, and the appearance of the browsing interface.
+
+@item WoMan Formatting
+These options control the layout that WoMan uses to format the man page.
+
+@item WoMan Faces
+These options control the display faces that WoMan uses to format the
+man page.
+@end table
+
+@menu
+* Interface Options::
+* Formatting Options::
+* Faces::
+* Special symbols::
+@end menu
+
+@node Interface Options, Formatting Options, Customization, Customization
+@comment node-name, next, previous, up
+@section Interface Options
+@cindex interface options
+
+These options control the process of locating the appropriate file to
+browse, and the appearance of the browsing interface.
+
+@vtable @code
+@item woman-man.conf-path
+A list of strings representing directories to search and/or files to try
+for a man configuration file. The default is
+
+@lisp
+("/etc" "/usr/local/lib")
+@end lisp
+
+@noindent
+[for GNU/Linux and Cygwin respectively.] A trailing separator (@file{/}
+for UNIX etc.) on directories is optional and the filename matched if a
+directory is specified is the first to match the regexp
+@code{man.*\.conf}. If the environment variable @code{MANPATH} is not
+set but a configuration file is found then it is parsed instead (or as
+well) to provide a default value for @code{woman-manpath}.
+
+@item woman-manpath
+A list of strings representing @emph{directory trees} to search for Unix
+manual files. Each element should be the name of a directory that
+contains subdirectories of the form @file{man?}, or more precisely
+subdirectories selected by the value of @code{woman-manpath-man-regexp}.
+Non-directory and unreadable files are ignored. This can also contain
+conses, with the car indicating a @code{PATH} variable component mapped
+to the directory tree given in the cdr.
+
+@cindex @code{MANPATH}, environment variable
+If not set then the environment variable @code{MANPATH} is used. If no
+such environment variable is found, the default list is determined by
+consulting the man configuration file if found. By default this is
+expected to be either @file{/etc/man.config} or
+@file{/usr/local/lib/man.conf}, which is controlled by the user option
+@code{woman-man.conf-path}. An empty substring of @code{MANPATH}
+denotes the default list. Otherwise, the default value of this variable
+is
+
+@lisp
+("/usr/man" "/usr/local/man")
+@end lisp
+
+Any environment variables (names of which must have the Unix-style form
+@code{$NAME}, e.g.@: @code{$HOME}, @code{$EMACSDATA}, @code{$EMACS_DIR},
+regardless of platform) are evaluated first but each element must
+evaluate to a @emph{single} directory name. Trailing @file{/}s are
+ignored. (Specific directories in @code{woman-path} are also searched.)
+
+On Microsoft platforms I recommend including drive letters explicitly,
+e.g.
+
+@lisp
+("C:/Cygwin/usr/man" "C:/usr/man" "C:/usr/local/man")
+@end lisp
+
+@cindex directory separator character
+@cindex @code{MANPATH}, directory separator
+The @code{MANPATH} environment variable may be set using DOS
+semi-colon-separated or Unix-style colon-separated syntax (but not
+mixed).
+
+@item woman-manpath-man-regexp
+A regular expression to match man directories @emph{under} the
+@code{woman-manpath} directories. These normally have names of the form
+@file{man?}. Its default value is @code{"[Mm][Aa][Nn]"}, which is
+case-insensitive mainly for the benefit of Microsoft platforms. Its
+purpose is to avoid directories such as @file{cat?}, @file{.},
+@file{..}, etc.
+
+@item woman-path
+A list of strings representing @emph{specific directories} to search for
+Unix manual files. For example
+
+@lisp
+("/emacs/etc")
+@end lisp
+
+These directories are searched in addition to the directory trees
+specified in @code{woman-manpath}. Each element should be a directory
+string or @code{nil}, which represents the current directory when the
+path is expanded and cached. However, the last component (only) of each
+directory string is treated as a regexp (Emacs, not shell) and the
+string is expanded into a list of matching directories. Non-directory
+and unreadable files are ignored. The default value on MS-DOS is
+
+@lisp
+("$DJDIR/info" "$DJDIR/man/cat[1-9onlp]")
+@end lisp
+
+@noindent
+and on other platforms is @code{nil}.
+
+Any environment variables (names of which must have the Unix-style form
+@code{$NAME}, e.g.@: @code{$HOME}, @code{$EMACSDATA}, @code{$EMACS_DIR},
+regardless of platform) are evaluated first but each element must
+evaluate to a @emph{single} directory name (regexp, see above). For
+example
+
+@lisp
+("$EMACSDATA")
+@end lisp
+
+@noindent
+or equivalently
+
+@lisp
+("$EMACS_DIR/etc")
+@end lisp
+
+@noindent
+Trailing @file{/}s are discarded. (The directory trees in
+@code{woman-manpath} are also searched.) On Microsoft platforms I
+recommend including drive letters explicitly.
+
+@item woman-cache-level
+A positive integer representing the level of topic caching:
+
+@enumerate
+@item
+cache only the topic and directory lists (uses minimal memory, but not
+recommended);
+@item
+cache also the directories for each topic (faster, without using much
+more memory);
+@item
+cache also the actual filenames for each topic (fastest, but uses twice
+as much memory).
+@end enumerate
+
+The default value is currently 2, a good general compromise. If the
+@code{woman} command is slow to find files then try 3, which may be
+particularly beneficial with large remote-mounted man directories. Run
+the @code{woman} command with a prefix argument or delete the cache file
+@code{woman-cache-filename} for a change to take effect. (Values < 1
+behave like 1; values > 3 behave like 3.)
+
+@item woman-cache-filename
+Either a string representing the full pathname of the WoMan directory
+and topic cache file, or @code{nil}. It is used to save and restore the
+cache between Emacs sessions. This is especially useful with
+remote-mounted man page files! The default value of @code{nil}
+suppresses this action. The ``standard'' non-@code{nil} filename is
+@file{~/.wmncach.el}. Remember that a prefix argument forces the
+@code{woman} command to update and re-write the cache.
+
+@item woman-dired-keys
+A list of @code{dired} mode keys to be defined to run WoMan on the
+current file, e.g.@: @code{("w" "W")} or any non-@code{nil} atom to
+automatically define @kbd{w} and @kbd{W} if they are unbound, or
+@code{nil} to do nothing. Default is @code{t}.
+
+@item woman-imenu-generic-expression
+Imenu support for Sections and Subsections: an alist with elements of
+the form @code{(MENU-TITLE REGEXP INDEX)}---see the documentation for
+@code{imenu-generic-expression}. Default value is
+
+@lisp
+((nil "\n\\([A-Z].*\\)" 1) ; SECTION, but not TITLE
+ ("*Subsections*" "^ \\([A-Z].*\\)" 1))
+@end lisp
+
+@item woman-imenu
+A boolean value that defaults to @code{nil}. If non-@code{nil} then WoMan adds
+a Contents menu to the menubar by calling @code{imenu-add-to-menubar}.
+
+@item woman-imenu-title
+A string representing the title to use if WoMan adds a Contents menu to
+the menubar. Default is @code{"CONTENTS"}.
+
+@item woman-use-topic-at-point
+A boolean value that defaults to @code{nil}. If non-@code{nil} then
+the @code{woman} command uses the word at point as the topic,
+@emph{without interactive confirmation}, if it exists as a topic.
+
+@item woman-use-topic-at-point-default
+A boolean value representing the default value for
+@code{woman-use-topic-at-point}. The default value is @code{nil}.
+[The variable @code{woman-use-topic-at-point} may be @code{let}-bound
+when @code{woman} is loaded, in which case its global value does not
+get defined. The function @code{woman-file-name} sets it to this
+value if it is unbound.]
+
+@item woman-uncompressed-file-regexp
+A regular match expression used to select man source files (ignoring any
+compression extension). The default value is
+@code{"\\.\\([0-9lmnt]\\w*\\)"} [which means a filename extension is
+required].
+
+@emph{Do not change this unless you are sure you know what you are doing!}
+
+The SysV standard man pages use two character suffixes, and this is
+becoming more common in the GNU world. For example, the man pages in
+the @code{ncurses} package include @file{toe.1m}, @file{form.3x}, etc.
+
+@strong{Please note:} an optional compression regexp will be appended,
+so this regexp @emph{must not} end with any kind of string terminator
+such as @code{$} or @code{\\'}.
+
+@item woman-file-compression-regexp
+A regular match expression used to match compressed man file extensions
+for which decompressors are available and handled by auto-compression
+mode. It should begin with @code{\\.} and end with @code{\\'} and
+@emph{must not} be optional. The default value is
+@code{"\\.\\(g?z\\|bz2\\)\\'"}, which matches the @code{gzip} and
+@code{bzip2} compression extensions.
+
+@emph{Do not change this unless you are sure you know what you are doing!}
+
+[It should be compatible with the @code{car} of
+@code{jka-compr-file-name-handler-entry}, but that is unduly
+complicated, includes an inappropriate extension (@file{.tgz}) and is
+not loaded by default!]
+
+@item woman-use-own-frame
+If non-@code{nil} then use a dedicated frame for displaying WoMan windows.
+This is useful only when WoMan is run under a window system such as X or
+Microsoft Windows that supports real multiple frames, in which case the
+default value is non-@code{nil}.
+@end vtable
+
+
+@node Formatting Options, Faces, Interface Options, Customization
+@comment node-name, next, previous, up
+@section Formatting Options
+@cindex formatting options
+
+These options control the layout that WoMan uses to format the man page.
+
+@vtable @code
+@item woman-fill-column
+An integer specifying the right margin for formatted text. Default is
+65.
+
+@item woman-fill-frame
+A boolean value. If non-@code{nil} then most of the frame width is used,
+overriding the value of @code{woman-fill-column}. Default is @code{nil}.
+
+@item woman-default-indent
+An integer specifying the default prevailing indent for the @code{-man}
+macros. Default is 5. Set this variable to 7 to emulate GNU/Linux man
+formatting.
+
+@item woman-bold-headings
+A boolean value. If non-@code{nil} then embolden section and subsection
+headings. Default is @code{t}. [Heading emboldening is @emph{not} standard
+@code{man} behavior.]
+
+@item woman-ignore
+A boolean value. If non-@code{nil} then unrecognised requests etc. are
+ignored. Default is @code{t}. This gives the standard @code{roff} behavior.
+If @code{nil} then they are left in the buffer, which may aid debugging.
+
+@item woman-preserve-ascii
+A boolean value. If non-@code{nil} then preserve @acronym{ASCII} characters in the
+WoMan buffer. Otherwise, non-@acronym{ASCII} characters (that display as
+@acronym{ASCII}) may remain, which is irrelevant unless the buffer is to be
+saved to a file. Default is @code{nil}.
+
+@item woman-emulation
+WoMan emulation, currently either @code{nroff} or @code{troff}. Default
+is @code{nroff}. @code{troff} emulation is experimental and largely
+untested.
+@end vtable
+
+
+@node Faces, Special symbols, Formatting Options, Customization
+@comment node-name, next, previous, up
+@section Faces
+@cindex faces
+
+These options control the display faces that WoMan uses to format the
+man page.
+
+@vtable @code
+@item woman-fontify
+A boolean value. If non-@code{nil} then WoMan assumes that face support is
+available. It defaults to a non-@code{nil} value if the display supports
+either colors or different fonts.
+
+@item woman-italic-face
+Face for italic font in man pages. Default: italic, underlined,
+foreground red. This is overkill! @code{troff} uses just italic;
+@code{nroff} uses just underline. You should probably select either
+italic or underline as you prefer, but not both, although italic and
+underline work together perfectly well!
+
+@item woman-bold-face
+Face for bold font in man pages. Default: bold, foreground blue.
+
+@item woman-unknown-face
+Face for all unknown fonts in man pages. Default: foreground brown.
+Brown is a good compromise: it is distinguishable from the default but
+not enough so as to make font errors look terrible. (Files that use
+non-standard fonts seem to do so badly or in idiosyncratic ways!)
+
+@item woman-addition-face
+Face for all additions made by WoMan to man pages.
+Default: foreground orange.
+@end vtable
+
+
+@node Special symbols, , Faces, Customization
+@comment node-name, next, previous, up
+@section Special symbols
+@cindex special symbols
+
+This section currently applies @emph{only} to Microsoft Windows.
+
+WoMan provides partial experimental support for special symbols,
+initially only for MS-Windows and only for MS-Windows fonts. This
+includes both non-@acronym{ASCII} characters from the main text font and use
+of a separate symbol font. Later, support will be added for other font
+types (e.g.@: @code{bdf} fonts) and for the X Window System. In Emacs
+20.7, the current support works partially under Windows 9x but may not
+work on any other platform.
+
+@vtable @code
+@item woman-use-extended-font
+A boolean value. If non-@code{nil} then WoMan may use non-@acronym{ASCII} characters
+from the default font. Default is @code{t}.
+
+@item woman-use-symbol-font
+A boolean value. If non-@code{nil} then WoMan may use the symbol font.
+Default is @code{nil}, mainly because it may change the line spacing (at
+least in NTEmacs 20).
+
+@item woman-symbol-font
+A string describing the symbol font to use for special characters.
+It should be compatible with, and the same size as, the default text font.
+Under MS-Windows, the default is
+
+@lisp
+"-*-Symbol-normal-r-*-*-*-*-96-96-p-*-ms-symbol"
+@end lisp
+@end vtable
+
+
+@c ===================================================================
+
+@node Log, Technical, Customization, Top
+@comment node-name, next, previous, up
+@chapter The *WoMan-Log* Buffer
+@cindex log buffer
+@cindex buffer, log
+
+This is modeled on the Emacs byte-compiler. It logs all files
+formatted by WoMan and the time taken. If WoMan finds anything that it
+cannot handle then it writes a warning to this buffer. If the variable
+@code{woman-show-log} is non-@code{nil} (by default it is @code{nil}) then
+WoMan automatically displays this buffer. @xref{Interface Options, ,
+Interface Options}. Many WoMan warnings can be completely ignored,
+because they are reporting the fact that WoMan has ignored requests that
+it is correct for WoMan to ignore. In some future version this level of
+paranoia may be reduced, but not until WoMan is deemed more reliable.
+At present, all warnings should be treated with some suspicion.
+Uninterpreted escape sequences are also logged (in some cases).
+
+By resetting the variable @code{woman-ignore} to @code{nil} (by default
+it is @code{t}), uninterpreted @code{roff} requests can optionally be
+left in the formatted buffer to indicate precisely where they occurred.
+@xref{Interface Options, , Interface Options}.
+
+@c ===================================================================
+
+@node Technical, Bugs, Log, Top
+@comment node-name, next, previous, up
+@chapter Technical Details
+@cindex technical details
+@cindex horizontal spacing
+@cindex spacing, horizontal and vertical
+@cindex vertical spacing
+@cindex resolution
+
+@heading Horizontal and vertical spacing and resolution
+
+WoMan currently assumes 10 characters per inch horizontally, hence a
+horizontal resolution of 24 basic units, and 5 lines per inch
+vertically, hence a vertical resolution of 48 basic units.
+(@code{nroff} uses 240 per inch.)
+
+@heading Vertical spacing and blank lines
+
+The number of consecutive blank lines in the formatted buffer should be
+either 0 or 1. A blank line should leave a space like .sp 1.
+Current policy is to output vertical space only immediately before text
+is output.
+
+@c ===================================================================
+
+@node Bugs, Acknowledgements, Technical, Top
+@comment node-name, next, previous, up
+@chapter Reporting Bugs
+@cindex reporting bugs
+@cindex bugs, reporting
+
+If WoMan fails completely, or formats a file incorrectly (i.e.@:
+obviously wrongly or significantly differently from @code{man}) or
+inelegantly, then please
+
+@enumerate
+@item
+try the latest version of @file{woman.el} from the Emacs CVS repository
+on @uref{http://savannah.gnu.org/}. If it still fails, please
+
+@item
+send a bug report to @email{bug-gnu-emacs@@gnu.org} and to
+@email{F.J.Wright@@qmw.ac.uk}. Please include the entry from the
+@code{*WoMan-Log*} buffer relating to the problem file, together with
+a brief description of the problem. Please indicate where you got the
+man source file from, but do not send it unless asked to send it.
+@end enumerate
+
+@c ===================================================================
+
+@node Acknowledgements, GNU Free Documentation License, Bugs, Top
+@comment node-name, next, previous, up
+@chapter Acknowledgements
+@cindex acknowledgements
+
+For Heather, Kathryn and Madelyn, the women in my life (although they
+will probably never use it)!
+
+I also thank the following for helpful suggestions, bug reports, code
+fragments, general interest, etc.:
+
+@quotation
+Jari Aalto, @email{jari.aalto@@cs.tpu.fi}@*
+Dean Andrews, @email{dean@@dra.com}@*
+Juanma Barranquero, @email{barranquero@@laley-actualidad.es}@*
+Karl Berry, @email{kb@@cs.umb.edu}@*
+Jim Chapman, @email{jchapman@@netcomuk.co.uk}@*
+Frederic Corne, @email{frederic.corne@@erli.fr}@*
+Peter Craft, @email{craft@@alacritech.com}@*
+Charles Curley, @email{ccurley@@trib.com}@*
+Jim Davidson, @email{jdavidso@@teknowledge.com}@*
+Kevin D'Elia, @email{Kevin.DElia@@mci.com}@*
+John Fitch, @email{jpff@@maths.bath.ac.uk}@*
+Hans Frosch, @email{jwfrosch@@rish.b17c.ingr.com}@*
+Guy Gascoigne-Piggford, @email{ggp@@informix.com}@*
+Brian Gorka, @email{gorkab@@sanchez.com}@*
+Nicolai Henriksen, @email{nhe@@lyngso-industri.dk}@*
+Thomas Herchenroeder, @email{the@@software-ag.de}@*
+Alexander Hinds, @email{ahinds@@thegrid.net}@*
+Stefan Hornburg, @email{sth@@hacon.de}@*
+Theodore Jump, @email{tjump@@cais.com}@*
+Paul Kinnucan, @email{paulk@@mathworks.com}@*
+Jonas Linde, @email{jonas@@init.se}@*
+Andrew McRae, @email{andrewm@@optimation.co.nz}@*
+Howard Melman, @email{howard@@silverstream.com}@*
+Dennis Pixton, @email{dennis@@math.binghamton.edu}@*
+T. V. Raman, @email{raman@@Adobe.com}@*
+Bruce Ravel, @email{bruce.ravel@@nist.gov}@*
+Benjamin Riefenstahl, @email{benny@@crocodial.de}@*
+Kevin Ruland, @email{kruland@@seistl.com}@*
+Tom Schutter, @email{tom@@platte.com}@*
+Wei-Xue Shi, @email{wxshi@@ma.neweb.ne.jp}@*
+Fabio Somenzi, @email{fabio@@joplin.colorado.edu}@*
+Karel Sprenger, @email{ks@@ic.uva.nl}@*
+Chris Szurgot, @email{szurgot@@itribe.net}@*
+Paul A. Thompson, @email{pat@@po.cwru.edu}@*
+Arrigo Triulzi, @email{arrigo@@maths.qmw.ac.uk}@*
+Geoff Voelker, @email{voelker@@cs.washington.edu}@*
+Eli Zaretskii, @email{eliz@@is.elta.co.il}
+@end quotation
+
+@c ===================================================================
+
+@comment END OF MANUAL TEXT
+@page
+
+
+@node GNU Free Documentation License, Command Index, Acknowledgements, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Command Index, Variable Index, GNU Free Documentation License, Top
+@comment node-name, next, previous, up
+@unnumbered Command Index
+
+@printindex fn
+
+@node Variable Index, Keystroke Index, Command Index, Top
+@comment node-name, next, previous, up
+@unnumbered Variable Index
+
+@printindex vr
+
+@c Without a page throw here, the page length seems to get reset to the
+@c depth of the index that fits on the page after the previous index.
+@c This must be a bug!
+
+@page
+
+@node Keystroke Index, Concept Index, Variable Index, Top
+@comment node-name, next, previous, up
+@unnumbered Keystroke Index
+
+@printindex ky
+
+@c Without a page throw here, the page length seems to get reset to the
+@c depth of the index that fits on the page after the previous index.
+@c This must be a bug!
+
+@page
+
+@node Concept Index, , Keystroke Index, Top
+@comment node-name, next, previous, up
+@unnumbered Concept Index
+
+@printindex cp
+
+@bye
+
+@ignore
+ arch-tag: a1a6b715-396f-4378-9b94-0b2ca0aa5028
+@end ignore
HCoop / bpt / emacs.git / commitdiff