+++ /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-05 Glenn Morris <rgm@gnu.org>
-
- * custom.texi (Safe File Variables): Clarify `!' and risky variables.
-
-2007-09-01 Jay Belanger <jay.p.belanger@gmail.com>
-
- * calc.texi (Date Conversions): Clarify definition of
- Julian day numbering.
- (Date Forms): Clarify definition of Julian day numbering;
- add some history.
-
-2007-08-30 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Version 5.07
-
-2007-08-29 Glenn Morris <rgm@gnu.org>
-
- * emacs.texi (EMACSVER): Increase to 23.0.50.
-
-2007-08-24 IRIE Tetsuya <irie@t.email.ne.jp> (tiny change)
-
- * message.texi (MIME): Replace mml-attach with mml-attach-file.
-
-2007-08-22 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Adding hyperlink types): New section.
- (Embedded LaTeX): Chapter updated because of LaTeX export.
- (LaTeX export): New section.
- (Using links out): New section.
-
-2007-08-22 Glenn Morris <rgm@gnu.org>
-
- * faq.texi (Learning how to do something): Refcards now in
- etc/refcards/ directory.
-
-2007-08-22 Michael Albinus <michael.albinus@gmx.de>
-
- * tramp.texi (Remote Programs): Persistency file must be cleared when
- changing `tramp-remote-path'.
- (Filename Syntax): Don't use @var{} constructs inside the @trampfn
- macro.
-
-2007-08-17 Eli Zaretskii <eliz@gnu.org>
-
- * basic.texi (Position Info): Add index entry for face at point.
- Mention that character faces are also displayed by "C-u C-x =".
-
-2007-08-17 Jay Belanger <jay.p.belanger@gmail.com>
-
- * calc.texi: Move contents to beginning of file.
- (Algebraic Entry): Fix the formatting of an example.
-
-2007-08-15 Jay Belanger <jay.p.belanger@gmail.com>
-
- * calc.texi (Basic Operations on Units): Mention exact versus
- inexact conversions.
-
-2007-08-14 Jay Belanger <jay.p.belanger@gmail.com>
-
- * calc.texi (Basic Operations on Units): Mention default
- values for new units.
- (Quick Calculator Mode): Mention that binary format will
- be displayed.
-
-2007-08-14 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Selecting a Group): Mention gnus-maximum-newsgroup.
-
-2007-08-10 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (NNTP): Mention nntp-xref-number-is-evil.
-
-2007-08-08 Glenn Morris <rgm@gnu.org>
-
- * glossary.texi (Glossary): Deprecate `iff'.
- * gnus.texi, sieve.texi: Replace `iff'.
-
-2007-08-07 Chong Yidong <cyd@stupidchicken.com>
-
- * files.texi (File Conveniences): Document point motion keys in Image
- mode.
-
-2007-08-03 Jay Belanger <jay.p.belanger@gmail.com>
-
- * calc.texi (Basic Graphics): Mention the graphing of error
- forms.
- (Graphics Options): Mention how `g s' handles error forms.
- (Curve Fitting): Mention plotting the curves.
- (Standard Nonlinear Models): Add additional models.
- (Curve Fitting Details): Mention the Levenberg-Marquardt method.
- (Linear Fits): Correct result.
-
-2007-08-01 Alan Mackenzie <acm@muc.de>
-
- * cc-mode.texi (Mailing Lists and Bug Reports): Correct "-no-site-file"
- to "--no-site-file".
-
-2007-07-29 Michael Albinus <michael.albinus@gmx.de>
-
- * tramp.texi (Frequently Asked Questions): Point to mode line
- extension in Emacs 23.1.
-
- * trampver.texi: Update release number.
-
-2007-07-27 Glenn Morris <rgm@gnu.org>
-
- * calc.texi (Copying)
- * emacs.texi (Copying): Include license text from gpl.texi, rather than
- in-line.
-
- * gpl.texi: New file with text of GPL.
- * Makefile.in (EMACSSOURCES): Add gpl.texi.
-
-2007-07-26 Dan Nicolaescu <dann@ics.uci.edu>
-
- * vc2-xtra.texi (Customizing VC): Add GIT and HG.
-
- * dired.texi (Wdired): Mention C-x C-q key binding.
-
-2007-07-28 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (GDB Graphical Interface): Qualify use of "M-x gdba".
-
-2007-07-25 Glenn Morris <rgm@gnu.org>
-
- * calc.texi (Copying)
- * emacs.texi (Copying): Replace license with GPLv3.
-
- * Relicense all FSF files to GPLv3 or later.
-
-2007-07-24 Glenn Morris <rgm@gnu.org>
-
- * calendar.texi (Writing Calendar Files): cal-tex-diary etc only work
- for some calendars.
-
-2007-07-23 Nick Roberts <nickrob@snap.net.nz>
-
- * screen.texi (Mode Line): Describe new mode-line flag that shows if
- default-directory for the current buffer is on a remote machine.
-
-2007-07-22 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.1.10.
-
- * tramp.texi (trampfn): Expand macro implementation in order to handle
- empty arguments.
- (trampfnmhl, trampfnuhl, trampfnhl): Remove macros. Replace all
- occurencies by trampfn.
- (Frequently Asked Questions): Extend example code for host
- identification in the modeline. Add bbdb to approaches shortening Tramp
- file names to be typed.
-
- * trampver.texi: Update release number.
-
-2007-07-21 Eli Zaretskii <eliz@gnu.org>
-
- * vc2-xtra.texi (Customizing VC) <vc-handled-backends>: Update the
- default value.
-
-2007-07-21 Richard Stallman <rms@gnu.org>
-
- * files.texi (Why Version Control?): Improve previous change.
-
-2007-07-18 Eric S. Raymond <esr@snark.thyrsus.com>
-
- * files.texi (Why Version Control?): New node.
-
-2007-07-17 Michael Albinus <michael.albinus@gmx.de>
-
- * tramp.texi: Move @setfilename ../info/tramp up, outside the header
- section. Reported by <poti@potis.org>.
- (Remote processes): Arguments of the program to be debugged are taken
- literally.
- (Frequently Asked Questions): Simplify recentf example.
-
-2007-07-14 Karl Berry <karl@gnu.org>
-
- * info.texi (@copying): New Back-Cover Text.
-
- * info.texi (Quitting Info): Move to proper place in source.
- (Reported by Benno Schulenberg.)
-
-2007-07-13 Eli Zaretskii <eliz@gnu.org>
-
- * Makefile.in (../info/emacs-mime): Use --enable-encoding.
-
- * makefile.w32-in ($(infodir)/emacs-mime): Ditto.
-
- * emacs-mime.texi: Add @documentencoding directive.
-
-2007-07-12 Nick Roberts <nickrob@snap.net.nz>
-
- * tramp.texi (Remote processes): Add an anchor to the subsection
- "Running a debugger on a remote host".
-
- * building.texi (Starting GUD): Add xref to this anchor.
-
-2007-07-12 Michael Albinus <michael.albinus@gmx.de>
-
- * tramp.texi (Remote processes): Don't call it "experimental" any
- longer. Add subsection about running a debugger on a remote host.
-
-2007-07-10 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Properties and columns): Chapter rewritten.
-
-2007-07-08 Michael Albinus <michael.albinus@gmx.de>
-
- * tramp.texi:
- * trampver.texi: Migrate to Tramp 2.1.
-
-2007-07-02 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Properties): New chapter.
-
-2007-07-02 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus-faq.texi ([3.2]): Fix locating of environment variables in the
- Control Panel.
-
- * gnus.texi (Misc Article): Add index entry for
- gnus-single-article-buffer.
-
-2007-06-27 Andreas Seltenreich <andreas@gate450.dyndns.org>
-
- * gnus.texi (Starting Up): Fix typo.
-
-2007-06-25 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Asynchronous Fetching): Fix typo.
-
-2007-06-24 Karl Berry <karl@gnu.org>
-
- * emacs.texi: new Back-Cover Text.
-
-2007-06-20 Jay Belanger <jay.p.belanger@gmail.com>
-
- * calc.texi:Change ifinfo to ifnottex (as appropriate) throughout.
- (About This Manual): Remove redundant information.
- (Getting Started): Mention author.
- (Basic Arithmetic, Customizing Calc): Make description of the
- variable `calc-multiplication-has-precedence' match its new effect.
-
-2007-06-19 Jay Belanger <jay.p.belanger@gmail.com>
-
- * calc.texi (Basic Arithmetic, Customizing Calc): Mention
- the variable `calc-multiplication-has-precedence'.
-
-2007-06-19 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Tag): Section swapped with node Timestamps.
- (Formula syntax for Lisp): Document new `L' flag.
-
-2007-06-06 Andreas Seltenreich <andreas@gate450.dyndns.org>
-
- * gnus.texi (Misc Group Stuff, Summary Buffer)
- (Server Commands, Article Keymap): Fix typo. s/function/command/.
-
-2007-06-07 Alan Mackenzie <acm@muc.de>
-
- * display.texi (Optional Mode Line): Document the new form of
- line+column numbers, "(561,2)".
-
-2007-06-06 Juanma Barranquero <lekktu@gmail.com>
-
- * cc-mode.texi (Comment Commands, Getting Started, Style Variables):
- * gnus.texi (Article Buttons, Mail Source Customization)
- (Sending or Not Sending, Customizing NNDiary):
- * maintaining.texi (Create Tags Table):
- * message.texi (Message Headers):
- * mh-e.texi (HTML): Fix typos.
-
-2007-06-07 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.0.56.
-
- * tramp.texi (Frequently Asked Questions): Improve ~/.zshrc
- settings. Reported by Ted Zlatanov <tzz@lifelogs.com>.
-
-2007-06-02 Chong Yidong <cyd@stupidchicken.com>
-
- * Version 22.1 released.
-
-2007-05-26 Michael Olson <mwolson@gnu.org>
-
- * erc.texi (Modules): Fix references to completion modules.
-
-2007-05-09 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Running NNDiary): Use ~/.gnus.el instead of gnusrc.
-
-2007-05-09 Didier Verna <didier@xemacs.org>
-
- * gnus.texi (Email Based Diary): New. Proper documentation for the
- nndiary back end and the gnus-diary library.
-
-2007-05-07 Karl Berry <karl@gnu.org>
-
- * emacs.texi (EMACSVER): Back to 22.
-
-2007-05-06 Richard Stallman <rms@gnu.org>
-
- * maintaining.texi (Create Tags Table): Clean up previous change.
-
-2007-05-05 Francesco Potort
\e,Al
\e(B <pot@gnu.org>
-
- * maintaining.texi (Create Tags Table): Add text about the dangers of
- making symbolic links to tags files.
-
-2007-05-04 Karl Berry <karl@gnu.org>
-
- * emacs.texi (EMACSVER) [smallbook]: 22.1 for printed version, not 22.
-
-2007-05-03 Karl Berry <karl@gnu.org>
-
- * emacs.texi (EMACSVER) [smallbook]: 22 for printed version.
-
- * .cvsignore (*.pdf): New entry.
-
- * texinfo.tex: Update from current version for better pdf generation.
-
- * emacs.texi (\urlcolor, \linkcolor) [smallbook]: \let to \Black
- for printing.
-
-2007-05-01 Richard Stallman <rms@gnu.org>
-
- * cmdargs.texi (Initial Options): Under --batch, mention --eval.
-
-2007-04-30 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Article Highlighting): Clarify gnus-cite-parse-max-size.
-
-2007-04-28 Glenn Morris <rgm@gnu.org>
-
- * ack.texi (Acknowledgments):
- * anti.texi (Antinews):
- * faq.texi (New in Emacs 22):
- * programs.texi (Program Modes): Restore mention of python.el pending
- consideration of legal status.
-
-2007-04-28 Richard Stallman <rms@gnu.org>
-
- * files.texi (File Names): Fixes to ~ description on MS systems.
-
-2007-04-27 J.D. Smith <jdsmith@as.arizona.edu>
-
- * idlwave.texi: Minor updates for IDLWAVE 6.1.
-
-2007-04-26 Glenn Morris <rgm@gnu.org>
-
- * emacs.texi (EMACSVER): Increase to 22.1.50.
-
-2007-04-25 Karl Berry <karl@gnu.org>
-
- * emacs.texi: Improve line breaks on copyright page,
- similar layout to lispref, 8.5x11 by default.
-
- * dired.texi (Image-Dired): Improve line break, fix typo.
-
-2007-04-24 Chong Yidong <cyd@stupidchicken.com>
-
- * programs.texi (Program Modes):
- * faq.texi (New in Emacs 22):
- * anti.texi (Antinews):
- * ack.texi (Acknowledgments): python.el removed.
-
-2007-04-23 Jay Belanger <jay.p.belanger@gmail.com>
-
- * calc.texi (Reporting bugs): Update maintainer's address.
-
-2007-04-23 Chong Yidong <cyd@stupidchicken.com>
-
- * display.texi (Highlight Interactively): Correct description of
- hi-lock-file-patterns-policy.
-
- * files.texi (File Archives): Mention self-extracting executables.
-
-2007-04-23 Eli Zaretskii <eliz@gnu.org>
-
- * search.texi (Unconditional Replace, Query Replace): Add xref to
- "Replacement and Case".
-
-2007-04-22 Chong Yidong <cyd@stupidchicken.com>
-
- * dired.texi (Image-Dired): Move from Thumbnails node.
- * misc.texi (Thumbnails): Node deleted.
- * emacs.texi (Top): Update node listing.
-
- * files.texi (File Conveniences):
- * ack.texi (Acknowledgments):
- * faq.texi (New in Emacs 22): Rename "tumme" to "image-dired".
-
-2007-04-21 Richard Stallman <rms@gnu.org>
-
- * display.texi (Highlight Interactively): Correct previous change.
- Clarify doc of hi-lock-find-patterns, and move new features into it.
-
-2007-04-20 David Koppelman <koppel@ece.lsu.edu>
-
- * display.texi (Highlight Interactively): Document
- hi-lock-file-patterns-policy.
-
-2007-04-20 Martin Rudalics <rudalics@gmx.at>
-
- * display.texi (Scrolling): Fix typo.
-
-2007-04-15 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Title page): Remove the date.
- (Basic Arithmetic): Emphasize that / binds less strongly than *.
- (The Standard Calc Interface): Change trail title.
- (Floats): Mention that when non-decimal floats are entered, only
- approximations are stored.
- (Copying): Move to the appendices.
- (GNU Free Documentation License): Add as an appendix.
-
-2007-04-15 Chong Yidong <cyd@stupidchicken.com>
-
- * ada-mode.texi, autotype.texi, cc-mode.texi, cl.texi:
- * dired-x.texi, ebrowse.texi, ediff.texi:
- * emacs-mime.texi, erc.texi, eshell.texi:
- * eudc.texi, flymake.texi, forms.texi, gnus.texi:
- * idlwave.texi, message.texi, newsticker.texi, org.texi:
- * pcl-cvs.texi, pgg.texi, rcirc.texi, reftex.texi, sc.texi:
- * ses.texi, sieve.texi, smtpmail.texi, speedbar.texi:
- * tramp.texi, url.texi, vip.texi, viper.texi, widget.texi:
- * woman.texi: Include GFDL.
-
- * doclicense.texi: Remove node heading, so that it can be included by
- other files.
-
- * emacs.texi: Insert node heading for GFDL.
-
- * dired-x.texi: Relicence under GFDL. Remove date from title page.
-
- * calc.texi (Algebraic Tutorial): Emphasize that / binds less strongly
- than *.
-
-2007-04-14 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Formula syntax for Calc): Emphasize the operator precedence
- in Calc.
-
-2007-04-14 Eli Zaretskii <eliz@gnu.org>
-
- * cmdargs.texi (Colors): Qualify "color of window" index entry by
- "command line".
-
- * display.texi (Faces): Refer to "Creating Frames" for face
- and other frame customizations in .emacs.
-
- * frames.texi (Creating Frames): Mention that face customizations can
- be put in .emacs. Add index entries.
-
-2007-04-12 Richard Stallman <rms@gnu.org>
-
- * glossary.texi (Glossary): Explain `iff'.
-
-2007-04-11 Karl Berry <karl@gnu.org>
-
- * gnu.texi (Top),
- * macos.texi (Mac Font Specs),
- * anti.texi (Antinews),
- * xresources.texi (Resources),
- * misc.texi (Emulation),
- * calendar.texi (Daylight Saving),
- * dired.texi (Dired and Find),
- * rmail.texi (Remote Mailboxes),
- * sending.texi (Mail Headers),
- * programs.texi (Which Function),
- * files.texi (Recover),
- * buffers.texi (Uniquify),
- * frames.texi (Wheeled Mice),
- * killing.texi (Rectangles): Wording to improve breaks in
- 8.5x11 format.
- * mule.texi (Language Environments): \hbadness=10000 since there's
- no way to reword.
- * emacs.texi (smallbook): New @set to more easily switch between
- smallbook and 8.5x11.
-
-2007-04-11 Richard Stallman <rms@gnu.org>
-
- * files.texi (File Conveniences): Add xref to Tumme.
- Delete text about Thumbnail mode.
-
-2007-04-09 Romain Francoise <romain@orebokech.com>
-
- * faq.texi (New in Emacs 22): Mention improvements to the Windows and
- Mac OS ports. Make it clear that mouse-1 complements and doesn't
- replace mouse-2.
-
-2007-04-09 Alan Mackenzie <acm@muc.de>
-
- * cmdargs.texi (Initial Options): Call "inhibit-splash-screen" by its
- new name. Insert concept index entries.
-
-2007-04-08 Richard Stallman <rms@gnu.org>
-
- * url.texi: Fix some indexing.
- (Disk Caching): Drop discussion of old/other Emacs versions.
-
-2007-04-08 Chong Yidong <cyd@stupidchicken.com>
-
- * display.texi (Standard Faces): Document prefix arg for
- list-faces-display.
-
- * rmail.texi (Rmail Scrolling): Document rmail-end-of-message.
-
- * woman.texi (Word at point, Interface Options): woman-topic-at-point
- renamed to woman-use-topic-at-point. Document new behavior.
-
-2007-04-07 Chong Yidong <cyd@stupidchicken.com>
-
- * url.texi (Disk Caching): Say Emacs 21 "and later".
-
- * cc-mode.texi (Font Locking Preliminaries): Link to Emacs manual node
- on Font locking which now mentions JIT lock.
-
- * killing.texi (Deletion): Rewrite description of M-\ prefix argument.
-
- * files.texi (Misc File Ops): Rewrite description of
- insert-file-literally.
-
-2007-04-01 Michael Olson <mwolson@gnu.org>
-
- * erc.texi: Update for the ERC 5.2 release.
-
-2007-03-31 David Kastrup <dak@gnu.org>
-
- * woman.texi (Topic, Interface Options): Explain changes semantics of
- woman-manpath in order to consider MANPATH_MAP entries.
-
-2007-03-31 Eli Zaretskii <eliz@gnu.org>
-
- * misc.texi (Printing): Postscript -> PostScript.
-
- * emacs-mime.texi (Non-MIME): Postscript -> PostScript.
-
- * ack.texi (Acknowledgments): Postscript -> PostScript.
-
- * custom.texi (Init File, Init Non-ASCII): Fix last change.
-
- * emacs.texi (Top): Fix the menu due to the change in custom.texi
- below.
-
-2007-03-30 Chong Yidong <cyd@stupidchicken.com>
-
- * custom.texi (Non-ASCII Rebinding): Node deleted. Material moved to
- Init Non-ASCII.
- (Init Rebinding, Init Syntax): Link to Init Non-ASCII instead.
- (Init Non-ASCII): New node.
-
-2007-03-28 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp>
-
- * macos.texi (Mac Font Specs): Mention AppleAntiAliasingThreshold.
-
-2007-03-26 Richard Stallman <rms@gnu.org>
-
- * pgg.texi (Caching passphrase): Clean up previous change.
-
-2007-03-25 Thien-Thi Nguyen <ttn@gnu.org>
-
- * gnus.texi (Setting Process Marks): Fix typo.
-
-2007-03-25 Romain Francoise <romain@orebokech.com>
-
- * faq.texi (New in Emacs 22): Reorganize using an itemized list for
- readability, and include various fixes by Daniel Brockman, Nick Roberts
- and Dieter Wilhelm.
-
-2007-03-24 Thien-Thi Nguyen <ttn@gnu.org>
-
- * gnus.texi (Splitting Mail): Reword "splitting"-as-adj to be -as-noun.
-
- * gnus.texi (Mail Source Specifiers): Fix typo.
-
-2007-03-22 Ralf Angeli <angeli@caeruleus.net>
-
- * reftex.texi (Imprint): Update maintainer information.
-
-2007-03-15 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * message.texi (Message Buffers): Update documentation for
- message-generate-new-buffers.
-
-2007-03-15 Daiki Ueno <ueno@unixuser.org>
-
- * pgg.texi (Caching passphrase): Describe pgg-passphrase-coding-system.
-
-2007-03-21 Glenn Morris <rgm@gnu.org>
-
- * eshell.texi (Known problems): Emacs 22 comes with eshell 2.4.2.
-
-2007-03-19 Chong Yidong <cyd@stupidchicken.com>
-
- * eshell.texi (Known problems): Emacs 21 -> 22.
-
- * cc-mode.texi (Performance Issues): Update note about 21.3 to 22.1.
-
-2007-03-18 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Time Zones): Mention that the DST rules changed in 2007.
-
-2007-03-12 Glenn Morris <rgm@gnu.org>
-
- * calc.texi (Time Zones): Switch to new North America DST rule.
-
- * calendar.texi, emacs.texi (Daylight Saving): Rename node from
- "Daylight Savings".
-
- * calc.texi, calendar.texi: Replace "daylight savings" with "daylight
- saving" in text throughout.
-
-2007-03-11 Andreas Seltenreich <uwi7@rz.uni-karlsruhe.de>
-
- * gnus.texi (Mail and Post): Update documentation for gnus-user-agent.
- The variable now uses a list of symbols instead of just a symbol.
- Reported by Christoph Conrad <christoph.conrad@gmx.de>.
-
-2007-03-06 Romain Francoise <romain@orebokech.com>
-
- * faq.texi (New in Emacs 22): Don't say "now" too much. Add MH-E to
- new packages, and mention Gnus update.
-
-2007-03-04 Richard Stallman <rms@gnu.org>
-
- * custom.texi (Safe File Variables): Minor correction.
-
-2007-02-27 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (NNTP): Mention nntp-never-echoes-commands and
- nntp-open-connection-functions-never-echo-commands.
-
-2007-02-28 Thien-Thi Nguyen <ttn@gnu.org>
-
- * rmail.texi (Movemail): Add internal ref.
- Don't indent the intro for the PROTO table.
- Format PROTO table items with @code.
-
-2007-02-27 Chong Yidong <cyd@stupidchicken.com>
-
- * pgg.texi (Caching passphrase): Document gpg-agent usage, gpg-agent
- problems on the console, and security risk in not using gpg-agent.
-
-2007-02-26 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi: Remove references to bashdb.
-
-2007-02-25 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (The spreadsheet): Renamed from "Table calculations".
- Completely reorganized and rewritten.
- (CamelCase links): Section removed.
- (Repeating items): New section.
- (Tracking TODO state changes): New section.
- (Agenda views): Chapter reorganized and rewritten.
- (HTML export): Section rewritten.
- (Tables in arbitrary syntax): New section.
- (Summary): Better feature summary.
- (Activation): Document problem with cut-and-paste of Lisp code
- from PDF files.
- (Visibility cycling): Document indirect buffer use.
- (Structure editing): Document sorting.
- (Remember): Section rewritten.
- (Time stamps): Better description of time stamp types.
- (Tag searches): Document regular expression search for tags.
- (Stuck projects): New section.
- (In-buffer settings): New keywords.
- (History and Acknowledgments): Updated description.
-
-2007-02-24 Alan Mackenzie <acm@muc.de>
-
- * cc-mode.texi (Movement Commands): Insert two missing command names.
- (Getting Started): Slight wording correction (use conditional).
-
-2007-02-22 Kim F. Storm <storm@cua.dk>
-
- * widget.texi (User Interface, Basic Types): Document need to put some
- text before the %v escape in :format string in editable-field widget.
-
-2007-02-19 Juanma Barranquero <lekktu@gmail.com>
-
- * mule.texi (Language Environments): Update list of supported language
- environments.
-
-2007-02-18 Romain Francoise <romain@orebokech.com>
-
- * pcl-cvs.texi (Miscellaneous commands): q runs `cvs-bury-buffer', not
- `cvs-mode-quit'.
-
-2007-02-14 Kim F. Storm <storm@cua.dk>
-
- * building.texi (Grep Searching): Fix lgrep doc.
-
-2007-02-12 Chong Yidong <cyd@stupidchicken.com>
-
- * back.texi: Remove unused file.
-
-2007-02-10 Markus Triska <markus.triska@gmx.at>
-
- * widget.texi (Programming Example): Put constant strings in :format.
-
-2007-02-07 Juanma Barranquero <lekktu@gmail.com>
-
- * faq.texi (Fullscreen mode on MS-Windows): New node.
-
-2007-02-05 Francesco Potort
\e,Al
\e(B <pot@gnu.org>
-
- * maintaining.texi (Tag Syntax): Now --members is the default for
- etags, not for ctags yet.
-
-2007-02-04 David Kastrup <dak@gnu.org>
-
- * faq.texi (AUCTeX): Update version number. Should probably be done
- for other packages as well.
-
-2007-02-03 Eli Zaretskii <eliz@gnu.org>
-
- * emacs.texi (Top): Update the top-level menus. Make the detailed menu
- headers compliant with Texinfo guidelines and with what texnfo-upd.el
- expects. Add comments to prevent people from inadvertently modifying
- the key parts needed by `texinfo-multiple-files-update'.
-
-2007-01-29 Chong Yidong <cyd@stupidchicken.com>
-
- * frames.texi (Secondary Selection): Window clicked does not matter
- when mouse-yank-at-point is non-nil.
-
-2007-01-28 Andreas Seltenreich <uwi7@rz.uni-karlsruhe.de>
-
- * gnus.texi (Batching Agents): Fix example. Reported by Tassilo Horn
- <tassilo@member.fsf.org>.
-
-2007-01-27 Eli Zaretskii <eliz@gnu.org>
-
- * msdog.texi (ls in Lisp): Document ls-lisp-format-time-list and
- ls-lisp-use-localized-time-format.
-
-2007-01-20 Markus Triska <markus.triska@gmx.at>
-
- * flymake.texi (Flymake mode): find-file-hook instead of ...-hooks.
-
-2007-01-13 Michael Olson <mwolson@gnu.org>
-
- * erc.texi (Modules): Mention capab-identify module.
-
-2007-01-16 Glenn Morris <rgm@gnu.org>
-
- * abbrevs.texi (Editing Abbrevs): Describe how to disable a
- system abbrev.
-
-2007-01-11 Richard Stallman <rms@gnu.org>
-
- * msdog.texi (Windows Keyboard): Another small cleanup.
-
-2007-01-10 Richard Stallman <rms@gnu.org>
-
- * msdog.texi (Windows Keyboard): Yet another try to make
- everyone happy with that passage.
-
-2007-01-05 Richard Stallman <rms@gnu.org>
-
- * anti.texi (Antinews): Mention M-x shell scrolling.
-
-2007-01-05 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Watch Expressions): Describe gdb-max-children.
-
-2007-01-05 Michael Olson <mwolson@gnu.org>
-
- * erc.texi (Getting Started): Update for /RECONNECT command.
-
-2007-01-04 Richard Stallman <rms@gnu.org>
-
- * ebrowse.texi: Change C-c b to C-c C-m.
-
- * msdog.texi (Windows Keyboard): Clarify previous change.
-
-2007-01-03 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Customizing Articles): Use index entries for gnus-treat-*
- variables only in info to avoid redundant entries in the printed
- manual.
-
-2007-01-02 Richard Stallman <rms@gnu.org>
-
- * custom.texi (Changing a Variable): Minor clarification.
- (Specific Customization): customize-customized => customize-unsaved.
-
- * entering.texi (Entering Emacs): Clean up text about restarting
- Emacs for each file.
-
- * misc.texi (Shell Options): Minor cleanup.
-
- * msdog.texi (Windows Keyboard): Explain that Windows was incompatible
- with Emacs, not vice versa.
-
- * programs.texi (Symbol Completion): Recommend customizing
- window manager.
-
- * xresources.texi (Resources): Minor fix.
-
-2007-01-02 Daiki Ueno <ueno@unixuser.org>
-
- * message.texi (Using PGP/MIME): Document gpg-agent usage.
-
-2007-01-02 Reiner Steib <Reiner.Steib@gmx.de>
-
- * message.texi (Security): Split into sub-nodes.
-
-2007-01-01 Alan Mackenzie <acm@muc.de>
-
- * cc-mode.texi ("Limitations and Known Bugs"): Document problems with
- eval-after-load in Emacs <=21 and a workaround. Document that
- trigraphs are not supported.
-
-2007-01-01 Alan Mackenzie <acm@muc.de>
-
- * cc-mode.texi ("Filling and Breaking"): Amend the doc for
- c-context-line-break. When invoked within a string, preserve
- whitespace. Add a backslash only when also in a macro.
-
-2007-01-01 Alan Mackenzie <acm@muc.de>
-
- * cc-mode.texi ("Choosing a Style"): Mention c-file-style.
-
-2007-01-01 Alan Mackenzie <acm@muc.de>
-
- * cc-mode.texi ("Movement Commands", "Sample .emacs File"): C-M-[ae]
- are now bound by default to c-\(beginning\|end\)-of-defun by default.
-
-2007-01-01 Alan Mackenzie <acm@muc.de>
-
- * cc-mode.texi ("Other Commands"): Move c-set-style (C-c .) here from
- "Choosing a Style".
-
- * cc-mode.texi ("Styles"): Add @dfn{style}.
-
-2007-01-01 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * xresources.texi (Table of Resources): Add scrollBarWidth resource.
-
-2007-01-01 Richard Stallman <rms@gnu.org>
-
- * commands.texi (User Input): Document keys stolen by window mangers.
-
-2006-12-31 Richard Stallman <rms@gnu.org>
-
- * custom.texi (Specific Customization): Document customize-option
- instead of customize-variable.
-
-2006-12-31 Kim F. Storm <storm@cua.dk>
-
- * major.texi (Choosing Modes): Document auto-mode-case-fold.
-
-2006-12-30 Kim F. Storm <storm@cua.dk>
-
- * killing.texi (CUA Bindings): Fix typo.
-
- * xresources.texi (Table of Resources): Mention grow-only value for
- auto-resize-tool-bars.
-
-2006-12-30 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.0.55.
-
- * trampver.texi: Update release number.
-
-2006-12-29 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Customizing Articles): Add index entries for all
- gnus-treat-* variables.
-
-2006-12-29 Jouni K. Sepp\e,Ad\e(Bnen <jks@iki.fi>
-
- * gnus.texi (IMAP): Fix incorrect explanation of
- nnimap-search-uids-not-since-is-evil in documentation for
- nnimap-expunge-search-string.
-
-2006-12-27 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (ifile spam filtering): Rename spam-ifile-database-path to
- spam-ifile-database.
-
-2006-12-26 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Spam Package Configuration Examples): Don't encourage to
- rebind C-s.
-
-2006-12-26 Jouni K. Sepp\e,Ad\e(Bnen <jks@iki.fi>
-
- * gnus.texi (Group Parameters, Group Maintenance, Topic Commands)
- (Mail Group Commands, Expiring Mail, IMAP): Add index entries for
- "expiring mail".
- (IMAP): Document nnimap-search-uids-not-since-is-evil and
- nnimap-nov-is-evil.
-
-2006-12-27 Eli Zaretskii <eliz@gnu.org>
-
- * msdog.texi (Windows Keyboard): Mention widespread Windows bindings,
- and how to get them back.
-
-2006-12-26 Richard Stallman <rms@gnu.org>
-
- * calendar.texi (Holidays): Holiday listing is based on current
- practice, but DST is not.
-
-2006-12-25 Richard Stallman <rms@gnu.org>
-
- * emacs.texi (Top): Update subnode menus.
-
- * mark.texi (Transient Mark): Fix xref.
-
- * killing.texi (Graphical Kill): Node deleted.
- (Killing): Add xref to Cut and Paste.
- (CUA Bindings): Update xref.
-
- * frames.texi (Cut and Paste): New section to hold other nodes.
- (Mouse Commands): Node demoted.
- (Cut/Paste Other App): Split out from Mouse Commands.
- (Word and Line Mouse): Likewise.
- (Secondary Selection, Clipboard): Nodes demoted.
-
-2006-12-25 Kevin Ryde <user42@zip.com.au>
-
- * cl.texi (Sorting Sequences): In sort*, add a little cautionary note
- about the key procedure being used heavily.
-
-2006-12-24 Chong Yidong <cyd@stupidchicken.com>
-
- * pgg.texi (Caching passphrase): Default for pgg-gpg-use-agent changed
- to t.
- (Prerequisites): Add explanation about gpg-agent.
-
-2006-12-24 Kevin Ryde <user42@zip.com.au>
-
- * calendar.texi (Holidays): US daylight saving begins second Sunday
- in March for 2007 onwards.
- (Daylight Savings): Show new US default daylight saving rules, 2nd
- Sun in Mar to 1st Sun in Nov, now in cal-dst.el.
-
-2006-12-23 Chong Yidong <cyd@stupidchicken.com>
-
- * calendar.texi (Scroll Calendar): < and > are switched.
-
-2006-12-23 Kevin Rodgers <ihs_4664@yahoo.com>
-
- * killing.texi (Deletion): Describe M-\ prefix argument.
-
-2006-12-23 Richard Stallman <rms@gnu.org>
-
- * search.texi (Regexp Search): Explain why forward and reverse regexp
- search are not mirror images.
-
-2006-12-22 Kevin Ryde <user42@zip.com.au>
-
- * cl.texi (Sorting Sequences): Typo in sort*, example showed plain
- "sort" instead of "sort*".
-
-2006-12-19 Richard Stallman <rms@gnu.org>
-
- * calc.texi (History and Acknowledgements): Recognize that Emacs
- now does have floating point.
-
-2006-12-19 Kim F. Storm <storm@cua.dk>
-
- * major.texi (Choosing Modes): Describe match-function elements for
- magic-mode-alist.
-
-2006-12-19 Michael Albinus <michael.albinus@gmx.de>
-
- * tramp.texi (External transfer methods): Describe new method `scpc'.
-
-2006-12-18 Eli Zaretskii <eliz@gnu.org>
-
- * msdog.texi (Windows Keyboard): Add a footnote about "Windows" keys
- peculiarities.
-
-2006-12-18 Richard Stallman <rms@gnu.org>
-
- * abbrevs.texi (Editing Abbrevs): Fix previous change.
-
-2006-12-17 Sascha Wilde <wilde@sha-bang.de>
-
- * pgg.texi: Added short note on gpg-agent to the introduction.
-
-2006-12-17 Alan Mackenzie <acm@muc.de>
-
- * programs.texi (Left Margin Paren): Remove the bit which says
- that CC Mode sets open-paren-in-column-0-is-defun-start to nil.
- Discuss some of the issues of setting this option to nil.
-
-2006-12-17 Glenn Morris <rgm@gnu.org>
-
- * abbrevs.texi (Editing Abbrevs): Mention system abbrevs.
-
-2006-12-16 Eli Zaretskii <eliz@gnu.org>
-
- * msdog.texi (Windows Keyboard): Clarify `w32-recognize-altgr' effect.
- (Windows Files): `w32-get-true-file-attributes' is only relevant for
- NTFS volumes.
- (ls in Lisp): `links' in `ls-lisp-verbosity' is only relevant to NTFS
- volumes.
-
-2006-12-15 Eli Zaretskii <eliz@gnu.org>
-
- * text.texi (HTML Mode): Fix "C-c TAB".
-
-2006-12-13 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Hiding Headers): Document that `long-to' and `many-to'
- also applies to Cc.
-
-2006-12-12 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (X-Face): Clarify. Say which programs are required
- on Windows.
-
-2006-12-09 Richard Stallman <rms@gnu.org>
-
- * misc.texi (Invoking emacsclient): Simplify TCP file text.
-
-2006-12-08 Kevin Rodgers <ihs_4664@yahoo.com>
-
- * files.texi (Misc File Ops): Document insert-file-literally.
-
-2006-12-08 Eli Zaretskii <eliz@gnu.org>
-
- * cmdargs.texi (Colors): Note that --color is intended for overriding
- the terminal defaults, not for normal invocation.
-
- * misc.texi (Emacs Server): Improve wording. Don't mention the
- ``server program''. Add a cross-reference to "Init File" node.
- (Invoking emacsclient): Add index entries. Document both short and
- long versions of command-line options. Document the -f option.
-
-2006-12-08 Michael Olson <mwolson@gnu.org>
-
- * erc.texi (Modules): Remove documentation for list module.
-
-2006-12-06 Richard Stallman <rms@gnu.org>
-
- * text.texi (Outline Format): Say to set outline-regexp
- and outline-level with major modes and file local variables.
-
-2006-12-05 Micha\e,Ak\e(Bl Cadilhac <michael.cadilhac@lrde.org>
-
- * anti.texi (Antinews): Mention the alternative to
- `~/.emacs_SHELLNAME', which is `~/.emacs.d/init_SHELLNAME.sh'.
-
- * faq.texi (^M in the shell buffer): Ditto.
-
- * misc.texi (Interactive Shell): Ditto.
-
-2006-12-04 Eli Zaretskii <eliz@gnu.org>
-
- * emacs.texi (Acknowledgments): Fix Arne J@o{}rgensen's name.
-
- * ack.texi (Acknowledgments): Fix Arne J@o{}rgensen's name.
-
-2006-12-01 Eli Zaretskii <eliz@gnu.org>
-
- * mule.texi (Enabling Multibyte): Rephrase the confusing reference to a
- colon in the mode line.
-
- * msdog.texi (Windows Processes) [@ifnottex]: Mention w32-shell-execute.
-
-2006-11-26 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Watch Expressions): Mention SPC for expanding/
- contracting watch expressions.
-
-2006-11-26 Kim F. Storm <storm@cua.dk>
-
- * kmacro.texi (Basic Keyboard Macro): Mention F3/F4 more.
-
-2006-11-26 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Debugger Operation): Define text command mode.
- Clarify how tooltips work.
- (GDB Graphical Interface): Explain how to run in text command mode
- more clearly.
-
-2006-11-25 Juanma Barranquero <lekktu@gmail.com>
-
- * mule.texi (Defining Fontsets): Fix use of `charset' and `font'.
-
-2006-11-22 Juanma Barranquero <lekktu@gmail.com>
-
- * anti.texi (Antinews): Mention --server-file and TCP sockets.
-
-2006-11-20 Michael Olson <mwolson@gnu.org>
-
- * erc.texi: Call this the 5.2 stable pre-release of ERC.
-
-2006-11-18 Chong Yidong <cyd@stupidchicken.com>
-
- * misc.texi (Interactive Shell): INSIDE_EMACS is set to t,
- and EMACS is deprecated.
-
-2006-11-18 Juanma Barranquero <lekktu@gmail.com>
-
- * makefile.w32-in (emacs.dvi): Remove xresmini.texi.
-
-2006-11-18 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * Makefile.in (emacs.dvi): Remove xresmini.texi.
-
- * emacs.texi: Include xresources.texi both for info and dvi.
-
- * xresources.texi: Merge text from xresmini.texi.
-
-2006-11-17 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Fix typos.
- (Agenda commands): Document `C-k'.
-
-2006-11-16 Eli Zaretskii <eliz@gnu.org>
-
- * url.texi (http/https): Fix a typo in the HTTP URL.
-
-2006-11-14 Stephen Leake <stephen_leake@stephe-leake.org>
-
- * ada-mode.texi: Total rewrite.
-
-2006-11-13 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Minor typo fixes.
-
-2006-11-13 Bill Wohler <wohler@newt.com>
-
- Release MH-E manual version 8.0.3.
-
- * mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for
- release 8.0.3.
-
- * mh-e.texi (Incorporating Mail): Use output of "mhparam Path"
- to set MAILDIR.
- (Reading Mail): Document the customization of read-mail-command
- for MH-E.
- (Viewing Attachments): Document mm-discouraged-alternatives.
- (Tool Bar): Fix Texinfo for mh-xemacs-use-tool-bar-flag.
- (Junk): Add more information about the settings of mh-junk-background
- in a program. Add /usr/bin/mh to PATH in examples.
-
-2006-11-12 Richard Stallman <rms@gnu.org>
-
- * woman.texi: Update author address but say he no longer maintains it.
-
-2006-11-12 Roberto Rodr\e,Am\e(Bguez <lanubeblanca@googlemail.com> (tiny change)
-
- * glossary.texi: Fix typos.
-
-2006-11-10 Carsten Dominik <carsten.dominik@gmail.com>
-
- * org.texi (ARCHIVE tag): Document C-TAB for forcing cycling of
- archived trees.
- (Checkboxes): Section moved to chapter 5, and extended.
- (The date/time prompt): New section.
- (Link abbreviations): New section.
- (Presentation and sorting): New section.
- (Custom agenda views): Section completely rewritten.
- (Summary): Compare with Planner.
- (Feedback): More info about creating backtraces.
- (Plain lists): Modified example.
- (Breaking down tasks): New section.
- (Custom time format): New section.
- (Time stamps): Document inactive timestamps.
- (Setting tags): More details about fast tag selection.
- (Block agenda): New section.
- (Custom agenda views): Section rewritten.
- (Block agenda): New section.
-
-2006-11-07 Michael Albinus <michael.albinus@gmx.de>
-
- * tramp.texi (Configuration): scp is the default method.
- (Default Method): Use ssh as example for another method.
-
-2006-11-06 Richard Stallman <rms@gnu.org>
-
- * emacs.texi (Acknowledgments): Fix name spelling, add Anna Bigatti.
-
- * ack.texi (Acknowledgments): Fix name spelling.
-
-2006-11-01 Juri Linkov <juri@jurta.org>
-
- * search.texi (Word Search): Document incremental word search.
-
-2006-10-28 Glenn Morris <rgm@gnu.org>
-
- * ack.texi (Acknowledgments): Add cal-html author.
-
- * calendar.texi (Writing Calendar Files): Rename section (was "LaTeX
- Calendar"). Describe new package cal-html.
- * emacs.texi (Top): Rename old node "LaTeX Calendar" to "Writing
- Calendar Files."
-
-2006-10-27 Richard Stallman <rms@gnu.org>
-
- * woman.texi: Downcase nroff/troff/roff.
- (Installation): Chapter deleted. Some xrefs deleted.
- (Background): woman doesn't advise man ;-).
-
-2006-10-26 Roberto Rodr\e,Am\e(Bguez <lanubeblanca@googlemail.com> (tiny change)
-
- * ada-mode.texi (Project files, Identifier completion)
- (Automatic Casing, Debugging, Using non-standard file names)
- (Working Remotely): Fix typos.
-
-2006-10-23 Richard Stallman <rms@gnu.org>
-
- * abbrevs.texi (Expanding Abbrevs): Expansion happens only when
- Abbrev mode is enabled.
-
-2006-10-20 Masatake YAMATO <jet@gyve.org>
-
- * cc-mode.texi (Sample .emacs File): Added missing `)' in
- sample code `my-c-initialization-hook'.
-
-2006-10-19 Stuart D. Herring <herring@lanl.gov>
-
- * widget.texi: Fix typos.
-
-2006-10-19 Michael Albinus <michael.albinus@gmx.de>
-
- * tramp.texi (Frequently Asked Questions): Remove questions marked with
- "???". There have been no complaints for years, so the information
- must be appropriate.
-
-2006-10-16 Richard Stallman <rms@gnu.org>
-
- * widget.texi: Use @var instead of capitalization.
- Clarify many widget type descriptions.
-
- * emacs.texi: Update ISBN.
-
-2006-10-13 Andreas Seltenreich <uwi7@rz.uni-karlsruhe.de>
-
- * gnus.texi (Other modes): Fix typo. Add alternative index entry for
- gnus-dired-attach.
- (Selecting a Group): Fix typo.
-
-2006-10-12 Roberto Rodr\e,Am\e(Bguez <lanubeblanca@googlemail.com> (tiny change)
-
- * widget.texi: Fix typos.
-
-2006-10-11 Kim F. Storm <storm@cua.dk>
-
- * emacs.texi (Acknowledgments): Use @dotless{i}.
-
-2006-10-08 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Breakpoints Buffer): Mention catchpoints.
-
-2006-10-08 Kim F. Storm <storm@cua.dk>
-
- * ack.texi (Acknowledgments): Update.
-
- * emacs.texi (Acknowledgments): Fix bad @/ form.
-
-2006-10-06 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Image Enhancements): Update for Emacs 22.
-
- * gnus-faq.texi ([1.3]): Update.
-
-2006-10-06 Richard Stallman <rms@gnu.org>
-
- * faq.texi (Displaying the current line or column):
- Delete "As of Emacs 20".
-
-2006-10-06 Romain Francoise <romain@orebokech.com>
-
- * faq.texi (VM): VM works with Emacs 22 too.
-
-2006-10-06 Richard Stallman <rms@gnu.org>
-
- * ebrowse.texi: Remove Emacs version "21" from title.
-
-2006-10-05 Kim F. Storm <storm@cua.dk>
-
- * emacs.texi (Acknowledgments): Add more contributors.
-
-2006-10-03 Richard Stallman <rms@gnu.org>
-
- * emacs.texi (Acknowledgments): Update version and edition.
-
-2006-10-02 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Foreign Groups): Say where change of editing commands are
- stored. Add reference to `gnus-parameters'.
-
-2006-10-01 Karl Berry <karl@gnu.org>
-
- * custom.texi (Customization Groups): Page break to keep example buffer
- on one page.
-
-2006-09-30 Karl Berry <karl@gnu.org>
-
- * programs.texi (Basic Indent): @need to improve page break.
- * text.texi: Rewording to improve page breaks, and use @LaTeX{}.
-
-2006-09-29 Glenn Morris <rgm@gnu.org>
-
- * calendar.texi (Date Formats): Doc fix for european-calendar-style.
-
-2006-09-29 Karl Berry <karl@gnu.org>
-
- * windows.texi (Basic Window): Remove forced @break, no longer
- desirable.
- * frames.texi (Frame Commands),
- * mark.texi (Marking Objects): Reword to avoid bad page break.
- * display.texi (Auto Scrolling): Use @tie{} to avoid bad line break.
-
-2006-09-19 Richard Stallman <rms@gnu.org>
-
- * frames.texi (Dialog Boxes): Clean up wording: avoid passive,
- stick to present tense.
-
-2006-09-18 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * frames.texi (Dialog Boxes): Rename x-use-old-gtk-file-dialog
- to x-gtk-use-old-file-dialog.
- (Dialog Boxes): Document x-gtk-file-dialog-help-text.
-
-2006-09-15 Jay Belanger <belanger@truman.edu>
-
- * calc.texi, emacs.texi, mh-e.texi (GNU GENERAL PUBLIC LICENSE):
- Change "Library Public License" to "Lesser Public License"
- throughout. Use "yyyy" to represent year.
-
-2006-09-15 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Setting tags): Typo fix.
-
-2006-09-14 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Oort Gnus): Add @xref for `mm-fill-flowed'.
-
-2006-09-12 Reiner Steib <Reiner.Steib@gmx.de>
-
- * files.texi (Visiting): Add index entry "open file".
-
- * reftex.texi (Citations Outside LaTeX): Simplify lisp example.
-
-2006-09-12 Paul Eggert <eggert@cs.ucla.edu>
-
- * faq.texi (Escape sequences in shell output): EMACS is now set
- to Emacs's absolute file name, not to "t".
- (^M in the shell buffer): Likewise.
- * misc.texi (Interactive Shell): Likewise.
-
-2006-09-11 Richard Stallman <rms@gnu.org>
-
- * building.texi (Compilation Mode): Clarification.
- (Grep Searching): Add xref to Compilation Mode.
-
-2006-09-11 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Mail Source Specifiers): Mention problem of duplicate
- mails with pop3-leave-mail-on-server. Fix wording.
- (Limiting): Improve gnus-summary-limit-to-articles.
- (X-Face): Fix typo.
-
-2006-09-11 Simon Josefsson <jas@extundo.com>
-
- * smtpmail.texi (Authentication): Explain TLS and SSL better, based on
- suggested by Phillip Lord <phillip.lord@newcastle.ac.uk>.
-
-2006-09-08 Richard Stallman <rms@gnu.org>
-
- * search.texi (Search): Ref multi-file search commands here.
- (Other Repeating Search): Not here.
-
-2006-09-06 Simon Josefsson <jas@extundo.com>
-
- * smtpmail.texi (Authentication): Mention SSL.
-
-2006-09-01 Eli Zaretskii <eliz@gnu.org>
-
- * rcirc.texi (Internet Relay Chat, Useful IRC commands):
- Don't use @indicateurl.
-
- * cc-mode.texi (Subword Movement): Don't use @headitem.
- (Custom Braces, Clean-ups): Don't use @tie.
-
-2006-08-29 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.0.54.
-
- * tramp.texi (Bug Reports): The Tramp mailing list is moderated now.
- Suggested by Adrian Phillips <a.phillips@met.no>.
-
-2006-08-28 Richard Stallman <rms@gnu.org>
-
- * windows.texi (Split Window): Update xref.
-
- * basic.texi (Continuation Lines): Update xref.
-
- * indent.texi (Tab Stops): Update xref.
-
- * emacs.texi (Top): Update subnode menu.
-
- * display.texi (Line Truncation, Displaying Boundaries): New nodes,
- split out of Display Custom.
-
-2006-08-25 Kim F. Storm <storm@cua.dk>
-
- * display.texi (Display Custom): Add variables overline-margin
- and x-underline-at-descent-line.
-
-2006-08-25 Richard Stallman <rms@gnu.org>
-
- * entering.texi (Exiting): Rewrite to give graphical displays
- priority over text terminals.
-
- * search.texi (Incremental Search): Move index entries.
-
-2006-08-23 Chong Yidong <cyd@stupidchicken.com>
-
- * custom.texi (Init File): Reference Find Init to avoid "home
- directory" confusion.
-
-2006-08-22 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Other GDB-UI Buffers): Describe how to edit
- a value in the locals buffer.
-
-2006-08-21 Richard Stallman <rms@gnu.org>
-
- * search.texi (Basic Isearch): Add `isearch' index entry.
-
-2006-08-16 Richard Stallman <rms@gnu.org>
-
- * misc.texi (Saving Emacs Sessions): Clean up wording.
-
- * mark.texi (Marking Objects): Mention term "select all".
-
- * emacs.texi (Top): Update subnode menu.
-
- * help.texi (Help Mode): Move node up in file.
-
-2006-08-15 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Installation, Activation): Split from Installation and
- Activation.
- (Clocking work time): Documented new features.
-
-2006-08-15 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Stack Buffer): Explain fringe arrow.
-
-2006-08-13 Alex Schroeder <alex@gnu.org>
-
- * rcirc.texi (Configuration): Use correct variable in rcirc-authinfo
- example.
-
-2006-08-12 Eli Zaretskii <eliz@gnu.org>
-
- * faq.texi (How to add fonts): New node.
-
- * misc.texi (Saving Emacs Sessions): Clarify when desktop is restored
- on startup.
-
-2006-08-11 Romain Francoise <romain@orebokech.com>
-
- * ack.texi (Acknowledgments): Delete mention to zone-mode.el.
-
-2006-08-10 Sven Joachim <svenjoac@gmx.de> (tiny change)
-
- * mule.texi (Recognize Coding, Text Coding): Fix typos.
-
-2006-08-10 Richard Stallman <rms@gnu.org>
-
- * text.texi (Format Faces): Substantial rewrites to deal
- with face merging. Empty regions don't count. Clarify
- face property inheritance.
-
-2006-08-08 Romain Francoise <romain@orebokech.com>
-
- * dired.texi (Marks vs Flags): Fix typo reported by Ari Roponen
- <arjuropo@cc.jyu.fi>.
-
-2006-08-05 Romain Francoise <romain@orebokech.com>
-
- * faq.texi (New in Emacs 22): Expand.
-
-2006-08-04 Eli Zaretskii <eliz@gnu.org>
-
- * cmdargs.texi (Window Size X) <--geometry>: Only width and height
- apply to all frames.
-
-2006-08-03 Michael Olson <mwolson@gnu.org>
-
- * erc.texi: Update for ERC 5.1.4.
-
-2006-08-01 Richard Stallman <rms@gnu.org>
-
- * help.texi (Name Help): Add index entries for describe-variable.
-
-2006-08-01 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (GDB Graphical Interface): Shorten node names.
- (GDB-UI Layout): Use GDB-related.
- (Other GDB-UI Buffers): Simplify English.
-
-2006-07-31 Richard Stallman <rms@gnu.org>
-
- * search.texi (Query Replace): Add xref for Dired's Q command.
-
-2006-07-28 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Oort Gnus): Mention that the Lisp files are now installed
- in .../site-lisp/gnus/ by default.
- [ From gnus-news.texi in the trunk. ]
-
-2006-07-27 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (MIME Commands): Additions for yEnc.
-
-2006-07-31 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (GDB commands in Fringe): Rename to...
- (Source Buffers): ..this and move forward. Describe hollow arrow and
- new option gdb-find-source-frame.
-
-2006-07-29 Richard Stallman <rms@gnu.org>
-
- * dired.texi (Operating on Files): Simplify previous change
- and fix Texinfo usage.
-
-2006-07-29 Eli Zaretskii <eliz@gnu.org>
-
- * dired.texi (Operating on Files): Add cross-references. State the
- Unix commands that do similar things.
-
-2006-07-28 Richard Stallman <rms@gnu.org>
-
- * mark.texi (Transient Mark): Clarify that region never disappears
- when Transient Mark mode is off, and not when it is on.
-
-2006-07-27 Richard Stallman <rms@gnu.org>
-
- * search.texi (Non-ASCII Isearch): Clarify. Mention C-q.
-
-2006-07-24 Richard Stallman <rms@gnu.org>
-
- * xresources.texi (GTK styles): Fix texinfo usage.
-
- * pgg.texi, org.texi, info.texi, forms.texi, flymake.texi:
- * faq.texi: Move periods and commas inside quotes.
-
- * commands.texi (User Input): Explain why we teach keyboard cmds.
-
- * xresources.texi, xresmini.texi, search.texi, programs.texi:
- * misc.texi, kmacro.texi, killing.texi, glossary.texi:
- * fortran-xtra.texi, files.texi, emacs.texi, emacs-xtra.texi:
- * doclicense.texi, display.texi, dired.texi, basic.texi:
- * anti.texi, ack.texi: Move periods and commas inside quotes.
-
-2006-07-22 Eli Zaretskii <eliz@gnu.org>
-
- * cmdargs.texi (General Variables): Document EMAIL.
-
-2006-07-21 Eli Zaretskii <eliz@gnu.org>
-
- * frames.texi (Frame Commands): Mention that focus-follows-mouse
- doesn't have effect on MS-Windows.
-
-2006-07-20 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Error forms): Mention M-+ keybinding for `calc-plus-minus'.
-
-2006-07-18 Chong Yidong <cyd@stupidchicken.com>
-
- * faq.texi (Security risks with Emacs): Document Emacs 22
- file-local-variable mechanism.
-
-2006-07-17 Richard Stallman <rms@gnu.org>
-
- * building.texi (Grep Searching): Explain about chaining grep commands.
-
-2006-07-12 Michael Olson <mwolson@gnu.org>
-
- * erc.texi: Update for ERC 5.1.3.
-
-2006-07-12 Alex Schroeder <alex@gnu.org>
-
- * rcirc.texi: Fix typos.
- (Getting started with rcirc): New calling convention for M-x irc.
- Mention #rcirc. Removed channel tracking.
- (Configuration): Changed the names of all variables that got changed
- recently, eg. rcirc-server to rcirc-default-server. Added
- documentation for rcirc-authinfo, some background for Bitlbee, and
- rcirc-track-minor-mode.
- (Scrolling conservatively): Fixed the xref from Auto Scrolling to just
- Scrolling.
- (Reconnecting after you have lost the connection): Fixed example code
- to match code changes.
-
-2006-07-10 Nick Roberts <nickrob@snap.net.nz>
-
- * killing.texi, gnus.texi, message.texi, mini.texi: Fix typos.
-
-2006-07-09 Chong Yidong <cyd@stupidchicken.com>
-
- * misc.texi (Invoking emacsclient): Document behavior when emacsclient
- is invoked for multiple files.
-
-2006-07-08 Eli Zaretskii <eliz@gnu.org>
-
- * msdog.texi (Windows Keyboard) [@iftex]: Add an @inforef to the
- on-line manual for the rest of this node.
- (Windows Mouse) <w32-pass-extra-mouse-buttons-to-system>: Include
- unconditionally.
- (Windows Processes) <w32-quote-process-args>: Include unconditionally.
- Improve wording.
- (Windows Printing): Improve wording.
- (Windows Misc) [@iftex]: Add an @inforef to the on-line manual for the
- rest of this node.
-
-2006-07-07 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Exporting): Document `C-c C-e' as the prefix for exporting
- commands.
- (Global TODO list): Document the use of the variables
- `org-agenda-todo-ignore-scheduled' and
- `org-agenda-todo-list-sublevels'.
-
-2006-07-05 Richard Stallman <rms@gnu.org>
-
- * faq.texi (Scrolling only one line): Fix xref.
-
-2006-07-05 Thien-Thi Nguyen <ttn@gnu.org>
-
- * building.texi (Lisp Eval):
- * faq.texi (Evaluating Emacs Lisp code):
- Throughout, replace eval-current-buffer with eval-buffer.
-
-2006-07-05 Nick Roberts <nickrob@snap.net.nz>
-
- * mule.texi (Coding Systems, Specify Coding): Link descriptions
- of character translation.
-
-2006-07-04 Nick Roberts <nickrob@snap.net.nz>
-
- * rmail.texi (Remote Mailboxes): Add missing @code keyword.
-
-2006-07-03 Karl Berry <karl@gnu.org>
-
- * emacs.texi (\hbadness): Set to 6000 so we aren't bothered by
- not-too-underfull hboxes in the TeX output.
- * abbrevs.texi, buffers.texi, building.texi, calendar.texi,
- * cmdargs.texi, custom.texi, dired.texi, macos.texi,
- * maintaining.texi, misc.texi, mule.texi, programs.texi, rmail.texi,
- * sending.texi, text.texi: Fix overfull/underfull boxes.
-
-2006-07-03 Romain Francoise <romain@orebokech.com>
-
- * m-x.texi (M-x): Fix.
-
-2006-07-03 Richard Stallman <rms@gnu.org>
-
- * rcirc.texi (Scrolling conservatively): Fix xref.
-
- * pcl-cvs.texi (Viewing differences): Usage fix.
-
- * search.texi (Other Repeating Search): filename -> file name.
-
- * misc.texi (Narrowing): Minor cleanups.
-
- * files.texi (Visiting): filename -> file name.
-
- * emacs.texi (Top): Update subnode menus.
-
- * mule.texi (Coding Systems): Move char translation stuff here.
- (Specify Coding, Output Coding): New nodes, out of Recognize Coding.
- (Recognize Coding): Substantial local rewrites.
- (International): Update menu.
-
- * display.texi (Auto Scrolling): New node, broken out of Scrolling.
- (Scrolling): Substantial local rewrites.
- (Display): Update menu and intro.
-
- * dired.texi: filename -> file name.
-
- * custom.texi (Safe File Variables): Texinfo usage fix.
-
-2006-07-03 Ted Zlatanov <tzz@lifelogs.com>
-
- * help.texi, m-x.texi: Lots of cleanups.
-
-2006-07-03 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Agenda commands): Document `s' key to save all org-mode
- buffers.
-
-2006-06-30 Eli Zaretskii <eliz@gnu.org>
-
- * msdog.texi (ls in Lisp, Windows Keyboard, Windows Mouse)
- (Windows Processes, Windows Misc): Shorten the printed version by
- selectively conditioning less important portions by @ifnottex.
-
-2006-06-30 Ralf Angeli <angeli@caeruleus.net>
-
- * pcl-cvs.texi (Customizing Faces): Remove -face suffix from face
- names. Mention `cvs-msg' face.
-
-2006-06-29 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Checkboxes): New section.
-
-2006-06-28 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Embedded LaTeX): Fix typos and implement small improvements
- throughout this chapter.
-
-2006-06-27 Chong Yidong <cyd@stupidchicken.com>
-
- * info.texi (Help-Small-Screen): Clarify placement of "All" and "Top"
- text for standalone vs Emacs info.
- (Help): Clarify header line description. Use mouse-1 for clicks.
- (Help-P): Use mouse-1 for clicks.
- (Help-^L): "Top" and "All" not displayed with dashes in Emacs.
- (Help-^L, Help-M, Help-Int, Search Index, Go to node)
- (Choose menu subtopic): Remove gratuitous Emacs command names.
- (Help-FOO): Put usual behavior first.
- (Help-Xref): Clicking on xrefs works in Emacs.
- (Search Text): Clarify what the default behavior is.
- (Create Info buffer): Fix Emacs window/X window confusion.
- (Emacs Info Variables): Fix for new Emacs init file behavior.
-
-2006-06-27 Richard Stallman <rms@gnu.org>
-
- * mini.texi (Minibuffer File): Minor cleanup.
-
-2006-06-25 Nick Roberts <nickrob@snap.net.nz>
-
- * frames.texi (XTerm Mouse): Rename to...
- (Text-Only Mouse): ...this. Mention t-mouse-mode.
-
- * emacs.texi (Top): Use new node name.
-
-2006-06-24 Eli Zaretskii <eliz@gnu.org>
-
- * emacs.texi (Top): Update the detailed menu according to changes in
- msdog.texi.
-
- * msdog.texi (Windows Keyboard): New section.
- (Windows Mouse): New section.
- (Windows System Menu): Remove section (text merged with "Windows
- Keyboard").
- (Windows Misc): New section.
-
- * dired.texi (Dired Enter): Refer to msdog.texi for ls-lisp emulation.
-
- * msdog.texi (ls in Lisp): New section.
-
- * files.texi (Visiting): Document case-insensitive wildcard matching
- under find-file-wildcards.
-
-2006-06-24 Andreas Seltenreich <uwi7@rz.uni-karlsruhe.de>
-
- * gnus.texi (Summary Buffer Lines): Fix typo.
-
-2006-06-23 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Embedded LaTeX): New chapter.
- (Archiving): Section rewritten.
- (Enhancing text): Some parts moved to the new chapter about LaTeX.
-
-2006-06-20 Bill Wohler <wohler@newt.com>
-
- Release MH-E manual version 8.0.1.
-
- * mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for
- release 8.0.1.
- (Preface): Depend on GNU mailutils 1.0 and higher.
-
-2006-06-19 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * message.texi (News Headers): Update message-syntax-checks section.
-
-2006-06-19 Karl Berry <karl@gnu.org>
-
- * info.texi (Advanced): Mention C-q, especially with ?.
-
-2006-06-19 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Publishing links): Document the `:link-validation-function'
- property.
- (Extensions and Hacking): New chapter, includes some sections of the
- "Miscellaneous" chapter.
-
-2006-06-16 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp>
-
- * macos.texi (Mac Input): Add description of mac-function-modifier.
- Now Unicode keyboard layouts work.
-
-2006-06-10 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Progress logging): New section.
-
-2006-06-10 Richard Stallman <rms@gnu.org>
-
- * mule.texi (Recognize Coding): Clarify previous change.
-
-2006-06-09 Kenichi Handa <handa@m17n.org>
-
- * mule.texi (Recognize Coding): Describe the convention of "CODING!"
- notation.
-
-2006-06-07 Kevin Ryde <user42@zip.com.au>
-
- * mule.texi (Coding Systems): Footnote xref "MS-DOS and MULE" in main
- manual for @ifnottex, but in emacs-extra for @iftex.
-
- * cmdargs.texi (General Variables): Fix smtpmail xref.
-
-2006-05-29 Stefan Monnier <monnier@iro.umontreal.ca>
-
- * viper.texi (Viper Specials):
- * programs.texi (Comment Commands):
- * gnus.texi (Example Setup):
- * faq.texi (Backspace invokes help):
- * dired-x.texi (Optional Installation Dired Jump):
- * custom.texi (Specifying File Variables):
- * calc.texi (Defining Simple Commands): Use ;; instead of ;;; to better
- follow coding conventions.
-
-2006-05-18 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Saving Articles): Clarify gnus-summary-save-article-mail.
-
-2006-06-07 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Watch Expressions): Move node to end.
- (GDB Graphical Interface): Move description of clicks in fringe...
- (GDB commands in the Fringe): ...to here. New node.
-
-2006-06-06 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (ASCII export): Document indentation adaptation.
- (Setting tags): Document mutually-exclusive tags.
-
-2006-06-05 Romain Francoise <romain@orebokech.com>
-
- * url.texi (irc): Mention new funs `url-irc-rcirc' and `url-irc-erc'.
- Fix typo.
-
- * gnus-faq.texi (Question 8.6): Update reference to the Gnus
- channel (#gnus@irc.freenode.net).
- Fix typos. Update copyright notice.
-
- * cc-mode.texi (Getting Started, Indentation Commands, Config Basics)
- (Custom Filling and Breaking, Custom Braces, Syntactic Symbols)
- (Line-Up Functions, Custom Macros):
- * ediff.texi (Window and Frame Configuration)
- (Highlighting Difference Regions, Highlighting Difference Regions):
- * emacs-mime.texi (Display Customization):
- * erc.texi (History):
- * eshell.texi (Known problems):
- * eudc.texi (Overview, BBDB):
- * gnus.texi (NNTP, IMAP, Advanced Scoring Examples)
- (The problem of spam, SpamOracle, Extending the Spam package)
- (Conformity, Terminology):
- * idlwave.texi (Routine Info, Routine Info)
- (Class and Keyword Inheritance, Padding Operators)
- (Breakpoints and Stepping, Electric Debug Mode)
- (Examining Variables, Troubleshooting):
- * org.texi (Creating timestamps):
- * reftex.texi (Commands, Options, Changes):
- * tramp.texi (Inline methods, Password caching)
- (Auto-save and Backup, Issues):
- * vip.texi (Files, Commands in Insert Mode):
- * viper.texi (Emacs Preliminaries, States in Viper)
- (Packages that Change Keymaps, Viper Specials, Groundwork):
- * xresmini.texi (GTK resources):
- Fix various typos.
-
-2006-06-05 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (GDB Graphical Interface): Update bindings.
- (Commands of GUD): Add gud-print. Remove gud-run.
- Restate availability more generally.
-
-2006-06-03 Ted Zlatanov <tzz@lifelogs.com>
-
- * mini.texi: Lots of cleanups.
-
-2006-06-01 Luc Teirlinck <teirllm@auburn.edu>
-
- * misc.texi (Shell History Copying): Update descriptions of `C-c RET'
- and Mouse-2.
-
-2006-06-01 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * screen.texi (Menu Bar): Change menu-bar-start to menu-bar-open.
-
-2006-05-31 Michael Ernst <mernst@alum.mit.edu>
-
- * ediff.texi: Fix typos.
-
-2006-05-31 Richard Stallman <rms@gnu.org>
-
- * basic.texi (Moving Point): Fix previous change.
-
-2006-05-30 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Small typo fixes.
-
-2006-05-29 Michael Albinus <michael.albinus@gmx.de>
-
- * tramp.texi (Frequently Asked Questions): Disable zsh zle.
-
-2006-05-29 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * screen.texi (Menu Bar): F10 for Gtk+/Lesstif/Lucid menus.
-
-2006-05-28 Ted Zlatanov <tzz@lifelogs.com>
-
- * basic.texi: Many simplifications and improvements in wording.
-
-2006-05-27 Thien-Thi Nguyen <ttn@gnu.org>
-
- * pcl-cvs.texi: Fix typos.
- (Customization): Say "us".
-
-2006-05-26 Eli Zaretskii <eliz@gnu.org>
-
- * org.texi: Remove bogus @setfilename.
-
-2006-05-26 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (ASCII export): Omit command name.
- (HTML export): Add prefix to all lines in Local Variable example.
- (Acknowledgments): Typeset names in italics.
-
-2006-05-26 Nick Roberts <nickrob@snap.net.nz>
-
- * anti.texi (Antinews): Create a node for gdb-ui.
-
-2006-05-24 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Plain lists): Add new item navigation commands.
- (External links): Document elisp and info links.
- (Custom searches): New section.
- (Publishing): New chapter.
- (HTML export): Include a list of supported CSS classes.
- (Setting tags): Describe the fast-tag-setting interface.
-
-2006-05-22 Reiner Steib <Reiner.Steib@gmx.de>
-
- * frames.texi (Menu Bars, Tool Bars): Add index entries.
-
-2006-05-20 Richard Stallman <rms@gnu.org>
-
- * dired.texi (Dired Navigation): dired-goto-file is now j.
-
-2006-05-20 Luc Teirlinck <teirllm@auburn.edu>
-
- * dired-x.texi: ifinfo -> ifnottex.
-
-2006-05-20 Eli Zaretskii <eliz@gnu.org>
-
- * mule.texi (Coding Systems): Mention the undecided-* coding systems
- and their aliases.
-
- * msdog.texi (Windows Printing): Mention non-support of plain text
- printing with some el-cheapo printers, and suggest a workaround.
-
-2006-05-20 Kevin Ryde <user42@zip.com.au>
-
- * text.texi (TeX Print): tex-dvi-view-command has a default value,
- remove the bit saying you must set it.
-
-2006-05-19 Luc Teirlinck <teirllm@auburn.edu>
-
- * trouble.texi (Checklist):
- * text.texi (Text, Auto Fill, Text Mode):
- * search.texi (Nonincremental Search):
- * rmail.texi (Rmail Labels):
- * mule.texi (Input Methods, Multibyte Conversion):
- * misc.texi (Gnus, Where to Look, PostScript):
- * maintaining.texi (Create Tags Table):
- * indent.texi (Indentation Commands):
- * fixit.texi (Spelling):
- * emacs.texi (Copying):
- * custom.texi (Init File): ifinfo -> ifnottex.
-
-2006-05-18 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Saving Articles): Clarify gnus-summary-save-article-mail.
-
-2006-05-17 Richard Stallman <rms@gnu.org>
-
- * files.texi (Diff Mode): Mention C-x `.
-
-2006-05-08 Richard Stallman <rms@gnu.org>
-
- * custom.texi (Disabling): Textual cleanups.
-
-2006-05-12 Reiner Steib <Reiner.Steib@gmx.de>
-
- * message.texi (Interface): Add tool bar customization.
- (MIME): Index and text additions for mml-attach.
- (MIME): Describe mml-dnd-protocol-alist and
- mml-dnd-attach-options.
-
- * gnus.texi (Oort Gnus): Reorder entries in sections.
- Fix some entries.
- (Starting Up): Add references to "Emacs for Heathens" and to
- "Finding the News". Add user-full-name and user-mail-address.
- (Group Buffer Format): Add tool bar customization and update.
- (Summary Buffer): Add tool bar customization.
- (Posting Styles): Add message-alternative-emails.
-
-2006-05-12 Glenn Morris <rgm@gnu.org>
-
- * calendar.texi (Displaying the Diary, Format of Diary File):
- Refer to diary-view-entries, diary-list-entries,
- diary-show-all-entries rather than obsolete aliases.
-
-2006-05-12 Eli Zaretskii <eliz@gnu.org>
-
- * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary)
- (Displaying the Diary, Special Diary Entries, Importing Diary):
- * building.texi (Compilation Shell):
- * buffers.texi (Several Buffers) [iftex]: Replace @xref's to
- emacs-xtra with @inforef's.
-
- * files.texi (Visiting): Fix wording.
-
- * mule.texi (Coding Systems, Text Coding): More indexing.
- Mention that C-x RET f can set eol conversion.
-
-2006-05-09 Michael Albinus <michael.albinus@gmx.de>
-
- * tramp.texi (Filename completion): Improve wording.
-
-2006-05-07 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * xresmini.texi (GTK resources): Insert GTK description.
-
- * xresources.texi (GTK resources): metafont should be menufont.
-
-2006-05-07 Romain Francoise <romain@orebokech.com>
-
- * faq.texi (Using regular expressions): Fix typo.
- (Packages that do not come with Emacs): Fix capitalization.
- (Replacing text across multiple files): Expand node to explain how
- to use `dired-do-query-replace-regexp' in more detail, based on
- suggestion by Eric Hanchrow <offby1@blarg.net>.
-
-2006-05-06 Michael Albinus <michael.albinus@gmx.de>
-
- * mini.texi (Completion Options):
- * tramp.texi (Filename completion): Completion of remote files'
- method, user name and host name is active only in partial
- completion mode.
-
-2006-05-06 Bill Wohler <wohler@newt.com>
-
- Release MH-E manual version 8.0.
-
- * mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for
- release 8.0.
-
-2006-05-06 Bill Wohler <wohler@newt.com>
-
- * mh-e.texi (MH-BOOK-HOME): Change from
- http://www.ics.uci.edu/~mh/book/mh to
- http://rand-mh.sourceforge.net/book/mh.
- Replace .htm suffix with .html for MH book files.
- (Using This Manual): Update key binding for getting relevant
- chapter in Info from command key.
- (Ranges): Fix itemx.
-
-2006-05-06 Eli Zaretskii <eliz@gnu.org>
-
- * makefile.w32-in (emacs.dvi):
- * Makefile.in (emacs.dvi): Add xresmini.texi.
-
- * xresmini.texi (Table of Resources): Remove xref to non-existent
- node "LessTif Resources".
-
- * msdog.texi (Microsoft Windows):
- * calendar.texi (Calendar/Diary, Displaying the Diary)
- (Special Diary Entries, Importing Diary, Holidays):
- * programs.texi (Program Modes):
- * text.texi (Text):
- * buffers.texi (Several Buffers):
- * files.texi (Comparing Files): Fix cross-references to emacs-xtra.
-
-2006-05-06 Eli Zaretskii <eliz@gnu.org>
-
- The following changes merge the emacs-xtra manual into the main
- manual, but only for on-line version of the manual.
-
- * vc2-xtra.texi (Version Backups, Local Version Control)
- (Making Snapshots, Change Logs and VC, Version Headers)
- (Customizing VC, CVS Options) [ifnottex]: Conditional xref's for
- on-line manual.
-
- * vc1-xtra.texi (VC Dired Mode) [ifnottex]: Conditional xref's
- for on-line manual.
-
- * msdog-xtra.texi (MS-DOS, MS-DOS Keyboard, MS-DOS Mouse)
- (MS-DOS Display, MS-DOS File Names, MS-DOS Printing)
- (MS-DOS and MULE, MS-DOS Processes) [ifnottex]: Conditional xref's
- for on-line manual.
-
- * fortran-xtra.texi (Fortran, Fortran Autofill)
- (Fortran Autofill, Fortran Abbrev) [ifnottex]: Conditional xref's
- for on-line manual.
-
- * picture-xtra.texi (Basic Picture, Rectangles in Picture) [ifnottex]:
- Conditional xref's for on-line manual.
-
- * emerge-xtra.texi (Emerge, Overview of Emerge)
- (Fine Points of Emerge) [ifnottex]: Conditional xref's for on-line
- manual.
-
- * Makefile.in (INFO_TARGETS): Remove ../info/emacs-xtra.
- (EMACS_XTRA): New variable, lists the new *-xtra.texi files.
- (EMACSSOURCES): Use EMACS_XTRA.
- (../info/emacs-xtra): Remove.
- (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites.
-
- * makefile.w32-in (INFO_TARGETS): Remove $(infodir)/emacs-xtra.
- (EMACS_XTRA): New variable, lists the new *-xtra.texi files.
- (EMACSSOURCES): Use EMACS_XTRA.
- ($(infodir)/emacs-xtra): Remove.
- (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites.
-
- * trouble.texi (Quitting):
- * text.texi (Text):
- * programs.texi (Program Modes):
- * msdog.texi (Microsoft Windows):
- * frames.texi (Frames):
- * files.texi (Backup, Version Control, VC Concepts)
- (Types of Log File, Advanced C-x v v, Log Buffer, Old Versions)
- (Registering, VC Status, VC Undo, Multi-User Branching)
- (Comparing Files):
- * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary)
- (Displaying the Diary, Special Diary Entries, Importing Diary):
- * buffers.texi (Several Buffers): Replace inforef to emacs-xtra by
- conditional xref's, depending on @iftex/@ifnottex.
-
- * msdog.texi (Microsoft Windows) [ifnottex]: Add menu entry for
- "MS-DOS". @include msdog-xtra.texi.
-
- * programs.texi (Programs) [ifnottex]: Add menu entry for "Fortran".
- <Top Level> [ifnottex]: @include fortran-xtra.texi.
-
- * files.texi (Secondary VC Commands) [ifnottex]: Add menu entries
- for vc-xtra.texi subsections.
- (VC Undo) [ifnottex]: @include vc1-xtra.texi and @lowersections it.
- (Multi-User Branching) [ifnottex]: @include vc2-xtra.texi.
-
- * sending.texi (Sending Mail): A @node line without explicit Prev,
- Next, and Up links.
-
- * abbrevs.texi (Abbrevs): A @node line without explicit Prev,
- Next, and Up links.
-
- * emacs.texi (Top) [ifnottex]: Add menu entries for "Picture Mode"
- and its sections. @include picture-xtra.texi.
-
- * maintaining.texi (Maintaining) [ifnottex]: Add menu entry for
- "Emerge".
- (List Tags) [ifnottex]: @include emerge-xtra.texi.
-
- * cal-xtra.texi (Daylight Savings): Remove this node: it is an
- exact duplicate of its name-sake in calendar.texi.
-
- * calendar.texi (Calendar/Diary) [ifnottex]: Add menu item for
- "Advanced Calendar/Diary Usage".
- (Time Intervals) [ifnottex]: @include cal-xtra.texi.
-
- * dired.texi (Subdirectories in Dired) [ifnottex]: @include
- dired-xtra.texi.
- (Dired) [ifnottex]: Add menu entry for "Subdir Switches".
-
- * files.texi (Reverting) [ifnottex]: @include arevert-xtra.texi.
- (Files) [ifnottex]: Add menu entry for Autorevert.
-
- * emacs-xtra.texi (Introduction): Reword to make consistent with
- printed version only.
- <Top level>: Remove the body of all chapters and move them to the
- new *-xtra.texi files. Use @raisesections and @lowersections to
- convert sections to chapters etc.
-
- * msdog-xtra.texi:
- * fortran-xtra.texi:
- * vc-xtra.texi:
- * vc1-xtra.texi:
- * vc2-xtra.texi:
- * emerge-xtra.texi:
- * cal-xtra.texi:
- * dired-xtra.texi:
- * arevert-xtra.texi: New files, with text from respective chapters
- of emacs-xtra.texi. Convert each @chapter into @section, @section
- into @subsection, etc.
-
- * emacs-xtra.texi (MS-DOS): Renamed from "MS-DOG". All references
- updated.
-
- * msdog.texi (Microsoft Windows): Rename from "Emacs and Microsoft
- Windows". All references updated.
-
-2006-05-06 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp>
-
- * macos.texi (Mac Input): Mention input from Character Palette.
- (Mac Font Specs): Fix typo.
-
-2006-05-05 Richard Stallman <rms@gnu.org>
-
- * files.texi (Diff Mode): Minor cleanup.
-
-2006-05-05 Karl Berry <karl@gnu.org>
-
- * texinfo.tex (\definetextfonsizexi, \definetextfonsizex): New cmds.
- (\fonttextsize): New user-level command to change text font size.
- * emacs.texi: Call @fonttextsize 10, inside @tex to avoid
- errors from the current release of makeinfo (4.8).
- * help.texi (Library Keywords): Change widest word in multitable
- template from `emulations' to `convenience'. (Not sure if this is
- related to the font change.)
-
-2006-05-05 Eli Zaretskii <eliz@gnu.org>
-
- * files.texi (File Names): Add a footnote about limited support of
- ~USER on MS-Windows.
-
- * cmdargs.texi (Initial Options): Add a footnote about limited
- support of ~USER on MS-Windows.
-
-2006-05-03 Richard Stallman <rms@gnu.org>
-
- * files.texi (Diff Mode): Node moved here.
- (Comparing Files): Delete what duplicates new node.
- (Files): Put Diff Mode in menu.
-
- * misc.texi (Diff Mode): Moved to files.texi.
-
- * emacs.texi (Top): Update menu for Diff Mode.
-
- * trouble.texi (Emergency Escape): Simplify.
-
- * emacs.texi (Top): Minor clarification.
-
-2006-05-03 Teodor Zlatanov <tzz@lifelogs.com>
-
- * commands.texi, entering.texi, screen.texi: Many simplifications.
-
-2006-05-03 Richard Stallman <rms@gnu.org>
-
- * commands.texi (Text Characters): Delete paragraph about unibyte
- non-ASCII printing chars.
-
- * killing.texi (Killing): Say "graphical displays".
- * display.texi: Say "graphical displays".
-
- * cmdargs.texi (Misc X): Say "graphical displays".
-
-2006-05-01 Richard Stallman <rms@gnu.org>
-
- * emacs.texi (Top): Add Diff Mode to menu.
-
-2006-05-01 Aaron S. Hawley <Aaron.Hawley@uvm.edu>
-
- * misc.texi (Diff Mode): New node.
-
-2006-05-01 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp>
-
- * macos.texi (Mac International): Now Carbon Emacs has ATSUI support.
- (Mac Environment Variables): Shorten example line.
- (Mac Font Specs): Shorten lisp lines. Add descriptions for ATSUI.
-
-2006-05-01 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (GUD Customization): Describe cases %d and %c.
- Update description for %e.
-
-2006-04-30 Glenn Morris <rgm@gnu.org>
-
- * calendar.texi (LaTeX Calendar): Mention cal-tex-preamble-extra.
-
-2006-04-29 Dan Nicolaescu <dann@ics.uci.edu>
-
- * custom.texi (Examining): Update C-h v output example.
-
-2006-04-29 Kim F. Storm <storm@cua.dk>
-
- * building.texi (Grep Searching): Add lgrep and rgrep.
-
-2006-04-26 Reiner Steib <Reiner.Steib@gmx.de>
-
- * pgg.texi (Caching passphrase): Fix markup and typos. Simplify.
-
-2006-04-26 Sascha Wilde <wilde@sha-bang.de> (tiny change)
-
- * pgg.texi (Caching passphrase): Add pgg-gpg-use-agent.
-
-2006-04-24 Bill Wohler <wohler@newt.com>
-
- * mh-e.texi (Getting Started): Make it more explicit that you need
- to install MH. Add pointers to current MH implementations.
-
-2006-04-23 Richard Stallman <rms@gnu.org>
-
- * emacs.texi [TeX]: Use xresmini.texi instead of xresources.texi.
-
- * xresmini.texi: New file.
-
- * xresources.texi (Face Resources): Split table into font resources
- and the rest. Combine similar attributes for brevity.
-
-2006-04-21 Bill Wohler <wohler@newt.com>
-
- Release MH-E manual version 7.94.
-
- * mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for
- release 7.94.
-
-2006-04-21 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Many small fixes.
- (Handling links): Rename from "Managing links".
-
-2006-04-21 Eli Zaretskii <eliz@gnu.org>
-
- * emacs-xtra.texi (MS-DOS File Names): Remove section about
- backslashes and case-insensitivity in file names (moved to the
- main manual).
- (MS-DOS Printing): Move most of the text to the main manual.
-
- * msdog.texi (Windows Files, Windows HOME, MS-Windows Printing):
- New nodes.
- (Windows Processes, Windows System Menu): Add index entries and
- fix wording.
-
-2006-04-20 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Spam Statistics Package): Fix typo in @pxref.
- (Splitting mail using spam-stat): Fix @xref.
-
-2006-04-20 Chong Yidong <cyd@stupidchicken.com>
-
- * gnus.texi (Spam Package): Major revision of the text.
- Previouly this node was "Filtering Spam Using The Spam ELisp Package".
-
-2006-04-20 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Time stamps): Better explanation of the purpose of
- different time stamps.
- (Structure editing, Plain lists): More details on how new items
- and headings are inserted.
-
-2006-04-18 J.D. Smith <jdsmith@as.arizona.edu>
-
- * misc.texi (Shell Ring): Add notes on saved input when
- navigating off the end of the history list.
-
-2006-04-18 Chong Yidong <cyd@mit.edu>
-
- * misc.texi (Shell Options): Correct default value of
- comint-scroll-show-maximum-output.
-
-2006-04-18 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Formula syntax): Fix link to Calc Manual.
-
-2006-04-17 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Emacsen): Don't support Emacs 20.7 and XEmacs 21.1.
-
-2006-04-17 Bill Wohler <wohler@newt.com>
-
- * mh-e.texi (Folders): Update mh-before-quit-hook and
- mh-quit-hook example with code that removes the buffers rather
- than just bury them.
-
-2006-04-18 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Watch Expressions): Update.
-
-2006-04-17 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.0.53.
-
-2006-04-13 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Updating settings): New section.
- (Visibility cycling): Better names for the startup folding
- options.
- (Exporting): Completely restructured.
- (The very busy C-c C-c key): New section.
- (Summary of in-buffer settings): New section.
-
-2006-04-12 Richard Stallman <rms@gnu.org>
-
- * search.texi: Clean up previous change.
-
-2006-04-12 Eli Zaretskii <eliz@gnu.org>
-
- * search.texi (Regexp Backslash, Regexp Replace): Add index
- entries for ``back reference'' and mention the term itself in the
- text.
-
-2006-04-11 Richard Stallman <rms@gnu.org>
-
- * custom.texi (Safe File Variables):
- Document enable-local-variables = :safe.
-
-2006-04-11 Karl Berry <karl@gnu.org>
-
- * emacs-xtra.texi, emacs.texi (Dired under VC, VC Dired Commands)
- (Remote Repositories, Version Backups, Local Version Control)
- (Snapshots, Making and Using Snapshots, Snapshot Caveats)
- (Miscellaneous Commands and Features of VC, Change Logs and VC)
- (Renaming VC Work Files and Master Files)
- (Inserting Version Control Headers, Customizing VC, General Options)
- (Options for RCS and SCCS, Options specific for CVS): Move all
- these nodes to emacs-xtra.texi, for brevity.
- * cmdargs.texi, files.texi: Change cross-references.
-
-2006-04-11 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi, gnus-faq.texi, message.texi: Gnus v5.10.8 is released.
-
-2006-04-10 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Misc Group Stuff, Summary Buffer, Article Keymap)
- (Server Commands): Key `v' is reserved for users.
-
-2006-04-11 J.D. Smith <jdsmith@as.arizona.edu>
-
- * files.texi (Old Versions): Update description of vc-annotate's
- use of color to indicate date ranges.
-
-2006-04-11 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Link format): New section, emphasis on bracket links.
- (External links): Document bracket links.
- (FAQ): Expand to cover shell links and the new link format.
-
-2006-04-09 Kevin Ryde <user42@zip.com.au>
-
- * org.texi (Formula syntax): Typo in node name of calc-eval xref.
-
- * sending.texi (Mail Sending): In send-mail-function @pxref smtpmail,
- put info and printed manual names the right way around.
-
-2006-04-09 Karl Berry <karl@gnu.org>
-
- * msdog.texi, emacs-xtra.texi: Move all the MS-DOS material to
- emacs-xtra.texi, leaving only MS Windows information.
- * building.texi, emacs.texi, frames.texi, gnu.texi, macos.texi,
- * msdog.texi, mule.texi, trouble.texi: Change cross-references and
- node names.
-
- * emacs.texi: Move @summarycontents and @contents to the beginning
- of the file.
-
-2006-04-07 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Summary Buffer Lines): Add `*'.
-
-2006-04-07 Jochen K\e,A|\e(Bpper <jochen@fhi-berlin.mpg.de>
-
- * gnus.texi (Group Parameters):
- Mention gnus-permanently-visible-groups.
-
-2006-04-06 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Face): Fix typo.
-
-2006-04-05 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (X-Face): Clarify.
- (Face): Need Emacs with PNG support.
-
-2006-04-08 Kevin Ryde <user42@zip.com.au>
-
- * text.texi (Fill Commands): fill-nobreak-predicate is now a hook.
-
-2006-04-07 Richard Stallman <rms@gnu.org>
-
- * programs.texi (Comments, Comment Commands, Options for Comments)
- (Multi-Line Comments): "Align", not "indent".
- (Basic Indent): C-j deletes trailing whitespace before the newline.
-
-2006-04-06 Richard Stallman <rms@gnu.org>
-
- * idlwave.texi: Delete the blocks "not suitable for inclusion with
- Emacs".
-
- * programs.texi (Basic Indent): Clarify relationship of C-j to TAB.
-
-2006-04-06 Eli Zaretskii <eliz@gnu.org>
-
- * killing.texi (Rectangles): Add index entry for marking a rectangle.
-
-2006-04-06 J.D. Smith <jdsmith@as.arizona.edu>
-
- * idlwave.texi: Updated for IDLWAVE version 6.0, factoring out
- blocks not suitable for inclusion with Emacs using variable
- PARTOFEMACS.
-
-2006-04-05 Richard Stallman <rms@gnu.org>
-
- * emacs.texi (Top): Update subnode menu.
-
- * trouble.texi (Unasked-for Search): Node deleted.
- (Lossage): Delete from menu.
-
-2006-04-04 Richard Stallman <rms@gnu.org>
-
- * trouble.texi: Various cleanups.
- (Checklist): Don't bother saying how to snail a bug report.
- (Emergency Escape): Much rewriting.
- (After a Crash): Rename the core dump immediately.
- (Total Frustration): Call it a psychotherapist.
- (Bug Criteria): Avoid "illegal instruction".
- (Sending Patches): We always put the contributor's name in.
-
- * misc.texi (Thumbnails): Minor correction.
-
-2006-04-04 Simon Josefsson <jas@extundo.com>
-
- * gnus.texi (Security): Improve.
-
-2006-04-03 Richard Stallman <rms@gnu.org>
-
- * misc.texi (Thumbnails): Minor cleanup.
-
-2006-04-02 Karl Berry <karl@gnu.org>
-
- * sending.texi (Mail Sending): pxref to Top needs five args.
-
- * texinfo.tex: Update to current version (2006-03-21.13).
-
-2006-04-02 Bill Wohler <wohler@newt.com>
-
- * mh-e.texi (Getting Started, Junk, Bug Reports)
- (MH FAQ and Support): Fix URLs.
-
-2006-03-31 Romain Francoise <romain@orebokech.com>
-
- * gnus.texi (Virtual Groups): `nnvirtual-always-rescan' defaults
- to t, not nil (and has for the past eight years).
-
-2006-03-31 Richard Stallman <rms@gnu.org>
-
- * emacs.texi (Top): Update subnode menu.
-
- * help.texi (Help Mode): Cleanup.
-
- * dired.texi: Many cleanups.
- (Dired Deletion): Describe dired-recursive-deletes.
- (Operating on Files): dired-create-directory moved.
- (Misc Dired Features): Move to here.
- (Tumme): Node moved to misc.texi.
-
- * custom.texi: Many cleanups.
- (Minor Modes): Don't mention ISO Accents Mode.
- (Examining): Update C-h v output example.
- (Hooks): Add index and xref for add-hook.
- (Locals): Delete list of vars that are always per-buffer. Rearrange.
- (Local Keymaps): Don't mention lisp-mode-map, c-mode-map.
-
- * misc.texi: Many cleanups.
- (beginning): Add to summary of topics.
- (Shell): Put eshell xref at the end. Remove eshell from table.
- (Thumbnails): New node.
-
-2006-03-31 Reiner Steib <Reiner.Steib@gmx.de>
-
- * message.texi, gnus.texi: Bump version to 5.11.
-
-2006-03-29 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Top): Add comment about version line.
-
- * message.texi (Top): Ditto. Change to take named versions into
- account.
-
-2006-03-28 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Posting Styles): Add x-face-file to example.
- (X-Face): Refer to posting styles.
-
- * gnus-faq.texi ([5.8]): Add x-face-file.
- ([8.4]): Add links to gmane.emacs.gnus.user and
- gmane.emacs.gnus.general.
-
-2006-03-28 Eli Zaretskii <eliz@gnu.org>
-
- * files.texi (File Name Cache): Make it clear that the cache is
- not persistent.
-
-2006-03-27 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus-faq.texi: Use .invalid.
- ([5.4]): Fix gnus-posting-styles example.
-
-2006-03-27 Romain Francoise <romain@orebokech.com>
-
- * faq.texi (Emacs/W3): Rename from `w3-mode'. Mention that
- Emacs/W3 needs a new maintainer.
- (Ispell): Update author and version info.
- (Mailcrypt): Mention PGG.
- (New in Emacs 22): Add PGG to the list of new packages.
- Include minor changes from "Ramprasad B" <ramprasad_i82@yahoo.com>
- updating dead URLs.
-
-2006-03-25 Karl Berry <karl@gnu.org>
-
- * ada-mode.texi, autotype.texi, calc.texi, cc-mode.texi, cl.texi,
- * dired-x.texi, ebrowse.texi, ediff.texi, emacs-mime.texi,
- * emacs-xtra.texi, emacs.texi, erc.texi, eshell.texi, eudc.texi,
- * faq.texi, forms.texi, gnu.texi, gnus.texi, idlwave.texi,
- * info.texi, message.texi, mh-e.texi, pcl-cvs.texi, pgg.texi,
- * rcirc.texi, reftex.texi, sc.texi, ses.texi, sieve.texi,
- * speedbar.texi, url.texi, vip.texi, viper.texi, widget.texi,
- * woman.texi: (1) use @copyright{} instead of (C) in typeset text;
- (2) do not indent copyright year list (or anything else).
-
-2006-03-21 Bill Wohler <wohler@newt.com>
-
- * mh-e.texi (Folders): Various edits.
-
-2006-03-20 Romain Francoise <romain@orebokech.com>
-
- * gnus.texi (Mail Folders): Grammar fix.
-
-2006-03-21 Juanma Barranquero <lekktu@gmail.com>
-
- * files.texi (VC Dired Mode): Remove misplaced brackets.
-
-2006-03-21 Andre Spiegel <spiegel@gnu.org>
-
- * files.texi: Various updates and clarifications in the VC chapter.
-
-2006-03-19 Luc Teirlinck <teirllm@auburn.edu>
-
- * help.texi (Help Mode): Document "C-c C-c".
-
-2006-03-19 Bill Wohler <wohler@newt.com>
-
- * mh-e.texi (Replying): Document Mail-Followup-To.
- Change manually-formatted table to multitable. Add debugging info.
- Move description of mh-reply-default-reply-to into paragraph
- that describes its values.
-
-2006-03-17 Bill Wohler <wohler@newt.com>
-
- * mh-e.texi: Use smallexample and smalllisp consistenly.
- (Sending Mail Tour): Update method of entering
- addresses and subject.
- (Sending Mail Tour, Reading Mail Tour, Processing Mail Tour)
- (Adding Attachments, Searching): Update screenshots for Emacs 22.
-
-2006-03-16 Luc Teirlinck <teirllm@auburn.edu>
-
- * emacs-xtra.texi (Top): Avoid ugly continuation line in
- menu in the standalone Info reader.
-
-2006-03-15 Chong Yidong <cyd@stupidchicken.com>
-
- * emacs-xtra.texi (Emerge, Picture Mode, Fortran): New chapters,
- moved here from Emacs manual.
-
- * programs.texi (Fortran): Section moved to emacs-xtra.
- (Program Modes): Xref to Fortran in emacs-xtra.
-
- * maintaining.texi (Emerge): Move to emacs-xtra.
- * files.texi (Comparing Files): Xref to Emerge in emacs-xtra.
-
- * picture.texi: File deleted.
- * Makefile.in:
- * makefile.w32-in: Remove picture.texi.
-
- * text.texi (Text): Xref to Picture Mode in emacs-xtra.
- * abbrevs.texi (Abbrevs):
- * sending.texi (Sending Mail): Picture node removed.
-
- * emacs.texi (Top): Update node listings.
-
-2006-03-15 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Version number change only.
-
-2006-03-14 Bill Wohler <wohler@newt.com>
-
- * mh-e.texi: Add index entries around each paragraph rather than
- depend on entries from beginning of node. Doing so ensures that
- index entries are less likely to be forgotten if text is cut and
- pasted, and are necessary anyway if the references are on a
- separate page. It seems that makeinfo is now (v. 4.8) only
- producing one index entry per node, so there is no longer any
- excuse not to. Use subheading instead of heading. The incorrect
- use of heading produced very large fonts in Info--as large as the
- main heading.
- (From Bill Wohler): MH-E never did appear in Emacs 21--MH-E
- versions 6 and 7 appeared *around* the time of these Emacs releases.
-
-2006-03-13 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Clean view): Document new startup options.
-
-2006-03-12 Richard Stallman <rms@gnu.org>
-
- * calendar.texi: Various cleanups.
-
-2006-03-11 Bill Wohler <wohler@newt.com>
-
- * mh-e.texi (Preface, More About MH-E, Options, HTML, Folders)
- (Composing, Scan Line Formats): Fix @refs.
- (Getting Started): Define MH profile and MH profile components.
- (Incorporating Mail, Reading Mail, Viewing, Printing)
- (Sending Mail, Forwarding, Editing Drafts, Inserting Letter)
- (Signature, Aliases, Scan Line Formats): Use @code instead of @samp
- for string constants.
- (Tool Bar): Remove spurious quote.
- (Junk): Use ``...'' instead of "...".
- (Scan Line Formats): Replace @samp with @kbd.
-
-2006-03-11 Luc Teirlinck <teirllm@auburn.edu>
-
- * search.texi (Regexps): Use @samp for regexp that is not in Lisp
- syntax.
-
-2006-03-10 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (NoCeM): Mention gnus-use-nocem can also be a number.
-
-2006-03-10 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Fancy Mail Splitting): Improve sentences so as to be
- easy to understand.
-
-2006-03-09 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi: Markup fix.
- (Fancy Mail Splitting): Specify new feature.
-
-2006-03-08 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Fancy Mail Splitting): Improve descriptions about
- partial-words matching.
-
-2006-03-07 Reiner Steib <Reiner.Steib@gmx.de>
-
- * emacs-mime.texi (Display Customization): Reword image/.* stuff.
-
- * gnus.texi (Oort Gnus): Add note about `gnus-load'.
- (MIME Commands): Fix mm-discouraged-alternatives.
-
-2006-03-08 Luc Teirlinck <teirllm@auburn.edu>
-
- * search.texi (Regexps): More accurately describe which characters
- are special in which situations. Recommend _not_ to quote `]' or
- `-' when they are not special.
-
-2006-03-07 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Version number change only.
-
-2006-03-06 Bill Wohler <wohler@newt.com>
-
- * mh-e.texi: Move from SourceForge repository to Savannah.
- This is version 7.93, which is a total rewrite from the previous
- edition 1.3 for MH-E version 5.0.2, and corresponds to MH-E
- version 7.93.
-
-2006-03-03 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Oort Gnus): Add `mm-fill-flowed'.
-
-2006-03-01 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Interaction): Add item about `org-mouse.el' by
- Piotr Zielinski.
- (Managing links): Document that also mouse-1 can be used to
- activate a link.
- (Headlines, FAQ): Add entry about hiding leading stars.
- (Miscellaneous): Resort the sections in this chapter to a more
- logical sequence.
-
-2006-02-28 Andre Spiegel <spiegel@gnu.org>
-
- * files.texi (Old Versions): Clarify operation of C-x v =.
-
-2006-02-27 Simon Josefsson <jas@extundo.com>
-
- * emacs-mime.texi (Flowed text): Add mm-fill-flowed. (Sync
- 2004-01-27 from the trunk).
-
-2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org>
-
- * cc-mode.texi: Rename c-hungry-backspace to
- c-hungry-delete-backwards, at the request of RMS. Leave the old
- name as an alias.
-
-2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org>
-
- * cc-mode.texi: Correct the definition of c-beginning-of-defun, to
- include the function header within the defun.
-
-2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org>
-
- * cc-mode.texi: Correct two typos.
-
-2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org>
-
- * cc-mode.texi (Comment Commands): State that C-u M-; kills any
- existing comment.
- (Electric Keys): Add a justification for electric indentation.
- (Hungry WS Deletion): Clear up the names and complications of the
- BACKSPACE and DELETE keys.
-
-2006-02-23 Juri Linkov <juri@jurta.org>
-
- * faq.texi (Common requests): Move `Turning on auto-fill by
- default' after `Wrapping words automatically'. Move `Working with
- unprintable characters' before `Searching for/replacing newlines'.
- Move `Replacing highlighted text' after `Highlighting a region'.
- Merge `Repeating commands' and `Repeating a command as many times
- as possible' into the former.
- (Packages that do not come with Emacs): Add refs to Gmane and
- etc/MORE.STUFF.
-
-2006-02-23 Juri Linkov <juri@jurta.org>
-
- * faq.texi (Newsgroup archives): Update URLs of GNU mail archives.
- (Reporting bugs): Suggest using `M-x report-emacs-bug'.
- Add xref to `(emacs)Reporting Bugs'.
- (Getting a printed manual): Add URL to other formats of the manual.
- (Common requests): Fix menu.
- (Highlighting a region): Remove ref to `Turning on syntax highlighting'.
- (Horizontal scrolling): Mention `truncate-partial-width-windows'.
- (Inserting text at the beginning of each line): Add pxref to
- `Changing the included text prefix'.
- (Forcing the cursor to remain in the same column): Mention `track-eol'
- and `set-goal-column'. Add pxref to `(emacs)Moving Point'.
- (Replacing text across multiple files): Add keybinding `Q' for
- `dired-do-query-replace'.
-
-2006-02-22 Carsten Dominik <dominik@science.uva.nl>
-
- * reftex.texi: Version number and date change only.
-
- * org.texi (Internal Links): Rewrite to cover the modified
- linking system.
-
-2006-02-21 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Watch Expressions): Update and describe
- gdb-speedbar-auto-raise.
-
-2006-02-19 Richard M. Stallman <rms@gnu.org>
-
- * emacs.texi: Use @smallbook.
- (Top): Update ref to Emacs paper, delete ref to Cookbook.
- Update subnode menu.
-
- * building.texi (Lisp Interaction): Minor addition.
-
-2006-02-18 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Watch Expressions): Update and be more precise.
-
-2006-02-17 Eli Zaretskii <eliz@gnu.org>
-
- * faq.texi: Remove the coding cookie, it's not needed anymore.
-
-2006-02-15 Francesco Potort
\e,Al
\e(B <pot@gnu.org>
-
- * maintaining.texi (Create Tags Table): Explain why the
- exception when etags writes to files under the /dev tree.
-
-2006-02-14 Richard M. Stallman <rms@gnu.org>
-
- * custom.texi (Safe File Variables): Lots of clarification.
- Renamed from Unsafe File Variables.
-
-2006-02-14 Chong Yidong <cyd@stupidchicken.com>
-
- * custom.texi (Unsafe File Variables): File variable confirmation
- assumed denied in batch mode.
-
-2006-02-14 Richard M. Stallman <rms@gnu.org>
-
- * building.texi (GDB User Interface Layout): Don't say `inferior'
- for program being debugged.
-
-2006-02-15 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (GDB Graphical Interface):
- Replace gdb-use-inferior-io-buffer with gdb-use-separate-io-buffer.
-
-2006-02-13 Chong Yidong <cyd@stupidchicken.com>
-
- * custom.texi (Specifying File Variables, Unsafe File Variables):
- New nodes, split from File Variables. Document new file local
- variable behavior.
-
-2006-02-13 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp>
-
- * display.texi (Standard Faces):
- * faq.texi (Colors on a TTY):
- * files.texi (Visiting):
- * frames.texi (Clipboard):
- * glossary.texi (Glossary) <Clipboard>:
- * xresources.texi (X Resources): Mention Mac OS port.
-
-2006-02-12 Karl Berry <karl@gnu.org>
-
- * faq.texi (Emacs for Atari ST): Use Sch@"auble instead of the
- 8-bit accented a.
-
-2006-02-12 Richard M. Stallman <rms@gnu.org>
-
- * building.texi (Building): Clarify topic in intro.
-
- * maintaining.texi (Maintaining): Change title; clarify topic.
- Delete duplicate index entries.
-
- * building.texi (Other GDB User Interface Buffers): Clarifications.
-
- * text.texi (Cell Commands): Clarifications.
-
- * programs.texi (Defuns): Delete duplicate explanation of
- left-margin paren convention.
- (Hungry Delete): Minor cleanup.
-
-2006-02-11 Mathias Dahl <mathias.dahl@gmail.com>
-
- * dired.texi (Tumme): More tumme documentation.
-
-2006-02-11 Alan Mackenzie <acm@muc.de>
-
- * programs.texi ("Hungry Delete"): Correct the appellation of the
- backspace and delete keys to @kbd{DEL} and @kbd{DELETE}.
-
-2006-02-11 Mathias Dahl <mathias.dahl@gmail.com>
-
- * dired.texi (Tumme): Fix small bug.
-
-2006-02-10 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp>
-
- * macos.texi (Mac International): Rename "fontset-mac" to
- "fontset-standard".
-
-2006-02-09 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Gnus Versions): Add history beyond start of Oort.
-
-2006-02-09 Mathias Dahl <mathias.dah@gmail.com>
-
- * dired.texi (Tumme): Basic documentation for Tumme added.
-
-2006-02-08 Romain Francoise <romain@orebokech.com>
-
- * faq.texi (Top): Remove paragraph about the FAQ being a
- transitional document, etc.
- (Searching for/replacing newlines): New node.
- (Yanking text in isearch): New node.
- (Inserting text at the beginning of each line): Rename and make
- more general, mention `M-;' in Message mode.
-
-2006-02-07 Luc Teirlinck <teirllm@auburn.edu>
-
- * mule.texi (International):
- * programs.texi (Basic Indent): Fix typos.
-
- * faq.texi (Meta key does not work in xterm)
- (Emacs does not display 8-bit characters)
- (Inputting eight-bit characters):
- * custom.texi (Minor Modes):
- * display.texi (Text Display):
- * commands.texi (Text Characters): Update xrefs.
-
-2006-02-07 Richard M. Stallman <rms@gnu.org>
-
- * emacs.texi (Top): Update subnode menu.
- Update info on old Emacs papers.
- (Intro): "Graphical display", not window system.
-
- * xresources.texi (GTK styles): Minor clarifications.
-
- * trouble.texi: "Graphical display", not window system.
- (Stuck Recursive): Minor clarification.
-
- * text.texi: Minor clarifications.
- (Sentences): Explain why two-space convention is better.
- Explain sentence-end-without-period here.
- (Fill Commands): Not here.
- (Refill): Node moved down.
- (Filling): Update menu.
- (Table Creation, Cell Justification, Column Commands): Clarify.
-
- * sending.texi: Minor clarifications.
-
- * search.texi (Regexp Backslash): Clarification.
-
- * rmail.texi: Minor cleanups.
- (Rmail): Delete digression about `rmail-mode'.
- (Rmail Inbox): Delete false advice wrt rmail-primary-inbox-list.
- (Rmail Files): Mention C-u M-x rmail.
- (Rmail Reply): Mention References.
- (Rmail Display): Mention rmail-nonignored-headers.
-
- * programs.texi: Minor cleanups.
- (Comment Commands): Mention momentary Transient Mark mode.
- (Matching): Be more specific about customizing show-paren-mode.
- (Info Lookup): Don't list the modes that support C-h S.
- Just say what it does in an unsupported mode.
- (Man Page): Delete excessive info on customizing woman.
- (Motion in C): Don't mention c-for/backward-into-nomenclature.
-
- * abbrevs.texi: Minor clarifications.
- (Dabbrev Customization): Talk about "dynamic abbrev expansion",
- not "dynamic abbrevs" as if they were a kind of abbrev.
-
- * picture.texi (Picture): Minor cleanup.
-
- * mule.texi (Communication Coding): Say "other applications".
- (Fontsets): Not specific to X. Add xref to X Resources.
- (Unibyte Mode): Rename from Single-Byte Character Support.
- "Graphical display", not window system.
- (International): Update menu.
-
- * maintaining.texi (Format of ChangeLog):
- New node, split out from ChangeLog.
- (ChangeLog): Clarifications in the remaining text.
- (Create Tags Table, Etags Regexps, Select Tags Table): Cleanups.
- (Find Tag): Add @w.
- (Tags Search): Explain tag table order here. Simplify grep ref.
- (List Tags): tags-tag-face is a variable, not a face.
- (Emerge): Cleanups.
-
- * kmacro.texi (Keyboard Macro Counter): Rewrite for clarity.
- (Keyboard Macros): Avoid "the user".
-
- * killing.texi: "Graphical display", not window system.
-
- * help.texi (Help Echo): "Graphical display", not window system.
-
- * glossary.texi: Say "you", not "the user". Say "graphical display".
-
- * frames.texi: Minor cleanups. "Graphical display", not window system.
-
- * files.texi (Visiting): Make drag-and-drop not X-specific.
-
- * custom.texi: Minor cleanups. "Graphical display", not window system.
-
- * cmdargs.texi: Minor cleanups.
-
- * building.texi (Compilation): Move and split kill-compilation para.
- Add para about multiple compilers.
- (Compilation Mode): Commands also available in grep mode and others.
- Mention C-u C-x ` more tutorially. Clarify C-x `.
- (Compilation Shell): Clarify. Put Bash example first.
- (Grep Searching): Minor cleanups; add @w.
- (Debuggers): Minor cleanups.
- (Starting GUD): Make GDB xgraphical mode issue clearer.
- (Debugger Operation): Lots of clarifications including
- GDB tooltip side-effect issue.
- (Commands of GUD): Clarify.
- (GUD Customization): Add bashdb-mode-hook.
- (GDB Graphical Interface): Rewrite for clarity.
- (GDB User Interface Layout): Rewrite for clarity.
- (Stack Buffer, Watch Expressions): Likewise.
- (Other GDB User Interface Buffers): Cleanups.
- (Lisp Libraries, External Lisp): Cleanup.
-
- * basic.texi (Position Info): "Graphical displays", rather than
- window systems.
-
- * anti.texi: Minor cleanup.
-
-2006-02-06 Romain Francoise <romain@orebokech.com>
-
- * faq.texi (VM): VM now at version 7.19.
- Set myself as maintainer of this file.
-
-2006-02-04 Michael Olson <mwolson@gnu.org>
-
- * erc.texi (History): Note that ERC is now included with Emacs.
-
-2006-02-03 Eli Zaretskii <eliz@gnu.org>
-
- * custom.texi (Init File, Find Init): Add cross-references to
- where $HOME is described.
-
-2006-02-01 Luc Teirlinck <teirllm@auburn.edu>
-
- * frames.texi (Frame Parameters): Remove @item for S-Mouse-1; it
- is not inside the @table.
-
- * emacs.texi (Top): Correct node name.
-
- * files.texi (File Names): Fix @xref.
- (Reverting): Fix typo.
-
- * mule.texi (International): Correct node name.
-
- * kmacro.texi (Save Keyboard Macro): Add missing @kbd to @table.
-
-2006-02-01 Richard M. Stallman <rms@gnu.org>
-
- * emacs.texi (Top): Update subnode menu.
-
- * mule.texi: Minor clarifications.
- Reduce the specific references to X Windows.
- Refer to "graphical" terminals, rather than window systems.
- (Text Coding): Rename from Specify Coding.
- (Communication Coding, File Name Coding, Terminal Coding):
- New nodes split out from Text Coding.
-
- * kmacro.texi: Minor clarifications.
- (Keyboard Macro Ring): Comment out some excessive commands.
- (Basic Keyboard Macro): Split up the table, putting part in each node.
-
- * major.texi: Minor clarifications.
-
- * misc.texi (Single Shell, Interactive Shell): Fix xrefs.
-
- * windows.texi: Minor clarifications.
- (Change Window): Don't describe mode-line mouse cmds here.
- Add xref to Mode Line Mouse.
-
- * msdog.texi (Text and Binary, MS-DOS and MULE): Fix xrefs.
-
- * macos.texi (Mac International): Fix xref.
-
- * indent.texi: Minor clarifications.
-
- * frames.texi: Minor clarifications.
- Reduce the specific references to X Windows.
- Refer to "graphical" terminals, rather than window systems.
- (Frame Parameters): Don't mention commands like
- set-foreground-color. Just say to customize a face.
- (Drag and Drop): Lisp-level stuff moved to Emacs Lisp manual.
-
- * files.texi: Minor clarifications.
- (Numbered Backups): New node, split out from Backup Names.
-
- * display.texi (Font Lock): C mode no longer depends on (-in-col-0.
-
- * cmdargs.texi (General Variables): Fix xref.
-
- * buffers.texi: Minor clarifications.
-
-2006-01-31 Romain Francoise <romain@orebokech.com>
-
- * message.texi (Message Headers): Explain what
- `message-alternative-emails' does in more detail.
- Update copyright year.
-
-2006-01-31 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Scrolling, Horizontal Scrolling, Follow Mode):
- Nodes moved to top.
-
- * display.texi: Minor clarifications.
- (Display): Rearrange menu.
- (Standard Faces): Mention query-replace face.
- (Faces): Simplify.
- (Font Lock): Simplify face customization info.
- (Highlight Changes): Node merged into Highlight Interactively.
- (Highlight Interactively): Much rewriting and cleanup.
- (Optional Mode Line): Narrowed line number not good for goto-line.
- Simplify face customization advice.
- (Text Display): Mention use of escape-glyph face.
- Move ctl-arrow and tab-width here.
- (Display Custom): Move no-redraw-on-reenter to end of node.
-
- * search.texi: Minor clarifications.
- (Isearch Scroll): Simplify.
- (Other Repeating Search): Document multi-occur-in-matching-buffers.
-
- * regs.texi (Registers): Mention bookmarks here.
-
- * mark.texi: Minor clarifications.
- (Selective Undo): Node deleted.
-
- * m-x.texi: Minor clarifications.
-
- * killing.texi: Minor clarifications.
- Refer to "graphical" terminals, rather than window systems.
-
- * help.texi: Clarifications.
- (Help): Don't describe C-h F and C-h K here.
- (Key Help): Describe C-h K here.
- (Name Help): Mention Emacs Lisp Intro.
- Describe C-h F here.
- (Misc Help): Mention C-h F and C-h K only briefly.
-
- * fixit.texi (Undo): New node, mostly copied from basic.texi.
- Selective undo text merged in.
- (Spelling): Mention Aspell along with Ispell.
-
- * emacs.texi (Top): Update subnode menus.
-
- * basic.texi (Basic Undo): Rename from Undo. Most of text
- moved to new Undo node.
-
-2006-01-30 Juanma Barranquero <lekktu@gmail.com>
-
- * makefile.w32-in (clean): Add newsticker, sieve, pgg, erc and rcirc.
-
-2006-01-29 Chong Yidong <cyd@stupidchicken.com>
-
- * basic.texi (Continuation Lines, Inserting Text):
- Mention longlines mode.
-
-2006-01-29 Richard M. Stallman <rms@gnu.org>
-
- * screen.texi: Minor cleaups.
- (Screen): Clean up the intro paragraphs.
- (Mode Line): Lots of rewriting. Handle frame-name better.
- eol-mnemonic-... vars moved out.
-
- * emacs.texi (Top): Change menu item for MS-DOS node.
- Update subnode menu.
-
- * msdog.texi (MS-DOS): Rewrite intro to explain how this
- chapter relates to Windows. Title changed.
-
- * mini.texi: Minor cleanups.
-
- * mark.texi (Selective Undo): New node, text moved from basic.texi.
- (Mark): Put it in the menu.
-
- * entering.texi: Minor cleanups.
-
- * emacs.texi (Top): Add xref to Mac chapter; explain Windows better.
- (Intro): Refer to "graphical" terminals, rather than X.
-
- * display.texi (Display Custom): Add xref to Variables.
- (Optional Mode Line): eol-mnemonic-... vars moved here.
-
- * commands.texi: Minor cleanups. Refer to "graphical" terminals,
- rather than X.
-
- * cc-mode.texi (Indentation Commands): Inserts newline, not "linefeed".
-
- * basic.texi: Minor cleanups.
- (Undo): selective-undo moved.
-
-2006-01-29 Michael Olson <mwolson@gnu.org>
-
- * makefile.w32-in ($(infodir)/erc, erc.dvi): New targets.
-
- * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add ERC.
-
- * faq.texi (New in Emacs 22): Mention ERC.
-
-2006-01-28 Luc Teirlinck <teirllm@auburn.edu>
-
- * rcirc.texi: Capitalize dir entry for consistency with the entry
- in info/dir and other entries in the Emacs category.
- Fix typos. Delete trailing whitespace.
-
-2006-01-28 Bj\e,Av\e(Brn Lindstr\e,Av\e(Bm <bkhl@elektrubadur.se>
-
- * rcirc.texi: Some @cindex changes, some changes from @kbd to @key.
-
-2006-01-27 Eli Zaretskii <eliz@gnu.org>
-
- * makefile.w32-in ($(infodir)/rcirc, rcirc.dvi): New targets.
- (INFO_TARGETS, DVI_TARGETS): Add rcirc.
-
- * Makefile.in (../info/rcirc, rcirc.dvi): New targets.
- (INFO_TARGETS, DVI_TARGETS): Add rcirc.
-
-2006-01-27 Alex Schroeder <alex@gnu.org>
-
- * rcirc.texi: New file.
-
-2006-01-25 Luc Teirlinck <teirllm@auburn.edu>
-
- * anti.texi (Antinews): Various corrections and additions.
-
-2006-01-23 Juri Linkov <juri@jurta.org>
-
- * custom.texi (Easy Customization, Customization Groups)
- (Browsing Custom): Mention links along with buttons.
-
- * widget.texi (User Interface): Add S-TAB for widget-backward.
-
-2006-01-22 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.0.52.
-
- * tramp.texi (Frequently Asked Questions): Remove Ange-FTP item.
- Add Tramp disabling item. New item for common connection problems.
- (various): Apply "ftp" as method for the download URL.
- (Bug Reports): Refer to FAQ for common problems.
-
-2006-01-21 Eli Zaretskii <eliz@gnu.org>
-
- * widget.texi (User Interface): Use @key for TAB.
-
- * text.texi (TeX Print): Use @key for TAB.
-
- * ses.texi (Formulas, Printer functions): Use @key for TAB.
-
- * kmacro.texi (Keyboard Macro Step-Edit): Use @key for TAB.
-
- * ebrowse.texi (Switching to Tree, Symbol Completion): Use @key
- for TAB.
-
- * cc-mode.texi (Indentation Calculation): Use @key for TAB.
-
-2006-01-15 Sven Joachim <svenjoac@gmx.de> (tiny change)
-
- * files.texi (File Aliases): Don't claim that usually separate
- buffers are created for two file names that name the same data.
- Mention additional situations where different names mean the same
- file on disk.
-
-2006-01-19 Richard M. Stallman <rms@gnu.org>
-
- * killing.texi (Deletion): Upcase @key argument.
-
- * custom.texi (Custom Themes): Minor cleanup.
-
- * programs.texi (Hungry Delete): Upcase @key argument.
-
-2006-01-16 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi: Update copyright.
-
-2006-01-16 Juri Linkov <juri@jurta.org>
-
- * display.texi (Standard Faces): Add `mode-line-buffer-id'.
- Move `mode-line-highlight' before `mode-line-buffer-id'.
-
-2006-01-13 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Article Washing): Additions.
-
-2006-01-08 Alex Schroeder <alex@gnu.org>
-
- * pgg.texi (Caching passphrase): Rewording.
-
-2006-01-14 Richard M. Stallman <rms@gnu.org>
-
- * basic.texi (Inserting Text): Minor cleanup.
-
-2006-01-13 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Agenda commands): Document tags command.
-
-2006-01-11 Luc Teirlinck <teirllm@auburn.edu>
-
- * custom.texi (Changing a Variable, Face Customization):
- Update for changes in Custom menus.
-
-2006-01-10 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (RSS): Document nnrss-wash-html-in-text-plain-parts.
-
-2006-01-06 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (RSS): Addition.
-
-2005-12-22 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Summary Post Commands): Fix function bound to `S O p'.
-
-2005-12-19 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * emacs-mime.texi (Display Customization): Add setting example to
- mm-discouraged-alternatives.
-
-2006-01-09 Stefan Monnier <monnier@iro.umontreal.ca>
-
- * flymake.texi (Obtaining Flymake): Remove chapter since Emacs's
- version is the canonical version.
-
-2006-01-08 Alex Schroeder <alex@gnu.org>
-
- * pgg.texi (Caching passphrase): Rewording.
-
-2006-01-06 Eli Zaretskii <eliz@gnu.org>
-
- * flymake.texi (Obtaining Flymake): Update Flymake's CVS
- repository URL.
-
-2006-01-06 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Removed the accidentally re-added empty line in the
- direntry.
-
-2006-01-05 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp>
-
- * macos.texi (Mac International): Undo last change.
-
-2006-01-05 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Agenda Views): Chapter reorganized.
-
-2006-01-02 Chong Yidong <cyd@stupidchicken.com>
-
- * custom.texi (Custom Themes): Describe the new
- customize-create-theme interface.
-
-2005-12-30 Juri Linkov <juri@jurta.org>
-
- * basic.texi (Position Info): Update example.
-
-2005-12-29 Romain Francoise <romain@orebokech.com>
-
- * faq.texi (Using Customize): New node.
-
-2005-12-28 Luc Teirlinck <teirllm@auburn.edu>
-
- * org.texi: Remove blank line in @direntry. It is non-standard
- and recursively produces blank lines all over the dir file (when
- using Texinfo 4.8).
-
-2005-12-27 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * frames.texi (Dialog Boxes): Add x-gtk-show-hidden-files.
-
-2005-12-24 Chong Yidong <cyd@stupidchicken.com>
-
- * custom.texi (Custom Themes): `load-theme' always loads.
-
-2005-12-23 Juri Linkov <juri@jurta.org>
-
- * display.texi (Highlight Interactively): Use double space to
- separate sentences. Replace C-p with M-p, and C-n with M-n.
-
-2005-12-22 Richard M. Stallman <rms@gnu.org>
-
- * custom.texi (Easy Customization and subnodes):
- Replace "active field" with "button".
- Use "user option" only for variables.
- Use "setting" for variable-or-face.
-
-2005-12-22 Luc Teirlinck <teirllm@auburn.edu>
-
- * buffers.texi (Select Buffer): Change order in table to make
- "Similar" refer to the correct item.
- (Indirect Buffers): Minor rewording.
-
-2005-12-21 Luc Teirlinck <teirllm@auburn.edu>
-
- * widget.texi (atoms): Delete obsolete remark about `file' widget.
-
-2005-12-20 Juri Linkov <juri@jurta.org>
-
- * files.texi (VC Status): Put P and N near p and n.
-
-2005-12-20 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Tags): Boolean logic documented.
- (Agenda Views): Document custom commands.
-
-2005-12-20 David Kastrup <dak@gnu.org>
-
- * faq.texi (AUCTeX): Update version and mailing list info.
-
-2005-12-19 Richard M. Stallman <rms@gnu.org>
-
- * programs.texi (Electric C): Delete the info about newline control.
- (Other C Commands): Minor cleanup.
- (Left Margin Paren): Minor cleanup.
-
-2005-12-19 Luc Teirlinck <teirllm@auburn.edu>
-
- * custom.texi (Easy Customization): Add "Browsing Custom" to menu.
- (Customization Groups): Delete text moved to "Browsing Custom".
- (Browsing Custom): New node.
- (Specific Customization): Clarify which commands only work for
- loaded options.
-
-2005-12-18 Bill Wohler <wohler@newt.com>
-
- * frames.texi (Tool Bars): Shorten text of previous change.
-
-2005-12-18 Aaron S. Hawley <Aaron.Hawley@uvm.edu>
-
- * files.texi (VC Status): Document log-view mode.
-
-2005-12-18 Bill Wohler <wohler@newt.com>
-
- * frames.texi (Tool Bars): Mention that you can turn off tool bars
- permanently via the customize interface.
-
-2005-12-17 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (MIME Commands): Mention addition of
- multipart/alternative to gnus-buttonized-mime-types and add xref
- to mm-discouraged-alternatives.
-
- * emacs-mime.texi (Display Customization): Mention addition of
- "image/.*" and add xref to gnus-buttonized-mime-types in the
- mm-discouraged-alternatives section.
-
-2005-12-16 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Tags): New section.
- (Agenda Views): Chapter reorganized.
-
-2005-12-16 Ralf Angeli <angeli@iwi.uni-sb.de>
-
- * killing.texi (Killing by Lines): Document `kill-whole-line'
- function.
-
-2005-12-16 Eli Zaretskii <eliz@gnu.org>
-
- * org.texi (Internal Links): Add a missing comma after an @xref.
-
-2005-12-16 L\e$,1 q\e(Brentey K\e,Aa\e(Broly <lorentey@elte.hu>
-
- * buffers.texi (Select Buffer): Change `prev-buffer' to
- `previous-buffer'. Indicate that these functions use a frame
- local buffer list.
-
-2005-12-14 Chong Yidong <cyd@stupidchicken.com>
-
- * faq.texi (Filling paragraphs with a single space): No need to
- change sentence-end now.
-
-2005-12-13 Romain Francoise <romain@orebokech.com>
-
- * faq.texi (Scrolling only one line): Use `scroll-conservatively'.
-
-2005-12-12 Jay Belanger <belanger@truman.edu>
-
- * faq.texi (Calc): Update version number.
-
-2005-12-12 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Progress Logging): New section.
-
-2005-12-12 Richard M. Stallman <rms@gnu.org>
-
- * custom.texi (Easy Customization): Change menu comment.
- (Prefix Keymaps): Fix spelling of Control-X-prefix.
-
- * help.texi (Apropos): Rewrite. Talk about "apropos patterns".
- (Help): Among the Apropos commands, describe only C-h a here.
-
-2005-12-11 Richard M. Stallman <rms@gnu.org>
-
- * programs.texi (Options for Comments): Comment-end starts with space.
-
- * glossary.texi (Glossary): Minor cleanup.
-
- * files.texi (Old Versions): Use @table.
-
-2005-12-10 Romain Francoise <romain@orebokech.com>
-
- Update the Emacs FAQ for the 22.1 release.
-
- * faq.texi: Set VER to `22.1'.
- (Basic editing): Explain how to use localized versions of the
- Tutorial. Mention that `C-h r' displays the manual. Delete
- obsolete WWW link to an Emacs 18 tutorial.
- (Getting a printed manual): Point to the new locations of the
- manuals on the GNU Web site.
- (Emacs Lisp documentation): Explain that the Emacs Lisp manual is
- available via Info (it was previously distributed separately).
- (Installing Texinfo documentation): The latest version of Texinfo
- is 4.8, not 4.0.
- (Informational files for Emacs): COPYING is the GNU General Public
- License, not the Emacs General Public License.
- (Informational files for Emacs): Delete obsolete link to the
- GNUinfo pages as they have been removed from the GNU Web site.
- (New in Emacs 22): New node.
- (Setting up a customization file): Say that most packages support
- Customize nowadays.
- (Colors on a TTY): Delete reference to instructions on how to
- enable syntax highlighting, it is now enabled by default.
- (Turning on abbrevs by default): Emacs now reads the abbrevs file
- at startup automatically.
- (Controlling case sensitivity): Mention `M-c' in isearch.
- (Using an already running Emacs process): Emacs now creates the
- socket in `/tmp/emacsUID'. Fix typos. Change default location of
- gnuserv. As emacsclient can now run Lisp code as well, delete a
- sentence praising gnuserv for that. Simplify description of how
- the client/server operation works.
- (Compiler error messages): Delete obsolete text (compile.el has
- been rewritten).
- (Indenting switch statements): Fix typo.
- (Matching parentheses): Simplify setup instructions, mention the
- menu bar item in the Options menu.
- (Repeating a command as many times as possible): Mention `C-x e'.
- (Going to a line by number): Mention new keymap and bindings
- `M-g M-g', `M-g M-p' and `M-g M-n'.
- (Turning on syntax highlighting): Now on by default. Simplify.
- (Replacing highlighted text): Use `1', not `t'.
- (Problems with very large files): The maximum size is now 256MB on
- 32-bit machines.
- (^M in the shell buffer): Mention `comint-process-echoes'.
- (Emacs for Apple computers): Emacs 22 has native support for Mac
- OS X.
- (Translating names to IP addresses): Delete node.
- (Binding keys to commands): Fix typo.
- (SPC no longer completes file names): New node.
- (MIME with Emacs mail packages): Delete section about the Emacs
- MIME FAQ (it's not reachable anymore).
-
-2005-12-10 David Koppelman <koppel@ece.lsu.edu>
-
- * display.texi (Highlight Interactively): Include
- global-hi-lock-mode. Add miscellaneous details and elaborations.
-
-2005-12-09 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Font Lock): Delete the Global FL menu item.
-
-2005-12-09 Luc Teirlinck <teirllm@auburn.edu>
-
- * custom.texi (Minibuffer Maps): Mention the maps for file name
- completion.
-
-2005-12-09 Kim F. Storm <storm@cua.dk>
-
- * killing.texi (CUA Bindings): Describe how to use C-x and C-c as
- prefix keys even when mark is active. Decribe that RET moves
- cursor to next corner in rectangle; clarify insert around rectangle.
-
-2005-12-08 Alan Mackenzie <bug-cc-mode@gnu.org>
-
- * cc-mode.texi: The manual has been extensively revised: the
- information about using CC Mode has been separated from the larger
- and more difficult chapters about configuration. It has been
- updated for CC Mode 5.31.
-
-2005-12-05 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * pgg.texi (User Commands): Fix description of pgg-verify-region.
- (Selecting an implementation): Fix descriptions.
-
-2005-11-30 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * message.texi (Various Message Variables): Addition.
-
-2005-11-29 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * message.texi: Fix default values.
-
-2005-11-25 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * message.texi (Header Commands): Clarify descriptions of
- message-cross-post-followup-to, message-reduce-to-to-cc, and
- message-insert-wide-reply.
- (Various Commands): Fix kindex for message-kill-to-signature;
- clarify description of message-tab.
-
-2005-11-22 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * message.texi (Mailing Lists): Fix description about MFT.
-
- * gnus.texi (Emacs Lisp): Use ~/.gnus.el instead of ~/.emacs.
-
-2005-11-17 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Slow Terminal Connection): Replace old description
- with new one.
-
-2005-11-16 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Oort Gnus): Use ~/.gnus.el instead of ~/.emacs;
- replace X-Draft-Headers with X-Draft-From.
-
-2005-11-14 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Various Various): Fix the default value of
- nnheader-max-head-length.
- (Gnus Versions): Fix typo.
-
-2005-12-08 Luc Teirlinck <teirllm@auburn.edu>
-
- * custom.texi (Customization): Use xref to elisp manual for
- non-TeX output.
- (Minor Modes): Update.
- (Customization Groups, Changing a Variable, Face Customization):
- Update for new appearance of Custom buffers.
- (Changing a Variable): `custom-buffer-done-function' has been
- replaced by `custom-buffer-done-kill'.
- (Specific Customization): In the `customize-group' buffer, a
- subgroup's contents are not "hidden". They are not included at
- all. They have no [Show] button.
- (Mouse Buttons): Add pxref to description of mouse event lists in
- Elisp manual. Add `menu-bar' and `header-line' dummy prefix keys.
- (Find Init): Emacs now looks for ~/.emacs.d/init.el instead of
- ~/.emacs.d/.emacs, if it can not find ~/.emacs(.el).
-
-2005-12-08 Richard M. Stallman <rms@gnu.org>
-
- * mini.texi (Completion Commands, Completion):
- In file name input, SPC does not do completion.
-
-2005-12-08 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Structure editing): Document new functionality of
- M-RET.
-
-2005-12-08 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (GDB Graphical Interface): Explain screen size
- setting.
- (Other GDB User Interface Buffers): Describe features specific to
- GDB 6.4.
-
-2005-12-06 Luc Teirlinck <teirllm@auburn.edu>
-
- * org.texi (Internal Links): Fix Texinfo usage.
-
-2005-12-06 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (TODO basics): Document the global todo list.
- (TODO items): Documents sparse tree for specific TODO
- keywords.
-
-2005-12-01 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (GDB User Interface Layout): Describe how to
- kill associated buffers.
- (Breakpoints Buffer): Use D instead of d for gdb-delete-breakpoint.
- (Watch Expressions): Be more precise.
- (Other GDB User Interface Buffers): Describe how to change a
- register value.
-
-2005-11-30 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Plain Lists): Typos fixed.
-
-2005-11-28 Jay Belanger <belanger@truman.edu>
-
- * calc.texi: Change references of `M-#' to `C-x *' prefix.
-
-2005-11-24 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Structure editing): New item moving commands added.
- (Plain Lists): New section.
-
-2005-11-24 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp>
-
- * macos.texi (Mac Input): Remove description of
- mac-command-key-is-meta. Add descriptions of
- mac-control-modifier, mac-command-modifier, and
- mac-option-modifier.
- (Mac International): Fix description of conversion of clipboard data.
- (Mac Font Specs): Add example of font customization by face attributes.
-
-2005-11-22 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Watch Expressions): Expand description.
- (Other GDB User Interface Buffers): Describe local map for
- gud-watch.
-
-2005-11-21 Chong Yidong <cyd@stupidchicken.com>
-
- * display.texi (Font Lock): Font lock is enabled by default now.
-
-2005-11-20 Juri Linkov <juri@jurta.org>
-
- * basic.texi (Position Info): Update examples of the output.
- Remove the fact that examples are produced in the TeXinfo buffer,
- because in the Info reader users will get a different output from
- `C-x ='.
-
- * building.texi (Compilation Mode): Remove paragraph duplicated
- from the node `Compilation'. Add `compilation-skip-threshold'.
-
- * display.texi (Font Lock): Suggest more user-friendly method of
- finding all Font Lock faces (M-x customize-group RET font-lock-faces).
-
-2005-11-18 Richard M. Stallman <rms@gnu.org>
-
- * files.texi (Registering): Mention @@ in mode line.
-
- * mini.texi (Minibuffer File): Clarify previous change. Add @findex.
-
-2005-11-08 Aaron S. Hawley <Aaron.Hawley@uvm.edu>
-
- * files.texi (Renaming and VC): Some back-ends don't
- handle renaming.
-
-2005-11-18 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (FAQ): Document `org-table-tab-jumps-over-hlines'.
- (Agenda): Document commands `org-cycle-agenda-files' and
- `org-agenda-file-to-front'
- (Built-in table editor): Document `org-table-sort-lines'.
- (HTML formatting): Export of hand-formatted lists.
-
-2005-11-17 Juri Linkov <juri@jurta.org>
-
- * emacs.texi (Top):
- * display.texi (Highlight Interactively): Put this font-lock based
- mode near Font Lock node.
-
-2005-11-16 Chong Yidong <cyd@stupidchicken.com>
-
- * ack.texi (Acknowledgments): Acknowledge Andrew Zhilin for Emacs
- icons.
-
-2005-11-12 Kim F. Storm <storm@cua.dk>
-
- * help.texi (Help): Fix C-h a entry. Add C-h d entry.
- (Help Summary): Add C-h d and C-h e.
- (Apropos): Clarify that all apropos commands may search for either
- list of words or a regexp. Add C-h d for apropos-documentation.
- Describe apropos-documentation-sort-by-scores user option.
-
-2005-11-10 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (XVarious): Fix description of gnus-use-toolbar; add
- new variable gnus-toolbar-thickness.
-
-2005-11-08 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (XVarious): Revert description of gnus-use-toolbar.
-
-2005-11-07 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (X-Face): Fix description.
- (XVarious): Remove gnus-xmas-logo-color-alist and
- gnus-xmas-logo-color-style; fix description of gnus-use-toolbar.
-
-2005-11-01 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Group Parameters): Mention new variable
- gnus-parameters-case-fold-search.
- (Home Score File): Addition.
-
-2005-11-09 Luc Teirlinck <teirllm@auburn.edu>
-
- * killing.texi (CUA Bindings): Add @section.
-
-2005-11-10 Kim F. Storm <storm@cua.dk>
-
- * emacs.texi (Top): Add CUA Bindings entry to menu.
-
- * killing.texi (CUA Bindings): New node. Moved here from
- misc.texi and extended with info on rectangle commands and
- rectangle highlighting, interface to registers, and the global
- mark feature.
-
- * misc.texi (Emulation): Move CUA bindings item to killing.texi.
-
- * regs.texi: Prev link points to CUA Bindings node.
-
-2005-11-07 Luc Teirlinck <teirllm@auburn.edu>
-
- * help.texi (Help Echo): By default, help echos are only shown on
- mouse-over, not on point-over.
-
-2005-11-04 J\e,Ai\e(Br\e,At\e(Bme Marant <jerome@marant.org>
-
- * misc.texi (Shell Mode): Describe how to activate password echoing.
-
-2005-11-04 Ulf Jasper <ulf.jasper@web.de>
-
- * newsticker.texi: VERSION changed to 1.9. Updated UPDATED.
- (Overview): List supported feed types.
- (Installation): No installation necessary when using autoload.
- (Configuration): Rename "RSS" to "news".
-
-2005-11-04 Ken Manheimer <ken.manheimer@gmail.com>
-
- * pgg.texi (User Commands): Document additional passphrase
- argument for pgg-encrypt-*, pgg-decrypt-*, and pgg-sign-* functions.
- (Backend methods): Likewise for corresponding pgg-scheme-* functions.
-
-2005-11-04 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Version number changed to 3.19.
-
-2005-11-04 Romain Francoise <romain@orebokech.com>
-
- * mark.texi (Mark Ring): Fix typo.
-
-2005-11-03 Richard M. Stallman <rms@gnu.org>
-
- * mark.texi (Mark Ring): Mention set-mark-command-repeat-pop.
-
-2005-11-01 Bill Wohler <wohler@newt.com>
-
- * help.texi (Help Mode): Fix typo.
-
-2005-11-01 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Other GDB User Interface Buffers): Describe
- the command gdb-use-inferior-io-buffer.
-
-2005-10-31 Romain Francoise <romain@orebokech.com>
-
- * files.texi (Compressed Files): Fix typo.
-
- * buffers.texi (Misc Buffer): Downcase `*shell*'.
-
- * windows.texi (Force Same Window): Likewise.
-
-2005-10-30 Bill Wohler <wohler@newt.com>
-
- * help.texi (Help Mode): URLs viewed with browse-url.
-
-2005-10-31 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (GDB Graphical Interface): Don't reference
- gdb-mouse-set-clear-breakpoint. Explain gdb-mouse-until
- must stay in same frame.
-
-2005-10-29 Chong Yidong <cyd@stupidchicken.com>
-
- * custom.texi (Init File): Document ~/.emacs.d/init.el.
-
- * anti.texi (Antinews): Likewise.
-
-2005-10-29 Sascha Wilde <wilde@sha-bang.de>
-
- * pgg.texi (How to use): Update the example to add autoload of
- pgg-encrypt-symmetric-region.
- (User Commands): Document pgg-encrypt-symmetric-region.
- (Backend methods): Document pgg-scheme-encrypt-symmetric-region.
-
-2005-10-28 Bill Wohler <wohler@newt.com>
-
- * help.texi (Help): Help mode now creates hyperlinks for URLs.
-
-2005-10-28 Richard M. Stallman <rms@gnu.org>
-
- * files.texi (Visiting): Explain how to enter ? in a file name.
-
- * trouble.texi (Memory Full): Mention !MEM FULL! in mode line.
-
-2005-10-27 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Predefined Units): Fix the symbol for a TeX points,
- mention other TeX-related units.
-
-2005-10-25 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (GDB Graphical Interface): Describe
- gdb-mouse-until.
-
-2005-10-23 Richard M. Stallman <rms@gnu.org>
-
- * custom.texi (Init File): Recommend when to use site-start.el.
-
-2005-10-23 Lars Hansen <larsh@soem.dk>
-
- * dired-x.texi (Miscellaneous Commands): Replace
- dired-do-relative-symlink by dired-do-relsymlink and
- dired-do-relative-symlink-regexp by dired-do-relsymlink-regexp.
-
-2005-10-23 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Predefined Units): Use `alpha' for the fine structure
- constant.
-
-2005-10-23 Michael Albinus <michael.albinus@gmx.de>
-
- * faq.texi (Bugs and problems): Replace
- `dired-move-to-filename-regexp' by
- `directory-listing-before-filename-regexp'.
-
-2005-10-22 Eli Zaretskii <eliz@gnu.org>
-
- * newsticker.texi (UPDATED): Set value.
-
-2005-10-17 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Document Groups): Remove duplicate item.
-
-2005-10-21 Juri Linkov <juri@jurta.org>
-
- * custom.texi (Examining): Mention accessing the old variable
- value via M-n in set-variable.
-
-2005-10-21 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Summary): Mention iCalendar support.
- (Exporting): Document iCalendar support.
-
-2005-10-18 Romain Francoise <romain@orebokech.com>
-
- * files.texi (Version Systems): Capitalize GNU.
-
- * viper.texi (Viper Specials): Likewise.
-
-2005-10-18 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Compilation Mode): Remove redundant paragraph.
- (Watch Expressions): Remove paragraph to reflect code change.
-
-2005-10-17 Juri Linkov <juri@jurta.org>
-
- * info.texi (Getting Started, Search Index, Expert Info):
- Fix wording.
- (Search Text): Replace `echo area' with `mode line'.
- (Search Index): Both `i' and `,' find all index entries.
- Replace example `C-f' with `C-l' (which exists in index of Info
- manual) and delete spaces in its keyboard input sequence.
- Delete unnecessary explanations about literal characters.
-
-2005-10-16 Richard M. Stallman <rms@gnu.org>
-
- * building.texi (Compilation Mode, Compilation): Clarified.
-
-2005-10-15 Richard M. Stallman <rms@gnu.org>
-
- * misc.texi (Saving Emacs Sessions): Mention savehist library.
-
-2005-10-14 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Document Server Internals): Addition.
-
-2005-10-13 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (A note on namespaces): Fix RFC reference.
-
-2005-10-12 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (RSS): Fix key description.
-
-2005-10-11 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi: Emacs/w3 -> Emacs/W3.
- (Browsing the Web): Fix description.
- (Web Searches): Ditto.
- (Customizing W3): Ditto.
-
-2005-10-07 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Maildir): Clarify expire-age and expire-group.
-
-2005-10-13 Kenichi Handa <handa@m17n.org>
-
- * basic.texi (Position Info): Fix previous change.
-
-2005-10-12 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * cmdargs.texi (Icons X): Fix typo.
-
-2005-10-12 Kenichi Handa <handa@m17n.org>
-
- * basic.texi (Position Info): Describe the case that Emacs shows
- "part of display ...".
-
-2005-10-11 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Integration): Mention using `a i' to compute definite
- integrals.
-
-2005-10-11 Juri Linkov <juri@jurta.org>
-
- * info.texi: Rearrange nodes.
- (Top): Update menu. Change ref `Info for Experts' to
- `Advanced Info Commands'.
- (Getting Started): Fix description of manual's parts.
- (Help-Int): Change xref `Info Search' to `Search Index', and
- `Expert Info' to `Advanced'.
- (Advanced): Move node one level up.
- (Search Text, Search Index): New nodes split out from `Info Search'.
- (Go to node, Choose menu subtopic, Create Info buffer): New nodes
- split out from `Advanced'.
- (Advanced, Emacs Info Variables): De-document editing an Info file
- in Info.
- (Emacs Info Variables): Move node from `Expert Info' to `Advanced'.
- (Creating an Info File): Delete node and move its text to
- `Expert Info'.
-
-2005-10-10 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * cmdargs.texi (Icons X): -nb => -nbi.
-
-2005-10-10 Chong Yidong <cyd@stupidchicken.com>
-
- * frames.texi (Speedbar): A couple more clarifications.
-
-2005-10-11 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (GDB User Interface Layout): Improve diagram.
- (Watch Expressions): Explain how to make speedbar global.
- (Other GDB User Interface Buffers): Make references more precise.
-
-2005-10-10 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi (Workflow states): Documented that change in keywords
- becomes active only after restart of Emacs.
-
-2005-10-09 Richard M. Stallman <rms@gnu.org>
-
- * frames.texi (Speedbar): Clarify the text.
-
-2005-10-09 Chong Yidong <cyd@stupidchicken.com>
-
- * frames.texi (Speedbar): Add information on keybindings,
- dismissing the speedbar, and buffer display mode. Link to
- speedbar manual.
-
-2005-10-09 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * cmdargs.texi (Icons X): Removed options -i, -itype, --icon-type,
- added -nb, --no-bitmap-icon.
-
-2005-10-08 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.0.51.
-
-2005-10-08 Nick Roberts <nickrob@snap.net.nz>
-
- * speedbar.texi (Introduction): Describe new location of speedbar
- on menubar.
- (Basic Key Bindings): Remove descriptions of bindings that have
- been removed.
-
-2005-10-07 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (GDB Graphical Interface): Add variables and
- functions to indices. Be more precise.
-
-2005-10-05 Nick Roberts <nickrob@snap.net.nz>
-
- * speedbar.texi (GDB): Describe use of watch expressions.
-
-2005-10-03 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * frames.texi (Drag and Drop): Remove the x- from
- x-dnd-open-file-other-window and xdnd-protocol-alist.
-
-2005-09-30 Romain Francoise <romain@orebokech.com>
-
- * mini.texi (Minibuffer): The default value now appears before the
- colon in minibuffer prompts.
-
-2005-09-28 Simon Josefsson <jas@extundo.com>
-
- * message.texi (IDNA): Fix.
-
-2005-09-28 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (NNTP): Remove nntp-buggy-select, nntp-read-timeout,
- nntp-server-hook, and nntp-warn-about-losing-connection; fix
- description of nntp-open-connection-function.
- (Common Variables): Fix descriptions.
-
-2005-09-26 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Server Buffer Format): Document the %a format spec.
-
-2005-09-25 Richard M. Stallman <rms@gnu.org>
-
- * search.texi (Regexp Search): Doc search-whitespace-regexp.
-
-2005-09-22 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Mail): Fix gnus-confirm-mail-reply-to-news entry.
-
-2005-09-20 Emanuele Giaquinta <emanuele.giaquinta@gmail.com> (tiny change)
-
- * text.texi (Paragraphs): Correction about Paragraph-Indent Text mode.
-
-2005-09-23 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi Version 3.16.
-
-2005-09-21 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp>
-
- * emacs.texi (Top): Update submenus from macos.texi.
-
- * macos.texi: Change `Mac OS 8 or 9' to `Mac OS Classic'.
- (Mac OS): Update feature support status.
- (Mac Input): List supported input scripts. Remove description
- about `mac-keyboard-text-encoding'. Mention mouse button
- emulation and related variables.
- (Mac International): Mention Central European and Cyrillic
- support. Now `keyboard-coding-system' is dynamically changed.
- Add description about coding system for selection. Add
- description about language environment.
- (Mac Environment Variables): Mention
- `~/.MacOSX/environment.plist'. Give example of command line
- arguments. Add Preferences support.
- (Mac Directories): Explicitly state that this node is for Mac OS
- Classic only.
- (Mac Font Specs): Mention specification for scalable fonts. List
- supported charsets. Add preferred way of creating fontsets. Add
- description about `mac-allow-anti-aliasing'.
- (Mac Functions): Add descriptions about `mac-set-file-creator',
- `mac-get-file-creator', `mac-set-file-type', `mac-get-file-type',
- and `mac-get-preference'.
-
-2005-09-19 Miles Bader <miles@gnu.org>
-
- * newsticker.texi: Get rid of CVS keywords.
-
-2005-09-15 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Finding the Parent): Fix description of how Gnus
- finds article.
-
-2005-09-14 Jari Aalto <jari.aalto@cante.net>
-
- * gnus.texi (Advanced Scoring Examples): New examples to teach how
- to drop off non-answered articles.
-
-2005-09-19 Juanma Barranquero <lekktu@gmail.com>
-
- * makefile.w32-in (newsticker.dvi): Use parentheses instead of curly
- braces (which are unsupported by NMAKE) for macro `srcdir'.
-
-2005-09-17 Eli Zaretskii <eliz@gnu.org>
-
- * makefile.w32-in (INFO_TARGETS, DVI_TARGETS): Add newsticker targets.
- (../info/newsticker, newsticker.dvi): New targets.
-
-2005-09-17 Ulf Jasper <ulf.jasper@web.de>
-
- * newsticker.texi: Replace @command with @code. Replace @example
- with @lisp.
- (Top): Added explanations to menu items.
- (GNU Free Documentation License): Removed.
-
-2005-09-16 Romain Francoise <romain@orebokech.com>
-
- Update all files to specify GFDL version 1.2.
-
- * doclicense.texi (GNU Free Documentation License): Update to
- version 1.2.
-
-2005-09-15 Richard M. Stallman <rms@gnu.org>
-
- * buffers.texi (List Buffers): Fix xref.
-
- * rmail.texi (Rmail Basics): Fix xref.
-
- * emacs.texi (Top): Update subnode menus.
-
- * files.texi (Saving Commands): New node, broken out of Saving.
- (Customize Save): New node, broken out of Saving.
- Clarify effect of write-region-inhibit-fsync.
- (Misc File Ops): Say write-region-inhibit-fsync affects write-region.
-
- * newsticker.texi: Fix @setfilename.
-
- * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add newsticker targets.
- (../info/newsticker, newsticker.dvi): New targets.
-
-2005-09-14 Romain Francoise <romain@orebokech.com>
-
- * files.texi (Saving): Mention write-region-inhibit-fsync.
-
-2005-09-05 Chong Yidong <cyd@stupidchicken.com>
-
- * custom.texi (Custom Themes): New node.
-
-2005-09-03 Richard M. Stallman <rms@gnu.org>
-
- * search.texi (Search Case): Mention vars that control
- case-fold-search for various operations.
-
-2005-08-30 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Version 3.15.
-
-2005-08-29 Luc Teirlinck <teirllm@auburn.edu>
-
- * ses.texi: Combine all three indices into one.
- Correct a few typos.
-
-2005-08-19 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * emacs-mime.texi (time-date): Fix description of safe-date-to-time.
-
-2005-08-18 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * emacs-mime.texi (Handles): Remove duplicate item.
- (Encoding Customization): Fix the default value for
- mm-coding-system-priorities.
- (Charset Translation): Emacs doesn't use mm-mime-mule-charset-alist.
- (Basic Functions): Fix reference.
-
-2005-08-09 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (Charsets): Fj hierarchy uses iso-2022-jp.
-
-2005-08-22 Juri Linkov <juri@jurta.org>
-
- * display.texi (Standard Faces): Merge the text from
- `(elisp)Standard Faces' into this node.
-
-2005-08-18 Luc Teirlinck <teirllm@auburn.edu>
-
- * emacs.texi (Top): Delete menu item for deleted node
- Keyboard Translations.
-
-2005-08-18 Richard M. Stallman <rms@gnu.org>
-
- * faq.texi (Obtaining the FAQ): Delete refs to Lerner's email
- and web site.
-
- * trouble.texi (Unasked-for Search):
- Delete xref to Keyboard Translations.
-
- * glossary.texi (Glossary): Delete xref.
-
- * faq.texi (Swapping keys): Xref for normal-erase-is-backspace-mode,
- not keyboard-translate.
-
- * custom.texi (Minor Modes): Say that the list here is not complete.
- (Keyboard Translations): Node deleted.
- (Disabling): Delete xref to it.
- (Customization Groups): Fix Custom buffer example.
- (Hooks): Mention remove-hooks.
-
-2005-08-17 Luc Teirlinck <teirllm@auburn.edu>
-
- * building.texi (GDB Graphical Interface): Improve filling of menu
- item.
-
-2005-08-18 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (GDB Graphical Interface): Use better node names.
-
-2005-08-14 Richard M. Stallman <rms@gnu.org>
-
- * text.texi (Sentences): Fix xref.
-
-2005-08-14 Juri Linkov <juri@jurta.org>
-
- * building.texi (Compilation, Grep Searching): Move grep command
- headings from `Compilation' to `Grep Searching'.
-
- * dired.texi (Dired and Find):
- * maintaining.texi (Tags Search): Replace grep xref to
- `Compilation' node with `Grep Searching'.
-
- * files.texi (Comparing Files): Replace xref to `Compilation' with
- `Compilation Mode'.
-
-2005-08-13 Alan Mackenzie <acm@muc.de>
-
- * search.texi (Non-ASCII Isearch): Correct a typo.
- (Replacement Commands): Mention query-replace key binding.
-
-2005-08-11 Richard M. Stallman <rms@gnu.org>
-
- * programs.texi (Options for Comments): Fix xref.
-
- * search.texi (Regexp Backslash, Regexp Example): New nodes split
- out of Regexps.
-
- * faq.texi (Using regular expressions): Fix xref.
-
-2005-08-09 Juri Linkov <juri@jurta.org>
-
- * building.texi (Compilation): Use `itemx' instead of `item'.
- (Grep Searching): Simplify phrase.
-
- * display.texi (Standard Faces): Describe vertical-border on
- window systems.
-
- * windows.texi (Split Window): Simplify phrase and mention
- vertical-border face.
-
-2005-08-09 Richard M. Stallman <rms@gnu.org>
-
- * files.texi (Comparing Files): Clarify compare-windows.
-
- * calendar.texi (Scroll Calendar): Document < and > in calendar.
-
-2005-08-09 Juri Linkov <juri@jurta.org>
-
- * info.texi (Help-P): Replace `Prev' with `Previous'.
- (Help-M, Help-Xref): Add S-TAB.
- (Help-FOO): Update `u' command.
- (Help-Xref): Move info about Mouse-2 from `Help-Int'.
- Update info about visibility of xref parts.
- (Help-Int): Fix `m' command. Rename `Info-last' to
- `Info-history-back'. Add `Info-history-forward'.
- (Advanced): Fix `g*' and `M-n' commands.
- (Info Search): Add `index-apropos' in stand-alone browser.
- Add isearch commands.
- (Emacs Info Variables): Remove `Info-fontify'.
- Add `Info-mode-hook'. Update face names.
- Add `Info-fontify-maximum-menu-size',
- `Info-fontify-visited-nodes', `Info-isearch-search'.
-
-2005-08-07 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.0.50.
-
- * tramp.texi: Use @option{} consequently for method names.
- (Inline methods, External transfer methods): Remove references to
- Cygwin.
- (Issues with Cygwin ssh): Explain trouble with Cygwin's ssh
- implementation.
-
-2005-08-06 Eli Zaretskii <eliz@gnu.org>
-
- * mule.texi (Coding Systems): Rephrase the paragraph about
- codepages: no need for "M-x codepage-setup" anymore, except on
- MS-DOS.
-
- * msdog.texi (MS-DOS and MULE): Clarify that this section is for
- the MS-DOS port only.
-
-2005-07-30 Eli Zaretskii <eliz@gnu.org>
-
- * makefile.w32-in (info): Don't run multi-install-info.bat.
- ($(infodir)/dir): New target, produced by running
- multi-install-info.bat.
-
-2005-07-27 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Startup Files): Fix name of gnus-site-init-file.
- Mention that gnus-init-file is not read when Emacs is invoked with
- --no-init-file or -q.
-
-2005-07-22 Eli Zaretskii <eliz@gnu.org>
-
- * files.texi (Quoted File Names): Add index entry.
-
-2005-07-19 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Version 3.14.
-
-2005-07-04 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Version 3.13.
-
-2005-07-19 Juri Linkov <juri@jurta.org>
-
- * files.texi (Comparing Files): Mention resync for `compare-windows'.
-
-2005-07-18 Juri Linkov <juri@jurta.org>
-
- * calc.texi (Time Zones, Logical Operations):
- * cl.texi (Overview):
- * custom.texi (Easy Customization):
- * files.texi (Old Versions):
- * frames.texi (Wheeled Mice):
- * mule.texi (Specify Coding):
- * org.texi (TODO types):
- * sc.texi (Emacs 18 MUAs):
- * speedbar.texi (Top):
- * text.texi (Cell Justification):
- * trouble.texi (After a Crash):
- * url.texi (History):
- * xresources.texi (GTK styles):
- Delete duplicate duplicate words.
-
-2005-07-17 Richard M. Stallman <rms@gnu.org>
-
- * frames.texi (Creating Frames): Fix foreground color example.
-
- * custom.texi (Init Examples): Clean up text about conditionals.
-
-2005-07-16 Richard M. Stallman <rms@gnu.org>
-
- * mini.texi (Completion Commands): Fix command name for ?.
-
-2005-07-16 Johan Bockgard <bojohan@users.sourceforge.net> (tiny change)
-
- * cl.texi (Type Predicates): Document `atom' type.
-
-2005-07-16 Eli Zaretskii <eliz@gnu.org>
-
- * display.texi (Standard Faces): Explain that customization of
- `menu' face has no effect on w32 and with GTK. Add
- cross-references.
-
- * cmdargs.texi (General Variables): Clarify the default location
- of $HOME on w32 systems.
-
-2005-07-15 Jason Rumney <jasonr@gnu.org>
-
- * cmdargs.texi (General Variables): Default HOME on MS Windows has
- changed.
-
-2005-07-08 Kenichi Handa <handa@m17n.org>
-
- * mule.texi (Recognize Coding): Recommend
- revert-buffer-with-coding-system instead of revert-buffer.
-
-2005-07-07 Richard M. Stallman <rms@gnu.org>
-
- * anti.texi (Antinews): Mention mode-line-inverse-video.
-
- * files.texi (Saving): Minor correction about C-x C-w.
-
- * display.texi (Display Custom): Don't mention mode-line-inverse-video.
-
-2005-07-07 Luc Teirlinck <teirllm@auburn.edu>
-
- * search.texi (Isearch Scroll): Add example of using the
- `isearch-scroll' property.
- (Slow Isearch): Reference anchor for `baud-rate' instead of entire
- `Display Custom' node.
- (Regexp Replace): Put text that requires Emacs Lisp knowledge last
- and de-emphasize it.
- (Other Repeating Search): `occur' currently can not correctly
- handle multiline matches. Correct, clarify and update description
- of `flush-lines' and `keep-lines'.
-
- * display.texi (Display Custom): Add anchor for `baud-rate'.
-
-2005-07-07 Richard M. Stallman <rms@gnu.org>
-
- * gnu.texi: Update where to get GNU status; add refs for how to help.
- Add footnotes 6 and 7.
-
-2005-07-04 Lute Kamstra <lute@gnu.org>
-
- Update FSF's address in GPL notices.
-
- * calc.texi (Copying):
- * doclicense.texi (GNU Free Documentation License):
- * faq.texi (Contacting the FSF):
- * mh-e.texi (Copying):
- * trouble.texi (Checklist): Update FSF's address.
-
-2005-07-03 Richard M. Stallman <rms@gnu.org>
-
- * flymake.texi (Example -- Configuring a tool called directly):
- Update name of flymake-build-relative-filename.
-
-2005-06-29 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (NoCeM): gnus-nocem-verifyer defaults to pgg-verify.
-
-2005-06-29 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Version 3.12.
-
-2005-06-24 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Text Display): Change index entries.
-
-2005-06-24 Eli Zaretskii <eliz@gnu.org>
-
- * makefile.w32-in (MAKEINFO): Use --force.
- (INFO_TARGETS, DVI_TARGETS): Make identical to the lists in
- Makefile.in.
- (gnus.dvi): Use "..." to quote Sed args, so that it works with
- more shells.
-
-2005-06-23 Richard M. Stallman <rms@gnu.org>
-
- * anti.texi (Antinews): Renamed show-nonbreak-escape to
- nobreak-char-display.
-
- * emacs.texi (Top): Update detailed node listing.
-
- * display.texi (Text Display): Renamed show-nonbreak-escape
- to nobreak-char-display and no-break-space to nobreak-space.
- (Standard Faces): Split up the list of standard faces
- and put it in a separate node. Add nobreak-space and
- escape-glyph.
-
- * speedbar.texi (Creating a display): Texinfo usage fixes.
-
- * tramp.texi (Customizing Completion, Auto-save and Backup):
- Texinfo usage fixes.
-
-2005-06-23 Lute Kamstra <lute@gnu.org>
-
- * mule.texi (Select Input Method): Fix typo.
-
-2005-06-23 Kenichi Handa <handa@m17n.org>
-
- * mule.texi (International): List all supported scripts. Adjust
- text for that leim is now included in the normal Emacs
- distribution.
- (Language Environments): List all language environments.
- Intlfonts contains fonts for most supported scripts, not all..
- (Select Input Method): Refer to C-u C-x = to see how to type to
- input a specifc character.
- (Recognize Coding): Fix typo, china-iso-8bit -> chinese-iso-8bit.
-
-2005-06-23 Juanma Barranquero <lekktu@gmail.com>
-
- * building.texi (Grep Searching):
- * dired-x.texi (Miscellaneous Commands):
- * ediff.texi (Miscellaneous):
- * gnus.texi (MIME Commands, Fancy Mail Splitting, Agent Visuals)
- (Agent Variables):
- * info.texi (Help-Xref):
- * message.texi (Message Headers):
- * org.texi (Remember):
- * reftex.texi (Options (Defining Label Environments)):
- (Options (Index Support)):
- (Options (Viewing Cross-References)):
- (Options (Misc)):
- (Changes):
- * speedbar.texi (Creating a display):
- * tramp.texi (Customizing Completion, Auto-save and Backup):
- Texinfo usage fix.
-
-2005-06-22 Miles Bader <miles@gnu.org>
-
- * display.texi (Faces): Change `vertical-divider' to `vertical-border'.
-
-2005-06-20 Miles Bader <miles@gnu.org>
-
- * display.texi (Faces): Add `vertical-divider'.
-
-2005-06-17 Richard M. Stallman <rms@gnu.org>
-
- * text.texi (Adaptive Fill): Minor clarification.
-
-2005-06-13 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Version 3.11.
-
-2005-06-12 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Getting Started): Remove extra menu item.
-
-2005-06-10 Lute Kamstra <lute@gnu.org>
-
- * emacs.texi (Top): Correct version number.
- * anti.texi (Antinews): Correct version number. Use EMACSVER to
- refer to the current version of Emacs.
-
-2005-06-08 Luc Teirlinck <teirllm@auburn.edu>
-
- * files.texi (Log Buffer): Document when there can be more than
- one file to be committed.
-
-2005-06-08 Juri Linkov <juri@jurta.org>
-
- * display.texi (Faces): Add `shadow' face.
-
-2005-06-07 Masatake YAMATO <jet@gyve.org>
-
- * display.texi (Faces): Write about mode-line-highlight.
-
-2005-06-06 Richard M. Stallman <rms@gnu.org>
-
- * misc.texi (Printing Package): Explain how to initialize
- printing package.
-
- * cmdargs.texi (Action Arguments): Clarify directory default for -l.
-
-2005-06-05 Chong Yidong <cyd@stupidchicken.com>
-
- * emacs.texi: Rename Hardcopy to Printing.
- Make PostScript and PostScript Variables subnodes of it.
-
- * misc.texi (Printing): Rename node from Hardcopy.
- Mention menu bar options.
- Move PostScript and PostScript Variables to submenu.
- (Printing package): New node.
-
- * mark.texi (Using Region): Change Hardcopy xref to Printing.
-
- * dired.texi (Operating on Files): Likewise.
-
- * calendar.texi (Displaying the Diary): Likewise.
-
- * msdog.texi (MS-DOS Printing, MS-DOS Processes): Likewise.
-
- * glossary.texi (Glossary): Likewise.
-
- * frames.texi (Mode Line Mouse): Mention mode-line-highlight
- effect.
-
-2005-06-04 Richard M. Stallman <rms@gnu.org>
-
- * trouble.texi (After a Crash): Polish previous change.
-
-2005-05-31 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Notations Used in This Manual): Use @kbd for key
- sequence.
- (Demonstration of Calc): Mention another way of starting Calc.
- (Starting Calc): Mention long name of M-#.
- (Embedded Mode Overview): Remove unnecessary instruction.
- (Other M-# commands): Rephrase `M-# 0' explanation.
- (Basic Embedded Mode): Rewrite discussion of prefix arguments to
- reflect current behavior.
-
-2005-05-30 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Hooks): Change description of calc-window-hook and
- calc-trail-window-hook to match usage.
- (Computational Functions): Add more constant-generating functions.
- (Customizable Variables): Use defvar.
-
-2005-05-30 Noah Friedman <friedman@splode.com>
-
- * trouble.texi (After a Crash): Mention emacs-buffer.gdb as a
- recovery mechanism.
-
-2005-05-28 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Assignments in Embedded Mode): Fix variable name.
- (Basic Embedded Mode): Explain behavior of arguments to
- calc-embedded-mode.
-
-2005-05-28 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Other Buffers): SPC toggles display of
- floating point registers.
-
-2005-05-27 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Queries in Keyboard Macros): Rewrite to reflect
- current behavior.
-
-2005-05-27 Nick Roberts <nickrob@snap.net.nz>
-
- * files.texi (Log Buffer): Merge in description of Log Edit
- mode from pcl-cvs.texi.
-
-2005-05-26 Richard M. Stallman <rms@gnu.org>
-
- * building.texi (Lisp Eval): C-M-x with arg runs Edebug.
-
-2005-05-25 Jay Belanger <belanger@truman.edu>
-
- * calc.texi: Change Calc version number throughout.
- (Keypad Mode): Change location in info output.
- (Keypad mode overview): Move picture of keypad.
-
-2005-05-24 Luc Teirlinck <teirllm@auburn.edu>
-
- * fixit.texi (Spelling): Delete confusing sentence; flyspell is
- not enabled by default.
- When not on a word, `ispell-word' by default checks the word
- before point.
-
-2005-05-24 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Debugger Operation): Simplify last sentence.
-
-2005-05-23 Lute Kamstra <lute@gnu.org>
-
- * emacs.texi: Update FSF's address throughout.
- (Preface): Use @cite.
- (Distrib): Add cross reference to the node "Copying". Mention the
- FDL. Don't refer to etc/{FTP,ORDERS}. Mention the sale of
- printed manuals.
- (Intro): Use @xref for the Emacs Lisp Intro.
-
-2005-05-21 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Storing variables): Mention that only most variables
- are void to begin with.
-
-2005-05-21 Kevin Ryde <user42@zip.com.au>
-
- * widget.texi (Basic Types): Update cross ref from "Enabling
- Mouse-1 to Follow Links" to "Links and Mouse-1" per recent
- lispref/text.texi change.
-
-2005-05-20 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Version 3.09.
-
-2005-05-18 Carsten Dominik <dominik@science.uva.nl>
-
- * reftex.texi: Version 4.28.
-
-2005-05-18 Luc Teirlinck <teirllm@auburn.edu>
-
- * buffers.texi (Select Buffer): Document `C-u M-g M-g'.
-
- * basic.texi (Moving Point): Mention default for `goto-line'.
-
- * programs.texi (Lisp Doc): Eldoc mode shows only the first line
- of a variable's docstring.
-
-2005-05-18 Lute Kamstra <lute@gnu.org>
-
- * maintaining.texi (Overview of Emerge): Add cross reference.
- Remove duplication.
-
- * emacs.texi (Top): Update to the current structure of the manual.
- * misc.texi (Emacs Server): Add menu description.
- * files.texi (Saving): Fix menu.
- * custom.texi (Customization): Fix menu.
- * mule.texi (International): Fix menu.
- * kmacro.texi (Keyboard Macros): Fix menu.
-
-2005-05-16 Luc Teirlinck <teirllm@auburn.edu>
-
- * display.texi: Various minor changes.
- (Faces): Delete text that is repeated in the next section.
-
-2005-05-16 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Debugger Operation): Mention GUD tooltips are
- disabled with GDB in text command mode.
-
-2005-05-16 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Storing Variables): Mention `calc-copy-special-constant'.
-
-2005-05-16 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi: Replace toolbar with "tool bar" for consistency.
- (Compilation Mode): Describe compilation-context-lines
- and use of arrow in compilation buffer.
- (Debugger Operation): Replace help text with variable's value.
-
- * frames.texi (Tooltips): Replace toolbar with "tool bar" for
- consistency.
-
-2005-05-15 Luc Teirlinck <teirllm@auburn.edu>
-
- * major.texi (Choosing Modes): normal-mode processes the -*- line.
- Add xref.
-
-2005-05-14 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Default Simplifications): Insert missing ! (logical
- not operator).
-
-2005-05-14 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.0.49.
-
-2005-05-14 Luc Teirlinck <teirllm@auburn.edu>
-
- * basic.texi (Moving Point): Mention `M-g g' binding for `goto-line'.
- (Position Info): Delete discussion of `goto-line'. It is already
- described in `Moving point'.
-
- * mini.texi (Completion Commands): Correct reference.
- (Completion Options): Fix typo.
-
- * killing.texi (Deletion): Complete description of `C-x C-o'.
-
-2005-05-10 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Default Simplifications): Mention that 0^0 simplifies
- to 1.
-
-2005-05-10 Richard M. Stallman <rms@gnu.org>
-
- * building.texi (Compilation): Clarify recompile's directory choice.
-
- * frames.texi (Tooltips): Cleanups.
-
- * basic.texi (Arguments): Fix punctuation.
-
-2005-05-09 Luc Teirlinck <teirllm@auburn.edu>
-
- * screen.texi (Menu Bar): The up and down (not left and right)
- arrow keys move through a keyboard menu.
-
-2005-05-08 Luc Teirlinck <teirllm@auburn.edu>
-
- * basic.texi: Various typo and grammar fixes.
- (Moving Point): C-a now runs move-beginning-of-line.
-
-2005-05-08 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Debugger Operation): Describe gud-tooltip-echo-area.
-
- * frames.texi (Tooltips): Describe help tooltips and GUD tooltips
- as different animals.
-
-2005-05-07 Luc Teirlinck <teirllm@auburn.edu>
-
- * frames.texi (Mouse References): Clarify `mouse-1-click-follows-link'.
- Correct index entry.
-
-2005-05-07 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Debugger Operation): Update to reflect changes
- in GUD tooltips.
-
-2005-04-30 Richard M. Stallman <rms@gnu.org>
-
- * files.texi (Compressed Files): Auto Compression normally enabled.
-
- * building.texi (Debugger Operation): Clarify previous change.
-
-2005-04-29 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Version 3.08, structure reorganized.
-
-2005-04-28 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Debugger Operation): Add description for
- GUD tooltips when program is not running.
-
-2005-04-26 Luc Teirlinck <teirllm@auburn.edu>
-
- * misc.texi (Shell): Add `Shell Prompts' to menu.
- (Shell Mode): Add xref to `Shell Prompts'. Clarify `C-c C-u'
- description. Delete remarks moved to new node.
- (Shell Prompts): New node.
- (History References): Replace remarks moved to `Shell Prompts'
- with xref to that node.
- (Remote Host): Clarify how to specify the terminal type when
- logging in to a different machine.
-
-2005-04-26 Richard M. Stallman <rms@gnu.org>
-
- * emacs.texi (Top): Update submenus from files.texi.
-
- * files.texi (Filesets): Clarify previous change.
-
- * dired.texi (Misc Dired Features): Clarify previous change.
-
-2005-04-25 Chong Yidong <cyd@stupidchicken.com>
-
- * ack.texi (Acknowledgments): Delete info about iso-acc.el.
-
- * dired.texi (Misc Dired Features): Document
- dired-compare-directories.
-
- * files.texi (Filesets): New node.
- (File Conveniences): Document Image mode.
-
- * text.texi (TeX Print): Document tex-compile.
-
-2005-04-25 Luc Teirlinck <teirllm@auburn.edu>
-
- * frames.texi (Tooltips): Tooltip mode is enabled by default.
- Delete redundant reference to tooltip Custom group. It is
- referred too again in the next paragraph.
-
-2005-04-24 Richard M. Stallman <rms@gnu.org>
-
- * ack.texi: Delete info about lazy-lock.el and fast-lock.el.
-
- * faq.texi: Delete info about lazy-lock.el and fast-lock.el.
-
-2005-04-19 Kim F. Storm <storm@cua.dk>
-
- * building.texi (Compilation Mode): Add M-g M-n and M-g M-p bindings.
-
-2005-04-18 Lars Hansen <larsh@math.ku.dk>
-
- * misc.texi (Saving Emacs Sessions): Add that "--no-desktop" now
- turns off desktop-save-mode.
-
-2005-04-17 Luc Teirlinck <teirllm@auburn.edu>
-
- * frames.texi (XTerm Mouse): Xterm Mouse mode is no longer enabled
- by default in terminals compatible with xterm. Mention that
- xterm-mouse-mode is a minor mode and put in pxref to Minor Modes
- node.
-
-2005-04-15 Carsten Dominik <dominik@science.uva.nl>
-
- * org.texi: Update to version 3.06.
-
-2005-04-13 Lute Kamstra <lute@gnu.org>
-
- * cc-mode.texi: Prevent creating an unnecessary empty cc-mode.ss file.
-
-2005-04-12 Luc Teirlinck <teirllm@auburn.edu>
-
- * frames.texi (XTerm Mouse): Xterm Mouse mode is now enabled by default.
-
-2005-04-12 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * xresources.texi (Table of Resources): Add cursorBlink.
-
-2005-04-11 Luc Teirlinck <teirllm@auburn.edu>
-
- * rmail.texi (Rmail Summary Edit): Explain numeric arguments to
- `d', `C-d' and `u'.
-
-2005-04-11 Richard M. Stallman <rms@gnu.org>
-
- * cmdargs.texi (Initial Options): -Q is now --quick, and does less.
- (Misc X): Add -D, --basic-display.
-
- * maintaining.texi (Change Log): Correct the description of
- the example.
-
- * major.texi (Choosing Modes): Document magic-mode-alist.
-
-2005-04-10 Thien-Thi Nguyen <ttn@gnu.org>
-
- * cl.texi (Porting Common Lisp): Fix typo.
-
-2005-04-10 Luc Teirlinck <teirllm@auburn.edu>
-
- * rmail.texi (Rmail Basics): Clarify description of `q' and `b'.
- (Rmail Deletion): `C-d' in RMAIL buffer does not accept a numeric arg.
- (Rmail Inbox): Give full name of `rmail-primary-inbox-list'.
- (Rmail Output): Clarify which statements apply to `o', `C-o' and
- `w', respectively.
- (Rmail Labels): Mention `l'.
- (Rmail Attributes): Correct pxref. Mention `stored' attribute.
- (Rmail Summary Edit): Describe `j' and RET.
-
-2005-04-10 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * xresources.texi (Lucid Resources): Add fontSet resource.
-
-2005-04-06 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (RSS): Addition.
-
-2005-04-09 Luc Teirlinck <teirllm@auburn.edu>
-
- * display.texi (Useless Whitespace): `indicate-unused-lines' is
- now called `indicate-empty-lines'.
-
-2005-04-06 Kim F. Storm <storm@cua.dk>
-
- * cmdargs.texi (Initial Options): Add --bare-bones alias for -Q.
-
-2005-04-04 Luc Teirlinck <teirllm@auburn.edu>
-
- * dired.texi (Dired Visiting): `dired-view-command-alist' has been
- deleted.
- (Marks vs Flags): Add some convenient key bindings.
- (Hiding Subdirectories): Delete redundant and inaccurate sentence.
- (Misc Dired Features): Correct and expand description of `w' command.
-
- * frames.texi (XTerm Mouse): Delete apparently false info.
- The GNU/Linux console currently does not appear to support
- `xterm-mouse-mode'.
-
-2005-04-04 Jay Belanger <belanger@truman.edu>
-
- * calc.texi: Change Calc version number.
- (Customizable variables): Fix description of calc-language-alist.
- (Copying): Put in version 2 of GPL.
-
-2005-04-03 Glenn Morris <gmorris@ast.cam.ac.uk>
-
- * calendar.texi (Diary): Mention shell utility `calendar'.
-
-2005-04-01 Richard M. Stallman <rms@gnu.org>
-
- * cmdargs.texi (Misc X): Explain horizontal scroll bars don't exist.
-
-2005-04-01 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Troubleshooting Commands): Remove comment about
- installation.
- (Installation): Remove section.
- (Customizable Variables): New section.
- (Basic Embedded Mode, Customizing Embedded Mode, Graphics)
- (Graphical Devices): Add references to Customizable Variables.
-
-2005-04-01 Lute Kamstra <lute@gnu.org>
-
- * maintaining.texi (Change Log): add-change-log-entry uses
- add-log-mailing-address.
-
-2005-03-31 Luc Teirlinck <teirllm@auburn.edu>
-
- * files.texi (Reverting): Move `auto-revert-check-vc-info' to
- `VC Mode Line' and put in an xref to that node.
- (VC Mode Line): Move `auto-revert-check-vc-info' here and clarify
- its description.
-
-2005-03-31 Paul Eggert <eggert@cs.ucla.edu>
-
- * calendar.texi (Calendar Systems): Say that the Persian calendar
- implemented here is the arithmetical one championed by Birashk.
-
-2005-03-30 Glenn Morris <gmorris@ast.cam.ac.uk>
-
- * programs.texi (Fortran Motion): Fix previous change.
-
-2005-03-25 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * emacs-mime.texi (Display Customization): Markup fixes.
- (rfc2047): Update.
-
-2005-03-23 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus-faq.texi: Replaced with auto-generated version.
-
-2005-03-29 Richard M. Stallman <rms@gnu.org>
-
- * mule.texi (Single-Byte Character Support): Reinstall the C-x 8 info.
-
-2005-03-29 Chong Yidong <cyd@stupidchicken.com>
-
- * text.texi (Refill): Refer to Long Lines Mode.
- (Longlines): New node.
- (Auto Fill): Don't index "word wrap" here.
- (Filling): Add Longlines to menu.
-
-2005-03-29 Richard M. Stallman <rms@gnu.org>
-
- * xresources.texi: Minor fixes.
-
- * misc.texi (Emacs Server): Fix Texinfo usage.
-
- * emacs.texi (Top): Don't use a real section heading for
- "Detailed Node Listing". Fake it instead.
-
- * basic.texi (Position Info): Minor cleanup.
-
- * mule.texi (Input Methods): Minor cleanup.
-
-2005-03-29 Glenn Morris <gmorris@ast.cam.ac.uk>
-
- * programs.texi (ForIndent Vars): `fortran-if-indent' does other
- constructs as well.
- (Fortran Motion): Add fortran-end-of-block, fortran-beginning-of-block.
-
-2005-03-29 Kenichi Handa <handa@m17n.org>
-
- * mule.texi (Input Methods): Refer to the command C-u C-x =.
-
- * basic.texi (Position Info): Update the description about the
- command C-u C-x =.
-
-2005-03-28 Richard M. Stallman <rms@gnu.org>
-
- * emacs.texi (Top): Use @section for the detailed node listing.
-
- * calendar.texi: Minor fixes to previous change.
-
- * programs.texi (Fortran): Small fixes to previous changes.
-
- * emacs.texi (Top): Update list of subnodes of Dired.
- Likewise for building.texi.
-
- * files.texi (File Conveniences): Delete Auto Image File mode.
-
-2005-03-28 Chong Yidong <cyd@stupidchicken.com>
-
- * building.texi (Flymake): New node.
-
- * custom.texi (Function Keys): Document kp- event types and
- keypad-setup package.
-
- * dired.texi (Wdired): New node.
-
- * files.texi (File Conveniences): Reorder entries.
- Explain how to turn on Auto-image-file mode.
- Document Thumbs mode.
-
- * mule.texi (Specify Coding): Document recode-region and
- recode-file-name.
-
- * programs.texi (Program Modes): Add Conf mode and DNS mode.
-
-2005-03-27 Luc Teirlinck <teirllm@auburn.edu>
-
- * commands.texi (Keys): M-o is now a prefix key.
-
-2005-03-27 Glenn Morris <gmorris@ast.cam.ac.uk>
-
- * programs.texi: Reformat and update copyright years.
- (Fortran): Update section.
-
-2005-03-26 Luc Teirlinck <teirllm@auburn.edu>
-
- * files.texi: Several small changes in addition to:
- (Visiting): Change xref for Dialog Boxes to ref.
- (Version Headers): Replace references to obsolete var
- `vc-header-alist' with `vc-BACKEND-header'.
- (Customizing VC): Update value of `vc-handled-backends'.
-
-2005-03-26 Glenn Morris <gmorris@ast.cam.ac.uk>
-
- * emacs-xtra.texi (Advanced Calendar/Diary Usage): New section;
- move here from Emacs Lisp Reference Manual.
- * calendar.texi (Calendar/Diary, Diary Commands)
- (Special Diary Entries, Importing Diary): Change some xrefs to
- point to emacs-xtra rather than elisp.
-
- * emacs-xtra.texi (Calendar Customizing):
- Move view-diary-entries-initially, view-calendar-holidays-initially,
- mark-diary-entries-in-calendar, mark-holidays-in-calendar to main
- Emacs Manual.
- (Appt Customizing): Merge entire section into main Emacs Manual.
- * calendar.texi (Holidays): Move view-calendar-holidays-initially,
- mark-holidays-in-calendar here from emacs-xtra.
- (Displaying the Diary): Move view-diary-entries-initially,
- mark-diary-entries-in-calendar here from emacs-xtra.
- (Appointments): Move appt-display-mode-line,
- appt-display-duration, appt-disp-window-function,
- appt-delete-window-function here from emacs-xtra.
-
- * calendar.texi: Update and reformat copyright.
- Change all @xrefs to the non-printing emacs-xtra to @inforefs.
- (Calendar/Diary): Menu now only on Mouse-3, not C-Mouse-3.
- (Diary): Refer to `diary-file' rather than ~/diary.
- (Diary Commands): Rename node to "Displaying the Diary".
- * emacs.texi (Top): Rename "Diary Commands" section.
- * misc.texi (Hardcopy): Rename "Diary Commands" xref.
-
-2005-03-26 Eli Zaretskii <eliz@gnu.org>
-
- * misc.texi (Emacs Server): Fix the command for setting
- server-name. Add an xref to Invoking emacsclient.
-
- * help.texi (Help Summary): Clarify when "C-h ." will do something
- nontrivial.
- (Apropos): Add cindex entry for apropos-sort-by-scores.
-
- * display.texi (Text Display): Add index entries for how no-break
- characters are displayed.
-
-2005-03-26 Stephan Stahl <stahl@eos.franken.de> (tiny change)
-
- * dired-x.texi (Multiple Dired Directories): default-directory was
- renamed to dired-default-directory.
-
-2005-03-26 Eli Zaretskii <eliz@gnu.org>
-
- * files.texi (Visiting): Fix cross-references introduced with the
- last change.
-
- * xresources.texi (GTK resources): Fix last change.
-
-2005-03-26 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Simplifying Formulas, Rewrite Rules):
- Change description of top and bottom of fraction.
- (Modulo Forms): Move description of how to create modulo forms to
- earlier in the section.
- (Fraction Mode): Suggest using : to get a fraction by dividing.
- (Basic Arithmetic): Adjust placement of command name.
- (Truncating the Stack): Emphasize that "hidden" entries are still
- visible.
- (Installation): Move discussion of printing manual to "About This
- Manual".
- (About This Manual): Mention how to print the manual.
- (Reporting Bugs): Remove first person.
- (Building Vectors): Add algebraic version of append.
- (Manipulating Vectors): Fix algebraic version of calc-reverse-vector.
- (Grouping Digits): Fix typo.
-
-2005-03-25 Chong Yidong <cyd@stupidchicken.com>
-
- * xresources.texi (X Resources): GTK options documented too.
- (Resources): Clarify meaning of program name.
- (Table of Resources): Add visualClass.
- (GTK resources): Rewrite.
- (GTK widget names, GTK Names in Emacs, GTK styles): Cleanups.
-
- * display.texi (Text Display): Mention non-breaking spaces.
-
- * files.texi (Reverting): Document auto-revert-check-vc-info.
-
- * frames.texi (Mouse Commands): Document
- x-mouse-click-focus-ignore-position and mouse-drag-copy-region.
-
- * help.texi (Help Summary): Add `C-h .'.
- (Apropos): Apropos accepts a list of search terms.
- Document apropos-sort-by-scores.
- (Help Echo): Document display-local-help.
-
- * misc.texi (Emacs Server): Document server-name.
- (Invoking emacsclient): Document -s option for server names.
-
- * text.texi (Outline Visibility): Introduce "current heading
- line" (commands can be called with point on a body line).
- Re-order table to follow the sequence of discussion.
- hide-body won't hide lines before first header line.
- (TeX Mode): Add DocTeX mode.
-
-2005-03-25 Werner Lemberg <wl@gnu.org>
-
- * calc.texi, cl.texi, gnus.texi, idlwave.texi, reftex.texi:
- Replace `legal' with `valid'.
-
-2005-03-25 Werner Lemberg <wl@gnu.org>
-
- * calc.texi, reftex.texi: Replace `illegal' with `invalid'.
-
-2005-03-24 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (General Mode Commands)
- (Mode Settings in Embedded Mode): Add some explanation of
- recording mode settings.
-
-2005-03-24 Richard M. Stallman <rms@gnu.org>
-
- * mule.texi (Single-Byte Character Support): Delete mention
- of iso-acc.el and iso-transl.el.
-
- * calc.texi: Remove praise of non-free software.
-
- * idlwave.texi: Don't say where to get IDL or its non-free manual.
- (Installation): Node deleted.
-
-2005-03-23 Lute Kamstra <lute@gnu.org>
-
- * search.texi (Non-ASCII Isearch): Rename from Non-Ascii Isearch.
-
-2005-03-23 Richard M. Stallman <rms@gnu.org>
-
- * url.texi (HTTP language/coding): Improve last change.
-
- * search.texi: Delete explicit node pointers.
- (Incremental Search): New menu.
- (Basic Isearch, Repeat Isearch, Error in Isearch)
- (Non-Ascii Isearch, Isearch Yank, Highlight Isearch, Isearch Scroll)
- (Slow Isearch): New subnodes.
- (Configuring Scrolling): Node deleted.
- (Search Case): Doc default-case-fold-search.
- (Regexp Replace): Move replace-regexp doc here.
-
- * rmail.texi (Movemail): Put commas inside closequotes.
-
- * picture.texi (Insert in Picture): Document C-c arrow combos.
- (Basic Picture): Clarify erasure.
-
- * display.texi (Font Lock): Put commas inside closequotes.
-
- * cmdargs.texi (General Variables): Put commas inside closequotes.
-
-2005-03-23 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Stack Buffer): Mention reverse contrast for
- *selected* frame (might not be current frame).
-
-2005-03-22 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Embedded Mode): Add new information on changing
- modes.
-
-2005-03-21 Richard M. Stallman <rms@gnu.org>
-
- * building.texi (Starting GUD): Add bashdb.
-
-2005-03-20 Chong Yidong <cyd@stupidchicken.com>
-
- * basic.texi (Moving Point): Add M-g M-g binding.
- (Undo): Document undo-only.
- (Position Info): Document M-g M-g and C-u M-g M-g.
-
- * building.texi (Building): Put Grep Searching after Compilation
- Shell.
- (Compilation Mode): Document M-n, M-p, M-}, M-{, and C-c C-f bindings.
- Document next-error-highlight.
- (Grep Searching): Document grep-highlight-matches.
- (Lisp Eval): Typing C-x C-e twice prints integers specially.
-
- * calendar.texi (Importing Diary): Rename node from iCalendar.
- Document diary-from-outlook.
-
- * dired.texi (Misc Dired Features): Rename node from Misc Dired
- Commands.
- Mention effect of X drag and drop on Dired buffers.
-
- * files.texi (Visiting): Document large-file-warning-threshold.
- Move paragraph on file-selection dialog.
- Mention visiting files using X drag and drop.
- (Reverting): Mention using Auto-Revert mode to tail files.
- Document auto-revert-tail-mode.
- (Version Systems): Minor correction.
- (Comparing Files): Diff-mode is no longer based on Compilation
- mode.
- Document compare-ignore-whitespace.
- (Misc File Ops): Explain passing a directory to rename-file.
- Likewise for copy-file and make-symbolic-link.
-
- * frames.texi (Wheeled Mice): Mouse wheel support on by default.
- Document mouse-wheel-progressive speed.
-
- * help.texi (Misc Help): Document numeric argument for C-h i.
- Correctly explain the effect of just C-u as argument.
-
- * killing.texi (Deletion): Document numeric argument for
- just-one-space.
-
- * mini.texi (Completion): Completion acts on text before point.
-
- * misc.texi (Saving Emacs Sessions): Document desktop-restore-eager.
- (Emulation): CUA mode replaces pc-bindings-mode,
- pc-selection-mode, and s-region.
-
- * mule.texi (Input Methods): Leim is now built-in.
- (Select Input Method): Document quail-show-key.
- (Specify Coding): Document revert-buffer-with-coding-system.
-
- * programs.texi (Fortran Motion): Document f90-next-statement,
- f90-previous-statement, f90-next-block, f90-previous-block,
- f90-end-of-block, and f90-beginning-of-block.
-
- * text.texi (Format Faces): Replace old M-g key prefix with M-o.
-
- * emacs.texi (Acknowledgments): Updated.
-
- * anti.texi: Total rewrite.
-
-2005-03-20 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.0.48.
-
- * trampver.texi.in: Replace "Emacs" by "GNU Emacs".
-
- * tramp.texi: Replace "Emacs" by "GNU Emacs". Replace "Linux" by
- "GNU/Linux". Change all addresses to .gnu.org.
- (Default Method): Offer shortened syntax for "su" and "sudo"
- methods.
-
-2005-03-19 Chong Yidong <cyd@stupidchicken.com>
-
- * ack.texi (Acknowledgments): Update.
-
-2005-03-19 Eli Zaretskii <eliz@gnu.org>
-
- * anti.texi (Antinews): Refer to Emacs 21.4, not 21.3. Update
- copyright years.
-
-2005-03-14 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Commands of GUD): Move paragraph on setting
- breakpoints with mouse to the GDB Graphical Interface node.
-
-2005-03-07 Richard M. Stallman <rms@gnu.org>
-
- * url.texi: Fix usage of "e.g.".
- (HTTP language/coding): Explain the rules for these strings.
-
- * misc.texi (Single Shell, Shell Options): Fix previous change.
-
- * building.texi (Debugger Operation): Update GUD tooltip enable info.
-
-2005-03-06 Richard M. Stallman <rms@gnu.org>
-
- * building.texi (Starting GUD): Don't explain text vs graphical
- GDB here. Just mention it and xref.
- Delete "just one debugger process".
- (Debugger Operation): Move GUD tooltip info here.
- (GUD Tooltips): Node deleted.
- (GDB Graphical Interface): Explain the two GDB modes here.
-
- * woman.texi (Introduction): Minor cleanups.
-
- * url.texi (HTTP language/coding): Get rid of "Emacs 21".
-
- * sending.texi (Sending Mail): Minor cleanup.
- (Mail Aliases): Explain quoting conventions.
- Update key rebinding example.
- (Header Editing): C-M-i is like M-TAB.
- (Mail Mode Misc): mail-attach-file does not do MIME.
-
- * rmail.texi (Rmail Inbox): Move text from Remote Mailboxes
- that really belongs here.
- (Remote Mailboxes): Text moved to Rmail Inbox.
- (Rmail Display): Mention Mouse-1.
- (Movemail): Clarify two movemail versions.
- Clarify rmail-movemail-program.
-
- * pcl-cvs.texi (About PCL-CVS): Get rid of "Emacs 21".
- (Installation): Node deleted.
-
- * misc.texi (Single Shell): Replace uudecode example with gpg example.
- Document async shell commands.
- (Shell History): Clarify.
- (Shell Ring): Mention C-UP an C-DOWN.
- (Shell Options): Add comint-prompt-read-only.
- (Invoking emacsclient): Set EDITOR to run Emacs.
- (Sorting): No need to explain what region is.
- (Saving Emacs Sessions): Fix typo.
- (Recursive Edit): Fix punctuation.
- (Emulation): Don't mention "PC bindings" which are standard.
- (Hyperlinking): Explain Mouse-1 convention here.
- (Find Func): Node deleted.
-
- * mh-e.texi (Preface): Get rid of "Emacs 21".
-
- * help.texi (Name Help): Xref to Hyperlinking.
-
- * glossary.texi (Glossary):
- Rename "Balance Parentheses" to "Balancing...".
- Add "Byte Compilation". Correct "Copyleft".
- New xref in "Customization".
- Clarify "Current Line", "Echoing", "Fringe", "Frame", "Speedbar".
- Add "Graphical Terminal" "Keybinding", "Margin", "Window System".
- Rename "Registers" to "Register".
- Replace "Selecting" with "Selected Frame",
- "Selected Window", and "Selecting a Buffer".
-
- * files.texi (Types of Log File): Explain how projects'
- methods can vary.
-
- * eshell.texi (Installation): Delete node (for Emacs 20).
-
- * display.texi (Faces): Delete "Emacs 21".
-
- * custom.texi (Changing a Variable): C-M-i like M-TAB.
- * fixit.texi (Spelling): C-M-i like M-TAB.
- * mini.texi (Completion Options): C-M-i like M-TAB.
- * programs.texi (Symbol Completion): C-M-i like M-TAB.
- * text.texi (Text Mode): C-M-i like M-TAB.
-
- * commands.texi (Keys): Mention F1 and F2 in list of prefixes.
-
- * calendar.texi (Specified Dates): Mention `g w'.
- (Appointments): appt-activate toggles with no arg.
-
-2005-03-05 Thien-Thi Nguyen <ttn@gnu.org>
-
- * flymake.texi: Refill and tweak style in @lisp blocks.
-
-2005-03-05 Juri Linkov <juri@jurta.org>
-
- * cmdargs.texi (Emacs Invocation): Add cindex
- "invocation (command line arguments)"
- (Misc X): Add -nbc, --no-blinking-cursor.
-
-2005-03-04 Ulf Jasper <ulf.jasper@web.de>
-
- * calendar.texi (iCalendar): No need to require it now.
-
-2005-03-03 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Slow/Expensive Connection): Don't abbreviate "very".
-
-2005-03-03 Nick Roberts <nickrob@snap.net.nz>
-
- * trouble.texi (Contributing): Mention Savannah. Direct users to
- emacs-devel.
-
-2005-03-01 Glenn Morris <gmorris@ast.cam.ac.uk>
-
- * calendar.texi (Adding to Diary): Mention redrawing of calendar
- window.
-
-2005-03-01 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Trigonometric and Hyperbolic Functions):
- Mention additional functions.
- (Algebraic Simplifications): Mention additional simplifications.
-
-2005-02-27 Richard M. Stallman <rms@gnu.org>
-
- * building.texi (Compilation): Update mode line status info.
-
-2005-02-27 Matt Hodges <MPHodges@member.fsf.org>
-
- * calendar.texi (General Calendar): Document binding of
- scroll-other-window-down.
- (Mayan Calendar): Fix earliest date.
- (Time Intervals): Document timeclock-change.
- Fix timeclock-ask-before-exiting documentation.
-
-2005-02-26 Kim F. Storm <storm@cua.dk>
-
- * frames.texi (Mouse References):
- Add mouse-1-click-in-non-selected-windows.
-
-2005-02-25 Richard M. Stallman <rms@gnu.org>
-
- * screen.texi (Screen): Explain better about cursors and mode lines;
- don't presuppose text terminals.
- (Point): Don't assume just one cursor.
- Clarify explanation of cursors.
- (Echo Area, Menu Bar): Cleanups.
-
- * mini.texi (Minibuffer): Prompts are highlighted.
- (Minibuffer Edit): Newline = C-j only on text terminals.
- Clarify resize-mini-windows values.
- Mention M-PAGEUP and M-PAGEDOWN.
- (Completion Commands): Mouse-1 like Mouse-2.
- (Minibuffer History): Explain history commands better.
- (Repetition): Add xref to Incremental Search.
-
- * mark.texi (Setting Mark): Clarify info about displaying mark.
- Clarify explanation of C-@ and C-SPC.
- (Transient Mark): Mention Delete Selection mode.
- (Marking Objects): Clean up text about extending the region.
-
- * m-x.texi (M-x): One C-g doesn't always go to top level.
- No delay before suggest-key-bindings output.
-
- * fixit.texi (Fixit): Mention C-/ for undo.
- (Spelling): Mention ESC TAB like M-TAB.
- Replacement words with r and R are rechecked.
- Say where C-g leaves point. Mention ? as input.
-
-2005-02-23 Lute Kamstra <lute@gnu.org>
-
- * cmdargs.texi (Initial Options): Add cross reference.
-
-2005-02-18 Jonathan Yavner <jyavner@member.fsf.org>
-
- * ses.texi: Add concept/function/variable indices (this work was
- donated by Brad Collins <brad@chenla.org>, copyright-assignment
- papers on file at FSF).
-
-2005-02-16 Luc Teirlinck <teirllm@auburn.edu>
-
- * emacs.texi (Top): Update menu for splitting of node in
- msdog.texi.
- * frames.texi (Frames): Update xref for splitting of node in
- msdog.texi.
- * trouble.texi (Quitting): Ditto.
-
-2005-02-16 Richard M. Stallman <rms@gnu.org>
-
- * windows.texi (Split Window): Simplify line truncation info
- and xref to Display Custom.
-
- * trouble.texi (Quitting): Emergency escape only for text terminal.
- (Screen Garbled): C-l for ungarbling is only for text terminal.
-
- * text.texi (Text Mode): ESC TAB alternative for M-TAB.
-
- * sending.texi (Header Editing): ESC TAB alternative for M-TAB.
-
- * programs.texi (Program Modes): Mention Python mode.
- (Moving by Defuns): Repeating C-M-h extends region.
- (Basic Indent): Clarify.
- (Custom C Indent): Clarify.
- (Expressions): Repeating C-M-@ extends region.
- (Info Lookup): Clarify for C-h S.
- (Symbol Completion): ESC TAB alternative for M-TAB.
- (Electric C): Clarify.
-
- * emacs.texi (Top): Update display.texi and frames.texi submenu data.
-
- * msdog.texi (MS-DOS Keyboard, MS-DOS Mouse): Split from
- MS-DOS Input node.
- (MS-DOS Keyboard): Start with explaining DEL and BREAK.
- (MS-DOS and MULE): Clarify.
- (MS-DOS Processes, Windows Processes): Fix typos.
-
- * major.texi (Choosing Modes): Clarify.
-
- * kmacro.texi (Basic Keyboard Macro): Doc F3, F4.
- (Keyboard Macro Step-Edit): Clarify.
-
- * indent.texi (Indentation): Clarifications.
-
- * help.texi (Help): Correct error about C-h in query-replace.
- Clarify apropos vs C-h a. Fix how to search in FAQ.
- (Key Help): Describe C-h w here.
- (Name Help): Minor cleanup. C-h w moved to Key Help.
- Clarify the "object" joke.
- (Apropos): Clarify. Mouse-1 like Mouse-2.
- (Help Mode): Mouse-1 like Mouse-2.
-
- * fixit.texi (Spelling): Mention ESC TAB as alt. for M-TAB.
-
- * display.texi (Display): Reorder menu.
- (Faces): Cleanup.
- (Font Lock): Cleanup. Mention Options menu.
- Delete obsolete text.
- (Scrolling): For C-l, don't presume text terminal.
- (Horizontal Scrolling): Simplify intro.
- (Follow Mode): Clarify.
- (Cursor Display): Moved before Display Custom.
- (Display Custom): Explain no-redraw-on-reenter is for text terminals.
- Doc default-tab-width. Doc line truncation more thoroughly.
-
- * dired.texi (Dired Enter): C-x C-f can run Dired.
- (Dired Visiting): Comment out `a' command.
- Mouse-1 is like Mouse-2.
- (Shell Commands in Dired): ? can be used more than once.
-
- * basic.texi (Continuation Lines): Simplify description of truncation,
- and refer to Display Custom for the rest of it.
-
-2005-02-10 Jay Belanger <belanger@truman.edu>
-
- * calc.texi: Change @LaTeX to La@TeX throughout.
- Redefine @expr as @math for TeX output.
- Redefine @texline as a no-op for TeX output.
- Define @tfn, replace @t by @tfn throughout.
-
-2005-02-09 Jay Belanger <belanger@truman.edu>
-
- * calc.texi: Add macro for LaTeX for info output.
-
-2005-02-08 Kim F. Storm <storm@cua.dk>
-
- * texinfo.tex (LaTex): Add def.
-
-2005-02-06 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (TeX Language Mode): Add mention of LaTeX mode, and
- change name to "TeX and LaTeX Language Modes." Mention LaTeX mode
- throughout manual.
-
-2005-02-06 Lute Kamstra <lute@gnu.org>
-
- * basic.texi (Undo): Fix typo.
-
- * cmdargs.texi (Emacs Invocation): Fix typo.
-
- * custom.texi (Init Examples): Fix typo.
-
- * abbrevs.texi (Expanding Abbrevs): Fix typo.
-
-2005-02-06 Richard M. Stallman <rms@gnu.org>
-
- * regs.texi (Registers): Registers can hold numbers, too.
-
- * killing.texi (Other Kill Commands): Cleanup.
- Delete redundant explanation of kill in read-only buffer.
- (Yanking): Mention term "copying".
- (Accumulating Text): Fix typo.
-
- * entering.texi (Entering Emacs): Update rationale at start.
- (Exiting): Treat iconifying on a par with suspension.
-
- * custom.texi (Minor Modes): Fix typo.
- (Easy Customization): Fix menu style.
- (Variables): Add xref.
- (Examining): Setting for future sessions works through .emacs.
- (Keymaps): "Text terminals", not "Many".
- (Init Rebinding): Explain \C-. Show example of \M-.
- Fix minor wording errors.
- (Function Keys): Explain vector syntax just once.
- (Named ASCII Chars): Clarify history of TAB/C-i connection.
- (Init File): Mention .emacs.d directory.
- (Init Examples): Add xref.
- (Find Init): Mention .emacs.d directory.
-
- * cmdargs.texi (Emacs Invocation): +LINENUM is also an option.
- (Action Arguments): Explain which kinds of -l args are found how.
- (Initial Options): --batch does not inhibit site-start.
- Add xrefs.
- (Command Example): Use --batch, not -batch.
-
- * basic.texi (Inserting Text): Cleanup wording.
- (Moving Point): Doc PRIOR, PAGEUP, NEXT, PAGEDOWN more systematically.
- C-n is not error at end of buffer.
- (Undo): Doc C-/ like C-_. Add xrefs.
- (Arguments): META key may be labeled ALT.
- Peculiar arg meanings are explained in doc strings.
-
- * abbrevs.texi (Expanding Abbrevs): Clarify.
-
-2005-02-05 Eli Zaretskii <eliz@gnu.org>
-
- * frames.texi (Frame Parameters): Add an xref to the description
- of list-colors-display. Add a pointer to the X docs about colors.
-
- * cmdargs.texi (Colors): Mention 16-, 88- and 256-color modes.
- Impove docs of list-colors-display.
-
-2005-02-03 Lute Kamstra <lute@gnu.org>
-
- * frames.texi (Frames, Drag and Drop): Fix typos.
-
-2005-02-03 Richard M. Stallman <rms@gnu.org>
-
- * windows.texi (Basic Window): Mention color-change in mode line.
- (Change Window): Explain dragging vertical boundaries.
-
- * text.texi (Sentences): Clarify.
- (Paragraphs): Explain M-a and blank lines.
- (Outline Mode): Clarify text and menu.
- (Hard and Soft Newlines): Mention use-hard-newlines.
-
- * frames.texi (Frames): Delete unnecessary mention of Windows.
- (Mouse Commands): Likewise. Mention xterm mouse support.
- (Clipboard): Clarify.
- (Mouse References): Mention use of Mouse-1 for following links.
- (Menu Mouse Clicks): Clarify.
- (Mode Line Mouse): Clarify.
- (Drag and Drop): Rewrite.
-
- * fixit.texi (Spelling): Fix typo.
-
- * files.texi (File Names): Clarify.
- (Visiting): Update conditions for use of file dialog. Clarify.
- (Saving): Doc d as answer in save-some-buffers.
- (Remote Files): Clean up the text.
-
- * dired.texi (Misc Dired Commands): Delete dired-marked-files.
-
- * buffers.texi (Select Buffer): Doc next-buffer and prev-buffer.
- (List Buffers): Clarify.
- (Several Buffers): Doc T command.
- (Buffer Convenience): Clarify menu.
-
- * basic.texi (Undo): Clarify last change.
-
-2005-02-02 Matt Hodges <MPHodges@member.fsf.org>
-
- * fixit.texi (Spelling): Fix typo.
-
-2005-02-01 Luc Teirlinck <teirllm@auburn.edu>
-
- * basic.texi (Undo): Update description of `undo-outer-limit'.
-
-2005-02-01 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi: Update documentation relating to GDB Graphical
- Interface.
-
-2005-01-30 Luc Teirlinck <teirllm@auburn.edu>
-
- * custom.texi (Easy Customization): Adapt menu to node name change.
-
-2005-01-30 Richard M. Stallman <rms@gnu.org>
-
- * custom.texi (Easy Customization): Defn of "User Option" now
- includes faces. Don't say just "option" when talking about variables.
- Do say just "options" to mean "anything customizable".
- (Specific Customization): Describe `customize-variable',
- not `customize-option'.
-
- * glossary.texi (Glossary) <Faces>: Add xref.
- <User Option>: Change definition--include faces. Change xref.
-
- * picture.texi (Picture): Mention artist.el.
-
- * sending.texi, screen.texi, programs.texi, misc.texi:
- * mini.texi, major.texi, maintaining.texi, macos.texi:
- * help.texi, frames.texi, files.texi:
- Don't say just "option" when talking about variables.
-
- * display.texi, mule.texi: Don't say just "option" when talking
- about variables. Other minor cleanups.
-
-2005-01-28 Lars Magne Ingebrigtsen <larsi@gnus.org>
-
- * gnus.texi: Some edits based on comments from David Abrahams.
-
-2005-01-24 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * gnus.texi (RSS): Fix the keystroke.
-
-2005-01-26 Lute Kamstra <lute@gnu.org>
-
- * cmdargs.texi (Initial Options): Add a cross reference to `Init
- File'. Mention the `-Q' option at the `--no-site-file' option.
-
-2005-01-24 David Kastrup <dak@gnu.org>
-
- * faq.texi: Update AUCTeX version info.
-
-2005-01-16 Xavier Maillard <zedek@gnu-rox.org> (tiny change)
-
- * gnus-faq.texi ([4.1]): Typo.
-
-2005-01-22 David Kastrup <dak@gnu.org>
-
- * building.texi (Grep Searching): Mention alias `find-grep' for
- `grep-find'.
-
-2005-01-20 Richard M. Stallman <rms@gnu.org>
-
- * calendar.texi (Time Intervals): Delete special stuff for MS-DOS.
-
-2005-01-19 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Keep Arguments): Mention that keeping arguments
- doesn't work with keyboard macros.
-
-2005-01-16 Richard M. Stallman <rms@gnu.org>
-
- * autotype.texi (Autoinserting): Fix small error.
-
-2005-01-16 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.0.47.
-
- * tramp.texi (Compilation): New section, describing compilation of
- remote files.
-
-2005-01-15 Sergey Poznyakoff <gray@Mirddin.farlep.net>
-
- * rmail.texi (Movemail): Explain differences
- between standard and mailutils versions of movemail.
- Describe command line and configuration options introduced
- with the latter.
- Explain the notion of mailbox URL, provide examples and
- cross-references to mailutils documentation.
- Describe various methods of specifying mailbox names,
- user names and user passwords for rmail.
- (Remote Mailboxes): New section. Describe
- how movemail handles remote mailboxes. Describe configuration
- options used to control its behavior.
- (Other Mailbox Formats): Explain handling of various mailbox
- formats.
-
-2005-01-13 Richard M. Stallman <rms@gnu.org>
-
- * commands.texi (Commands): Clarification.
-
-2005-01-11 Richard M. Stallman <rms@gnu.org>
-
- * programs.texi (Multi-line Indent): Fix previous change.
- (Fortran Autofill): Simplify description of fortran-auto-fill-mode.
-
-2005-01-11 Kim F. Storm <storm@cua.dk>
-
- * widget.texi (Basic Types): Add :follow-link keyword.
-
-2005-01-09 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Basic Commands): Describe new behavior of calc-reset.
-
-2005-01-08 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Faces): isearch-lazy-highlight-face renamed to
- lazy-highlight.
-
- * search.texi (Query Replace): Mention faces query-replace
- and lazy-highlight.
- (Incremental Search): Update isearch highlighting info.
-
-2005-01-08 Jay Belanger <belanger@truman.edu>
-
- * calc.texi: Change throughout to reflect new default value of
- calc-settings-file.
-
-2005-01-06 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * message.texi (Reply): `message-reply-to-function' should return
- a list. Suggested by ARISAWA Akihiro <ari@mbf.ocn.co.jp>.
-
-2005-01-06 Hiroshi Fujishima <pooh@nature.tsukuba.ac.jp> (tiny change)
-
- * faq.texi (Changing load-path): Fix typo.
-
-2005-01-05 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Programming Tutorial): Replace kbd command by
- appropriate characters for a keyboard macro.
-
-2005-01-04 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Basic Tutorial, Programming Tutorial): Remove caveats
- for Lucid Emacs.
- (Programming Tutorial): Mention that the user needs to be in the
- right mode to compute some functions.
-
-2005-01-04 Richard M. Stallman <rms@gnu.org>
-
- * custom.texi (Saving Customizations): Minor improvement.
-
-2005-01-04 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Rewrite rules): Remove an exercise (on 0^0) which is
- no longer applicable.
-
-2005-01-03 Luc Teirlinck <teirllm@auburn.edu>
-
- * custom.texi (Saving Customizations): Emacs no longer loads
- `custom-file' after .emacs. No longer mention customizing through
- Custom.
-
-2005-01-01 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Programming Tutorial): Changed description of how to
- edit keyboard macros to match current behavior.
-
-2005-01-01 Andreas Schwab <schwab@suse.de>
-
- * killing.texi (Graphical Kill): Move up under node Killing,
- change @section to @subsection.
-
-2005-01-01 Richard M. Stallman <rms@gnu.org>
-
- * custom.texi (Face Customization): Mention hex color specs.
-
- * emacs.texi (Top): Update Killing submenu.
-
- * killing.texi (Killing): Reorganize section.
- No more TeX-only text; put the node command at start of chapter.
- But the first section heading is used only in TeX.
- Rewrite the text to read better in this mode.
- (Graphical Kill): New subnode gets some of the text that
- used to be in the first section.
-
-2004-12-31 Richard M. Stallman <rms@gnu.org>
-
- * dired.texi (Shell Commands in Dired): Delete the ? example.
-
- * display.texi (Scrolling): Correct scroll-preserve-screen-position.
-
- * files.texi (Saving): Describe new require-final-newline features
- and mode-require-final-newline.
-
-2004-12-31 Jay Belanger <belanger@truman.edu>
-
- * calc.texi: Mention C-cC-c as the way to finish editing throughout.
-
-2004-12-29 Richard M. Stallman <rms@gnu.org>
-
- * custom.texi (File Variables): Clarify previous change.
-
-2004-12-27 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * frames.texi (Dialog Boxes): Mention Gtk+ 2.6 also, as that version is
- out now.
-
-2004-12-27 Richard M. Stallman <rms@gnu.org>
-
- * Makefile.in (MAKEINFO): Specify --force.
-
- * basic.texi (Moving Point): C-e now runs move-end-of-line.
- (Undo): Doc undo-outer-limit.
-
-2004-12-20 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Types Tutorial): Emphasize that you can't divide by
- zero.
-
-2004-12-17 Luc Teirlinck <teirllm@auburn.edu>
-
- * cc-mode.texi (Text Filling and Line Breaking): Put period after
- @xref.
- (Font Locking): Avoid @strong{Note:}.
-
-2004-12-17 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.0.46.
-
- * tramp.texi (bottom): Add arch-tag. It was lost, somehow.
-
-2004-12-16 Luc Teirlinck <teirllm@auburn.edu>
-
- * url.texi: Correct typos.
- (Retrieving URLs): @var{nil}->@code{nil}.
- (HTTP language/coding, mailto): Replace "GNU Emacs Manual" with
- the standard "The GNU Emacs Manual" in fifth argument of @xref's.
- (Dealing with HTTP documents): @inforef->@xref.
-
-2004-12-15 Juri Linkov <juri@jurta.org>
-
- * mark.texi (Transient Mark, Mark Ring): M-< and other
- movement commands don't set mark in Transient Mark mode
- if mark is active.
-
-2004-12-15 Jay Belanger <belanger@truman.edu>
-
- * calc.texi: Consistently capitalized all mode names.
- (Answers to Exercises): Mention that an answer can be a fraction
- when in Fraction mode.
-
-2004-12-13 Jay Belanger <belanger@truman.edu>
-
- * calc.texi: Fix some TeX definitions.
-
-2004-12-12 Juri Linkov <juri@jurta.org>
-
- * misc.texi (FFAP): Add C-x C-r, C-x C-v, C-x C-d,
- C-x 4 r, C-x 4 d, C-x 5 r, C-x 5 d.
-
- * dired.texi (Dired Navigation): Add @r{(Dired)} to M-g.
- (Misc Dired Commands): Add @r{(Dired)} to w.
-
-2004-12-12 Juri Linkov <juri@jurta.org>
-
- * mark.texi (Marking Objects): Marking commands also extend the
- region when mark is active in Transient Mark mode.
-
-2004-12-09 Luc Teirlinck <teirllm@auburn.edu>
-
- * reftex.texi (Imprint): Remove erroneous @value's.
-
-2004-12-08 Luc Teirlinck <teirllm@auburn.edu>
-
- * custom.texi (Saving Customizations): Emacs only loads the custom
- file automatically after the init file in version 22.1 or later.
- Adapt text and examples to this fact.
-
- * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, $(infodir)/org)
- (org.dvi, $(infodir)/url, url.dvi, clean): Add org and url manuals.
-
-2004-12-08 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Starting Calc): Remove comment about installation.
- (Keypad Mode Overview): Remove comment about Emacs 19 support.
-
-2004-12-08 Luc Teirlinck <teirllm@auburn.edu>
-
- * url.texi: Update @setfilename.
- (Getting Started): No need to worry about Gnus versions.
- (Dealing with HTTP documents): Use @inforef.
-
- * org.texi: Fix @direntry file name.
-
-2004-12-07 Luc Teirlinck <teirllm@auburn.edu>
-
- * frames.texi (Scroll Bars): The option `scroll-bar-mode' has to
- be set through Custom. Otherwise, it has no effect.
-
-2004-12-07 Stefan <monnier@iro.umontreal.ca>
-
- * url.texi: New file.
-
- * Makefile.in (INFO_TARGETS, DVI_TARGETS, ../info/url, url.dvi): Add it.
-
-2004-12-06 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Using Calc): Remove paragraph about installation.
-
-2004-12-06 Jay Belanger <belanger@truman.edu>
-
- * calc.texi: Use more Texinfo macros and less TeX defs.
- Remove @refill's.
-
-2004-12-06 Richard M. Stallman <rms@gnu.org>
-
- * org.texi: New file.
-
-2004-12-05 Richard M. Stallman <rms@gnu.org>
-
- * cmdargs.texi, doclicense.texi, xresources.texi, emacs.texi:
- * entering.texi: Rename Command Line to Emacs Invocation.
-
- * Makefile.in (org.dvi, ../info/org): New targets.
- (INFO_TARGETS): Add ../info/org.
- (DVI_TARGETS): Add org.dvi.
- (maintainer-clean): Remove the info files in the info dir.
-
- * misc.texi (Term Mode): Correcty describe C-c.
-
- * custom.texi (Easy Customization): Move up to section level,
- before Variables. Avoid using the term "variable"; say "option".
- New initial explanation.
- (Variables): In initial explanation, connect "variable" to the
- already-explained "user option".
-
- * emacs.texi (Top): Fix ref to Command Line.
- Move reference to Easy Customization.
-
- * xresources.texi (X Resources): Fix From link.
-
- * doclicense.texi (GNU Free Documentation License): Fix To link.
-
- * entering.texi (Entering Emacs): Fix xref, now to Command Line.
-
- * cmdargs.texi (Command Line): Node renamed from Command Arguments.
-
-2004-12-03 Richard M. Stallman <rms@gnu.org>
-
- * cmdargs.texi (Initial Options): Clarify batch mode i/o.
-
-2004-12-01 Luc Teirlinck <teirllm@auburn.edu>
-
- * kmacro.texi: Several small changes in addition to the following.
- (Keyboard Macro Ring): Describe behavior of `C-x C-k C-k' when
- defining a keyboard macro.
- Mention `kmacro-ring-max'.
- (Keyboard Macro Counter): Clarify description of
- `kmacro-insert-counter', `kmacro-set-counter',
- `kmacro-add-counter' and `kmacro-set-format'.
-
-2004-11-29 Reiner Steib <Reiner.Steib@gmx.de>
-
- * custom.texi (File Variables): Add `unibyte' and make it more
- clear that `unibyte' and `coding' are special. Suggested by Simon
- Krahnke <overlord@gmx.li>.
-
- * mule.texi (Enabling Multibyte): Refer to File Variables.
- Suggested by Simon Krahnke <overlord@gmx.li>.
-
-2004-11-26 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * frames.texi (Dialog Boxes): Rename use-old-gtk-file-dialog to
- x-use-old-gtk-file-dialog.
-
-2004-11-26 Eli Zaretskii <eliz@gnu.org>
-
- * idlwave.texi: Fix the setfilename directive to put the produced
- file in ../info.
- (Continued Statement Indentation): Resurrect Jan D.'s change from
- 2004-11-03 that was lost when a newer version of idlwave.texi was
- imported.
-
-2004-11-20 Richard M. Stallman <rms@gnu.org>
-
- * text.texi (Fill Prefix): M-q doesn't apply fill prefix to first line.
-
-2004-11-09 Lars Brinkhoff <lars@nocrew.org>
-
- * building.texi (Lisp Eval): Delete hyphen in section name.
-
-2004-11-19 Thien-Thi Nguyen <ttn@gnu.org>
-
- * files.texi (Old Versions):
- No longer document annotation as "CVS only".
-
-2004-11-10 Andre Spiegel <spiegel@gnu.org>
-
- * files.texi (Version Control): Rewrite the introduction about
- version systems, mentioning the new ones that we support. Thanks
- to Alex Ott, Karl Fogel, Stefan Monnier, and David Kastrup for
- suggestions.
-
-2004-12-08 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus-faq.texi ([5.1]): Added missing bracket.
-
- * gnus.texi (Filtering Spam Using The Spam ELisp Package): Index
- `spam-initialize'.
-
-2004-11-22 Reiner Steib <Reiner.Steib@gmx.de>
-
- * message.texi (Various Message Variables): Mention that all mail
- file variables are derived from `message-directory'.
-
- * gnus.texi (Splitting Mail): Clarify bogus group.
-
-2004-11-02 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * emacs-mime.texi (Encoding Customization): Fix
- mm-coding-system-priorities entry.
-
-2004-11-03 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * frames.texi (Dialog Boxes):
- * idlwave.texi (Continued Statement Indentation):
- * reftex.texi (Options (Index Support)):
- (Displaying and Editing the Index, Table of Contents):
- * speedbar.texi (Creating a display, Major Display Modes): Replace
- non-nil with non-@code{nil}.
-
-2004-11-02 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * frames.texi (Dialog Boxes): Document use-old-gtk-file-dialog.
-
-2004-10-23 Eli Zaretskii <eliz@gnu.org>
-
- * text.texi (Text Based Tables, Table Definition)
- (Table Creation, Table Recognition, Cell Commands)
- (Cell Justification, Row Commands, Column Commands)
- (Fixed Width Mode, Table Conversion, Measuring Tables)
- (Table Misc): New nodes, documenting the Table Mode.
-
-2004-10-21 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Algebraic-Style Calculations): Removed a comment.
-
-2004-10-19 Jason Rumney <jasonr@gnu.org>
-
- * makefile.w32-in (info): Change order of arguments to makeinfo.
-
-2004-10-19 Ulf Jasper <ulf.jasper@web.de>
-
- * calendar.texi (iCalendar): Update for package changes.
-
-2004-10-18 Luc Teirlinck <teirllm@auburn.edu>
-
- * calc.texi (Reporting Bugs): Double up `@'.
-
-2004-10-18 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Reporting Bugs): Changed the address that bugs
- should be sent to.
-
-2004-10-15 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (New Features): Add 5.11.
-
- * message.texi (Resending): Remove wrong default value.
-
- * gnus.texi (Mail Source Specifiers): Describe possible problems
- of `pop3-leave-mail-on-server'. Add `pop3-movemail' and
- `pop3-leave-mail-on-server' to the index.
-
-2004-10-15 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * message.texi (Canceling News): Add how to set a password.
-
-2004-10-12 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Help Commands): Changed the descriptions of
- calc-describe-function and calc-describe-variable to match their
- current behavior.
-
-2004-10-12 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus-faq.texi ([5.9]): Improve code for reply-in-news.
-
-2004-10-12 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.0.45.
-
- * tramp.texi (Frequently Asked Questions): Comment paragraph about
- plink link. The URL is outdated. Originator contacted for
- clarification.
-
-2004-10-10 Juri Linkov <juri@jurta.org>
-
- * gnus.texi (Top, Marking Articles): Join two menus in one node
- because a node can have only one menu.
-
-2004-10-09 Luc Teirlinck <teirllm@auburn.edu>
-
- * files.texi (Misc File Ops): View mode is a minor mode.
-
-2004-10-09 Juri Linkov <juri@jurta.org>
-
- * gnus.texi (Fancy Mail Splitting): Remove backslash in the
- example of nnmail-split-fancy.
-
-2004-10-08 Glenn Morris <gmorris@ast.cam.ac.uk>
-
- * calendar.texi (iCalendar): Style changes.
-
-2004-10-07 Luc Teirlinck <teirllm@auburn.edu>
-
- * search.texi (Regexps): The regexp described in the example is no
- longer stored in the variable `sentence-end'.
-
-2004-10-06 Karl Berry <karl@gnu.org>
-
- * info.texi (@kbd{1}--@kbd{9}): No space around --, for
- consistency with other uses of dashes.
-
-2004-10-06 Nick Roberts <nickrob@snap.net.nz>
-
- * building.texi (Starting GUD): Note that multiple debugging
- sessions requires `gdb --fullname'.
-
-2004-10-05 Ulf Jasper <ulf.jasper@web.de>
-
- * calendar.texi (iCalendar): New section for a new package.
-
-2004-10-05 Karl Berry <karl@gnu.org>
-
- * info.texi: Consistently use --- throughout, periods at end of
- menu descriptions, and a couple typos.
-
-2004-10-05 Luc Teirlinck <teirllm@auburn.edu>
-
- * text.texi: Various small changes in addition to the following.
- (Text): Replace xref for autotype with inforef.
- (Sentences): Explain nil value for `sentence-end'.
- (Paragraphs): Update default values for `paragraph-start' and
- `paragraph-separate'.
- (Text Mode): Correct description of Text mode's effect on the
- syntax table.
- (Outline Visibility): `hide-other' does not hide top level headings.
- `selective-display-ellipses' no longer has an effect on Outline mode.
- (TeX Misc): Add missing @cindex.
- Replace xref for RefTeX with inforef.
- (Requesting Formatted Text): The variable
- `enriched-fill-after-visiting' no longer exists.
- (Editing Format Info): Update names of menu items and commands.
- (Format Faces): Mention special effect of specifying the default face.
- Describe inheritance of text properties.
- Correct description of `fixed' face.
- (Format Indentation): Correct description of effect of setting
- margins. Mention `set-left-margin' and `set-right-margin'.
- (Format Justification): Update names of menu items.
- `set-justification-full' is now bound to `M-j b'.
- Mention that `default-justification' is a per buffer variable.
- (Format Properties): Update name of menu item.
- (Forcing Enriched Mode): `format-decode-buffer' automatically
- turns on Enriched mode if the buffer is in text/enriched format.
-
-2004-10-05 Emilio C. Lopes <eclig@gmx.net>
-
- * calendar.texi (From Other Calendar): Add calendar-goto-iso-week.
-
-2004-09-28 Kim F. Storm <storm@cua.dk>
-
- * display.texi (Display Custom) <indicate-buffer-boundaries>:
- Align with new functionality.
-
-2004-09-26 Jesper Harder <harder@ifa.au.dk>
-
- * sieve.texi (Manage Sieve API): nil -> @code{nil}.
- * pgg.texi (User Commands, Backend methods): Do.
- * gnus.texi: Markup fixes.
- (Setting Process Marks): Fix `M P a' entry.
- * emacs-mime.texi: Fixes.
-
-2004-09-23 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus-faq.texi ([5.12]): Fix code example for FQDN in Message-Ids
- again.
- Use 5.10 instead of 5.10.0.
-
-2004-09-20 Lars Magne Ingebrigtsen <larsi@gnus.org>
-
- * gnus.texi (Summary Mail Commands): S D e.
-
-2004-09-20 Raymond Scholz <ray-2004@zonix.de> (tiny change)
-
- * gnus.texi (Misc Article): Refer to `Summary Buffer Mode Line' in
- the gnus-article-mode-line-format section.
-
-2004-09-20 Helmut Waitzmann <Helmut.Waitzmann@web.de> (tiny change)
-
- * gnus.texi (Various Summary Stuff): Fix the documentation for
- gnus-newsgroup-variables.
-
-2004-09-20 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (MIME Commands): Added
- gnus-mime-display-multipart-as-mixed,
- gnus-mime-display-multipart-alternative-as-mixed,
- gnus-mime-display-multipart-related-as-mixed.
- (Mail Source Customization): Clarify `mail-source-directory'.
- (Splitting Mail): Mention gnus-group-find-new-groups.
- (SpamOracle): Fixed typo.
-
- * gnus-faq.texi: Untabify.
- ([6.3]): nnir.el is in contrib directory.
-
- * message.texi (News Headers): Clarify how a unique ID is created.
-
- * gnus.texi (Batching Agents): Fixed typo in example. Reported
- by Hiroshi Fujishima <pooh@nature.tsukuba.ac.jp>.
-
-2004-09-20 Andre Srinivasan <andre@e2open.com>
-
- * gnus.texi (Group Parameters): Added more on hooks. (Small
- change.)
-
-2004-09-20 Florian Weimer <fw@deneb.enyo.de>
-
- * gnus.texi (Charsets): Point to relevant section in emacs-mime.
-
-2004-09-22 Luc Teirlinck <teirllm@auburn.edu>
-
- * display.texi (Display Custom): Remove stray `@end defvar'.
-
-2004-09-23 Kim F. Storm <storm@cua.dk>
-
- * display.texi (Display Custom): Add `overflow-newline-into-fringe',
- `indicate-buffer-boundaries' and `default-indicate-buffer-boundaries'.
-
-2004-09-22 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Vectors as Lists): Added a warning that the tutorial
- might be hidden during part of the session.
-
-2004-09-20 Jay Belanger <belanger@truman.edu>
-
- * calc.texi (Notations Used in This Manual): Put in an earlier
- mention that DEL could be called Backspace.
-
-2004-09-20 Richard M. Stallman <rms@gnu.org>
-
- * custom.texi (Hooks): Explain using setq to clear out a hook.
- (File Variables): Explain multiline string constants.
- (Non-ASCII Rebinding): Explain when you need to update
- non-ASCII char codes in .emacs.
-
- * building.texi (Compilation): Explain how to make a silent
- subprocess that won't be terminated. Explain compilation-environment.
-
-2004-09-13 Kim F. Storm <storm@cua.dk>
-
- * mini.texi (Repetition): Rename isearch-resume-enabled to
- isearch-resume-in-command-history and change default to disabled.
-
-2004-09-10 Simon Josefsson <jas@extundo.com>
-
- * gnus.texi (IMAP): Add example. Suggested and partially written
- by Steinar Bang <sb@dod.no>.
-
-2004-09-10 Teodor Zlatanov <tzz@lifelogs.com>
-
- * gnus.texi (IMAP): Add comments about imaps synonym to imap in
- netrc syntax.
-
-2004-09-10 Teodor Zlatanov <tzz@lifelogs.com>
-
- * gnus.texi (Spam ELisp Package Sequence of Events): Some clarifications.
- (Spam ELisp Package Global Variables): More clarifications.
-
-2004-09-10 Teodor Zlatanov <tzz@lifelogs.com>
-
- * gnus.texi (Spam ELisp Package Filtering of Incoming Mail):
- Mention spam-split does not modify incoming mail.
-
-2004-09-10 Teodor Zlatanov <tzz@lifelogs.com>
-
- * gnus.texi (Spam ELisp Package Sequence of Events): Fix typo.
-
-2004-09-10 Eli Zaretskii <eliz@gnu.org>
-
- * Makefile.in (../info/gnus, gnus.dvi): Depend on gnus-faq.texi.
-
-2004-09-09 Kim F. Storm <storm@cua.dk>
-
- * kmacro.texi (Save Keyboard Macro): Replace `name-last-kbd-macro'
- with new `kmacro-name-last-macro'.
-
-2004-09-09 Reiner Steib <Reiner.Steib@gmx.de>
-
- * makefile.w32-in (sieve, pgg): Use $(infodir).
-
-2004-09-08 Juri Linkov <juri@jurta.org>
-
- * mini.texi (Minibuffer History): Add `history-delete-duplicates'.
-
-2004-09-08 Dhruva Krishnamurthy <dhruva.krishnamurthy@gmail.com> (tiny change)
-
- * makefile.w32-in: Fix PGG and Sieve entries.
-
-2004-09-03 Juri Linkov <juri@jurta.org>
-
- * search.texi (Incremental Search): Update wording for M-%.
-
-2004-09-02 Luc Teirlinck <teirllm@auburn.edu>
-
- * killing.texi (Killing): Correct description of kill commands in
- read-only buffer.
-
-2004-09-02 Teodor Zlatanov <tzz@lifelogs.com>
-
- * building.texi (Compilation Mode): Add a paragraph about rules
- for finding the compilation buffer for `next-error'.
-
- * search.texi (Other Repeating Search): Mention that Occur mode
- supports the next-error functionality.
-
-2004-09-02 Juri Linkov <juri@jurta.org>
-
- * search.texi (Regexp Replace): Add missing backslash to \footnote.
-
-2004-08-31 Luc Teirlinck <teirllm@auburn.edu>
-
- * kmacro.texi (Basic Keyboard Macro):
- `apply-macro-to-region-lines' now operates on all lines that begin
- in the region, rather than on all complete lines in the region.
-
-2004-08-31 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * frames.texi (Drag and drop): Add documentation about
- x-dnd-test-function and x-dnd-known-types.
-
-2004-08-30 Luc Teirlinck <teirllm@auburn.edu>
-
- * indent.texi: Various minor changes in addition to:
- (Indentation Commands): Correct description of `indent-relative'.
- (Tab Stops): <TAB> is no longer bound to `tab-to-tab-stop' in Text
- mode. The *Tab Stops* buffer uses Overwrite Mode.
- (Just Spaces): `tabify' converts sequences of at least two spaces
- to tabs.
-
-2004-08-28 Eli Zaretskii <eliz@gnu.org>
-
- * faq.texi (Emacs for MS-DOS): Update URLs for the MS-DOS port of
- Emacs and related programs.
-
-2004-08-27 Luc Teirlinck <teirllm@auburn.edu>
-
- * frames.texi (Secondary Selection): Setting the secondary
- selection with M-Drag-Mouse-1 does not alter the kill ring,
- setting it with M-Mouse-1 and M-Mouse-3 does.
- (Mode Line Mouse): C-Mouse-2 on scroll bar now also works for
- toolkit scroll bars.
- (Scroll Bars): Ditto.
-
- * windows.texi (Basic Window): When using a window system, the value
- of point in a non-selected window is indicated by a hollow box.
- (Split Window): Side by side windows are separated by a scroll bar,
- if scroll bars are used.
- C-Mouse-2 on scroll bar now also works for toolkit scroll bars.
- (Change Window): Correct Mouse-2 vs Mouse-3 mess-up.
- (Window Convenience): Update bindings for `winner-undo' and
- `winner-redo'.
-
- * ack.texi (Acknowledgments): Use `@unnumbered'.
- * misc.texi : Adapt sectioning in Info to the node structure.
- (Invoking emacsclient): Make "Invoking emacsclient" a subsection
- of "Using Emacs as a Server".
- * building.texi (Building): Interchange nodes (for correct numbering).
- * programs.texi (Programs): Interchange nodes (for correct numbering).
- * killing.texi, entering.texi, commands.texi: Adapt sectioning in
- Info to the node structure.
- * emacs.texi: Make "GNU GENERAL PUBLIC LICENSE" an appendix.
- Rearrange order of nodes and sections such that both "GNU GENERAL
- PUBLIC LICENSE" and "GNU Free Documentation License" appear at the
- end, as appropriate for appendices.
- (Acknowledgments): Put inside @iftex instead of @ifnotinfo.
- Use `@unnumberedsec'.
- * trouble.texi: Adapt sectioning in Info to the node structure.
- Adapt node pointers to change in emacs.texi.
- * cmdargs.texi, doclicense.texi: Adapt node pointers.
-
-2004-08-27 Richard M. Stallman <rms@gnu.org>
-
- * faq.texi: Fix texinfo usage, esp. doublequotes.
- (Difference between Emacs and XEmacs): Some clarification.
-
- * faq.texi (Difference between Emacs and XEmacs):
- Explain not to contrast XEmacs with GNU Emacs.
-
-2004-08-26 Richard M. Stallman <rms@gnu.org>
-
- * faq.texi (Difference between Emacs and XEmacs): Rewrite.
-
-2004-08-25 Kenichi Handa <handa@m17n.org>
-
- * custom.texi (Non-ASCII Rebinding): Fix and simplify the
- description for unibyte mode.
-
-2004-08-23 Luc Teirlinck <teirllm@auburn.edu>
-
- * display.texi (Font Lock): Correct invalid (for hardcopy) @xref.
-
- * search.texi (Regexps): Correct cryptic (in hardcopy) @ref.
- (Configuring Scrolling): Correct invalid (for hardcopy) @xref.
- (Regexp Replace): Standardize reference to hardcopy Elisp Manual
- in @pxref.
-
-2004-08-22 Luc Teirlinck <teirllm@auburn.edu>
-
- * kmacro.texi (Keyboard Macro Counter, Keyboard Macro Step-Edit):
- Change section names.
-
-2004-08-22 David Kastrup <dak@gnu.org>
-
- * reftex.texi (AUCTeX): Update links, section name.
-
- * faq.texi (Calc): Update availability (included in 22.1).
- (AUCTeX): Update availability, information, versions, description.
-
-2004-08-21 Luc Teirlinck <teirllm@auburn.edu>
-
- * kmacro.texi (Keyboard Macro Ring): Rename section.
- Emacs treats the head of the macro ring as the `last keyboard macro'.
- (Keyboard Macro Counter): Minor change.
- (Save Keyboard Macro): Some clarifications.
- (Edit Keyboard Macro): Rename section.
-
- * buffers.texi (Buffers): Maximum buffer size is now 256M on
- 32-bit machines.
- (Several Buffers): Clarify which buffer is selected if `2' is
- pressed in the Buffer Menu.
- Auto Revert mode can be used to update the Buffer Menu
- automatically.
-
-2004-08-21 Eli Zaretskii <eliz@gnu.org>
-
- * help.texi (Misc Help): Add an index entry for finding an Info
- manual by its file name.
-
-2004-08-20 Luc Teirlinck <teirllm@auburn.edu>
-
- * files.texi (Backup Deletion): Correct description of
- `delete-old-versions'.
- (Time Stamps): `time-stamp' needs to be added to `before-save-hook'.
- (Auto Save Files): Recommend `auto-save-mode' to reenable
- auto-saving, rather than the abbreviation `auto-save'.
-
-2004-08-17 Luc Teirlinck <teirllm@auburn.edu>
-
- * emacs.texi (Top): Mention "cutting" and "pasting" as synonyms
- for "killing" and "yanking" in main menu.
-
-2004-08-16 Richard M. Stallman <rms@gnu.org>
-
- * killing.texi (Yanking, Killing): Minor cleanups.
-
- * mark.texi (Momentary Mark): Minor cleanups.
-
-2004-08-15 Kenichi Handa <handa@etl.go.jp>
-
- * custom.texi (Non-ASCII Rebinding):
- C-q always inserts the right code to pass to global-set-key.
-
-2004-08-14 Eli Zaretskii <eliz@gnu.org>
-
- * Makefile.in (../info/tramp, tramp.dvi): Depend on trampver.texi.
-
-2004-08-13 Luc Teirlinck <teirllm@auburn.edu>
-
- * regs.texi (RegNumbers): Mention `C-x r i' binding for
- `insert-register', instead of `C-x r g' binding, for consistency.
-
-2004-08-12 Luc Teirlinck <teirllm@auburn.edu>
-
- * fixit.texi (Spelling): Fix typo.
-
-2004-08-11 Luc Teirlinck <teirllm@auburn.edu>
-
- * help.texi (Help): Fix Texinfo usage.
-
-2004-08-11 Martin Stjernholm <bug-cc-mode@gnu.org>
-
- * cc-mode.texi: Various updates for CC Mode 5.30.9.
-
-2004-08-10 Michael Albinus <michael.albinus@gmx.de>
-
- Sync with Tramp 2.0.44.
-
-2004-08-05 Lars Hansen <larsh@math.ku.dk>
-
- * widget.texi (User Interface): Update how to separate the
- editable field of an editable-field widget from other widgets.
- (Programming Example): Add text after field.
-
-2004-07-24 Richard M. Stallman <rms@gnu.org>
-
- * text.texi (Paragraphs): Update how paragraphs are separated
- and the default for paragraph-separate.
-
- * search.texi (Regexp Replace): Further update text for new
- replacement operators.
-
-2004-08-31 Katsumi Yamaoka <yamaoka@jpl.org>
-
- * emacs-mime.texi (Encoding Customization): Add a note to the
- mm-content-transfer-encoding-defaults entry.
- (rfc2047): Update.
-
- * gnus.texi (Article Highlighting): Add
- gnus-cite-ignore-quoted-from.
- (POP before SMTP): New node.
- (Posting Styles): Addition.
- (Splitting Mail): Add nnmail-split-lowercase-expanded.
- (Fancy Mail Splitting): Ditto.
- (X-Face): Add gnus-x-face.
-
-2004-08-30 Reiner Steib <Reiner.Steib@gmx.de>
-
- * emacs-mime.texi, gnus-faq.texi, gnus.texi, message.texi,
- * pgg.texi, sieve.texi: Use @copying and @insertcopying.
-
-2004-08-22 Reiner Steib <Reiner.Steib@gmx.de>
-
- * gnus.texi (Mail Source Specifiers): Describe
- `pop3-leave-mail-on-server'.
-
-2004-08-02 Reiner Steib <Reiner.Steib@gmx.de>
-
- * Makefile.in, makefile.w32-in: Added PGG and Sieve files.
-
- * pgg.texi, sieve.texi: Import from the v5_10 branch of the Gnus
- repository. Change setfilename.
-
- * emacs-mime.texi, gnus-faq.texi, gnus.texi, message.texi: Ditto.
-
-2004-07-18 Luc Teirlinck <teirllm@auburn.edu>
-
- * emacs-xtra.texi (Subdir switches): Dired does not remember the
- `R' switch.
-
- * dired.texi (Dired Updating): `k' only deletes inserted
- subdirectories from the Dired buffer if a prefix argument was given.
-
- * search.texi (Regexps): Delete redundant definition of `symbol' in
- description of `\_>'. It already occurs in the description of `\_<'.
-
-2004-07-02 Juri Linkov <juri@jurta.org>
-
- * pcl-cvs.texi (Viewing differences): Add `d r'.
-
-2004-07-01 Juri Linkov <juri@jurta.org>
-
- * search.texi (Incremental Search): Add C-M-w, C-M-y, M-%, C-M-%, M-e.
- (Regexp Search): Add M-r.
-
-2004-06-30 Luc Teirlinck <teirllm@auburn.edu>
-
- * makefile.w32-in (EMACSSOURCES): Remove emacs-xtra.
-
-2004-06-29 Jesper Harder <harder@ifa.au.dk>
-
- * ses.texi, viper.texi, search.texi, flymake.texi, faq.texi:
- * eshell.texi, ediff.texi, calendar.texi: Markup fixes.
-
-2004-06-25 Richard M. Stallman <rms@gnu.org>
-
- * search.texi (Regexp Replace): Rewrite description of \# \, and \?.
-
-2004-06-25 David Kastrup <dak@gnu.org>
-
- * search.texi (Regexp Replace): Some typo corrections and
- rearrangement.
-
-2004-06-24 David Kastrup <dak@gnu.org>
-
- * search.texi (Unconditional Replace): Use replace-string instead
- of query-replace in example.
- (Regexp Replace): Add explanations for `\,', `\#' and `\?'
- sequences.
- (Query Replace): Correct explanation of `^' which does not use
- the mark stack.
-
-2004-06-21 Nick Roberts <nickrob@gnu.org>
-
- * misc.texi (Shell History Copying): Document comint-insert-input.
- (Shell Ring): Describe comint-dynamic-list-input-ring here.
-
-2004-06-21 Karl Berry <karl@gnu.org>
-
- * info.texi (Top): Mention that only Emacs has mouse support.
- (Getting Started): Mention this in a few other places.
-
-2004-06-20 Jesper Harder <harder@ifa.au.dk>
-
- * msdog.texi (Text and Binary, MS-DOS Printing): Use m-dash.
- * custom.texi (Customization): Do.
- * anti.texi (Antinews): Do.
- * abbrevs.texi (Defining Abbrevs): Do.
-
- * programs.texi (Info Lookup): Fix keybinding for
- info-lookup-symbol.
-
-2004-06-16 Juanma Barranquero <lektu@terra.es>
-
- * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, EMACSSOURCES):
- Add emacs-xtra.
- ($(infodir)/emacs-xtra, emacs-xtra.dvi): New dependencies.
- (clean): Add emacs-xtra and flymake. Remove redundancies.
-
-2004-06-15 Luc Teirlinck <teirllm@auburn.edu>
-
- * Makefile.in (INFO_TARGETS, DVI_TARGETS, ../info/emacs-xtra):
- Add emacs-xtra.
- * emacs-xtra.texi: New file.
-
-2004-06-14 Luc Teirlinck <teirllm@auburn.edu>
-
- * dired.texi (Dired Enter): Mention conditions on `ls' switches.
- (Dired and Find): Mention differences with ordinary Dired buffers.
-
-2004-06-13 Luc Teirlinck <teirllm@auburn.edu>
-
- * autotype.texi (Copyrights, Timestamps): Recommend
- `before-save-hook' instead of `write-file-functions'.
-
-2004-06-13 Richard M. Stallman <rms@gnu.org>
-
- * custom.texi (Init Syntax): Explain about vars that do special
- things when set with setq or with Custom.
- (Init Examples): Add line-number-mode example.
-
-2004-06-13 Lars Hansen <larsh@math.ku.dk>
-
- * dired-x.texi (dired-mark-omitted): Update keybinding.
-
-2004-06-12 Juri Linkov <juri@jurta.org>
-
- * dired.texi (Operating on Files): Add dired-do-touch.
-
-2004-06-10 Kim F. Storm <storm@cua.dk>
-
- * pcl-cvs.texi (Viewing differences): Add 'd y'.
-
-2004-06-10 Juri Linkov <juri@jurta.org>
-
- * building.texi (Lisp Eval): Add C-M-x on defface.
-
-2004-06-08 Luc Teirlinck <teirllm@auburn.edu>
-
- * files.texi (Reverting): Auto-Revert mode and
- Global Auto-Revert mode no longer revert remote files.
-
-2004-06-05 Lars Hansen <larsh@math.ku.dk>
-
- * dired-x.texi (variable dired-omit-mode): Rename from
- dired-omit-files-p.
- (function dired-omit-mode): Rename from dired-omit-toggle.
- Call dired-omit-mode rather than set dired-omit-files-p.
- (dired-mark-omitted): Describe command.
-
-2004-05-29 Michael Albinus <michael.albinus@gmx.de>
-
- Version 2.0.41 of Tramp released.
-
-2004-05-29 Juanma Barranquero <lektu@terra.es>
-
- * makefile.w32-in (../info/flymake, flymake.dvi): New targets.
- (INFO_TARGETS, DVI_TARGETS): Add Flymake.
-
-2004-05-29 Richard M. Stallman <rms@gnu.org>
-
- * custom.texi (Init File): Two dashes start --no-site-file.
-
- * cl.texi (Top): Call this chapter `Introduction'.
- (Overview): In TeX, no section heading here.
-
- * cc-mode.texi: Put commas after i.e. and e.g. Minor cleanups.
-
-2004-05-29 Alan Mackenzie <acm@muc.de>
-
- * programs.texi: Update for CC Mode 5.30 and incidental amendments.
- ("AWK"): Is consistently thus spelt throughout.
- (AWK, Pike): Document as "C-like modes".
- (@kbd{M-j}): Document as alternative to @kbd{C-M-j}.
- (M-x man): Supersedes M-x manual-entry.
- Add numerous index entries. Correct "ESC a/e" to "M-a/e".
-
- ("Comments in C"): Delete node; the info is in CC Mode manual.
- (c-comment-only-line-offset): Remove description.
-
- (C-c ., C-c C-c): Describe new C Mode bindings.
-
- (C-u TAB, indent-code-rigidly, c-indent-exp, c-tab-always-indent)
- (@dfn{Style}, c-default-style, comment-column, comment-padding)
- (c-up-conditional, c-beginning-of-statement, c-end-of-statement):
- Amend definitions.
-
- (c-beginning-of-defun, c-end-of-defun, c-context-line-break):
- Describe functions.
-
- (c-comment-start-regexp, c-hanging-comment-ender-p)
- (c-hanging-comment-starter-p): Remove obsolete definitions.
-
- * emacs.texi: Remove the menu entry "Comments in C".
-
-2004-05-29 Eli Zaretskii <eliz@gnu.org>
-
- * Makefile.in (../info/flymake, flymake.dvi): New targets.
- (INFO_TARGETS, DVI_TARGETS): Add Flymake.
-
-2004-05-29 Pavel Kobiakov <pk_at_work@yahoo.com>
-
- * flymake.texi: New file.
-
-2004-05-28 Simon Josefsson <jas@extundo.com>
-
- * smtpmail.texi (Authentication): Improve STARTTLS discussion.
-
-2004-05-27 Luc Teirlinck <teirllm@auburn.edu>
-
- * dired.texi (Dired and Find): `find-ls-option' does not apply to
- `M-x locate'.
-
-2004-05-16 Karl Berry <karl@gnu.org>
-
- * emacs.texi (ack.texi) [@ifnottex]: Change condition; with @ifinfo,
- makeinfo --html fails.
- * help.texi (Help Summary) [@ifnottex]: Likewise.
-
-2004-05-13 Nick Roberts <nickrob@gnu.org>
-
- * building.texi (GDB Graphical Interface): Update and describe
- layout first.
-
-2004-05-07 Kai Grossjohann <kai@emptydomain.de>
-
- Version 2.0.40 of Tramp released.
-
-2004-04-25 Michael Albinus <Michael.Albinus@alcatel.de>
-
- Complete rework, based on review by Karl Berry <karl@gnu.org>.
-
- * tramp.texi (Auto-save and Backup): Explain exploitation of new
- variables `tramp-backup-directory-alist' and
- `tramp-bkup-backup-directory-info'.
- (Overview, Connection types)
- (External transfer methods, Default Method)
- (Windows setup hints): Remove restriction of password entering
- with external methods.
- (Auto-save and Backup): Make file name example
- (X)Emacs neutral. In case of XEmacs, `bkup-backup-directory-info'
- and `auto-save-directory' must be used.
- (Frequently Asked Questions): Use "MS Windows NT/2000/XP" (not
- only "NT"). Remove doubled entry "What kinds of systems does
- @tramp{} work on".
- (tramp): Macro removed.
- (Obtaining Tramp): Flag removed from title.
- (all): "tramp-" and "-" removed from flag names. Flags `tramp'
- and `trampver' used properly. Flag `tramp-inst' replaced by
- `installchapter'. Installation related text adapted.
-
-2004-05-04 Jason Rumney <jasonr@gnu.org>
-
- * makefile.w32-in: Revert last change.
-
-2004-05-03 Jason Rumney <jasonr@gnu.org>
-
- * makefile.w32-in (MULTI_INSTALL_INFO, ENVADD): Use forward slashes.
-
-2004-04-28 Masatake YAMATO <jet@gyve.org>
-
- * widget.texi (Programming Example): Remove overlays.
-
-2004-04-27 Jesper Harder <harder@ifa.au.dk>
-
- * faq.texi, viper.texi, dired-x.texi, autotype.texi: lisp -> Lisp.
-
-2004-04-23 Juanma Barranquero <lektu@terra.es>
-
- * makefile.w32-in: Add "-*- makefile -*-" mode tag.
-
-2004-04-18 Juri Linkov <juri@jurta.org>
-
- * fixit.texi (Spelling): Remove file extension from ispell xref.
-
-2004-04-15 Kim F. Storm <storm@cua.dk>
-
- * cmdargs.texi (Initial Options): Add -Q.
-
-2004-04-05 Kim F. Storm <storm@cua.dk>
-
- * custom.texi (File Variables): Add safe-local-eval-forms.
-
-2004-04-05 Jesper Harder <harder@ifa.au.dk>
-
- * info.texi (Info Search): Add info-apropos.
-
-2004-04-02 Luc Teirlinck <teirllm@auburn.edu>
-
- * files.texi (Reverting): Correct description of revert-buffer's
- handling of point.
-
-2004-03-22 Juri Linkov <juri@jurta.org>
-
- * emacs.texi (Top): Add `Misc X'.
-
- * faq.texi, trouble.texi: Fix help key bindings.
-
- * glossary.texi: Improve references.
-
- * help.texi: Sync keywords with finder.el.
-
- * mini.texi (Completion): Add description for menu items.
-
- * misc.texi (Browse-URL, FFAP): Add information about keywords.
-
- * sending.texi (Mail Methods): Fix xref to Message manual.
-
-2004-03-17 Luc Teirlinck <teirllm@auburn.edu>
-
- * info.texi (Advanced): Replace @unnumberedsubsec by @subheading
- (as suggested by Karl Berry). Update information about colored
- stars in menus. Add new subheading describing M-n.
-
-2004-03-12 Richard M. Stallman <rms@gnu.org>
-
- * cl.texi (Top): Rename top node's title.
-
- * buffers.texi (Misc Buffer): Add index entry for rename-uniquely.
-
-2004-03-08 Karl Berry <karl@gnu.org>
-
- * info.texi: \input texinfo.tex instead of just texinfo, to avoid
- problems making the texinfo distribution.
-
-2004-03-04 Richard M. Stallman <rms@gnu.org>
-
- * search.texi (Regexps): Explain that ^ and $ have their
- special meanings only in certain contexts.
-
- * programs.texi (Expressions): Doc C-M-SPC as alias for C-M-@.
-
- * mule.texi (Specify Coding): Doc C-x RET F.
-
- * buffers.texi (Misc Buffer): Explain use of M-x rename-uniquely
- for multiple compile and grep buffers.
- (Indirect Buffers): Don't recommand clone-indirect-buffer
- for multiple compile and grep buffers.
-
-2004-02-29 Simon Josefsson <jas@extundo.com>
-
- * smtpmail.texi (Authentication): Changed the list of supported
- authentication mechanisms from CRAM-MD5, PLAIN and LOGIN-MD5 to
- CRAM-MD5 and LOGIN, tiny patch from Andreas Voegele
- <voegelas@gmx.net>.
-
-2004-02-29 Juanma Barranquero <lektu@terra.es>
-
- * makefile.w32-in (mostlyclean, clean, maintainer-clean):
- Use $(DEL) instead of rm, and ignore exit code.
-
-2004-02-29 Kai Grossjohann <kgrossjo@eu.uu.net>
-
- Tramp version 2.0.39 released.
-
-2004-02-29 Michael Albinus <Michael.Albinus@alcatel.de>
-
- * tramp.texi (Customizing Completion): Explain new functions
- `tramp-parse-shostkeys' and `tramp-parse-sknownhosts'.
- (all): Savannah URLs unified to "http://savannah.nongnu.org".
- (Top): Refer to Savannah mailing list as the major one. Mention
- older mailing lists in HTML mode only.
- (Auto-save and Backup): Add auto-save. Based on wording of Kai.
- (Frequently Asked Questions): Remote hosts must not be Unix-like
- for "smb" method.
- (Password caching): New node.
- (External transfer methods): Refer to password caching for "smb"
- method.
-
-2004-02-23 Nick Roberts <nick@nick.uklinux.net>
-
- * building.texi (Watch Expressions): Update.
-
-2004-02-21 Juri Linkov <juri@jurta.org>
-
- * cmdargs.texi (Action Arguments): Add alias --find-file. Add
- --directory, --help, --version. Move text about command-line-args
- to Command Arguments.
- (Initial Options): Add @cindex for --script. Fix @cindex for -q.
- Add --no-desktop. Add alias --no-multibyte, --no-unibyte.
- (Window Size X): Join -g and --geometry. Add @cindex.
- (Borders X): Fix @cindex for -ib. Add @cindex for -bw.
- (Title X): Remove alias -title.
- (Misc X): New node.
-
-2004-02-17 Karl Berry <karl@gnu.org>
-
- * info.texi (Help-Int): Mention the new line number feature.
-
-2004-02-15 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * frames.texi (Drag and drop): Add Motif to list of supported
- protocols.
-
-2004-02-14 Jonathan Yavner <jyavner@member.fsf.org>
-
- * ses.texi (Advanced Features): New functionality for
- ses-set-header-row (defaults to current row unless C-u used).
- (Acknowledgements): Add Stefan Monnier.
-
-2004-02-03 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * frames.texi (Drag and drop): New section.
-
-2004-01-24 Richard M. Stallman <rms@gnu.org>
-
- * emacs.texi (Acknowledgments): Renamed from Acknowledgements.
- Include it only @ifnotinfo. Patch the preceding and following
- node headers to point to each other.
-
-2004-01-11 Glenn Morris <gmorris@ast.cam.ac.uk>
-
- * calendar.texi (Appointments): Update section.
-
-2003-12-29 Kevin Ryde <user42@zip.com.au>
-
- * viper.texi (Vi Macros): Fix reference to the Emacs manual.
-
- * programs.texi (C Modes): Fix the xref.
-
-2003-12-23 Nick Roberts <nick@nick.uklinux.net>
-
- * building.texi (Watch Expressions): Update.
- (Commands of GUD): Include use of toolbar + breakpoints set from
- fringe/margin.
-
-2003-12-03 Andre Spiegel <spiegel@gnu.org>
-
- * files.texi: Say how to disable VC. Suggested by Alan Mackenzie
- <acm@muc.de>.
-
-2003-11-30 Kai Grossjohann <kai.grossjohann@gmx.net>
-
- Tramp version 2.0.38 released.
-
- * tramp.texi (Remote shell setup): Warn of environment variables
- FRUMPLE if user frumple exists. Suggested by Sven Gabriel
- <sven.gabriel@imk.fzk.de>.
- (Configuration): Tramp now chooses base64/uuencode
- automatically. Update wording accordingly.
- (Top): More description for the `Default Method' menu entry.
- (Default Method): Use @code, not @var, for Lisp variables.
- (Default Method): New subsection `Which method is the right one
- for me?' Suggested by Christian Kirsch.
- (Configuration): Pointer to new subsection added.
- (Default Method): Too many "use" in one sentence.
- Rephrase. Reported by Christian Kirsch.
- (Filename Syntax): Old `su' example is probably a left-over from
- the sm/su method naming. Replace with `ssh', instead.
- (External transfer methods, Auto-save and Backup):
- Typo fixes.
-
-2003-11-02 Michael Albinus <Michael.Albinus@alcatel.de>
-
- * tramp.texi (all): Harmonize all occurences of @tramp{}.
- (Top): Mention japanese manual only if flag `jamanual' is set.
- Insert section `Japanese manual' in menu.
-
-2003-11-29 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * frames.texi (Dialog Boxes): Add use-file-dialog.
-
-2003-11-26 Thien-Thi Nguyen <ttn@gnu.org>
-
- * eshell.texi (Known Problems): Add doc item.
-
-2003-11-22 Martin Stjernholm <bug-cc-mode@gnu.org>
-
- * ack.texi: Note that Alan Mackenzie contributed the AWK support
- in CC Mode.
-
-2003-11-22 Martin Stjernholm <bug-cc-mode@gnu.org>
-
- * cc-mode.texi: Update for CC Mode 5.30.
-
- Note: Please refrain from doing purely cosmetic changes like
- removing trailing whitespace in this manual; it clobbers cvs
- merging for no good reason.
-
-2003-11-02 Jesper Harder <harder@ifa.au.dk> (tiny change)
-
- * man/ack.texi, man/basic.texi, man/cmdargs.texi:
- * man/commands.texi, man/custom.texi, man/display.texi:
- * man/ediff.texi, man/emacs.texi, man/faq.texi, man/files.texi:
- * man/frames.texi, man/glossary.texi, man/killing.texi:
- * man/macos.texi, man/mark.texi, man/misc.texi, man/msdog.texi:
- * man/mule.texi, man/rmail.texi, man/search.texi:
- * man/sending.texi, man/text.texi, man/tramp.texi:
- * man/trouble.texi, man/vip.texi, man/viper.texi, man/widget.texi:
- * man/woman.texi: Replace @sc{ascii} and ASCII with @acronym{ASCII}.
-
-2003-11-01 Alan Mackenzie <acm@muc.de>
-
- * search.texi (Scrolling During Incremental Search): Document a
- new scrolling facility in isearch mode.
-
-2003-10-26 Karl Berry <karl@gnu.org>
-
- * info.texi (Info Search): Echo area, not echo are. From Debian
- diff.
-
-2003-10-26 Per Abrahamsen <abraham@dina.kvl.dk>
-
- * widget.texi (Defining New Widgets): Document new beavior of
- :buttons and :children keywords.
-
-2003-10-22 Miles Bader <miles@gnu.org>
-
- * Makefile.in (info): Move before $(top_srcdir)/info.
-
-2003-10-22 Nick Roberts <nick@nick.uklinux.net>
-
- * building.texi (Watch Expressions): Update section on data display
- to reflect code changes (GDB Graphical Interface).
-
-2003-10-17 Thien-Thi Nguyen <ttn@gnu.org>
-
- * tramp.texi (Inline methods): Small grammar fix.
- (External transfer methods): Likewise.
-
-2003-10-13 Richard M. Stallman <rms@gnu.org>
-
- * xresources.texi (GTK resources): Clean up previous change.
-
-2003-10-12 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * xresources.texi (GTK resources): Add a note that some themes
- disallow customizations. Add scroll theme example.
-
-2003-10-08 Nick Roberts <nick@nick.uklinux.net>
-
- * speedbar.texi: Remove paragraph for GUD that is no longer true.
-
-2003-10-06 Luc Teirlinck <teirllm@auburn.edu>
-
- * texinfo.tex: Replace `%' in arch tagline by @ignore.
-
-2003-09-30 Richard M. Stallman <rms@gnu.org>
-
- * dired-x.texi (Miscellaneous Commands): Delete M-g, w, T.
-
- * widget.texi (User Interface): Fix typos.
-
- * pcl-cvs.texi, cl.texi, woman.texi, ediff.texi: Fix @strong{Note:}.
-
- * cmdargs.texi (General Variables): Remove MAILRC envvar.
-
- * misc.texi (Saving Emacs Sessions): Shorten the section,
- collapsing back into one node.
-
-2003-09-30 Lars Hansen <larsh@math.ku.dk>
-
- * misc.texi: Section "Saving Emacs Sessions" rewritten.
-
-2003-09-29 Jan Dj\e,Ad\e(Brv. <jan.h.d@swipnet.se>
-
- * xresources.texi (GTK names in Emacs): Correct typo.
-
-2003-09-29 Thien-Thi Nguyen <ttn@gnu.org>
-
- * pcl-cvs.texi (Selected Files): Fix typo.
-
-2003-09-24 Luc Teirlinck <teirllm@mail.auburn.edu>
-
- * cmdargs.texi (Font X): Mention new default font. More
- fully describe long font names, wildcard patterns and the
- problems involved. (Result of discussion on emacs-devel.)
-
-2003-09-22 Luc Teirlinck <teirllm@mail.auburn.edu>
-
- * emacs.texi (Acknowledgements): Correct typo.
-
-2003-09-22 Richard M. Stallman <rms@gnu.org>
-
- * dired.texi (Misc Dired Commands): New node.
- (Dired Navigation): Add dired-goto-file.
-
- * files.texi (File Aliases, Misc File Ops): Add @cindex entries.
-
- * emacs.texi (Acknowledgements): New node, split from Distribution.
-
- * cmdargs.texi (Action Arguments): -f reads interactive args.
-
-2003-09-21 Karl Berry <karl@gnu.org>
-
- * info.texi (] and [ commands): No period at end of section title.
-
-2003-09-08 Lute Kamstra <lute@gnu.org>
-
- * screen.texi (Mode Line): Say that POS comes before LINE.
- Mention `size-indication-mode'.
- * display.texi (Optional Mode Line): Document
- `size-indication-mode'.
- * basic.texi (Position Info): Mention `size-indication-mode'.
-
-2003-09-07 Luc Teirlinck <teirllm@mail.auburn.edu>
-
- * xresources.texi (Resources): Refer to `editres' man page.
- (Lucid Resources): Update defaults. Expand description of
- `shadowThickness'.
-
-2003-09-04 Miles Bader <miles@gnu.org>
-
- * Makefile.in (top_srcdir): New variable.
- ($(top_srcdir)/info): New rule.
- (info): Depend on it.
-
-2003-09-03 Peter Runestig <peter@runestig.com>
-
- * makefile.w32-in: New file.
-
-2003-08-29 Richard M. Stallman <rms@gnu.org>
-
- * misc.texi (Saving Emacs Sessions): Correct previous change.
-
-2003-08-26 Per Abrahamsen <abraham@dina.kvl.dk>
-
- * widget.texi (User Interface): Explain the need of static text
- around an editable field.
-
-2003-08-19 Luc Teirlinck <teirllm@mail.auburn.edu>
-
- * widget.texi (Basic Types): The argument to `:help-echo' can now
- be a form that evaluates to a string.
-
- * emacs.texi (Top): Update menu to reflect new Keyboard Macros chapter.
- (Intro): Include kmacro.texi after fixit.texi instead of after
- custom.texi. (As suggested by Kim Storm.)
-
-2003-08-18 Luc Teirlinck <teirllm@mail.auburn.edu>
-
- * fixit.texi (Fixit): Update `Next' pointer.
- * files.texi (Files): Update `Previous' pointer.
- * kmacro.texi (Keyboard Macros): Remove redundant node and section.
- * emacs.texi (Intro): Include kmacro.texi after custom.texi.
- (Suggested by Kim Storm.)
- * Makefile (EMACSSOURCES): Add kmacro.texi. (Suggested by Kim Storm.)
-
-2003-08-18 Kim F. Storm <storm@cua.dk>
-
- * kmacro.texi: New file describing enhanced keyboard macro
- functionality. Replaces old description in custom.texi.
-
- * custom.texi (Customization): Add xref to Keyboard Macros chapter.
- (Keyboard Macros): Move to new kmacro.texi file.
-
- * emacs.texi (Keyboard Macros): Reference new keyboard macro topics.
-
- * calc.texi (Queries in Macros): Update xref to keyboard macro query.
-
-2003-08-17 Edward M. Reingold <reingold@emr.cs.iit.edu>
-
- * calendar.texi (Specified Dates): Add `calendar-goto-day-of-year'.
-
-2003-08-17 Alex Schroeder <alex@gnu.org>
-
- * misc.texi (Saving Emacs Sessions): Manual M-x desktop-save not
- required.
-
-2003-08-16 Richard M. Stallman <rms@gnu.org>
-
- * dired-x.texi (Shell Command Guessing): Explain *.
-
-2003-08-16 Chunyu Wang <spr@db.cs.hit.edu.cn> (tiny change)
-
- * pcl-cvs.texi (Log Edit Mode): Fix key binding for
- log-edit-insert-changelog.
-
-2003-08-05 Richard M. Stallman <rms@gnu.org>
-
- * programs.texi (Lisp Indent): Don't describe
- lisp-indent-function property here. Use xref to Lisp Manual.
-
-2003-08-03 Karl Berry <karl@gnu.org>
-
- * info.texi: Need @contents.
-
-2003-08-03 Glenn Morris <gmorris@ast.cam.ac.uk>
-
- * calendar.texi (Date Formats): Document changed behaviour of
- abbreviations.
-
-2003-07-24 Markus Rost <rost@math.ohio-state.edu>
-
- * buffers.texi (List Buffers): Fix previous change.
-
-2003-07-20 Kai Gro\e,A_\e(Bjohann <kai.grossjohann@gmx.net>
-
- Tramp version 2.0.36 released.
-
- * tramp.texi (Remote shell setup): Explain about problems with
- non-Bourne commands in ~/.profile and ~/.shrc.
-
-2003-07-13 Markus Rost <rost@math.ohio-state.edu>
-
- * buffers.texi (List Buffers): Adjust to new format of *Buffer
- List*.
-
-2003-07-07 Luc Teirlinck <teirllm@mail.auburn.edu>
-
- * info.texi (Help-Inv, Help-M, Help-Xref): Update following
- renaming of `vis-mode' to `visible-mode'.
-
- * display.texi (Font Lock): Fix typo.
-
-2003-07-07 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Font Lock): Add xref for format info on
- font-lock-remove-keywords.
-
- * building.texi (Compilation): Document what happens with asynch
- children of compiler process.
-
- * help.texi (Library Keywords): Use @multitable.
-
-2003-07-04 Luc Teirlinck <teirllm@mail.auburn.edu>
-
- * info.texi (Top, Help-Small-Screen): Remove accidentally added
- next, prev and up pointers.
-
-2003-07-02 Luc Teirlinck <teirllm@mail.auburn.edu>
-
- * info.texi (Help): Mention existence of Emacs and stand-alone
- Info at the very beginning of the tutorial.
- (Help-Inv): New node.
- (Help-]): New node.
- (Help-M): Systematically point out the differences between default
- Emacs and stand-alone versions. Delete second menu.
- (Help-Xref): Systematically point out the differences between
- default Emacs and stand-alone versions.
- (Help-Int): Change `l' example.
- (Expert Info): Fix typos.
- (Emacs Info Variables): Mention `Info-hide-note-references' and
- new default for `Info-scroll-prefer-subnodes'.
-
-2003-06-17 Kai Gro\e,A_\e(Bjohann <kai.grossjohann@gmx.net>
-
- Version 2.0.35 of Tramp released.
-
- * tramp.texi: From Michael Albinus <Michael.Albinus@alcatel.de>:
- (Inline methods): Add methods `remsh' and `plink1'.
- (External transfer methods): Add method `remcp'.
- (Multi-hop Methods): Add method `remsh'.
- Small patch from Adrian Aichner <adrian@xemacs.org>:
- Fix minor typos.
- (Concept Index): Added to make manual searchable via
- `Info-index'.
- (Version Control): Add cindex entry.
-
-2003-06-04 Richard M. Stallman <rms@gnu.org>
-
- * programs.texi (Expressions): Delete C-M-DEL.
-
- * misc.texi (Shell Options): Clarify comint-scroll-show-maximum-output.
- comint-move-point-for-output renamed from
- comint-scroll-to-bottom-on-output.
-
- * custom.texi (Init Rebinding): Replace previous change with xref.
- (Non-ASCII Rebinding): Explain that issue more briefly here.
-
-2003-05-28 Richard M. Stallman <rms@gnu.org>
-
- * indent.texi (Indentation): Condense, simplify, clarify prev change.
-
-2003-05-28 Nick Roberts <nick@nick.uklinux.net>
-
- * building.texi (GDB Graphical Interface): New node.
- (Rewritten somewhat by RMS.)
-
-2003-05-28 Kai Gro\e,A_\e(Bjohann <kai.grossjohann@gmx.net>
-
- * custom.texi (Init Rebinding): Xref Non-ASCII Rebinding, for
- non-English letters. Explain how to set coding systems correctly
- and how to include the right coding cookie in the file.
-
-2003-05-24 Kai Gro\e,A_\e(Bjohann <kai.grossjohann@gmx.net>
-
- * trampver.texi: Version 2.0.34 released.
-
-2003-05-22 Kai Gro\e,A_\e(Bjohann <kai.grossjohann@gmx.net>
-
- * indent.texi (Indentation): Explain the concepts.
- (Just Spaces): Explain why preventing tabs for indentation might
- be useful.
-
-2003-05-03 Glenn Morris <gmorris@ast.cam.ac.uk>
-
- * faq.texi: Improve previous changes.
-
-2003-05-02 Glenn Morris <gmorris@ast.cam.ac.uk>
-
- * faq.texi: Update copyright and maintenance details.
- Update some package URLs, versions, and maintainers.
- Remove many references to the Emacs Lisp Archive.
-
-2003-04-23 Simon Josefsson <jas@extundo.com>
-
- * smtpmail.texi: Fix license (the invariant sections mentioned has
- never been part of the smtp manual). Align info dir entry with
- other emacs packages.
-
-2003-04-16 Richard M. Stallman <rms@gnu.org>
-
- * search.texi (Regexps): Ref to Lisp manual for more regexp features.
-
-2003-04-08 Michael Albinus <Michael.Albinus@alcatel.de>
-
- * tramp.texi: Version 2.0.33 released.
- Remove installation chapter. Remove XEmacs specifics.
-
-2003-03-29 Richard M. Stallman <rms@gnu.org>
-
- * tramp.texi (Top): Undo the previous renaming.
- (emacs-other-name, emacs-other-dir, emacs-other-file-name): Delete.
-
-2003-03-29 Kai Gro\e,A_\e(Bjohann <kai.grossjohann@gmx.net>
-
- * Makefile.in (../info/tramp): Compile Emacs, instead of XEmacs,
- version of manual.
-
- * tramp.texi (Auto-save and Backup): New node.
-
-2003-03-29 Michael Albinus <Michael.Albinus@alcatel.de>
-
- * tramp.texi (Top): Include trampver.texi. Rename "Emacs" to "GNU
- Emacs" in order to have better differentiation to "XEmacs".
- `emacs-other-name', `emacs-other-dir' and `emacs-other-file-name'
- are new macros in order to point to the other Emacs flavor where
- appropriate. In info case, point to node `Installation' in order
- to explain how to generate the other way. In html case, make a
- link to the other html file.
- (Obtaining TRAMP): Added a paragraph saying to perform `autoconf'
- after CVS checkout/update.
- (Installation): Completely rewritten.
- (Installation parameters, Load paths): New sections under
- `Installation'.
-
-2003-02-28 Kai Gro\e,A_\e(Bjohann <kai.grossjohann@uni-duisburg.de>
-
- * tramp.texi: Version 2.0.30 released.
- Replace word "path" with "localname" where used as a component of
- a Tramp file name.
-
-2003-02-28 Michael Albinus <Michael.Albinus@alcatel.de>
-
- * tramp.texi (Frequently Asked Questions): `tramp-chunksize'
- introduced.
- (Installation): Explain what to do if files from the tramp/contrib
- directory are needed.
-
-2003-02-23 Alex Schroeder <alex@emacswiki.org>
-
- * smtpmail.texi (How Mail Works): New.
-
-2003-02-22 Alex Schroeder <alex@emacswiki.org>
-
- * cmdargs.texi (General Variables): Document SMTPSERVER.
-
- * smtpmail.texi: New file.
-
- * sending.texi: Remove SMTP node.
- (Mail Sending): Describe `send-mail-function'. Link to SMTP
- library.
-
- * Makefile.in: Build SMTP manual.
-
-2003-02-22 Alex Schroeder <alex@emacswiki.org>
-
- * sending.texi (Sending via SMTP): Explain MTA/MUA.
-
-2003-02-22 Simon Josefsson <jas@extundo.com>
-
- * sending.texi (Mail Methods): Add node about SMTP.
-
-2003-02-17 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * xresources.texi (GTK names in Emacs): Add emacs-toolbar - GtkToolbar.
-
-2003-02-05 Kai Gro\e,A_\e(Bjohann <kai.grossjohann@uni-duisburg.de>
-
- * tramp.texi: Version 2.0.29 released.
- (Installation): In Emacs, use M-x texinfo-format-buffer RET, not
- M-x makeinfo-buffer RET. Reported by gebser@ameritech.net.
-
-2003-02-01 Michael Albinus <Michael.Albinus@alcatel.de>
-
- * tramp.texi (Frequently Asked Questions): Explain a workaround if
- another package loads accidently Ange-FTP.
-
-2003-01-24 Michael Albinus <Michael.Albinus@alcatel.de>
-
- * tramp.texi (Customizing Completion): Add function
- `tramp-parse-sconfig'. Change example of
- `tramp-set-completion-function', because parsing of ssh config
- files looks more natural.
-
-2003-02-01 Kevin Ryde <user42@zip.com.au>
-
- * glossary.texi (Glossary): Correction to cl cross reference.
-
-2003-01-20 Richard M. Stallman <rms@gnu.org>
-
- * killing.texi (Rectangles): Document C-x c r.
-
-2003-01-19 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * xresources.texi (GTK resources): New node.
- (GTK widget names): New node.
- (GTK names in Emacs): New node.
- (GTK styles): New node.
-
-2003-01-15 ShengHuo ZHU <zsh@cs.rochester.edu>
-
- * gnus.texi: Do not use `path' in several locations.
-
-2003-01-09 Francesco Potort
\e,Al
\e(B <pot@gnu.org>
-
- * maintaining.texi (Create Tags Table): Add reference to the new
- `etags --help --lang=LANG' option.
-
-2002-12-26 Kai Gro\e,A_\e(Bjohann <kai.grossjohann@uni-duisburg.de>
-
- * tramp.texi (External transfer methods): New method `smb'. From
- Michael Albinus.
-
-2002-11-05 Karl Berry <karl@gnu.org>
-
- * info.texi (Info-fontify): Reorder face list to avoid bad line
- breaks.
-
-2002-10-06 Kai Gro\e,A_\e(Bjohann <Kai.Grossjohann@CS.Uni-Dortmund.DE>
-
- * tramp.texi: Move @copying to standard place. Use
- @insertcopying.
-
-2002-10-02 Karl Berry <karl@gnu.org>
-
- * (ada-mode.texi autotype.texi calc.texi cc-mode.texi cl.texi
- dired-x.texi ebrowse.texi ediff.texi emacs-mime.texi emacs.texi
- eshell.texi eudc.texi faq.texi forms.texi idlwave.texi info.texi
- message.texi mh-e.texi pcl-cvs.texi reftex.texi sc.texi ses.texi
- speedbar.texi vip.texi viper.texi widget.texi woman.texi):
- Per rms, update all manuals to use @copying instead of @ifinfo.
- Also use @ifnottex instead of @ifinfo around the top node, where
- needed for the sake of the HTML output.
- (The Gnus manual is not fixed since it's not clear to me how it
- works; and the Tramp manual already uses @copying, although in an
- unusual way. All others were changed.)
-
-2002-09-10 Jonathan Yavner <jyavner@engineer.com>
-
- * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add SES.
- (../info/ses, ses.dvi): New targets.
- * ses.texi: New file.
-
-2002-09-06 Pavel Jan
\e,Am
\e(Bk <Pavel@Janik.cz>
-
- * texinfo.tex: Update to texinfo 4.2.
-
-2002-08-27 Carsten Dominik <dominik@sand.science.uva.nl>
-
- * reftex.texi: Update to RefTeX 4.19.
-
-2002-06-17 Kai Gro\e,A_\e(Bjohann <Kai.Grossjohann@CS.Uni-Dortmund.DE>
-
- * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add Tramp.
- (../info/tramp, tramp.dvi): New targets.
-
-2002-01-04 Eli Zaretskii <eliz@is.elta.co.il>
-
- * Makefile.in (DVI_TARGETS): Add calc.dvi.
- (calc.dvi): Uncomment.
-
-2001-12-20 Eli Zaretskii <eliz@is.elta.co.il>
-
- * Makefile.in (EMACSSOURCES): Update the list of Emacs manual
- source files.
-
-2001-11-16 Eli Zaretskii <eliz@is.elta.co.il>
-
- * Makefile.in (emacsman): New target.
-
-2001-11-07 Eli Zaretskii <eliz@is.elta.co.il>
-
- * Makefile.in (INFO_TARGETS): Add ../info/calc.
- (../info/calc): New target.
-
-2001-10-20 Gerd Moellmann <gerd@gnu.org>
-
- * (Version 21.1 released.)
-
-2001-10-05 Gerd Moellmann <gerd@gnu.org>
-
- * Branch for 21.1.
-
-2001-04-14 Eli Zaretskii <eliz@is.elta.co.il>
-
- * Makefile.in (../info/info): Use an explicit -o switch to
- makeinfo.
-
-2001-03-05 Gerd Moellmann <gerd@gnu.org>
-
- * Makefile.in (mostlyclean, maintainer-clean): Delete more files.
-
-2000-12-20 Eli Zaretskii <eliz@is.elta.co.il>
-
- * Makefile.in (../info/idlwave): Use --no-split.
-
-2000-12-14 Dave Love <fx@gnu.org>
-
- * Makefile.in (mostlyclean): Remove gnustmp.*
- (gnus.dvi): Change rule to remove @latex stuff.
-
-2000-10-19 Eric M. Ludlam <zappo@ultranet.com>
-
- * Makefile.in (Speedbar): Add build targets for speedbar.texi.
-
-2000-10-13 John Wiegley <johnw@gnu.org>
-
- * Makefile.in: Add build targets for eshell.texi.
-
-2000-09-25 Gerd Moellmann <gerd@gnu.org>
-
- * Makefile.in: Remove/comment speedbar stuff.
-
-2000-09-22 Dave Love <fx@gnu.org>
-
- * Makefile.in: Add emacs-mime.
-
-2000-08-08 Eli Zaretskii <eliz@is.elta.co.il>
-
- * Makefile.in (INFO_TARGETS): Add ../info/woman.
- (DVI_TARGETS): Add woman.dvi.
- (../info/woman, woman.dvi): New targets.
-
-2000-05-31 Stefan Monnier <monnier@cs.yale.edu>
-
- * .cvsignore (*.tmp): New entry. Seems to be used for @macro.
-
- * pcl-cvs.texi: New file.
- * Makefile.in (INFO_TARGETS, DVI_TARGETS: Add pcl-cvs.
- (../info/pcl-cvs, pcl-cvs.dvi): New targets.
-
-2000-05-11 Gerd Moellmann <gerd@gnu.org>
-
- * Makefile.in (INFO_TARGETS): Add info/ebrowse.
- (../info/ebrowse, ebrowse.dvi): New targets.
-
-2000-01-13 Gerd Moellmann <gerd@gnu.org>
-
- * Makefile.in (INFO_TARGETS): Add eudc.
- (DVI_TARGETS): Add eudc.dvi.
- (../info/eudc, eudc.dvi): New targets.
-
-2000-01-05 Eli Zaretskii <eliz@is.elta.co.il>
-
- * Makefile.in (INFO_TARGETS): Rename emacs-faq to efaq (for
- compatibility with 8+3 filesystems).
- (../info/efaq): Rename from emacs-faq.
-
-2000-01-03 Eli Zaretskii <eliz@is.elta.co.il>
-
- * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add idlwave.
- (../info/idlwave, idlwave.dvi): New targets.
-
-1999-10-23 Dave Love <fx@gnu.org>
-
- * Makefile.in: Use autotype.texi.
-
-1999-10-12 Stefan Monnier <monnier@cs.yale.edu>
-
- * Makefile.in (faq): Use ../info/emacs-faq.info (as specified in the
- faq.texi file) rather than ../info/faq.
-
-1999-10-07 Gerd Moellmann <gerd@gnu.org>
-
- * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add ada-mode.
- (../info/ada-mode, ada-mode.dvi): New targets.
-
-1999-09-01 Dave Love <fx@gnu.org>
-
- * Makefile.in: Add faq.
-
-1999-07-12 Richard Stallman <rms@gnu.org>
-
- * Version 20.4 released.
-
-1998-12-04 Markus Rost <rost@delysid.gnu.org>
-
- * Makefile.in (INFO_TARGETS): Delete customize.info.
- (DVI_TARGETS): Delete customize.dvi.
- (../info/customize, customize.dvi): Targets deleted.
-
-1998-08-19 Richard Stallman <rms@psilocin.ai.mit.edu>
-
- * Version 20.3 released.
-
-1998-05-06 Richard Stallman <rms@psilocin.gnu.org>
-
- * Makefile.in (EMACSSOURCES): Add mule.texi.
- Add msdog.texi, ack.texi. Remove gnu1.texi.
-
-1998-04-06 Andreas Schwab <schwab@gnu.org>
-
- * Makefile.in (ENVADD): Enviroment vars to pass to texi2dvi. Use
- it in dvi targets.
- (../etc/GNU): Change to $(srcdir) first.
-
-1998-03-11 Carsten Dominik <cd@delysid.gnu.org>
-
- * reftex.texi: Update for RefTeX version 3.22.
-
-1998-02-08 Richard Stallman <rms@psilocin.gnu.org>
-
- * Makefile.in (reftex.dvi, ../info/reftex): New targets.
- (INFO_TARGETS, DVI_TARGETS): Add the new targets.
-
-1997-09-23 Paul Eggert <eggert@twinsun.com>
-
- * Makefile.in: Merge changes mistakenly made to `Makefile'.
- (INFO_TARGETS): Change ../info/custom to ../info/customize.
- (../info/customize): Rename from ../info/custom.
- (../info/viper, viper.dvi): Remove dependency on viper-cmd.texi.
-
-1997-09-19 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
-
- * Version 20.2 released.
-
-1997-09-15 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
-
- * Version 20.1 released.
-
-1997-08-24 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
-
- * Makefile (../info/customize, customize.dvi): New targets.
- (INFO_TARGETS): Add ../info/customize.
- (DVI_TARGETS): Add customize.dvi.
-
-1997-07-10 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
-
- * Makefile (../info/viper, viper.dvi): Delete viper-cmd.texi dep.
-
-1996-08-11 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
-
- * Version 19.33 released.
-
-1996-07-31 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
-
- * Version 19.32 released.
-
-1996-06-27 Lars Magne Ingebrigtsen <larsi@ifi.uio.no>
-
- * Makefile.in: Add rules for the Message manual.
-
-1996-06-26 Lars Magne Ingebrigtsen <larsi@ifi.uio.no>
-
- * gnus.texi: New version.
-
- * message.texi: New manual.
-
-1996-06-20 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
-
- * Makefile.in (All info targets): cd $(srcdir) to do the work.
-
-1996-06-19 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
-
- * Makefile.in (All info targets): Specify $(srcdir) in input files.
- Specify -I option.
- (All dvi targets): Set the TEXINPUTS variable.
-
-1996-05-25 Karl Heuer <kwzh@gnu.ai.mit.edu>
-
- * Version 19.31 released.
-
-1996-01-07 Richard Stallman <rms@whiz-bang.gnu.ai.mit.edu>
-
- * Makefile.in (../info/ccmode): Rename from ../info/cc-mode.
- (INFO_TARGETS): Use new name. This avoids name conflict on MSDOS.
-
-1995-11-29 Richard Stallman <rms@mole.gnu.ai.mit.edu>
-
- * Makefile.in (../info/cc-mode, cc-mode.dvi): New targets.
- (INFO_TARGETS): Add ../info/cc-mode.
- (DVI_TARGETS): Add cc-mode.dvi.
-
-1995-11-24 Richard Stallman <rms@mole.gnu.ai.mit.edu>
-
- * Version 19.30 released.
-
-1995-11-04 Lars Magne Ingebrigtsen <larsi@ifi.uio.no>
-
- * gnus.texi: New file.
-
-1995-11-04 Erik Naggum <erik@naggum.no>
-
- * gnus.texi: File deleted.
-
-1995-11-02 Stephen Gildea <gildea@stop.mail-abuse.org>
-
- * mh-e.texi: "Function Index" -> "Command Index" to work with
- Emacs 19.30 C-h C-k support of separately-documented commands.
-
-1995-06-26 Richard Stallman <rms@mole.gnu.ai.mit.edu>
-
- * Makefile.in (../info/ediff, ediff.dvi): New targets.
- (INFO_TARGETS, DVI_TARGETS): Add those new targets.
-
-1995-04-24 Richard Stallman <rms@mole.gnu.ai.mit.edu>
-
- * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add viper targets.
- (../info/viper, viper.dvi): New targets.
-
-1995-04-20 Kevin Rodgers <kevinr@ihs.com>
-
- * dired-x.texi (Installation): Change the example to set
- buffer-local variables like dired-omit-files-p in
- dired-mode-hook.
-
-1995-04-17 Richard Stallman <rms@mole.gnu.ai.mit.edu>
-
- * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add mh-e targets.
- (../info/mh-e, mh-e.dvi): New targets.
-
-1995-02-07 Richard Stallman <rms@pogo.gnu.ai.mit.edu>
-
- * Makefile.in (maintainer-clean): Rename from realclean.
-
-1994-11-23 Richard Stallman <rms@mole.gnu.ai.mit.edu>
-
- * Makefile.in: New file.
- * Makefile: File deleted.
-
-1994-11-19 Richard Stallman <rms@mole.gnu.ai.mit.edu>
-
- * Makefile (TEXINDEX_OBJS): Variable deleted.
- (texindex, texindex.o, getopt.o): Rules deleted.
- All deps on texindex deleted.
- (distclean): Don't delete texindex.
- (mostlyclean): Don't delete *.o.
- * texindex.c, getopt.c: Files deleted.
-
-1994-09-07 Richard Stallman <rms@mole.gnu.ai.mit.edu>
-
- * Version 19.26 released.
-
-1994-07-02 Richard Stallman (rms@gnu.ai.mit.edu)
-
- * Makefile (EMACSSOURCES): Exclude undo.texi.
-
-1994-05-30 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Version 19.25 released.
-
-1994-05-23 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Version 19.24 released.
-
-1994-05-16 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Version 19.23 released.
-
-1994-04-17 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Makefile: Delete spurious tab.
-
-1994-02-16 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Makefile (.SUFFIXES): New rule.
-
-1994-01-15 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Makefile (dired-x.dvi, ../info/dired-x): New targets.
- (INFO_TARGETS, DVI_TARGETS): Add the new targets.
-
-1994-01-08 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Makefile (../info/sc): Rename frin sc.info.
- (../info/cl): Likewise.
- (INFO_TARGETS): Use new names.
-
-1993-12-04 Richard Stallman (rms@srarc2)
-
- * getopt.c: New file.
- * Makefile (TEXINDEX_OBJS): Use getopt.o in this dir, not ../lib-src.
- (getopt.o): New rule.
- (dvi): Don't depend on texindex.
- (emacs.dvi, cl.dvi, forms.dvi, vip.dvi, gnus.dvi, sc.dvi):
- Depend on texindex.
-
-1993-12-03 Richard Stallman (rms@srarc2)
-
- * Makefile (../info/sc.info): Rename from ../info/sc.
- (TEXI2DVI): New variable.
- (emacs.dvi, cl.dvi forms.dvi, sc.dvi, vip.dvi, gnus.dvi, info.dvi):
- Add explicit commands.
- (TEXINDEX_OBJS): Delete duplicate getopt.o.
-
-1993-11-27 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Version 19.22 released.
-
-1993-11-18 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Makefile (TEXINDEX_OBJS): Delete spurious period.
-
-1993-11-16 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Version 19.21 released.
-
-1993-11-15 Paul Eggert (eggert@twinsun.com)
-
- * man/Makefile (../info/cl.info): Rename from ../info/cl.
-
-1993-11-15 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Makefile (../etc/GNU): New target.
- (EMACSSOURCES): Add gnu1.texi.
-
-1993-11-14 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Makefile (realclean): Don't delete the Info files.
-
-1993-10-25 Brian Fox (bfox@albert.gnu.ai.mit.edu)
-
- * forms.texi: Fix forms.texi so that it will format correctly.
- Add missing `@end iftex', fix bad reference.
-
- * info.texi, info-stn.texi: New files implement texinfo version of
- `info' file.
-
- * frames.texi (Creating Frames): Mention `C-x 5' instead of `C-x
- 4' where appropriate.
-
-1993-10-20 Brian Fox (bfox@ai.mit.edu)
-
- * Makefile: Fix targets for texindex, new info.texi files.
- * info-stnd.texi: New file implements info for standalone info
- reader.
- * info.texi: Update to include recent changes to "../info/info".
- New source file for ../info/info; includes info-stnd.texi.
-
- * texindex.c: Include "../src/config.h" if building in emacs.
-
- * Makefile: Change all files to FILENAME.texi, force all targets
- to be FILENAME, not FILENAME.info. This changes sc.texinfo,
- vip.texinfo, forms.texinfo, cl.texinfo.
- Add target to build texindex.c, defining `emacs'.
-
- * forms.texi: Install new file to match version 2.3 of forms.el.
-
-1993-08-14 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Version 19.19 released.
-
-1993-08-10 Simon Leinen (simon@lia.di.epfl.ch)
-
- * sc.texinfo: Fix info file name.
-
- * Makefile (info): Add gnus and sc.
- (dvi): Add gnus.dvi and sc.dvi.
- (../info/sc, sc.dvi): New targets.
-
-1993-08-08 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Version 19.18 released.
-
-1993-07-20 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Makefile: Fix source file names of the separate manuals.
- (gnus.dvi, ../info/gnus): New targets.
-
-1993-07-18 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * Version 19.17 released.
-
-1993-07-10 Richard Stallman (rms@mole.gnu.ai.mit.edu)
-
- * split-man: Fix typos in last change.
-
-1993-07-06 Jim Blandy (jimb@geech.gnu.ai.mit.edu)
-
- * Version 19.16 released.
-
-1993-06-19 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
-
- * version 19.15 released.
-
-1993-06-18 Jim Blandy (jimb@geech.gnu.ai.mit.edu)
-
- * Makefile (distclean): It's rm, not rf.
-
-1993-06-17 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
-
- * Version 19.14 released.
-
-1993-06-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
-
- * Makefile: New file.
-
-1993-06-08 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
-
- * Version 19.13 released.
-
-1993-05-27 Jim Blandy (jimb@geech.gnu.ai.mit.edu)
-
- * Version 19.9 released.
-
-1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
-
- * Version 19.8 released.
-
-1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
-
- * cmdargs.texi: Document the -i, -itype, and -iconic options.
-
- * trouble.texi: It's `enable-flow-control-on', not
- `evade-flow-control-on'.
-
-1993-05-24 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
-
- * display.texi: Document standard-display-european.
-
-1993-05-22 Jim Blandy (jimb@geech.gnu.ai.mit.edu)
-
- * Version 19.7 released.
-
- * emacs.texi: Add a sentence to the top menu mentioning the
- specific version of Emacs this manual applies to.
-
-1993-04-25 Eric S. Raymond (eric@mole.gnu.ai.mit.edu)
-
- * basic.texi: Document next-line-add-lines variable used to
- implement down-arrow.
-
- * killing.texi: Document kill-whole-line.
-
-1993-04-18 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu)
-
- * text.texi: Update unix TeX ordering information.
-
-1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu)
-
- * news.texi: Mention fill-rectangle in keybinding list.
-
- * killing.texi: Document fill-rectangle.
-
-1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu)
-
- * vc.texi: Bring the docs up to date with VC 5.2.
-
-1992-01-10 Eric S. Raymond (eric@mole.gnu.ai.mit.edu)
-
- * emacs.tex: Mention blackbox and gomoku under Amusements.
- Assembler mode is now mentioned and appropriately indexed
- under Programming Modes.
-
-1991-02-15 Robert J. Chassell (bob@wookumz.ai.mit.edu)
-
- * emacs.tex: Update TeX ordering information.
-
-1990-08-30 David Lawrence (tale@pogo.ai.mit.edu)
-
- * gnus.texinfo: New file. Removed installation instructions.
-
-1990-06-26 David Lawrence (tale@geech)
-
- * emacs.tex: Note that completion-ignored-extensions is not used
- to filter out names when all completions are displayed in
- *Completions*.
-
-1990-05-25 Richard Stallman (rms@sugar-bombs.ai.mit.edu)
-
- * texindex.tex: If USG, include sys/types.h and sys/fcntl.h.
-
-1990-03-21 Jim Kingdon (kingdon@pogo.ai.mit.edu)
-
- * emacs.tex: Add @findex grep.
-
-1989-01-17 Robert J. Chassell (bob@rice-chex.ai.mit.edu)
-
- * texinfo.tex: Change spelling of `\sc' font to `\smallcaps' and
- then define `\sc' as the command for smallcaps in Texinfo. This
- means that the @sc command will produce small caps. bfox has
- made the corresponding change to makeinfo and texinfm.el.
-
-1988-08-16 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu)
-
- * emacs.tex: Correct two typos. No other changes before
- Version 19 will be made.
-
- * vip.texinfo: Remove menu entry Adding Lisp Code in node
- Customization since the menu entry did not point to anything.
- Also add an @finalout command to remove overfull hboxes from the
- printed output.
-
- * cl.texinfo: Add @bye, \input line and @settitle to file.
- This file is clearly intended to be a chapter of some other work,
- but the other work does not yet exist.
-
-1988-07-25 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu)
-
- * texinfo.texinfo: Three typos corrected.
-
-1988-05-23 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu)
-
- * emacs.tex: Update information for obtaining TeX distribution from the
- University of Washington.
-
-;; Local Variables:
-;; coding: iso-2022-7bit
-;; fill-column: 79
-;; add-log-time-zone-rule: t
-;; End:
-
- Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 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.
-
-;;; arch-tag: f1d62776-3ed5-4811-9d96-267252577dbd
+++ /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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003,
-@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Abbrevs
-@chapter Abbrevs
-@cindex abbrevs
-@cindex expansion (of abbrevs)
-
- A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert
-it, into some different text. Abbrevs are defined by the user to expand
-in specific ways. For example, you might define @samp{foo} as an abbrev
-expanding to @samp{find outer otter}. Then you could insert
-@samp{find outer otter } into the buffer by typing @kbd{f o o
-@key{SPC}}.
-
- A second kind of abbreviation facility is called @dfn{dynamic abbrev
-expansion}. You use dynamic abbrev expansion with an explicit command
-to expand the letters in the buffer before point by looking for other
-words in the buffer that start with those letters. @xref{Dynamic
-Abbrevs}.
-
- ``Hippie'' expansion generalizes abbreviation expansion.
-@xref{Hippie Expand, , Hippie Expansion, autotype, Features for
-Automatic Typing}.
-
-@menu
-* Abbrev Concepts:: Fundamentals of defined abbrevs.
-* Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
-* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
-* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
-* Saving Abbrevs:: Saving the entire list of abbrevs for another session.
-* Dynamic Abbrevs:: Abbreviations for words already in the buffer.
-* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling.
-@end menu
-
-@node Abbrev Concepts
-@section Abbrev Concepts
-
- An @dfn{abbrev} is a word which has been defined to @dfn{expand} into
-a specified @dfn{expansion}. When you insert a word-separator character
-following the abbrev, that expands the abbrev---replacing the abbrev
-with its expansion. For example, if @samp{foo} is defined as an abbrev
-expanding to @samp{find outer otter}, then you can insert @samp{find
-outer otter.} into the buffer by typing @kbd{f o o .}.
-
-@findex abbrev-mode
-@vindex abbrev-mode
-@cindex Abbrev mode
-@cindex mode, Abbrev
- Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
-Disabling Abbrev mode does not cause abbrev definitions to be forgotten,
-but they do not expand until Abbrev mode is enabled again. The command
-@kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it
-turns Abbrev mode on if the argument is positive, off otherwise.
-@xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is
-on when the variable is non-@code{nil}. The variable @code{abbrev-mode}
-automatically becomes local to the current buffer when it is set.
-
- Abbrevs can have @dfn{mode-specific} definitions, active only in one major
-mode. Abbrevs can also have @dfn{global} definitions that are active in
-all major modes. The same abbrev can have a global definition and various
-mode-specific definitions for different major modes. A mode-specific
-definition for the current major mode overrides a global definition.
-
- You can define abbrevs interactively during the editing session. You
-can also save lists of abbrev definitions in files for use in later
-sessions. Some users keep extensive lists of abbrevs that they load
-in every session.
-
-@node Defining Abbrevs
-@section Defining Abbrevs
-
-@table @kbd
-@item C-x a g
-Define an abbrev, using one or more words before point as its expansion
-(@code{add-global-abbrev}).
-@item C-x a l
-Similar, but define an abbrev specific to the current major mode
-(@code{add-mode-abbrev}).
-@item C-x a i g
-Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}).
-@item C-x a i l
-Define a word in the buffer as a mode-specific abbrev
-(@code{inverse-add-mode-abbrev}).
-@item M-x define-global-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET}
-Define @var{abbrev} as an abbrev expanding into @var{exp}.
-@item M-x define-mode-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET}
-Define @var{abbrev} as a mode-specific abbrev expanding into @var{exp}.
-@item M-x kill-all-abbrevs
-Discard all abbrev definitions, leaving a blank slate.
-@end table
-
-@kindex C-x a g
-@findex add-global-abbrev
- The usual way to define an abbrev is to enter the text you want the
-abbrev to expand to, position point after it, and type @kbd{C-x a g}
-(@code{add-global-abbrev}). This reads the abbrev itself using the
-minibuffer, and then defines it as an abbrev for one or more words before
-point. Use a numeric argument to say how many words before point should be
-taken as the expansion. For example, to define the abbrev @samp{foo} as
-mentioned above, insert the text @samp{find outer otter} and then type
-@kbd{C-u 3 C-x a g f o o @key{RET}}.
-
- An argument of zero to @kbd{C-x a g} means to use the contents of the
-region as the expansion of the abbrev being defined.
-
-@kindex C-x a l
-@findex add-mode-abbrev
- The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but
-defines a mode-specific abbrev. Mode-specific abbrevs are active only in a
-particular major mode. @kbd{C-x a l} defines an abbrev for the major mode
-in effect at the time @kbd{C-x a l} is typed. The arguments work the same
-as for @kbd{C-x a g}.
-
-@kindex C-x a i g
-@findex inverse-add-global-abbrev
-@kindex C-x a i l
-@findex inverse-add-mode-abbrev
- If the abbrev text itself is already in the buffer, you can use the
-commands @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and
-@kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) to define it as an
-abbrev by specify the expansion in the minibuffer. These commands are
-called ``inverse'' because they invert the meaning of the two text
-strings they use (one from the buffer and one read with the
-minibuffer).
-
-@findex define-mode-abbrev
-@findex define-global-abbrev
- You can define an abbrev without inserting either the abbrev or its
-expansion in the buffer using the command @code{define-global-abbrev}.
-It reads two arguments---the abbrev, and its expansion. The command
-@code{define-mode-abbrev} does likewise for a mode-specific abbrev.
-
- To change the definition of an abbrev, just define a new definition.
-When the abbrev has a prior definition, the abbrev definition commands
-ask for confirmation before replacing it.
-
-@findex kill-all-abbrevs
- To remove an abbrev definition, give a negative argument to the
-abbrev definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}.
-The former removes a global definition, while the latter removes a
-mode-specific definition. @kbd{M-x kill-all-abbrevs} removes all
-abbrev definitions, both global and local.
-
-@node Expanding Abbrevs
-@section Controlling Abbrev Expansion
-
- When Abbrev mode is enabled, an abbrev expands whenever it is
-present in the buffer just before point and you type a self-inserting
-whitespace or punctuation character (@key{SPC}, comma, etc.@:). More
-precisely, any character that is not a word constituent expands an
-abbrev, and any word-constituent character can be part of an abbrev.
-The most common way to use an abbrev is to insert it and then insert a
-punctuation or whitespace character to expand it.
-
-@vindex abbrev-all-caps
- Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find
-outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into
-@samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the
-variable @code{abbrev-all-caps} (setting it non-@code{nil} specifies
-@samp{FIND OUTER OTTER}).
-
- These commands are used to control abbrev expansion:
-
-@table @kbd
-@item M-'
-Separate a prefix from a following abbrev to be expanded
-(@code{abbrev-prefix-mark}).
-@item C-x a e
-@findex expand-abbrev
-Expand the abbrev before point (@code{expand-abbrev}).
-This is effective even when Abbrev mode is not enabled.
-@item M-x expand-region-abbrevs
-Expand some or all abbrevs found in the region.
-@end table
-
-@kindex M-'
-@findex abbrev-prefix-mark
- You may wish to expand an abbrev and attach a prefix to the expansion;
-for example, if @samp{cnst} expands into @samp{construction}, you might want
-to use it to enter @samp{reconstruction}. It does not work to type
-@kbd{recnst}, because that is not necessarily a defined abbrev. What
-you can do is use the command @kbd{M-'} (@code{abbrev-prefix-mark}) in
-between the prefix @samp{re} and the abbrev @samp{cnst}. First, insert
-@samp{re}. Then type @kbd{M-'}; this inserts a hyphen in the buffer to
-indicate that it has done its work. Then insert the abbrev @samp{cnst};
-the buffer now contains @samp{re-cnst}. Now insert a non-word character
-to expand the abbrev @samp{cnst} into @samp{construction}. This
-expansion step also deletes the hyphen that indicated @kbd{M-'} had been
-used. The result is the desired @samp{reconstruction}.
-
- If you actually want the text of the abbrev in the buffer, rather than
-its expansion, you can accomplish this by inserting the following
-punctuation with @kbd{C-q}. Thus, @kbd{foo C-q ,} leaves @samp{foo,} in
-the buffer, not expanding it.
-
-@findex unexpand-abbrev
- If you expand an abbrev by mistake, you can undo the expansion and
-bring back the abbrev itself by typing @kbd{C-_} to undo (@pxref{Undo}).
-This also undoes the insertion of the non-word character that expanded
-the abbrev. If the result you want is the terminating non-word
-character plus the unexpanded abbrev, you must reinsert the terminating
-character, quoting it with @kbd{C-q}. You can also use the command
-@kbd{M-x unexpand-abbrev} to cancel the last expansion without
-deleting the terminating character.
-
-@findex expand-region-abbrevs
- @kbd{M-x expand-region-abbrevs} searches through the region for defined
-abbrevs, and for each one found offers to replace it with its expansion.
-This command is useful if you have typed in text using abbrevs but forgot
-to turn on Abbrev mode first. It may also be useful together with a
-special set of abbrev definitions for making several global replacements at
-once. This command is effective even if Abbrev mode is not enabled.
-
- Expanding any abbrev first runs the hook @code{pre-abbrev-expand-hook}
-(@pxref{Hooks}).
-
-@need 1500
-@node Editing Abbrevs
-@section Examining and Editing Abbrevs
-
-@table @kbd
-@item M-x list-abbrevs
-Display a list of all abbrev definitions. With a numeric argument, list
-only local abbrevs.
-@item M-x edit-abbrevs
-Edit a list of abbrevs; you can add, alter or remove definitions.
-@end table
-
-@findex list-abbrevs
- The output from @kbd{M-x list-abbrevs} looks like this:
-
-@example
-@var{various other tables@dots{}}
-(lisp-mode-abbrev-table)
-"dk" 0 "define-key"
-(global-abbrev-table)
-"dfn" 0 "definition"
-@end example
-
-@noindent
-(Some blank lines of no semantic significance, and some other abbrev
-tables, have been omitted.)
-
- A line containing a name in parentheses is the header for abbrevs in a
-particular abbrev table; @code{global-abbrev-table} contains all the global
-abbrevs, and the other abbrev tables that are named after major modes
-contain the mode-specific abbrevs.
-
- Within each abbrev table, each nonblank line defines one abbrev. The
-word at the beginning of the line is the abbrev. The number that
-follows is the number of times the abbrev has been expanded. Emacs
-keeps track of this to help you see which abbrevs you actually use, so
-that you can eliminate those that you don't use often. The string at
-the end of the line is the expansion.
-
- Some abbrevs are marked with @samp{(sys)}. These ``system'' abbrevs
-(@pxref{Abbrevs,,, elisp, The Emacs Lisp Reference Manual}) are
-pre-defined by various modes, and are not saved to your abbrev file.
-To disable a ``system'' abbrev, define an abbrev of the same name that
-expands to itself, and save it to your abbrev file.
-
-@findex edit-abbrevs
-@kindex C-c C-c @r{(Edit Abbrevs)}
- @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev
-definitions by editing a list of them in an Emacs buffer. The list has
-the same format described above. The buffer of abbrevs is called
-@samp{*Abbrevs*}, and is in Edit-Abbrevs mode. Type @kbd{C-c C-c} in
-this buffer to install the abbrev definitions as specified in the
-buffer---and delete any abbrev definitions not listed.
-
- The command @code{edit-abbrevs} is actually the same as
-@code{list-abbrevs} except that it selects the buffer @samp{*Abbrevs*}
-whereas @code{list-abbrevs} merely displays it in another window.
-
-@node Saving Abbrevs
-@section Saving Abbrevs
-
- These commands allow you to keep abbrev definitions between editing
-sessions.
-
-@table @kbd
-@item M-x write-abbrev-file @key{RET} @var{file} @key{RET}
-Write a file @var{file} describing all defined abbrevs.
-@item M-x read-abbrev-file @key{RET} @var{file} @key{RET}
-Read the file @var{file} and define abbrevs as specified therein.
-@item M-x quietly-read-abbrev-file @key{RET} @var{file} @key{RET}
-Similar but do not display a message about what is going on.
-@item M-x define-abbrevs
-Define abbrevs from definitions in current buffer.
-@item M-x insert-abbrevs
-Insert all abbrevs and their expansions into current buffer.
-@end table
-
-@findex write-abbrev-file
- @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and
-then writes a description of all current abbrev definitions into that
-file. This is used to save abbrev definitions for use in a later
-session. The text stored in the file is a series of Lisp expressions
-that, when executed, define the same abbrevs that you currently have.
-
-@findex read-abbrev-file
-@findex quietly-read-abbrev-file
-@vindex abbrev-file-name
- @kbd{M-x read-abbrev-file} reads a file name using the minibuffer
-and then reads the file, defining abbrevs according to the contents of
-the file. The function @code{quietly-read-abbrev-file} is similar
-except that it does not display a message in the echo area; you cannot
-invoke it interactively, and it is used primarily in the @file{.emacs}
-file. If either of these functions is called with @code{nil} as the
-argument, it uses the file name specified in the variable
-@code{abbrev-file-name}, which is by default @code{"~/.abbrev_defs"}.
-That file is your standard abbrev definition file, and Emacs loads
-abbrevs from it automatically when it starts up.
-
-@vindex save-abbrevs
- Emacs will offer to save abbrevs automatically if you have changed
-any of them, whenever it offers to save all files (for @kbd{C-x s} or
-@kbd{C-x C-c}). It saves them in the file specified by
-@code{abbrev-file-name}. This feature can be inhibited by setting the
-variable @code{save-abbrevs} to @code{nil}.
-
-@findex insert-abbrevs
-@findex define-abbrevs
- The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are
-similar to the previous commands but work on text in an Emacs buffer.
-@kbd{M-x insert-abbrevs} inserts text into the current buffer after point,
-describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses
-the entire current buffer and defines abbrevs accordingly.
-
-@node Dynamic Abbrevs
-@section Dynamic Abbrev Expansion
-
- The abbrev facility described above operates automatically as you
-insert text, but all abbrevs must be defined explicitly. By contrast,
-@dfn{dynamic abbrevs} allow the meanings of abbreviations to be
-determined automatically from the contents of the buffer, but dynamic
-abbrev expansion happens only when you request it explicitly.
-
-@kindex M-/
-@kindex C-M-/
-@findex dabbrev-expand
-@findex dabbrev-completion
-@table @kbd
-@item M-/
-Expand the word in the buffer before point as a @dfn{dynamic abbrev},
-by searching in the buffer for words starting with that abbreviation
-(@code{dabbrev-expand}).
-
-@item C-M-/
-Complete the word before point as a dynamic abbrev
-(@code{dabbrev-completion}).
-@end table
-
-@vindex dabbrev-limit
- For example, if the buffer contains @samp{does this follow } and you
-type @kbd{f o M-/}, the effect is to insert @samp{follow} because that
-is the last word in the buffer that starts with @samp{fo}. A numeric
-argument to @kbd{M-/} says to take the second, third, etc.@: distinct
-expansion found looking backward from point. Repeating @kbd{M-/}
-searches for an alternative expansion by looking farther back. After
-scanning all the text before point, it searches the text after point.
-The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how far
-away in the buffer to search for an expansion.
-
-@vindex dabbrev-check-all-buffers
- After scanning the current buffer, @kbd{M-/} normally searches other
-buffers, unless you have set @code{dabbrev-check-all-buffers} to
-@code{nil}.
-
-@vindex dabbrev-ignored-buffer-regexps
- For finer control over which buffers to scan, customize the variable
-@code{dabbrev-ignored-buffer-regexps}. Its value is a list of regular
-expressions. If a buffer's name matches any of these regular
-expressions, dynamic abbrev expansion skips that buffer.
-
- A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to
-search first for expansions after point, then other buffers, and
-consider expansions before point only as a last resort. If you repeat
-the @kbd{M-/} to look for another expansion, do not specify an
-argument. Repeating @kbd{M-/} cycles through all the expansions after
-point and then the expansions before point.
-
- After you have expanded a dynamic abbrev, you can copy additional
-words that follow the expansion in its original context. Simply type
-@kbd{@key{SPC} M-/} for each additional word you want to copy. The
-spacing and punctuation between words is copied along with the words.
-
- The command @kbd{C-M-/} (@code{dabbrev-completion}) performs
-completion of a dynamic abbrev. Instead of trying the possible
-expansions one by one, it finds all of them, then inserts the text
-that they have in common. If they have nothing in common, @kbd{C-M-/}
-displays a list of completions, from which you can select a choice in
-the usual manner. @xref{Completion}.
-
- Dynamic abbrev expansion is completely independent of Abbrev mode; the
-expansion of a word with @kbd{M-/} is completely independent of whether
-it has a definition as an ordinary abbrev.
-
-@node Dabbrev Customization
-@section Customizing Dynamic Abbreviation
-
- Normally, dynamic abbrev expansion ignores case when searching for
-expansions. That is, the expansion need not agree in case with the word
-you are expanding.
-
-@vindex dabbrev-case-fold-search
- This feature is controlled by the variable
-@code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored in
-this search; if it is @code{nil}, the word and the expansion must match
-in case. If the value of @code{dabbrev-case-fold-search} is
-@code{case-fold-search}, which is true by default, then the variable
-@code{case-fold-search} controls whether to ignore case while searching
-for expansions.
-
-@vindex dabbrev-case-replace
- Normally, dynamic abbrev expansion preserves the case pattern
-@emph{of the dynamic abbrev you are expanding}, by converting the
-expansion to that case pattern.
-
-@vindex dabbrev-case-fold-search
- The variable @code{dabbrev-case-replace} controls whether to
-preserve the case pattern of the dynamic abbrev. If it is @code{t},
-the dynamic abbrev's case pattern is preserved in most cases; if it is
-@code{nil}, the expansion is always copied verbatim. If the value of
-@code{dabbrev-case-replace} is @code{case-replace}, which is true by
-default, then the variable @code{case-replace} controls whether to
-copy the expansion verbatim.
-
- However, if the expansion contains a complex mixed case pattern, and
-the dynamic abbrev matches this pattern as far as it goes, then the
-expansion is always copied verbatim, regardless of those variables.
-Thus, for example, if the buffer contains
-@code{variableWithSillyCasePattern}, and you type @kbd{v a M-/}, it
-copies the expansion verbatim including its case pattern.
-
-@vindex dabbrev-abbrev-char-regexp
- The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil},
-controls which characters are considered part of a word, for dynamic expansion
-purposes. The regular expression must match just one character, never
-two or more. The same regular expression also determines which
-characters are part of an expansion. The value @code{nil} has a special
-meaning: dynamic abbrevs are made of word characters, but expansions are
-made of word and symbol characters.
-
-@vindex dabbrev-abbrev-skip-leading-regexp
- In shell scripts and makefiles, a variable name is sometimes prefixed
-with @samp{$} and sometimes not. Major modes for this kind of text can
-customize dynamic abbrev expansion to handle optional prefixes by setting
-the variable @code{dabbrev-abbrev-skip-leading-regexp}. Its value
-should be a regular expression that matches the optional prefix that
-dynamic abbrev expression should ignore.
-
-@ignore
- arch-tag: 638e0079-9540-48ec-9166-414083e16445
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2002, 2003,
-@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@c
-@node Acknowledgments, Screen, Concept Index, Top
-@unnumbered Acknowledgments
-
-Many people have contributed code included in the Free Software
-Foundation's distribution of GNU Emacs. To show our appreciation for
-their public spirit, we list here in alphabetical order those who have
-written substantial portions.
-
-@c We should list here anyone who has contributed a new package,
-@c and anyone who has made major enhancements in Emacs
-@c that many users would notice and consider important.
-
-@itemize @bullet
-@item
-Per Abrahamsen wrote the customization buffer facilities, as well as
-@file{double.el} for typing accented characters not normally available
-from the keyboard, @file{xt-mouse.el} which handles mouse commands
-through Xterm, @file{gnus-cus.el} which implements customization
-commands for Gnus, @file{gnus-cite.el}, a citation-parsing facility
-for news articles and @file{cpp.el} which hides or highlights parts of
-C programs according to preprocessor conditionals.
-
-@item
-Tomas Abrahamsson wrote @file{artist.el}, a package for producing @acronym{ASCII}
-art with a mouse or with keyboard keys.
-
-@item
-Jay K.@: Adams wrote @file{jka-compr.el}, providing automatic
-decompression and recompression for compressed files.
-
-@item
-Ralf Angeli wrote @file{scroll-lock.el}, a minor mode which keeps the
-point vertically fixed by scrolling the window when moving up and down
-in the buffer.
-
-@item
-Joe Arceneaux wrote the original text property implementation, and
-implemented support for X11.
-
-@item
-Miles Bader wrote @file{image-file.el}, support code for visiting
-image files, @file{minibuf-eldef.el}, a minor mode whereby the default
-value is shown in the minibuffer prompt only when appropriate, and
-@file{button.el}, the library that implements clickable buttons.
-
-@item
-David Bakhash wrote @file{strokes.el}, a mode for controlling Emacs by
-moving the mouse in particular patterns.
-
-@item
-Eli Barzilay wrote @file{calculator.el}, a desktop calculator for
-Emacs.
-
-@item
-Steven L.@: Baur wrote
-@c If earcon.el actually works with Emacs 21, it isn't useful for lack
-@c of sound files. -- fx
-@c @file{earcon.el}, a facility for sound effects
-@c for email and news messages,
-@file{footnote.el} which lets you include
-footnotes in email messages, and @file{gnus-audio.el} which provides
-sound effects for Gnus.
-
-@item
-Alexander L. Belikoff, Sergey Berezin, David Edmondson, Andreas
-Fuchs, Mario Lang, Gergely Nagy, Michael Olson, and Alex Schroeder
-contributed ERC, an advanced Internet Relay Chat client.
-
-@item
-Boaz Ben-Zvi wrote @file{profile.el}, to time Emacs Lisp functions.
-
-@item
-Anna M. Bigatti wrote @file{cal-html.el}, which produces HTML calendars.
-
-@item
-Ray Blaak wrote @file{delphi.el}, a major mode for editing Delphi
-(Object Pascal) source code.
-
-@item
-Jim Blandy wrote Emacs 19's input system, brought its configuration and
-build process up to the GNU coding standards, and contributed to the
-frame support and multi-face support. Jim also wrote @file{tvi970.el},
-terminal support for the TeleVideo 970 terminals.
-
-@item
-Per Bothner wrote @file{term.el}, a terminal emulator in an Emacs
-buffer.
-
-@item
-Terrence M.@: Brannon wrote @file{landmark.el}, a neural-network robot
-that learns landmarks.
-
-@item
-Frank Bresz wrote @file{diff.el}, a program to display @code{diff}
-output.
-
-@item
-Peter Breton implemented:
-
-@itemize @minus
-@item
-@file{dirtrack} which does better tracking of directory changes in shell
-buffers,
-@item
-@file{filecache.el} which records which directories your files are in,
-@item
-@file{locate.el} which interfaces to the @code{locate} command,
-@item
-@file{find-lisp.el}, an Emacs Lisp emulation of the @code{find} program,
-@item
-@file{net-utils.el}, and
-@item
-the ``generic mode'' feature.
-@end itemize
-
-@item
-Emmanuel Briot wrote @file{xml.el}, an XML parser for Emacs.
-
-@item
-Kevin Broadey wrote @file{foldout.el}, providing folding extensions to
-Emacs's outline modes.
-
-@c @item
-@c Vincent Broman wrote @file{ada.el}, a mode for editing Ada code
-@c (since replaced by @file{ada-mode.el}).
-
-@item
-David M.@: Brown wrote @file{array.el}, for editing arrays and other
-tabular data.
-
-@item
-W@l{}odek Bzyl and Ryszard Kubiak wrote @file{ogonek.el}, a package for
-changing the encoding of Polish characters.
-
-@item
-Bill Carpenter provided @file{feedmail.el}, a package for massaging
-outgoing mail messages and sending them through various popular mailers.
-
-@item
-Per Cederqvist and Inge Wallin wrote @file{ewoc.el}, an Emacs widget for
-manipulating object collections.
-
-@item
-Hans Chalupsky wrote @file{advice.el}, an overloading mechanism for
-Emacs Lisp functions, and @file{trace.el}, a tracing facility for Emacs
-Lisp.
-
-@item
-Chris Chase and Carsten Dominik wrote @file{idlwave.el}, an editing mode
-for IDL and WAVE CL.
-
-@item
-Bob Chassell wrote @file{texnfo-upd.el} and @file{makeinfo.el}, modes
-and utilities for working with Texinfo files; and @file{page-ext.el},
-commands for extended page handling.
-
-@item
-Andrew Choi wrote the Macintosh support code, and contributed
-@file{mac-win.el}, support for the Mac window system.
-
-@item
-James Clark wrote @file{sgml-mode.el}, a mode for editing SGML
-documents, and contributed to Emacs's dumping procedures.
-
-@item
-Mike Clarkson wrote @file{edt.el}, an emulation of DEC's EDT editor.
-
-@item
-Glynn Clements provided @file{gamegrid.el} and a couple of games that
-use it, Snake and Tetris.
-
-@item
-Georges Brun-Cottan and Stefan Monnier wrote @file{easy-mmode.el}, a
-package for easy definition of major and minor modes.
-
-@item
-Andrew Csillag wrote M4 mode (@file{m4-mode.el}).
-
-@item
-Doug Cutting and Jamie Zawinski wrote @file{disass.el}, a disassembler
-for compiled Emacs Lisp code.
-
-@item
-Mathias Dahl wrote @file{image-dired.el}, a package for viewing image
-files as ``thumbnails.''
-
-@item
-Michael DeCorte wrote @file{emacs.csh}, a C-shell script that starts a
-new Emacs job, or restarts a paused Emacs if one exists.
-
-@item
-Gary Delp wrote @file{mailpost.el}, an interface between RMAIL and the
-@file{/usr/uci/post} mailer.
-
-@item
-Matthieu Devin wrote @file{delsel.el}, a package to make newly-typed
-text replace the current selection.
-
-@item
-Eric Ding contributed @file{goto-addr.el},
-
-@item
-Jan Dj@"{a}rv added support for the GTK+ toolkit and X drag-and-drop.
-
-@item
-Carsten Dominik wrote @file{reftex.el}, a package for setting up
-labels and cross-references in La@TeX{} documents, and @file{org.el},
-a mode for maintaining notes, todo lists, and project planning.
-
-@item
-Scott Draves wrote @file{tq.el}, help functions for maintaining
-transaction queues between Emacs and its subprocesses.
-
-@item
-Benjamin Drieu wrote @file{pong.el}, an implementation of the classical
-pong game.
-
-@item
-Viktor Dukhovni wrote support for dumping under SunOS version 4.
-
-@item
-John Eaton co-wrote Octave mode.
-
-@item
-Rolf Ebert co-wrote Ada mode (@file{ada-mode.el}).
-
-@item
-Stephen Eglen implemented @file{mspools.el}, for use with Procmail,
-which tells you which mail folders have mail waiting in them, and
-@file{iswitchb.el}, a feature for incremental reading and completion of
-buffer names.
-
-@item
-Torbj@"orn
-Einarsson contributed the Fortran 90 mode (@file{f90.el}).
-
-@item
-Tsugutomo Enami co-wrote the support for international character sets.
-
-@item
-Hans Henrik Eriksen wrote @file{simula.el}, a mode for editing SIMULA 87
-code.
-
-@item
-Michael Ernst wrote @file{reposition.el}, a command for recentering a
-function's source code and preceding comment on the screen.
-
-@item
-Ata Etemadi wrote @file{cdl.el}, functions for working with Common Data
-Language source code.
-
-@item
-Frederick Farnbach implemented @file{morse.el}, which converts text to
-Morse code.
-
-@item
-Oscar Figueiredo wrote EUDC, the Emacs Unified Directory Client, which
-is an interface to directory servers via LDAP, CCSO PH/QI, or BBDB; and
-@file{ldap.el}, the LDAP client interface.
-
-@item
-Fred Fish wrote the support for dumping COFF executable files.
-
-@item
-Karl Fogel wrote:
-
-@itemize @minus
-@item
-@file{bookmark.el}, for creating named placeholders, saving them and
-jumping to them later,
-@item
-@file{mail-hist.el}, a history mechanism for outgoing mail messages, and
-@item
-@file{saveplace.el}, for preserving point's location in files between
-editing sessions.
-@end itemize
-
-@item
-Gary Foster wrote @file{crisp.el}, the emulation for CRiSP and Brief
-editors, and @file{scroll-lock.el} (now @file{scroll-all.el}) a mode
-for scrolling several buffers together.
-
-@item
-Noah Friedman wrote @file{rlogin.el}, an interface to Rlogin,
-@file{type-break.el}, which reminds you to take periodic breaks from
-typing, and @code{eldoc-mode}, a mode to show the defined parameters or
-the doc string for the Lisp function near point. With Roland McGrath,
-he wrote @file{rsz-mini.el}, a minor mode to automatically resize the
-minibuffer to fit the text it contains.
-
-@item
-Keith Gabryelski wrote @file{hexl.el}, a mode for editing binary files.
-
-@item
-Kevin Gallagher rewrote and enhanced the EDT emulation, and wrote
-@file{flow-ctrl.el}, a package for coping with unsuppressible XON/XOFF
-flow control.
-
-@item
-Kevin Gallo added multiple-frame support for Windows NT and wrote
-@file{w32-win.el}, support functions for the MS-Windows window system.
-
-@item
-Juan Le@'{o}n Lahoz Garc@'{i}a wrote @file{wdired.el}, a package for
-performing file operations by directly editing Dired buffers.
-
-@item
-Howard Gayle wrote:
-
-@itemize @minus
-@item
-the C and lisp code for display tables and case tables,
-@item
-@file{rot13.el}, a command to display the plain-text form of a buffer
-encoded with the Caesar cipher,
-@item
-@file{case-table.el}, code to extend the character set and support case
-tables,
-@item
-much of the support for the ISO-8859 European character sets (which
-includes @file{iso-ascii.el}, @file{iso-insert.el}, @file{iso-swed.el},
-@file{latin-1.el}, @file{iso-syntax.el}, @file{iso-transl.el},
-@file{swedish.el}), and
-@item
-@file{vt100-led.el}, a package for controlling the LED's on
-VT100-compatible terminals.
-@end itemize
-
-@item
-Stephen Gildea made the Emacs quick reference card, and made many
-contributions for @file{time-stamp.el}, a package for maintaining
-last-change time stamps in files.
-
-@item
-Julien Gilles wrote @file{gnus-ml.el}, a mailing list minor mode for
-Gnus.
-
-@item
-David Gillespie wrote:
-
-@itemize @minus
-@item
-The Common Lisp compatibility packages,
-@item
-@code{Calc}, an advanced calculator and mathematical tool,
-@item
-@file{complete.el}, a partial completion mechanism, and
-@item
-@file{edmacro.el}, a package for editing keyboard macros.
-@end itemize
-
-@item
-Bob Glickstein contributed the @file{sregex.el} feature, a facility for
-writing regexps using a Lisp-like syntax.
-
-@item
-Boris Goldowsky wrote:
-
-@itemize @minus
-@item
-@file{avoid.el}, a package to keep the mouse cursor out of the way of
-the text cursor,
-@item
-@file{shadowfile.el}, a package for keeping identical copies of files in
-more than one place,
-@item
-@file{format.el}, a package for reading and writing files in various
-formats,
-@item
-@file{enriched.el}, a package for saving text properties in files, and
-@item
-@file{facemenu.el}, a package for specifying faces.
-@end itemize
-
-@item
-Michelangelo Grigni wrote @file{ffap.el} which visits a file,
-taking the file name from the buffer.
-
-@item
-Odd Gripenstam wrote @file{dcl-mode.el} for editing DCL command files.
-
-@item
-Kai Gro@ss{}johann and Michael Albinus wrote the Tramp package, which
-provides transparent remote file editing using rcp, ssh, ftp, and other
-network protocols.
-
-@item
-Michael Gschwind wrote @file{iso-cvt.el}, a package to convert between
-the ISO 8859-1 character set and the notations for non-@acronym{ASCII}
-characters used by @TeX{} and net tradition, and @file{latin-2.el}, code
-which sets up case-conversion and syntax tables for the ISO Latin-2
-character set.
-
-@item
-Henry Guillaume wrote @file{find-file.el}, a package to visit files
-related to the currently visited file.
-
-@item
-Doug Gwyn wrote the portable @code{alloca} implementation.
-
-@item
-Ken'ichi Handa implemented most of the support for international
-character sets, and wrote @file{isearch-x.el}, a facility for searching
-non-@acronym{ASCII} text. Together with Naoto Takahashi, he wrote
-@file{quail.el}, a simple input facility for typing non-@acronym{ASCII} text from
-an @acronym{ASCII} keyboard. Ken'ichi also wrote @file{ps-bdf.el}, a BDF font
-support for printing non-@acronym{ASCII} text on a PostScript printer.
-
-@item
-Chris Hanson wrote @file{netuname.el}, a package to use HP-UX's Remote
-File Access facility from Emacs.
-
-@item
-Jesper Harder wrote @file{yenc.el}, for decoding yenc encoded messages.
-
-@item
-K. Shane Hartman wrote:
-
-@itemize @minus
-@item
-@file{chistory.el} and @file{echistory.el}, packages for browsing
-command history lists,
-@item
-@file{electric.el} and @file{helper.el}, providing an alternative
-command loop and appropriate help facilities,
-@item
-@file{emacsbug.el}, a package for reporting Emacs bugs,
-@item
-@file{picture.el}, a mode for editing @acronym{ASCII} pictures, and
-@item
-@file{view.el}, a package for perusing files and buffers without editing
-them.
-@end itemize
-
-@item
-John Heidemann wrote @file{mouse-copy.el} and @file{mouse-drag.el},
-which provide alternative mouse-based editing and scrolling features.
-
-@item
-Jon K Hellan wrote @file{utf7.el}, support for mail-safe transformation
-format of Unicode.
-
-@item
-Markus Heritsch co-wrote Ada mode (@file{ada-mode.el}).
-
-@item
-Karl Heuer wrote the original blessmail script, implemented the
-@code{intangible} text property, and rearranged the structure of the
-@code{Lisp_Object} type to allow for more data bits.
-
-@item
-Manabu Higashida ported Emacs to MS-DOS.
-
-@item
-Anders Holst wrote @file{hippie-exp.el}, a versatile completion and
-expansion package.
-
-@item
-Kurt Hornik co-wrote Octave mode.
-
-@item
-Tom Houlder wrote @file{mantemp.el}, which generates manual C@t{++}
-template instantiations.
-
-@item
-Joakim Hove wrote @file{html2text.el}, a html to plain text converter.
-@item
-Denis Howe wrote @file{browse-url.el}, a package for invoking a WWW
-browser to display a URL.
-
-@item
-Lars Magne Ingebrigtsen did a major redesign of the Gnus news-reader and
-wrote many of its parts.
-
-@item
-Andrew Innes contributed extensively to the MS-Windows support.
-
-@item
-Seiichiro Inoue improved Emacs's XIM support.
-
-@item
-Ulf Jasper wrote @file{icalendar.el}, a package for converting Emacs
-diary entries to and from the iCalendar format, and
-@file{newsticker.el}, an RSS and Atom based Newsticker.
-
-@item
-Kyle Jones wrote @file{life.el}, a package to play Conway's ``life'' game,
-and @file{mldrag.el}, a package which allows the user to resize windows
-by dragging mode lines and vertical window separators with the mouse.
-
-@item
-Terry Jones wrote @file{shadow.el}, a package for finding potential
-load-path problems when some Lisp file ``shadows'' another.
-
-@item
-Simon Josefsson wrote:
-
-@itemize @minus
-@item
-@file{dns-mode.el}, an editing mode for Domain Name System master files,
-@item
-@file{flow-fill.el}, a package for interpreting RFC2646 formatted text
-in messages,
-@item
-@file{fringe.el}, a package for customizing the fringe,
-@item
-@file{imap.el}, an Emacs Lisp library for talking to IMAP servers,
-@item
-@file{nnimap}, the IMAP back-end for Gnus, and
-@item
-@file{rfc2104.el}, a hashed message authentication facility.
-@end itemize
-
-@item
-Arne J@o{}rgensen wrote @file{latexenc.el}, a package to
-automatically guess the correct coding system in LaTeX files.
-
-@item
-Tomoji Kagatani implemented @file{smtpmail.el}, used for sending out
-mail with SMTP.
-
-@item
-David Kaufman wrote @file{yow.c}, an essential utility program for the
-hopelessly pinheaded.
-
-@item
-Henry Kautz wrote @file{bib-mode.el}, a mode for maintaining
-bibliography databases compatible with @code{refer} (the @code{troff}
-version) and @code{lookbib}, and @file{refbib.el}, a package to convert
-those databases to the format used by the LaTeX text formatting package.
-
-@item
-Taichi Kawabata added support for Devanagari script and the Indian
-languages.
-
-@item
-Howard Kaye wrote @file{sort.el}, commands to sort text in Emacs
-buffers.
-
-@item
-Michael Kifer wrote @file{ediff.el}, an interactive interface to the
-@command{diff}, @command{patch}, and @command{merge} programs, and
-Viper, the newest emulation for VI.
-
-@item
-Richard King wrote the first version of @file{userlock.el} and
-@file{filelock.c}, which provide simple support for multiple users
-editing the same file. He also wrote the initial version of
-@file{uniquify.el}, a facility to make buffer names unique by adding
-parts of the file's name to the buffer name.
-@c We're not using his backquote.el any more.
-
-@item
-Peter Kleiweg wrote @file{ps-mode.el}, a major mode for editing
-PostScript files and running a PostScript interpreter interactively from
-within Emacs.
-
-@item
-Pavel Kobiakov wrote @file{flymake.el}, a minor mode for performing
-on-the-fly syntax checking.
-
-@item
-Larry K.@: Kolodney wrote @file{cvtmail.c}, a program to convert the mail
-directories used by Gosling Emacs into RMAIL format.
-
-@item
-David M.@: Koppelman wrote @file{hi-lock.el}, a minor mode for
-interactive automatic highlighting of parts of the buffer text.
-
-@item
-Koseki Yoshinori wrote @file{iimage.el}, a minor mode for displaying
-inline images.
-
-@item
-Robert Krawitz wrote the original @file{xmenu.c}, part of Emacs's pop-up
-menu support.
-
-@item
-Sebastian Kremer wrote Emacs 19's @code{dired-mode}, with contributions
-by Lawrence R.@: Dodd. He also wrote @file{ls-lisp.el}, a Lisp emulation
-of the @code{ls} command for platforms which don't have @code{ls} as a
-standard program.
-
-@item
-Geoff Kuenning wrote Emacs 19's @file{ispell.el}, based on work by Ken
-Stevens and others.
-
-@item
-David K@ringaccent{a}gedal wrote @file{tempo.el}, providing support for
-easy insertion of boilerplate text and other common constructions.
-
-@item
-Daniel LaLiberte wrote:
-
-@itemize @minus
-@item
-@file{edebug.el}, a source-level debugger for Emacs Lisp,
-@item
-@file{cl-specs.el}, specifications to help @code{edebug} debug code
-written using David Gillespie's Common Lisp support,
-@item
-@file{cust-print.el}, a customizable package for printing lisp objects,
-@item
-@file{eval-reg.el}, a re-implementation of @code{eval-region} in Emacs
-Lisp, and
-@item
-@file{isearch.el}, Emacs's incremental search minor mode.
-@end itemize
-
-@item
-James R.@: Larus wrote @file{mh-e.el}, an interface to the MH mail system.
-
-@item
-Vinicius Jose Latorre wrote the Emacs printing facilities, as well as:
-
-@itemize @minus
-@item
-@code{ps-print}, a package for pretty-printing Emacs buffers to
-PostScript printers,
-@item
-@file{delim-col.el}, a package to arrange text into columns,
-@item
-@file{ebnf2ps.el}, a package that translates EBNF grammar to a syntactic
-chart that can be printed to a PostScript printer.
-@end itemize
-
-@item
-Frederic Lepied contributed @file{expand.el}, which uses the abbrev
-mechanism for inserting programming constructs.
-
-@item
-Peter Liljenberg wrote @file{elint.el}, a Lint-style code checker for
-Emacs Lisp programs.
-
-@item
-Lars Lindberg wrote @file{msb.el}, which provides more flexible menus
-for buffer selection, and rewrote @file{dabbrev.el}.
-
-@item
-Anders Lindgren wrote @file{autorevert.el}, a package for automatically
-reverting files visited by Emacs that were changed on disk;
-@file{cwarn.el}, a package to highlight suspicious C and C@t{++}
-constructs; and @file{follow.el}, a minor mode to synchronize windows
-that show the same buffer.
-
-@item
-Thomas Link wrote @file{filesets.el}, a package for handling sets of
-files.
-
-@item
-Dave Love wrote much of the code dealing with Unicode support and
-Latin-N unification. He added support for many coding systems,
-including those in @file{code-pages.el} and the various UTF-7 and
-UTF-16 coding systems. He also wrote:
-
-@itemize @minus
-@item
-@code{autoarg-mode}, a global minor mode whereby digit keys supply
-prefix arguments, and @code{autoarg-kp-mode} which redefines the keypad
-numeric keys to digit arguments,
-@item
-@file{autoconf.el}, a mode for editing Autoconf @file{configure.in}
-files,
-@item
-@file{cfengine.el}, a mode for editing Cfengine files,
-@item
-@file{elide-head.el}, a package for eliding boilerplate text, such as
-copyright notices, from file headers,
-@item
-@file{hl-line.el}, a package that provides a minor mode for highlighting
-the line in the current window on which point is,
-@item
-@file{latin-8.el} and @file{latin-9.el}, code which sets up
-case-conversion and syntax tables for the ISO Latin-8 and Latin-9
-character sets,
-@item
-@file{latin1-disp.el}, a package that lets you display ISO 8859
-characters on Latin-1 terminals by setting up appropriate display
-tables,
-@item
-@file{python.el}, a major mode for the Python programming language.
-@item
-@file{refill.el}, a mode for automatic paragraph refilling, akin to
-typical word processors,
-@item
-@file{smiley-ems.el}, a facility for displaying smiley faces, and
-@item
-@file{tool-bar.el}, a mode to control the display of the Emacs tool bar.
-@end itemize
-
-@item
-Eric Ludlam wrote the Speedbar package and the following packages:
-
-@itemize @minus
-@item
-@file{checkdoc.el}, for checking doc strings in Emacs Lisp programs,
-@item
-@file{dframe.el}, providing dedicatd frame support modes, and
-@item
-@file{ezimage.el}, a generalized way to place images over text.
-@end itemize
-
-@item
-Alan Mackenzie wrote the integrated AWK support in CC Mode.
-
-@item
-Christopher J.@: Madsen wrote @file{decipher.el}, a package for cracking
-simple substitution ciphers.
-
-@item
-Neil M.@: Mager wrote @file{appt.el}, functions to notify users of their
-appointments. It finds appointments recorded in the diary files
-generated by Edward M.@: Reingold's @code{calendar} package.
-
-@item
-Ken Manheimer wrote @file{allout.el}, a mode for manipulating and
-formatting outlines, and @file{icomplete.el}, which provides incremental
-completion feedback in the minibuffer.
-
-@item
-Bill Mann wrote @file{perl-mode.el}, a mode for editing Perl code.
-
-@item
-Brian Marick and Daniel LaLiberte wrote @file{hideif.el}, support for
-hiding selected code within C @code{#ifdef} clauses.
-
-@item
-Simon Marshall wrote @file{regexp-opt.el}, which generates a regular
-expression from a list of strings. He also extended @file{comint.el},
-originally written by Olin Shivers.
-
-@item
-Bengt Martensson, Marc Shapiro, Mike Newton, Aaron Larson, and Stefan
-Schoef, wrote @file{bibtex.el}, a mode for editing Bib@TeX{}
-bibliography files.
-
-@item
-Charlie Martin wrote @file{autoinsert.el}, which provides automatic
-mode-sensitive insertion of text into new files.
-
-@item
-Thomas May wrote @file{blackbox.el}, a version of the traditional
-blackbox game.
-
-@item
-Roland McGrath wrote:
-
-@itemize @minus
-@item
-@file{compile.el}, a package for running compilations in a buffer, and
-then visiting the locations reported in error messages,
-@item
-@file{etags.el}, a package for jumping to function definitions and
-searching or replacing in all the files mentioned in a @file{TAGS} file,
-@item
-@file{find-dired.el}, for using @code{dired} commands on output from the
-@code{find} program, with Sebastian Kremer,
-@item
-@file{map-ynp.el}, a general purpose boolean question-asker,
-@item
-@file{autoload.el}, providing semi-automatic maintenance of autoload
-files, and
-@item
-@file{upd-copyr.el}, providing semi-automatic maintenance of copyright
-notices in source code.
-@end itemize
-
-@item
-David Megginson wrote @file{derived.el}, which allows one to define new
-major modes by inheriting key bindings and commands from existing major
-modes.
-
-@item
-Will Mengarini wrote @file{repeat.el}, a command to repeat the preceding
-command with its arguments.
-
-@item
-Wayne Mesard wrote @file{hscroll.el} which does horizontal scrolling
-automatically.
-
-@item
-Brad Miller wrote @file{gnus-gl.el}, a Gnus interface for GroupLens.
-
-@item
-Richard Mlynarik wrote:
-
-@itemize @minus
-@item
-@file{cl-indent.el}, a package for indenting Common Lisp code,
-@item
-@file{ebuff-menu.el}, an ``electric'' browser for buffer listings,
-@item
-@file{ehelp.el}, bindings for browsing help screens,
-@item
-@file{rfc822.el}, a parser for E-mail addresses in the RFC-822 format,
-used in mail messages and news articles,
-@item
-@file{terminal.el}, a terminal emulator for Emacs subprocesses, and
-@item
-@file{yow.el}, an essential utility (try @kbd{M-x yow}).
-@end itemize
-
-@item
-Gerd Moellmann was the Emacs maintainer from the beginning of Emacs 21
-development until the release of 21.1. He wrote:
-
-@itemize @minus
-@item
-the new display engine for Emacs 21,
-@item
-the asynchronous timers facility (@file{atimer.c}),
-@item
-the @code{ebrowse} C@t{++} browser,
-@item
-@file{jit-lock.el}, the Just-In-Time font-lock support mode,
-@item
-@file{tooltip.el}, a package for displaying tooltips, and
-@item
-@file{authors.el} package for maintaining the @file{AUTHORS} files.
-@end itemize
-
-@item
-Stefan Monnier added support for Arch, Subversion, and Meta-CVS to VC,
-and re-wrote much of the Emacs server to use the built-in networking
-primitives. He also wrote:
-
-@itemize @minus
-@item
-@code{PCL-CVS}, a directory-level front end to the CVS version control
-system,
-@item
-@file{reveal.el}, a minor mode for automatically revealing invisible
-text,
-@item
-@file{smerge-mode.el}, a minor mode for resolving @code{diff3}
-conflicts, and
-@item
-@file{diff-mode.el}, a mode for viewing and editing context diffs.
-@end itemize
-
-@item
-Morioka Tomohiko wrote several packages for MIME support in Gnus and
-elsewhere.
-
-@item
-Sen Nagata wrote @file{crm.el}, a package for reading multiple strings
-with completion, and @file{rfc2368.el}, support for @code{mailto:}
-URLs.
-
-@item
-Erik Naggum wrote the time-conversion functions. He also wrote
-@file{disp-table.el}, a package for dealing with display tables,
-@file{latin-4.el} and @file{latin-5.el}, code which sets up
-case-conversion and syntax tables for the ISO Latin-4 and Latin-5
-character sets, @file{mailheader.el}, a package for parsing email
-headers, and @file{parse-time.el}, a package for parsing time strings.
-
-@item
-Thomas Neumann and Eric Raymond wrote @file{makefile.el} (now
-@file{make-mode.el}), a mode for editing makefiles.
-
-@item
-Thien-Thi Nguyen and Dan Nicolaescu wrote @file{hideshow.el}, a minor
-mode for selectively displaying blocks of text.
-
-@item
-Dan Nicolaescu wrote @file{romanian.el}, support for editing Romanian
-text, and @file{iris-ansi.el}, support for running Emacs on SGI's
-@code{xwsh} and @code{winterm} terminal emulators.
-
-@item
-Jurgen Nickelsen wrote @file{ws-mode.el}, providing WordStar emulation.
-
-@item
-Hrvoje Niksic wrote @file{savehist.el}, for saving the minibuffer
-history between Emacs sessions.
-
-@item
-Jeff Norden wrote @file{kermit.el}, a package to help the Kermit
-dialup communications program run comfortably in an Emacs shell buffer.
-
-@item
-Andrew Norman wrote @file{ange-ftp.el}, providing transparent FTP
-support.
-
-@item
-Alexandre Oliva wrote @file{gnus-mlspl.el}, a group params-based mail
-splitting mechanism.
-
-@item
-Takaaki Ota wrote @file{table.el}, a package for creating and editing
-embedded text-based tables.
-
-@item
-Pieter E.@: J.@: Pareit wrote @file{mixal-mode.el}, an editing mode for
-the MIX assembly language.
-
-@item
-David Pearson contributed @file{quickurl.el}, a simple method of
-inserting a URL into the current buffer based on text at point;
-@file{5x5.el}, a game to fill all squares on the field.
-
-@item
-Jeff Peck wrote:
-
-@itemize @minus
-@item
-@file{emacstool.c}, support for running Emacs under SunView/Sun Windows,
-@item
-@file{sun.el}, key bindings for sunterm keys,
-@item
-@file{sun-curs.el}, cursor definitions for Sun Windows, and
-@item
-@file{sun-fns.el} and @file{sun-mouse.el}, providing mouse support for
-Sun Windows.
-@end itemize
-
-@item
-Damon Anton Permezel wrote @file{hanoi.el}, an animated demonstration of
-the ``Towers of Hanoi'' puzzle.
-
-@item
-William M.@: Perry wrote @file{mailcap.el}, a MIME media types
-configuration facility, @file{mwheel.el}, a package for supporting
-mouse wheels, and the URL package.
-
-@item
-Per Persson wrote @file{gnus-vm.el}, the VM interface for Gnus.
-
-@item
-Jens Petersen wrote @file{find-func.el}, which makes it easy to find
-the source code for an Emacs Lisp function or variable.
-
-@item
-Daniel Pfeiffer wrote:
-
-@itemize @minus
-@item
-@file{conf-mode.el}, a major mode for editing configuration files,
-@item
-@file{copyright.el}, a package for updating copyright notices in files,
-@item
-@file{executable.el}, a package for executing interpreter scripts,
-@item
-@file{sh-script.el}, a mode for editing shell scripts,
-@item
-@file{skeleton.el}, implementing a concise language for writing
-statement skeletons, and
-@item
-@file{two-column.el}, a minor mode for simultaneous two-column editing.
-@end itemize
-
-Daniel also rewrote @file{apropos.el}, originally written by Joe Wells,
-and, together with Jim Blandy, co-authored @file{wyse50.el}, support for
-Wyse 50 terminals.
-
-@item
-Richard L.@: Pieri wrote @file{pop3.el}, a Post Office Protocol (RFC
-1460) interface for Emacs.
-
-@item
-Fred Pierresteguy and Paul Reilly made Emacs work with X Toolkit
-widgets.
-
-@item
-Christian Plaunt wrote @file{soundex.el}, an implementation of the
-Soundex algorithm for comparing English words by their pronunciation.
-
-@item
-David Ponce wrote:
-
-@itemize @minus
-@item
-@file{recentf.el}, a package that puts a menu of recently visited
-files in the Emacs menu bar,
-@item
-@file{ruler-mode.el}, a minor mode for displaying a ruler in the
-header line, and
-@item
-@file{tree-widget.el}, a package to display hierarchical data structures.
-@end itemize
-
-@item
-Francesco A.@: Potorti wrote @file{cmacexp.el}, providing a command which
-runs the C preprocessor on a region of a file and displays the results.
-He also expanded and redesigned the @code{etags} program.
-
-@item
-Michael D.@: Prange and Steven A.@: Wood wrote @file{fortran.el}, a mode for
-editing FORTRAN code.
-@c We're not distributing his tex-mode.el anymore; we're using Ed Reingold's.
-
-@item
-Mukesh Prasad contributed @file{vmsproc.el}, a facility for running
-asynchronous subprocesses on VMS.
-
-@item
-Marko Rahamaa wrote @file{latin-3.el}, code which sets up
-case-conversion and syntax tables for the ISO Latin-3 character set.
-
-@item
-Ashwin Ram wrote @file{refer.el}, commands to look up references in
-bibliography files by keyword.
-
-@item
-Eric S.@: Raymond wrote:
-
-@itemize @minus
-@item
-@file{vc.el}, an interface to the RCS and SCCS source code version
-control systems, with Paul Eggert,
-@item
-@file{gud.el}, a package for running source-level debuggers like GDB
-and SDB in Emacs,
-@item
-@file{asm-mode.el}, a mode for editing assembly language code,
-@item
-@file{AT386.el}, terminal support package for IBM's AT keyboards,
-@item
-@file{cookie1.el}, support for ``fortune-cookie'' programs like
-@file{yow.el} and @file{spook.el},
-@item
-@file{finder.el}, a package for finding Emacs Lisp packages by keyword
-and topic,
-@item
-@file{keyswap.el}, code to swap the @key{BS} and @key{DEL} keys,
-@item
-@file{loadhist.el}, functions for loading and unloading Emacs features,
-@item
-@file{lisp-mnt.el}, functions for working with the special headers used
-in Emacs Lisp library files, and
-@item
-code to set and make use of the @code{load-history} lisp variable, which
-records the source file from which each lisp function loaded into Emacs
-came.
-@end itemize
-
-@item
-Edward M.@: Reingold wrote the extensive calendar and diary support (try
-@kbd{M-x calendar}), with contributions from Stewart Clamen, Nachum
-Dershowitz, Paul Eggert, Steve Fisk, Michael Kifer, and Lara Rios. Andy
-Oram contributed to its documentation. Reingold has also contributed to
-@file{tex-mode.el}, a mode for editing @TeX{} files, as have William
-F.@: Schelter, Dick King, Stephen Gildea, Michael Prange, and Jacob Gore.
-
-@item
-David Reitter wrote @file{mailclient.el} which can send mail via the
-system's designated mail client.
-
-@item
-Alex Rezinsky contributed @file{which-func.el}, a mode that shows the
-name of the current function in the mode line.
-
-@item
-Rob Riepel contributed @file{tpu-edt.el} and its associated files,
-providing an emulation of the VMS TPU text editor emulating the VMS EDT
-editor, and @file{vt-control.el}, providing some control functions for
-the DEC VT line of terminals.
-
-@item
-Nick Roberts wrote @file{gdb-ui.el}, the graphical user interface to
-GDB.
-
-@item
-Roland B.@: Roberts contributed much of the VMS support distributed with
-Emacs 19, along with Joseph M.@: Kelsey, and @file{vms-pmail.el}, support
-for using Emacs within VMS MAIL.
-
-@item
-John Robinson wrote @file{bg-mouse.el}, support for the mouse on the BBN
-Bitgraph terminal.
-
-@item
-Danny Roozendaal implemented @file{handwrite.el}, which converts text
-into ``handwriting.''
-
-@item
-William Rosenblatt wrote @file{float.el}, implementing a floating-point
-numeric type using Lisp cons cells and integers.
-
-@item
-Guillermo J.@: Rozas wrote @file{scheme.el}, a mode for editing Scheme and
-DSSSL code, and @file{fakemail.c}, an interface to the System V mailer.
-
-@item
-Ivar Rummelhoff provided @file{winner.el}, which records
-recent window configurations so you can move back to them.
-
-@item
-Jason Rumney has ported the Emacs 21 display engine to MS-Windows, and
-contributed extensively to the MS-Windows port of Emacs.
-
-@item
-Wolfgang Rupprecht contributed Emacs 19's floating-point support
-(including @file{float-sup.el} and @file{floatfns.c}), and
-@file{sup-mouse.el}, support for the Supdup mouse on lisp machines.
-
-@item
-Kevin Ryde wrote @file{info-xref.el}, a library for checking
-references in Info files.
-
-@item
-James B.@: Salem and Brewster Kahle wrote @file{completion.el}, providing
-dynamic word completion.
-
-@item
-Masahiko Sato wrote @file{vip.el}, an emulation of the VI editor.
-
-@item
-Holger Schauer wrote @file{fortune.el}, a package for using fortune in
-message signatures.
-
-@item
-William Schelter wrote @file{telnet.el}, support for @code{telnet}
-sessions within Emacs.
-
-@item
-Ralph Schleicher contributed @file{battery.el}, a package for displaying
-laptop computer battery status, and @file{info-look.el}, a package for
-looking up Info documentation for symbols in the buffer.
-
-@item
-Michael Schmidt and Tom Perrine wrote @file{modula2.el}, a mode for
-editing Modula-2 code, based on work by Mick Jordan and Peter Robinson.
-
-@item
-Ronald S.@: Schnell wrote @file{dunnet.el}, a text adventure game.
-
-@item
-Philippe Schnoebelen wrote @file{gomoku.el}, a Go Moku game played
-against Emacs, and @file{mpuz.el}, a multiplication puzzle.
-
-@item
-Jan Schormann wrote @file{solitaire.el}, an Emacs Lisp implementation of
-the Solitaire game.
-
-@item
-Alex Schroeder wrote @file{ansi-color.el}, a package for translating
-ANSI color escape sequences to Emacs faces, and @file{sql.el}, a package
-for interactively running an SQL interpreter in an Emacs buffer.
-
-@item
-Randal Schwartz wrote @file{pp.el}, a pretty-printer for lisp objects.
-
-@item
-Oliver Seidel wrote @file{todo-mode.el}, a package for maintaining
-@file{TODO} list files.
-
-@item
-Manuel Serrano contributed the Flyspell package that does spell checking
-as you type.
-
-@item
-Hovav Shacham wrote @file{windmove.el}, a set of commands for selecting
-windows based on their geometrical position on the frame.
-
-@item
-Stanislav Shalunov wrote @file{uce.el}, for responding to unsolicited
-commercial email.
-
-@item
-Richard Sharman contributed @file{hilit-chg.el}, which uses colors
-to show recent editing changes.
-
-@item
-Olin Shivers wrote:
-
-@itemize @minus
-@item
-@file{comint.el}, a library for modes running interactive command-line-
-oriented subprocesses,
-@item
-@file{cmuscheme.el}, for running inferior Scheme processes,
-@item
-@file{inf-lisp.el}, for running inferior Lisp process, and
-@item
-@file{shell.el}, for running inferior shells.
-@end itemize
-
-@item
-Espen Skoglund wrote @file{pascal.el}, a mode for editing Pascal code.
-
-@item
-Rick Sladkey wrote @file{backquote.el}, a lisp macro for creating
-mostly-constant data.
-
-@item
-Lynn Slater wrote @file{help-macro.el}, a macro for writing interactive
-help for key bindings.
-
-@item
-Chris Smith wrote @file{icon.el}, a mode for editing Icon code.
-
-@item
-David Smith wrote @file{ielm.el}, a mode for interacting with the Emacs
-Lisp interpreter as a subprocess.
-
-@item
-Paul D.@: Smith wrote @file{snmp-mode.el}.
-
-@item
-William Sommerfeld wrote @file{scribe.el}, a mode for editing Scribe
-files, and @file{server.el}, a package allowing programs to send files
-to an extant Emacs job to be edited.
-
-@item
-Andre Spiegel made many contributions to the Emacs Version Control
-package, and in particular made it support multiple back ends.
-
-@item
-Michael Staats wrote @file{pc-select.el}, which rebinds keys for
-selecting regions to follow many other systems.
-
-@item
-Richard Stallman invented Emacs, and then wrote:
-
-@itemize @minus
-@item
-@file{easymenu.el}, a facility for defining Emacs menus,
-@item
-@file{menu-bar.el}, the Emacs menu bar support code,
-@item
-@file{paren.el}, a package to make matching parentheses stand out in
-color, and
-@item
-most of the rest of Emacs code.
-@end itemize
-
-@item
-Sam Steingold wrote @file{gulp.el}, a facility for asking package
-maintainers for updated versions of their packages via e-mail, and
-@file{midnight.el}, a package for running a command every midnight.
-
-@item
-Ake Stenhoff and Lars Lindberg wrote @file{imenu.el}, a framework for
-browsing indices made from buffer contents.
-
-@item
-Peter Stephenson contributed @file{vcursor.el}, which implements a
-``virtual cursor'' that you can move with the keyboard and use for
-copying text.
-
-@item
-Ken Stevens wrote the initial version of @file{ispell.el} and maintains
-that package since Ispell 3.1 release.
-
-@item
-Jonathan Stigelman wrote @file{hilit19.el}, a package providing
-automatic highlighting in source code buffers, mail readers, and other
-contexts.
-
-@item
-Kim F.@: Storm made many improvements to the Emacs display engine,
-process support, and networking support. He also wrote:
-
-@itemize @minus
-@item
-@file{bindat.el}, a package for encoding and decoding binary data.
-@item
-@file{cua.el}, which allows Emacs to emulate the standard CUA key
-bindings.
-@item
-@file{ido.el}, a package for selecting buffers and files quickly.
-@item
-@file{kmacro.el}, the keyboard macro facility.
-@end itemize
-
-@item
-Martin Stjernholm co-authored CC Mode, a major editing mode for C,
-C@t{++}, Objective-C, Java, Pike, CORBA IDL, and AWK code.
-
-@item
-Steve Strassman did not write @file{spook.el}, and even if he did, he
-really didn't mean for you to use it in an anarchistic way.
-
-@item
-Olaf Sylvester wrote @file{bs.el}, a package for manipulating Emacs
-buffers.
-
-@item
-Tibor @v{S}imko and Milan Zamazal wrote @file{slovak.el}, support for
-editing text in Slovak language.
-
-@item
-Naoto Takahashi wrote @file{utf-8.el}, support for encoding and
-decoding UTF-8 data.
-
-@item
-Luc Teirlinck wrote @file{help-at-pt.el}, providing local help through
-the keyboard.
-
-@item
-Jean-Philippe Theberge wrote @file{thumbs.el}, a package for viewing
-image files as ``thumbnails.''
-
-@item
-Jens T.@: Berger Thielemann wrote @file{word-help.el}, which is
-part of the basis for @file{info-look.el}.
-
-@item
-Spencer Thomas wrote the original @file{dabbrev.el}, providing a command
-which completes the partial word before point, based on other nearby
-words for which it is a prefix. He also wrote the original dumping
-support.
-
-@item
-Jim Thompson wrote @file{ps-print.el}, which converts
-Emacs text to PostScript.
-
-@item
-Tom Tromey and Chris Lindblad wrote @file{tcl.el}, a major mode for
-editing Tcl/Tk source files and running a Tcl interpreter as an Emacs
-subprocess.
-
-@item
-Eli Tziperman wrote @file{rmail-spam-filter.el}, a spam filter for RMAIL.
-@item
-Daiki Ueno wrote @file{starttls.el}, support for Transport Layer
-Security protocol, and the PGG package adding GnuPG and PGP support.
-
-@item
-Masanobu Umeda wrote:
-
-@itemize @minus
-@item
-GNUS, a feature-full reader for Usenet news,
-@item
-@file{prolog.el}, a mode for editing Prolog code,
-@item
-@file{rmailsort.el}, a package for sorting messages in RMAIL folders,
-@item
-@file{metamail.el}, an interface to the Metamail program,
-@item
-@file{gnus-kill.el}, the Kill File mode for Gnus,
-@item
-@file{gnus-mh.el}, an mh-e interface for Gnus,
-@item
-@file{gnus-msg.el}, a mail and post interface for Gnus,
-@item
-@file{tcp.el}, emulation of the @code{open-network-stream} function for
-some Emacs configurations which lack it, and
-@item
-@file{timezone.el}, providing functions for dealing with time zones.
-@end itemize
-
-@item
-Rajesh Vaidheeswarran wrote @file{whitespace.el}, a package that
-detects and cleans up excess whitespace in a file.
-
-@item
-Neil W.@: Van Dyke wrote @file{webjump.el}, a ``hot links'' package.
-
-@item
-Didier Verna contributed @file{rect.el}, a package of functions for
-operations on rectangle regions of text.
-
-@item
-Ulrik Vieth implemented @file{meta-mode.el}, for editing MetaFont code.
-
-@item
-Geoffrey Voelker wrote the Windows NT support. He also wrote
-@file{dos-w32.el}, functions shared by the MS-DOS and MS-Windows ports
-of Emacs, and @file{w32-fns.el}, MS-Windows specific support functions.
-
-@item
-Johan Vromans wrote @file{forms.el} and its associated files, a
-mode for filling in forms.
-
-@item
-Colin Walters wrote @file{ibuffer.el}, a Dired-like major mode for
-operating on buffers.
-
-@item
-Barry Warsaw wrote:
-
-@itemize @minus
-@item
-@file{assoc.el}, a set of utility functions for working with association
-lists,
-@item
-@file{cc-mode.el}, a major mode for editing C, C@t{++}, and Java code,
-based on earlier work by Dave Detlefs, Stewart Clamen, and Richard
-Stallman,
-@item
-@file{elp.el}, a new profiler for Emacs Lisp programs.
-@item
-@file{man.el}, a mode for reading UNIX manual pages,
-@item
-@file{regi.el}, providing an AWK-like functionality for use in lisp
-programs,
-@item
-@file{reporter.el}, providing customizable bug reporting for lisp
-packages, and
-@item
-@file{supercite.el}, a minor mode for quoting sections of mail messages
-and news articles.
-@end itemize
-
-@item
-Morten Welinder introduced face support into the MS-DOS port of Emacs,
-and also wrote:
-
-@itemize @minus
-@item
-@file{desktop.el}, facilities for saving some of Emacs's state between
-sessions,
-@item
-@file{timer.el}, the Emacs facility to run commands at a given time or
-frequency, or when Emacs is idle, and its C-level support code,
-@item
-@file{pc-win.el}, the MS-DOS ``window-system'' support,
-@item
-@file{internal.el}, an ``internal terminal'' emulator for the MS-DOS
-port of Emacs,
-@item
-@file{arc-mode.el}, the mode for editing compressed archives,
-@item
-@file{s-region.el}, commands for setting the region using the shift key
-and motion commands, and
-@item
-@file{dos-fns.el}, functions for use under MS-DOS.
-@end itemize
-
-He also helped port Emacs to MS-DOS.
-
-@item
-Joseph Brian Wells wrote:
-
-@itemize @minus
-@item
-@file{apropos.el}, a command to find commands, functions, and variables
-whose names contain matches for a regular expression,
-@item
-@file{resume.el}, support for processing command-line arguments after
-resuming a suspended Emacs job, and
-@item
-@file{mail-extr.el}, a package for extracting names and addresses from
-mail headers, with contributions from Jamie Zawinski.
-@end itemize
-
-@item
-Rodney Whitby and Reto Zimmermann wrote @file{vhdl-mode.el}, a major
-mode for editing VHDL source code.
-
-@item
-John Wiegley wrote @file{align.el}, a set of commands for aligning text
-according to regular-expression based rules; @file{timeclock.el}, a
-package for keeping track of time spent on projects;
-@file{pcomplete.el}, a programmable completion facility; and
-@code{eshell}, a command shell implemented entirely in Emacs Lisp.
-
-@item
-Ed Wilkinson wrote @file{b2m.c}, a program to convert mail files from
-RMAIL format to Unix @code{mbox} format.
-
-@item
-Mike Williams wrote @file{mouse-sel.el}, providing enhanced mouse
-selection, and @file{thingatpt.el}, a library of functions for finding
-the ``thing'' (word, line, s-expression) containing point.
-
-@item
-Bill Wohler wrote the Emacs interface to the MH mail system.
-
-@item
-Dale R.@: Worley wrote @file{emerge.el}, a package for interactively
-merging two versions of a file.
-
-@item
-Francis J.@: Wright wrote @code{WoMan}, a package for browsing
-manual pages without the @code{man} command.
-
-@item
-Tom Wurgler wrote @file{emacs-lock.el}, which makes it harder
-to exit with valuable buffers unsaved.
-
-@item
-Masatake Yamato wrote @file{ld-script.el}, an editing mode for GNU
-linker scripts, and contributed subword handling in CC mode.
-
-@item
-Jonathan Yavner wrote @file{testcover.el}, a package for keeping track
-of the testing status of Emacs Lisp code, and the SES spreadsheet
-package.
-
-@item
-Ryan Yeske wrote @file{rcirc.el} a simple Internet Relay Chat client.
-@item
-Ilya Zakharevich and Bob Olson contributed @file{cperl-mode.el}, a major
-mode for editing Perl code. Ilya Zakharevich also wrote @file{tmm.el},
-a mode for accessing the Emacs menu bar on a text-mode terminal.
-
-@item
-Milan Zamazal wrote @file{czech.el}, support for editing Czech text,
-@file{glasses.el}, a package for easier reading of source code which
-uses illegible identifier names such as @code{cantReadThisVariable}, and
-@file{tildify.el}, commands for adding hard spaces to text, @TeX{}, and
-SGML/HTML files.
-
-@item
-Victor Zandy contributed @file{zone.el}, a package for people who like
-to zone out in front of Emacs.
-
-@item
-Eli Zaretskii made many standard Emacs features work on MS-DOS. He also
-wrote @file{tty-colors.el}, which implements transparent mapping of X
-colors to tty colors, and (together with Kenichi Handa)
-@file{codepage.el}, a package for editing text encoded in DOS/Windows
-code pages.
-
-@item
-Jamie Zawinski wrote:
-
-@itemize @minus
-@item
-Emacs 19's optimizing byte compiler, with Hallvard Furuseth,
-@item
-much of the support for faces and X selections,
-@item
-@file{mailabbrev.el}, a package providing automatic expansion of mail
-aliases, and
-@item
-@file{tar-mode.el}, providing simple viewing and editing commands for
-tar files.
-@end itemize
-
-@item
-Andrew Zhilin created the Emacs icons used beginning with Emacs 22.
-
-@item
-Shenghuo Zhu wrote:
-
-@itemize @minus
-@item
-@file{binhex.el}, a package for reading and writing binhex files,
-@item
-@file{mm-partial.el}, message/partial support for MIME messages,
-@item
-@file{rfc1843.el}, an HZ decoding package,
-@item
-@file{uudecode.el}, an Emacs Lisp decoder for uuencoded data,
-@item
-@file{webmail.el}, an interface to Web mail.
-@end itemize
-
-@item
-Ian T.@: Zimmerman wrote @file{gametree.el}.
-
-@item
-Neal Ziring and Felix S.@: T.@: Wu wrote @file{vi.el}, an emulation of the
-VI text editor.
-
-@item
-Detlev Zundel wrote @file{re-builder.el}, a package for building regexps
-with visual feedback.
-
-@end itemize
-
-Others too numerous to mention have reported and fixed bugs, and added
-features to many parts of Emacs. (Many are mentioned in the
-@file{ChangeLog} files which are summarized in the file @file{AUTHORS}
-in the distribution.) We thank them for their generosity as well.
-
-This list intended to mention every contributor of a major package or
-feature we currently distribute; if you know of someone we have omitted,
-please report that as a manual bug.
-
-@ignore
- arch-tag: bb1d0fa4-0240-4992-b5d4-8602d1e3d4ba
-@end ignore
+++ /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
-@c This is part of the Emacs manual.
-@c Copyright (C) 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-
-@node Antinews, Mac OS, X Resources, Top
-@appendix Emacs 21 Antinews
-
- For those users who live backwards in time, here is information about
-downgrading to Emacs version 21.4. We hope you will enjoy the greater
-simplicity that results from the absence of many Emacs @value{EMACSVER}
-features.
-
-@itemize @bullet
-
-@item
-The buffer position and line number are now displayed at the end of
-the mode line, where they can be more easily seen.
-
-@item
-The mode line of the selected window is no longer displayed with a
-special face. All mode lines are created equal. Meanwhile, you can
-use the variable @code{mode-line-inverse-video} to control whether
-mode lines are highlighted at all---@code{nil} means don't highlight
-them.
-
-@item
-Clicking on a link with the left mouse button (@kbd{mouse-1}) will
-always set point at the position clicked, instead of following the
-link. If you want to follow the link, use the middle mouse button
-(@kbd{mouse-2}).
-
-@item
-Emacs is tired of X droppings. If you drop a file or a piece of text
-onto an Emacs window, nothing will happen.
-
-@item
-On an xterm, even if you enable Xterm Mouse mode, Emacs provides a
-more convincing simulation of a text terminal by not responding to
-mouse clicks on the mode line, header line, or display margin.
-
-@item
-For simplicity, windows always have fringes. We wouldn't want to
-in-fringe anyone's windows. Likewise, horizontal scrolling always
-works in the same automatic way.
-
-@item
-The horizontal-bar cursor shape has been removed.
-
-@item
-If command line arguments are given, Emacs will not display a splash
-screen, so that you can immediately get on with your editing. The
-command-line option @samp{--no-splash} is therefore obsolete, and has
-been removed.
-
-@item
-These command line options have also been removed: @samp{--color},
-@samp{--fullwidth}, @samp{--fullheight}, @samp{--fullscreen},
-@samp{--no-blinking-cursor}, @samp{--no-desktop}, and @samp{-Q}.
-
-@item
-The @samp{--geometry} option applies only to the initial frame, and
-the @samp{-f} option will not read arguments for interactive
-functions.
-
-@item
-We have standardized on one location for the user init file: the file
-named @file{.emacs} in your home directory. Emacs will not look for
-the init file in @file{~/.emacs.d/init.el}. Similarly, don't try
-putting @file{.emacs_SHELL} as @file{init_SHELL.sh} in
-@file{~/.emacs.d}; Emacs won't find it.
-
-@item
-Emacs will not read @file{~/.abbrev_defs} automatically. If you want
-to load abbrev definitions from a file, you must always do so
-explicitly.
-
-@item
-When you are logged in as root, all files now give you writable
-buffers, reflecting the fact that you can write any files.
-
-@item
-The maximum size of buffers and integer variables has been halved. On
-32-bit machines, the maximum buffer size is now 128 megabytes.
-
-@item
-An unquoted @samp{$} in a file name is now an error, if the following
-name is not recognized as an environment variable. Thus,
-the file name @file{foo$bar} would probably be an error. Meanwhile,
-the @code{setenv} command does not expand @samp{$} at all.
-
-@item
-If a single command accumulates too much undo information, Emacs never
-discards it. If Emacs runs out of memory as a result, it will handle
-this by crashing.
-
-@item
-Many commands have been removed from the menus or rearranged.
-
-@item
-The @kbd{C-h} (help) subcommands have been rearranged---especially
-those that display specific files. Type @kbd{C-h C-h} to see a list
-of these commands; that will show you what is different.
-
-@item
-The @kbd{C-h v} and @kbd{C-h f} commands no longer show a hyperlink to
-the C source code, even if it is available. If you want to find the
-source code, grep for it.
-
-@item
-The apropos commands will not accept a list of words to match, in
-order to encourage you to be more specific. Also, the user option
-@code{apropos-sort-by-scores} has been removed.
-
-@item
-The minibuffer prompt is now displayed using the default face.
-The colon is enough to show you what part is the prompt.
-
-@item
-Minibuffer completion commands always complete the entire minibuffer
-contents, just as if you had typed them at the end of the minibuffer,
-no matter where point is actually located.
-
-@item
-The command @code{backward-kill-sexp} is now bound to @kbd{C-M-delete}
-and @kbd{C-M-backspace}. Be careful when using these key sequences!
-It may shut down your X server, or reboot your operating system.
-
-@item
-Commands to set the mark at a place away from point, including
-@kbd{M-@@}, @kbd{M-h}, etc., don't do anything special when you repeat
-them. In most cases, typing these commands multiple times is
-equivalent to typing them once. @kbd{M-h} ignores numeric arguments.
-
-@item
-The user option @code{set-mark-command-repeat-pop} has been removed.
-
-@item
-@kbd{C-@key{SPC} C-@key{SPC}} has no special meaning--it just sets the
-mark twice. Neither does @kbd{C-u C-x C-x}, which simply exchanges
-point and mark like @kbd{C-x C-x}.
-
-@item
-The function @code{sentence-end} has been eliminated in favor of a
-more straightforward approach: directly setting the variable
-@code{sentence-end}. For example, to end each sentence with a single
-space, use
-
-@lisp
-(setq sentence-end "[.?!][]\"')@}]*\\($\\|[ \t]\\)[ \t\n]*")
-@end lisp
-
-@item
-The variable @code{fill-nobreak-predicate} is no longer customizable,
-and it can only hold a single function.
-
-@item
-Nobreak spaces and hyphens are displayed just like normal characters,
-and the user option @code{nobreak-char-display} has been removed.
-
-@item
-@kbd{C-w} in an incremental search always grabs an entire word
-into the search string. More precisely, it grabs text through
-the next end of a word.
-
-@item
-Yanking now preserves all text properties that were in the killed
-text. The variable @code{yank-excluded-properties} has been removed.
-
-@item
-Occur mode, Info mode, and Comint-derived modes now control
-fontification in their own way, and @kbd{M-x font-lock-mode} has
-nothing to do with it. To control fontification in Info mode, use the
-variable @code{Info-fontify}.
-
-@item
-@samp{M-x shell} is now completely standard in regard to scrolling
-behavior. It no longer has the option of scrolling the input line to
-the bottom of the window the way a text terminal running a shell does.
-
-@item
-The Grep package has been merged with Compilation mode. Many
-grep-specific commands and user options have thus been eliminated.
-Also, @kbd{M-x grep} never tries the GNU grep @samp{-H} option,
-and instead silently appends @file{/dev/null} to the command line.
-
-@item
-In Dired's @kbd{!} command, @samp{*} and @samp{?} now
-cause substitution of the file names wherever they appear---not
-only when they are surrounded by whitespace.
-
-@item
-When a file is managed with version control, the command @kbd{C-x C-q}
-(whose general meaning is to make a buffer read-only or writable) now
-does so by checking the file in or out. Checking the file out makes
-the buffer writable; checking it in makes the buffer read-only.
-
-You can still use @kbd{C-x v v} to do these operations if you wish;
-its meaning is unchanged. If you want to control the buffer's
-read-only flag without performing any version control operation,
-use @kbd{M-x toggle-read-only}.
-
-@item
-SGML mode does not handle XML syntax, and does not have indentation
-support.
-
-@item
-Many Info mode commands have been removed. Incremental search in Info
-searches only the current node.
-
-@item
-Many @code{etags} features for customizing parsing using regexps
-have been removed.
-
-@item
-The Emacs server now runs a small C program called @file{emacsserver},
-rather than trying to handle everything in Emacs Lisp. Now there can
-only be one Emacs server running at a time. The @code{server-mode}
-command and @code{server-name} user option have been eliminated.
-
-@item
-The @file{emacsclient} program no longer accepts the @samp{--eval},
-@samp{--display} and @samp{--server-file} command line options, and
-can only establish local connections using Unix domain sockets.
-
-@item
-The command @code{quail-show-key}, for showing how to input a
-character, has been removed.
-
-@item
-The default value of @code{keyboard-coding-system} is always
-@code{nil}, regardless of your locale settings. If you want some
-other value, set it yourself.
-
-@item
-Unicode support and unification between Latin-@var{n} character sets
-have been removed. Cutting and pasting X selections does not support
-``extended segments'', so there are certain coding systems it cannot
-handle.
-
-@item
-The input methods for Emacs are included in a separate distribution
-called ``Leim.'' To use this, you must extract the Leim tar file on
-top of the Emacs distribution, into the same directory, before you
-build Emacs.
-
-@item
-The following input methods have been eliminated: 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.
-
-@item
-The following language environments have been eliminated: Belarusian,
-Bulgarian, Chinese-EUC-TW, Croatian, French, Georgian, Italian,
-Latin-6, Latin-7, Latvian, Lithuanian, Malayalam, Russian, Russian,
-Slovenian, Swedish, Tajik, Tamil, UTF-8, Ukrainian, Ukrainian, Welsh,
-and Windows-1255.
-
-@item
-The @code{code-pages} library, which contained various 8-bit coding
-systems, has been removed.
-
-@item
-The Kmacro package has been replaced with a simple and elegant
-keyboard macro system. Use @kbd{C-x (} to start a new keyboard macro,
-@kbd{C-x )} to end the macro, and @kbd{C-x e} to execute the last
-macro. Use @kbd{M-x name-last-kbd-macro} to name the most recently
-defined macro.
-
-@item
-Emacs no longer displays your breakpoints in the source buffer, so you
-have to remember where you left them. It can be difficult to inspect
-the state of your debugged program from the command line, so Emacs
-tries to demonstrate this in the GUD buffer.
-
-@item
-The Calc, CUA, Ibuffer, Ido, Password, Printing, Reveal,
-Ruler-mode, SES, Table, Tramp, and URL packages have been removed.
-The Benchmark, Cfengine, Conf, Dns, Flymake, Python, Thumbs, and
-Wdired modes have also been removed.
-
-@item
-The Emacs Lisp Reference Manual and the Introduction to Programming in
-Emacs Lisp are now distributed separately, not in the Emacs
-distribution.
-
-@item
-On MS Windows, there is no longer any support for tooltips, images,
-sound, different mouse pointer shapes, or pointing devices with more
-than 3 buttons. If you want these features, consider switching to
-another operating system. But even if you don't want these features,
-you should still switch---for freedom's sake.
-
-@item
-Emacs will not use Unicode for clipboard operations on MS Windows.
-
-@item
-To keep up with decreasing computer memory capacity and disk space, many
-other functions and files have been eliminated in Emacs 21.4.
-@end itemize
-
-@ignore
- arch-tag: 32932bd9-46f5-41b2-8a0e-fb0cc4caeb29
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@c
-@c This file is included either in emacs-xtra.texi (when producing the
-@c printed version) or in the main Emacs manual (for the on-line version).
-@node Autorevert
-@section Auto Reverting non-file Buffers
-
-Normally Global Auto Revert Mode only reverts file buffers. There are
-two ways to auto-revert certain non-file buffers: enabling Auto Revert
-Mode in those buffers (using @kbd{M-x auto-revert-mode}) and setting
-@code{global-auto-revert-non-file-buffers} to @code{t}. The latter
-enables Auto Reverting for all types of buffers for which it is
-implemented, that is, for the types of buffers listed in the menu
-below.
-
-Like file buffers, non-file buffers should normally not revert while
-you are working on them, or while they contain information that might
-get lost after reverting. Therefore, they do not revert if they are
-``modified''. This can get tricky, because deciding when a non-file
-buffer should be marked modified is usually more difficult than for
-file buffers.
-
-Another tricky detail is that, for efficiency reasons, Auto Revert
-often does not try to detect all possible changes in the buffer, only
-changes that are ``major'' or easy to detect. Hence, enabling
-auto-reverting for a non-file buffer does not always guarantee that
-all information in the buffer is up to date and does not necessarily
-make manual reverts useless.
-
-At the other extreme, certain buffers automatically auto-revert every
-@code{auto-revert-interval} seconds. (This currently only applies to
-the Buffer Menu.) In this case, Auto Revert does not print any
-messages while reverting, even when @code{auto-revert-verbose} is
-non-@code{nil}.
-
-The details depend on the particular types of buffers and are
-explained in the corresponding sections.
-
-@menu
-* Auto Reverting the Buffer Menu::
-* Auto Reverting Dired::
-* Supporting additional buffers::
-@end menu
-
-@node Auto Reverting the Buffer Menu
-@subsection Auto Reverting the Buffer Menu
-
-If auto-reverting of non-file buffers is enabled, the Buffer Menu
-automatically reverts every @code{auto-revert-interval} seconds,
-whether there is a need for it or not. (It would probably take longer
-to check whether there is a need than to actually revert.)
-
-If the Buffer Menu inappropriately gets marked modified, just revert
-it manually using @kbd{g} and auto-reverting will resume. However, if
-you marked certain buffers to get deleted or to be displayed, you have
-to be careful, because reverting erases all marks. The fact that
-adding marks sets the buffer's modified flag prevents Auto Revert from
-automatically erasing the marks.
-
-@node Auto Reverting Dired
-@subsection Auto Reverting Dired buffers
-
-Auto-reverting Dired buffers currently works on GNU or Unix style
-operating systems. It may not work satisfactorily on some other
-systems.
-
-Dired buffers only auto-revert when the file list of the buffer's main
-directory changes. They do not auto-revert when information about a
-particular file changes or when inserted subdirectories change. To be
-sure that @emph{all} listed information is up to date, you have to
-manually revert using @kbd{g}, @emph{even} if auto-reverting is
-enabled in the Dired buffer. Sometimes, you might get the impression
-that modifying or saving files listed in the main directory actually
-does cause auto-reverting. This is because making changes to a file,
-or saving it, very often causes changes in the directory itself, for
-instance, through backup files or auto-save files. However, this is
-not guaranteed.
-
-If the Dired buffer is marked modified and there are no changes you
-want to protect, then most of the time you can make auto-reverting
-resume by manually reverting the buffer using @kbd{g}. There is one
-exception. If you flag or mark files, you can safely revert the
-buffer. This will not erase the flags or marks (unless the marked
-file has been deleted, of course). However, the buffer will stay
-modified, even after reverting, and auto-reverting will not resume.
-This is because, if you flag or mark files, you may be working on the
-buffer and you might not want the buffer to change without warning.
-If you want auto-reverting to resume in the presence of marks and
-flags, mark the buffer non-modified using @kbd{M-~}. However, adding,
-deleting or changing marks or flags will mark it modified again.
-
-Remote Dired buffers are not auto-reverted. Neither are Dired buffers
-for which you used shell wildcards or file arguments to list only some
-of the files. @samp{*Find*} and @samp{*Locate*} buffers do not
-auto-revert either.
-
-@node Supporting additional buffers
-@subsection Adding Support for Auto-Reverting additional Buffers.
-
-This section is intended for Elisp programmers who would like to add
-support for auto-reverting new types of buffers.
-
-To support auto-reverting the buffer must first of all have a
-@code{revert-buffer-function}. @xref{Definition of
-revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}.
-
-In addition, it @emph{must} have a @code{buffer-stale-function}.
-
-@defvar buffer-stale-function
-The value of this variable is a function to check whether a non-file
-buffer needs reverting. This should be a function with one optional
-argument @var{noconfirm}. The function should return non-@code{nil}
-if the buffer should be reverted. The buffer is current when this
-function is called.
-
-While this function is mainly intended for use in auto-reverting, it
-could be used for other purposes as well. For instance, if
-auto-reverting is not enabled, it could be used to warn the user that
-the buffer needs reverting. The idea behind the @var{noconfirm}
-argument is that it should be @code{t} if the buffer is going to be
-reverted without asking the user and @code{nil} if the function is
-just going to be used to warn the user that the buffer is out of date.
-In particular, for use in auto-reverting, @var{noconfirm} is @code{t}.
-If the function is only going to be used for auto-reverting, you can
-ignore the @var{noconfirm} argument.
-
-If you just want to automatically auto-revert every
-@code{auto-revert-interval} seconds, use:
-
-@example
-(set (make-local-variable 'buffer-stale-function)
- #'(lambda (&optional noconfirm) 'fast))
-@end example
-
-@noindent
-in the buffer's mode function.
-
-The special return value @samp{fast} tells the caller that the need
-for reverting was not checked, but that reverting the buffer is fast.
-It also tells Auto Revert not to print any revert messages, even if
-@code{auto-revert-verbose} is non-@code{nil}. This is important, as
-getting revert messages every @code{auto-revert-interval} seconds can
-be very annoying. The information provided by this return value could
-also be useful if the function is consulted for purposes other than
-auto-reverting.
-@end defvar
-
-Once the buffer has a @code{revert-buffer-function} and a
-@code{buffer-stale-function}, several problems usually remain.
-
-The buffer will only auto-revert if it is marked unmodified. Hence,
-you will have to make sure that various functions mark the buffer
-modified if and only if either the buffer contains information that
-might be lost by reverting or there is reason to believe that the user
-might be inconvenienced by auto-reverting, because he is actively
-working on the buffer. The user can always override this by manually
-adjusting the modified status of the buffer. To support this, calling
-the @code{revert-buffer-function} on a buffer that is marked
-unmodified should always keep the buffer marked unmodified.
-
-It is important to assure that point does not continuously jump around
-as a consequence of auto-reverting. Of course, moving point might be
-inevitable if the buffer radically changes.
-
-You should make sure that the @code{revert-buffer-function} does not
-print messages that unnecessarily duplicate Auto Revert's own messages
-if @code{auto-revert-verbose} is @code{t} and effectively override a
-@code{nil} value for @code{auto-revert-verbose}. Hence, adapting a
-mode for auto-reverting often involves getting rid of such messages.
-This is especially important for buffers that automatically
-auto-revert every @code{auto-revert-interval} seconds.
-
-Also, you may want to update the documentation string of
-@code{global-auto-revert-non-file-buffers}.
-
-@ifinfo
-Finally, you should add a node to this chapter's menu. This node
-@end ifinfo
-@ifnotinfo
-Finally, you should add a section to this chapter. This section
-@end ifnotinfo
-should at the very least make clear whether enabling auto-reverting
-for the buffer reliably assures that all information in the buffer is
-completely up to date (or will be after @code{auto-revert-interval}
-seconds).
-
-@ignore
- arch-tag: 2983e613-a272-45f6-9593-3010ad7f865e
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Basic, Minibuffer, Exiting, Top
-@chapter Basic Editing Commands
-
-@kindex C-h t
-@findex help-with-tutorial
- Here we explain the basics of how to enter text, make corrections,
-and save the text in a file. If this material is new to you, we
-suggest you first run the Emacs learn-by-doing tutorial, by typing
-@kbd{Control-h t} inside Emacs. (@code{help-with-tutorial}).
-
- To clear and redisplay the screen, type @kbd{C-l} (@code{recenter}).
-
-@menu
-
-* Inserting Text:: Inserting text by simply typing it.
-* Moving Point:: Moving the cursor to the place where you want to
- change something.
-* Erasing:: Deleting and killing text.
-* Basic Undo:: Undoing recent changes in the text.
-* Files: Basic Files. Visiting, creating, and saving files.
-* Help: Basic Help. Asking what a character does.
-* Blank Lines:: Making and deleting blank lines.
-* Continuation Lines:: How Emacs displays lines too wide for the screen.
-* Position Info:: What page, line, row, or column is point on?
-* Arguments:: Numeric arguments for repeating a command N times.
-* Repeating:: Repeating the previous command quickly.
-@end menu
-
-@node Inserting Text
-@section Inserting Text
-
-@cindex insertion
-@cindex graphic characters
- Typing printing characters inserts them into the text you are
-editing. It inserts them into the buffer at the cursor; more
-precisely, it inserts them at @dfn{point}, but the cursor normally
-shows where point is. @xref{Point}.
-
- Insertion moves the cursor forward, and the following text moves
-forward with the cursor. If the text in the buffer is @samp{FOOBAR},
-with the cursor before the @samp{B}, and you type @kbd{XX}, you get
-@samp{FOOXXBAR}, with the cursor still before the @samp{B}.
-
- To @dfn{delete} text you have just inserted, use the large key
-labeled @key{DEL}, @key{BACKSPACE} or @key{DELETE} which is a short
-distance above the @key{RET} or @key{ENTER} key. Regardless of the
-label on that key, Emacs thinks of it as @key{DEL}, and that's what we
-call it in this manual. @key{DEL} is the key you normally use outside
-Emacs to erase the last character that you typed.
-
- The @key{DEL} key deletes the character @emph{before} the cursor.
-As a consequence, the cursor and all the characters after it move
-backwards. If you type a printing character and then type @key{DEL},
-they cancel out.
-
- On most computers, Emacs sets up @key{DEL} automatically. In some
-cases, especially with text-only terminals, Emacs may guess wrong. If
-the key that ought to erase the last character doesn't do it in Emacs,
-see @ref{DEL Does Not Delete}.
-
- Most PC keyboards have both a @key{BACKSPACE} key a little ways
-above @key{RET} or @key{ENTER}, and a @key{DELETE} key elsewhere. On
-these keyboards, Emacs tries to set up @key{BACKSPACE} as @key{DEL}.
-The @key{DELETE} key deletes ``forwards'' like @kbd{C-d} (see below),
-which means it deletes the character underneath the cursor (after
-point).
-
-@kindex RET
-@cindex newline
- To end a line and start typing a new one, type @key{RET}. (This
-key may be labeled @key{RETURN} or @key{ENTER}, but in Emacs we call
-it @key{RET}.) This inserts a newline character in the buffer. If
-point is at the end of the line, this creates a new blank line after
-it. If point is in the middle of a line, the effect is to split that
-line. Typing @key{DEL} when the cursor is at the beginning of a line
-deletes the preceding newline character, thus joining the line with
-the one before it.
-
- Emacs can split lines automatically when they become too long, if
-you turn on a special minor mode called @dfn{Auto Fill} mode.
-@xref{Filling}, for Auto Fill mode and other methods of @dfn{filling}
-text.
-
- If you prefer printing characters to replace (overwrite) existing
-text, rather than shove it to the right, you should enable Overwrite
-mode, a minor mode. @xref{Minor Modes}.
-
-@cindex quoting
-@kindex C-q
-@findex quoted-insert
- Only printing characters and @key{SPC} insert themselves in Emacs.
-Other characters act as editing commands and do not insert themselves.
-These include control characters, and characters with codes above 200
-octal. If you need to insert one of these characters in the buffer,
-you must @dfn{quote} it by typing the character @kbd{Control-q}
-(@code{quoted-insert}) first. (This character's name is normally
-written @kbd{C-q} for short.) There are two ways to use
-@kbd{C-q}:
-
-@itemize @bullet
-@item
-@kbd{C-q} followed by any non-graphic character (even @kbd{C-g})
-inserts that character.
-
-@item
-@kbd{C-q} followed by a sequence of octal digits inserts the character
-with the specified octal character code. You can use any number of
-octal digits; any non-digit terminates the sequence. If the
-terminating character is @key{RET}, it serves only to terminate the
-sequence. Any other non-digit terminates the sequence and then acts
-as normal input---thus, @kbd{C-q 1 0 1 B} inserts @samp{AB}.
-
-The use of octal sequences is disabled in ordinary non-binary
-Overwrite mode, to give you a convenient way to insert a digit instead
-of overwriting with it.
-@end itemize
-
-@cindex 8-bit character codes
-@noindent
-When multibyte characters are enabled, if you specify a code in the
-range 0200 through 0377 octal, @kbd{C-q} assumes that you intend to
-use some ISO 8859-@var{n} character set, and converts the specified
-code to the corresponding Emacs character code. @xref{Enabling
-Multibyte}. You select @emph{which} of the ISO 8859 character sets to
-use through your choice of language environment (@pxref{Language
-Environments}).
-
-@vindex read-quoted-char-radix
-To use decimal or hexadecimal instead of octal, set the variable
-@code{read-quoted-char-radix} to 10 or 16. If the radix is greater than
-10, some letters starting with @kbd{a} serve as part of a character
-code, just like digits.
-
-A numeric argument tells @kbd{C-q} how many copies of the quoted
-character to insert (@pxref{Arguments}).
-
-@findex newline
-@findex self-insert
- Customization information: @key{DEL} in most modes runs the command
-@code{delete-backward-char}; @key{RET} runs the command
-@code{newline}, and self-inserting printing characters run the command
-@code{self-insert}, which inserts whatever character you typed. Some
-major modes rebind @key{DEL} to other commands.
-
-@node Moving Point
-@section Changing the Location of Point
-
-@cindex arrow keys
-@cindex moving point
-@cindex movement
-@cindex cursor motion
-@cindex moving the cursor
- To do more than insert characters, you have to know how to move point
-(@pxref{Point}). The simplest way to do this is with arrow keys, or by
-clicking the left mouse button where you want to move to.
-
- There are also control and meta characters for cursor motion. Some
-are equivalent to the arrow keys (it is faster to use these control
-keys than move your hand over to the arrow keys). Others do more
-sophisticated things.
-
-@kindex C-a
-@kindex C-e
-@kindex C-f
-@kindex C-b
-@kindex C-n
-@kindex C-p
-@kindex M->
-@kindex M-<
-@kindex M-r
-@kindex LEFT
-@kindex RIGHT
-@kindex UP
-@kindex DOWN
-@findex move-beginning-of-line
-@findex move-end-of-line
-@findex forward-char
-@findex backward-char
-@findex next-line
-@findex previous-line
-@findex beginning-of-buffer
-@findex end-of-buffer
-@findex goto-char
-@findex goto-line
-@findex move-to-window-line
-@table @kbd
-@item C-a
-Move to the beginning of the line (@code{move-beginning-of-line}).
-@item C-e
-Move to the end of the line (@code{move-end-of-line}).
-@item C-f
-Move forward one character (@code{forward-char}). The right-arrow key
-does the same thing.
-@item C-b
-Move backward one character (@code{backward-char}). The left-arrow
-key has the same effect.
-@item M-f
-Move forward one word (@code{forward-word}).
-@item M-b
-Move backward one word (@code{backward-word}).
-@item C-n
-Move down one line vertically (@code{next-line}). This command
-attempts to keep the horizontal position unchanged, so if you start in
-the middle of one line, you move to the middle of the next. The
-down-arrow key does the same thing.
-@item C-p
-Move up one line, vertically (@code{previous-line}). The up-arrow key
-has the same effect. This command preserves position within the line,
-like @kbd{C-n}.
-@item M-r
-Move point to left margin, vertically centered in the window
-(@code{move-to-window-line}). Text does not move on the screen.
-A numeric argument says which screen line to place point on, counting
-downward from the top of the window (zero means the top line). A
-negative argument counts lines up from the bottom (@minus{}1 means the
-bottom line).
-@item M-<
-Move to the top of the buffer (@code{beginning-of-buffer}). With
-numeric argument @var{n}, move to @var{n}/10 of the way from the top.
-@xref{Arguments}, for more information on numeric arguments.@refill
-@item M->
-Move to the end of the buffer (@code{end-of-buffer}).
-@item C-v
-@itemx @key{PAGEDOWN}
-@itemx @key{PRIOR}
-Scroll the display one screen forward, and move point if necessary to
-put it on the screen (@code{scroll-up}). This doesn't always move
-point, but it is commonly used to do so. If your keyboard has a
-@key{PAGEDOWN} or @key{PRIOR} key, it does the same thing.
-
-Scrolling commands are described further in @ref{Scrolling}.
-@item M-v
-@itemx @key{PAGEUP}
-@itemx @key{NEXT}
-Scroll one screen backward, and move point if necessary to put it on
-the screen (@code{scroll-down}). This doesn't always move point, but
-it is commonly used to do so. If your keyboard has a @key{PAGEUP} or
-@key{NEXT} key, it does the same thing.
-@item M-x goto-char
-Read a number @var{n} and move point to buffer position @var{n}.
-Position 1 is the beginning of the buffer.
-@item M-g M-g
-@itemx M-g g
-@itemx M-x goto-line
-Read a number @var{n} and move point to the beginning of line number
-@var{n}. Line 1 is the beginning of the buffer. If point is on or
-just after a number in the buffer, and you type @key{RET} with the
-minibuffer empty, that number is used for @var{n}.
-@item C-x C-n
-@findex set-goal-column
-@kindex C-x C-n
-Use the current column of point as the @dfn{semipermanent goal column}
-for @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}). When a
-semipermanent goal column is in effect, those commands always try to
-move to this column, or as close as possible to it, after moving
-vertically. The goal column remains in effect until canceled.
-@item C-u C-x C-n
-Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} try to
-preserve the horizontal position, as usual.
-@end table
-
-@vindex track-eol
- If you set the variable @code{track-eol} to a non-@code{nil} value,
-then @kbd{C-n} and @kbd{C-p}, when starting at the end of the line, move
-to the end of another line. Normally, @code{track-eol} is @code{nil}.
-@xref{Variables}, for how to set variables such as @code{track-eol}.
-
-@vindex next-line-add-newlines
- @kbd{C-n} normally stops at the end of the buffer when you use it on
-the last line of the buffer. However, if you set the variable
-@code{next-line-add-newlines} to a non-@code{nil} value, @kbd{C-n} on
-the last line of a buffer creates an additional line at the end and
-moves down into it.
-
-@node Erasing
-@section Erasing Text
-
-@table @kbd
-@item @key{DEL}
-Delete the character before point (@code{delete-backward-char}).
-@item C-d
-Delete the character after point (@code{delete-char}).
-@item @key{DELETE}
-@itemx @key{BACKSPACE}
-One of these keys, whichever is the large key above the @key{RET} or
-@key{ENTER} key, deletes the character before point---it is @key{DEL}.
-If @key{BACKSPACE} is @key{DEL}, and your keyboard also has @key{DELETE},
-then @key{DELETE} deletes forwards, like @kbd{C-d}.
-@item C-k
-Kill to the end of the line (@code{kill-line}).
-@item M-d
-Kill forward to the end of the next word (@code{kill-word}).
-@item M-@key{DEL}
-Kill back to the beginning of the previous word
-(@code{backward-kill-word}).
-@end table
-
-@cindex killing characters and lines
-@cindex deleting characters and lines
-@cindex erasing characters and lines
- You already know about the @key{DEL} key which deletes the character
-before point (that is, before the cursor). Another key, @kbd{Control-d}
-(@kbd{C-d} for short), deletes the character after point (that is, the
-character that the cursor is on). This shifts the rest of the text on
-the line to the left. If you type @kbd{C-d} at the end of a line, it
-joins that line with the following line.
-
- To erase a larger amount of text, use the @kbd{C-k} key, which
-erases (kills) a line at a time. If you type @kbd{C-k} at the
-beginning or middle of a line, it kills all the text up to the end of
-the line. If you type @kbd{C-k} at the end of a line, it joins that
-line with the following line.
-
- @xref{Killing}, for more flexible ways of killing text.
-
-@node Basic Undo
-@section Undoing Changes
-
- Emacs records a list of changes made in the buffer text, so you can
-you can undo recent changes, as far as the records go.
-Usually each editing command makes a separate entry in the undo
-records, but sometimes an entry covers just part of a command, and
-very simple commands may be grouped.
-
-@table @kbd
-@item C-x u
-Undo one entry of the undo records---usually, one command worth
-(@code{undo}).
-@item C-_
-@itemx C-/
-The same.
-@end table
-
- The command @kbd{C-x u} (or @kbd{C-_} or @kbd{C-/}) is how you undo.
-Normally this command undoes the last change, and moves point back to
-where it was before the change.
-
- If you repeat @kbd{C-x u} (or its aliases), each repetition undoes
-another, earlier change, back to the limit of the undo information
-available. If all recorded changes have already been undone, the undo
-command displays an error message and does nothing.
-
- The undo command applies only to changes in the buffer; you can't
-use it to undo mere cursor motion. However, some cursor motion
-commands set the mark, so if you use these commands from time to time,
-you can move back to the neighborhoods you have moved through by
-popping the mark ring (@pxref{Mark Ring}).
-
-@node Basic Files
-@section Files
-
- Text that you insert in an Emacs buffer lasts only as long as the
-Emacs session. To keep any text permanently you must put it in a
-@dfn{file}. Files are named units of text which are stored by the
-operating system for you to retrieve later by name. To use the
-contents of a file in any way, you must specify the file name. That
-includes editing the file with Emacs.
-
- Suppose there is a file named @file{test.emacs} in your home
-directory. To begin editing this file in Emacs, type
-
-@example
-C-x C-f test.emacs @key{RET}
-@end example
-
-@noindent
-Here the file name is given as an @dfn{argument} to the command @kbd{C-x
-C-f} (@code{find-file}). That command uses the @dfn{minibuffer} to
-read the argument, and you type @key{RET} to terminate the argument
-(@pxref{Minibuffer}).
-
- Emacs obeys this command by @dfn{visiting} the file: it creates a
-buffer, it copies the contents of the file into the buffer, and then
-displays the buffer for editing. If you alter the text, you can
-@dfn{save} the new text in the file by typing @kbd{C-x C-s}
-(@code{save-buffer}). This copies the altered buffer contents back
-into the file @file{test.emacs}, making them permanent. Until you
-save, the changed text exists only inside Emacs, and the file
-@file{test.emacs} is unaltered.
-
- To create a file, just visit it with @kbd{C-x C-f} as if it already
-existed. This creates an empty buffer, in which you can insert the
-text you want to put in the file. Emacs actually creates the file the
-first time you save this buffer with @kbd{C-x C-s}.
-
- To learn more about using files in Emacs, see @ref{Files}.
-
-@node Basic Help
-@section Help
-
-@cindex getting help with keys
- If you forget what a key does, you can find out with the Help
-character, which is @kbd{C-h} (or @key{F1}, which is an alias for
-@kbd{C-h}). Type @kbd{C-h k} followed by the key of interest; for
-example, @kbd{C-h k C-n} tells you what @kbd{C-n} does. @kbd{C-h} is
-a prefix key; @kbd{C-h k} is just one of its subcommands (the command
-@code{describe-key}). The other subcommands of @kbd{C-h} provide
-different kinds of help. Type @kbd{C-h} twice to get a description of
-all the help facilities. @xref{Help}.
-
-@node Blank Lines
-@section Blank Lines
-
-@cindex inserting blank lines
-@cindex deleting blank lines
- Here are special commands and techniques for inserting and deleting
-blank lines.
-
-@table @kbd
-@item C-o
-Insert one or more blank lines after the cursor (@code{open-line}).
-@item C-x C-o
-Delete all but one of many consecutive blank lines
-(@code{delete-blank-lines}).
-@end table
-
-@kindex C-o
-@kindex C-x C-o
-@cindex blank lines
-@findex open-line
-@findex delete-blank-lines
- To insert a new line of text before an existing line,
-type the new line of text, followed by @key{RET}.
-However, it may be easier to see what you are doing if you first make a
-blank line and then insert the desired text into it. This is easy to do
-using the key @kbd{C-o} (@code{open-line}), which inserts a newline
-after point but leaves point in front of the newline. After @kbd{C-o},
-type the text for the new line. @kbd{C-o F O O} has the same effect as
-@w{@kbd{F O O @key{RET}}}, except for the final location of point.
-
- You can make several blank lines by typing @kbd{C-o} several times, or
-by giving it a numeric argument specifying how many blank lines to make.
-@xref{Arguments}, for how. If you have a fill prefix, the @kbd{C-o}
-command inserts the fill prefix on the new line, if typed at the
-beginning of a line. @xref{Fill Prefix}.
-
- The easy way to get rid of extra blank lines is with the command
-@kbd{C-x C-o} (@code{delete-blank-lines}). @kbd{C-x C-o} in a run of
-several blank lines deletes all but one of them. @kbd{C-x C-o} on a
-lone blank line deletes that one. When point is on a nonblank line,
-@kbd{C-x C-o} deletes all following blank lines (if any).
-
-@node Continuation Lines
-@section Continuation Lines
-
-@cindex continuation line
-@cindex wrapping
-@cindex line wrapping
-@cindex fringes, and continuation lines
- When a text line is too long to fit in one screen line, Emacs
-displays it on two or more screen lines. This is called
-@dfn{continuation} or @dfn{line wrapping}. On graphical displays,
-Emacs indicates line wrapping with small bent arrows in the left and
-right window fringes. On text-only terminals, Emacs displays a
-@samp{\} character at the right margin of a screen line if it is not
-the last in its text line. This @samp{\} character says that the
-following screen line is not really a new text line.
-
- When line wrapping occurs just before a character that is wider than one
-column, some columns at the end of the previous screen line may be
-``empty.'' In this case, Emacs displays additional @samp{\}
-characters in the ``empty'' columns before the @samp{\}
-character that indicates continuation.
-
- Continued lines can be difficult to read, since lines can break in
-the middle of a word. If you prefer, you can make Emacs insert a
-newline automatically when a line gets too long, by using Auto Fill
-mode. Or enable Long Lines mode, which ensures that wrapping only
-occurs between words. @xref{Filling}.
-
-@cindex truncation
-@cindex line truncation, and fringes
- Emacs can optionally @dfn{truncate} long lines---this means
-displaying just one screen line worth, and the rest of the long line
-does not appear at all. @samp{$} in the last column or a small
-straight arrow in the window's right fringe indicates a truncated
-line.
-
- @xref{Line Truncation}, for more about line truncation,
-and other variables that control how text is displayed.
-
-@node Position Info
-@section Cursor Position Information
-
- Here are commands to get information about the size and position of
-parts of the buffer, and to count lines.
-
-@table @kbd
-@item M-x what-page
-Display the page number of point, and the line number within that page.
-@item M-x what-line
-Display the line number of point in the whole buffer.
-@item M-x line-number-mode
-@itemx M-x column-number-mode
-Toggle automatic display of the current line number or column number.
-@xref{Optional Mode Line}.
-@item M-=
-Display the number of lines in the current region (@code{count-lines-region}).
-@xref{Mark}, for information about the region.
-@item C-x =
-Display the character code of character after point, character position of
-point, and column of point (@code{what-cursor-position}).
-@item M-x hl-line-mode
-Enable or disable highlighting of the current line. @xref{Cursor
-Display}.
-@item M-x size-indication-mode
-Toggle automatic display of the size of the buffer.
-@xref{Optional Mode Line}.
-@end table
-
-@findex what-page
-@findex what-line
-@cindex line number commands
-@cindex location of point
-@cindex cursor location
-@cindex point location
- @kbd{M-x what-line} displays the current line number
-in the echo area. You can also see the current line number in the
-mode line; see @ref{Mode Line}; but if you narrow the buffer, the
-line number in the mode line is relative to the accessible portion
-(@pxref{Narrowing}). By contrast, @code{what-line} shows both the
-line number relative to the narrowed region and the line number
-relative to the whole buffer.
-
- @kbd{M-x what-page} counts pages from the beginning of the file, and
-counts lines within the page, showing both numbers in the echo area.
-@xref{Pages}.
-
-@kindex M-=
-@findex count-lines-region
- Use @kbd{M-=} (@code{count-lines-region}) to displays the number of
-lines in the region (@pxref{Mark}). @xref{Pages}, for the command
-@kbd{C-x l} which counts the lines in the current page.
-
-@kindex C-x =
-@findex what-cursor-position
- The command @kbd{C-x =} (@code{what-cursor-position}) shows what
-cursor's column position, and other information about point and the
-character after it. It displays a line in the echo area that looks
-like this:
-
-@smallexample
-Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53
-@end smallexample
-
- The four values after @samp{Char:} describe the character that follows
-point, first by showing it and then by giving its character code in
-decimal, octal and hex. For a non-@acronym{ASCII} multibyte character, these are
-followed by @samp{file} and the character's representation, in hex, in
-the buffer's coding system, if that coding system encodes the character
-safely and with a single byte (@pxref{Coding Systems}). If the
-character's encoding is longer than one byte, Emacs shows @samp{file ...}.
-
- However, if the character displayed is in the range 0200 through
-0377 octal, it may actually stand for an invalid UTF-8 byte read from
-a file. In Emacs, that byte is represented as a sequence of 8-bit
-characters, but all of them together display as the original invalid
-byte, in octal code. In this case, @kbd{C-x =} shows @samp{part of
-display ...} instead of @samp{file}.
-
- @samp{point=} is followed by the position of point expressed as a
-character count. The start of the buffer is position 1, one character
-later is position 2, and so on. The next, larger, number is the total
-number of characters in the buffer. Afterward in parentheses comes
-the position expressed as a percentage of the total size.
-
- @samp{column=} is followed by the horizontal position of point, in
-columns from the left edge of the window.
-
- If the buffer has been narrowed, making some of the text at the
-beginning and the end temporarily inaccessible, @kbd{C-x =} displays
-additional text describing the currently accessible range. For example, it
-might display this:
-
-@smallexample
-Char: C (67, #o103, #x43) point=252 of 889 (28%) <231-599> column=0
-@end smallexample
-
-@noindent
-where the two extra numbers give the smallest and largest character
-position that point is allowed to assume. The characters between those
-two positions are the accessible ones. @xref{Narrowing}.
-
- If point is at the end of the buffer (or the end of the accessible
-part), the @w{@kbd{C-x =}} output does not describe a character after
-point. The output might look like this:
-
-@smallexample
-point=36169 of 36168 (EOB) column=0
-@end smallexample
-
-@cindex character set of character at point
-@cindex font of character at point
-@cindex text properties at point
-@cindex face at point
- @w{@kbd{C-u C-x =}} displays the following additional information about a
-character.
-
-@itemize @bullet
-@item
-The character set name, and the codes that identify the character
-within that character set; @acronym{ASCII} characters are identified
-as belonging to the @code{ascii} character set.
-
-@item
-The character's syntax and categories.
-
-@item
-The character's encodings, both internally in the buffer, and externally
-if you were to save the file.
-
-@item
-What keys to type to input the character in the current input method
-(if it supports the character).
-
-@item
-If you are running Emacs on a graphical display, the font name and
-glyph code for the character. If you are running Emacs on a text-only
-terminal, the code(s) sent to the terminal.
-
-@item
-The character's text properties (@pxref{Text Properties,,,
-elisp, the Emacs Lisp Reference Manual}), including any non-default
-faces used to display the character, and any overlays containing it
-(@pxref{Overlays,,, elisp, the same manual}).
-@end itemize
-
- Here's an example showing the Latin-1 character A with grave accent,
-in a buffer whose coding system is @code{iso-latin-1}, whose
-terminal coding system is @code{iso-latin-1} (so the terminal actually
-displays the character as @samp{@`A}), and which has font-lock-mode
-(@pxref{Font Lock}) enabled:
-
-@smallexample
- character: @`A (2240, #o4300, #x8c0, U+00C0)
- charset: latin-iso8859-1
- (Right-Hand Part of Latin Alphabet 1@dots{}
- code point: #x40
- syntax: w which means: word
- category: l:Latin
- to input: type "`A" with latin-1-prefix
-buffer code: #x81 #xC0
- file code: #xC0 (encoded by coding system iso-latin-1)
- display: terminal code #xC0
-
-There are text properties here:
- fontified t
-@end smallexample
-
-@node Arguments
-@section Numeric Arguments
-@cindex numeric arguments
-@cindex prefix arguments
-@cindex arguments to commands
-
- In mathematics and computer usage, @dfn{argument} means
-``data provided to a function or operation.'' You can give any Emacs
-command a @dfn{numeric argument} (also called a @dfn{prefix argument}).
-Some commands interpret the argument as a repetition count. For
-example, @kbd{C-f} with an argument of ten moves forward ten characters
-instead of one. With these commands, no argument is equivalent to an
-argument of one. Negative arguments tell most such commands to move or
-act in the opposite direction.
-
-@kindex M-1
-@kindex M-@t{-}
-@findex digit-argument
-@findex negative-argument
- If your terminal keyboard has a @key{META} key (labeled @key{ALT} on
-PC keyboards), the easiest way to specify a numeric argument is to
-type digits and/or a minus sign while holding down the @key{META} key.
-For example,
-
-@example
-M-5 C-n
-@end example
-
-@noindent
-moves down five lines. The characters @kbd{Meta-1}, @kbd{Meta-2},
-and so on, as well as @kbd{Meta--}, do this because they are keys bound
-to commands (@code{digit-argument} and @code{negative-argument}) that
-are defined to set up an argument for the next command.
-@kbd{Meta--} without digits normally means @minus{}1. Digits and
-@kbd{-} modified with Control, or Control and Meta, also specify numeric
-arguments.
-
-@kindex C-u
-@findex universal-argument
- You can also specify a numeric argument by typing @kbd{C-u}
-(@code{universal-argument}) followed by the digits. The advantage of
-@kbd{C-u} is that you can type the digits without modifier keys; thus,
-@kbd{C-u} works on all terminals. For a negative argument, type a
-minus sign after @kbd{C-u}. A minus sign without digits normally
-means @minus{}1.
-
- @kbd{C-u} alone has the special meaning of
-``four times'': it multiplies the argument for the next command by
-four. @kbd{C-u C-u} multiplies it by sixteen. Thus, @kbd{C-u C-u
-C-f} moves forward sixteen characters. This is a good way to move
-forward ``fast,'' since it moves about 1/5 of a line in the usual size
-screen. Other useful combinations are @kbd{C-u C-n}, @kbd{C-u C-u
-C-n} (move down a good fraction of a screen), @kbd{C-u C-u C-o} (make
-``a lot'' of blank lines), and @kbd{C-u C-k} (kill four lines).
-
- Some commands care whether there is an argument, but ignore its
-value. For example, the command @kbd{M-q} (@code{fill-paragraph})
-fills text; with an argument, it justifies the text as well.
-(@xref{Filling}, for more information on @kbd{M-q}.) Plain @kbd{C-u}
-is a handy way of providing an argument for such commands.
-
- Some commands use the value of the argument as a repeat count, but do
-something peculiar when there is no argument. For example, the command
-@kbd{C-k} (@code{kill-line}) with argument @var{n} kills @var{n} lines,
-including their terminating newlines. But @kbd{C-k} with no argument is
-special: it kills the text up to the next newline, or, if point is right at
-the end of the line, it kills the newline itself. Thus, two @kbd{C-k}
-commands with no arguments can kill a nonblank line, just like @kbd{C-k}
-with an argument of one. (@xref{Killing}, for more information on
-@kbd{C-k}.)
-
- A few commands treat a plain @kbd{C-u} differently from an ordinary
-argument. A few others may treat an argument of just a minus sign
-differently from an argument of @minus{}1. These unusual cases are
-described when they come up; they exist to make an individual command
-more convenient, and they are documented in that command's
-documentation string.
-
- You can use a numeric argument before a self-inserting character to
-insert multiple copies of it. This is straightforward when the
-character is not a digit; for example, @kbd{C-u 6 4 a} inserts 64
-copies of the character @samp{a}. But this does not work for
-inserting digits; @kbd{C-u 6 4 1} specifies an argument of 641. You
-can separate the argument from the digit to insert with another
-@kbd{C-u}; for example, @kbd{C-u 6 4 C-u 1} does insert 64 copies of
-the character @samp{1}.
-
- We use the term ``prefix argument'' as well as ``numeric argument,''
-to emphasize that you type these argument before the command, and to
-distinguish them from minibuffer arguments that come after the
-command.
-
-@node Repeating
-@section Repeating a Command
-@cindex repeating a command
-
- Many simple commands, such as those invoked with a single key or
-with @kbd{M-x @var{command-name} @key{RET}}, can be repeated by
-invoking them with a numeric argument that serves as a repeat count
-(@pxref{Arguments}). However, if the command you want to repeat
-prompts for input, or uses a numeric argument in another way, that
-method won't work.
-
-@kindex C-x z
-@findex repeat
- The command @kbd{C-x z} (@code{repeat}) provides another way to repeat
-an Emacs command many times. This command repeats the previous Emacs
-command, whatever that was. Repeating a command uses the same arguments
-that were used before; it does not read new arguments each time.
-
- To repeat the command more than once, type additional @kbd{z}'s: each
-@kbd{z} repeats the command one more time. Repetition ends when you
-type a character other than @kbd{z}, or press a mouse button.
-
- For example, suppose you type @kbd{C-u 2 0 C-d} to delete 20
-characters. You can repeat that command (including its argument) three
-additional times, to delete a total of 80 characters, by typing @kbd{C-x
-z z z}. The first @kbd{C-x z} repeats the command once, and each
-subsequent @kbd{z} repeats it once again.
-
-@ignore
- arch-tag: cda8952a-c439-41c1-aecf-4bc0d6482956
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Buffers, Windows, Files, Top
-@chapter Using Multiple Buffers
-
-@cindex buffers
- The text you are editing in Emacs resides in an object called a
-@dfn{buffer}. Each time you visit a file, a buffer is created to hold the
-file's text. Each time you invoke Dired, a buffer is created to hold the
-directory listing. If you send a message with @kbd{C-x m}, a buffer named
-@samp{*mail*} is used to hold the text of the message. When you ask for a
-command's documentation, that appears in a buffer called @samp{*Help*}.
-
-@cindex selected buffer
-@cindex current buffer
- At any time, one and only one buffer is @dfn{current}. It is also
-called the @dfn{selected buffer}. Often we say that a command operates on
-``the buffer'' as if there were only one; but really this means that the
-command operates on the current buffer (most commands do).
-
- When Emacs has multiple windows, each window has its own chosen
-buffer and displays it; at any time, only one of the windows is
-selected, and its chosen buffer is the current buffer. Each window's
-mode line normally displays the name of the window's chosen buffer
-(@pxref{Windows}).
-
- Each buffer has a name, which can be of any length, and you can select
-any buffer by giving its name. Most buffers are made by visiting files,
-and their names are derived from the files' names. But you can also create
-an empty buffer with any name you want. A newly started Emacs has a buffer
-named @samp{*scratch*} which can be used for evaluating Lisp expressions in
-Emacs. The distinction between upper and lower case matters in buffer
-names.
-
- Each buffer records individually what file it is visiting, whether it is
-modified, and what major mode and minor modes are in effect in it
-(@pxref{Major Modes}). Any Emacs variable can be made @dfn{local to} a
-particular buffer, meaning its value in that buffer can be different from
-the value in other buffers. @xref{Locals}.
-
-@cindex buffer size, maximum
- A buffer's size cannot be larger than some maximum, which is defined
-by the largest buffer position representable by the @dfn{Emacs integer}
-data type. This is because Emacs tracks buffer positions using that
-data type. For 32-bit machines, the largest buffer size is 256
-megabytes.
-
-@menu
-* Select Buffer:: Creating a new buffer or reselecting an old one.
-* List Buffers:: Getting a list of buffers that exist.
-* Misc Buffer:: Renaming; changing read-onlyness; copying text.
-* Kill Buffer:: Killing buffers you no longer need.
-* Several Buffers:: How to go through the list of all buffers
- and operate variously on several of them.
-* Indirect Buffers:: An indirect buffer shares the text of another buffer.
-* Buffer Convenience:: Convenience and customization features for
- buffer handling.
-@end menu
-
-@node Select Buffer
-@section Creating and Selecting Buffers
-@cindex change buffers
-@cindex switch buffers
-
-@table @kbd
-@item C-x b @var{buffer} @key{RET}
-Select or create a buffer named @var{buffer} (@code{switch-to-buffer}).
-@item C-x 4 b @var{buffer} @key{RET}
-Similar, but select @var{buffer} in another window
-(@code{switch-to-buffer-other-window}).
-@item C-x 5 b @var{buffer} @key{RET}
-Similar, but select @var{buffer} in a separate frame
-(@code{switch-to-buffer-other-frame}).
-@item C-x @key{LEFT}
-Select the previous buffer in the list of existing buffers.
-@item C-x @key{RIGHT}
-Select the next buffer in the list of existing buffers.
-@item C-u M-g M-g
-@itemx C-u M-g g
-Read a number @var{n} and move to line @var{n} in the most recently
-selected buffer other than the current buffer.
-@end table
-
-@kindex C-x b
-@findex switch-to-buffer
- To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
-@key{RET}}. This runs the command @code{switch-to-buffer} with argument
-@var{bufname}. You can use completion to enter the buffer
-name (@pxref{Completion}). An empty argument to @kbd{C-x b}
-specifies the buffer that was current most recently among those not
-now displayed in any window.
-
-@kindex C-x @key{LEFT}
-@kindex C-x @key{RIGHT}
-@findex next-buffer
-@findex previous-buffer
- For conveniently switching between a few buffers, use the commands
-@kbd{C-x @key{LEFT}} and @kbd{C-x @key{RIGHT}}. @kbd{C-x @key{RIGHT}}
-(@code{previous-buffer}) selects the previous buffer (following the order
-of most recent selection in the current frame), while @kbd{C-x @key{LEFT}}
-(@code{next-buffer}) moves through buffers in the reverse direction.
-
-@kindex C-x 4 b
-@findex switch-to-buffer-other-window
-@vindex even-window-heights
- To select a buffer in a window other than the current one, type
-@kbd{C-x 4 b @var{bufname} @key{RET}}. This runs the command
-@code{switch-to-buffer-other-window} which displays the buffer
-@var{bufname} in another window. By default, if displaying the buffer
-causes two vertically adjacent windows to be displayed, the heights of
-those windows are evened out; to countermand that and preserve the
-window configuration, set the variable @code{even-window-heights} to
-@code{nil}.
-
-@kindex C-x 5 b
-@findex switch-to-buffer-other-frame
- Similarly, @kbd{C-x 5 b @var{buffer} @key{RET}} runs the command
-@code{switch-to-buffer-other-frame} which selects a buffer in another
-frame.
-
-@vindex display-buffer-reuse-frames
- You can control how certain buffers are handled by these commands by
-customizing the variables @code{special-display-buffer-names},
-@code{special-display-regexps}, @code{same-window-buffer-names}, and
-@code{same-window-regexps}. See @ref{Force Same Window}, and
-@ref{Special Buffer Frames}, for more about these variables. In
-addition, if the value of @code{display-buffer-reuse-frames} is
-non-@code{nil}, and the buffer you want to switch to is already
-displayed in some frame, Emacs will just raise that frame.
-
- Most buffers are created by visiting files, or by Emacs commands that
-want to display some text, but you can also create a buffer explicitly
-by typing @kbd{C-x b @var{bufname} @key{RET}}. This makes a new, empty
-buffer that is not visiting any file, and selects it for editing. Such
-buffers are used for making notes to yourself. If you try to save one,
-you are asked for the file name to use. The new buffer's major mode is
-determined by the value of @code{default-major-mode} (@pxref{Major
-Modes}).
-
- Note that @kbd{C-x C-f}, and any other command for visiting a file,
-can also be used to switch to an existing file-visiting buffer.
-@xref{Visiting}.
-
- @kbd{C-u M-g M-g}, that is @code{goto-line} with a prefix argument
-of just @kbd{C-u}, reads a number @var{n} using the minibuffer,
-selects the most recently selected buffer other than the current
-buffer in another window, and then moves point to the beginning of
-line number @var{n} in that buffer. This is mainly useful in a buffer
-that refers to line numbers in another buffer: if point is on or just
-after a number, @code{goto-line} uses that number as the default for
-@var{n}. Note that prefix arguments other than just @kbd{C-u} behave
-differently. @kbd{C-u 4 M-g M-g} goes to line 4 in the @emph{current}
-buffer, without reading a number from the minibuffer. (Remember that
-@kbd{M-g M-g} without prefix argument reads a number @var{n} and then
-moves to line number @var{n} in the current buffer.)
-
- Emacs uses buffer names that start with a space for internal purposes.
-It treats these buffers specially in minor ways---for example, by
-default they do not record undo information. It is best to avoid using
-such buffer names yourself.
-
-@node List Buffers
-@section Listing Existing Buffers
-
-@table @kbd
-@item C-x C-b
-List the existing buffers (@code{list-buffers}).
-@end table
-
-@cindex listing current buffers
-@kindex C-x C-b
-@findex list-buffers
- To display a list of existing buffers, type @kbd{C-x C-b}. Each
-line in the list shows one buffer's name, major mode and visited file.
-The buffers are listed in the order that they were current; the
-buffers that were current most recently come first.
-
- @samp{*} in the first field of a line indicates the buffer is
-``modified.'' If several buffers are modified, it may be time to save
-some with @kbd{C-x s} (@pxref{Save Commands}). @samp{%} indicates a
-read-only buffer. @samp{.} marks the current buffer. Here is an
-example of a buffer list:@refill
-
-@smallexample
-CRM Buffer Size Mode File
-. * .emacs 3294 Emacs-Lisp ~/.emacs
- % *Help* 101 Help
- search.c 86055 C ~/cvs/emacs/src/search.c
- % src 20959 Dired by name ~/cvs/emacs/src/
- * *mail* 42 Mail
- % HELLO 1607 Fundamental ~/cvs/emacs/etc/HELLO
- % NEWS 481184 Outline ~/cvs/emacs/etc/NEWS
- *scratch* 191 Lisp Interaction
- * *Messages* 1554 Fundamental
-@end smallexample
-
-@noindent
-Note that the buffer @samp{*Help*} was made by a help request; it is
-not visiting any file. The buffer @code{src} was made by Dired on the
-directory @file{~/cvs/emacs/src/}. You can list only buffers that are
-visiting files by giving the command a prefix argument, as in
-@kbd{C-u C-x C-b}.
-
- @code{list-buffers} omits buffers whose names begin with a space,
-unless they visit files: such buffers are used internally by Emacs.
-
-@need 2000
-@node Misc Buffer
-@section Miscellaneous Buffer Operations
-
-@table @kbd
-@item C-x C-q
-Toggle read-only status of buffer (@code{toggle-read-only}).
-@item M-x rename-buffer @key{RET} @var{name} @key{RET}
-Change the name of the current buffer.
-@item M-x rename-uniquely
-Rename the current buffer by adding @samp{<@var{number}>} to the end.
-@item M-x view-buffer @key{RET} @var{buffer} @key{RET}
-Scroll through buffer @var{buffer}.
-@end table
-
-@kindex C-x C-q
-@vindex buffer-read-only
-@cindex read-only buffer
- A buffer can be @dfn{read-only}, which means that commands to change
-its contents are not allowed. The mode line indicates read-only
-buffers with @samp{%%} or @samp{%*} near the left margin. Read-only
-buffers are usually made by subsystems such as Dired and Rmail that
-have special commands to operate on the text; also by visiting a file
-whose access control says you cannot write it.
-
-@findex toggle-read-only
- If you wish to make changes in a read-only buffer, use the command
-@kbd{C-x C-q} (@code{toggle-read-only}). It makes a read-only buffer
-writable, and makes a writable buffer read-only. This
-works by setting the variable @code{buffer-read-only}, which has a local
-value in each buffer and makes the buffer read-only if its value is
-non-@code{nil}. If you have files under version control, you may find
-it convenient to bind @kbd{C-x C-q} to @code{vc-toggle-read-only}
-instead. Then, typing @kbd{C-x C-q} not only changes the read-only
-flag, but it also checks the file in or out. @xref{Version
-Control}.
-
-@findex rename-buffer
- @kbd{M-x rename-buffer} changes the name of the current buffer. You
-specify the new name as a minibuffer argument; there is no default.
-If you specify a name that is in use for some other buffer, an error
-happens and no renaming is done.
-
-@findex rename-uniquely
- @kbd{M-x rename-uniquely} renames the current buffer to a similar
-name with a numeric suffix added to make it both different and unique.
-This command does not need an argument. It is useful for creating
-multiple shell buffers: if you rename the @samp{*shell*} buffer, then
-do @kbd{M-x shell} again, it makes a new shell buffer named
-@samp{*shell*}; meanwhile, the old shell buffer continues to exist
-under its new name. This method is also good for mail buffers,
-compilation buffers, and most Emacs features that create special
-buffers with particular names. (With some of these features, such as
-@kbd{M-x compile}, @kbd{M-x grep} an @kbd{M-x info}, you need to
-switch to some other buffer before using the command, in order for it
-to make a different buffer.)
-
-@findex view-buffer
- @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc
-File Ops}) except that it examines an already existing Emacs buffer.
-View mode provides commands for scrolling through the buffer
-conveniently but not for changing it. When you exit View mode with
-@kbd{q}, that switches back to the buffer (and the position) which was
-previously displayed in the window. Alternatively, if you exit View
-mode with @kbd{e}, the buffer and the value of point that resulted from
-your perusal remain in effect.
-
- The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer}
-can be used to copy text from one buffer to another. @xref{Accumulating
-Text}.
-
-@node Kill Buffer
-@section Killing Buffers
-
-@cindex killing buffers
- If you continue an Emacs session for a while, you may accumulate a
-large number of buffers. You may then find it convenient to @dfn{kill}
-the buffers you no longer need. On most operating systems, killing a
-buffer releases its space back to the operating system so that other
-programs can use it. Here are some commands for killing buffers:
-
-@table @kbd
-@item C-x k @var{bufname} @key{RET}
-Kill buffer @var{bufname} (@code{kill-buffer}).
-@item M-x kill-some-buffers
-Offer to kill each buffer, one by one.
-@end table
-
-@findex kill-buffer
-@findex kill-some-buffers
-@kindex C-x k
-
- @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you
-specify in the minibuffer. The default, used if you type just
-@key{RET} in the minibuffer, is to kill the current buffer. If you
-kill the current buffer, another buffer becomes current: one that was
-current in the recent past but is not displayed in any window now. If
-you ask to kill a file-visiting buffer that is modified (has unsaved
-editing), then you must confirm with @kbd{yes} before the buffer is
-killed.
-
- The command @kbd{M-x kill-some-buffers} asks about each buffer, one by
-one. An answer of @kbd{y} means to kill the buffer. Killing the current
-buffer or a buffer containing unsaved changes selects a new buffer or asks
-for confirmation just like @code{kill-buffer}.
-
- The buffer menu feature (@pxref{Several Buffers}) is also convenient
-for killing various buffers.
-
-@vindex kill-buffer-hook
- If you want to do something special every time a buffer is killed, you
-can add hook functions to the hook @code{kill-buffer-hook} (@pxref{Hooks}).
-
-@findex clean-buffer-list
- If you run one Emacs session for a period of days, as many people do,
-it can fill up with buffers that you used several days ago. The command
-@kbd{M-x clean-buffer-list} is a convenient way to purge them; it kills
-all the unmodified buffers that you have not used for a long time. An
-ordinary buffer is killed if it has not been displayed for three days;
-however, you can specify certain buffers that should never be killed
-automatically, and others that should be killed if they have been unused
-for a mere hour.
-
-@cindex Midnight mode
-@vindex midnight-mode
-@vindex midnight-hook
- You can also have this buffer purging done for you, every day at
-midnight, by enabling Midnight mode. Midnight mode operates each day at
-midnight; at that time, it runs @code{clean-buffer-list}, or whichever
-functions you have placed in the normal hook @code{midnight-hook}
-(@pxref{Hooks}).
-
- To enable Midnight mode, use the Customization buffer to set the
-variable @code{midnight-mode} to @code{t}. @xref{Easy Customization}.
-
-@node Several Buffers
-@section Operating on Several Buffers
-@cindex buffer menu
-
- The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows
-you to request operations on various Emacs buffers by editing an Emacs
-buffer containing a list of them. You can save buffers, kill them
-(here called @dfn{deleting} them, for consistency with Dired), or display
-them.
-
-@table @kbd
-@item M-x buffer-menu
-Begin editing a buffer listing all Emacs buffers.
-@item M-x buffer-menu-other-window.
-Similar, but do it in another window.
-@end table
-
-@findex buffer-menu
-@findex buffer-menu-other-window
- The command @code{buffer-menu} writes a list of all Emacs
-buffers@footnote{Buffers which don't visit files and whose names begin
-with a space are omitted: these are used internally by Emacs.} into the
-buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
-mode.
-
- The buffer is read-only, and can be
-changed only through the special commands described in this section.
-The usual Emacs cursor motion commands can be used in the @samp{*Buffer
-List*} buffer. The following commands apply to the buffer described on
-the current line.
-
-@table @kbd
-@item d
-Request to delete (kill) the buffer, then move down. The request
-shows as a @samp{D} on the line, before the buffer name. Requested
-deletions take place when you type the @kbd{x} command.
-@item C-d
-Like @kbd{d} but move up afterwards instead of down.
-@item s
-Request to save the buffer. The request shows as an @samp{S} on the
-line. Requested saves take place when you type the @kbd{x} command.
-You may request both saving and deletion for the same buffer.
-@item x
-Perform previously requested deletions and saves.
-@item u
-Remove any request made for the current line, and move down.
-@item @key{DEL}
-Move to previous line and remove any request made for that line.
-@end table
-
- The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove
-flags also move down (or up) one line. They accept a numeric argument
-as a repeat count.
-
- These commands operate immediately on the buffer listed on the current
-line:
-
-@table @kbd
-@item ~
-Mark the buffer ``unmodified.'' The command @kbd{~} does this
-immediately when you type it.
-@item %
-Toggle the buffer's read-only flag. The command @kbd{%} does
-this immediately when you type it.
-@item t
-Visit the buffer as a tags table. @xref{Select Tags Table}.
-@end table
-
- There are also commands to select another buffer or buffers:
-
-@table @kbd
-@item q
-Quit the buffer menu---immediately display the most recent formerly
-visible buffer in its place.
-@item @key{RET}
-@itemx f
-Immediately select this line's buffer in place of the @samp{*Buffer
-List*} buffer.
-@item o
-Immediately select this line's buffer in another window as if by
-@kbd{C-x 4 b}, leaving @samp{*Buffer List*} visible.
-@item C-o
-Immediately display this line's buffer in another window, but don't
-select the window.
-@item 1
-Immediately select this line's buffer in a full-screen window.
-@item 2
-Immediately set up two windows, with this line's buffer selected in
-one, and the previously current buffer (aside from the buffer
-@samp{*Buffer List*}) displayed in the other.
-@item b
-Bury the buffer listed on this line.
-@item m
-Mark this line's buffer to be displayed in another window if you exit
-with the @kbd{v} command. The request shows as a @samp{>} at the
-beginning of the line. (A single buffer may not have both a delete
-request and a display request.)
-@item v
-Immediately select this line's buffer, and also display in other windows
-any buffers previously marked with the @kbd{m} command. If you have not
-marked any buffers, this command is equivalent to @kbd{1}.
-@end table
-
- There is also a command that affects the entire buffer list:
-
-@table @kbd
-@item T
-Delete, or reinsert, lines for non-file buffers. This command toggles
-the inclusion of such buffers in the buffer list.
-@end table
-
- What @code{buffer-menu} actually does is create and switch to a
-suitable buffer, and turn on Buffer Menu mode in it. Everything else
-described above is implemented by the special commands provided in
-Buffer Menu mode. One consequence of this is that you can switch from
-the @samp{*Buffer List*} buffer to another Emacs buffer, and edit
-there. You can reselect the @samp{*Buffer List*} buffer later, to
-perform the operations already requested, or you can kill it, or pay
-no further attention to it.
-
- The list in the @samp{*Buffer List*} buffer looks exactly like the
-buffer list described in @ref{List Buffers}, because they really are
-the same. The only difference between @code{buffer-menu} and
-@code{list-buffers} is that @code{buffer-menu} switches to the
-@samp{*Buffer List*} buffer in the selected window;
-@code{list-buffers} displays the same buffer in another window. If
-you run @code{list-buffers} (that is, type @kbd{C-x C-b}) and select
-the buffer list manually, you can use all of the commands described
-here.
-
- Normally, the buffer @samp{*Buffer List*} is not updated
-automatically when buffers are created and killed; its contents are
-just text. If you have created, deleted or renamed buffers, the way
-to update @samp{*Buffer List*} to show what you have done is to type
-@kbd{g} (@code{revert-buffer}). You can make this happen regularly
-every @code{auto-revert-interval} seconds if you enable Auto Revert
-mode in this buffer, as long as it is not marked modified. Global
-Auto Revert mode applies to the @samp{*Buffer List*} buffer only if
-@code{global-auto-revert-non-file-buffers} is non-@code{nil}.
-@iftex
-@inforef{Autorevert,, emacs-xtra}, for details.
-@end iftex
-@ifnottex
-@xref{Autorevert, global-auto-revert-non-file-buffers}, for details.
-@end ifnottex
-
-
- The command @code{buffer-menu-other-window} works the same as
-@code{buffer-menu}, except that it displays the buffers list in
-another window.
-
-@node Indirect Buffers
-@section Indirect Buffers
-@cindex indirect buffer
-@cindex base buffer
-
- An @dfn{indirect buffer} shares the text of some other buffer, which
-is called the @dfn{base buffer} of the indirect buffer. In some ways it
-is the analogue, for buffers, of a symbolic link between files.
-
-@table @kbd
-@findex make-indirect-buffer
-@item M-x make-indirect-buffer @key{RET} @var{base-buffer} @key{RET} @var{indirect-name} @key{RET}
-Create an indirect buffer named @var{indirect-name} whose base buffer
-is @var{base-buffer}.
-@findex clone-indirect-buffer
-@item M-x clone-indirect-buffer @key{RET}
-Create an indirect buffer that is a twin copy of the current buffer.
-@item C-x 4 c
-@kindex C-x 4 c
-@findex clone-indirect-buffer-other-window
-Create an indirect buffer that is a twin copy of the current buffer, and
-select it in another window (@code{clone-indirect-buffer-other-window}).
-@end table
-
- The text of the indirect buffer is always identical to the text of its
-base buffer; changes made by editing either one are visible immediately
-in the other. But in all other respects, the indirect buffer and its
-base buffer are completely separate. They have different names,
-different values of point, different narrowing, different markers,
-different major modes, and different local variables.
-
- An indirect buffer cannot visit a file, but its base buffer can. If
-you try to save the indirect buffer, that actually works by saving the
-base buffer. Killing the base buffer effectively kills the indirect
-buffer, but killing an indirect buffer has no effect on its base buffer.
-
- One way to use indirect buffers is to display multiple views of an
-outline. @xref{Outline Views}.
-
- A quick and handy way to make an indirect buffer is with the command
-@kbd{M-x clone-indirect-buffer}. It creates and selects an indirect
-buffer whose base buffer is the current buffer. With a numeric
-argument, it prompts for the name of the indirect buffer; otherwise it
-uses the name of the current buffer, with a @samp{<@var{n}>} suffix
-added. @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window})
-works like @kbd{M-x clone-indirect-buffer}, but it selects the new
-buffer in another window.
-
- The more general way to make an indirect buffer is with the command
-@kbd{M-x make-indirect-buffer}. It creates an indirect buffer from
-buffer @var{base-buffer}, under the name @var{indirect-name}. It
-prompts for both @var{base-buffer} and @var{indirect-name} using the
-minibuffer.
-
-@node Buffer Convenience
-@section Convenience Features and Customization of Buffer Handling
-
- This section describes several modes and features that make it more
-convenient to switch between buffers.
-
-@menu
-* Uniquify:: Making buffer names unique with directory parts.
-* Iswitchb:: Switching between buffers with substrings.
-* Buffer Menus:: Configurable buffer menu.
-@end menu
-
-@node Uniquify
-@subsection Making Buffer Names Unique
-
-@cindex unique buffer names
-@cindex directories in buffer names
- When several buffers visit identically-named files, Emacs must give
-the buffers distinct names. The usual method for making buffer names
-unique adds @samp{<2>}, @samp{<3>}, etc. to the end of the buffer
-names (all but one of them).
-
-@vindex uniquify-buffer-name-style
- Other methods work by adding parts of each file's directory to the
-buffer name. To select one, customize the variable
-@code{uniquify-buffer-name-style} (@pxref{Easy Customization}).
-
- To begin with, the @code{forward} naming method includes part of the
-file's directory name at the beginning of the buffer name; using this
-method, buffers visiting the files @file{/u/rms/tmp/Makefile} and
-@file{/usr/projects/zaphod/Makefile} would be named
-@samp{tmp/Makefile} and @samp{zaphod/Makefile}, respectively (instead
-of @samp{Makefile} and @samp{Makefile<2>}).
-
- In contrast, the @code{post-forward} naming method would call the
-buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}, and the
-@code{reverse} naming method would call them @samp{Makefile\tmp} and
-@samp{Makefile\zaphod}. The nontrivial difference between
-@code{post-forward} and @code{reverse} occurs when just one directory
-name is not enough to distinguish two files; then @code{reverse} puts
-the directory names in reverse order, so that @file{/top/middle/file}
-becomes @samp{file\middle\top}, while @code{post-forward} puts them in
-forward order after the file name, as in @samp{file|top/middle}.
-
- Which rule to follow for putting the directory names in the buffer
-name is not very important if you are going to @emph{look} at the
-buffer names before you type one. But as an experienced user, if you
-know the rule, you won't have to look. And then you may find that one
-rule or another is easier for you to remember and apply quickly.
-
-@node Iswitchb
-@subsection Switching Between Buffers using Substrings
-
-@findex iswitchb-mode
-@cindex Iswitchb mode
-@cindex mode, Iswitchb
-@kindex C-x b @r{(Iswitchb mode)}
-@kindex C-x 4 b @r{(Iswitchb mode)}
-@kindex C-x 5 b @r{(Iswitchb mode)}
-@kindex C-x 4 C-o @r{(Iswitchb mode)}
-
- Iswitchb global minor mode provides convenient switching between
-buffers using substrings of their names. It replaces the normal
-definitions of @kbd{C-x b}, @kbd{C-x 4 b}, @kbd{C-x 5 b}, and @kbd{C-x
-4 C-o} with alternative commands that are somewhat ``smarter.''
-
- When one of these commands prompts you for a buffer name, you can
-type in just a substring of the name you want to choose. As you enter
-the substring, Iswitchb mode continuously displays a list of buffers
-that match the substring you have typed.
-
- At any time, you can type @key{RET} to select the first buffer in
-the list. So the way to select a particular buffer is to make it the
-first in the list. There are two ways to do this. You can type more
-of the buffer name and thus narrow down the list, excluding unwanted
-buffers above the desired one. Alternatively, you can use @kbd{C-s}
-and @kbd{C-r} to rotate the list until the desired buffer is first.
-
- @key{TAB} while entering the buffer name performs completion on the
-string you have entered, based on the displayed list of buffers.
-
- To enable Iswitchb mode, type @kbd{M-x iswitchb-mode}, or customize
-the variable @code{iswitchb-mode} to @code{t} (@pxref{Easy
-Customization}).
-
-@node Buffer Menus
-@subsection Customizing Buffer Menus
-
-@findex bs-show
-@cindex buffer list, customizable
-@table @kbd
-@item M-x bs-show
-Make a list of buffers similarly to @kbd{M-x list-buffers} but
-customizable.
-@end table
-
- @kbd{M-x bs-show} pops up a buffer list similar to the one normally
-displayed by @kbd{C-x C-b} but which you can customize. If you prefer
-this to the usual buffer list, you can bind this command to @kbd{C-x
-C-b}. To customize this buffer list, use the @code{bs} Custom group
-(@pxref{Easy Customization}).
-
-@findex msb-mode
-@cindex mode, MSB
-@cindex MSB mode
-@cindex buffer menu
-@findex mouse-buffer-menu
-@kindex C-Down-Mouse-1
- MSB global minor mode (``MSB'' stands for ``mouse select buffer'')
-provides a different and customizable mouse buffer menu which you may
-prefer. It replaces the bindings of @code{mouse-buffer-menu},
-normally on @kbd{C-Down-Mouse-1}, and the menu bar buffer menu. You
-can customize the menu in the @code{msb} Custom group.
-
-@ignore
- arch-tag: 08c43460-f4f4-4b43-9cb5-1ea9ad991695
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Building, Maintaining, Programs, Top
-@chapter Compiling and Testing Programs
-@cindex building programs
-@cindex program building
-@cindex running Lisp functions
-
- The previous chapter discusses the Emacs commands that are useful for
-making changes in programs. This chapter deals with commands that assist
-in the larger process of compiling and testing programs.
-
-@menu
-* Compilation:: Compiling programs in languages other
- than Lisp (C, Pascal, etc.).
-* Compilation Mode:: The mode for visiting compiler errors.
-* Compilation Shell:: Customizing your shell properly
- for use in the compilation buffer.
-* Grep Searching:: Searching with grep.
-* Flymake:: Finding syntax errors on the fly.
-* Debuggers:: Running symbolic debuggers for non-Lisp programs.
-* Executing Lisp:: Various modes for editing Lisp programs,
- with different facilities for running
- the Lisp programs.
-* Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
-* Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
-* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
-* External Lisp:: Communicating through Emacs with a separate Lisp.
-@end menu
-
-@node Compilation
-@section Running Compilations under Emacs
-@cindex inferior process
-@cindex make
-@cindex compilation errors
-@cindex error log
-
- Emacs can run compilers for noninteractive languages such as C and
-Fortran as inferior processes, feeding the error log into an Emacs buffer.
-It can also parse the error messages and show you the source lines where
-compilation errors occurred.
-
-@table @kbd
-@item M-x compile
-Run a compiler asynchronously under Emacs, with error messages going to
-the @samp{*compilation*} buffer.
-@item M-x recompile
-Invoke a compiler with the same command as in the last invocation of
-@kbd{M-x compile}.
-@item M-x kill-compilation
-Kill the running compilation subprocess.
-@end table
-
-@findex compile
- To run @code{make} or another compilation command, do @kbd{M-x
-compile}. This command reads a shell command line using the minibuffer,
-and then executes the command in an inferior shell, putting output in
-the buffer named @samp{*compilation*}. The current buffer's default
-directory is used as the working directory for the execution of the
-command; normally, therefore, the compilation happens in this
-directory.
-
-@vindex compile-command
- The default for the compilation command is normally @samp{make -k},
-which is correct most of the time for nontrivial programs.
-(@xref{Top,, Make, make, GNU Make Manual}.) If you have done @kbd{M-x
-compile} before, the default each time is the command you used the
-previous time. @code{compile} stores this command in the variable
-@code{compile-command}, so setting that variable specifies the default
-for the next use of @kbd{M-x compile}. If a file specifies a file
-local value for @code{compile-command}, that provides the default when
-you type @kbd{M-x compile} in that file's buffer. @xref{File
-Variables}.
-
- Starting a compilation displays the buffer @samp{*compilation*} in
-another window but does not select it. The buffer's mode line tells
-you whether compilation is finished, with the word @samp{run},
-@samp{signal} or @samp{exit} inside the parentheses. You do not have
-to keep this buffer visible; compilation continues in any case. While
-a compilation is going on, the string @samp{Compiling} appears in the
-mode lines of all windows. When this string disappears, the
-compilation is finished.
-
- If you want to watch the compilation transcript as it appears, switch
-to the @samp{*compilation*} buffer and move point to the end of the
-buffer. When point is at the end, new compilation output is inserted
-above point, which remains at the end. If point is not at the end of
-the buffer, it remains fixed while more compilation output is added at
-the end of the buffer.
-
-@cindex compilation buffer, keeping point at end
-@vindex compilation-scroll-output
- If you set the variable @code{compilation-scroll-output} to a
-non-@code{nil} value, then the compilation buffer always scrolls to
-follow output as it comes in.
-
-@findex recompile
- To rerun the last compilation with the same command, type @kbd{M-x
-recompile}. This automatically reuses the compilation command from
-the last invocation of @kbd{M-x compile}. It also reuses the
-@samp{*compilation*} buffer and starts the compilation in its default
-directory, which is the directory in which the previous compilation
-was started.
-
- When the compiler process terminates, for whatever reason, the mode
-line of the @samp{*compilation*} buffer changes to say @samp{exit}
-(followed by the exit code, @samp{[0]} for a normal exit), or
-@samp{signal} (if a signal terminated the process), instead of
-@samp{run}.
-
-@findex kill-compilation
- Starting a new compilation also kills any compilation already
-running in @samp{*compilation*}, as the buffer can only handle one
-compilation at any time. However, @kbd{M-x compile} asks for
-confirmation before actually killing a compilation that is running.
-You can also kill the compilation process with @kbd{M-x
-kill-compilation}.
-
- If you want to run two compilations at once, you should start the
-first one, then rename the @samp{*compilation*} buffer (perhaps using
-@code{rename-uniquely}; @pxref{Misc Buffer}), and start the other
-compilation. That will create a new @samp{*compilation*} buffer.
-
- Emacs does not expect a compiler process to launch asynchronous
-subprocesses; if it does, and they keep running after the main
-compiler process has terminated, Emacs may kill them or their output
-may not arrive in Emacs. To avoid this problem, make the main process
-wait for its subprocesses to finish. In a shell script, you can do this
-using @samp{$!} and @samp{wait}, like this:
-
-@example
-(sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess}
-echo first message
-wait $pid # @r{Wait for subprocess}
-@end example
-
- If the background process does not output to the compilation buffer,
-so you only need to prevent it from being killed when the main
-compilation process terminates, this is sufficient:
-
-@example
-nohup @var{command}; sleep 1
-@end example
-
-@vindex compilation-environment
- You can control the environment passed to the compilation command
-with the variable @code{compilation-environment}. Its value is a list
-of environment variable settings; each element should be a string of
-the form @code{"@var{envvarname}=@var{value}"}. These environment
-variable settings override the usual ones.
-
-@node Compilation Mode
-@section Compilation Mode
-
-@cindex Compilation mode
-@cindex mode, Compilation
- The @samp{*compilation*} buffer uses a special major mode,
-Compilation mode, whose main feature is to provide a convenient way to
-visit the source line corresponding to an error message. These
-commands are also available in other special buffers that list
-locations in files, including those made by @kbd{M-x grep} and
-@kbd{M-x occur}.
-
-@table @kbd
-@item M-g M-n
-@itemx M-g n
-@itemx C-x `
-Visit the locus of the next error message or match.
-@item M-g M-p
-@itemx M-g p
-Visit the locus of the previous error message or match.
-@item @key{RET}
-Visit the locus of the error message that point is on.
-This command is used in the compilation buffer.
-@item Mouse-2
-Visit the locus of the error message that you click on.
-@item M-n
-Find and highlight the locus of the next error message, without
-selecting the source buffer.
-@item M-p
-Find and highlight the locus of the previous error message, without
-selecting the source buffer.
-@item M-@}
-Move point to the next error for a different file than the current
-one.
-@item M-@{
-Move point to the previous error for a different file than the current
-one.
-@item C-c C-f
-Toggle Next Error Follow minor mode, which makes cursor motion in the
-compilation buffer produce automatic source display.
-@end table
-
-@findex compile-goto-error
- You can visit the source for any particular error message by moving
-point in the @samp{*compilation*} buffer to that error message and
-typing @key{RET} (@code{compile-goto-error}). Alternatively, you can
-click @kbd{Mouse-2} on the error message; you need not switch to the
-@samp{*compilation*} buffer first.
-
-@kindex M-g M-n
-@kindex M-g n
-@kindex C-x `
-@findex next-error
-@vindex next-error-highlight
- To parse the compiler error messages sequentially, type @kbd{C-x `}
-(@code{next-error}). The character following the @kbd{C-x} is the
-backquote or ``grave accent,'' not the single-quote. This command is
-available in all buffers, not just in @samp{*compilation*}; it
-displays the next error message at the top of one window and source
-location of the error in another window. It also temporarily
-highlights the relevant source line, for a period controlled by the
-variable @code{next-error-highlight}.
-
- The first time @w{@kbd{C-x `}} is used after the start of a compilation,
-it moves to the first error's location. Subsequent uses of @kbd{C-x
-`} advance down to subsequent errors. If you visit a specific error
-message with @key{RET} or @kbd{Mouse-2}, subsequent @w{@kbd{C-x `}}
-commands advance from there. When @w{@kbd{C-x `}} gets to the end of the
-buffer and finds no more error messages to visit, it fails and signals
-an Emacs error. @w{@kbd{C-u C-x `}} starts scanning from the beginning of
-the compilation buffer, and goes to the first error's location.
-
-@vindex compilation-skip-threshold
- By default, @w{@kbd{C-x `}} skips less important messages. The variable
-@code{compilation-skip-threshold} controls this. If its value is 2,
-@w{@kbd{C-x `}} skips anything less than error, 1 skips anything less
-than warning, and 0 doesn't skip any messages. The default is 1.
-
- When the window has a left fringe, an arrow in the fringe points to
-the current message in the compilation buffer. The variable
-@code{compilation-context-lines} controls the number of lines of
-leading context to display before the current message. Going to an
-error message location scrolls the @samp{*compilation*} buffer to put
-the message that far down from the top. The value @code{nil} is
-special: if there's a left fringe, the window doesn't scroll at all
-if the message is already visible. If there is no left fringe,
-@code{nil} means display the message at the top of the window.
-
- If you're not in the compilation buffer when you run
-@code{next-error}, Emacs will look for a buffer that contains error
-messages. First, it looks for one displayed in the selected frame,
-then for one that previously had @code{next-error} called on it, and
-then at the current buffer. Finally, Emacs looks at all the remaining
-buffers. @code{next-error} signals an error if it can't find any such
-buffer.
-
-@vindex compilation-error-regexp-alist
-@vindex grep-regexp-alist
- To parse messages from the compiler, Compilation mode uses the
-variable @code{compilation-error-regexp-alist} which lists various
-formats of error messages and tells Emacs how to extract the source file
-and the line number from the text of a message. If your compiler isn't
-supported, you can tailor Compilation mode to it by adding elements to
-that list. A similar variable @code{grep-regexp-alist} tells Emacs how
-to parse output of a @code{grep} command.
-
-@findex compilation-next-error
-@findex compilation-previous-error
-@findex compilation-next-file
-@findex compilation-previous-file
- Compilation mode also redefines the keys @key{SPC} and @key{DEL} to
-scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error})
-and @kbd{M-p} (@code{compilation-previous-error}) to move to the next
-or previous error message. You can also use @kbd{M-@{}
-(@code{compilation-next-file} and @kbd{M-@}}
-(@code{compilation-previous-file}) to move up or down to an error
-message for a different source file.
-
-@cindex Next Error Follow mode
-@findex next-error-follow-minor-mode
- You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In
-this minor mode, ordinary cursor motion in the compilation buffer
-automatically updates the source buffer. For instance, moving the
-cursor to the next error message causes the location of that error to
-be displayed immediately.
-
- The features of Compilation mode are also available in a minor mode
-called Compilation Minor mode. This lets you parse error messages in
-any buffer, not just a normal compilation output buffer. Type @kbd{M-x
-compilation-minor-mode} to enable the minor mode. This defines the keys
-@key{RET} and @kbd{Mouse-2}, as in the Compilation major mode.
-
- Compilation minor mode works in any buffer, as long as the contents
-are in a format that it understands. In an Rlogin buffer (@pxref{Remote
-Host}), Compilation minor mode automatically accesses remote source
-files by FTP (@pxref{File Names}).
-
-@node Compilation Shell
-@section Subshells for Compilation
-
- Emacs uses a shell to run the compilation command, but specifies the
-option for a noninteractive shell. This means, in particular, that
-the shell should start with no prompt. If you find your usual shell
-prompt making an unsightly appearance in the @samp{*compilation*}
-buffer, it means you have made a mistake in your shell's init file by
-setting the prompt unconditionally. (This init file's name may be
-@file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or
-various other things, depending on the shell you use.) The shell init
-file should set the prompt only if there already is a prompt. Here's
-how to do it in bash:
-
-@example
-if [ "$@{PS1+set@}" = set ]
-then PS1=@dots{}
-fi
-@end example
-
-@noindent
-And here's how to do it in csh:
-
-@example
-if ($?prompt) set prompt = @dots{}
-@end example
-
- There may well be other things that your shell's init file
-ought to do only for an interactive shell. You can use the same
-method to conditionalize them.
-
- The MS-DOS ``operating system'' does not support asynchronous
-subprocesses; to work around this lack, @kbd{M-x compile} runs the
-compilation command synchronously on MS-DOS. As a consequence, you must
-wait until the command finishes before you can do anything else in
-Emacs.
-@iftex
-@inforef{MS-DOS,,emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{MS-DOS}.
-@end ifnottex
-
-@node Grep Searching
-@section Searching with Grep under Emacs
-
- Just as you can run a compiler from Emacs and then visit the lines
-with compilation errors, you can also run @code{grep} and then visit
-the lines on which matches were found. This works by treating the
-matches reported by @code{grep} as if they were ``errors.'' The
-buffer of matches uses Grep mode, which is a variant of Compilation
-mode (@pxref{Compilation Mode}).
-
-@table @kbd
-@item M-x grep
-@item M-x lgrep
-Run @code{grep} asynchronously under Emacs, with matching lines
-listed in the buffer named @samp{*grep*}.
-@item M-x grep-find
-@itemx M-x find-grep
-@itemx M-x rgrep
-Run @code{grep} via @code{find}, with user-specified arguments, and
-collect output in the buffer named @samp{*grep*}.
-@item M-x kill-grep
-Kill the running @code{grep} subprocess.
-@end table
-
-@findex grep
- To run @code{grep}, type @kbd{M-x grep}, then enter a command line
-that specifies how to run @code{grep}. Use the same arguments you
-would give @code{grep} when running it normally: a @code{grep}-style
-regexp (usually in single-quotes to quote the shell's special
-characters) followed by file names, which may use wildcards. If you
-specify a prefix argument for @kbd{M-x grep}, it finds the tag
-(@pxref{Tags}) in the buffer around point, and puts that into the
-default @code{grep} command.
-
- Your command need not simply run @code{grep}; you can use any shell
-command that produces output in the same format. For instance, you
-can chain @code{grep} commands, like this:
-
-@example
-grep -nH -e foo *.el | grep bar | grep toto
-@end example
-
- The output from @code{grep} goes in the @samp{*grep*} buffer. You
-can find the corresponding lines in the original files using @w{@kbd{C-x
-`}}, @key{RET}, and so forth, just like compilation errors.
-
- Some grep programs accept a @samp{--color} option to output special
-markers around matches for the purpose of highlighting. You can make
-use of this feature by setting @code{grep-highlight-matches} to
-@code{t}. When displaying a match in the source buffer, the exact
-match will be highlighted, instead of the entire source line.
-
-@findex grep-find
-@findex find-grep
- The command @kbd{M-x grep-find} (also available as @kbd{M-x
-find-grep}) is similar to @kbd{M-x grep}, but it supplies a different
-initial default for the command---one that runs both @code{find} and
-@code{grep}, so as to search every file in a directory tree. See also
-the @code{find-grep-dired} command, in @ref{Dired and Find}.
-
-@findex lgrep
-@findex rgrep
- The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep}
-(recursive grep) are more user-friendly versions of @code{grep} and
-@code{grep-find}, which prompt separately for the regular expression
-to match, the files to search, and the base directory for the search.
-Case sensitivity of the search is controlled by the
-current value of @code{case-fold-search}.
-
-These commands build the shell commands based on the variables
-@code{grep-template} (for @code{lgrep}) and @code{grep-find-template}
-(for @code{rgrep}).
-
-The files to search can use aliases defined in the variable
-@code{grep-files-aliases}.
-
-Subdirectories listed in the variable
-@code{grep-find-ignored-directories} such as those typically used by
-various version control systems, like CVS and arch, are automatically
-skipped by @code{rgrep}.
-
-@node Flymake
-@section Finding Syntax Errors On The Fly
-@cindex checking syntax
-
- Flymake mode is a minor mode that performs on-the-fly syntax
-checking for many programming and markup languages, including C, C++,
-Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell
-mode, which performs spell checking for ordinary human languages in a
-similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode
-runs an appropriate syntax checking tool in the background, using a
-temporary copy of the buffer. It then parses the error and warning
-messages, and highlights the erroneous lines in the buffer. The
-syntax checking tool used depends on the language; for example, for
-C/C++ files this is usually the C compiler. Flymake can also use
-build tools such as @code{make} for checking complicated projects.
-
- To activate Flymake mode, type @kbd{M-x flymake-mode}. You can move
-to the errors spotted by Flymake mode with @kbd{M-x
-flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To
-display any error messages associated with the current line, use
-@kbd{M-x flymake-display-err-menu-for-current-line}.
-
- For more details about using Flymake, see @ref{Top, Flymake,
-Flymake, flymake, The Flymake Manual}.
-
-@node Debuggers
-@section Running Debuggers Under Emacs
-@cindex debuggers
-@cindex GUD library
-@cindex GDB
-@cindex DBX
-@cindex SDB
-@cindex XDB
-@cindex Perldb
-@cindex JDB
-@cindex PDB
-
-@c Do you believe in GUD?
-The GUD (Grand Unified Debugger) library provides an interface to
-various symbolic debuggers from within Emacs. We recommend the
-debugger GDB, which is free software, but GUD can also run DBX, SDB or
-XDB. GUD can also serve as an interface to Perl's debugging mode, the
-Python debugger PDB, and to JDB, the Java Debugger.
-@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference
-Manual}, for information on debugging Emacs Lisp programs.
-
-@menu
-* Starting GUD:: How to start a debugger subprocess.
-* Debugger Operation:: Connection between the debugger and source buffers.
-* Commands of GUD:: Key bindings for common commands.
-* GUD Customization:: Defining your own commands for GUD.
-* GDB Graphical Interface:: An enhanced mode that uses GDB features to
- implement a graphical debugging environment through
- Emacs.
-@end menu
-
-@node Starting GUD
-@subsection Starting GUD
-
- There are several commands for starting a debugger, each corresponding
-to a particular debugger program.
-
-@table @kbd
-@item M-x gdb @key{RET} @var{file} @key{RET}
-@findex gdb
-Run GDB as a subprocess of Emacs. By default, this uses an IDE-like
-graphical interface; see @ref{GDB Graphical Interface}. Only GDB
-works with the graphical interface.
-
-@item M-x dbx @key{RET} @var{file} @key{RET}
-@findex dbx
-Run DBX as a subprocess of Emacs. Since Emacs does not implement a
-graphical interface for DBX, communication with DBX works by typing
-commands in the GUD interaction buffer. The same is true for all
-the other supported debuggers.
-
-@item M-x xdb @key{RET} @var{file} @key{RET}
-@findex xdb
-@vindex gud-xdb-directories
-Similar, but run XDB. Use the variable
-@code{gud-xdb-directories} to specify directories to search for source
-files.
-
-@item M-x sdb @key{RET} @var{file} @key{RET}
-@findex sdb
-Similar, but run SDB.
-
- Some versions of SDB do not mention source file names in their
-messages. When you use them, you need to have a valid tags table
-(@pxref{Tags}) in order for GUD to find functions in the source code.
-If you have not visited a tags table or the tags table doesn't list one
-of the functions, you get a message saying @samp{The sdb support
-requires a valid tags table to work}. If this happens, generate a valid
-tags table in the working directory and try again.
-
-@item M-x perldb @key{RET} @var{file} @key{RET}
-@findex perldb
-Run the Perl interpreter in debug mode to debug @var{file}, a Perl program.
-
-@item M-x jdb @key{RET} @var{file} @key{RET}
-@findex jdb
-Run the Java debugger to debug @var{file}.
-
-@item M-x pdb @key{RET} @var{file} @key{RET}
-@findex pdb
-Run the Python debugger to debug @var{file}.
-@end table
-
- Each of these commands takes one argument: a command line to invoke
-the debugger. In the simplest case, specify just the name of the
-executable file you want to debug. You may also use options that the
-debugger supports. However, shell wildcards and variables are not
-allowed. GUD assumes that the first argument not starting with a
-@samp{-} is the executable file name.
-
-Tramp provides a facility to debug programs on remote hosts.
-@xref{Running a debugger on a remote host, Running a debugger on a remote host,, tramp, The Tramp Manual}.
-@c Running a debugger on a remote host
-
-@node Debugger Operation
-@subsection Debugger Operation
-
-@cindex fringes, and current execution line in GUD
- Generally when you run a debugger with GUD, the debugger uses an Emacs
-buffer for its ordinary input and output. This is called the GUD
-buffer. Input and output from the program you are debugging also use
-this buffer. We call this @dfn{text command mode}. The GDB Graphical
-Interface can use further buffers (@pxref{GDB Graphical Interface}).
-
- The debugger displays the source files of the program by visiting
-them in Emacs buffers. An arrow in the left fringe indicates the
-current execution line.@footnote{On a text-only terminal, the arrow
-appears as @samp{=>} and overlays the first two text columns.} Moving
-point in this buffer does not move the arrow. The arrow is not part
-of the file's text; it appears only on the screen.
-
- You can start editing these source files at any time in the buffers
-that display them. If you do modify a source file, keep in mind that
-inserting or deleting lines will throw off the arrow's positioning;
-GUD has no way of figuring out which line corresponded before your
-changes to the line number in a debugger message. Also, you'll
-typically have to recompile and restart the program for your changes
-to be reflected in the debugger's tables.
-
-@cindex tooltips with GUD
-@vindex tooltip-gud-modes
-@vindex gud-tooltip-mode
-@vindex gud-tooltip-echo-area
- The Tooltip facility (@pxref{Tooltips}) provides support for GUD@.
-You activate this feature by turning on the minor mode
-@code{gud-tooltip-mode}. Then you can display a variable's value in a
-tooltip simply by pointing at it with the mouse. This operates in the
-GUD buffer and in source buffers with major modes in the list
-@code{gud-tooltip-modes}. If the variable @code{gud-tooltip-echo-area}
-is non-@code{nil} then the variable's value is displayed in the echo
-area. When debugging a C program using the GDB Graphical Interface, you
-can also display macro definitions associated with an identifier when
-the program is not executing.
-
- GUD tooltips are disabled when you use GDB in text command mode
-(@pxref{GDB Graphical Interface}), because displaying an expression's
-value in GDB can sometimes expand a macro and result in a side effect
-that interferes with the program's operation. The GDB graphical
-interface supports GUD tooltips and assures they will not cause side
-effects.
-
-@node Commands of GUD
-@subsection Commands of GUD
-
- The GUD interaction buffer uses a variant of Shell mode, so the
-Emacs commands of Shell mode are available (@pxref{Shell Mode}). All
-the usual commands for your debugger are available, and you can use
-the Shell mode history commands to repeat them. If you wish, you can
-control your debugger process entirely through this buffer.
-
- GUD mode also provides commands for setting and clearing
-breakpoints, for selecting stack frames, and for stepping through the
-program. These commands are available both in the GUD buffer and
-globally, but with different key bindings. It also has its own tool
-bar from which you can invoke the more common commands by clicking on
-the appropriate icon. This is particularly useful for repetitive
-commands like @code{gud-next} and @code{gud-step}, and allows you to
-keep the GUD buffer hidden.
-
- The breakpoint commands are normally used in source file buffers,
-because that is the easiest way to specify where to set or clear the
-breakpoint. Here's the global command to set a breakpoint:
-
-@table @kbd
-@item C-x @key{SPC}
-@kindex C-x SPC
-Set a breakpoint on the source line that point is on.
-@end table
-
-@kindex C-x C-a @r{(GUD)}
- Here are the other special commands provided by GUD@. The keys
-starting with @kbd{C-c} are available only in the GUD interaction
-buffer. The key bindings that start with @kbd{C-x C-a} are available
-in the GUD interaction buffer and also in source files. Some of these
-commands are not available to all the supported debuggers.
-
-@table @kbd
-@item C-c C-l
-@kindex C-c C-l @r{(GUD)}
-@itemx C-x C-a C-l
-@findex gud-refresh
-Display in another window the last line referred to in the GUD
-buffer (that is, the line indicated in the last location message).
-This runs the command @code{gud-refresh}.
-
-@item C-c C-s
-@kindex C-c C-s @r{(GUD)}
-@itemx C-x C-a C-s
-@findex gud-step
-Execute a single line of code (@code{gud-step}). If the line contains
-a function call, execution stops after entering the called function.
-
-@item C-c C-n
-@kindex C-c C-n @r{(GUD)}
-@itemx C-x C-a C-n
-@findex gud-next
-Execute a single line of code, stepping across entire function calls
-at full speed (@code{gud-next}).
-
-@item C-c C-i
-@kindex C-c C-i @r{(GUD)}
-@itemx C-x C-a C-i
-@findex gud-stepi
-Execute a single machine instruction (@code{gud-stepi}).
-
-@item C-c C-p
-@kindex C-c C-p @r{(GUD)}
-@itemx C-x C-a C-p
-@findex gud-print
-Evaluate the expression at point (@code{gud-print}). If Emacs
-does not print the exact expression that you want, mark it as a region
-first.
-
-@need 3000
-@item C-c C-r
-@kindex C-c C-r @r{(GUD)}
-@itemx C-x C-a C-r
-@findex gud-cont
-Continue execution without specifying any stopping point. The program
-will run until it hits a breakpoint, terminates, or gets a signal that
-the debugger is checking for (@code{gud-cont}).
-
-@need 1000
-@item C-c C-d
-@kindex C-c C-d @r{(GUD)}
-@itemx C-x C-a C-d
-@findex gud-remove
-Delete the breakpoint(s) on the current source line, if any
-(@code{gud-remove}). If you use this command in the GUD interaction
-buffer, it applies to the line where the program last stopped.
-
-@item C-c C-t
-@kindex C-c C-t @r{(GUD)}
-@itemx C-x C-a C-t
-@findex gud-tbreak
-Set a temporary breakpoint on the current source line, if any
-(@code{gud-tbreak}). If you use this command in the GUD interaction
-buffer, it applies to the line where the program last stopped.
-
-@item C-c <
-@kindex C-c < @r{(GUD)}
-@itemx C-x C-a <
-@findex gud-up
-Select the next enclosing stack frame (@code{gud-up}). This is
-equivalent to the GDB command @samp{up}.
-
-@item C-c >
-@kindex C-c > @r{(GUD)}
-@itemx C-x C-a >
-@findex gud-down
-Select the next inner stack frame (@code{gud-down}). This is
-equivalent to the GDB command @samp{down}.
-
-@item C-c C-u
-@kindex C-c C-u @r{(GUD)}
-@itemx C-x C-a C-u
-@findex gud-until
-Continue execution to the current line (@code{gud-until}). The
-program will run until it hits a breakpoint, terminates, gets a signal
-that the debugger is checking for, or reaches the line on which the
-cursor currently sits.
-
-@item C-c C-f
-@kindex C-c C-f @r{(GUD)}
-@itemx C-x C-a C-f
-@findex gud-finish
-Run the program until the selected stack frame returns or
-stops for some other reason (@code{gud-finish}).
-@end table
-
- If you are using GDB, these additional key bindings are available:
-
-@table @kbd
-@item C-x C-a C-j
-@kindex C-x C-a C-j @r{(GUD)}
-@findex gud-jump
-Only useful in a source buffer, @code{gud-jump} transfers the
-program's execution point to the current line. In other words, the
-next line that the program executes will be the one where you gave the
-command. If the new execution line is in a different function from
-the previously one, GDB prompts for confirmation since the results may
-be bizarre. See the GDB manual entry regarding @code{jump} for
-details.
-
-@item @key{TAB}
-@kindex TAB @r{(GUD)}
-@findex gud-gdb-complete-command
-With GDB, complete a symbol name (@code{gud-gdb-complete-command}).
-This key is available only in the GUD interaction buffer.
-@end table
-
- These commands interpret a numeric argument as a repeat count, when
-that makes sense.
-
- Because @key{TAB} serves as a completion command, you can't use it to
-enter a tab as input to the program you are debugging with GDB.
-Instead, type @kbd{C-q @key{TAB}} to enter a tab.
-
-@node GUD Customization
-@subsection GUD Customization
-
-@vindex gdb-mode-hook
-@vindex dbx-mode-hook
-@vindex sdb-mode-hook
-@vindex xdb-mode-hook
-@vindex perldb-mode-hook
-@vindex pdb-mode-hook
-@vindex jdb-mode-hook
- On startup, GUD runs one of the following hooks: @code{gdb-mode-hook},
-if you are using GDB; @code{dbx-mode-hook}, if you are using DBX;
-@code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you
-are using XDB; @code{perldb-mode-hook}, for Perl debugging mode;
-@code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can
-use these hooks to define custom key bindings for the debugger
-interaction buffer. @xref{Hooks}.
-
- Here is a convenient way to define a command that sends a particular
-command string to the debugger, and set up a key binding for it in the
-debugger interaction buffer:
-
-@findex gud-def
-@example
-(gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring})
-@end example
-
- This defines a command named @var{function} which sends
-@var{cmdstring} to the debugger process, and gives it the documentation
-string @var{docstring}. You can then use the command @var{function} in any
-buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds
-the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to
-@kbd{C-x C-a @var{binding}} generally.
-
- The command string @var{cmdstring} may contain certain
-@samp{%}-sequences that stand for data to be filled in at the time
-@var{function} is called:
-
-@table @samp
-@item %f
-The name of the current source file. If the current buffer is the GUD
-buffer, then the ``current source file'' is the file that the program
-stopped in.
-
-@item %l
-The number of the current source line. If the current buffer is the GUD
-buffer, then the ``current source line'' is the line that the program
-stopped in.
-
-@item %e
-In transient-mark-mode the text in the region, if it is active.
-Otherwise the text of the C lvalue or function-call expression at or
-adjacent to point.
-
-@item %a
-The text of the hexadecimal address at or adjacent to point.
-
-@item %p
-The numeric argument of the called function, as a decimal number. If
-the command is used without a numeric argument, @samp{%p} stands for the
-empty string.
-
-If you don't use @samp{%p} in the command string, the command you define
-ignores any numeric argument.
-
-@item %d
-The name of the directory of the current source file.
-
-@item %c
-Fully qualified class name derived from the expression surrounding point
-(jdb only).
-@end table
-
-@node GDB Graphical Interface
-@subsection GDB Graphical Interface
-
- By default, the command @code{gdb} starts GDB using a graphical
-interface, using Emacs windows for display program state information.
-In effect, this makes Emacs into an IDE (interactive development
-environment). With it, you do not need to use textual GDB commands;
-you can control the debugging session with the mouse. For example,
-you can click in the fringe of a source buffer to set a breakpoint
-there, or on a stack frame in the stack buffer to select that frame.
-
- This mode requires telling GDB that its ``screen size'' is
-unlimited, so it sets the height and width accordingly. For correct
-operation you must not change these values during the GDB session.
-
-@vindex gud-gdb-command-name
-@findex gdba
- You can also run GDB in text command mode, like other debuggers. To
-do this, replace the GDB @code{"--annotate=3"} option with
-@code{"--fullname"} either in the minibuffer for the current Emacs
-session, or the custom variable @code{gud-gdb-command-name} for all
-future sessions. You need to use text command mode to debug multiple
-programs within one Emacs session. If you have customized
-@code{gud-gdb-command-name} in this way, you can use @kbd{M-x gdba} to
-invoke GDB in graphical mode. Moreover, this command succeeds where
-@kbd{M-x gdb} fails, such as when your @file{.gdbinit} file contains
-executable GDB commands.
-
-@menu
-* GDB-UI Layout:: Control the number of displayed buffers.
-* Source Buffers:: Use the mouse in the fringe/margin to
- control your program.
-* Breakpoints Buffer:: A breakpoint control panel.
-* Stack Buffer:: Select a frame from the call stack.
-* Other GDB-UI Buffers:: Input/output, locals, registers,
- assembler, threads and memory buffers.
-* Watch Expressions:: Monitor variable values in the speedbar.
-@end menu
-
-@node GDB-UI Layout
-@subsubsection GDB User Interface Layout
-@cindex GDB User Interface layout
-
-@vindex gdb-many-windows
- If the variable @code{gdb-many-windows} is @code{nil} (the default
-value) then @kbd{M-x gdb} normally displays only the GUD buffer.
-However, if the variable @code{gdb-show-main} is also non-@code{nil},
-it starts with two windows: one displaying the GUD buffer, and the
-other showing the source for the @code{main} function of the program
-you are debugging.
-
- If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb}
-displays the following frame layout:
-
-@smallexample
-@group
-+--------------------------------+--------------------------------+
-| GUD buffer (I/O of GDB) | Locals buffer |
-|--------------------------------+--------------------------------+
-| Primary Source buffer | I/O buffer for debugged pgm |
-|--------------------------------+--------------------------------+
-| Stack buffer | Breakpoints buffer |
-+--------------------------------+--------------------------------+
-@end group
-@end smallexample
-
- However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O
-buffer does not appear and the primary source buffer occupies the full
-width of the frame.
-
-@findex gdb-restore-windows
- If you change the window layout, for example, while editing and
-re-compiling your program, then you can restore this standard window
-layout with the command @code{gdb-restore-windows}.
-
-@findex gdb-many-windows
- To switch between this standard layout and a simple layout
-containing just the GUD buffer and a source file, type @kbd{M-x
-gdb-many-windows}.
-
- You may also specify additional GDB-related buffers to display,
-either in the same frame or a different one. Select the buffers you
-want with the @samp{GUD->GDB-windows} and @samp{GUD->GDB-Frames}
-sub-menus. If the menu-bar is unavailable, type @code{M-x
-gdb-display-@var{buffertype}-buffer} or @code{M-x
-gdb-frame-@var{buffertype}-buffer} respectively, where
-@var{buffertype} is the relevant buffer type, such as
-@samp{breakpoints}. Most of these buffers are read-only, and typing
-@kbd{q} in them kills them.
-
- When you finish debugging, kill the GUD buffer with @kbd{C-x k},
-which will also kill all the buffers associated with the session.
-However you need not do this if, after editing and re-compiling your
-source code within Emacs, you wish continue debugging. When you
-restart execution, GDB will automatically find your new executable.
-Keeping the GUD buffer has the advantage of keeping the shell history
-as well as GDB's breakpoints. You do need to check that the
-breakpoints in recently edited source files are still in the right
-places.
-
-@node Source Buffers
-@subsubsection Source Buffers
-@cindex GDB commands in Fringe
-
-@c @findex gdb-mouse-set-clear-breakpoint
-@c @findex gdb-mouse-toggle-breakpoint
-Many GDB commands can be entered using keybindings or the tool bar but
-sometimes it is quicker to use the fringe. These commands either
-manipulate breakpoints or control program execution. When there is no
-fringe, you can use the margin but this is only present when the
-source file already has a breakpoint.
-
-You can click @kbd{Mouse-1} in the fringe or display margin of a
-source buffer to set a breakpoint there and, on a graphical display, a
-red bullet will appear on that line. If a breakpoint already exists
-on that line, the same click will remove it. You can also enable or
-disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet.
-
-A solid arrow in the left fringe of a source buffer indicates the line
-of the innermost frame where the debugged program has stopped. A
-hollow arrow indicates the current execution line of higher level
-frames.
-
-If you drag the arrow in the fringe with @kbd{Mouse-1}
-(@code{gdb-mouse-until}), execution will continue to the line where
-you release the button, provided it is still in the same frame.
-Alternatively, you can click @kbd{Mouse-3} at some point in the fringe
-of this buffer and execution will advance to there. A similar command
-(@code{gdb-mouse-jump}) allows you to jump to a source line without
-executing the intermediate lines by clicking @kbd{C-Mouse-3}. This
-command allows you to go backwards which can be useful for running
-through code that has already executed, in order to examine its
-execution in more detail.
-
-@table @kbd
-@item Mouse-1
-Set or clear a breakpoint.
-
-@item C-Mouse-1
-Enable or disable a breakpoint.
-
-@item Mouse-3
-Continue execution to here.
-
-@item C-Mouse-3
-Jump to here.
-@end table
-
-If the variable @code{gdb-find-source-frame} is non-@code{nil} and
-execution stops in a frame for which there is no source code e.g after
-an interrupt, then Emacs finds and displays the first frame further up
-stack for which there is source. If it is @code{nil} then the source
-buffer continues to display the last frame which maybe more useful,
-for example, when re-setting a breakpoint.
-
-@node Breakpoints Buffer
-@subsubsection Breakpoints Buffer
-
- The breakpoints buffer shows the existing breakpoints, watchpoints and
-catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has
-these special commands, which mostly apply to the @dfn{current
-breakpoint}, the breakpoint which point is on.
-
-@table @kbd
-@item @key{SPC}
-@kindex SPC @r{(GDB breakpoints buffer)}
-@findex gdb-toggle-breakpoint
-Enable/disable the current breakpoint (@code{gdb-toggle-breakpoint}).
-On a graphical display, this changes the color of a bullet in the
-margin of a source buffer at the relevant line. This is red when
-the breakpoint is enabled and grey when it is disabled. Text-only
-terminals correspondingly display a @samp{B} or @samp{b}.
-
-@item D
-@kindex D @r{(GDB breakpoints buffer)}
-@findex gdb-delete-breakpoint
-Delete the current breakpoint (@code{gdb-delete-breakpoint}).
-
-@item @key{RET}
-@kindex RET @r{(GDB breakpoints buffer)}
-@findex gdb-goto-breakpoint
-Visit the source line for the current breakpoint
-(@code{gdb-goto-breakpoint}).
-
-@item Mouse-2
-@kindex Mouse-2 @r{(GDB breakpoints buffer)}
-Visit the source line for the breakpoint you click on.
-@end table
-
-@node Stack Buffer
-@subsubsection Stack Buffer
-
- The stack buffer displays a @dfn{call stack}, with one line for each
-of the nested subroutine calls (@dfn{stack frames}) now active in the
-program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}.
-
-@findex gdb-frames-select
-An arrow in the fringe points to the selected frame or, if the fringe is
-not present, the number of the selected frame is displayed in reverse
-contrast. To select a frame in GDB, move point in the stack buffer to
-that stack frame and type @key{RET} (@code{gdb-frames-select}), or click
-@kbd{Mouse-2} on a stack frame. If the locals buffer is visible,
-selecting a stack frame updates it to display the local variables of the
-new frame.
-
-@node Other GDB-UI Buffers
-@subsubsection Other Buffers
-
-@table @asis
-@item Input/Output Buffer
-@vindex gdb-use-separate-io-buffer
-If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil},
-the program being debugged takes its input and displays its output
-here. Otherwise it uses the GUD buffer for that. To toggle whether
-GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}.
-This takes effect when you next restart the program you are debugging.
-
-The history and replay commands from Shell mode are available here,
-as are the commands to send signals to the debugged program.
-@xref{Shell Mode}.
-
-@item Locals Buffer
-The locals buffer displays the values of local variables of the
-current frame for simple data types (@pxref{Frame Info, Frame Info,
-Information on a frame, gdb, The GNU debugger}). Press @key{RET} or
-click @kbd{Mouse-2} on the value if you want to edit it.
-
-Arrays and structures display their type only. With GDB 6.4 or later,
-move point to their name and press @key{RET}, or alternatively click
-@kbd{Mouse-2} there, to examine their values. With earlier versions
-of GDB, use @kbd{Mouse-2} or @key{RET} on the type description
-(@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}.
-
-@item Registers Buffer
-@findex toggle-gdb-all-registers
-The registers buffer displays the values held by the registers
-(@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or
-click @kbd{Mouse-2} on a register if you want to edit its value.
-With GDB 6.4 or later, recently changed register values display with
-@code{font-lock-warning-face}. With earlier versions of GDB, you can
-press @key{SPC} to toggle the display of floating point registers
-(@code{toggle-gdb-all-registers}).
-
-@item Assembler Buffer
-The assembler buffer displays the current frame as machine code. An
-arrow points to the current instruction, and you can set and remove
-breakpoints as in a source buffer. Breakpoint icons also appear in
-the fringe or margin.
-
-@item Threads Buffer
-@findex gdb-threads-select
-The threads buffer displays a summary of all threads currently in your
-program (@pxref{Threads, Threads, Debugging programs with multiple
-threads, gdb, The GNU debugger}). Move point to any thread in the
-list and press @key{RET} to select it (@code{gdb-threads-select}) and
-display the associated source in the primary source buffer.
-Alternatively, click @kbd{Mouse-2} on a thread to select it. If the
-locals buffer is visible, its contents update to display the variables
-that are local in the new thread.
-
-@item Memory Buffer
-The memory buffer lets you examine sections of program memory
-(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}).
-Click @kbd{Mouse-1} on the appropriate part of the header line to
-change the starting address or number of data items that the buffer
-displays. Click @kbd{Mouse-3} on the header line to select the
-display format or unit size for these data items.
-@end table
-
-@node Watch Expressions
-@subsubsection Watch Expressions
-@cindex Watching expressions in GDB
-
-@findex gud-watch
-@kindex C-x C-a C-w @r{(GUD)}
- If you want to see how a variable changes each time your program
-stops, move point into the variable name and click on the watch icon
-in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you
-specify a prefix argument, you can enter the variable name in the
-minibuffer.
-
- Each watch expression is displayed in the speedbar. Complex data
-types, such as arrays, structures and unions are represented in a tree
-format. Leaves and simple data types show the name of the expression
-and its value and, when the speedbar frame is selected, display the
-type as a tooltip. Higher levels show the name, type and address
-value for pointers and just the name and type otherwise. Root expressions
-also display the frame address as a tooltip to help identify the frame
-in which they were defined.
-
- To expand or contract a complex data type, click @kbd{Mouse-2} or
-press @key{SPC} on the tag to the left of the expression. Emacs asks
-for confirmation before expanding the expression if its number of
-immediate children exceeds the value of the variable
-@code{gdb-max-children}.
-
-@kindex D @r{(GDB speedbar)}
-@findex gdb-var-delete
- To delete a complex watch expression, move point to the root
-expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}).
-
-@kindex RET @r{(GDB speedbar)}
-@findex gdb-edit-value
- To edit a variable with a simple data type, or a simple element of a
-complex data type, move point there in the speedbar and type @key{RET}
-(@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to
-edit it. Either way, this reads the new value using the minibuffer.
-
-@vindex gdb-show-changed-values
- If you set the variable @code{gdb-show-changed-values} to
-non-@code{nil} (the default value), Emacs uses
-@code{font-lock-warning-face} to highlight values that have recently
-changed and @code{shadow} face to make variables which have gone out of
-scope less noticeable. When a variable goes out of scope you can't
-edit its value.
-
-@vindex gdb-use-colon-colon-notation
- If the variable @code{gdb-use-colon-colon-notation} is
-non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}}
-format. This allows the user to display watch expressions which share
-the same variable name. The default value is @code{nil}.
-
-@vindex gdb-speedbar-auto-raise
-To automatically raise the speedbar every time the display of watch
-expressions updates, set @code{gdb-speedbar-auto-raise} to
-non-@code{nil}. This can be useful if you are debugging with a full
-screen Emacs frame.
-
-@node Executing Lisp
-@section Executing Lisp Expressions
-
- Emacs has several different major modes for Lisp and Scheme. They are
-the same in terms of editing commands, but differ in the commands for
-executing Lisp expressions. Each mode has its own purpose.
-
-@table @asis
-@item Emacs-Lisp mode
-The mode for editing source files of programs to run in Emacs Lisp.
-This mode defines @kbd{C-M-x} to evaluate the current defun.
-@xref{Lisp Libraries}.
-@item Lisp Interaction mode
-The mode for an interactive session with Emacs Lisp. It defines
-@kbd{C-j} to evaluate the sexp before point and insert its value in the
-buffer. @xref{Lisp Interaction}.
-@item Lisp mode
-The mode for editing source files of programs that run in Lisps other
-than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun
-to an inferior Lisp process. @xref{External Lisp}.
-@item Inferior Lisp mode
-The mode for an interactive session with an inferior Lisp process.
-This mode combines the special features of Lisp mode and Shell mode
-(@pxref{Shell Mode}).
-@item Scheme mode
-Like Lisp mode but for Scheme programs.
-@item Inferior Scheme mode
-The mode for an interactive session with an inferior Scheme process.
-@end table
-
- Most editing commands for working with Lisp programs are in fact
-available globally. @xref{Programs}.
-
-@node Lisp Libraries
-@section Libraries of Lisp Code for Emacs
-@cindex libraries
-@cindex loading Lisp code
-
- Lisp code for Emacs editing commands is stored in files whose names
-conventionally end in @file{.el}. This ending tells Emacs to edit them in
-Emacs-Lisp mode (@pxref{Executing Lisp}).
-
-@cindex byte code
- Emacs Lisp code can be compiled into byte-code, which loads faster,
-takes up less space, and executes faster. @xref{Byte Compilation,,
-Byte Compilation, elisp, the Emacs Lisp Reference Manual}. By
-convention, the compiled code for a library goes in a separate file
-whose name ends in @samp{.elc}. Thus, the compiled code for
-@file{foo.el} goes in @file{foo.elc}.
-
-@findex load-file
- To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. This
-command reads a file name using the minibuffer and then executes the
-contents of that file as Lisp code. It is not necessary to visit the
-file first; in any case, this command reads the file as found on disk,
-not text in an Emacs buffer.
-
-@findex load
-@findex load-library
- Once a file of Lisp code is installed in the Emacs Lisp library
-directories, users can load it using @kbd{M-x load-library}. Programs
-can load it by calling @code{load}, a more primitive function that is
-similar but accepts some additional arguments.
-
- @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it
-searches a sequence of directories and tries three file names in each
-directory. Suppose your argument is @var{lib}; the three names are
-@file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just
-@file{@var{lib}}. If @file{@var{lib}.elc} exists, it is by convention
-the result of compiling @file{@var{lib}.el}; it is better to load the
-compiled file, since it will load and run faster.
-
- If @code{load-library} finds that @file{@var{lib}.el} is newer than
-@file{@var{lib}.elc} file, it issues a warning, because it's likely
-that somebody made changes to the @file{.el} file and forgot to
-recompile it. Nonetheless, it loads @file{@var{lib}.elc}. This is
-because people often leave unfinished edits the source file, and don't
-recompile it until they think it is ready to use.
-
- Because the argument to @code{load-library} is usually not in itself
-a valid file name, file name completion is not available. Indeed, when
-using this command, you usually do not know exactly what file name
-will be used.
-
-@vindex load-path
- The sequence of directories searched by @kbd{M-x load-library} is
-specified by the variable @code{load-path}, a list of strings that are
-directory names. The default value of the list contains the directories where
-the Lisp code for Emacs itself is stored. If you have libraries of
-your own, put them in a single directory and add that directory
-to @code{load-path}. @code{nil} in this list stands for the current default
-directory, but it is probably not a good idea to put @code{nil} in the
-list. If you find yourself wishing that @code{nil} were in the list,
-most likely what you really want to do is use @kbd{M-x load-file}
-this once.
-
-@cindex autoload
- Often you do not have to give any command to load a library, because
-the commands defined in the library are set up to @dfn{autoload} that
-library. Trying to run any of those commands calls @code{load} to load
-the library; this replaces the autoload definitions with the real ones
-from the library.
-
-@vindex load-dangerous-libraries
-@cindex Lisp files byte-compiled by XEmacs
- By default, Emacs refuses to load compiled Lisp files which were
-compiled with XEmacs, a modified versions of Emacs---they can cause
-Emacs to crash. Set the variable @code{load-dangerous-libraries} to
-@code{t} if you want to try loading them.
-
-@node Lisp Eval
-@section Evaluating Emacs Lisp Expressions
-@cindex Emacs-Lisp mode
-@cindex mode, Emacs-Lisp
-
-@findex emacs-lisp-mode
- Lisp programs intended to be run in Emacs should be edited in
-Emacs-Lisp mode; this happens automatically for file names ending in
-@file{.el}. By contrast, Lisp mode itself is used for editing Lisp
-programs intended for other Lisp systems. To switch to Emacs-Lisp mode
-explicitly, use the command @kbd{M-x emacs-lisp-mode}.
-
- For testing of Lisp programs to run in Emacs, it is often useful to
-evaluate part of the program as it is found in the Emacs buffer. For
-example, after changing the text of a Lisp function definition,
-evaluating the definition installs the change for future calls to the
-function. Evaluation of Lisp expressions is also useful in any kind of
-editing, for invoking noninteractive functions (functions that are
-not commands).
-
-@table @kbd
-@item M-:
-Read a single Lisp expression in the minibuffer, evaluate it, and print
-the value in the echo area (@code{eval-expression}).
-@item C-x C-e
-Evaluate the Lisp expression before point, and print the value in the
-echo area (@code{eval-last-sexp}).
-@item C-M-x
-Evaluate the defun containing or after point, and print the value in
-the echo area (@code{eval-defun}).
-@item M-x eval-region
-Evaluate all the Lisp expressions in the region.
-@item M-x eval-buffer
-Evaluate all the Lisp expressions in the buffer.
-@end table
-
-@ifinfo
-@c This uses ``colon'' instead of a literal `:' because Info cannot
-@c cope with a `:' in a menu
-@kindex M-@key{colon}
-@end ifinfo
-@ifnotinfo
-@kindex M-:
-@end ifnotinfo
-@findex eval-expression
- @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating
-a Lisp expression interactively. It reads the expression using the
-minibuffer, so you can execute any expression on a buffer regardless of
-what the buffer contains. When the expression is evaluated, the current
-buffer is once again the buffer that was current when @kbd{M-:} was
-typed.
-
-@kindex C-M-x @r{(Emacs-Lisp mode)}
-@findex eval-defun
- In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command
-@code{eval-defun}, which parses the defun containing or following point
-as a Lisp expression and evaluates it. The value is printed in the echo
-area. This command is convenient for installing in the Lisp environment
-changes that you have just made in the text of a function definition.
-
- @kbd{C-M-x} treats @code{defvar} expressions specially. Normally,
-evaluating a @code{defvar} expression does nothing if the variable it
-defines already has a value. But @kbd{C-M-x} unconditionally resets the
-variable to the initial value specified in the @code{defvar} expression.
-@code{defcustom} expressions are treated similarly.
-This special feature is convenient for debugging Lisp programs.
-Typing @kbd{C-M-x} on a @code{defface} expression reinitializes
-the face according to the @code{defface} specification.
-
-@kindex C-x C-e
-@findex eval-last-sexp
- The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp
-expression preceding point in the buffer, and displays the value in the
-echo area. It is available in all major modes, not just Emacs-Lisp
-mode. It does not treat @code{defvar} specially.
-
- When the result of an evaluation is an integer, you can type
-@kbd{C-x C-e} a second time to display the value of the integer result
-in additional formats (octal, hexadecimal, and character).
-
- If @kbd{C-x C-e}, or @kbd{M-:} is given a numeric argument, it
-inserts the value into the current buffer at point, rather than
-displaying it in the echo area. The argument's value does not matter.
-@kbd{C-M-x} with a numeric argument instruments the function
-definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}).
-
-@findex eval-region
-@findex eval-buffer
- The most general command for evaluating Lisp expressions from a buffer
-is @code{eval-region}. @kbd{M-x eval-region} parses the text of the
-region as one or more Lisp expressions, evaluating them one by one.
-@kbd{M-x eval-buffer} is similar but evaluates the entire
-buffer. This is a reasonable way to install the contents of a file of
-Lisp code that you are ready to test. Later, as you find bugs and
-change individual functions, use @kbd{C-M-x} on each function that you
-change. This keeps the Lisp world in step with the source file.
-
-@vindex eval-expression-print-level
-@vindex eval-expression-print-length
-@vindex eval-expression-debug-on-error
- The two customizable variables @code{eval-expression-print-level} and
-@code{eval-expression-print-length} control the maximum depth and length
-of lists to print in the result of the evaluation commands before
-abbreviating them. @code{eval-expression-debug-on-error} controls
-whether evaluation errors invoke the debugger when these commands are
-used; its default is @code{t}.
-
-@node Lisp Interaction
-@section Lisp Interaction Buffers
-
- The buffer @samp{*scratch*} which is selected when Emacs starts up is
-provided for evaluating Lisp expressions interactively inside Emacs.
-
- The simplest way to use the @samp{*scratch*} buffer is to insert Lisp
-expressions and type @kbd{C-j} after each expression. This command
-reads the Lisp expression before point, evaluates it, and inserts the
-value in printed representation before point. The result is a complete
-typescript of the expressions you have evaluated and their values.
-
- The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which
-is the same as Emacs-Lisp mode except for the binding of @kbd{C-j}.
-
-@findex lisp-interaction-mode
- The rationale for this feature is that Emacs must have a buffer when
-it starts up, but that buffer is not useful for editing files since a
-new buffer is made for every file that you visit. The Lisp interpreter
-typescript is the most useful thing I can think of for the initial
-buffer to do. Type @kbd{M-x lisp-interaction-mode} to put the current
-buffer in Lisp Interaction mode.
-
-@findex ielm
- An alternative way of evaluating Emacs Lisp expressions interactively
-is to use Inferior Emacs-Lisp mode, which provides an interface rather
-like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp
-expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer
-which uses this mode. For more information see that command's
-documentation.
-
-@node External Lisp
-@section Running an External Lisp
-
- Emacs has facilities for running programs in other Lisp systems. You can
-run a Lisp process as an inferior of Emacs, and pass expressions to it to
-be evaluated. You can also pass changed function definitions directly from
-the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
-process.
-
-@findex run-lisp
-@vindex inferior-lisp-program
-@kindex C-x C-z
- To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs
-the program named @code{lisp}, the same program you would run by typing
-@code{lisp} as a shell command, with both input and output going through
-an Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal
-output'' from Lisp will go into the buffer, advancing point, and any
-``terminal input'' for Lisp comes from text in the buffer. (You can
-change the name of the Lisp executable file by setting the variable
-@code{inferior-lisp-program}.)
-
- To give input to Lisp, go to the end of the buffer and type the input,
-terminated by @key{RET}. The @samp{*lisp*} buffer is in Inferior Lisp
-mode, which combines the special characteristics of Lisp mode with most
-of the features of Shell mode (@pxref{Shell Mode}). The definition of
-@key{RET} to send a line to a subprocess is one of the features of Shell
-mode.
-
-@findex lisp-mode
- For the source files of programs to run in external Lisps, use Lisp
-mode. You can switch to this mode with @kbd{M-x lisp-mode}, and it is
-used automatically for files whose names end in @file{.l},
-@file{.lsp}, or @file{.lisp}.
-
-@kindex C-M-x @r{(Lisp mode)}
-@findex lisp-eval-defun
- When you edit a function in a Lisp program you are running, the easiest
-way to send the changed definition to the inferior Lisp process is the key
-@kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-eval-defun},
-which finds the defun around or following point and sends it as input to
-the Lisp process. (Emacs can send input to any inferior process regardless
-of what buffer is current.)
-
- Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing
-programs to be run in another Lisp system) and Emacs-Lisp mode (for
-editing Lisp programs to be run in Emacs; see @pxref{Lisp Eval}): in
-both modes it has the effect of installing the function definition
-that point is in, but the way of doing so is different according to
-where the relevant Lisp environment is found.
-
-
-@ignore
- arch-tag: 9c3c2f71-b332-4144-8500-3ff9945a50ed
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@c
-@c This file is included either in emacs-xtra.texi (when producing the
-@c printed version) or in the main Emacs manual (for the on-line version).
-
-@c Moved here from the Emacs Lisp Reference Manual, 2005-03-26.
-@node Advanced Calendar/Diary Usage
-@section Customizing the Calendar and Diary
-
- There are many customizations that you can use to make the calendar and
-diary suit your personal tastes.
-
-@menu
-* Calendar Customizing:: Defaults you can set.
-* Holiday Customizing:: Defining your own holidays.
-* Date Display Format:: Changing the format.
-* Time Display Format:: Changing the format.
-* Diary Customizing:: Defaults you can set.
-* Hebrew/Islamic Entries:: How to obtain them.
-* Fancy Diary Display:: Enhancing the diary display, sorting entries,
- using included diary files.
-* Sexp Diary Entries:: Fancy things you can do.
-@end menu
-
-@node Calendar Customizing
-@subsection Customizing the Calendar
-@vindex calendar-holiday-marker
-@vindex diary-entry-marker
- The variable @code{calendar-holiday-marker} specifies how to mark a
-date as being a holiday. Its value may be a single-character string
-to insert next to the date, or a face name to use for displaying the
-date. Likewise, the variable @code{diary-entry-marker} specifies how
-to mark a date that has diary entries. The calendar creates faces
-named @code{holiday-face} and @code{diary-face} for these purposes;
-those symbols are the default values of these variables.
-
-@vindex calendar-load-hook
- The variable @code{calendar-load-hook} is a normal hook run when the
-calendar package is first loaded (before actually starting to display
-the calendar).
-
-@vindex initial-calendar-window-hook
- Starting the calendar runs the normal hook
-@code{initial-calendar-window-hook}. Recomputation of the calendar
-display does not run this hook. But if you leave the calendar with the
-@kbd{q} command and reenter it, the hook runs again.@refill
-
-@vindex today-visible-calendar-hook
- The variable @code{today-visible-calendar-hook} is a normal hook run
-after the calendar buffer has been prepared with the calendar when the
-current date is visible in the window. One use of this hook is to
-replace today's date with asterisks; to do that, use the hook function
-@code{calendar-star-date}.
-
-@findex calendar-star-date
-@example
-(add-hook 'today-visible-calendar-hook 'calendar-star-date)
-@end example
-
-@noindent
-Another standard hook function marks the current date, either by
-changing its face or by adding an asterisk. Here's how to use it:
-
-@findex calendar-mark-today
-@example
-(add-hook 'today-visible-calendar-hook 'calendar-mark-today)
-@end example
-
-@noindent
-@vindex calendar-today-marker
-The variable @code{calendar-today-marker} specifies how to mark
-today's date. Its value should be a single-character string to insert
-next to the date or a face name to use for displaying the date. A
-face named @code{calendar-today-face} is provided for this purpose;
-that symbol is the default for this variable.
-
-@vindex today-invisible-calendar-hook
-@noindent
- A similar normal hook, @code{today-invisible-calendar-hook} is run if
-the current date is @emph{not} visible in the window.
-
-@vindex calendar-move-hook
- Each of the calendar cursor motion commands runs the hook
-@code{calendar-move-hook} after it moves the cursor.
-
-@node Holiday Customizing
-@subsection Customizing the Holidays
-
-@vindex calendar-holidays
-@vindex christian-holidays
-@vindex hebrew-holidays
-@vindex islamic-holidays
- Emacs knows about holidays defined by entries on one of several lists.
-You can customize these lists of holidays to your own needs, adding or
-deleting holidays. The lists of holidays that Emacs uses are for
-general holidays (@code{general-holidays}), local holidays
-(@code{local-holidays}), Christian holidays (@code{christian-holidays}),
-Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Muslim)
-holidays (@code{islamic-holidays}), and other holidays
-(@code{other-holidays}).
-
-@vindex general-holidays
- The general holidays are, by default, holidays common throughout the
-United States. To eliminate these holidays, set @code{general-holidays}
-to @code{nil}.
-
-@vindex local-holidays
- There are no default local holidays (but sites may supply some). You
-can set the variable @code{local-holidays} to any list of holidays, as
-described below.
-
-@vindex all-christian-calendar-holidays
-@vindex all-hebrew-calendar-holidays
-@vindex all-islamic-calendar-holidays
- By default, Emacs does not include all the holidays of the religions
-that it knows, only those commonly found in secular calendars. For a
-more extensive collection of religious holidays, you can set any (or
-all) of the variables @code{all-christian-calendar-holidays},
-@code{all-hebrew-calendar-holidays}, or
-@code{all-islamic-calendar-holidays} to @code{t}. If you want to
-eliminate the religious holidays, set any or all of the corresponding
-variables @code{christian-holidays}, @code{hebrew-holidays}, and
-@code{islamic-holidays} to @code{nil}.@refill
-
-@vindex other-holidays
- You can set the variable @code{other-holidays} to any list of
-holidays. This list, normally empty, is intended for individual use.
-
-@cindex holiday forms
- Each of the lists (@code{general-holidays}, @code{local-holidays},
-@code{christian-holidays}, @code{hebrew-holidays},
-@code{islamic-holidays}, and @code{other-holidays}) is a list of
-@dfn{holiday forms}, each holiday form describing a holiday (or
-sometimes a list of holidays).
-
- Here is a table of the possible kinds of holiday form. Day numbers
-and month numbers count starting from 1, but ``dayname'' numbers
-count Sunday as 0. The element @var{string} is always the
-name of the holiday, as a string.
-
-@table @code
-@item (holiday-fixed @var{month} @var{day} @var{string})
-A fixed date on the Gregorian calendar.
-
-@item (holiday-float @var{month} @var{dayname} @var{k} @var{string})
-The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar
-(@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back
-from the end of the month.
-
-@item (holiday-hebrew @var{month} @var{day} @var{string})
-A fixed date on the Hebrew calendar.
-
-@item (holiday-islamic @var{month} @var{day} @var{string})
-A fixed date on the Islamic calendar.
-
-@item (holiday-julian @var{month} @var{day} @var{string})
-A fixed date on the Julian calendar.
-
-@item (holiday-sexp @var{sexp} @var{string})
-A date calculated by the Lisp expression @var{sexp}. The expression
-should use the variable @code{year} to compute and return the date of a
-holiday, or @code{nil} if the holiday doesn't happen this year. The
-value of @var{sexp} must represent the date as a list of the form
-@code{(@var{month} @var{day} @var{year})}.
-
-@item (if @var{condition} @var{holiday-form})
-A holiday that happens only if @var{condition} is true.
-
-@item (@var{function} @r{[}@var{args}@r{]})
-A list of dates calculated by the function @var{function}, called with
-arguments @var{args}.
-@end table
-
- For example, suppose you want to add Bastille Day, celebrated in
-France on July 14. You can do this as follows:
-
-@smallexample
-(setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
-@end smallexample
-
-@noindent
-The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the
-fourteenth day of the seventh month (July).
-
- Many holidays occur on a specific day of the week, at a specific time
-of month. Here is a holiday form describing Hurricane Supplication Day,
-celebrated in the Virgin Islands on the fourth Monday in August:
-
-@smallexample
-(holiday-float 8 1 4 "Hurricane Supplication Day")
-@end smallexample
-
-@noindent
-Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
-Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
-the month (1 specifies the first occurrence, 2 the second occurrence,
-@minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and
-so on).
-
- You can specify holidays that occur on fixed days of the Hebrew,
-Islamic, and Julian calendars too. For example,
-
-@smallexample
-(setq other-holidays
- '((holiday-hebrew 10 2 "Last day of Hanukkah")
- (holiday-islamic 3 12 "Mohammed's Birthday")
- (holiday-julian 4 2 "Jefferson's Birthday")))
-@end smallexample
-
-@noindent
-adds the last day of Hanukkah (since the Hebrew months are numbered with
-1 starting from Nisan), the Islamic feast celebrating Mohammed's
-birthday (since the Islamic months are numbered from 1 starting with
-Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
-Julian calendar.
-
- To include a holiday conditionally, use either Emacs Lisp's @code{if} or the
-@code{holiday-sexp} form. For example, American presidential elections
-occur on the first Tuesday after the first Monday in November of years
-divisible by 4:
-
-@smallexample
-(holiday-sexp '(if (= 0 (% year 4))
- (calendar-gregorian-from-absolute
- (1+ (calendar-dayname-on-or-before
- 1 (+ 6 (calendar-absolute-from-gregorian
- (list 11 1 year)))))))
- "US Presidential Election")
-@end smallexample
-
-@noindent
-or
-
-@smallexample
-(if (= 0 (% displayed-year 4))
- (fixed 11
- (extract-calendar-day
- (calendar-gregorian-from-absolute
- (1+ (calendar-dayname-on-or-before
- 1 (+ 6 (calendar-absolute-from-gregorian
- (list 11 1 displayed-year)))))))
- "US Presidential Election"))
-@end smallexample
-
- Some holidays just don't fit into any of these forms because special
-calculations are involved in their determination. In such cases you
-must write a Lisp function to do the calculation. To include eclipses,
-for example, add @code{(eclipses)} to @code{other-holidays}
-and write an Emacs Lisp function @code{eclipses} that returns a
-(possibly empty) list of the relevant Gregorian dates among the range
-visible in the calendar window, with descriptive strings, like this:
-
-@smallexample
-(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
-@end smallexample
-
-@node Date Display Format
-@subsection Date Display Format
-@vindex calendar-date-display-form
-
- You can customize the manner of displaying dates in the diary, in mode
-lines, and in messages by setting @code{calendar-date-display-form}.
-This variable holds a list of expressions that can involve the variables
-@code{month}, @code{day}, and @code{year}, which are all numbers in
-string form, and @code{monthname} and @code{dayname}, which are both
-alphabetic strings. In the American style, the default value of this
-list is as follows:
-
-@smallexample
-((if dayname (concat dayname ", ")) monthname " " day ", " year)
-@end smallexample
-
-@noindent
-while in the European style this value is the default:
-
-@smallexample
-((if dayname (concat dayname ", ")) day " " monthname " " year)
-@end smallexample
-
-@noindent
-The ISO standard date representation is this:
-
-@smallexample
-(year "-" month "-" day)
-@end smallexample
-
-@noindent
-This specifies a typical American format:
-
-@smallexample
-(month "/" day "/" (substring year -2))
-@end smallexample
-
-@node Time Display Format
-@subsection Time Display Format
-@vindex calendar-time-display-form
-
- The calendar and diary by default display times of day in the
-conventional American style with the hours from 1 through 12, minutes,
-and either @samp{am} or @samp{pm}. If you prefer the European style,
-also known in the US as military, in which the hours go from 00 to 23,
-you can alter the variable @code{calendar-time-display-form}. This
-variable is a list of expressions that can involve the variables
-@code{12-hours}, @code{24-hours}, and @code{minutes}, which are all
-numbers in string form, and @code{am-pm} and @code{time-zone}, which are
-both alphabetic strings. The default value of
-@code{calendar-time-display-form} is as follows:
-
-@smallexample
-(12-hours ":" minutes am-pm
- (if time-zone " (") time-zone (if time-zone ")"))
-@end smallexample
-
-@noindent
-Here is a value that provides European style times:
-
-@smallexample
-(24-hours ":" minutes
- (if time-zone " (") time-zone (if time-zone ")"))
-@end smallexample
-
-@node Diary Customizing
-@subsection Customizing the Diary
-
-@vindex holidays-in-diary-buffer
- Ordinarily, the mode line of the diary buffer window indicates any
-holidays that fall on the date of the diary entries. The process of
-checking for holidays can take several seconds, so including holiday
-information delays the display of the diary buffer noticeably. If you'd
-prefer to have a faster display of the diary buffer but without the
-holiday information, set the variable @code{holidays-in-diary-buffer} to
-@code{nil}.@refill
-
-@vindex number-of-diary-entries
- The variable @code{number-of-diary-entries} controls the number of
-days of diary entries to be displayed at one time. It affects the
-initial display when @code{view-diary-entries-initially} is @code{t}, as
-well as the command @kbd{M-x diary}. For example, the default value is
-1, which says to display only the current day's diary entries. If the
-value is 2, both the current day's and the next day's entries are
-displayed. The value can also be a vector of seven elements: for
-example, if the value is @code{[0 2 2 2 2 4 1]} then no diary entries
-appear on Sunday, the current date's and the next day's diary entries
-appear Monday through Thursday, Friday through Monday's entries appear
-on Friday, while on Saturday only that day's entries appear.
-
-@vindex print-diary-entries-hook
-@findex print-diary-entries
- The variable @code{print-diary-entries-hook} is a normal hook run
-after preparation of a temporary buffer containing just the diary
-entries currently visible in the diary buffer. (The other, irrelevant
-diary entries are really absent from the temporary buffer; in the diary
-buffer, they are merely hidden.) The default value of this hook does
-the printing with the command @code{lpr-buffer}. If you want to use a
-different command to do the printing, just change the value of this
-hook. Other uses might include, for example, rearranging the lines into
-order by day and time.
-
-@vindex diary-date-forms
- You can customize the form of dates in your diary file, if neither the
-standard American nor European styles suits your needs, by setting the
-variable @code{diary-date-forms}. This variable is a list of patterns
-for recognizing a date. Each date pattern is a list whose elements may
-be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs
-Lisp Reference Manual}) or the symbols @code{month}, @code{day},
-@code{year}, @code{monthname}, and @code{dayname}. All these elements
-serve as patterns that match certain kinds of text in the diary file.
-In order for the date pattern, as a whole, to match, all of its elements
-must match consecutively.
-
- A regular expression in a date pattern matches in its usual fashion,
-using the standard syntax table altered so that @samp{*} is a word
-constituent.
-
- The symbols @code{month}, @code{day}, @code{year}, @code{monthname},
-and @code{dayname} match the month number, day number, year number,
-month name, and day name of the date being considered. The symbols that
-match numbers allow leading zeros; those that match names allow
-three-letter abbreviations and capitalization. All the symbols can
-match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any
-month'', and so on, it should match regardless of the date being
-considered.
-
- The default value of @code{diary-date-forms} in the American style is
-this:
-
-@example
-((month "/" day "[^/0-9]")
- (month "/" day "/" year "[^0-9]")
- (monthname " *" day "[^,0-9]")
- (monthname " *" day ", *" year "[^0-9]")
- (dayname "\\W"))
-@end example
-
- The date patterns in the list must be @emph{mutually exclusive} and
-must not match any portion of the diary entry itself, just the date and
-one character of whitespace. If, to be mutually exclusive, the pattern
-must match a portion of the diary entry text---beyond the whitespace
-that ends the date---then the first element of the date pattern
-@emph{must} be @code{backup}. This causes the date recognizer to back
-up to the beginning of the current word of the diary entry, after
-finishing the match. Even if you use @code{backup}, the date pattern
-must absolutely not match more than a portion of the first word of the
-diary entry. The default value of @code{diary-date-forms} in the
-European style is this list:
-
-@example
-((day "/" month "[^/0-9]")
- (day "/" month "/" year "[^0-9]")
- (backup day " *" monthname "\\W+\\<[^*0-9]")
- (day " *" monthname " *" year "[^0-9]")
- (dayname "\\W"))
-@end example
-
-@noindent
-Notice the use of @code{backup} in the third pattern, because it needs
-to match part of a word beyond the date itself to distinguish it from
-the fourth pattern.
-
-@node Hebrew/Islamic Entries
-@subsection Hebrew- and Islamic-Date Diary Entries
-
- Your diary file can have entries based on Hebrew or Islamic dates, as
-well as entries based on the world-standard Gregorian calendar.
-However, because recognition of such entries is time-consuming and most
-people don't use them, you must explicitly enable their use. If you
-want the diary to recognize Hebrew-date diary entries, for example,
-you must do this:
-
-@vindex nongregorian-diary-listing-hook
-@vindex nongregorian-diary-marking-hook
-@findex list-hebrew-diary-entries
-@findex mark-hebrew-diary-entries
-@smallexample
-(add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
-(add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
-@end smallexample
-
-@noindent
-If you want Islamic-date entries, do this:
-
-@findex list-islamic-diary-entries
-@findex mark-islamic-diary-entries
-@smallexample
-(add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
-(add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
-@end smallexample
-
- Hebrew- and Islamic-date diary entries have the same formats as
-Gregorian-date diary entries, except that @samp{H} precedes a Hebrew
-date and @samp{I} precedes an Islamic date. Moreover, because the
-Hebrew and Islamic month names are not uniquely specified by the first
-three letters, you may not abbreviate them. For example, a diary entry
-for the Hebrew date Heshvan 25 could look like this:
-
-@smallexample
-HHeshvan 25 Happy Hebrew birthday!
-@end smallexample
-
-@noindent
-and would appear in the diary for any date that corresponds to Heshvan 25
-on the Hebrew calendar. And here is an Islamic-date diary entry that matches
-Dhu al-Qada 25:
-
-@smallexample
-IDhu al-Qada 25 Happy Islamic birthday!
-@end smallexample
-
- As with Gregorian-date diary entries, Hebrew- and Islamic-date entries
-are nonmarking if they are preceded with an ampersand (@samp{&}).
-
- Here is a table of commands used in the calendar to create diary entries
-that match the selected date and other dates that are similar in the Hebrew
-or Islamic calendar:
-
-@table @kbd
-@item i h d
-Add a diary entry for the Hebrew date corresponding to the selected date
-(@code{insert-hebrew-diary-entry}).
-@item i h m
-Add a diary entry for the day of the Hebrew month corresponding to the
-selected date (@code{insert-monthly-hebrew-diary-entry}). This diary
-entry matches any date that has the same Hebrew day-within-month as the
-selected date.
-@item i h y
-Add a diary entry for the day of the Hebrew year corresponding to the
-selected date (@code{insert-yearly-hebrew-diary-entry}). This diary
-entry matches any date which has the same Hebrew month and day-within-month
-as the selected date.
-@item i i d
-Add a diary entry for the Islamic date corresponding to the selected date
-(@code{insert-islamic-diary-entry}).
-@item i i m
-Add a diary entry for the day of the Islamic month corresponding to the
-selected date (@code{insert-monthly-islamic-diary-entry}).
-@item i i y
-Add a diary entry for the day of the Islamic year corresponding to the
-selected date (@code{insert-yearly-islamic-diary-entry}).
-@end table
-
-@findex insert-hebrew-diary-entry
-@findex insert-monthly-hebrew-diary-entry
-@findex insert-yearly-hebrew-diary-entry
-@findex insert-islamic-diary-entry
-@findex insert-monthly-islamic-diary-entry
-@findex insert-yearly-islamic-diary-entry
- These commands work much like the corresponding commands for ordinary
-diary entries: they apply to the date that point is on in the calendar
-window, and what they do is insert just the date portion of a diary entry
-at the end of your diary file. You must then insert the rest of the
-diary entry.
-
-@node Fancy Diary Display
-@subsection Fancy Diary Display
-@vindex diary-display-hook
-@findex simple-diary-display
-
- Diary display works by preparing the diary buffer and then running the
-hook @code{diary-display-hook}. The default value of this hook
-(@code{simple-diary-display}) hides the irrelevant diary entries and
-then displays the buffer. However, if you specify the hook as follows,
-
-@cindex diary buffer
-@findex fancy-diary-display
-@example
-(add-hook 'diary-display-hook 'fancy-diary-display)
-@end example
-
-@noindent
-this enables fancy diary display. It displays diary entries and
-holidays by copying them into a special buffer that exists only for the
-sake of display. Copying to a separate buffer provides an opportunity
-to change the displayed text to make it prettier---for example, to sort
-the entries by the dates they apply to.
-
- As with simple diary display, you can print a hard copy of the buffer
-with @code{print-diary-entries}. To print a hard copy of a day-by-day
-diary for a week, position point on Sunday of that week, type
-@kbd{7 d}, and then do @kbd{M-x print-diary-entries}. As usual, the
-inclusion of the holidays slows down the display slightly; you can speed
-things up by setting the variable @code{holidays-in-diary-buffer} to
-@code{nil}.
-
-@vindex diary-list-include-blanks
- Ordinarily, the fancy diary buffer does not show days for which there are
-no diary entries, even if that day is a holiday. If you want such days to be
-shown in the fancy diary buffer, set the variable
-@code{diary-list-include-blanks} to @code{t}.@refill
-
-@cindex sorting diary entries
- If you use the fancy diary display, you can use the normal hook
-@code{list-diary-entries-hook} to sort each day's diary entries by their
-time of day. Here's how:
-
-@findex sort-diary-entries
-@example
-(add-hook 'list-diary-entries-hook 'sort-diary-entries t)
-@end example
-
-@noindent
-For each day, this sorts diary entries that begin with a recognizable
-time of day according to their times. Diary entries without times come
-first within each day.
-
- Fancy diary display also has the ability to process included diary
-files. This permits a group of people to share a diary file for events
-that apply to all of them. Lines in the diary file of this form:
-
-@smallexample
-#include "@var{filename}"
-@end smallexample
-
-@noindent
-includes the diary entries from the file @var{filename} in the fancy
-diary buffer. The include mechanism is recursive, so that included files
-can include other files, and so on; you must be careful not to have a
-cycle of inclusions, of course. Here is how to enable the include
-facility:
-
-@vindex list-diary-entries-hook
-@vindex mark-diary-entries-hook
-@findex include-other-diary-files
-@findex mark-included-diary-files
-@smallexample
-(add-hook 'list-diary-entries-hook 'include-other-diary-files)
-(add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
-@end smallexample
-
-The include mechanism works only with the fancy diary display, because
-ordinary diary display shows the entries directly from your diary file.
-
-@node Sexp Diary Entries
-@subsection Sexp Entries and the Fancy Diary Display
-@cindex sexp diary entries
-
- Sexp diary entries allow you to do more than just have complicated
-conditions under which a diary entry applies. If you use the fancy
-diary display, sexp entries can generate the text of the entry depending
-on the date itself. For example, an anniversary diary entry can insert
-the number of years since the anniversary date into the text of the
-diary entry. Thus the @samp{%d} in this diary entry:
-
-@findex diary-anniversary
-@smallexample
-%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
-@end smallexample
-
-@noindent
-gets replaced by the age, so on October 31, 1990 the entry appears in
-the fancy diary buffer like this:
-
-@smallexample
-Arthur's birthday (42 years old)
-@end smallexample
-
-@noindent
-If the diary file instead contains this entry:
-
-@smallexample
-%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
-@end smallexample
-
-@noindent
-the entry in the fancy diary buffer for October 31, 1990 appears like this:
-
-@smallexample
-Arthur's 42nd birthday
-@end smallexample
-
- Similarly, cyclic diary entries can interpolate the number of repetitions
-that have occurred:
-
-@findex diary-cyclic
-@smallexample
-%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
-@end smallexample
-
-@noindent
-looks like this:
-
-@smallexample
-Renew medication (5th time)
-@end smallexample
-
-@noindent
-in the fancy diary display on September 8, 1990.
-
- There is an early reminder diary sexp that includes its entry in the
-diary not only on the date of occurrence, but also on earlier dates.
-For example, if you want a reminder a week before your anniversary, you
-can use
-
-@findex diary-remind
-@smallexample
-%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary
-@end smallexample
-
-@noindent
-and the fancy diary will show
-@smallexample
-Ed's anniversary
-@end smallexample
-@noindent
-both on December 15 and on December 22.
-
-@findex diary-date
- The function @code{diary-date} applies to dates described by a month,
-day, year combination, each of which can be an integer, a list of
-integers, or @code{t}. The value @code{t} means all values. For
-example,
-
-@smallexample
-%%(diary-date '(10 11 12) 22 t) Rake leaves
-@end smallexample
-
-@noindent
-causes the fancy diary to show
-
-@smallexample
-Rake leaves
-@end smallexample
-
-@noindent
-on October 22, November 22, and December 22 of every year.
-
-@findex diary-float
- The function @code{diary-float} allows you to describe diary entries
-that apply to dates like the third Friday of November, or the last
-Tuesday in April. The parameters are the @var{month}, @var{dayname},
-and an index @var{n}. The entry appears on the @var{n}th @var{dayname}
-of @var{month}, where @var{dayname}=0 means Sunday, 1 means Monday, and
-so on. If @var{n} is negative it counts backward from the end of
-@var{month}. The value of @var{month} can be a list of months, a single
-month, or @code{t} to specify all months. You can also use an optional
-parameter @var{day} to specify the @var{n}th @var{dayname} of
-@var{month} on or after/before @var{day}; the value of @var{day} defaults
-to 1 if @var{n} is positive and to the last day of @var{month} if
-@var{n} is negative. For example,
-
-@smallexample
-%%(diary-float t 1 -1) Pay rent
-@end smallexample
-
-@noindent
-causes the fancy diary to show
-
-@smallexample
-Pay rent
-@end smallexample
-
-@noindent
-on the last Monday of every month.
-
- The generality of sexp diary entries lets you specify any diary
-entry that you can describe algorithmically. A sexp diary entry
-contains an expression that computes whether the entry applies to any
-given date. If its value is non-@code{nil}, the entry applies to that
-date; otherwise, it does not. The expression can use the variable
-@code{date} to find the date being considered; its value is a list
-(@var{month} @var{day} @var{year}) that refers to the Gregorian
-calendar.
-
- The sexp diary entry applies to a date when the expression's value
-is non-@code{nil}, but some values have more specific meanings. If
-the value is a string, that string is a description of the event which
-occurs on that date. The value can also have the form
-@code{(@var{mark} . @var{string})}; then @var{mark} specifies how to
-mark the date in the calendar, and @var{string} is the description of
-the event. If @var{mark} is a single-character string, that character
-appears next to the date in the calendar. If @var{mark} is a face
-name, the date is displayed in that face. If @var{mark} is
-@code{nil}, that specifies no particular highlighting for the date.
-
- Suppose you get paid on the 21st of the month if it is a weekday, and
-on the Friday before if the 21st is on a weekend. Here is how to write
-a sexp diary entry that matches those dates:
-
-@smallexample
-&%%(let ((dayname (calendar-day-of-week date))
- (day (car (cdr date))))
- (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
- (and (memq day '(19 20)) (= dayname 5)))
- ) Pay check deposited
-@end smallexample
-
- The following sexp diary entries take advantage of the ability (in the fancy
-diary display) to concoct diary entries whose text varies based on the date:
-
-@findex diary-sunrise-sunset
-@findex diary-phases-of-moon
-@findex diary-day-of-year
-@findex diary-iso-date
-@findex diary-julian-date
-@findex diary-astro-day-number
-@findex diary-hebrew-date
-@findex diary-islamic-date
-@findex diary-french-date
-@findex diary-mayan-date
-@table @code
-@item %%(diary-sunrise-sunset)
-Make a diary entry for the local times of today's sunrise and sunset.
-@item %%(diary-phases-of-moon)
-Make a diary entry for the phases (quarters) of the moon.
-@item %%(diary-day-of-year)
-Make a diary entry with today's day number in the current year and the number
-of days remaining in the current year.
-@item %%(diary-iso-date)
-Make a diary entry with today's equivalent ISO commercial date.
-@item %%(diary-julian-date)
-Make a diary entry with today's equivalent date on the Julian calendar.
-@item %%(diary-astro-day-number)
-Make a diary entry with today's equivalent astronomical (Julian) day number.
-@item %%(diary-hebrew-date)
-Make a diary entry with today's equivalent date on the Hebrew calendar.
-@item %%(diary-islamic-date)
-Make a diary entry with today's equivalent date on the Islamic calendar.
-@item %%(diary-french-date)
-Make a diary entry with today's equivalent date on the French Revolutionary
-calendar.
-@item %%(diary-mayan-date)
-Make a diary entry with today's equivalent date on the Mayan calendar.
-@end table
-
-@noindent
-Thus including the diary entry
-
-@example
-&%%(diary-hebrew-date)
-@end example
-
-@noindent
-causes every day's diary display to contain the equivalent date on the
-Hebrew calendar, if you are using the fancy diary display. (With simple
-diary display, the line @samp{&%%(diary-hebrew-date)} appears in the
-diary for any date, but does nothing particularly useful.)
-
- These functions can be used to construct sexp diary entries based on
-the Hebrew calendar in certain standard ways:
-
-@cindex rosh hodesh
-@findex diary-rosh-hodesh
-@cindex parasha, weekly
-@findex diary-parasha
-@cindex candle lighting times
-@findex diary-sabbath-candles
-@cindex omer count
-@findex diary-omer
-@cindex yahrzeits
-@findex diary-yahrzeit
-@table @code
-@item %%(diary-rosh-hodesh)
-Make a diary entry that tells the occurrence and ritual announcement of each
-new Hebrew month.
-@item %%(diary-parasha)
-Make a Saturday diary entry that tells the weekly synagogue scripture reading.
-@item %%(diary-sabbath-candles)
-Make a Friday diary entry that tells the @emph{local time} of Sabbath
-candle lighting.
-@item %%(diary-omer)
-Make a diary entry that gives the omer count, when appropriate.
-@item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name}
-Make a diary entry marking the anniversary of a date of death. The date
-is the @emph{Gregorian} (civil) date of death. The diary entry appears
-on the proper Hebrew calendar anniversary and on the day before. (In
-the European style, the order of the parameters is changed to @var{day},
-@var{month}, @var{year}.)
-@end table
-
- All the functions documented above take an optional argument
-@var{mark} which specifies how to mark the date in the calendar display.
-If one of these functions decides that it applies to a certain date,
-it returns a value that contains @var{mark}.
-
-@ignore
- arch-tag: 52cb299f-fd1f-4616-bfe6-91b988669431
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Calendar/Diary, Gnus, Dired, Top
-@chapter The Calendar and the Diary
-@cindex calendar
-@findex calendar
-
- Emacs provides the functions of a desk calendar, with a diary of
-planned or past events. It also has facilities for managing your
-appointments, and keeping track of how much time you spend working on
-certain projects.
-
- To enter the calendar, type @kbd{M-x calendar}; this displays a
-three-month calendar centered on the current month, with point on the
-current date. With a numeric argument, as in @kbd{C-u M-x calendar}, it
-prompts you for the month and year to be the center of the three-month
-calendar. The calendar uses its own buffer, whose major mode is
-Calendar mode.
-
- @kbd{Mouse-2} in the calendar brings up a menu of operations on a
-particular date; @kbd{Mouse-3} brings up a menu of commonly used
-calendar features that are independent of any particular date. To exit
-the calendar, type @kbd{q}.
-
-@iftex
- This chapter describes the basic calendar features.
-@inforef{Advanced Calendar/Diary Usage,, emacs-xtra}, for information
-about more specialized features.
-@end iftex
-
-@menu
-* Calendar Motion:: Moving through the calendar; selecting a date.
-* Scroll Calendar:: Bringing earlier or later months onto the screen.
-* Counting Days:: How many days are there between two dates?
-* General Calendar:: Exiting or recomputing the calendar.
-* Writing Calendar Files:: Writing calendars to files of various formats.
-* Holidays:: Displaying dates of holidays.
-* Sunrise/Sunset:: Displaying local times of sunrise and sunset.
-* Lunar Phases:: Displaying phases of the moon.
-* Other Calendars:: Converting dates to other calendar systems.
-* Diary:: Displaying events from your diary.
-* Appointments:: Reminders when it's time to do something.
-* Importing Diary:: Converting diary events to/from other formats.
-* Daylight Saving:: How to specify when daylight saving time is active.
-* Time Intervals:: Keeping track of time intervals.
-@ifnottex
-* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
-@end ifnottex
-@end menu
-
-@node Calendar Motion
-@section Movement in the Calendar
-
-@cindex moving inside the calendar
- Calendar mode provides commands to move through the calendar in
-logical units of time such as days, weeks, months, and years. If you
-move outside the three months originally displayed, the calendar
-display ``scrolls'' automatically through time to make the selected
-date visible. Moving to a date lets you view its holidays or diary
-entries, or convert it to other calendars; moving by long time periods
-is also useful simply to scroll the calendar.
-
-@menu
-* Calendar Unit Motion:: Moving by days, weeks, months, and years.
-* Move to Beginning or End:: Moving to start/end of weeks, months, and years.
-* Specified Dates:: Moving to the current date or another
- specific date.
-@end menu
-
-@node Calendar Unit Motion
-@subsection Motion by Standard Lengths of Time
-
- The commands for movement in the calendar buffer parallel the
-commands for movement in text. You can move forward and backward by
-days, weeks, months, and years.
-
-@table @kbd
-@item C-f
-Move point one day forward (@code{calendar-forward-day}).
-@item C-b
-Move point one day backward (@code{calendar-backward-day}).
-@item C-n
-Move point one week forward (@code{calendar-forward-week}).
-@item C-p
-Move point one week backward (@code{calendar-backward-week}).
-@item M-@}
-Move point one month forward (@code{calendar-forward-month}).
-@item M-@{
-Move point one month backward (@code{calendar-backward-month}).
-@item C-x ]
-Move point one year forward (@code{calendar-forward-year}).
-@item C-x [
-Move point one year backward (@code{calendar-backward-year}).
-@end table
-
-@kindex C-f @r{(Calendar mode)}
-@findex calendar-forward-day
-@kindex C-b @r{(Calendar mode)}
-@findex calendar-backward-day
-@kindex C-n @r{(Calendar mode)}
-@findex calendar-forward-week
-@kindex C-p @r{(Calendar mode)}
-@findex calendar-backward-week
- The day and week commands are natural analogues of the usual Emacs
-commands for moving by characters and by lines. Just as @kbd{C-n}
-usually moves to the same column in the following line, in Calendar
-mode it moves to the same day in the following week. And @kbd{C-p}
-moves to the same day in the previous week.
-
- The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and
-@kbd{C-p}, just as they normally are in other modes.
-
-@kindex M-@} @r{(Calendar mode)}
-@findex calendar-forward-month
-@kindex M-@{ @r{(Calendar mode)}
-@findex calendar-backward-month
-@kindex C-x ] @r{(Calendar mode)}
-@findex calendar-forward-year
-@kindex C-x [ @r{(Calendar mode)}
-@findex calendar-forward-year
- The commands for motion by months and years work like those for
-weeks, but move a larger distance. The month commands @kbd{M-@}} and
-@kbd{M-@{} move forward or backward by an entire month. The year
-commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a
-whole year.
-
- The easiest way to remember these commands is to consider months and
-years analogous to paragraphs and pages of text, respectively. But
-the commands themselves are not quite analogous. The ordinary Emacs
-paragraph commands move to the beginning or end of a paragraph,
-whereas these month and year commands move by an entire month or an
-entire year, keeping the same date within the month or year.
-
- All these commands accept a numeric argument as a repeat count.
-For convenience, the digit keys and the minus sign specify numeric
-arguments in Calendar mode even without the Meta modifier. For example,
-@kbd{100 C-f} moves point 100 days forward from its present location.
-
-@node Move to Beginning or End
-@subsection Beginning or End of Week, Month or Year
-
- A week (or month, or year) is not just a quantity of days; we think of
-weeks (months, years) as starting on particular dates. So Calendar mode
-provides commands to move to the beginning or end of a week, month or
-year:
-
-@table @kbd
-@kindex C-a @r{(Calendar mode)}
-@findex calendar-beginning-of-week
-@item C-a
-Move point to start of week (@code{calendar-beginning-of-week}).
-@kindex C-e @r{(Calendar mode)}
-@findex calendar-end-of-week
-@item C-e
-Move point to end of week (@code{calendar-end-of-week}).
-@kindex M-a @r{(Calendar mode)}
-@findex calendar-beginning-of-month
-@item M-a
-Move point to start of month (@code{calendar-beginning-of-month}).
-@kindex M-e @r{(Calendar mode)}
-@findex calendar-end-of-month
-@item M-e
-Move point to end of month (@code{calendar-end-of-month}).
-@kindex M-< @r{(Calendar mode)}
-@findex calendar-beginning-of-year
-@item M-<
-Move point to start of year (@code{calendar-beginning-of-year}).
-@kindex M-> @r{(Calendar mode)}
-@findex calendar-end-of-year
-@item M->
-Move point to end of year (@code{calendar-end-of-year}).
-@end table
-
- These commands also take numeric arguments as repeat counts, with the
-repeat count indicating how many weeks, months, or years to move
-backward or forward.
-
-@vindex calendar-week-start-day
-@cindex weeks, which day they start on
-@cindex calendar, first day of week
- By default, weeks begin on Sunday. To make them begin on Monday
-instead, set the variable @code{calendar-week-start-day} to 1.
-
-@node Specified Dates
-@subsection Specified Dates
-
- Calendar mode provides commands for moving to a particular date
-specified in various ways.
-
-@table @kbd
-@item g d
-Move point to specified date (@code{calendar-goto-date}).
-@item g D
-Move point to specified day of year (@code{calendar-goto-day-of-year}).
-@item g w
-Move point to specified week of year (@code{calendar-goto-iso-week}).
-@item o
-Center calendar around specified month (@code{calendar-other-month}).
-@item .
-Move point to today's date (@code{calendar-goto-today}).
-@end table
-
-@kindex g d @r{(Calendar mode)}
-@findex calendar-goto-date
- @kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day
-of the month, and then moves to that date. Because the calendar includes all
-dates from the beginning of the current era, you must type the year in its
-entirety; that is, type @samp{1990}, not @samp{90}.
-
-@kindex g D @r{(Calendar mode)}
-@findex calendar-goto-day-of-year
-@kindex g w @r{(Calendar mode)}
-@findex calendar-goto-iso-week
- @kbd{g D} (@code{calendar-goto-day-of-year}) prompts for a year and
-day number, and moves to that date. Negative day numbers count
-backward from the end of the year. @kbd{g w}
-(@code{calendar-goto-iso-week}) prompts for a year and week number,
-and moves to that week.
-
-@kindex o @r{(Calendar mode)}
-@findex calendar-other-month
- @kbd{o} (@code{calendar-other-month}) prompts for a month and year,
-then centers the three-month calendar around that month.
-
-@kindex . @r{(Calendar mode)}
-@findex calendar-goto-today
- You can return to today's date with @kbd{.}@:
-(@code{calendar-goto-today}).
-
-@node Scroll Calendar
-@section Scrolling in the Calendar
-
-@cindex scrolling in the calendar
- The calendar display scrolls automatically through time when you
-move out of the visible portion. You can also scroll it manually.
-Imagine that the calendar window contains a long strip of paper with
-the months on it. Scrolling the calendar means moving the strip
-horizontally, so that new months become visible in the window.
-
-@table @kbd
-@item >
-Scroll calendar one month forward (@code{scroll-calendar-left}).
-@item <
-Scroll calendar one month backward (@code{scroll-calendar-right}).
-@item C-v
-@itemx @key{NEXT}
-Scroll calendar three months forward
-(@code{scroll-calendar-left-three-months}).
-@item M-v
-@itemx @key{PRIOR}
-Scroll calendar three months backward
-(@code{scroll-calendar-right-three-months}).
-@end table
-
-@kindex > @r{(Calendar mode)}
-@findex scroll-calendar-left
-@kindex < @r{(Calendar mode)}
-@findex scroll-calendar-right
- The most basic calendar scroll commands scroll by one month at a
-time. This means that there are two months of overlap between the
-display before the command and the display after. @kbd{>} scrolls the
-calendar contents one month forward in time. @kbd{<} scrolls the
-contents one month backwards in time.
-
-@kindex C-v @r{(Calendar mode)}
-@findex scroll-calendar-left-three-months
-@kindex M-v @r{(Calendar mode)}
-@findex scroll-calendar-right-three-months
- The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire
-``screenful''---three months---in analogy with the usual meaning of
-these commands. @kbd{C-v} makes later dates visible and @kbd{M-v} makes
-earlier dates visible. These commands take a numeric argument as a
-repeat count; in particular, since @kbd{C-u} multiplies the next command
-by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and
-typing @kbd{C-u M-v} scrolls the calendar backward by a year.
-
- The function keys @key{NEXT} and @key{PRIOR} are equivalent to
-@kbd{C-v} and @kbd{M-v}, just as they are in other modes.
-
-@node Counting Days
-@section Counting Days
-
-@table @kbd
-@item M-=
-Display the number of days in the current region
-(@code{calendar-count-days-region}).
-@end table
-
-@kindex M-= @r{(Calendar mode)}
-@findex calendar-count-days-region
- To determine the number of days in the region, type @kbd{M-=}
-(@code{calendar-count-days-region}). The numbers of days shown is
-@emph{inclusive}; that is, it includes the days specified by mark and
-point.
-
-@node General Calendar
-@section Miscellaneous Calendar Commands
-
-@table @kbd
-@item p d
-Display day-in-year (@code{calendar-print-day-of-year}).
-@item C-c C-l
-Regenerate the calendar window (@code{redraw-calendar}).
-@item SPC
-Scroll the next window up (@code{scroll-other-window}).
-@item DEL
-Scroll the next window down (@code{scroll-other-window-down}).
-@item q
-Exit from calendar (@code{exit-calendar}).
-@end table
-
-@kindex p d @r{(Calendar mode)}
-@cindex day of year
-@findex calendar-print-day-of-year
- To display the number of days elapsed since the start of the year, or
-the number of days remaining in the year, type the @kbd{p d} command
-(@code{calendar-print-day-of-year}). This displays both of those
-numbers in the echo area. The count of days elapsed includes the
-selected date. The count of days remaining does not include that
-date.
-
-@kindex C-c C-l @r{(Calendar mode)}
-@findex redraw-calendar
- If the calendar window text gets corrupted, type @kbd{C-c C-l}
-(@code{redraw-calendar}) to redraw it. (This can only happen if you use
-non-Calendar-mode editing commands.)
-
-@kindex SPC @r{(Calendar mode)}
- In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window})
-and @kbd{DEL} (@code{scroll-other-window-down}) to scroll the other
-window up or down, respectively. This is handy when you display a list
-of holidays or diary entries in another window.
-
-@kindex q @r{(Calendar mode)}
-@findex exit-calendar
- To exit from the calendar, type @kbd{q} (@code{exit-calendar}). This
-buries all buffers related to the calendar, selecting other buffers.
-(If a frame contains a dedicated calendar window, exiting from the
-calendar iconifies that frame.)
-
-@node Writing Calendar Files
-@section Writing Calendar Files
-
- These packages produce files of various formats containing calendar
-and diary entries, for display purposes.
-
-@cindex calendar and HTML
- The Calendar HTML commands produce files of HTML code that contain
-calendar and diary entries. Each file applies to one month, and has a
-name of the format @file{@var{yyyy}-@var{mm}.html}, where @var{yyyy} and
-@var{mm} are the four-digit year and two-digit month, respectively. The
-variable @code{cal-html-directory} specifies the default output
-directory for the HTML files.
-
-@vindex cal-html-css-default
- Diary entries enclosed by @code{<} and @code{>} are interpreted as
-HTML tags (for example: this is a diary entry with <font
-color=''red''>some red text</font>). You can change the overall
-appearance of the displayed HTML pages (for example, the color of
-various page elements, header styles) via a stylesheet @file{cal.css} in
-the directory containing the HTML files (see the value of the variable
-@code{cal-html-css-default} for relevant style settings).
-
-@kindex t @r{(Calendar mode)}
-@table @kbd
-@item H m
-Generate a one-month calendar (@code{cal-html-cursor-month}).
-@item H y
-Generate a calendar file for each month of a year, as well as an index
-page (@code{cal-html-cursor-year}). By default, this command writes
-files to a @var{yyyy} subdirectory - if this is altered some hyperlinks
-between years will not work.
-@end table
-
- If the variable @code{cal-html-print-day-number-flag} is
-non-@code{nil}, then the monthly calendars show the day-of-the-year
-number. The variable @code{cal-html-year-index-cols} specifies the
-number of columns in the yearly index page.
-
-@cindex calendar and La@TeX{}
- The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that
-prints as a calendar. Depending on the command you use, the printed
-calendar covers the day, week, month or year that point is in.
-
-@kindex t @r{(Calendar mode)}
-@table @kbd
-@item t m
-Generate a one-month calendar (@code{cal-tex-cursor-month}).
-@item t M
-Generate a sideways-printing one-month calendar
-(@code{cal-tex-cursor-month-landscape}).
-@item t d
-Generate a one-day calendar
-(@code{cal-tex-cursor-day}).
-@item t w 1
-Generate a one-page calendar for one week
-(@code{cal-tex-cursor-week}).
-@item t w 2
-Generate a two-page calendar for one week
-(@code{cal-tex-cursor-week2}).
-@item t w 3
-Generate an ISO-style calendar for one week
-(@code{cal-tex-cursor-week-iso}).
-@item t w 4
-Generate a calendar for one Monday-starting week
-(@code{cal-tex-cursor-week-monday}).
-@item t f w
-Generate a Filofax-style two-weeks-at-a-glance calendar
-(@code{cal-tex-cursor-filofax-2week}).
-@item t f W
-Generate a Filofax-style one-week-at-a-glance calendar
-(@code{cal-tex-cursor-filofax-week}).
-@item t y
-Generate a calendar for one year
-(@code{cal-tex-cursor-year}).
-@item t Y
-Generate a sideways-printing calendar for one year
-(@code{cal-tex-cursor-year-landscape}).
-@item t f y
-Generate a Filofax-style calendar for one year
-(@code{cal-tex-cursor-filofax-year}).
-@end table
-
- Some of these commands print the calendar sideways (in ``landscape
-mode''), so it can be wider than it is long. Some of them use Filofax
-paper size (3.75in x 6.75in). All of these commands accept a prefix
-argument which specifies how many days, weeks, months or years to print
-(starting always with the selected one).
-
- If the variable @code{cal-tex-holidays} is non-@code{nil} (the default),
-then the printed calendars show the holidays in @code{calendar-holidays}.
-If the variable @code{cal-tex-diary} is non-@code{nil} (the default is
-@code{nil}), diary entries are included also (in monthly, filofax, and
-iso-week calendars only). If the variable @code{cal-tex-rules} is
-non-@code{nil} (the default is @code{nil}), the calendar displays ruled
-pages in styles that have sufficient room. Consult the documentation of
-the individual cal-tex functions to see which calendars support which
-features.
-
- You can use the variable @code{cal-tex-preamble-extra} to insert extra
-La@TeX{} commands in the preamble of the generated document if you need
-to.
-
-@node Holidays
-@section Holidays
-@cindex holidays
-
- The Emacs calendar knows about all major and many minor holidays,
-and can display them.
-
-@table @kbd
-@item h
-Display holidays for the selected date
-(@code{calendar-cursor-holidays}).
-@item Mouse-2 Holidays
-Display any holidays for the date you click on.
-@item x
-Mark holidays in the calendar window (@code{mark-calendar-holidays}).
-@item u
-Unmark calendar window (@code{calendar-unmark}).
-@item a
-List all holidays for the displayed three months in another window
-(@code{list-calendar-holidays}).
-@item M-x holidays
-List all holidays for three months around today's date in another
-window.
-@item M-x list-holidays
-List holidays in another window for a specified range of years.
-@end table
-
-@kindex h @r{(Calendar mode)}
-@findex calendar-cursor-holidays
-@vindex view-calendar-holidays-initially
- To see if any holidays fall on a given date, position point on that
-date in the calendar window and use the @kbd{h} command. Alternatively,
-click on that date with @kbd{Mouse-2} and then choose @kbd{Holidays}
-from the menu that appears. Either way, this displays the holidays for
-that date, in the echo area if they fit there, otherwise in a separate
-window.
-
-@kindex x @r{(Calendar mode)}
-@findex mark-calendar-holidays
-@kindex u @r{(Calendar mode)}
-@findex calendar-unmark
-@vindex mark-holidays-in-calendar
- To view the distribution of holidays for all the dates shown in the
-calendar, use the @kbd{x} command. This displays the dates that are
-holidays in a different face (or places a @samp{*} after these dates, if
-display with multiple faces is not available).
-@iftex
-@inforef{Calendar Customizing, calendar-holiday-marker, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Calendar Customizing, calendar-holiday-marker}.
-@end ifnottex
- The command applies both to the currently visible months and to
-other months that subsequently become visible by scrolling. To turn
-marking off and erase the current marks, type @kbd{u}, which also
-erases any diary marks (@pxref{Diary}). If the variable
-@code{mark-holidays-in-calendar} is non-@code{nil}, creating or
-updating the calendar marks holidays automatically.
-
-@kindex a @r{(Calendar mode)}
-@findex list-calendar-holidays
- To get even more detailed information, use the @kbd{a} command, which
-displays a separate buffer containing a list of all holidays in the
-current three-month range. You can use @key{SPC} and @key{DEL} in the
-calendar window to scroll that list up and down, respectively.
-
-@findex holidays
- The command @kbd{M-x holidays} displays the list of holidays for the
-current month and the preceding and succeeding months; this works even
-if you don't have a calendar window. If the variable
-@code{view-calendar-holidays-initially} is non-@code{nil}, creating
-the calendar displays holidays in this way. If you want the list of
-holidays centered around a different month, use @kbd{C-u M-x
-holidays}, which prompts for the month and year.
-
- The holidays known to Emacs include United States holidays and the
-major Christian, Jewish, and Islamic holidays; also the solstices and
-equinoxes.
-
-@findex list-holidays
- The command @kbd{M-x list-holidays} displays the list of holidays for
-a range of years. This function asks you for the starting and stopping
-years, and allows you to choose all the holidays or one of several
-categories of holidays. You can use this command even if you don't have
-a calendar window.
-
- The dates used by Emacs for holidays are based on @emph{current
-practice}, not historical fact. For example Veteran's Day began in
-1919, but is shown in earlier years.
-
-@node Sunrise/Sunset
-@section Times of Sunrise and Sunset
-@cindex sunrise and sunset
-
- Special calendar commands can tell you, to within a minute or two, the
-times of sunrise and sunset for any date.
-
-@table @kbd
-@item S
-Display times of sunrise and sunset for the selected date
-(@code{calendar-sunrise-sunset}).
-@item Mouse-2 Sunrise/sunset
-Display times of sunrise and sunset for the date you click on.
-@item M-x sunrise-sunset
-Display times of sunrise and sunset for today's date.
-@item C-u M-x sunrise-sunset
-Display times of sunrise and sunset for a specified date.
-@end table
-
-@kindex S @r{(Calendar mode)}
-@findex calendar-sunrise-sunset
-@findex sunrise-sunset
- Within the calendar, to display the @emph{local times} of sunrise and
-sunset in the echo area, move point to the date you want, and type
-@kbd{S}. Alternatively, click @kbd{Mouse-2} on the date, then choose
-@samp{Sunrise/sunset} from the menu that appears. The command @kbd{M-x
-sunrise-sunset} is available outside the calendar to display this
-information for today's date or a specified date. To specify a date
-other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for
-the year, month, and day.
-
- You can display the times of sunrise and sunset for any location and
-any date with @kbd{C-u C-u M-x sunrise-sunset}. This asks you for a
-longitude, latitude, number of minutes difference from Coordinated
-Universal Time, and date, and then tells you the times of sunrise and
-sunset for that location on that date.
-
- Because the times of sunrise and sunset depend on the location on
-earth, you need to tell Emacs your latitude, longitude, and location
-name before using these commands. Here is an example of what to set:
-
-@vindex calendar-location-name
-@vindex calendar-longitude
-@vindex calendar-latitude
-@example
-(setq calendar-latitude 40.1)
-(setq calendar-longitude -88.2)
-(setq calendar-location-name "Urbana, IL")
-@end example
-
-@noindent
-Use one decimal place in the values of @code{calendar-latitude} and
-@code{calendar-longitude}.
-
- Your time zone also affects the local time of sunrise and sunset.
-Emacs usually gets time zone information from the operating system, but
-if these values are not what you want (or if the operating system does
-not supply them), you must set them yourself. Here is an example:
-
-@vindex calendar-time-zone
-@vindex calendar-standard-time-zone-name
-@vindex calendar-daylight-time-zone-name
-@example
-(setq calendar-time-zone -360)
-(setq calendar-standard-time-zone-name "CST")
-(setq calendar-daylight-time-zone-name "CDT")
-@end example
-
-@noindent
-The value of @code{calendar-time-zone} is the number of minutes
-difference between your local standard time and Coordinated Universal
-Time (Greenwich time). The values of
-@code{calendar-standard-time-zone-name} and
-@code{calendar-daylight-time-zone-name} are the abbreviations used in
-your time zone. Emacs displays the times of sunrise and sunset
-@emph{corrected for daylight saving time}. @xref{Daylight Saving},
-for how daylight saving time is determined.
-
- As a user, you might find it convenient to set the calendar location
-variables for your usual physical location in your @file{.emacs} file.
-And when you install Emacs on a machine, you can create a
-@file{default.el} file which sets them properly for the typical location
-of most users of that machine. @xref{Init File}.
-
-@node Lunar Phases
-@section Phases of the Moon
-@cindex phases of the moon
-@cindex moon, phases of
-
- These calendar commands display the dates and times of the phases of
-the moon (new moon, first quarter, full moon, last quarter). This
-feature is useful for debugging problems that ``depend on the phase of
-the moon.''
-
-@table @kbd
-@item M
-Display the dates and times for all the quarters of the moon for the
-three-month period shown (@code{calendar-phases-of-moon}).
-@item M-x phases-of-moon
-Display dates and times of the quarters of the moon for three months around
-today's date.
-@end table
-
-@kindex M @r{(Calendar mode)}
-@findex calendar-phases-of-moon
- Within the calendar, use the @kbd{M} command to display a separate
-buffer of the phases of the moon for the current three-month range. The
-dates and times listed are accurate to within a few minutes.
-
-@findex phases-of-moon
- Outside the calendar, use the command @kbd{M-x phases-of-moon} to
-display the list of the phases of the moon for the current month and the
-preceding and succeeding months. For information about a different
-month, use @kbd{C-u M-x phases-of-moon}, which prompts for the month and
-year.
-
- The dates and times given for the phases of the moon are given in
-local time (corrected for daylight saving, when appropriate); but if
-the variable @code{calendar-time-zone} is void, Coordinated Universal
-Time (the Greenwich time zone) is used. @xref{Daylight Saving}.
-
-@node Other Calendars
-@section Conversion To and From Other Calendars
-
-@cindex Gregorian calendar
- The Emacs calendar displayed is @emph{always} the Gregorian calendar,
-sometimes called the ``new style'' calendar, which is used in most of
-the world today. However, this calendar did not exist before the
-sixteenth century and was not widely used before the eighteenth century;
-it did not fully displace the Julian calendar and gain universal
-acceptance until the early twentieth century. The Emacs calendar can
-display any month since January, year 1 of the current era, but the
-calendar displayed is the Gregorian, even for a date at which the
-Gregorian calendar did not exist.
-
- While Emacs cannot display other calendars, it can convert dates to
-and from several other calendars.
-
-@menu
-* Calendar Systems:: The calendars Emacs understands
- (aside from Gregorian).
-* To Other Calendar:: Converting the selected date to various calendars.
-* From Other Calendar:: Moving to a date specified in another calendar.
-* Mayan Calendar:: Moving to a date specified in a Mayan calendar.
-@end menu
-
-@node Calendar Systems
-@subsection Supported Calendar Systems
-
-@cindex ISO commercial calendar
- The ISO commercial calendar is used largely in Europe.
-
-@cindex Julian calendar
- The Julian calendar, named after Julius Caesar, was the one used in Europe
-throughout medieval times, and in many countries up until the nineteenth
-century.
-
-@cindex Julian day numbers
-@cindex astronomical day numbers
- Astronomers use a simple counting of days elapsed since noon, Monday,
-January 1, 4713 B.C. on the Julian calendar. The number of days elapsed
-is called the @dfn{Julian day number} or the @dfn{Astronomical day number}.
-
-@cindex Hebrew calendar
- The Hebrew calendar is used by tradition in the Jewish religion. The
-Emacs calendar program uses the Hebrew calendar to determine the dates
-of Jewish holidays. Hebrew calendar dates begin and end at sunset.
-
-@cindex Islamic calendar
- The Islamic calendar is used in many predominantly Islamic countries.
-Emacs uses it to determine the dates of Islamic holidays. There is no
-universal agreement in the Islamic world about the calendar; Emacs uses
-a widely accepted version, but the precise dates of Islamic holidays
-often depend on proclamation by religious authorities, not on
-calculations. As a consequence, the actual dates of observance can vary
-slightly from the dates computed by Emacs. Islamic calendar dates begin
-and end at sunset.
-
-@cindex French Revolutionary calendar
- The French Revolutionary calendar was created by the Jacobins after the 1789
-revolution, to represent a more secular and nature-based view of the annual
-cycle, and to install a 10-day week in a rationalization measure similar to
-the metric system. The French government officially abandoned this
-calendar at the end of 1805.
-
-@cindex Mayan calendar
- The Maya of Central America used three separate, overlapping calendar
-systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}.
-Emacs knows about all three of these calendars. Experts dispute the
-exact correlation between the Mayan calendar and our calendar; Emacs uses the
-Goodman-Martinez-Thompson correlation in its calculations.
-
-@cindex Coptic calendar
-@cindex Ethiopic calendar
- The Copts use a calendar based on the ancient Egyptian solar calendar.
-Their calendar consists of twelve 30-day months followed by an extra
-five-day period. Once every fourth year they add a leap day to this
-extra period to make it six days. The Ethiopic calendar is identical in
-structure, but has different year numbers and month names.
-
-@cindex Persian calendar
- The Persians use a solar calendar based on a design of Omar Khayyam.
-Their calendar consists of twelve months of which the first six have 31
-days, the next five have 30 days, and the last has 29 in ordinary years
-and 30 in leap years. Leap years occur in a complicated pattern every
-four or five years.
-The calendar implemented here is the arithmetical Persian calendar
-championed by Birashk, based on a 2,820-year cycle. It differs from
-the astronomical Persian calendar, which is based on astronomical
-events. As of this writing the first future discrepancy is projected
-to occur on March 20, 2025. It is currently not clear what the
-official calendar of Iran will be that far into the future.
-
-@cindex Chinese calendar
- The Chinese calendar is a complicated system of lunar months arranged
-into solar years. The years go in cycles of sixty, each year containing
-either twelve months in an ordinary year or thirteen months in a leap
-year; each month has either 29 or 30 days. Years, ordinary months, and
-days are named by combining one of ten ``celestial stems'' with one of
-twelve ``terrestrial branches'' for a total of sixty names that are
-repeated in a cycle of sixty.
-
-@node To Other Calendar
-@subsection Converting To Other Calendars
-
- The following commands describe the selected date (the date at point)
-in various other calendar systems:
-
-@table @kbd
-@item Mouse-2 Other calendars
-Display the date that you click on, expressed in various other calendars.
-@kindex p @r{(Calendar mode)}
-@findex calendar-print-iso-date
-@item p c
-Display ISO commercial calendar equivalent for selected day
-(@code{calendar-print-iso-date}).
-@findex calendar-print-julian-date
-@item p j
-Display Julian date for selected day (@code{calendar-print-julian-date}).
-@findex calendar-print-astro-day-number
-@item p a
-Display astronomical (Julian) day number for selected day
-(@code{calendar-print-astro-day-number}).
-@findex calendar-print-hebrew-date
-@item p h
-Display Hebrew date for selected day (@code{calendar-print-hebrew-date}).
-@findex calendar-print-islamic-date
-@item p i
-Display Islamic date for selected day (@code{calendar-print-islamic-date}).
-@findex calendar-print-french-date
-@item p f
-Display French Revolutionary date for selected day
-(@code{calendar-print-french-date}).
-@findex calendar-print-chinese-date
-@item p C
-Display Chinese date for selected day
-(@code{calendar-print-chinese-date}).
-@findex calendar-print-coptic-date
-@item p k
-Display Coptic date for selected day
-(@code{calendar-print-coptic-date}).
-@findex calendar-print-ethiopic-date
-@item p e
-Display Ethiopic date for selected day
-(@code{calendar-print-ethiopic-date}).
-@findex calendar-print-persian-date
-@item p p
-Display Persian date for selected day
-(@code{calendar-print-persian-date}).
-@findex calendar-print-mayan-date
-@item p m
-Display Mayan date for selected day (@code{calendar-print-mayan-date}).
-@end table
-
- If you are using X, the easiest way to translate a date into other
-calendars is to click on it with @kbd{Mouse-2}, then choose @kbd{Other
-calendars} from the menu that appears. This displays the equivalent
-forms of the date in all the calendars Emacs understands, in the form of
-a menu. (Choosing an alternative from this menu doesn't actually do
-anything---the menu is used only for display.)
-
- Otherwise, move point to the date you want to convert, then type the
-appropriate command starting with @kbd{p} from the table above. The
-prefix @kbd{p} is a mnemonic for ``print,'' since Emacs ``prints'' the
-equivalent date in the echo area.
-
-@node From Other Calendar
-@subsection Converting From Other Calendars
-
- You can use the other supported calendars to specify a date to move
-to. This section describes the commands for doing this using calendars
-other than Mayan; for the Mayan calendar, see the following section.
-
-@kindex g @var{char} @r{(Calendar mode)}
-@findex calendar-goto-iso-date
-@findex calendar-goto-iso-week
-@findex calendar-goto-julian-date
-@findex calendar-goto-astro-day-number
-@findex calendar-goto-hebrew-date
-@findex calendar-goto-islamic-date
-@findex calendar-goto-french-date
-@findex calendar-goto-chinese-date
-@findex calendar-goto-persian-date
-@findex calendar-goto-coptic-date
-@findex calendar-goto-ethiopic-date
-@table @kbd
-@item g c
-Move to a date specified in the ISO commercial calendar
-(@code{calendar-goto-iso-date}).
-@item g w
-Move to a week specified in the ISO commercial calendar
-(@code{calendar-goto-iso-week}).
-@item g j
-Move to a date specified in the Julian calendar
-(@code{calendar-goto-julian-date}).
-@item g a
-Move to a date specified with an astronomical (Julian) day number
-(@code{calendar-goto-astro-day-number}).
-@item g h
-Move to a date specified in the Hebrew calendar
-(@code{calendar-goto-hebrew-date}).
-@item g i
-Move to a date specified in the Islamic calendar
-(@code{calendar-goto-islamic-date}).
-@item g f
-Move to a date specified in the French Revolutionary calendar
-(@code{calendar-goto-french-date}).
-@item g C
-Move to a date specified in the Chinese calendar
-(@code{calendar-goto-chinese-date}).
-@item g p
-Move to a date specified in the Persian calendar
-(@code{calendar-goto-persian-date}).
-@item g k
-Move to a date specified in the Coptic calendar
-(@code{calendar-goto-coptic-date}).
-@item g e
-Move to a date specified in the Ethiopic calendar
-(@code{calendar-goto-ethiopic-date}).
-@end table
-
- These commands ask you for a date on the other calendar, move point to
-the Gregorian calendar date equivalent to that date, and display the
-other calendar's date in the echo area. Emacs uses strict completion
-(@pxref{Completion}) whenever it asks you to type a month name, so you
-don't have to worry about the spelling of Hebrew, Islamic, or French names.
-
-@findex list-yahrzeit-dates
-@cindex yahrzeits
- One common question concerning the Hebrew calendar is the computation
-of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs
-calendar includes a facility for such calculations. If you are in the
-calendar, the command @kbd{M-x list-yahrzeit-dates} asks you for a
-range of years and then displays a list of the yahrzeit dates for those
-years for the date given by point. If you are not in the calendar,
-this command first asks you for the date of death and the range of
-years, and then displays the list of yahrzeit dates.
-
-@node Mayan Calendar
-@subsection Converting from the Mayan Calendar
-
- Here are the commands to select dates based on the Mayan calendar:
-
-@table @kbd
-@item g m l
-Move to a date specified by the long count calendar
-(@code{calendar-goto-mayan-long-count-date}).
-@item g m n t
-Move to the next occurrence of a place in the
-tzolkin calendar (@code{calendar-next-tzolkin-date}).
-@item g m p t
-Move to the previous occurrence of a place in the
-tzolkin calendar (@code{calendar-previous-tzolkin-date}).
-@item g m n h
-Move to the next occurrence of a place in the
-haab calendar (@code{calendar-next-haab-date}).
-@item g m p h
-Move to the previous occurrence of a place in the
-haab calendar (@code{calendar-previous-haab-date}).
-@item g m n c
-Move to the next occurrence of a place in the
-calendar round (@code{calendar-next-calendar-round-date}).
-@item g m p c
-Move to the previous occurrence of a place in the
-calendar round (@code{calendar-previous-calendar-round-date}).
-@end table
-
-@cindex Mayan long count
- To understand these commands, you need to understand the Mayan calendars.
-The @dfn{long count} is a counting of days with these units:
-
-@display
-1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal
-1 katun = 20 tun@ @ @ 1 baktun = 20 katun
-@end display
-
-@kindex g m @r{(Calendar mode)}
-@findex calendar-goto-mayan-long-count-date
-@noindent
-Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
-tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long
-count dates as early as 7.17.18.13.3, but no earlier. When you use the
-@kbd{g m l} command, type the Mayan long count date with the baktun,
-katun, tun, uinal, and kin separated by periods.
-
-@findex calendar-previous-tzolkin-date
-@findex calendar-next-tzolkin-date
-@cindex Mayan tzolkin calendar
- The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
-independent cycles of 13 and 20 days. Since this cycle repeats
-endlessly, Emacs provides commands to move backward and forward to the
-previous or next point in the cycle. Type @kbd{g m p t} to go to the
-previous tzolkin date; Emacs asks you for a tzolkin date and moves point
-to the previous occurrence of that date. Similarly, type @kbd{g m n t}
-to go to the next occurrence of a tzolkin date.
-
-@findex calendar-previous-haab-date
-@findex calendar-next-haab-date
-@cindex Mayan haab calendar
- The Mayan haab calendar is a cycle of 365 days arranged as 18 months
-of 20 days each, followed a 5-day monthless period. Like the tzolkin
-cycle, this cycle repeats endlessly, and there are commands to move
-backward and forward to the previous or next point in the cycle. Type
-@kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab
-date and moves point to the previous occurrence of that date.
-Similarly, type @kbd{g m n h} to go to the next occurrence of a haab
-date.
-
-@c This is omitted because it is too long for smallbook format.
-@c @findex calendar-previous-calendar-round-date
-@findex calendar-next-calendar-round-date
-@cindex Mayan calendar round
- The Maya also used the combination of the tzolkin date and the haab
-date. This combination is a cycle of about 52 years called a
-@emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for
-both a haab and a tzolkin date and then moves point to the previous
-occurrence of that combination. Use @kbd{g m n c} to move point to the
-next occurrence of a combination. These commands signal an error if the
-haab/tzolkin date combination you have typed is impossible.
-
- Emacs uses strict completion (@pxref{Strict Completion}) whenever it
-asks you to type a Mayan name, so you don't have to worry about
-spelling.
-
-@node Diary
-@section The Diary
-@cindex diary
-
- The Emacs diary keeps track of appointments or other events on a daily
-basis, in conjunction with the calendar. To use the diary feature, you
-must first create a @dfn{diary file} containing a list of events and
-their dates. Then Emacs can automatically pick out and display the
-events for today, for the immediate future, or for any specified
-date.
-
- The name of the diary file is specified by the variable
-@code{diary-file}; @file{~/diary} is the default. A sample diary file
-is (note that the file format is essentially the same as that used by
-the external shell utility @samp{calendar}):
-
-@example
-12/22/1988 Twentieth wedding anniversary!!
-&1/1. Happy New Year!
-10/22 Ruth's birthday.
-* 21, *: Payday
-Tuesday--weekly meeting with grad students at 10am
- Supowit, Shen, Bitner, and Kapoor to attend.
-1/13/89 Friday the thirteenth!!
-&thu 4pm squash game with Lloyd.
-mar 16 Dad's birthday
-April 15, 1989 Income tax due.
-&* 15 time cards due.
-@end example
-
-@noindent
-This example uses extra spaces to align the event descriptions of most
-of the entries. Such formatting is purely a matter of taste.
-
- Although you probably will start by creating a diary manually, Emacs
-provides a number of commands to let you view, add, and change diary
-entries.
-
-@menu
-* Displaying the Diary:: Viewing diary entries and associated calendar dates.
-* Format of Diary File:: Entering events in your diary.
-* Date Formats:: Various ways you can specify dates.
-* Adding to Diary:: Commands to create diary entries.
-* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
-@end menu
-
-@node Displaying the Diary
-@subsection Displaying the Diary
-
- Once you have created a diary file, you can use the calendar to view
-it. You can also view today's events outside of Calendar mode.
-
-@table @kbd
-@item d
-Display all diary entries for the selected date
-(@code{diary-view-entries}).
-@item Mouse-2 Diary
-Display all diary entries for the date you click on.
-@item s
-Display the entire diary file (@code{diary-show-all-entries}).
-@item m
-Mark all visible dates that have diary entries
-(@code{mark-diary-entries}).
-@item u
-Unmark the calendar window (@code{calendar-unmark}).
-@item M-x print-diary-entries
-Print hard copy of the diary display as it appears.
-@item M-x diary
-Display all diary entries for today's date.
-@item M-x diary-mail-entries
-Mail yourself email reminders about upcoming diary entries.
-@end table
-
-@kindex d @r{(Calendar mode)}
-@findex diary-view-entries
-@vindex view-diary-entries-initially
- Displaying the diary entries with @kbd{d} shows in a separate window
-the diary entries for the selected date in the calendar. The mode line
-of the new window shows the date of the diary entries and any holidays
-that fall on that date. If you specify a numeric argument with @kbd{d},
-it shows all the diary entries for that many successive days. Thus,
-@kbd{2 d} displays all the entries for the selected date and for the
-following day.
-
- Another way to display the diary entries for a date is to click
-@kbd{Mouse-2} on the date, and then choose @kbd{Diary entries} from
-the menu that appears. If the variable
-@code{view-diary-entries-initially} is non-@code{nil}, creating the
-calendar lists the diary entries for the current date (provided the
-current date is visible).
-
-@kindex m @r{(Calendar mode)}
-@findex mark-diary-entries
-@vindex mark-diary-entries-in-calendar
- To get a broader view of which days are mentioned in the diary, use
-the @kbd{m} command. This displays the dates that have diary entries in
-a different face (or places a @samp{+} after these dates, if display
-with multiple faces is not available).
-@iftex
-@inforef{Calendar Customizing, diary-entry-marker, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Calendar Customizing, diary-entry-marker}.
-@end ifnottex
- The command applies both to the currently visible months and to
-other months that subsequently become visible by scrolling. To turn
-marking off and erase the current marks, type @kbd{u}, which also
-turns off holiday marks (@pxref{Holidays}). If the variable
-@code{mark-diary-entries-in-calendar} is non-@code{nil}, creating or
-updating the calendar marks diary dates automatically.
-
-@kindex s @r{(Calendar mode)}
-@findex diary-show-all-entries
- To see the full diary file, rather than just some of the entries, use
-the @kbd{s} command.
-
- Display of selected diary entries uses the selective display feature
-to hide entries that don't apply. The diary buffer as you see it is
-an illusion, so simply printing the buffer does not print what you see
-on your screen. There is a special command to print hard copy of the
-diary buffer @emph{as it appears}; this command is @kbd{M-x
-print-diary-entries}. It sends the data directly to the printer. You
-can customize it like @code{lpr-region} (@pxref{Printing}).
-
-@findex diary
- The command @kbd{M-x diary} displays the diary entries for the current
-date, independently of the calendar display, and optionally for the next
-few days as well; the variable @code{number-of-diary-entries} specifies
-how many days to include.
-@iftex
-@inforef{Diary Customizing,, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Diary Customizing, number-of-diary-entries}.
-@end ifnottex
-
- If you put @code{(diary)} in your @file{.emacs} file, this
-automatically displays a window with the day's diary entries, when you
-enter Emacs. The mode line of the displayed window shows the date and
-any holidays that fall on that date.
-
-@findex diary-mail-entries
-@vindex diary-mail-days
- Many users like to receive notice of events in their diary as email.
-To send such mail to yourself, use the command @kbd{M-x
-diary-mail-entries}. A prefix argument specifies how many days
-(starting with today) to check; otherwise, the variable
-@code{diary-mail-days} says how many days.
-
-@node Format of Diary File
-@subsection The Diary File
-@cindex diary file
-
-@vindex diary-file
- Your @dfn{diary file} is a file that records events associated with
-particular dates. The name of the diary file is specified by the
-variable @code{diary-file}; @file{~/diary} is the default. The
-@code{calendar} utility program supports a subset of the format allowed
-by the Emacs diary facilities, so you can use that utility to view the
-diary file, with reasonable results aside from the entries it cannot
-understand.
-
- Each entry in the diary file describes one event and consists of one
-or more lines. An entry always begins with a date specification at the
-left margin. The rest of the entry is simply text to describe the
-event. If the entry has more than one line, then the lines after the
-first must begin with whitespace to indicate they continue a previous
-entry. Lines that do not begin with valid dates and do not continue a
-preceding entry are ignored.
-
- You can inhibit the marking of certain diary entries in the calendar
-window; to do this, insert an ampersand (@samp{&}) at the beginning of
-the entry, before the date. This has no effect on display of the entry
-in the diary window; it affects only marks on dates in the calendar
-window. Nonmarking entries are especially useful for generic entries
-that would otherwise mark many different dates.
-
- If the first line of a diary entry consists only of the date or day
-name with no following blanks or punctuation, then the diary window
-display doesn't include that line; only the continuation lines appear.
-For example, this entry:
-
-@example
-02/11/1989
- Bill B. visits Princeton today
- 2pm Cognitive Studies Committee meeting
- 2:30-5:30 Liz at Lawrenceville
- 4:00pm Dentist appt
- 7:30pm Dinner at George's
- 8:00-10:00pm concert
-@end example
-
-@noindent
-appears in the diary window without the date line at the beginning.
-This style of entry looks neater when you display just a single day's
-entries, but can cause confusion if you ask for more than one day's
-entries.
-
- You can edit the diary entries as they appear in the window, but it is
-important to remember that the buffer displayed contains the @emph{entire}
-diary file, with portions of it concealed from view. This means, for
-instance, that the @kbd{C-f} (@code{forward-char}) command can put point
-at what appears to be the end of the line, but what is in reality the
-middle of some concealed line.
-
- @emph{Be careful when editing the diary entries!} Inserting
-additional lines or adding/deleting characters in the middle of a
-visible line cannot cause problems, but editing at the end of a line may
-not do what you expect. Deleting a line may delete other invisible
-entries that follow it. Before editing the diary, it is best to display
-the entire file with @kbd{s} (@code{diary-show-all-entries}).
-
-@node Date Formats
-@subsection Date Formats
-
- Here are some sample diary entries, illustrating different ways of
-formatting a date. The examples all show dates in American order
-(month, day, year), but Calendar mode supports European order (day,
-month, year) as an option.
-
-@example
-4/20/93 Switch-over to new tabulation system
-apr. 25 Start tabulating annual results
-4/30 Results for April are due
-*/25 Monthly cycle finishes
-Friday Don't leave without backing up files
-@end example
-
- The first entry appears only once, on April 20, 1993. The second and
-third appear every year on the specified dates, and the fourth uses a
-wildcard (asterisk) for the month, so it appears on the 25th of every
-month. The final entry appears every week on Friday.
-
- You can use just numbers to express a date, as in
-@samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}.
-This must be followed by a nondigit. In the date itself, @var{month}
-and @var{day} are numbers of one or two digits. The optional @var{year}
-is also a number, and may be abbreviated to the last two digits; that
-is, you can use @samp{11/12/1989} or @samp{11/12/89}.
-
- Dates can also have the form @samp{@var{monthname} @var{day}} or
-@samp{@var{monthname} @var{day}, @var{year}}, where the month's name can
-be spelled in full or abbreviated (with or without a period). The
-preferred abbreviations can be controlled using the variables
-@code{calendar-abbrev-length}, @code{calendar-month-abbrev-array}, and
-@code{calendar-day-abbrev-array}. The default is to use the first three
-letters of a name as its abbreviation. Case is not significant.
-
- A date may be @dfn{generic}; that is, partially unspecified. Then the
-entry applies to all dates that match the specification. If the date
-does not contain a year, it is generic and applies to any year.
-Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*};
-this matches any month, day, or year, respectively. Thus, a diary entry
-@samp{3/*/*} matches any day in March of any year; so does @samp{march
-*}.
-
-@vindex european-calendar-style
-@findex european-calendar
-@findex american-calendar
- If you prefer the European style of writing dates---in which the day
-comes before the month---type @kbd{M-x european-calendar} while in the
-calendar, or set the variable @code{european-calendar-style} to @code{t}
-with @kbd{M-x customize}, or @emph{before} using any calendar or diary
-command. This mode interprets all dates in the diary in the European
-manner, and also uses European style for displaying diary dates. (Note
-that there is no comma after the @var{monthname} in the European style.)
-To go back to the (default) American style of writing dates, type
-@kbd{M-x american-calendar}.
-
- You can use the name of a day of the week as a generic date which
-applies to any date falling on that day of the week. You can abbreviate
-the day of the week to three letters (with or without a period) or spell
-it in full; case is not significant.
-
-@node Adding to Diary
-@subsection Commands to Add to the Diary
-
- While in the calendar, there are several commands to create diary
-entries:
-
-@table @kbd
-@item i d
-Add a diary entry for the selected date (@code{insert-diary-entry}).
-@item i w
-Add a diary entry for the selected day of the week (@code{insert-weekly-diary-entry}).
-@item i m
-Add a diary entry for the selected day of the month (@code{insert-monthly-diary-entry}).
-@item i y
-Add a diary entry for the selected day of the year (@code{insert-yearly-diary-entry}).
-@end table
-
-@kindex i d @r{(Calendar mode)}
-@findex insert-diary-entry
- You can make a diary entry for a specific date by selecting that date
-in the calendar window and typing the @kbd{i d} command. This command
-displays the end of your diary file in another window and inserts the
-date; you can then type the rest of the diary entry.
-
-@kindex i w @r{(Calendar mode)}
-@findex insert-weekly-diary-entry
-@kindex i m @r{(Calendar mode)}
-@findex insert-monthly-diary-entry
-@kindex i y @r{(Calendar mode)}
-@findex insert-yearly-diary-entry
- If you want to make a diary entry that applies to a specific day of
-the week, select that day of the week (any occurrence will do) and type
-@kbd{i w}. This inserts the day-of-week as a generic date; you can then
-type the rest of the diary entry. You can make a monthly diary entry in
-the same fashion: select the day of the month, use the @kbd{i m}
-command, and type the rest of the entry. Similarly, you can insert a
-yearly diary entry with the @kbd{i y} command.
-
- All of the above commands make marking diary entries by default. To
-make a nonmarking diary entry, give a numeric argument to the command.
-For example, @kbd{C-u i w} makes a nonmarking weekly diary entry.
-
- When you modify the diary file, be sure to save the file before
-exiting Emacs. Saving the diary file after using any of the above
-insertion commands will automatically update the diary marks in the
-calendar window, if appropriate. You can use the command
-@code{redraw-calendar} to force an update at any time.
-
-@node Special Diary Entries
-@subsection Special Diary Entries
-
- In addition to entries based on calendar dates, the diary file can
-contain @dfn{sexp entries} for regular events such as anniversaries.
-These entries are based on Lisp expressions (sexps) that Emacs evaluates
-as it scans the diary file. Instead of a date, a sexp entry contains
-@samp{%%} followed by a Lisp expression which must begin and end with
-parentheses. The Lisp expression determines which dates the entry
-applies to.
-
- Calendar mode provides commands to insert certain commonly used
-sexp entries:
-
-@table @kbd
-@item i a
-Add an anniversary diary entry for the selected date
-(@code{insert-anniversary-diary-entry}).
-@item i b
-Add a block diary entry for the current region
-(@code{insert-block-diary-entry}).
-@item i c
-Add a cyclic diary entry starting at the date
-(@code{insert-cyclic-diary-entry}).
-@end table
-
-@kindex i a @r{(Calendar mode)}
-@findex insert-anniversary-diary-entry
- If you want to make a diary entry that applies to the anniversary of a
-specific date, move point to that date and use the @kbd{i a} command.
-This displays the end of your diary file in another window and inserts
-the anniversary description; you can then type the rest of the diary
-entry. The entry looks like this:
-
-@findex diary-anniversary
-@example
-%%(diary-anniversary 10 31 1948) Arthur's birthday
-@end example
-
-@noindent
-This entry applies to October 31 in any year after 1948; @samp{10 31
-1948} specifies the date. (If you are using the European calendar
-style, the month and day are interchanged.) The reason this expression
-requires a beginning year is that advanced diary functions can use it to
-calculate the number of elapsed years.
-
- A @dfn{block} diary entry applies to a specified range of consecutive
-dates. Here is a block diary entry that applies to all dates from June
-24, 1990 through July 10, 1990:
-
-@findex diary-block
-@example
-%%(diary-block 6 24 1990 7 10 1990) Vacation
-@end example
-
-@noindent
-The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990}
-indicates the stopping date. (Again, if you are using the European calendar
-style, the month and day are interchanged.)
-
-@kindex i b @r{(Calendar mode)}
-@findex insert-block-diary-entry
- To insert a block entry, place point and the mark on the two
-dates that begin and end the range, and type @kbd{i b}. This command
-displays the end of your diary file in another window and inserts the
-block description; you can then type the diary entry.
-
-@kindex i c @r{(Calendar mode)}
-@findex insert-cyclic-diary-entry
- @dfn{Cyclic} diary entries repeat after a fixed interval of days. To
-create one, select the starting date and use the @kbd{i c} command. The
-command prompts for the length of interval, then inserts the entry,
-which looks like this:
-
-@findex diary-cyclic
-@example
-%%(diary-cyclic 50 3 1 1990) Renew medication
-@end example
-
-@noindent
-This entry applies to March 1, 1990 and every 50th day following;
-@samp{3 1 1990} specifies the starting date. (If you are using the
-European calendar style, the month and day are interchanged.)
-
- All three of these commands make marking diary entries. To insert a
-nonmarking entry, give a numeric argument to the command. For example,
-@kbd{C-u i a} makes a nonmarking anniversary diary entry.
-
- Marking sexp diary entries in the calendar is @emph{extremely}
-time-consuming, since every date visible in the calendar window must be
-individually checked. So it's a good idea to make sexp diary entries
-nonmarking (with @samp{&}) when possible.
-
- Another sophisticated kind of sexp entry, a @dfn{floating} diary entry,
-specifies a regularly occurring event by offsets specified in days,
-weeks, and months. It is comparable to a crontab entry interpreted by
-the @code{cron} utility. Here is a nonmarking, floating diary entry
-that applies to the last Thursday in November:
-
-@findex diary-float
-@example
-&%%(diary-float 11 4 -1) American Thanksgiving
-@end example
-
-@noindent
-The 11 specifies November (the eleventh month), the 4 specifies Thursday
-(the fourth day of the week, where Sunday is numbered zero), and the
-@minus{}1 specifies ``last'' (1 would mean ``first,'' 2 would mean
-``second,'' @minus{}2 would mean ``second-to-last,'' and so on). The
-month can be a single month or a list of months. Thus you could change
-the 11 above to @samp{'(1 2 3)} and have the entry apply to the last
-Thursday of January, February, and March. If the month is @code{t}, the
-entry applies to all months of the year.@refill
-
- Each of the standard sexp diary entries takes an optional parameter
-specifying the name of a face or a single-character string to use when
-marking the entry in the calendar. Most generally, sexp diary entries
-can perform arbitrary computations to determine when they apply.
-@iftex
-@inforef{Sexp Diary Entries,, emacs-xtra}.
-@end iftex
-@ifnottex
-@inforef{Sexp Diary Entries}.
-@end ifnottex
-
-@node Appointments
-@section Appointments
-@cindex appointment notification
-
-@vindex appt-display-format
-@vindex appt-audible
-@vindex appt-display-mode-line
- If you have a diary entry for an appointment, and that diary entry
-begins with a recognizable time of day, Emacs can warn you several
-minutes beforehand that that appointment is pending. Emacs alerts you
-to the appointment by displaying a message in your chosen format, as
-specified by the variable @code{appt-display-format}. If the value of
-@code{appt-audible} is non-@code{nil}, the warning includes an audible
-reminder. In addition, if @code{appt-display-mode-line} is
-non-@code{nil}, Emacs displays the number of minutes to the
-appointment on the mode line.
-
-@vindex appt-display-duration
-@vindex appt-disp-window-function
-@vindex appt-delete-window-function
- If @code{appt-display-format} has the value @code{window}, then the
-variable @code{appt-display-duration} controls how long the reminder
-window is visible for; and the variables
-@code{appt-disp-window-function} and @code{appt-delete-window-function}
-give the names of functions used to create and destroy the window,
-respectively.
-
-@findex appt-activate
- To enable appointment notification, use the command @kbd{M-x
-appt-activate}. With a positive argument, it enables notification;
-with a negative argument, it disables notification; with no argument,
-it toggles. Enabling notification also sets up an appointment list
-for today from the diary file, giving all diary entries found with
-recognizable times of day, and reminds you just before each of them.
-
- For example, suppose the diary file contains these lines:
-
-@example
-Monday
- 9:30am Coffee break
- 12:00pm Lunch
-@end example
-
-@vindex appt-message-warning-time
-@noindent
-Then on Mondays, you will be reminded at around 9:20am about your
-coffee break and at around 11:50am about lunch. The variable
-@code{appt-message-warning-time} specifies how many minutes in advance
-to warn you; its default value is 12 (12 minutes).
-
- You can write times in am/pm style (with @samp{12:00am} standing
-for midnight and @samp{12:00pm} standing for noon), or 24-hour
-European/military style. You need not be consistent; your diary file
-can have a mixture of the two styles. Times must be at the beginning
-of lines if they are to be recognized.
-
-@vindex appt-display-diary
- Emacs updates the appointments list from the diary file
-automatically just after midnight. You can force an update at any
-time by re-enabling appointment notification. Both these actions also
-display the day's diary buffer, unless you set
-@code{appt-display-diary} to @code{nil}. The appointments list is
-also updated whenever the diary file is saved.
-
-@findex appt-add
-@findex appt-delete
-@cindex alarm clock
- You can also use the appointment notification facility like an alarm
-clock. The command @kbd{M-x appt-add} adds entries to the appointment
-list without affecting your diary file. You delete entries from the
-appointment list with @kbd{M-x appt-delete}.
-
-@node Importing Diary
-@section Importing and Exporting Diary Entries
-
- You can transfer diary entries between Emacs diary files and a
-variety of other formats.
-
-@vindex diary-outlook-formats
- You can import diary entries from Outlook-generated appointment
-messages. While viewing such a message in Rmail or Gnus, do @kbd{M-x
-diary-from-outlook} to import the entry. You can make this command
-recognize additional appointment message formats by customizing the
-variable @code{diary-outlook-formats}.
-
-@cindex iCalendar support
- The icalendar package allows you to transfer data between your Emacs
-diary file and iCalendar files, which are defined in ``RFC
-2445---Internet Calendaring and Scheduling Core Object Specification
-(iCalendar)'' (as well as the earlier vCalendar format).
-
- Importing works for ``ordinary'' (i.e. non-recurring) events, but
-(at present) may not work correctly (if at all) for recurring events.
-Exporting of diary files into iCalendar files should work correctly
-for most diary entries. This feature is a work in progress, so the
-commands may evolve in future.
-
-@findex icalendar-import-buffer
- The command @code{icalendar-import-buffer} extracts
-iCalendar data from the current buffer and adds it to your (default)
-diary file. This function is also suitable for automatic extraction of
-iCalendar data; for example with the Rmail mail client one could use:
-
-@example
-(add-hook 'rmail-show-message-hook 'icalendar-import-buffer)
-@end example
-
-@findex icalendar-import-file
- The command @code{icalendar-import-file} imports an iCalendar file
-and adds the results to an Emacs diary file. For example:
-
-@example
-(icalendar-import-file "/here/is/calendar.ics"
- "/there/goes/ical-diary")
-@end example
-
-@noindent
-You can use an @code{#include} directive to add the import file contents
-to the main diary file, if these are different files.
-@iftex
-@inforef{Fancy Diary Display,, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Fancy Diary Display}.
-@end ifnottex
-
-
-@findex icalendar-export-file, icalendar-export-region
- Use @code{icalendar-export-file} to interactively export an entire
-Emacs diary file to iCalendar format. To export only a part of a diary
-file, mark the relevant area, and call @code{icalendar-export-region}.
-In both cases the result is appended to the target file.
-
-@node Daylight Saving
-@section Daylight Saving Time
-@cindex daylight saving time
-
- Emacs understands the difference between standard time and daylight
-saving time---the times given for sunrise, sunset, solstices,
-equinoxes, and the phases of the moon take that into account. The rules
-for daylight saving time vary from place to place and have also varied
-historically from year to year. To do the job properly, Emacs needs to
-know which rules to use.
-
-@vindex calendar-daylight-savings-starts
-@vindex calendar-daylight-savings-ends
- Some operating systems keep track of the rules that apply to the place
-where you are; on these systems, Emacs gets the information it needs
-from the system automatically. If some or all of this information is
-missing, Emacs fills in the gaps with the rules currently used in
-Cambridge, Massachusetts. If the resulting rules are not what you want,
-you can tell Emacs the rules to use by setting certain variables:
-@code{calendar-daylight-savings-starts} and
-@code{calendar-daylight-savings-ends}.
-
- These values should be Lisp expressions that refer to the variable
-@code{year}, and evaluate to the Gregorian date on which daylight
-saving time starts or (respectively) ends, in the form of a list
-@code{(@var{month} @var{day} @var{year})}. The values should be
-@code{nil} if your area does not use daylight saving time.
-
- Emacs uses these expressions to determine the starting date of
-daylight saving time for the holiday list and for correcting times of
-day in the solar and lunar calculations.
-
- The values for Cambridge, Massachusetts are as follows:
-
-@example
-(calendar-nth-named-day 2 0 3 year)
-(calendar-nth-named-day 1 0 11 year)
-@end example
-
-@noindent
-That is, the second 0th day (Sunday) of the third month (March) in
-the year specified by @code{year}, and the first Sunday of the eleventh month
-(November) of that year. If daylight saving time were
-changed to start on October 1, you would set
-@code{calendar-daylight-savings-starts} to this:
-
-@example
-(list 10 1 year)
-@end example
-
- If there is no daylight saving time at your location, or if you want
-all times in standard time, set @code{calendar-daylight-savings-starts}
-and @code{calendar-daylight-savings-ends} to @code{nil}.
-
-@vindex calendar-daylight-time-offset
- The variable @code{calendar-daylight-time-offset} specifies the
-difference between daylight saving time and standard time, measured in
-minutes. The value for Cambridge, Massachusetts is 60.
-
-@c @vindex calendar-daylight-savings-starts-time too long!
-@vindex calendar-daylight-savings-ends-time
- Finally, the two variables
-@code{calendar-daylight-savings-starts-time} and
-@code{calendar-daylight-savings-ends-time} specify the number of
-minutes after midnight local time when the transition to and from
-daylight saving time should occur. For Cambridge, Massachusetts both
-variables' values are 120.
-
-@node Time Intervals
-@section Summing Time Intervals
-@cindex time intervals, summing
-@cindex summing time intervals
-@cindex timeclock
-
- The timeclock feature adds up time intervals, so you can (for
-instance) keep track of how much time you spend working on particular
-projects.
-
-@findex timeclock-in
-@findex timeclock-out
-@findex timeclock-change
-@findex timeclock-workday-remaining
-@findex timeclock-when-to-leave
- Use the @kbd{M-x timeclock-in} command when you start working on a
-project, and @kbd{M-x timeclock-out} command when you're done. Each
-time you do this, it adds one time interval to the record of the
-project. You can change to working on a different project with @kbd{M-x
-timeclock-change}.
-
- Once you've collected data from a number of time intervals, you can use
-@kbd{M-x timeclock-workday-remaining} to see how much time is left to
-work today (assuming a typical average of 8 hours a day), and @kbd{M-x
-timeclock-when-to-leave} which will calculate when you're ``done.''
-
-@vindex timeclock-modeline-display
-@findex timeclock-modeline-display
- If you want Emacs to display the amount of time ``left'' of your
-workday in the mode line, either customize the
-@code{timeclock-modeline-display} variable and set its value to
-@code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command.
-
-@vindex timeclock-ask-before-exiting
- Terminating the current Emacs session might or might not mean that
-you have stopped working on the project and, by default, Emacs asks
-you. You can, however, set the value of the variable
-@code{timeclock-ask-before-exiting} to @code{nil} (via @kbd{M-x
-customize}) to avoid the question; then, only an explicit @kbd{M-x
-timeclock-out} or @kbd{M-x timeclock-change} will tell Emacs that the
-current interval is over.
-
-@cindex @file{.timelog} file
-@vindex timeclock-file
-@findex timeclock-reread-log
- The timeclock functions work by accumulating the data in a file
-called @file{.timelog} in your home directory. You can specify a
-different name for this file by customizing the variable
-@code{timeclock-file}. If you edit the timeclock file manually, or if
-you change the value of any of timeclock's customizable variables, you
-should run the command @kbd{M-x timeclock-reread-log} to update the
-data in Emacs from the file.
-
-@ifnottex
-@include cal-xtra.texi
-@end ifnottex
-
-@ignore
- arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Emacs Invocation, X Resources, GNU Free Documentation License, Top
-@appendix Command Line Arguments for Emacs Invocation
-@cindex command line arguments
-@cindex arguments (command line)
-@cindex options (command line)
-@cindex switches (command line)
-@cindex startup (command line arguments)
-@cindex invocation (command line arguments)
-
- GNU Emacs supports command line arguments to request various actions
-when invoking Emacs. These are for compatibility with other editors and
-for sophisticated activities. We don't recommend using them for
-ordinary editing.
-
- Arguments starting with @samp{-} are @dfn{options}, and so is
-@samp{+@var{linenum}}. All other arguments specify files to visit.
-Emacs visits the specified files while it starts up. The last file
-name on your command line becomes the current buffer; the other files
-are also visited in other buffers. If there are two files, they are
-both displayed; otherwise the last file is displayed along with a
-buffer list that shows what other buffers there are. As with most
-programs, the special argument @samp{--} says that all subsequent
-arguments are file names, not options, even if they start with
-@samp{-}.
-
- Emacs command options can specify many things, such as the size and
-position of the X window Emacs uses, its colors, and so on. A few
-options support advanced usage, such as running Lisp functions on files
-in batch mode. The sections of this chapter describe the available
-options, arranged according to their purpose.
-
- There are two ways of writing options: the short forms that start with
-a single @samp{-}, and the long forms that start with @samp{--}. For
-example, @samp{-d} is a short form and @samp{--display} is the
-corresponding long form.
-
- The long forms with @samp{--} are easier to remember, but longer to
-type. However, you don't have to spell out the whole option name; any
-unambiguous abbreviation is enough. When a long option takes an
-argument, you can use either a space or an equal sign to separate the
-option name and the argument. Thus, you can write either
-@samp{--display sugar-bombs:0.0} or @samp{--display=sugar-bombs:0.0}.
-We recommend an equal sign because it makes the relationship clearer,
-and the tables below always show an equal sign.
-
-@cindex initial options (command line)
-@cindex action options (command line)
-@vindex command-line-args
- Most options specify how to initialize Emacs, or set parameters for
-the Emacs session. We call them @dfn{initial options}. A few options
-specify things to do: for example, load libraries, call functions, or
-terminate Emacs. These are called @dfn{action options}. These and file
-names together are called @dfn{action arguments}. Emacs processes all
-the action arguments in the order they are written. The @file{.emacs} file
-can access the values of the action arguments as the elements of a list in
-the variable @code{command-line-args}.
-
-
-
-@menu
-* Action Arguments:: Arguments to visit files, load libraries,
- and call functions.
-* Initial Options:: Arguments that take effect while starting Emacs.
-* Command Example:: Examples of using command line arguments.
-* Resume Arguments:: Specifying arguments when you resume a running Emacs.
-* Environment:: Environment variables that Emacs uses.
-* Display X:: Changing the default display and using remote login.
-* Font X:: Choosing a font for text, under X.
-* Colors:: Choosing display colors.
-* Window Size X:: Start-up window size, under X.
-* Borders X:: Internal and external borders, under X.
-* Title X:: Specifying the initial frame's title.
-* Icons X:: Choosing what sort of icon to use, under X.
-* Misc X:: Other display options.
-@end menu
-
-@node Action Arguments
-@appendixsec Action Arguments
-
- Here is a table of the action arguments and options:
-
-@table @samp
-@item @var{file}
-@opindex --file
-@itemx --file=@var{file}
-@opindex --find-file
-@itemx --find-file=@var{file}
-@opindex --visit
-@itemx --visit=@var{file}
-@cindex visiting files, command-line argument
-@vindex inhibit-startup-buffer-menu
-Visit @var{file} using @code{find-file}. @xref{Visiting}.
-If you visit several files at startup in this way, Emacs
-also displays a Buffer Menu buffer to show you what files it
-has visited. You can inhibit that by setting @code{inhibit-startup-buffer-menu} to @code{t}.
-
-@item +@var{linenum} @var{file}
-@opindex +@var{linenum}
-Visit @var{file} using @code{find-file}, then go to line number
-@var{linenum} in it.
-
-@item +@var{linenum}:@var{columnnum} @var{file}
-Visit @var{file} using @code{find-file}, then go to line number
-@var{linenum} and put point at column number @var{columnnum}.
-
-@need 3000
-@item -l @var{file}
-@opindex -l
-@itemx --load=@var{file}
-@opindex --load
-@cindex loading Lisp libraries, command-line argument
-Load a Lisp library named @var{file} with the function @code{load}.
-@xref{Lisp Libraries}. If @var{file} is not an absolute file name,
-the library can be found either in the current directory, or in the
-Emacs library search path as specified with @env{EMACSLOADPATH}
-(@pxref{General Variables}).
-
-@strong{Warning:} If previous command-line arguments have visited
-files, the current directory is the directory of the last file
-visited.
-
-@item -L @var{dir}
-@opindex -L
-@itemx --directory=@var{dir}
-@opindex --directory
-Add directory @var{dir} to the variable @code{load-path}.
-
-@item -f @var{function}
-@opindex -f
-@itemx --funcall=@var{function}
-@opindex --funcall
-@cindex call Lisp functions, command-line argument
-Call Lisp function @var{function}. If it is an interactive function
-(a command), it reads the arguments interactively just as if you had
-called the same function with a key sequence. Otherwise, it calls the
-function with no arguments.
-
-@item --eval=@var{expression}
-@opindex --eval
-@itemx --execute=@var{expression}
-@opindex --execute
-@cindex evaluate expression, command-line argument
-Evaluate Lisp expression @var{expression}.
-
-@item --insert=@var{file}
-@opindex --insert
-@cindex insert file contents, command-line argument
-Insert the contents of @var{file} into the current buffer. This is like
-what @kbd{M-x insert-file} does. @xref{Misc File Ops}.
-
-@item --kill
-@opindex --kill
-Exit from Emacs without asking for confirmation.
-
-@item --help
-@opindex --help
-Print a usage message listing all available options, then exit
-successfully.
-
-@item --version
-@opindex --version
-Print Emacs version, then exit successfully.
-@end table
-
-@node Initial Options
-@appendixsec Initial Options
-
- The initial options specify parameters for the Emacs session. This
-section describes the more general initial options; some other options
-specifically related to the X Window System appear in the following
-sections.
-
- Some initial options affect the loading of init files. The normal
-actions of Emacs are to first load @file{site-start.el} if it exists,
-then your own init file @file{~/.emacs} if it exists, and finally
-@file{default.el} if it exists. @xref{Init File}. Certain options
-prevent loading of some of these files or substitute other files for
-them.
-
-@table @samp
-@item -t @var{device}
-@opindex -t
-@itemx --terminal=@var{device}
-@opindex --terminal
-@cindex device for Emacs terminal I/O
-Use @var{device} as the device for terminal input and output.
-@samp{--terminal} implies @samp{--no-window-system}.
-
-@item -d @var{display}
-@opindex -d
-@itemx --display=@var{display}
-@opindex --display
-@cindex display for Emacs frame
-Use the X Window System and use the display named @var{display} to open
-the initial Emacs frame. @xref{Display X}, for more details.
-
-@item -nw
-@opindex -nw
-@itemx --no-window-system
-@opindex --no-window-system
-@cindex disable window system
-Don't communicate directly with the window system, disregarding the
-@env{DISPLAY} environment variable even if it is set. This means that
-Emacs uses the terminal from which it was launched for all its display
-and input.
-
-@need 3000
-@cindex batch mode
-@item -batch
-@opindex --batch
-@itemx --batch
-Run Emacs in @dfn{batch mode}. Batch mode is used for running
-programs written in Emacs Lisp from shell scripts, makefiles, and so
-on. You should also use the @samp{-l}, @samp{-f} or @samp{--eval}
-option, to invoke a Lisp program to do batch processing.
-
-In batch mode, Emacs does not display the text being edited, and the
-standard terminal interrupt characters such as @kbd{C-z} and @kbd{C-c}
-continue to have their normal effect. The functions @code{prin1},
-@code{princ} and @code{print} output to @code{stdout} instead of the
-echo area, while @code{message} and error messages output to
-@code{stderr}. Functions that would normally read from the minibuffer
-take their input from @code{stdin} instead.
-
-@samp{--batch} implies @samp{-q} (do not load an init file), but
-@file{site-start.el} is loaded nonetheless. It also causes Emacs to
-exit after processing all the command options. In addition, it
-disables auto-saving except in buffers for which it has been
-explicitly requested.
-
-@item --script @var{file}
-@opindex --script
-@cindex script mode
-Run Emacs in batch mode, like @samp{--batch}, and then read and
-execute the Lisp code in @var{file}.
-
-The normal use of this option is in executable script files that run
-Emacs. They can start with this text on the first line
-
-@example
-#!/usr/bin/emacs --script
-@end example
-
-@noindent
-which will invoke Emacs with @samp{--script} and supply the name of
-the script file as @var{file}. Emacs Lisp then treats @samp{#!} as a
-comment delimiter.
-
-@item -q
-@opindex -q
-@itemx --no-init-file
-@opindex --no-init-file
-@cindex bypassing init and @file{default.el} file
-@cindex init file, not loading
-@cindex @file{default.el} file, not loading
-Do not load your Emacs init file @file{~/.emacs}, or @file{default.el}
-either. Regardless of this switch, @file{site-start.el} is still loaded.
-When invoked like this, Emacs does not allow saving options
-changed with the @kbd{M-x customize} command and its variants.
-@xref{Easy Customization}.
-
-@item --no-site-file
-@opindex --no-site-file
-@cindex @file{site-start.el} file, not loading
-Do not load @file{site-start.el}. The options @samp{-q}, @samp{-u}
-and @samp{--batch} have no effect on the loading of this file---this
-option and @samp{-Q} are the only options that block it.
-
-@item -Q
-@opindex -Q
-@itemx --quick
-@opindex --quick
-Start emacs with minimum customizations. This is like using @samp{-q}
-and @samp{--no-site-file}, but also disables the startup screen.
-
-@item --no-splash
-@opindex --no-splash
-@vindex inhibit-splash-screen
-@cindex splash screen
-@cindex startup message
-Do not display a splash screen on startup. You can also achieve this
-effect by setting the variable @code{inhibit-splash-screen} to
-non-@code{nil} in you personal init file (but @emph{not} in
-@file{site-start.el}). (This variable was called
-@code{inhibit-startup-message} in previous Emacs versions.)
-
-@item --no-desktop
-@opindex --no-desktop
-Do not reload any saved desktop. @xref{Saving Emacs Sessions}.
-
-@item -u @var{user}
-@opindex -u
-@itemx --user=@var{user}
-@opindex --user
-@cindex load init file of another user
-Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of
-your own@footnote{
-This option has no effect on MS-Windows.}.
-
-@item --debug-init
-@opindex --debug-init
-@cindex errors in init file
-Enable the Emacs Lisp debugger for errors in the init file.
-@xref{Error Debugging,, Entering the Debugger on an Error, elisp, The
-GNU Emacs Lisp Reference Manual}.
-
-@item --unibyte
-@opindex --unibyte
-@itemx --no-multibyte
-@opindex --no-multibyte
-@cindex unibyte operation, command-line argument
-Do almost everything with single-byte buffers and strings.
-All buffers and strings are unibyte unless you (or a Lisp program)
-explicitly ask for a multibyte buffer or string. (Note that Emacs
-always loads Lisp files in multibyte mode, even if @samp{--unibyte} is
-specified; see @ref{Enabling Multibyte}.) Setting the environment
-variable @env{EMACS_UNIBYTE} has the same effect
-(@pxref{General Variables}).
-
-@item --multibyte
-@opindex --multibyte
-@itemx --no-unibyte
-@opindex --no-unibyte
-Inhibit the effect of @env{EMACS_UNIBYTE}, so that Emacs
-uses multibyte characters by default, as usual.
-@end table
-
-@node Command Example
-@appendixsec Command Argument Example
-
- Here is an example of using Emacs with arguments and options. It
-assumes you have a Lisp program file called @file{hack-c.el} which, when
-loaded, performs some useful operation on the current buffer, expected
-to be a C program.
-
-@example
-emacs --batch foo.c -l hack-c -f save-buffer >& log
-@end example
-
-@noindent
-This says to visit @file{foo.c}, load @file{hack-c.el} (which makes
-changes in the visited file), save @file{foo.c} (note that
-@code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
-then exit back to the shell (because of @samp{--batch}). @samp{--batch}
-also guarantees there will be no problem redirecting output to
-@file{log}, because Emacs will not assume that it has a display terminal
-to work with.
-
-@node Resume Arguments
-@appendixsec Resuming Emacs with Arguments
-
- You can specify action arguments for Emacs when you resume it after
-a suspension. To prepare for this, put the following code in your
-@file{.emacs} file (@pxref{Hooks}):
-
-@c `resume-suspend-hook' is correct. It is the name of a function.
-@example
-(add-hook 'suspend-hook 'resume-suspend-hook)
-(add-hook 'suspend-resume-hook 'resume-process-args)
-@end example
-
- As further preparation, you must execute the shell script
-@file{emacs.csh} (if you use csh as your shell) or @file{emacs.bash}
-(if you use bash as your shell). These scripts define an alias named
-@code{edit}, which will resume Emacs giving it new command line
-arguments such as files to visit. The scripts are found in the
-@file{etc} subdirectory of the Emacs distribution.
-
- Only action arguments work properly when you resume Emacs. Initial
-arguments are not recognized---it's too late to execute them anyway.
-
- Note that resuming Emacs (with or without arguments) must be done from
-within the shell that is the parent of the Emacs job. This is why
-@code{edit} is an alias rather than a program or a shell script. It is
-not possible to implement a resumption command that could be run from
-other subjobs of the shell; there is no way to define a command that could
-be made the value of @env{EDITOR}, for example. Therefore, this feature
-does not take the place of the Emacs Server feature (@pxref{Emacs
-Server}).
-
- The aliases use the Emacs Server feature if you appear to have a
-server Emacs running. However, they cannot determine this with complete
-accuracy. They may think that a server is still running when in
-actuality you have killed that Emacs, because the file
-@file{/tmp/esrv@dots{}} still exists. If this happens, find that
-file and delete it.
-
-@node Environment
-@appendixsec Environment Variables
-@cindex environment variables
-
- The @dfn{environment} is a feature of the operating system; it
-consists of a collection of variables with names and values. Each
-variable is called an @dfn{environment variable}; environment variable
-names are case-sensitive, and it is conventional to use upper case
-letters only. The values are all text strings.
-
- What makes the environment useful is that subprocesses inherit the
-environment automatically from their parent process. This means you
-can set up an environment variable in your login shell, and all the
-programs you run (including Emacs) will automatically see it.
-Subprocesses of Emacs (such as shells, compilers, and version-control
-software) inherit the environment from Emacs, too.
-
-@findex setenv
-@findex getenv
- Inside Emacs, the command @kbd{M-x getenv} gets the value of an
-environment variable. @kbd{M-x setenv} sets a variable in the Emacs
-environment. (Environment variable substitutions with @samp{$} work
-in the value just as in file names; see @ref{File Names with $}.)
-
- The way to set environment variables outside of Emacs depends on the
-operating system, and especially the shell that you are using. For
-example, here's how to set the environment variable @env{ORGANIZATION}
-to @samp{not very much} using Bash:
-
-@example
-export ORGANIZATION="not very much"
-@end example
-
-@noindent
-and here's how to do it in csh or tcsh:
-
-@example
-setenv ORGANIZATION "not very much"
-@end example
-
- When Emacs is using the X Window System, various environment
-variables that control X work for Emacs as well. See the X
-documentation for more information.
-
-@menu
-* General Variables:: Environment variables that all versions of Emacs use.
-* Misc Variables:: Certain system-specific variables.
-* MS-Windows Registry:: An alternative to the environment on MS-Windows.
-@end menu
-
-@node General Variables
-@appendixsubsec General Variables
-
- Here is an alphabetical list of specific environment variables that
-have special meanings in Emacs, giving the name of each variable and
-its meaning. Most of these variables are also used by some other
-programs. Emacs does not require any of these environment variables
-to be set, but it uses their values if they are set.
-
-@table @env
-@item CDPATH
-Used by the @code{cd} command to search for the directory you specify,
-when you specify a relative directory name.
-@item EMACS_UNIBYTE
-@cindex unibyte operation, environment variable
-Defining this environment variable with a nonempty value directs Emacs
-to do almost everything with single-byte buffers and strings. It is
-equivalent to using the @samp{--unibyte} command-line option on each
-invocation. @xref{Initial Options}.
-@item EMACSDATA
-Directory for the architecture-independent files that come with Emacs.
-This is used to initialize the Lisp variable @code{data-directory}.
-@item EMACSDOC
-Directory for the documentation string file,
-@file{DOC-@var{emacsversion}}. This is used to initialize the Lisp
-variable @code{doc-directory}.
-@item EMACSLOADPATH
-A colon-separated list of directories@footnote{
-Here and below, whenever we say ``colon-separated list of directories,''
-it pertains to Unix and GNU/Linux systems. On MS-DOS and MS-Windows,
-the directories are separated by semi-colons instead, since DOS/Windows
-file names might include a colon after a drive letter.}
-to search for Emacs Lisp files---used to initialize @code{load-path}.
-@item EMACSPATH
-A colon-separated list of directories to search for executable
-files---used to initialize @code{exec-path}.
-@item EMAIL
-@vindex user-mail-address@r{, initialization}
-Your email address; used to initialize the Lisp variable
-@code{user-mail-address}, which the Emacs mail interface puts into
-the @samp{From} header of outgoing messages (@pxref{Mail Headers}).
-@item ESHELL
-Used for shell-mode to override the @env{SHELL} environment variable.
-@item HISTFILE
-The name of the file that shell commands are saved in between logins.
-This variable defaults to @file{~/.bash_history} if you use Bash, to
-@file{~/.sh_history} if you use ksh, and to @file{~/.history}
-otherwise.
-@item HOME
-The location of your files in the directory tree; used for
-expansion of file names starting with a tilde (@file{~}). On MS-DOS,
-it defaults to the directory from which Emacs was started, with
-@samp{/bin} removed from the end if it was present. On Windows, the
-default value of @env{HOME} is the @file{Application Data}
-subdirectory of the user profile directory (normally, this is
-@file{C:/Documents and Settings/@var{username}/Application Data},
-where @var{username} is your user name), though for backwards
-compatibility @file{C:/} will be used instead if a @file{.emacs} file
-is found there.
-@item HOSTNAME
-The name of the machine that Emacs is running on.
-@item INCPATH
-A colon-separated list of directories. Used by the @code{complete} package
-to search for files.
-@item INFOPATH
-A colon-separated list of directories in which to search for Info files.
-@item LC_ALL
-@itemx LC_COLLATE
-@itemx LC_CTYPE
-@itemx LC_MESSAGES
-@itemx LC_MONETARY
-@itemx LC_NUMERIC
-@itemx LC_TIME
-@itemx LANG
-The user's preferred locale. The locale has six categories, specified
-by the environment variables @env{LC_COLLATE} for sorting,
-@env{LC_CTYPE} for character encoding, @env{LC_MESSAGES} for system
-messages, @env{LC_MONETARY} for monetary formats, @env{LC_NUMERIC} for
-numbers, and @env{LC_TIME} for dates and times. If one of these
-variables is not set, the category defaults to the value of the
-@env{LANG} environment variable, or to the default @samp{C} locale if
-@env{LANG} is not set. But if @env{LC_ALL} is specified, it overrides
-the settings of all the other locale environment variables.
-
-On MS-Windows, if @env{LANG} is not already set in the environment
-when Emacs starts, Emacs sets it based on the system-wide default
-language, which you can set in the @samp{Regional Settings} Control Panel
-on some versions of MS-Windows.
-
-The value of the @env{LC_CTYPE} category is
-matched against entries in @code{locale-language-names},
-@code{locale-charset-language-names}, and
-@code{locale-preferred-coding-systems}, to select a default language
-environment and coding system. @xref{Language Environments}.
-@item LOGNAME
-The user's login name. See also @env{USER}.
-@item MAIL
-The name of your system mail inbox.
-@item MH
-Name of setup file for the mh system. (The default is @file{~/.mh_profile}.)
-@item NAME
-Your real-world name.
-@item NNTPSERVER
-The name of the news server. Used by the mh and Gnus packages.
-@item ORGANIZATION
-The name of the organization to which you belong. Used for setting the
-`Organization:' header in your posts from the Gnus package.
-@item PATH
-A colon-separated list of directories in which executables reside. This
-is used to initialize the Emacs Lisp variable @code{exec-path}.
-@item PWD
-If set, this should be the default directory when Emacs was started.
-@item REPLYTO
-If set, this specifies an initial value for the variable
-@code{mail-default-reply-to}. @xref{Mail Headers}.
-@item SAVEDIR
-The name of a directory in which news articles are saved by default.
-Used by the Gnus package.
-@item SHELL
-The name of an interpreter used to parse and execute programs run from
-inside Emacs.
-@item SMTPSERVER
-The name of the outgoing mail server. Used by the SMTP library
-(@pxref{Top,,,smtpmail,Sending mail via SMTP}).
-@cindex background mode, on @command{xterm}
-@item TERM
-The type of the terminal that Emacs is using. This variable must be
-set unless Emacs is run in batch mode. On MS-DOS, it defaults to
-@samp{internal}, which specifies a built-in terminal emulation that
-handles the machine's own display. If the value of @env{TERM} indicates
-that Emacs runs in non-windowed mode from @command{xterm} or a similar
-terminal emulator, the background mode defaults to @samp{light}, and
-Emacs will choose colors that are appropriate for a light background.
-@item TERMCAP
-The name of the termcap library file describing how to program the
-terminal specified by the @env{TERM} variable. This defaults to
-@file{/etc/termcap}.
-@item TMPDIR
-Used by the Emerge package as a prefix for temporary files.
-@item TZ
-This specifies the current time zone and possibly also daylight
-saving time information. On MS-DOS, if @env{TZ} is not set in the
-environment when Emacs starts, Emacs defines a default value as
-appropriate for the country code returned by DOS. On MS-Windows, Emacs
-does not use @env{TZ} at all.
-@item USER
-The user's login name. See also @env{LOGNAME}. On MS-DOS, this
-defaults to @samp{root}.
-@item VERSION_CONTROL
-Used to initialize the @code{version-control} variable (@pxref{Numbered Backups}).
-@end table
-
-@node Misc Variables
-@appendixsubsec Miscellaneous Variables
-
-These variables are used only on particular configurations:
-
-@table @env
-@item COMSPEC
-On MS-DOS and MS-Windows, the name of the command interpreter to use
-when invoking batch files and commands internal to the shell. On MS-DOS
-this is also used to make a default value for the @env{SHELL} environment
-variable.
-
-@item NAME
-On MS-DOS, this variable defaults to the value of the @env{USER}
-variable.
-
-@item TEMP
-@itemx TMP
-On MS-DOS and MS-Windows, these specify the name of the directory for
-storing temporary files in.
-
-@item EMACSTEST
-On MS-DOS, this specifies a file to use to log the operation of the
-internal terminal emulator. This feature is useful for submitting bug
-reports.
-
-@item EMACSCOLORS
-On MS-DOS, this specifies the screen colors. It is useful to set them
-this way, since otherwise Emacs would display the default colors
-momentarily when it starts up.
-
-The value of this variable should be the two-character encoding of the
-foreground (the first character) and the background (the second
-character) colors of the default face. Each character should be the
-hexadecimal code for the desired color on a standard PC text-mode
-display. For example, to get blue text on a light gray background,
-specify @samp{EMACSCOLORS=17}, since 1 is the code of the blue color and
-7 is the code of the light gray color.
-
-The PC display usually supports only eight background colors. However,
-Emacs switches the DOS display to a mode where all 16 colors can be used
-for the background, so all four bits of the background color are
-actually used.
-
-@item WINDOW_GFX
-Used when initializing the Sun windows system.
-
-@item PRELOAD_WINSOCK
-On MS-Windows, if you set this variable, Emacs will load and initialize
-the network library at startup, instead of waiting until the first
-time it is required.
-
-@item emacs_dir
-On MS-Windows, @env{emacs_dir} is a special environment variable, which
-indicates the full path of the directory in which Emacs is installed.
-If Emacs is installed in the standard directory structure, it
-calculates this value automatically. It is not much use setting this
-variable yourself unless your installation is non-standard, since
-unlike other environment variables, it will be overridden by Emacs at
-startup. When setting other environment variables, such as
-@env{EMACSLOADPATH}, you may find it useful to use @env{emacs_dir}
-rather than hard-coding an absolute path. This allows multiple
-versions of Emacs to share the same environment variable settings, and
-it allows you to move the Emacs installation directory, without
-changing any environment or registry settings.
-@end table
-
-@node MS-Windows Registry
-@appendixsubsec The MS-Windows System Registry
-@pindex addpm, MS-Windows installation program
-@cindex registry, setting environment variables and resources on MS-Windows
-
-Under MS-Windows, the installation program @command{addpm.exe} adds
-values for @env{emacs_dir}, @env{EMACSLOADPATH}, @env{EMACSDATA},
-@env{EMACSPATH}, @env{EMACSDOC}, @env{SHELL} and @env{TERM} to the
-@file{HKEY_LOCAL_MACHINE} section of the system registry, under
-@file{/Software/GNU/Emacs}. It does this because there is no standard
-place to set environment variables across different versions of
-Windows. Running @command{addpm.exe} is no longer strictly necessary
-in recent versions of Emacs, but if you are upgrading from an older
-version, running @command{addpm.exe} ensures that you do not have
-older registry entries from a previous installation, which may not be
-compatible with the latest version of Emacs.
-
-When Emacs starts, as well as checking the environment, it also checks
-the System Registry for those variables and for @env{HOME}, @env{LANG}
-and @env{PRELOAD_WINSOCK}.
-
-To determine the value of those variables, Emacs goes through the
-following procedure. First, the environment is checked. If the
-variable is not found there, Emacs looks for registry keys by that
-name under @file{/Software/GNU/Emacs}; first in the
-@file{HKEY_CURRENT_USER} section of the registry, and if not found
-there, in the @file{HKEY_LOCAL_MACHINE} section. Finally, if Emacs
-still cannot determine the values, compiled-in defaults are used.
-
-In addition to the environment variables above, you can also add many
-of the settings which on X belong in the @file{.Xdefaults} file
-(@pxref{X Resources}) to the @file{/Software/GNU/Emacs} registry key.
-Settings you add to the @file{HKEY_LOCAL_MACHINE} section will affect
-all users of the machine. Settings you add to the
-@file{HKEY_CURRENT_USER} section will only affect you, and will
-override machine wide settings.
-
-@node Display X
-@appendixsec Specifying the Display Name
-@cindex display name (X Window System)
-@cindex @env{DISPLAY} environment variable
-
- The environment variable @env{DISPLAY} tells all X clients, including
-Emacs, where to display their windows. Its value is set by default
-in ordinary circumstances, when you start an X server and run jobs
-locally. Occasionally you may need to specify the display yourself; for
-example, if you do a remote login and want to run a client program
-remotely, displaying on your local screen.
-
- With Emacs, the main reason people change the default display is to
-let them log into another system, run Emacs on that system, but have the
-window displayed at their local terminal. You might need to log in
-to another system because the files you want to edit are there, or
-because the Emacs executable file you want to run is there.
-
- The syntax of the @env{DISPLAY} environment variable is
-@samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the
-host name of the X Window System server machine, @var{display} is an
-arbitrarily-assigned number that distinguishes your server (X terminal)
-from other servers on the same machine, and @var{screen} is a
-rarely-used field that allows an X server to control multiple terminal
-screens. The period and the @var{screen} field are optional. If
-included, @var{screen} is usually zero.
-
- For example, if your host is named @samp{glasperle} and your server is
-the first (or perhaps the only) server listed in the configuration, your
-@env{DISPLAY} is @samp{glasperle:0.0}.
-
- You can specify the display name explicitly when you run Emacs, either
-by changing the @env{DISPLAY} variable, or with the option @samp{-d
-@var{display}} or @samp{--display=@var{display}}. Here is an example:
-
-@smallexample
-emacs --display=glasperle:0 &
-@end smallexample
-
- You can inhibit the direct use of the window system and GUI with the
-@samp{-nw} option. It tells Emacs to display using ordinary @acronym{ASCII} on
-its controlling terminal. This is also an initial option.
-
- Sometimes, security arrangements prevent a program on a remote system
-from displaying on your local system. In this case, trying to run Emacs
-produces messages like this:
-
-@smallexample
-Xlib: connection to "glasperle:0.0" refused by server
-@end smallexample
-
-@noindent
-You might be able to overcome this problem by using the @command{xhost}
-command on the local system to give permission for access from your
-remote machine.
-
-@node Font X
-@appendixsec Font Specification Options
-@cindex font name (X Window System)
-
- By default, Emacs displays text in a twelve point Courier font (when
-using X). You can specify a different font on your command line
-through the option @samp{-fn @var{name}} (or @samp{--font}, which is
-an alias for @samp{-fn}).
-
-@table @samp
-@item -fn @var{name}
-@opindex -fn
-@itemx --font=@var{name}
-@opindex --font
-@cindex specify default font from the command line
-Use font @var{name} as the default font.
-@end table
-
- Under X, each font has a long name which consists of fourteen words
-or numbers, separated by dashes. Some fonts also have shorter
-nicknames. For instance, @samp{9x15} is such a nickname. This font
-makes each character nine pixels wide and fifteen pixels high. You
-can use either kind of name. Case is insignificant in both kinds.
-You can use wildcard patterns for the font name; then Emacs lets X
-choose one of the fonts that match the pattern. The wildcard
-character @samp{*} matches any sequence of characters (including none)
-and @samp{?} matches any single character. However, matching is
-implementation-dependent, and can be inaccurate when wildcards match
-dashes in a long name. For reliable results, supply all 14 dashes and
-use wildcards only within a field. Here is an example, which happens
-to specify the font whose nickname is @samp{6x13}:
-
-@smallexample
-emacs -fn \
- "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" &
-@end smallexample
-
-@noindent
-You can also specify the font in your @file{.Xdefaults} file:
-
-@smallexample
-emacs.font: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
-@end smallexample
-
- Note that if you use a wildcard pattern on the command line, you
-need to enclose it in single or double quotes, to prevent the shell
-from accidentally expanding it into a list of file names. On the
-other hand, you should not quote the name in the @file{.Xdefaults}
-file.
-
-The default font used by Emacs (under X) is:
-
-@smallexample
--adobe-courier-medium-r-*-*-*-120-*-*-*-*-iso8859-1
-@end smallexample
-
- A long font name has the following form:
-
-@smallexample
--@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}
-@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{registry}-@var{encoding}
-@end smallexample
-
-@table @var
-@item maker
-This is the name of the font manufacturer.
-@item family
-This is the name of the font family---for example, @samp{courier}.
-@item weight
-This is normally @samp{bold}, @samp{medium} or @samp{light}. Other
-words may appear here in some font names.
-@item slant
-This is @samp{r} (roman), @samp{i} (italic), @samp{o} (oblique),
-@samp{ri} (reverse italic), or @samp{ot} (other).
-@item widthtype
-This is normally @samp{condensed}, @samp{extended}, @samp{semicondensed}
-or @samp{normal}. Other words may appear here in some font names.
-@item style
-This is an optional additional style name. Usually it is empty---most
-long font names have two hyphens in a row at this point.
-@item pixels
-This is the font height, in pixels.
-@item height
-This is the font height on the screen, measured in tenths of a printer's
-point---approximately 1/720 of an inch. In other words, it is the point
-size of the font, times ten. For a given vertical resolution,
-@var{height} and @var{pixels} are proportional; therefore, it is common
-to specify just one of them and use @samp{*} for the other.
-@item horiz
-This is the horizontal resolution, in pixels per inch, of the screen for
-which the font is intended.
-@item vert
-This is the vertical resolution, in pixels per inch, of the screen for
-which the font is intended. Normally the resolution of the fonts on
-your system is the right value for your screen; therefore, you normally
-specify @samp{*} for this and @var{horiz}.
-@item spacing
-This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c}
-(character cell).
-@item width
-This is the average character width, in pixels, multiplied by ten.
-@item registry
-@itemx encoding
-These together make up the X font character set that the font depicts.
-(X font character sets are not the same as Emacs charsets, but they
-are solutions for the same problem.) You can use the
-@command{xfontsel} program to check which choices you have. However,
-normally you should use @samp{iso8859} for @var{registry} and @samp{1}
-for @var{encoding}.
-@end table
-
-@cindex listing system fonts
- You will probably want to use a fixed-width default font---that is,
-a font in which all characters have the same width. Any font with
-@samp{m} or @samp{c} in the @var{spacing} field of the long name is a
-fixed-width font. Here's how to use the @command{xlsfonts} program to
-list all the fixed-width fonts available on your system:
-
-@example
-xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+"
-xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*'
-xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*'
-@end example
-
-@noindent
-To see what a particular font looks like, use the @command{xfd} command.
-For example:
-
-@example
-xfd -fn 6x13
-@end example
-
-@noindent
-displays the entire font @samp{6x13}.
-
- While running Emacs, you can set the font of the current frame
-(@pxref{Frame Parameters}) or for a specific kind of text
-(@pxref{Faces}).
-
-@node Colors
-@appendixsec Window Color Options
-@cindex color of window, from command line
-@cindex text colors, from command line
-
-@findex list-colors-display
-@cindex available colors
- On a color display, you can specify which color to use for various
-parts of the Emacs display. To find out what colors are available on
-your system, type @kbd{M-x list-colors-display}, or press
-@kbd{C-Mouse-2} and select @samp{Display Colors} from the pop-up menu.
-(A particular window system might support many more colors, but the
-list displayed by @code{list-colors-display} shows their portable
-subset that can be safely used on any display supported by Emacs.)
-If you do not specify colors, on windowed displays the default for the
-background is white and the default for all other colors is black. On a
-monochrome display, the foreground is black, the background is white,
-and the border is gray if the display supports that. On terminals, the
-background is usually black and the foreground is white.
-
- Here is a list of the command-line options for specifying colors:
-
-@table @samp
-@item -fg @var{color}
-@opindex -fg
-@itemx --foreground-color=@var{color}
-@opindex --foreground-color
-@cindex foreground color, command-line argument
-Specify the foreground color. @var{color} should be a standard color
-name, or a numeric specification of the color's red, green, and blue
-components as in @samp{#4682B4} or @samp{RGB:46/82/B4}.
-@item -bg @var{color}
-@opindex -bg
-@itemx --background-color=@var{color}
-@opindex --background-color
-@cindex background color, command-line argument
-Specify the background color.
-@item -bd @var{color}
-@opindex -bd
-@itemx --border-color=@var{color}
-@opindex --border-color
-@cindex border color, command-line argument
-Specify the color of the border of the X window.
-@item -cr @var{color}
-@opindex -cr
-@itemx --cursor-color=@var{color}
-@opindex --cursor-color
-@cindex cursor color, command-line argument
-Specify the color of the Emacs cursor which indicates where point is.
-@item -ms @var{color}
-@opindex -ms
-@itemx --mouse-color=@var{color}
-@opindex --mouse-color
-@cindex mouse pointer color, command-line argument
-Specify the color for the mouse cursor when the mouse is in the Emacs window.
-@item -r
-@opindex -r
-@itemx -rv
-@opindex -rv
-@itemx --reverse-video
-@opindex --reverse-video
-@cindex reverse video, command-line argument
-Reverse video---swap the foreground and background colors.
-@item --color=@var{mode}
-@opindex --color
-@cindex standard colors on a character terminal
-@cindex override character terminal color support
-For a character terminal only, specify the mode of color support.
-This option is intended for overriding the number of supported colors
-that the character terminal advertises in its @code{termcap} or
-@code{terminfo} database. The parameter @var{mode} can be one of the
-following:
-@table @samp
-@item never
-@itemx no
-Don't use colors even if the terminal's capabilities specify color
-support.
-@item default
-@itemx auto
-Same as when @option{--color} is not used at all: Emacs detects at
-startup whether the terminal supports colors, and if it does, turns on
-colored display.
-@item always
-@itemx yes
-@itemx ansi8
-Turn on the color support unconditionally, and use color commands
-specified by the ANSI escape sequences for the 8 standard colors.
-@item @var{num}
-Use color mode for @var{num} colors. If @var{num} is -1, turn off
-color support (equivalent to @samp{never}); if it is 0, use the
-default color support for this terminal (equivalent to @samp{auto});
-otherwise use an appropriate standard mode for @var{num} colors.
-Depending on your terminal's capabilities, Emacs might be able to turn
-on a color mode for 8, 16, 88, or 256 as the value of @var{num}. If
-there is no mode that supports @var{num} colors, Emacs acts as if
-@var{num} were 0, i.e.@: it uses the terminal's default color support
-mode.
-@end table
-If @var{mode} is omitted, it defaults to @var{ansi8}.
-@end table
-
- For example, to use a coral mouse cursor and a slate blue text cursor,
-enter:
-
-@example
-emacs -ms coral -cr 'slate blue' &
-@end example
-
- You can reverse the foreground and background colors through the
-@samp{-rv} option or with the X resource @samp{reverseVideo}.
-
- The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on
-text-only terminals as well as on graphical displays.
-
-@node Window Size X
-@appendixsec Options for Window Size and Position
-@cindex geometry of Emacs window
-@cindex position and size of Emacs frame
-@cindex width and height of Emacs frame
-@cindex specifying fullscreen for Emacs frame
-
- Here is a list of the command-line options for specifying size and
-position of the initial Emacs frame:
-
-@table @samp
-@item -g @var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]}
-@opindex -g
-@itemx --geometry=@var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]}
-@opindex --geometry
-@cindex geometry, command-line argument
-Specify the size @var{width} and @var{height} (measured in character
-columns and lines), and positions @var{xoffset} and @var{yoffset}
-(measured in pixels). The @var{width} and @var{height} parameters
-apply to all frames, whereas @var{xoffset} and @var{yoffset} only to
-the initial frame.
-
-@item -fs
-@opindex -fs
-@itemx --fullscreen
-@opindex --fullscreen
-@cindex fullscreen, command-line argument
-Specify that width and height shall be the size of the screen.
-
-@item -fh
-@opindex -fh
-@itemx --fullheight
-@opindex --fullheight
-@cindex fullheight, command-line argument
-Specify that the height shall be the height of the screen.
-
-@item -fw
-@opindex -fw
-@itemx --fullwidth
-@opindex --fullwidth
-@cindex fullwidth, command-line argument
-Specify that the width shall be the width of the screen.
-@end table
-
-
-@noindent
-In the @samp{--geometry} option, @code{@r{@{}+-@r{@}}} means either a plus
- sign or a minus sign. A plus
-sign before @var{xoffset} means it is the distance from the left side of
-the screen; a minus sign means it counts from the right side. A plus
-sign before @var{yoffset} means it is the distance from the top of the
-screen, and a minus sign there indicates the distance from the bottom.
-The values @var{xoffset} and @var{yoffset} may themselves be positive or
-negative, but that doesn't change their meaning, only their direction.
-
- Emacs uses the same units as @command{xterm} does to interpret the geometry.
-The @var{width} and @var{height} are measured in characters, so a large font
-creates a larger frame than a small font. (If you specify a proportional
-font, Emacs uses its maximum bounds width as the width unit.) The
-@var{xoffset} and @var{yoffset} are measured in pixels.
-
- You do not have to specify all of the fields in the geometry
-specification. If you omit both @var{xoffset} and @var{yoffset}, the
-window manager decides where to put the Emacs frame, possibly by
-letting you place it with the mouse. For example, @samp{164x55}
-specifies a window 164 columns wide, enough for two ordinary width
-windows side by side, and 55 lines tall.
-
- The default width for Emacs is 80 characters and the default height is
-40 lines. You can omit either the width or the height or both. If
-you start the geometry with an integer, Emacs interprets it as the
-width. If you start with an @samp{x} followed by an integer, Emacs
-interprets it as the height. Thus, @samp{81} specifies just the width;
-@samp{x45} specifies just the height.
-
- If you start with @samp{+} or @samp{-}, that introduces an offset,
-which means both sizes are omitted. Thus, @samp{-3} specifies the
-@var{xoffset} only. (If you give just one offset, it is always
-@var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the
-@var{yoffset}, placing the frame near the bottom left of the screen.
-
- You can specify a default for any or all of the fields in
-@file{.Xdefaults} file, and then override selected fields with a
-@samp{--geometry} option.
-
- Since the mode line and the echo area occupy the last 2 lines of the
-frame, the height of the initial text window is 2 less than the height
-specified in your geometry. In non-X-toolkit versions of Emacs, the
-menu bar also takes one line of the specified number. But in the X
-toolkit version, the menu bar is additional and does not count against
-the specified height. The tool bar, if present, is also additional.
-
- Enabling or disabling the menu bar or tool bar alters the amount of
-space available for ordinary text. Therefore, if Emacs starts up with
-a tool bar (which is the default), and handles the geometry
-specification assuming there is a tool bar, and then your
-@file{~/.emacs} file disables the tool bar, you will end up with a
-frame geometry different from what you asked for. To get the intended
-size with no tool bar, use an X resource to specify ``no tool bar''
-(@pxref{Table of Resources}); then Emacs will already know there's no
-tool bar when it processes the specified geometry.
-
- When using one of @samp{--fullscreen}, @samp{--fullwidth} or
-@samp{--fullheight} there may be some space around the frame
-anyway. That is because Emacs rounds the sizes so they are an
-even number of character heights and widths.
-
- Some window managers have options that can make them ignore both
-program-specified and user-specified positions (sawfish is one).
-If these are set, Emacs fails to position the window correctly.
-
-@node Borders X
-@appendixsec Internal and External Borders
-@cindex borders (X Window System)
-
- An Emacs frame has an internal border and an external border. The
-internal border is an extra strip of the background color around the
-text portion of the frame. Emacs itself draws the internal border.
-The external border is added by the window manager outside the frame;
-depending on the window manager you use, it may contain various boxes
-you can click on to move or iconify the window.
-
-@table @samp
-@item -ib @var{width}
-@opindex -ib
-@itemx --internal-border=@var{width}
-@opindex --internal-border
-@cindex internal border width, command-line argument
-Specify @var{width} as the width of the internal border (between the text
-and the main border), in pixels.
-
-@item -bw @var{width}
-@opindex -bw
-@itemx --border-width=@var{width}
-@opindex --border-width
-@cindex main border width, command-line argument
-Specify @var{width} as the width of the main border, in pixels.
-@end table
-
- When you specify the size of the frame, that does not count the
-borders. The frame's position is measured from the outside edge of the
-external border.
-
- Use the @samp{-ib @var{n}} option to specify an internal border
-@var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to
-specify the width of the external border (though the window manager may
-not pay attention to what you specify). The default width of the
-external border is 2.
-
-@node Title X
-@appendixsec Frame Titles
-
- An Emacs frame may or may not have a specified title. The frame
-title, if specified, appears in window decorations and icons as the
-name of the frame. If an Emacs frame has no specified title, the
-default title has the form @samp{@var{invocation-name}@@@var{machine}}
-(if there is only one frame) or the selected window's buffer name (if
-there is more than one frame).
-
- You can specify a title for the initial Emacs frame with a command
-line option:
-
-@table @samp
-@item -T @var{title}
-@opindex -T
-@itemx --title=@var{title}
-@opindex --title
-@cindex frame title, command-line argument
-Specify @var{title} as the title for the initial Emacs frame.
-@end table
-
- The @samp{--name} option (@pxref{Resources}) also specifies the title
-for the initial Emacs frame.
-
-@node Icons X
-@appendixsec Icons
-@cindex icons (X Window System)
-
- Most window managers allow you to ``iconify'' a frame, removing
-it from sight, and leaving a small, distinctive ``icon'' window in its
-place. Clicking on the icon window makes the frame itself appear again.
-If you have many clients running at once, you can avoid cluttering up
-the screen by iconifying most of the clients.
-
-@table @samp
-@item -nbi
-@opindex -nbi
-@itemx --no-bitmap-icon
-@opindex --no-bitmap-icon
-@cindex Emacs icon, a gnu
-Do not use a picture of a gnu as the Emacs icon.
-
-@item -iconic
-@opindex --iconic
-@itemx --iconic
-@cindex start iconified, command-line argument
-Start Emacs in iconified state.
-@end table
-
- By default Emacs uses an icon window containing a picture of the GNU gnu.
-The @samp{-nbi} or @samp{--no-bitmap-icon} option tells Emacs to let the
-window manager choose what sort of icon to use---usually just a small
-rectangle containing the frame's title.
-
- The @samp{-iconic} option tells Emacs to begin running as an icon,
-rather than showing a frame right away. In this situation, the icon
-is the only indication that Emacs has started; the text frame doesn't
-appear until you deiconify it.
-
-@node Misc X
-@appendixsec Other Display Options
-
-@table @samp
-@item -hb
-@opindex -hb
-@itemx --horizontal-scroll-bars
-@opindex --horizontal-scroll-bars
-@c @cindex horizontal scroll bars, command-line argument
-Enable horizontal scroll bars. Since horizontal scroll bars
-are not yet implemented, this actually does nothing.
-
-@item -vb
-@opindex -vb
-@itemx --vertical-scroll-bars
-@opindex --vertical-scroll-bars
-@cindex vertical scroll bars, command-line argument
-Enable vertical scroll bars.
-
-@item -lsp @var{pixels}
-@opindex -lsp
-@itemx --line-spacing=@var{pixels}
-@opindex --line-spacing
-@cindex line spacing, command-line argument
-Specify @var{pixels} as additional space to put between lines, in pixels.
-
-@item -nbc
-@opindex -nbc
-@itemx --no-blinking-cursor
-@opindex --no-blinking-cursor
-@cindex blinking cursor disable, command-line argument
-Disable the blinking cursor on graphical displays.
-
-@item -D
-@opindex -D
-@itemx --basic-display
-@opindex --basic-display
-Disable the menu-bar, the tool-bar, the scroll-bars, and tool tips,
-and turn off the blinking cursor. This can be useful for making a
-test case that simplifies debugging of display problems.
-@end table
-
- The @samp{--xrm} option (@pxref{Resources}) specifies additional
-X resource values.
-
-@ignore
- arch-tag: fffecd9e-7329-4a51-a3cc-dd4a9889340e
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@iftex
-@chapter Characters, Keys and Commands
-
- This chapter explains the character sets used by Emacs for input
-commands and for the contents of files, and the fundamental concepts of
-@dfn{keys} and @dfn{commands}, whereby Emacs interprets your keyboard
-and mouse input.
-@end iftex
-
-@ifnottex
-@raisesections
-@end ifnottex
-
-@node User Input, Keys, Screen, Top
-@section Kinds of User Input
-@cindex input with the keyboard
-@cindex keyboard input
-@cindex character set (keyboard)
-@cindex @acronym{ASCII}
-@cindex C-
-@cindex Control
-@cindex control characters
-
- GNU Emacs is designed for use with keyboard commands because that is
-the most efficient way to edit. You can do editing with the mouse, as
-in other editors, and you can give commands with the menu bar and tool
-bar, and scroll with the scroll bar. But if you keep on editing that
-way, you won't get the benefits of Emacs. Therefore, this manual
-documents primarily how to edit with the keyboard. You can force
-yourself to practice using the keyboard by using the shell command
-@samp{emacs -nw} to start Emacs, so that the mouse won't work.
-
- Emacs uses an extension of the @acronym{ASCII} character set for
-keyboard input; it also accepts non-character input events including
-function keys and mouse button actions.
-
- @acronym{ASCII} consists of 128 character codes. Some of these codes are
-assigned graphic symbols such as @samp{a} and @samp{=}; the rest are
-control characters, such as @kbd{Control-a} (usually written @kbd{C-a}
-for short). @kbd{C-a} gets its name from the fact that you type it by
-holding down the @key{CTRL} key while pressing @kbd{a}.
-
- Some @acronym{ASCII} control characters have special names, and most
-terminals have special keys you can type them with: for example,
-@key{RET}, @key{TAB}, @key{DEL} and @key{ESC}. The space character is
-usually known as @key{SPC}, even though strictly speaking it is a
-graphic character that is blank.
-
- Emacs extends the @acronym{ASCII} character set with thousands more printing
-characters (@pxref{International}), additional control characters, and a
-few more modifiers that can be combined with any character.
-
- On @acronym{ASCII} terminals, there are only 32 possible control characters.
-These are the control variants of letters and @samp{@@[]\^_}. In
-addition, the shift key is meaningless with control characters:
-@kbd{C-a} and @kbd{C-A} are the same character, and Emacs cannot
-distinguish them.
-
- The Emacs character set has room for control variants of all
-printing characters, and distinguishes @kbd{C-A} from @kbd{C-a}.
-Graphical terminals make it possible to enter all these characters.
-For example, @kbd{C--} (that's Control-Minus) and @kbd{C-5} are
-meaningful Emacs commands on a graphical terminal.
-
- Another Emacs character-set extension is additional modifier bits.
-Only one modifier bit is commonly used; it is called Meta. Every
-character has a Meta variant; examples include @kbd{Meta-a} (normally
-written @kbd{M-a}, for short), @kbd{M-A} (different from @kbd{M-a},
-but they are normally equivalent in Emacs), @kbd{M-@key{RET}}, and
-@kbd{M-C-a}. That last means @kbd{a} with both the @key{CTRL} and
-@key{META} modifiers. We usually write it as @kbd{C-M-a} rather than
-@kbd{M-C-a}, for reasons of tradition.
-
-@cindex Meta
-@cindex M-
-@cindex @key{ESC} replacing @key{META} key
- Some terminals have a @key{META} key, and allow you to type Meta
-characters by holding this key down. Thus, you can type @kbd{Meta-a}
-by holding down @key{META} and pressing @kbd{a}. The @key{META} key
-works much like the @key{SHIFT} key. In fact, this key is more often
-labeled @key{ALT} or @key{EDIT}, instead of @key{META}; on a Sun
-keyboard, it may have a diamond on it.
-
- If there is no @key{META} key, you can still type Meta characters
-using two-character sequences starting with @key{ESC}. Thus, you can
-enter @kbd{M-a} by typing @kbd{@key{ESC} a}. You can enter
-@kbd{C-M-a} by typing @kbd{@key{ESC} C-a}. Unlike @key{META}, which
-modifies other characters, @key{ESC} is a separate character. You
-don't hold down @key{ESC} while typing the next character; instead,
-you press it and release it, then you enter the next character.
-@key{ESC} is allowed on terminals with @key{META} keys, too, in case
-you have formed a habit of using it.
-
- Emacs defines several other modifier keys that can be applied to any
-input character. These are called @key{SUPER}, @key{HYPER} and
-@key{ALT}. We write @samp{s-}, @samp{H-} and @samp{A-} to say that a
-character uses these modifiers. Thus, @kbd{s-H-C-x} is short for
-@kbd{Super-Hyper-Control-x}. Not all graphical terminals actually
-provide keys for these modifier flags---in fact, many terminals have a
-key labeled @key{ALT} which is really a @key{META} key. The standard
-key bindings of Emacs do not include any characters with these
-modifiers. But you can assign them meanings of your own by
-customizing Emacs.
-
- If your keyboard lacks one of these modifier keys, you can enter it
-using @kbd{C-x @@}: @kbd{C-x @@ h} adds the ``hyper'' flag to the next
-character, @kbd{C-x @@ s} adds the ``super'' flag, and @kbd{C-x @@ a}
-adds the ``alt'' flag. For instance, @kbd{C-x @@ h C-a} is a way to
-enter @kbd{Hyper-Control-a}. (Unfortunately there is no way to add
-two modifiers by using @kbd{C-x @@} twice for the same character,
-because the first one goes to work on the @kbd{C-x}.)
-
- Keyboard input includes keyboard keys that are not characters at
-all, such as function keys and arrow keys. Mouse buttons are also not
-characters. However, you can modify these events with the modifier
-keys @key{CTRL}, @key{META}, @key{SUPER}, @key{HYPER} and @key{ALT},
-just like keyboard characters.
-
-@cindex input event
- Input characters and non-character inputs are collectively called
-@dfn{input events}. @xref{Input Events,,, elisp, The Emacs Lisp
-Reference Manual}, for the full Lisp-level details. If you are not
-doing Lisp programming, but simply want to redefine the meaning of
-some characters or non-character events, see @ref{Customization}.
-
- @acronym{ASCII} terminals cannot really send anything to the computer except
-@acronym{ASCII} characters. These terminals use a sequence of characters to
-represent each function key. But that is invisible to the Emacs user,
-because the keyboard input routines catch these special sequences
-and convert them to function key events before any other part of Emacs
-gets to see them.
-
-@cindex keys stolen by window manager
-@cindex window manager, keys stolen by
- On graphical displays, the window manager is likely to block the
-character @kbd{Meta-@key{TAB}} before Emacs can see it. It may also
-block @kbd{Meta-@key{SPC}}, @kbd{C-M-d} and @kbd{C-M-l}. If you have
-these problems, we recommend that you customize your window manager to
-turn off those commands, or put them on key combinations that Emacs
-does not use.
-
-@node Keys, Commands, User Input, Top
-@section Keys
-
-@cindex key sequence
-@cindex key
- A @dfn{key sequence} (@dfn{key}, for short) is a sequence of input
-events that is meaningful as a unit---a ``single command.'' Some
-Emacs command sequences are invoked by just one character or one
-event; for example, just @kbd{C-f} moves forward one character in the
-buffer. But Emacs also has commands that take two or more events to
-invoke.
-
-@cindex complete key
-@cindex prefix key
- If a sequence of events is enough to invoke a command, it is a
-@dfn{complete key}. Examples of complete keys include @kbd{C-a},
-@kbd{X}, @key{RET}, @key{NEXT} (a function key), @key{DOWN} (an arrow
-key), @kbd{C-x C-f}, and @kbd{C-x 4 C-f}. If it isn't long enough to be
-complete, we call it a @dfn{prefix key}. The above examples show that
-@kbd{C-x} and @kbd{C-x 4} are prefix keys. Every key sequence is either
-a complete key or a prefix key.
-
- Most single characters constitute complete keys in the standard Emacs
-command bindings. A few of them are prefix keys. A prefix key combines
-with the following input event to make a longer key sequence, which may
-itself be complete or a prefix. For example, @kbd{C-x} is a prefix key,
-so @kbd{C-x} and the next input event combine to make a two-event
-key sequence. Most of these key sequences are complete keys, including
-@kbd{C-x C-f} and @kbd{C-x b}. A few, such as @kbd{C-x 4} and @kbd{C-x
-r}, are themselves prefix keys that lead to three-event key
-sequences. There's no limit to the length of a key sequence, but in
-practice people rarely use sequences longer than four events.
-
- You can't add input events onto a complete key. For example, the
-two-event sequence @kbd{C-f C-k} is not a key, because the @kbd{C-f}
-is a complete key in itself. It's impossible to give @kbd{C-f C-k} an
-independent meaning as a command. @kbd{C-f C-k} is two key sequences,
-not one.@refill
-
- All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h},
-@kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x
-n}, @w{@kbd{C-x r}}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x
-6}, @key{ESC}, @kbd{M-g}, and @kbd{M-o}. (@key{F1} and @key{F2} are
-aliases for @kbd{C-h} and @kbd{C-x 6}.) This list is not cast in stone;
-it describes the standard key bindings. If you customize Emacs, you can make
-new prefix keys, or eliminate some of the standard ones (not
-recommended for most users). @xref{Key Bindings}.
-
- If you make or eliminate prefix keys, that changes the set of
-possible key sequences. For example, if you redefine @kbd{C-f} as a
-prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless
-you define that too as a prefix). Conversely, if you remove the
-prefix definition of @kbd{C-x 4}, then @kbd{C-x 4 f} and @kbd{C-x 4
-@var{anything}} are no longer keys.
-
- Typing the help character (@kbd{C-h} or @key{F1}) after a prefix key
-displays a list of the commands starting with that prefix. There are
-a few prefix keys after which @kbd{C-h} does not work---for historical
-reasons, they define other meanings for @kbd{C-h} which are painful to
-change. @key{F1} works after all prefix keys.
-
-@node Commands, Text Characters, Keys, Top
-@section Keys and Commands
-
-@cindex binding
-@cindex command
-@cindex function definition
- This manual is full of passages that tell you what particular keys
-do. But Emacs does not assign meanings to keys directly. Instead,
-Emacs assigns meanings to named @dfn{commands}, and then gives keys
-their meanings by @dfn{binding} them to commands.
-
- Every command has a name chosen by a programmer. The name is
-usually made of a few English words separated by dashes; for example,
-@code{next-line} or @code{forward-word}. A command also has a
-@dfn{function definition} which is a Lisp program; this is how the
-command does its work. In Emacs Lisp, a command is a Lisp function with
-special options to read arguments and for interactive use. For more
-information on commands and functions, see @ref{What Is a Function,,
-What Is a Function, elisp, The Emacs Lisp Reference Manual}. (The
-definition here is simplified slightly.)
-
- The bindings between keys and commands are recorded in tables called
-@dfn{keymaps}. @xref{Keymaps}.
-
- When we say that ``@kbd{C-n} moves down vertically one line'' we are
-glossing over a subtle distinction that is irrelevant in ordinary use,
-but vital for Emacs customization. The command @code{next-line} does
-a vertical move downward. @kbd{C-n} has this effect @emph{because} it
-is bound to @code{next-line}. If you rebind @kbd{C-n} to the command
-@code{forward-word}, @kbd{C-n} will move forward one word instead.
-Rebinding keys is an important method of customization.
-
- In the rest of this manual, we usually ignore this distinction to
-keep things simple. We will often speak of keys like @kbd{C-n} as
-commands, even though strictly speaking the key is bound to a command.
-Usually we state the name of the command which really does the work in
-parentheses after mentioning the key that runs it. For example, we
-will say that ``The command @kbd{C-n} (@code{next-line}) moves point
-vertically down,'' meaning that the command @code{next-line} moves
-vertically down, and the key @kbd{C-n} is normally bound to it.
-
- Since we are discussing customization, we should tell you about
-@dfn{variables}. Often the description of a command will say, ``To
-change this, set the variable @code{mumble-foo}.'' A variable is a
-name used to store a value. Most of the variables documented in this
-manual are meant for customization: some command or other part of
-Emacs examines the variable and behaves differently according to the
-value that you set. You can ignore the information about variables
-until you are interested in customizing them. Then read the basic
-information on variables (@pxref{Variables}) and the information about
-specific variables will make sense.
-
-@node Text Characters, Entering Emacs, Commands, Top
-@section Character Set for Text
-@cindex characters (in text)
-
- Text in Emacs buffers is a sequence of characters. In the simplest
-case, these are @acronym{ASCII} characters, each stored in one 8-bit
-byte. Both @acronym{ASCII} control characters (octal codes 000
-through 037, and 0177) and @acronym{ASCII} printing characters (codes
-040 through 0176) are allowed. The other modifier flags used in
-keyboard input, such as Meta, are not allowed in buffers.
-
- Non-@acronym{ASCII} printing characters can also appear in buffers,
-when multibyte characters are enabled. They have character codes
-starting at 256, octal 0400, and each one is represented as a sequence
-of two or more bytes. @xref{International}. Single-byte characters
-with codes 128 through 255 can also appear in multibyte buffers.
-However, non-@acronym{ASCII} control characters cannot appear in a
-buffer.
-
- Some @acronym{ASCII} control characters serve special purposes in text, and have
-special names. For example, the newline character (octal code 012) is
-used in the buffer to end a line, and the tab character (octal code 011)
-is used for indenting to the next tab stop column (normally every 8
-columns). @xref{Text Display}.
-
- If you disable multibyte characters, then you can use only one
-alphabet of non-@acronym{ASCII} characters, which all fit in one byte.
-They use octal codes 0200 through 0377. @xref{Unibyte Mode}.
-
-@ifnottex
-@lowersections
-@end ifnottex
-
-@ignore
- arch-tag: 9be43eef-d1f4-4d03-a916-c741ea713a45
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Customization, Quitting, Amusements, Top
-@chapter Customization
-@cindex customization
-
- This chapter talks about various topics relevant to adapting the
-behavior of Emacs in ways we have anticipated.
-@iftex
-See @cite{The Emacs Lisp Reference Manual}
-@end iftex
-@ifnottex
-@xref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp
-Reference Manual},
-@end ifnottex
-for how to make more far-reaching and open-ended changes. @xref{X
-Resources}, for information on using X resources to customize Emacs.
-
- Customization that you do within Emacs normally affects only the
-particular Emacs session that you do it in---it does not persist
-between sessions unless you save the customization in a file such as
-your init file (@file{.emacs}) that will affect future sessions.
-(@xref{Init File}.) When you tell the customization buffer to save
-customizations for future sessions, this actually works by editing
-@file{.emacs} for you.
-
- Another means of customization is the keyboard macro, which is a
-sequence of keystrokes to be replayed with a single command.
-@xref{Keyboard Macros}, for full instruction how to record, manage, and
-replay sequences of keys.
-
-@menu
-* Minor Modes:: Each minor mode is one feature you can turn on
- independently of any others.
-* Easy Customization:: Convenient way to browse and change settings.
-* Variables:: Many Emacs commands examine Emacs variables
- to decide what to do; by setting variables,
- you can control their functioning.
-* Key Bindings:: The keymaps say what command each key runs.
- By changing them, you can "redefine keys".
-* Syntax:: The syntax table controls how words and
- expressions are parsed.
-* Init File:: How to write common customizations in the
- @file{.emacs} file.
-@end menu
-
-@node Minor Modes
-@section Minor Modes
-@cindex minor modes
-@cindex mode, minor
-
- Minor modes are optional features which you can turn on or off. For
-example, Auto Fill mode is a minor mode in which @key{SPC} breaks lines
-between words as you type. All the minor modes are independent of each
-other and of the selected major mode. Most minor modes say in the mode
-line when they are enabled; for example, @samp{Fill} in the mode line means
-that Auto Fill mode is enabled.
-
- You should append @code{-mode} to the name of a minor mode to
-produce the name of the command that turns the mode on or off. Thus,
-the command to enable or disable Auto Fill mode is called
-@code{auto-fill-mode}. These commands are usually invoked with
-@kbd{M-x}, but you can bind keys to them if you wish.
-
- With no argument, the minor mode function turns the mode on if it
-was off, and off if it was on. This is known as @dfn{toggling}. A
-positive argument always turns the mode on, and an explicit zero
-argument or a negative argument always turns it off.
-
- Some minor modes are global: while enabled, they affect everything
-you do in the Emacs session, in all buffers. Other minor modes are
-buffer-local; they apply only to the current buffer, so you can enable
-the mode in certain buffers and not others.
-
- For most minor modes, the command name is also the name of a
-variable. The variable's value is non-@code{nil} if the mode is
-enabled and @code{nil} if it is disabled. Some minor-mode commands
-work by just setting the variable. For example, the command
-@code{abbrev-mode} works by setting the value of @code{abbrev-mode} as
-a variable; it is this variable that directly turns Abbrev mode on and
-off. You can directly set the variable's value instead of calling the
-mode function. For other minor modes, you need to either set the
-variable through the Customize interface or call the mode function to
-correctly enable or disable the mode. To check which of these two
-possibilities applies to a given minor mode, use @kbd{C-h v} to ask
-for documentation on the variable name.
-
- For minor mode commands that work by just setting the minor mode
-variable, that variable provides a good way for Lisp programs to turn
-minor modes on and off; it is also useful in a file's local variables
-list (@pxref{File Variables}). But please think twice before setting
-minor modes with a local variables list, because most minor modes are
-a matter of user preference---other users editing the same file might
-not want the same minor modes you prefer.
-
- The most useful buffer-local minor modes include Abbrev mode, Auto
-Fill mode, Auto Save mode, Font-Lock mode, Glasses mode, Outline minor
-mode, Overwrite mode, and Binary Overwrite mode.
-
- Abbrev mode allows you to define abbreviations that automatically expand
-as you type them. For example, @samp{amd} might expand to @samp{abbrev
-mode}. @xref{Abbrevs}, for full information.
-
- Auto Fill mode allows you to enter filled text without breaking lines
-explicitly. Emacs inserts newlines as necessary to prevent lines from
-becoming too long. @xref{Filling}.
-
- Auto Save mode saves the buffer contents periodically to reduce the
-amount of work you can lose in case of a crash. @xref{Auto Save}.
-
- Enriched mode enables editing and saving of formatted text.
-@xref{Formatted Text}.
-
- Flyspell mode automatically highlights misspelled words.
-@xref{Spelling}.
-
- Font-Lock mode automatically highlights certain textual units found
-in programs, such as comments, strings, and function names being
-defined. This requires a display that can show multiple fonts or
-colors. @xref{Faces}.
-
-@ignore
- ISO Accents mode makes the characters @samp{`}, @samp{'}, @samp{"},
-@samp{^}, @samp{/} and @samp{~} combine with the following letter, to
-produce an accented letter in the ISO Latin-1 character set. The
-newer and more general feature of input methods more or less
-supersedes ISO Accents mode. @xref{Unibyte Mode}.
-@end ignore
-
- Outline minor mode provides the same facilities as the major mode
-called Outline mode; but since it is a minor mode instead, you can
-combine it with any major mode. @xref{Outline Mode}.
-
-@cindex Overwrite mode
-@cindex mode, Overwrite
- Overwrite mode causes ordinary printing characters to replace existing
-text instead of shoving it to the right. For example, if point is in
-front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a
-@kbd{G} changes it to @samp{FOOGAR}, instead of producing @samp{FOOGBAR}
-as usual. In Overwrite mode, the command @kbd{C-q} inserts the next
-character whatever it may be, even if it is a digit---this gives you a
-way to insert a character instead of replacing an existing character.
-
-@findex overwrite-mode
-@kindex INSERT
- The command @code{overwrite-mode} is an exception to the rule that
-commands which toggle minor modes are normally not bound to keys: it is
-bound to the @key{INSERT} function key. This is because many other
-programs bind @key{INSERT} to similar functions.
-
-@findex binary-overwrite-mode
- Binary Overwrite mode is a variant of Overwrite mode for editing
-binary files; it treats newlines and tabs like other characters, so that
-they overwrite other characters and can be overwritten by them.
-In Binary Overwrite mode, digits after @kbd{C-q} specify an
-octal character code, as usual.
-
- Here are some useful minor modes that normally apply to all buffers
-at once. Since Line Number mode and Transient Mark mode can be
-enabled or disabled just by setting the value of the minor mode
-variable, you @emph{can} set them differently for particular buffers,
-by explicitly making the corresponding variable local in those
-buffers. @xref{Locals}.
-
- Icomplete mode displays an indication of available completions when
-you are in the minibuffer and completion is active. @xref{Completion
-Options}.
-
- Line Number mode enables continuous display in the mode line of the
-line number of point, and Column Number mode enables display of the
-column number. @xref{Mode Line}.
-
- Scroll Bar mode gives each window a scroll bar (@pxref{Scroll Bars}).
-Menu Bar mode gives each frame a menu bar (@pxref{Menu Bars}). Both of
-these modes are enabled by default when you use the X Window System.
-
- In Transient Mark mode, every change in the buffer contents
-``deactivates'' the mark, so that commands that operate on the region
-will get an error. This means you must either set the mark, or
-explicitly ``reactivate'' it, before each command that uses the region.
-The advantage of Transient Mark mode is that Emacs can display the
-region highlighted. @xref{Mark}.
-
-@node Easy Customization
-@section Easy Customization Interface
-
-@cindex settings
- Emacs has many @dfn{settings} which have values that you can specify
-in order to customize various commands. Many are documented in this
-manual. Most settings are @dfn{user options}---that is to say, Lisp
-variables (@pxref{Variables})---so their names appear in the Variable
-Index (@pxref{Variable Index}). The other settings are faces and
-their attributes (@pxref{Faces}).
-
-@findex customize
-@cindex customization buffer
- You can browse interactively through settings and change them using
-@kbd{M-x customize}. This command creates a @dfn{customization
-buffer}, which offers commands to navigate through a logically
-organized structure of the Emacs settings; you can also use it to edit
-and set their values, and to save settings permanently in your
-@file{~/.emacs} file (@pxref{Init File}).
-
- The appearance of the example buffers in this section is typically
-different under a graphical display, since faces are then used to indicate
-buttons, links and editable fields.
-
-@menu
-* Groups: Customization Groups. How settings are classified in a structure.
-* Browsing: Browsing Custom. Browsing and searching for settings.
-* Changing a Variable:: How to edit an option's value and set the option.
-* Saving Customizations:: Specifying the file for saving customizations.
-* Face Customization:: How to edit the attributes of a face.
-* Specific Customization:: Making a customization buffer for specific
- variables, faces, or groups.
-* Custom Themes:: How to define collections of customized options
- that can be loaded and unloaded together.
-@end menu
-
-@node Customization Groups
-@subsection Customization Groups
-@cindex customization groups
-
- For customization purposes, settings are organized into @dfn{groups}
-to help you find them. Groups are collected into bigger groups, all
-the way up to a master group called @code{Emacs}.
-
- @kbd{M-x customize} creates a customization buffer that shows the
-top-level @code{Emacs} group and the second-level groups immediately
-under it. It looks like this, in part:
-
-@c we want the buffer example to all be on one page, but unfortunately
-@c that's quite a bit of text, so force all space to the bottom.
-@page
-@smallexample
-@group
-/- Emacs group: ---------------------------------------------------\
- [State]: visible group members are all at standard values.
- Customization of the One True Editor.
- See also [Manual].
-
-Editing group: [Go to Group]
-Basic text editing facilities.
-
-External group: [Go to Group]
-Interfacing to external utilities.
-
-@var{more second-level groups}
-
-\- Emacs group end ------------------------------------------------/
-@end group
-@end smallexample
-
-@noindent
-This says that the buffer displays the contents of the @code{Emacs}
-group. The other groups are listed because they are its contents. But
-they are listed differently, without indentation and dashes, because
-@emph{their} contents are not included. Each group has a single-line
-documentation string; the @code{Emacs} group also has a @samp{[State]}
-line.
-
-@cindex editable fields (customization buffer)
-@cindex buttons (customization buffer)
-@cindex links (customization buffer)
- Most of the text in the customization buffer is read-only, but it
-typically includes some @dfn{editable fields} that you can edit.
-There are also @dfn{buttons} and @dfn{links}, which do something when
-you @dfn{invoke} them. To invoke a button or a link, either click on
-it with @kbd{Mouse-1}, or move point to it and type @key{RET}.
-
- For example, the phrase @samp{[State]} that appears in
-a second-level group is a button. It operates on the same
-customization buffer. The phrase @samp{[Go to Group]} is a kind
-of hypertext link to another group. Invoking it creates a new
-customization buffer, which shows that group and its contents.
-
- The @code{Emacs} group includes a few settings, but mainly it
-contains other groups, which contain more groups, which contain the
-settings. By browsing the hierarchy of groups, you will eventually
-find the feature you are interested in customizing. Then you can use
-the customization buffer to set that feature's settings. You can also
-go straight to a particular group by name, using the command @kbd{M-x
-customize-group}.
-
-@node Browsing Custom
-@subsection Browsing and Searching for Options and Faces
-@findex customize-browse
-
- @kbd{M-x customize-browse} is another way to browse the available
-settings. This command creates a special customization buffer which
-shows only the names of groups and settings, and puts them in a
-structure.
-
- In this buffer, you can show the contents of a group by invoking the
-@samp{[+]} button. When the group contents are visible, this button
-changes to @samp{[-]}; invoking that hides the group contents again.
-
- Each group or setting in this buffer has a link which says
-@samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking this link
-creates an ordinary customization buffer showing just that group and
-its contents, just that user option, or just that face. This is the
-way to change settings that you find with @kbd{M-x customize-browse}.
-
- If you can guess part of the name of the settings you are interested
-in, @kbd{M-x customize-apropos} is another way to search for settings.
-However, unlike @code{customize} and @code{customize-browse},
-@code{customize-apropos} can only find groups and settings that are
-loaded in the current Emacs session. @xref{Specific Customization,,
-Customizing Specific Items}.
-
-@node Changing a Variable
-@subsection Changing a Variable
-
- Here is an example of what a variable (a user option) looks like in
-the customization buffer:
-
-@smallexample
-Kill Ring Max: [Hide Value] 60
- [State]: STANDARD.
-Maximum length of kill ring before oldest elements are thrown away.
-@end smallexample
-
- The text following @samp{[Hide Value]}, @samp{60} in this case, indicates
-the current value of the variable. If you see @samp{[Show Value]} instead of
-@samp{[Hide Value]}, it means that the value is hidden; the customization
-buffer initially hides values that take up several lines. Invoke
-@samp{[Show Value]} to show the value.
-
- The line after the variable name indicates the @dfn{customization
-state} of the variable: in the example above, it says you have not
-changed the option yet. The @samp{[State]} button at the beginning of
-this line gives you a menu of various operations for customizing the
-variable.
-
- The line after the @samp{[State]} line displays the beginning of the
-variable's documentation string. If there are more lines of
-documentation, this line ends with a @samp{[More]} button; invoke that
-to show the full documentation string.
-
- To enter a new value for @samp{Kill Ring Max}, move point to the
-value and edit it textually. For example, you can type @kbd{M-d},
-then insert another number. As you begin to alter the text, you will
-see the @samp{[State]} line change to say that you have edited the
-value:
-
-@smallexample
-[State]: EDITED, shown value does not take effect until you set or @r{@dots{}}
- save it.
-@end smallexample
-
-@cindex user options, how to set
-@cindex variables, how to set
-@cindex settings, how to set
- Editing the value does not actually set the variable. To do that,
-you must @dfn{set} the variable. To do this, invoke the
-@samp{[State]} button and choose @samp{Set for Current Session}.
-
- The state of the variable changes visibly when you set it:
-
-@smallexample
-[State]: SET for current session only.
-@end smallexample
-
- You don't have to worry about specifying a value that is not valid;
-the @samp{Set for Current Session} operation checks for validity and
-will not install an unacceptable value.
-
-@kindex M-TAB @r{(customization buffer)}
-@findex widget-complete
- While editing a field that is a file name, directory name,
-command name, or anything else for which completion is defined, you
-can type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
-(@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.)
-
- Some variables have a small fixed set of possible legitimate values.
-These variables don't let you edit the value textually. Instead, a
-@samp{[Value Menu]} button appears before the value; invoke this
-button to change the value. For a boolean ``on or off'' value, the
-button says @samp{[Toggle]}, and it changes to the other value.
-@samp{[Value Menu]} and @samp{[Toggle]} simply edit the buffer; the
-changes take real effect when you use the @samp{Set for Current
-Session} operation.
-
- Some variables have values with complex structure. For example, the
-value of @code{file-coding-system-alist} is an association list. Here
-is how it appears in the customization buffer:
-
-@smallexample
-File Coding System Alist: [Hide Value]
-[INS] [DEL] File regexp: \.elc\'
- Choice: [Value Menu] Encoding/decoding pair:
- Decoding: emacs-mule
- Encoding: emacs-mule
-[INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\'
- Choice: [Value Menu] Encoding/decoding pair:
- Decoding: raw-text
- Encoding: raw-text-unix
-[INS] [DEL] File regexp: \.tar\'
- Choice: [Value Menu] Encoding/decoding pair:
- Decoding: no-conversion
- Encoding: no-conversion
-[INS] [DEL] File regexp:
- Choice: [Value Menu] Encoding/decoding pair:
- Decoding: undecided
- Encoding: nil
-[INS]
- [State]: STANDARD.
-Alist to decide a coding system to use for a file I/O @r{@dots{}}
- operation. [Hide Rest]
-The format is ((PATTERN . VAL) ...),
-where PATTERN is a regular expression matching a file name,
-@r{[@dots{}more lines of documentation@dots{}]}
-@end smallexample
-
-@noindent
-Each association in the list appears on four lines, with several
-editable fields and/or buttons. You can edit the regexps and coding
-systems using ordinary editing commands. You can also invoke
-@samp{[Value Menu]} to switch to a different kind of value---for
-instance, to specify a function instead of a pair of coding systems.
-
-To delete an association from the list, invoke the @samp{[DEL]} button
-for that item. To add an association, invoke @samp{[INS]} at the
-position where you want to add it. There is an @samp{[INS]} button
-between each pair of associations, another at the beginning and another
-at the end, so you can add a new association at any position in the
-list.
-
-@kindex TAB @r{(customization buffer)}
-@kindex S-TAB @r{(customization buffer)}
-@findex widget-forward
-@findex widget-backward
- Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful
-for moving through the customization buffer. @key{TAB}
-(@code{widget-forward}) moves forward to the next button or editable
-field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to
-the previous button or editable field.
-
- Typing @key{RET} on an editable field also moves forward, just like
-@key{TAB}. We set it up this way because people often type @key{RET}
-when they are finished editing a field. To insert a newline within an
-editable field, use @kbd{C-o} or @kbd{C-q C-j}.
-
-@cindex saving a setting
-@cindex settings, how to save
- Setting the variable changes its value in the current Emacs session;
-@dfn{saving} the value changes it for future sessions as well. To
-save the variable, invoke @samp{[State]} and select the @samp{Save for
-Future Sessions} operation. This works by writing code so as to set
-the variable again, each time you start Emacs (@pxref{Saving
-Customizations}).
-
- You can also restore the variable to its standard value by invoking
-@samp{[State]} and selecting the @samp{Erase Customization} operation.
-There are actually four reset operations:
-
-@table @samp
-@item Undo Edits
-If you have made some modifications and not yet set the variable,
-this restores the text in the customization buffer to match
-the actual value.
-
-@item Reset to Saved
-This restores the value of the variable to the last saved value,
-and updates the text accordingly.
-
-@item Erase Customization
-This sets the variable to its standard value, and updates the text
-accordingly. This also eliminates any saved value for the variable,
-so that you will get the standard value in future Emacs sessions.
-
-@item Set to Backup Value
-This sets the variable to a previous value that was set in the
-customization buffer in this session. If you customize a variable
-and then reset it, which discards the customized value,
-you can get the discarded value back again with this operation.
-@end table
-
-@cindex comments on customized settings
- Sometimes it is useful to record a comment about a specific
-customization. Use the @samp{Add Comment} item from the
-@samp{[State]} menu to create a field for entering the comment. The
-comment you enter will be saved, and displayed again if you again view
-the same variable in a customization buffer, even in another session.
-
- The state of a group indicates whether anything in that group has been
-edited, set or saved.
-
- Near the top of the customization buffer there are two lines of buttons:
-
-@smallexample
- [Set for Current Session] [Save for Future Sessions]
- [Undo Edits] [Reset to Saved] [Erase Customization] [Finish]
-@end smallexample
-
-@vindex custom-buffer-done-function
-@noindent
-Invoking @samp{[Finish]} either buries or kills this customization
-buffer according to the setting of the option
-@code{custom-buffer-done-kill}; the default is to bury the buffer.
-Each of the other buttons performs an operation---set, save or
-reset---on each of the settings in the buffer that could meaningfully
-be set, saved or reset. They do not operate on settings whose values
-are hidden, nor on subgroups which are hidden or not visible in the buffer.
-
-@node Saving Customizations
-@subsection Saving Customizations
-
- Saving customizations from the customization buffer works by writing
-code that future sessions will read, code to set up those
-customizations again.
-
-@vindex custom-file
- Normally this saves customizations in your init file,
-@file{~/.emacs}. If you wish, you can save customizations in another
-file instead. To make this work, your @file{~/.emacs} should set
-@code{custom-file} to the name of that file. Then you should load the
-file by calling @code{load}. For example:
-
-@example
-(setq custom-file "~/.emacs-custom.el")
-(load custom-file)
-@end example
-
- You can use @code{custom-file} to specify different customization
-files for different Emacs versions, like this:
-
-@example
-(cond ((< emacs-major-version 21)
- ;; @r{Emacs 20 customization.}
- (setq custom-file "~/.custom-20.el"))
- ((and (= emacs-major-version 21) (< emacs-minor-version 4))
- ;; @r{Emacs 21 customization, before version 21.4.}
- (setq custom-file "~/.custom-21.el"))
- ((< emacs-major-version 22)
- ;; @r{Emacs version 21.4 or later.}
- (setq custom-file "~/.custom-21.4.el"))
- (t
- ;; @r{Emacs version 22.1 or later.}
- (setq custom-file "~/.custom-22.el")))
-
-(load custom-file)
-@end example
-
- If Emacs was invoked with the @option{-q} or @option{--no-init-file}
-options (@pxref{Initial Options}), it will not let you save your
-customizations in your @file{~/.emacs} init file. This is because
-saving customizations from such a session would wipe out all the other
-customizations you might have on your init file.
-
-@node Face Customization
-@subsection Customizing Faces
-@cindex customizing faces
-@cindex bold font
-@cindex italic font
-@cindex fonts and faces
-
- In addition to variables, some customization groups also include
-faces. When you show the contents of a group, both the variables and
-the faces in the group appear in the customization buffer. Here is an
-example of how a face looks:
-
-@smallexample
-Custom Changed Face:(sample) [Hide Face]
- [State]: STANDARD.
-Face used when the customize item has been changed.
-Parent groups: [Custom Magic Faces]
-Attributes: [ ] Font Family: *
- [ ] Width: *
- [ ] Height: *
- [ ] Weight: *
- [ ] Slant: *
- [ ] Underline: *
- [ ] Overline: *
- [ ] Strike-through: *
- [ ] Box around text: *
- [ ] Inverse-video: *
- [X] Foreground: white (sample)
- [X] Background: blue (sample)
- [ ] Stipple: *
- [ ] Inherit: *
-@end smallexample
-
- Each face attribute has its own line. The @samp{[@var{x}]} button
-before the attribute name indicates whether the attribute is
-@dfn{enabled}; @samp{[X]} means that it's enabled, and @samp{[ ]}
-means that it's disabled. You can enable or disable the attribute by
-clicking that button. When the attribute is enabled, you can change
-the attribute value in the usual ways.
-
- For the colors, you can specify a color name (use @kbd{M-x
-list-colors-display} for a list of them) or a hexadecimal color
-specification of the form @samp{#@var{rr}@var{gg}@var{bb}}.
-(@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is
-green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.) On a
-black-and-white display, the colors you can use for the background are
-@samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, and
-@samp{gray3}. Emacs supports these shades of gray by using background
-stipple patterns instead of a color.
-
- Setting, saving and resetting a face work like the same operations for
-variables (@pxref{Changing a Variable}).
-
- A face can specify different appearances for different types of
-display. For example, a face can make text red on a color display, but
-use a bold font on a monochrome display. To specify multiple
-appearances for a face, select @samp{For All Kinds of Displays} in the
-menu you get from invoking @samp{[State]}.
-
-@findex modify-face
- Another more basic way to set the attributes of a specific face is
-with @kbd{M-x modify-face}. This command reads the name of a face, then
-reads the attributes one by one. For the color and stipple attributes,
-the attribute's current value is the default---type just @key{RET} if
-you don't want to change that attribute. Type @samp{none} if you want
-to clear out the attribute.
-
-@node Specific Customization
-@subsection Customizing Specific Items
-
- Instead of finding the setting you want to change by navigating the
-structure of groups, here are other ways to specify the settings that
-you want to customize.
-
-@table @kbd
-@item M-x customize-option @key{RET} @var{option} @key{RET}
-Set up a customization buffer with just one user option variable,
-@var{option}.
-@item M-x customize-face @key{RET} @var{face} @key{RET}
-Set up a customization buffer with just one face, @var{face}.
-@item M-x customize-group @key{RET} @var{group} @key{RET}
-Set up a customization buffer with just one group, @var{group}.
-@item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
-Set up a customization buffer with all the settings and groups that
-match @var{regexp}.
-@item M-x customize-changed @key{RET} @var{version} @key{RET}
-Set up a customization buffer with all the settings and groups
-whose meaning has changed since Emacs version @var{version}.
-@item M-x customize-saved
-Set up a customization buffer containing all settings that you
-have saved with customization buffers.
-@item M-x customize-unsaved
-Set up a customization buffer containing all settings that you have
-set but not saved.
-@end table
-
-@findex customize-option
- If you want to alter a particular user option with the customization
-buffer, and you know its name, you can use the command @kbd{M-x
-customize-option} and specify the user option (variable) name. This
-sets up the customization buffer with just one user option---the one
-that you asked for. Editing, setting and saving the value work as
-described above, but only for the specified user option. Minibuffer
-completion is handy if you only know part of the name. However, this
-command can only see options that have been loaded in the current
-Emacs session.
-
-@findex customize-face
- Likewise, you can modify a specific face, chosen by name, using
-@kbd{M-x customize-face}. By default it operates on the face used
-on the character after point.
-
-@findex customize-group
- You can also set up the customization buffer with a specific group,
-using @kbd{M-x customize-group}. The immediate contents of the chosen
-group, including settings (user options and faces), and other groups,
-all appear as well (even if not already loaded). However, the
-subgroups' own contents are not included.
-
-@findex customize-apropos
- For a more general way of controlling what to customize, you can use
-@kbd{M-x customize-apropos}. You specify a regular expression as
-argument; then all @emph{loaded} settings and groups whose names match
-this regular expression are set up in the customization buffer. If
-you specify an empty regular expression, this includes @emph{all}
-loaded groups and settings---which takes a long time to set up.
-
-@findex customize-changed
- When you upgrade to a new Emacs version, you might want to consider
-customizing new settings, and settings whose meanings or default
-values have changed. To do this, use @kbd{M-x customize-changed} and
-specify a previous Emacs version number using the minibuffer. It
-creates a customization buffer which shows all the settings and groups
-whose definitions have been changed since the specified version,
-loading them if necessary.
-
-@findex customize-saved
-@findex customize-unsaved
- If you change settings and then decide the change was a mistake, you
-can use two special commands to revisit your previous changes. Use
-@kbd{M-x customize-saved} to look at the settings that you have saved.
-Use @kbd{M-x customize-unsaved} to look at the settings that you
-have set but not saved.
-
-@node Custom Themes
-@subsection Customization Themes
-@cindex custom themes
-
- @dfn{Custom themes} are collections of settings that can be enabled
-or disabled as a unit. You can use Custom themes to switch quickly
-and easily between various collections of settings, and to transfer
-such collections from one computer to another.
-
-@findex customize-create-theme
- To define a Custom theme, use @kbd{M-x customize-create-theme},
-which brings up a buffer named @samp{*New Custom Theme*}. At the top
-of the buffer is an editable field where you can specify the name of
-the theme. Click on the button labelled @samp{Insert Variable} to add
-a variable to the theme, and click on @samp{Insert Face} to add a
-face. You can edit these values in the @samp{*New Custom Theme*}
-buffer like in an ordinary Customize buffer. To remove an option from
-the theme, click on its @samp{State} button and select @samp{Delete}.
-
-@vindex custom-theme-directory
- After adding the desired options, click on @samp{Save Theme} to save
-the Custom theme. This writes the theme definition to a file
-@file{@var{foo}-theme.el} (where @var{foo} is the theme name you
-supplied), in the directory @file{~/.emacs.d/}. You can specify the
-directory by setting @code{custom-theme-directory}.
-
- You can view and edit the settings of a previously-defined theme by
-clicking on @samp{Visit Theme} and specifying the theme name. You can
-also import the variables and faces that you have set using Customize
-by visiting the ``special'' theme named @samp{user}. This theme, which
-records all the options that you set in the ordinary customization
-buffer, is always enabled, and always takes precedence over all other
-enabled Custom themes. Additionally, the @samp{user} theme is
-recorded with code in your @file{.emacs} file, rather than a
-@file{user-theme.el} file.
-
-@vindex custom-enabled-themes
- Once you have defined a Custom theme, you can use it by customizing
-the variable @code{custom-enabled-themes}. This is a list of Custom
-themes that are @dfn{enabled}, or put into effect. If you set
-@code{custom-enabled-themes} using the Customize interface, the theme
-definitions are automatically loaded from the theme files, if they
-aren't already. If you save the value of @code{custom-enabled-themes}
-for future Emacs sessions, those Custom themes will be enabled
-whenever Emacs is started up.
-
- If two enabled themes specify different values for an option, the
-theme occurring earlier in @code{custom-enabled-themes} takes effect.
-
-@findex load-theme
-@findex enable-theme
-@findex disable-theme
- You can temporarily enable a Custom theme with @kbd{M-x
-enable-theme}. This prompts for a theme name in the minibuffer, loads
-the theme from the theme file if necessary, and enables the theme.
-You can @dfn{disable} any enabled theme with the command @kbd{M-x
-disable-theme}; this returns the options specified in the theme to
-their original values. To re-enable the theme, type @kbd{M-x
-enable-theme} again. If a theme file is changed during your Emacs
-session, you can reload it by typing @kbd{M-x load-theme}. (This also
-enables the theme.)
-
-@node Variables
-@section Variables
-@cindex variable
-@cindex option, user
-@cindex user option
-
- A @dfn{variable} is a Lisp symbol which has a value. The symbol's
-name is also called the name of the variable. A variable name can
-contain any characters that can appear in a file, but conventionally
-variable names consist of words separated by hyphens. A variable can
-have a documentation string which describes what kind of value it should
-have and how the value will be used.
-
- Emacs Lisp allows any variable (with a few exceptions) to have any
-kind of value, but most variables that Emacs uses expect a value of a
-certain type. Often the value should always be a string, or should
-always be a number. Sometimes we say that a certain feature is turned
-on if a variable is ``non-@code{nil},'' meaning that if the variable's
-value is @code{nil}, the feature is off, but the feature is on for
-@emph{any} other value. The conventional value to use to turn on the
-feature---since you have to pick one particular value when you set the
-variable---is @code{t}.
-
- Emacs uses many Lisp variables for internal record keeping, but the
-most interesting variables for a non-programmer user are those meant
-for users to change---these are called @dfn{user options}.
-
- Each user option that you can set with the customization buffer is
-in fact a Lisp variable. Emacs does not (usually) change the values
-of these variables on its own; instead, you set the values in order to
-control the behavior of certain Emacs commands. Use of the
-customization buffer is explained above (@pxref{Easy Customization});
-here we describe other aspects of Emacs variables.
-
-@menu
-* Examining:: Examining or setting one variable's value.
-* Hooks:: Hook variables let you specify programs for parts
- of Emacs to run on particular occasions.
-* Locals:: Per-buffer values of variables.
-* File Variables:: How files can specify variable values.
-@end menu
-
-@node Examining
-@subsection Examining and Setting Variables
-@cindex setting variables
-
-@table @kbd
-@item C-h v @var{var} @key{RET}
-Display the value and documentation of variable @var{var}
-(@code{describe-variable}).
-@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET}
-Change the value of variable @var{var} to @var{value}.
-@end table
-
- To examine the value of a single variable, use @kbd{C-h v}
-(@code{describe-variable}), which reads a variable name using the
-minibuffer, with completion. It displays both the value and the
-documentation of the variable. For example,
-
-@example
-C-h v fill-column @key{RET}
-@end example
-
-@noindent
-displays something like this:
-
-@smallexample
-fill-column is a variable defined in `C source code'.
-fill-column's value is 70
-Local in buffer custom.texi; global value is 70
-Automatically becomes buffer-local when set in any fashion.
-
-This variable is safe to use as a file local variable only if its value
-satisfies the predicate `integerp'.
-
-Documentation:
-*Column beyond which automatic line-wrapping should happen.
-Interactively, you can set the buffer local value using C-x f.
-
-You can customize this variable.
-@end smallexample
-
-@noindent
-The line that says you can customize the variable indicates that this
-variable is a user option. (The star also indicates this, but it is
-an obsolete indicator that may eventually disappear.) @kbd{C-h v} is
-not restricted to user options; it allows any variable name.
-
-@findex set-variable
-The most convenient way to set a specific user option variable is with
-@kbd{M-x set-variable}. This reads the variable name with the
-minibuffer (with completion), and then reads a Lisp expression for the
-new value using the minibuffer a second time (you can insert the old
-value into the minibuffer for editing via @kbd{M-n}). For example,
-
-@example
-M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
-@end example
-
-@noindent
-sets @code{fill-column} to 75.
-
- @kbd{M-x set-variable} is limited to user option variables, but you can
-set any variable with a Lisp expression, using the function @code{setq}.
-Here is a @code{setq} expression to set @code{fill-column}:
-
-@example
-(setq fill-column 75)
-@end example
-
- To execute an expression like this one, go to the @samp{*scratch*}
-buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp
-Interaction}.
-
- Setting variables, like all means of customizing Emacs except where
-otherwise stated, affects only the current Emacs session. The only
-way to alter the variable in future sessions is to put something in
-the @file{~/.emacs} file to set it those sessions (@pxref{Init File}).
-
-@node Hooks
-@subsection Hooks
-@cindex hook
-@cindex running a hook
-
- @dfn{Hooks} are an important mechanism for customization of Emacs. A
-hook is a Lisp variable which holds a list of functions, to be called on
-some well-defined occasion. (This is called @dfn{running the hook}.)
-The individual functions in the list are called the @dfn{hook functions}
-of the hook. With rare exceptions, hooks in Emacs are empty when Emacs
-starts up, so the only hook functions in any given hook are the ones you
-explicitly put there as customization.
-
- Most major modes run one or more @dfn{mode hooks} as the last step of
-initialization. This makes it easy for you to customize the behavior of
-the mode, by setting up a hook function to override the local variable
-assignments already made by the mode. But hooks are also used in other
-contexts. For example, the hook @code{suspend-hook} runs just before
-Emacs suspends itself (@pxref{Exiting}).
-
-@cindex normal hook
- Most Emacs hooks are @dfn{normal hooks}. This means that running the
-hook operates by calling all the hook functions, unconditionally, with
-no arguments. We have made an effort to keep most hooks normal so that
-you can use them in a uniform way. Every variable in Emacs whose name
-ends in @samp{-hook} is a normal hook.
-
-@cindex abnormal hook
- There are also a few @dfn{abnormal hooks}. These variables' names end
-in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What
-makes these hooks abnormal is that there is something peculiar about the
-way its functions are called---perhaps they are given arguments, or
-perhaps the values they return are used in some way. For example,
-@code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because
-as soon as one hook function returns a non-@code{nil} value, the rest
-are not called at all. The documentation of each abnormal hook variable
-explains in detail what is peculiar about it.
-
-@findex add-hook
- You can set a hook variable with @code{setq} like any other Lisp
-variable, but the recommended way to add a hook function to a hook
-(either normal or abnormal) is by calling @code{add-hook}.
-@xref{Hooks,,, elisp, The Emacs Lisp Reference Manual}.
-
- For example, here's how to set up a hook to turn on Auto Fill mode
-when entering Text mode and other modes based on Text mode:
-
-@example
-(add-hook 'text-mode-hook 'turn-on-auto-fill)
-@end example
-
- The next example shows how to use a hook to customize the indentation
-of C code. (People often have strong personal preferences for one
-format compared to another.) Here the hook function is an anonymous
-lambda expression.
-
-@example
-@group
-(setq my-c-style
- '((c-comment-only-line-offset . 4)
-@end group
-@group
- (c-cleanup-list . (scope-operator
- empty-defun-braces
- defun-close-semi))
-@end group
-@group
- (c-offsets-alist . ((arglist-close . c-lineup-arglist)
- (substatement-open . 0)))))
-@end group
-
-@group
-(add-hook 'c-mode-common-hook
- '(lambda ()
- (c-add-style "my-style" my-c-style t)))
-@end group
-@end example
-
- It is best to design your hook functions so that the order in which
-they are executed does not matter. Any dependence on the order is
-``asking for trouble.'' However, the order is predictable: the most
-recently added hook functions are executed first.
-
-@findex remove-hook
- If you play with adding various different versions of a hook
-function by calling @code{add-hook} over and over, remember that all
-the versions you added will remain in the hook variable together. You
-can clear out individual functions by calling @code{remove-hook}, or
-do @code{(setq @var{hook-variable} nil)} to remove everything.
-
-@node Locals
-@subsection Local Variables
-
-@table @kbd
-@item M-x make-local-variable @key{RET} @var{var} @key{RET}
-Make variable @var{var} have a local value in the current buffer.
-@item M-x kill-local-variable @key{RET} @var{var} @key{RET}
-Make variable @var{var} use its global value in the current buffer.
-@item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET}
-Mark variable @var{var} so that setting it will make it local to the
-buffer that is current at that time.
-@end table
-
-@cindex local variables
- Almost any variable can be made @dfn{local} to a specific Emacs
-buffer. This means that its value in that buffer is independent of its
-value in other buffers. A few variables are always local in every
-buffer. Every other Emacs variable has a @dfn{global} value which is in
-effect in all buffers that have not made the variable local.
-
-@findex make-local-variable
- @kbd{M-x make-local-variable} reads the name of a variable and makes
-it local to the current buffer. Changing its value subsequently in
-this buffer will not affect others, and changes in its global value
-will not affect this buffer.
-
-@findex make-variable-buffer-local
-@cindex per-buffer variables
- @kbd{M-x make-variable-buffer-local} marks a variable so it will
-become local automatically whenever it is set. More precisely, once a
-variable has been marked in this way, the usual ways of setting the
-variable automatically do @code{make-local-variable} first. We call
-such variables @dfn{per-buffer} variables. Many variables in Emacs
-are normally per-buffer; the variable's document string tells you when
-this is so. A per-buffer variable's global value is normally never
-effective in any buffer, but it still has a meaning: it is the initial
-value of the variable for each new buffer.
-
- Major modes (@pxref{Major Modes}) always make variables local to the
-buffer before setting the variables. This is why changing major modes
-in one buffer has no effect on other buffers. Minor modes also work
-by setting variables---normally, each minor mode has one controlling
-variable which is non-@code{nil} when the mode is enabled
-(@pxref{Minor Modes}). For many minor modes, the controlling variable
-is per buffer, and thus always buffer-local. Otherwise, you can make
-it local in a specific buffer like any other variable.
-
- A few variables cannot be local to a buffer because they are always
-local to each display instead (@pxref{Multiple Displays}). If you try to
-make one of these variables buffer-local, you'll get an error message.
-
-@findex kill-local-variable
- @kbd{M-x kill-local-variable} makes a specified variable cease to be
-local to the current buffer. The global value of the variable
-henceforth is in effect in this buffer. Setting the major mode kills
-all the local variables of the buffer except for a few variables
-specially marked as @dfn{permanent locals}.
-
-@findex setq-default
- To set the global value of a variable, regardless of whether the
-variable has a local value in the current buffer, you can use the Lisp
-construct @code{setq-default}. This construct is used just like
-@code{setq}, but it sets variables' global values instead of their local
-values (if any). When the current buffer does have a local value, the
-new global value may not be visible until you switch to another buffer.
-Here is an example:
-
-@example
-(setq-default fill-column 75)
-@end example
-
-@noindent
-@code{setq-default} is the only way to set the global value of a variable
-that has been marked with @code{make-variable-buffer-local}.
-
-@findex default-value
- Lisp programs can use @code{default-value} to look at a variable's
-default value. This function takes a symbol as argument and returns its
-default value. The argument is evaluated; usually you must quote it
-explicitly. For example, here's how to obtain the default value of
-@code{fill-column}:
-
-@example
-(default-value 'fill-column)
-@end example
-
-@node File Variables
-@subsection Local Variables in Files
-@cindex local variables in files
-@cindex file local variables
-
- A file can specify local variable values for use when you edit the
-file with Emacs. Visiting the file checks for local variable
-specifications; it automatically makes these variables local to the
-buffer, and sets them to the values specified in the file.
-
-@menu
-* Specifying File Variables:: Specifying file local variables.
-* Safe File Variables:: Making sure file local variables are safe.
-@end menu
-
-@node Specifying File Variables
-@subsubsection Specifying File Variables
-
- There are two ways to specify file local variable values: in the first
-line, or with a local variables list. Here's how to specify them in the
-first line:
-
-@example
--*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
-@end example
-
-@noindent
-You can specify any number of variables/value pairs in this way, each
-pair with a colon and semicolon as shown above. @code{mode:
-@var{modename};} specifies the major mode; this should come first in the
-line. The @var{value}s are not evaluated; they are used literally.
-Here is an example that specifies Lisp mode and sets two variables with
-numeric values:
-
-@smallexample
-;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
-@end smallexample
-
- You can also specify the coding system for a file in this way: just
-specify a value for the ``variable'' named @code{coding}. The ``value''
-must be a coding system name that Emacs recognizes. @xref{Coding
-Systems}. @w{@samp{unibyte: t}} specifies unibyte loading for a
-particular Lisp file. @xref{Enabling Multibyte}.
-
- The @code{eval} pseudo-variable, described below, can be specified in
-the first line as well.
-
-@cindex shell scripts, and local file variables
- In shell scripts, the first line is used to identify the script
-interpreter, so you cannot put any local variables there. To
-accommodate this, Emacs looks for local variable specifications in the
-@emph{second} line when the first line specifies an interpreter.
-
- A @dfn{local variables list} goes near the end of the file, in the
-last page. (It is often best to put it on a page by itself.) The local
-variables list starts with a line containing the string @samp{Local
-Variables:}, and ends with a line containing the string @samp{End:}. In
-between come the variable names and values, one set per line, as
-@samp{@var{variable}:@: @var{value}}. The @var{value}s are not
-evaluated; they are used literally. If a file has both a local
-variables list and a @samp{-*-} line, Emacs processes @emph{everything}
-in the @samp{-*-} line first, and @emph{everything} in the local
-variables list afterward.
-
- Here is an example of a local variables list:
-
-@example
-;; Local Variables: **
-;; mode:lisp **
-;; comment-column:0 **
-;; comment-start: ";; " **
-;; comment-end:"**" **
-;; End: **
-@end example
-
- Each line starts with the prefix @samp{;; } and each line ends with
-the suffix @samp{ **}. Emacs recognizes these as the prefix and
-suffix based on the first line of the list, by finding them
-surrounding the magic string @samp{Local Variables:}; then it
-automatically discards them from the other lines of the list.
-
- The usual reason for using a prefix and/or suffix is to embed the
-local variables list in a comment, so it won't confuse other programs
-that the file is intended as input for. The example above is for a
-language where comment lines start with @samp{;; } and end with
-@samp{**}; the local values for @code{comment-start} and
-@code{comment-end} customize the rest of Emacs for this unusual
-syntax. Don't use a prefix (or a suffix) if you don't need one.
-
- If you write a multi-line string value, you should put the prefix
-and suffix on each line, even lines that start or end within the
-string. They will be stripped off for processing the list. If you
-want to split a long string across multiple lines of the file, you can
-use backslash-newline, which is ignored in Lisp string constants.
-Here's an example of doing this:
-
-@example
-# Local Variables:
-# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \
-# -Dmumble=blaah"
-# End:
-@end example
-
- Some ``variable names'' have special meanings in a local variables
-list. Specifying the ``variable'' @code{mode} really sets the major
-mode, while any value specified for the ``variable'' @code{eval} is
-simply evaluated as an expression (its value is ignored). A value for
-@code{coding} specifies the coding system for character code
-conversion of this file, and a value of @code{t} for @code{unibyte}
-says to visit the file in a unibyte buffer. These four ``variables''
-are not really variables; setting them in any other context has no
-special meaning.
-
- @emph{If @code{mode} is used to set a major mode, it should be the
-first ``variable'' in the list.} Otherwise, the entries that precede
-it will usually be ignored, since most modes kill all local variables
-as part of their initialization.
-
- You can use the @code{mode} ``variable'' to set minor modes as well
-as the major modes; in fact, you can use it more than once, first to
-set the major mode and then to set minor modes which are specific to
-particular buffers. But most minor modes should not be specified in
-the file at all, because they represent user preferences.
-
- For example, you may be tempted to try to turn on Auto Fill mode with
-a local variable list. That is a mistake. The choice of Auto Fill mode
-or not is a matter of individual taste, not a matter of the contents of
-particular files. If you want to use Auto Fill, set up major mode hooks
-with your @file{.emacs} file to turn it on (when appropriate) for you
-alone (@pxref{Init File}). Don't use a local variable list to impose
-your taste on everyone.
-
- The start of the local variables list must be no more than 3000
-characters from the end of the file, and must be in the last page if the
-file is divided into pages. Otherwise, Emacs will not notice it is
-there. The purpose of this rule is so that a stray @samp{Local
-Variables:}@: not in the last page does not confuse Emacs, and so that
-visiting a long file that is all one page and has no local variables
-list need not take the time to search the whole file.
-
- Use the command @code{normal-mode} to reset the local variables and
-major mode of a buffer according to the file name and contents,
-including the local variables list if any. @xref{Choosing Modes}.
-
-@node Safe File Variables
-@subsubsection Safety of File Variables
-
- File-local variables can be dangerous; when you visit someone else's
-file, there's no telling what its local variables list could do to
-your Emacs. Improper values of the @code{eval} ``variable,'' and
-other variables such as @code{load-path}, could execute Lisp code you
-didn't intend to run.
-
- Therefore, whenever Emacs encounters file local variable values that
-are not known to be safe, it displays the file's entire local
-variables list, and asks you for confirmation before setting them.
-You can type @kbd{y} or @key{SPC} to put the local variables list into
-effect, or @kbd{n} to ignore it. When Emacs is run in batch mode
-(@pxref{Initial Options}), it can't really ask you, so it assumes the
-answer @kbd{n}.
-
- Emacs normally recognizes certain variables/value pairs as safe.
-For instance, it is safe to give @code{comment-column} or
-@code{fill-column} any integer value. If a file specifies only
-known-safe variable/value pairs, Emacs does not ask for confirmation
-before setting them. Otherwise, you can tell Emacs to record all the
-variable/value pairs in this file as safe, by typing @kbd{!} at the
-confirmation prompt. When Emacs encounters these variable/value pairs
-subsequently, in the same file or others, it will assume they are
-safe.
-
-@vindex safe-local-variable-values
-@cindex risky variable
- Some variables, such as @code{load-path}, are considered
-particularly @dfn{risky}: there is seldom any reason to specify them
-as local variables, and changing them can be dangerous. If a file
-contains only risky local variables, Emacs neither offers nor accepts
-@kbd{!} as input at the confirmation prompt. If some of the local
-variables in a file are risky, and some are only potentially unsafe, you
-can enter @kbd{!} at the prompt. It applies all the variables, but only
-marks the non-risky ones as safe for the future. If you really want to
-record safe values for risky variables, do it directly by customizing
-@samp{safe-local-variable-values} (@pxref{Easy Customization}).
-
-@vindex enable-local-variables
- The variable @code{enable-local-variables} allows you to change the
-way Emacs processes local variables. Its default value is @code{t},
-which specifies the behavior described above. If it is @code{nil},
-Emacs simply ignores all file local variables. @code{:safe} means use
-only the safe values and ignore the rest. Any other value says to
-query you about each file that has local variables, without trying to
-determine whether the values are known to be safe.
-
-@vindex enable-local-eval
- The variable @code{enable-local-eval} controls whether Emacs
-processes @code{eval} variables. The three possibilities for the
-variable's value are @code{t}, @code{nil}, and anything else, just as
-for @code{enable-local-variables}. The default is @code{maybe}, which
-is neither @code{t} nor @code{nil}, so normally Emacs does ask for
-confirmation about processing @code{eval} variables.
-
-@vindex safe-local-eval-forms
- But there is an exception. The @code{safe-local-eval-forms} is a
-customizable list of eval forms which are safe. Emacs does not ask
-for confirmation when it finds these forms for the @code{eval}
-variable.
-
-@node Key Bindings
-@section Customizing Key Bindings
-@cindex key bindings
-
- This section describes @dfn{key bindings}, which map keys to commands,
-and @dfn{keymaps}, which record key bindings. It also explains how
-to customize key bindings.
-
- Recall that a command is a Lisp function whose definition provides for
-interactive use. Like every Lisp function, a command has a function
-name, which usually consists of lower-case letters and hyphens.
-
-@menu
-* Keymaps:: Generalities. The global keymap.
-* Prefix Keymaps:: Keymaps for prefix keys.
-* Local Keymaps:: Major and minor modes have their own keymaps.
-* Minibuffer Maps:: The minibuffer uses its own local keymaps.
-* Rebinding:: How to redefine one key's meaning conveniently.
-* Init Rebinding:: Rebinding keys with your init file, @file{.emacs}.
-* Function Keys:: Rebinding terminal function keys.
-* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on.
-* Mouse Buttons:: Rebinding mouse buttons in Emacs.
-* Disabling:: Disabling a command means confirmation is required
- before it can be executed. This is done to protect
- beginners from surprises.
-@end menu
-
-@node Keymaps
-@subsection Keymaps
-@cindex keymap
-
- The bindings between key sequences and command functions are recorded
-in data structures called @dfn{keymaps}. Emacs has many of these, each
-used on particular occasions.
-
- Recall that a @dfn{key sequence} (@dfn{key}, for short) is a sequence
-of @dfn{input events} that have a meaning as a unit. Input events
-include characters, function keys and mouse buttons---all the inputs
-that you can send to the computer with your terminal. A key sequence
-gets its meaning from its @dfn{binding}, which says what command it
-runs. The function of keymaps is to record these bindings.
-
-@cindex global keymap
- The @dfn{global} keymap is the most important keymap because it is
-always in effect. The global keymap defines keys for Fundamental mode;
-most of these definitions are common to most or all major modes. Each
-major or minor mode can have its own keymap which overrides the global
-definitions of some keys.
-
- For example, a self-inserting character such as @kbd{g} is
-self-inserting because the global keymap binds it to the command
-@code{self-insert-command}. The standard Emacs editing characters such
-as @kbd{C-a} also get their standard meanings from the global keymap.
-Commands to rebind keys, such as @kbd{M-x global-set-key}, actually work
-by storing the new binding in the proper place in the global map.
-@xref{Rebinding}.
-
- Meta characters work differently; Emacs translates each Meta
-character into a pair of characters starting with @key{ESC}. When you
-type the character @kbd{M-a} in a key sequence, Emacs replaces it with
-@kbd{@key{ESC} a}. A meta key comes in as a single input event, but
-becomes two events for purposes of key bindings. The reason for this is
-historical, and we might change it someday.
-
-@cindex function key
- Most modern keyboards have function keys as well as character keys.
-Function keys send input events just as character keys do, and keymaps
-can have bindings for them.
-
- On text terminals, typing a function key actually sends the computer a
-sequence of characters; the precise details of the sequence depends on
-which function key and on the model of terminal you are using. (Often
-the sequence starts with @kbd{@key{ESC} [}.) If Emacs understands your
-terminal type properly, it recognizes the character sequences forming
-function keys wherever they occur in a key sequence (not just at the
-beginning). Thus, for most purposes, you can pretend the function keys
-reach Emacs directly and ignore their encoding as character sequences.
-
-@cindex mouse
- Mouse buttons also produce input events. These events come with other
-data---the window and position where you pressed or released the button,
-and a time stamp. But only the choice of button matters for key
-bindings; the other data matters only if a command looks at it.
-(Commands designed for mouse invocation usually do look at the other
-data.)
-
- A keymap records definitions for single events. Interpreting a key
-sequence of multiple events involves a chain of keymaps. The first
-keymap gives a definition for the first event; this definition is
-another keymap, which is used to look up the second event in the
-sequence, and so on.
-
- Key sequences can mix function keys and characters. For example,
-@kbd{C-x @key{SELECT}} is meaningful. If you make @key{SELECT} a prefix
-key, then @kbd{@key{SELECT} C-n} makes sense. You can even mix mouse
-events with keyboard events, but we recommend against it, because such
-key sequences are inconvenient to use.
-
- As a user, you can redefine any key; but it is usually best to stick
-to key sequences that consist of @kbd{C-c} followed by a letter (upper
-or lower case). These keys are ``reserved for users,'' so they won't
-conflict with any properly designed Emacs extension. The function
-keys @key{F5} through @key{F9} are also reserved for users. If you
-redefine some other key, your definition may be overridden by certain
-extensions or major modes which redefine the same key.
-
-@node Prefix Keymaps
-@subsection Prefix Keymaps
-
- A prefix key such as @kbd{C-x} or @key{ESC} has its own keymap,
-which holds the definition for the event that immediately follows
-that prefix.
-
- The definition of a prefix key is usually the keymap to use for
-looking up the following event. The definition can also be a Lisp
-symbol whose function definition is the following keymap; the effect is
-the same, but it provides a command name for the prefix key that can be
-used as a description of what the prefix key is for. Thus, the binding
-of @kbd{C-x} is the symbol @code{Control-X-prefix}, whose function
-definition is the keymap for @kbd{C-x} commands. The definitions of
-@kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in
-the global map, so these prefix keys are always available.
-
- Aside from ordinary prefix keys, there is a fictitious ``prefix key''
-which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp
-Reference Manual}, for special information about menu bar key bindings.
-Mouse button events that invoke pop-up menus are also prefix keys; see
-@ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more
-details.
-
- Some prefix keymaps are stored in variables with names:
-
-@itemize @bullet
-@item
-@vindex ctl-x-map
-@code{ctl-x-map} is the variable name for the map used for characters that
-follow @kbd{C-x}.
-@item
-@vindex help-map
-@code{help-map} is for characters that follow @kbd{C-h}.
-@item
-@vindex esc-map
-@code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta
-characters are actually defined by this map.
-@item
-@vindex ctl-x-4-map
-@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
-@item
-@vindex mode-specific-map
-@code{mode-specific-map} is for characters that follow @kbd{C-c}.
-@end itemize
-
-@node Local Keymaps
-@subsection Local Keymaps
-
-@cindex local keymap
- So far we have explained the ins and outs of the global map. Major
-modes customize Emacs by providing their own key bindings in @dfn{local
-keymaps}. For example, C mode overrides @key{TAB} to make it indent the
-current line for C code. Portions of text in the buffer can specify
-their own keymaps to substitute for the keymap of the buffer's major
-mode.
-
-@cindex minor mode keymap
- Minor modes can also have local keymaps. Whenever a minor mode is
-in effect, the definitions in its keymap override both the major
-mode's local keymap and the global keymap.
-
- A local keymap can locally redefine a key as a prefix key by defining
-it as a prefix keymap. If the key is also defined globally as a prefix,
-then its local and global definitions (both keymaps) effectively
-combine: both of them are used to look up the event that follows the
-prefix key. Thus, if the mode's local keymap defines @kbd{C-c} as
-another keymap, and that keymap defines @kbd{C-z} as a command, this
-provides a local meaning for @kbd{C-c C-z}. This does not affect other
-sequences that start with @kbd{C-c}; if those sequences don't have their
-own local bindings, their global bindings remain in effect.
-
- Another way to think of this is that Emacs handles a multi-event key
-sequence by looking in several keymaps, one by one, for a binding of the
-whole key sequence. First it checks the minor mode keymaps for minor
-modes that are enabled, then it checks the major mode's keymap, and then
-it checks the global keymap. This is not precisely how key lookup
-works, but it's good enough for understanding the results in ordinary
-circumstances.
-
-@cindex rebinding major mode keys
- Most major modes construct their keymaps when the mode is used for
-the first time in a session. If you wish to change one of these
-keymaps, you must use the major mode's @dfn{mode hook}
-(@pxref{Hooks}).
-
-@findex define-key
- For example, the command @code{texinfo-mode} to select Texinfo mode
-runs the hook @code{texinfo-mode-hook}. Here's how you can use the hook
-to add local bindings (not very useful, we admit) for @kbd{C-c n} and
-@kbd{C-c p} in Texinfo mode:
-
-@example
-(add-hook 'texinfo-mode-hook
- '(lambda ()
- (define-key texinfo-mode-map "\C-cp"
- 'backward-paragraph)
- (define-key texinfo-mode-map "\C-cn"
- 'forward-paragraph)))
-@end example
-
-@node Minibuffer Maps
-@subsection Minibuffer Keymaps
-
-@cindex minibuffer keymaps
-@vindex minibuffer-local-map
-@vindex minibuffer-local-ns-map
-@vindex minibuffer-local-completion-map
-@vindex minibuffer-local-must-match-map
-@vindex minibuffer-local-filename-completion-map
-@vindex minibuffer-local-must-match-filename-map
- The minibuffer has its own set of local keymaps; they contain various
-completion and exit commands.
-
-@itemize @bullet
-@item
-@code{minibuffer-local-map} is used for ordinary input (no completion).
-@item
-@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
-just like @key{RET}. This is used mainly for Mocklisp compatibility.
-@item
-@code{minibuffer-local-completion-map} is for permissive completion.
-@item
-@code{minibuffer-local-must-match-map} is for strict completion and
-for cautious completion.
-@item
-Finally, @code{minibuffer-local-filename-completion-map} and
-@code{minibuffer-local-must-match-filename-map} are like the two
-previous ones, but they are specifically for file name completion.
-They do not bind @key{SPC}.
-@end itemize
-
-@node Rebinding
-@subsection Changing Key Bindings Interactively
-@cindex key rebinding, this session
-@cindex redefining keys, this session
-
- The way to redefine an Emacs key is to change its entry in a keymap.
-You can change the global keymap, in which case the change is effective in
-all major modes (except those that have their own overriding local
-definitions for the same key). Or you can change the current buffer's
-local map, which affects all buffers using the same major mode.
-
-@findex global-set-key
-@findex local-set-key
-@findex global-unset-key
-@findex local-unset-key
-@table @kbd
-@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
-Define @var{key} globally to run @var{cmd}.
-@item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
-Define @var{key} locally (in the major mode now in effect) to run
-@var{cmd}.
-@item M-x global-unset-key @key{RET} @var{key}
-Make @var{key} undefined in the global map.
-@item M-x local-unset-key @key{RET} @var{key}
-Make @var{key} undefined locally (in the major mode now in effect).
-@end table
-
- For example, suppose you like to execute commands in a subshell within
-an Emacs buffer, instead of suspending Emacs and executing commands in
-your login shell. Normally, @kbd{C-z} is bound to the function
-@code{suspend-emacs} (when not using the X Window System), but you can
-change @kbd{C-z} to invoke an interactive subshell within Emacs, by
-binding it to @code{shell} as follows:
-
-@example
-M-x global-set-key @key{RET} C-z shell @key{RET}
-@end example
-
-@noindent
-@code{global-set-key} reads the command name after the key. After you
-press the key, a message like this appears so that you can confirm that
-you are binding the key you want:
-
-@example
-Set key C-z to command:
-@end example
-
- You can redefine function keys and mouse events in the same way; just
-type the function key or click the mouse when it's time to specify the
-key to rebind.
-
- You can rebind a key that contains more than one event in the same
-way. Emacs keeps reading the key to rebind until it is a complete key
-(that is, not a prefix key). Thus, if you type @kbd{C-f} for
-@var{key}, that's the end; it enters the minibuffer immediately to
-read @var{cmd}. But if you type @kbd{C-x}, since that's a prefix, it
-reads another character; if that is @kbd{4}, another prefix character,
-it reads one more character, and so on. For example,
-
-@example
-M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
-@end example
-
-@noindent
-redefines @kbd{C-x 4 $} to run the (fictitious) command
-@code{spell-other-window}.
-
- The two-character keys consisting of @kbd{C-c} followed by a letter
-are reserved for user customizations. Lisp programs are not supposed to
-define these keys, so the bindings you make for them will be available
-in all major modes and will never get in the way of anything.
-
- You can remove the global definition of a key with
-@code{global-unset-key}. This makes the key @dfn{undefined}; if you
-type it, Emacs will just beep. Similarly, @code{local-unset-key} makes
-a key undefined in the current major mode keymap, which makes the global
-definition (or lack of one) come back into effect in that major mode.
-
- If you have redefined (or undefined) a key and you subsequently wish
-to retract the change, undefining the key will not do the job---you need
-to redefine the key with its standard definition. To find the name of
-the standard definition of a key, go to a Fundamental mode buffer in a
-fresh Emacs and use @kbd{C-h c}. The documentation of keys in this
-manual also lists their command names.
-
- If you want to prevent yourself from invoking a command by mistake, it
-is better to disable the command than to undefine the key. A disabled
-command is less work to invoke when you really want to.
-@xref{Disabling}.
-
-@node Init Rebinding
-@subsection Rebinding Keys in Your Init File
-
- If you have a set of key bindings that you like to use all the time,
-you can specify them in your @file{.emacs} file by using their Lisp
-syntax. (@xref{Init File}.)
-
- The simplest method for doing this works for @acronym{ASCII} characters and
-Meta-modified @acronym{ASCII} characters only. This method uses a string to
-represent the key sequence you want to rebind. For example, here's how
-to bind @kbd{C-z} to @code{shell}:
-
-@example
-(global-set-key "\C-z" 'shell)
-@end example
-
-@noindent
-This example uses a string constant containing one character,
-@kbd{C-z}. (@samp{\C-} is string syntax for a control character.) The
-single-quote before the command name, @code{shell}, marks it as a
-constant symbol rather than a variable. If you omit the quote, Emacs
-would try to evaluate @code{shell} immediately as a variable. This
-probably causes an error; it certainly isn't what you want.
-
- Here is another example that binds the key sequence @kbd{C-x M-l}:
-
-@example
-(global-set-key "\C-x\M-l" 'make-symbolic-link)
-@end example
-
- To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the
-string, you can use the Emacs Lisp escape sequences, @samp{\t},
-@samp{\r}, @samp{\e}, and @samp{\d}. Here is an example which binds
-@kbd{C-x @key{TAB}}:
-
-@example
-(global-set-key "\C-x\t" 'indent-rigidly)
-@end example
-
- These examples show how to write some other special @acronym{ASCII} characters
-in strings for key bindings:
-
-@example
-(global-set-key "\r" 'newline) ;; @key{RET}
-(global-set-key "\d" 'delete-backward-char) ;; @key{DEL}
-(global-set-key "\C-x\e\e" 'repeat-complex-command) ;; @key{ESC}
-@end example
-
- When the key sequence includes function keys or mouse button events,
-or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, you must use
-the more general method of rebinding, which uses a vector to specify the
-key sequence.
-
- The way to write a vector in Emacs Lisp is with square brackets around
-the vector elements. Use spaces to separate the elements. If an
-element is a symbol, simply write the symbol's name---no other
-delimiters or punctuation are needed. If a vector element is a
-character, write it as a Lisp character constant: @samp{?} followed by
-the character as it would appear in a string.
-
- Here are examples of using vectors to rebind @kbd{C-=} (a control
-character not in @acronym{ASCII}), @kbd{C-M-=} (not in @acronym{ASCII} because @kbd{C-=}
-is not), @kbd{H-a} (a Hyper character; @acronym{ASCII} doesn't have Hyper at
-all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a
-keyboard-modified mouse button):
-
-@example
-(global-set-key [?\C-=] 'make-symbolic-link)
-(global-set-key [?\M-\C-=] 'make-symbolic-link)
-(global-set-key [?\H-a] 'make-symbolic-link)
-(global-set-key [f7] 'make-symbolic-link)
-(global-set-key [C-mouse-1] 'make-symbolic-link)
-@end example
-
- You can use a vector for the simple cases too. Here's how to
-rewrite the first six examples above to use vectors:
-
-@example
-(global-set-key [?\C-z] 'shell)
-(global-set-key [?\C-x ?l] 'make-symbolic-link)
-(global-set-key [?\C-x ?\t] 'indent-rigidly)
-(global-set-key [?\r] 'newline)
-(global-set-key [?\d] 'delete-backward-char)
-(global-set-key [?\C-x ?\e ?\e] 'repeat-complex-command)
-@end example
-
-@noindent
-As you see, you represent a multi-character key sequence with a vector
-by listing all of the characters, in order, within the square brackets
-that delimit the vector.
-
- Language and coding systems can cause problems with key bindings
-for non-@acronym{ASCII} characters. @xref{Init Non-ASCII}.
-
-@node Function Keys
-@subsection Rebinding Function Keys
-
- Key sequences can contain function keys as well as ordinary
-characters. Just as Lisp characters (actually integers) represent
-keyboard characters, Lisp symbols represent function keys. If the
-function key has a word as its label, then that word is also the name of
-the corresponding Lisp symbol. Here are the conventional Lisp names for
-common function keys:
-
-@table @asis
-@item @code{left}, @code{up}, @code{right}, @code{down}
-Cursor arrow keys.
-
-@item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior}
-Other cursor repositioning keys.
-
-@item @code{select}, @code{print}, @code{execute}, @code{backtab}
-@itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline}
-@itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar}
-Miscellaneous function keys.
-
-@item @code{f1}, @code{f2}, @dots{} @code{f35}
-Numbered function keys (across the top of the keyboard).
-
-@item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide}
-@itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter}
-@itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal}
-Keypad keys (to the right of the regular keyboard), with names or punctuation.
-
-@item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9}
-Keypad keys with digits.
-
-@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
-Keypad PF keys.
-@end table
-
- These names are conventional, but some systems (especially when using
-X) may use different names. To make certain what symbol is used for a
-given function key on your terminal, type @kbd{C-h c} followed by that
-key.
-
- A key sequence which contains function key symbols (or anything but
-@acronym{ASCII} characters) must be a vector rather than a string.
-Thus, to bind function key @samp{f1} to the command @code{rmail},
-write the following:
-
-@example
-(global-set-key [f1] 'rmail)
-@end example
-
-@noindent
-To bind the right-arrow key to the command @code{forward-char}, you can
-use this expression:
-
-@example
-(global-set-key [right] 'forward-char)
-@end example
-
-@noindent
-This uses the Lisp syntax for a vector containing the symbol
-@code{right}. (This binding is present in Emacs by default.)
-
- @xref{Init Rebinding}, for more information about using vectors for
-rebinding.
-
- You can mix function keys and characters in a key sequence. This
-example binds @kbd{C-x @key{NEXT}} to the command @code{forward-page}.
-
-@example
-(global-set-key [?\C-x next] 'forward-page)
-@end example
-
-@noindent
-where @code{?\C-x} is the Lisp character constant for the character
-@kbd{C-x}. The vector element @code{next} is a symbol and therefore
-does not take a question mark.
-
- You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER},
-@key{SUPER}, @key{ALT} and @key{SHIFT} with function keys. To represent
-these modifiers, add the strings @samp{C-}, @samp{M-}, @samp{H-},
-@samp{s-}, @samp{A-} and @samp{S-} at the front of the symbol name.
-Thus, here is how to make @kbd{Hyper-Meta-@key{RIGHT}} move forward a
-word:
-
-@example
-(global-set-key [H-M-right] 'forward-word)
-@end example
-
-@cindex keypad
- Many keyboards have a ``numeric keypad'' on the right hand side.
-The numeric keys in the keypad double up as cursor motion keys,
-toggled by a key labeled @samp{Num Lock}. By default, Emacs
-translates these keys to the corresponding keys in the main keyboard.
-For example, when @samp{Num Lock} is on, the key labeled @samp{8} on
-the numeric keypad produces @code{kp-8}, which is translated to
-@kbd{8}; when @samp{Num Lock} is off, the same key produces
-@code{kp-up}, which is translated to @key{UP}. If you rebind a key
-such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too.
-However, if you rebind a @samp{kp-} key directly, that won't affect
-its non-keypad equivalent.
-
- Emacs provides a convenient method for binding the numeric keypad
-keys, using the variables @code{keypad-setup},
-@code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and
-@code{keypad-numlock-shifted-setup}. These can be found in the
-@samp{keyboard} customization group (@pxref{Easy Customization}). You
-can rebind the keys to perform other tasks, such as issuing numeric
-prefix arguments.
-
-@node Named ASCII Chars
-@subsection Named @acronym{ASCII} Control Characters
-
- @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL}
-started out as names for certain @acronym{ASCII} control characters,
-used so often that they have special keys of their own. For instance,
-@key{TAB} was another name for @kbd{C-i}. Later, users found it
-convenient to distinguish in Emacs between these keys and the ``same''
-control characters typed with the @key{CTRL} key. Therefore, on most
-modern terminals, they are no longer the same, and @key{TAB} is
-distinguishable from @kbd{C-i}.
-
- Emacs can distinguish these two kinds of input if the keyboard does.
-It treats the ``special'' keys as function keys named @code{tab},
-@code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and
-@code{delete}. These function keys translate automatically into the
-corresponding @acronym{ASCII} characters @emph{if} they have no
-bindings of their own. As a result, neither users nor Lisp programs
-need to pay attention to the distinction unless they care to.
-
- If you do not want to distinguish between (for example) @key{TAB} and
-@kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB}
-(octal code 011). If you do want to distinguish, make one binding for
-this @acronym{ASCII} character, and another for the ``function key'' @code{tab}.
-
- With an ordinary @acronym{ASCII} terminal, there is no way to distinguish
-between @key{TAB} and @kbd{C-i} (and likewise for other such pairs),
-because the terminal sends the same character in both cases.
-
-@node Mouse Buttons
-@subsection Rebinding Mouse Buttons
-@cindex mouse button events
-@cindex rebinding mouse buttons
-@cindex click events
-@cindex drag events
-@cindex down events
-@cindex button down events
-
- Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary
-mouse events in Emacs are @dfn{click} events; these happen when you
-press a button and release it without moving the mouse. You can also
-get @dfn{drag} events, when you move the mouse while holding the button
-down. Drag events happen when you finally let go of the button.
-
- The symbols for basic click events are @code{mouse-1} for the leftmost
-button, @code{mouse-2} for the next, and so on. Here is how you can
-redefine the second mouse button to split the current window:
-
-@example
-(global-set-key [mouse-2] 'split-window-vertically)
-@end example
-
- The symbols for drag events are similar, but have the prefix
-@samp{drag-} before the word @samp{mouse}. For example, dragging the
-first button generates a @code{drag-mouse-1} event.
-
- You can also define bindings for events that occur when a mouse button
-is pressed down. These events start with @samp{down-} instead of
-@samp{drag-}. Such events are generated only if they have key bindings.
-When you get a button-down event, a corresponding click or drag event
-will always follow.
-
-@cindex double clicks
-@cindex triple clicks
- If you wish, you can distinguish single, double, and triple clicks. A
-double click means clicking a mouse button twice in approximately the
-same place. The first click generates an ordinary click event. The
-second click, if it comes soon enough, generates a double-click event
-instead. The event type for a double-click event starts with
-@samp{double-}: for example, @code{double-mouse-3}.
-
- This means that you can give a special meaning to the second click at
-the same place, but it must act on the assumption that the ordinary
-single click definition has run when the first click was received.
-
- This constrains what you can do with double clicks, but user interface
-designers say that this constraint ought to be followed in any case. A
-double click should do something similar to the single click, only
-``more so.'' The command for the double-click event should perform the
-extra work for the double click.
-
- If a double-click event has no binding, it changes to the
-corresponding single-click event. Thus, if you don't define a
-particular double click specially, it executes the single-click command
-twice.
-
- Emacs also supports triple-click events whose names start with
-@samp{triple-}. Emacs does not distinguish quadruple clicks as event
-types; clicks beyond the third generate additional triple-click events.
-However, the full number of clicks is recorded in the event list, so
-if you know Emacs Lisp you can distinguish if you really want to
-(@pxref{Accessing Events,,, elisp, The Emacs Lisp Reference Manual}).
-We don't recommend distinct meanings for more than three clicks, but
-sometimes it is useful for subsequent clicks to cycle through the same
-set of three meanings, so that four clicks are equivalent to one
-click, five are equivalent to two, and six are equivalent to three.
-
- Emacs also records multiple presses in drag and button-down events.
-For example, when you press a button twice, then move the mouse while
-holding the button, Emacs gets a @samp{double-drag-} event. And at the
-moment when you press it down for the second time, Emacs gets a
-@samp{double-down-} event (which is ignored, like all button-down
-events, if it has no binding).
-
-@vindex double-click-time
- The variable @code{double-click-time} specifies how much time can
-elapse between clicks and still allow them to be grouped as a multiple
-click. Its value is in units of milliseconds. If the value is
-@code{nil}, double clicks are not detected at all. If the value is
-@code{t}, then there is no time limit. The default is 500.
-
-@vindex double-click-fuzz
- The variable @code{double-click-fuzz} specifies how much the mouse
-can move between clicks and still allow them to be grouped as a multiple
-click. Its value is in units of pixels on windowed displays and in
-units of 1/8 of a character cell on text-mode terminals; the default is
-3.
-
- The symbols for mouse events also indicate the status of the modifier
-keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-},
-@samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-}
-or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}.
-
- A frame includes areas that don't show text from the buffer, such as
-the mode line and the scroll bar. You can tell whether a mouse button
-comes from a special area of the screen by means of dummy ``prefix
-keys.'' For example, if you click the mouse in the mode line, you get
-the prefix key @code{mode-line} before the ordinary mouse-button symbol.
-Thus, here is how to define the command for clicking the first button in
-a mode line to run @code{scroll-up}:
-
-@example
-(global-set-key [mode-line mouse-1] 'scroll-up)
-@end example
-
- Here is the complete list of these dummy prefix keys and their
-meanings:
-
-@table @code
-@item mode-line
-The mouse was in the mode line of a window.
-@item vertical-line
-The mouse was in the vertical line separating side-by-side windows. (If
-you use scroll bars, they appear in place of these vertical lines.)
-@item vertical-scroll-bar
-The mouse was in a vertical scroll bar. (This is the only kind of
-scroll bar Emacs currently supports.)
-@item menu-bar
-The mouse was in the menu bar.
-@item header-line
-The mouse was in a header line.
-@ignore
-@item horizontal-scroll-bar
-The mouse was in a horizontal scroll bar. Horizontal scroll bars do
-horizontal scrolling, and people don't use them often.
-@end ignore
-@end table
-
- You can put more than one mouse button in a key sequence, but it isn't
-usual to do so.
-
-@node Disabling
-@subsection Disabling Commands
-@cindex disabled command
-
- Disabling a command means that invoking it interactively asks for
-confirmation from the user. The purpose of disabling a command is to
-prevent users from executing it by accident; we do this for commands
-that might be confusing to the uninitiated.
-
- Attempting to invoke a disabled command interactively in Emacs
-displays a window containing the command's name, its documentation,
-and some instructions on what to do immediately; then Emacs asks for
-input saying whether to execute the command as requested, enable it
-and execute it, or cancel. If you decide to enable the command, you
-must then answer another question---whether to do this permanently, or
-just for the current session. (Enabling permanently works by
-automatically editing your @file{.emacs} file.) You can also type
-@kbd{!} to enable @emph{all} commands, for the current session only.
-
- The direct mechanism for disabling a command is to put a
-non-@code{nil} @code{disabled} property on the Lisp symbol for the
-command. Here is the Lisp program to do this:
-
-@example
-(put 'delete-region 'disabled t)
-@end example
-
- If the value of the @code{disabled} property is a string, that string
-is included in the message displayed when the command is used:
-
-@example
-(put 'delete-region 'disabled
- "It's better to use `kill-region' instead.\n")
-@end example
-
-@findex disable-command
-@findex enable-command
- You can make a command disabled either by editing the @file{.emacs}
-file directly, or with the command @kbd{M-x disable-command}, which edits
-the @file{.emacs} file for you. Likewise, @kbd{M-x enable-command}
-edits @file{.emacs} to enable a command permanently. @xref{Init File}.
-
- If Emacs was invoked with the @option{-q} or @option{--no-init-file}
-options (@pxref{Initial Options}), it will not edit your
-@file{~/.emacs} init file. Doing so could lose information
-because Emacs has not read your init file.
-
- Whether a command is disabled is independent of what key is used to
-invoke it; disabling also applies if the command is invoked using
-@kbd{M-x}. However, disabling a command has no effect on calling it
-as a function from Lisp programs.
-
-@node Syntax
-@section The Syntax Table
-@cindex syntax table
-
- All the Emacs commands which parse words or balance parentheses are
-controlled by the @dfn{syntax table}. The syntax table says which
-characters are opening delimiters, which are parts of words, which are
-string quotes, and so on. It does this by assigning each character to
-one of fifteen-odd @dfn{syntax classes}. In some cases it specifies
-some additional information also.
-
- Each major mode has its own syntax table (though related major modes
-sometimes share one syntax table), which it installs in each buffer
-that uses the mode. The syntax table installed in the current buffer
-is the one that all commands use, so we call it ``the'' syntax table.
-
-@kindex C-h s
-@findex describe-syntax
- To display a description of the contents of the current syntax
-table, type @kbd{C-h s} (@code{describe-syntax}). The description of
-each character includes the string you would have to give to
-@code{modify-syntax-entry} to set up that character's current syntax,
-starting with the character which designates its syntax class, plus
-some English text to explain its meaning.
-
- A syntax table is actually a Lisp object, a char-table, whose
-elements are cons cells. For full information on the syntax table,
-see @ref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp
-Reference Manual}.
-
-@node Init File
-@section The Init File, @file{~/.emacs}
-@cindex init file
-@cindex Emacs initialization file
-@cindex key rebinding, permanent
-@cindex rebinding keys, permanently
-@cindex startup (init file)
-
- When Emacs is started, it normally loads a Lisp program from the file
-@file{.emacs} or @file{.emacs.el} in your home directory (@pxref{Find Init}).
-We call this file your @dfn{init file} because it specifies how to
-initialize Emacs for you. You can use the command line switch
-@samp{-q} to prevent loading your init file, and @samp{-u} (or
-@samp{--user}) to specify a different user's init file (@pxref{Initial
-Options}).
-
- You can also use @file{~/.emacs.d/init.el} as the init file. Emacs
-tries this if it cannot find @file{~/.emacs} or @file{~/.emacs.el}.
-
-@cindex @file{default.el}, the default init file
- There can also be a @dfn{default init file}, which is the library
-named @file{default.el}, found via the standard search path for
-libraries. The Emacs distribution contains no such library; your site
-may create one for local customizations. If this library exists, it is
-loaded whenever you start Emacs (except when you specify @samp{-q}).
-But your init file, if any, is loaded first; if it sets
-@code{inhibit-default-init} non-@code{nil}, then @file{default} is not
-loaded.
-
-@cindex site init file
-@cindex @file{site-start.el}, the site startup file
- Your site may also have a @dfn{site startup file}; this is named
-@file{site-start.el}, if it exists. Like @file{default.el}, Emacs
-finds this file via the standard search path for Lisp libraries.
-Emacs loads this library before it loads your init file. To inhibit
-loading of this library, use the option @samp{--no-site-file}.
-@xref{Initial Options}. We recommend against using
-@file{site-start.el} for changes that some users may not like. It is
-better to put them in @file{default.el}, so that users can more easily
-override them.
-
- You can place @file{default.el} and @file{site-start.el} in any of
-the directories which Emacs searches for Lisp libraries. The variable
-@code{load-path} (@pxref{Lisp Libraries}) specifies these directories.
-Many sites put these files in the @file{site-lisp} subdirectory of the
-Emacs installation directory, typically
-@file{/usr/local/share/emacs/site-lisp}.
-
- If you have a large amount of code in your @file{.emacs} file, you
-should rename it to @file{~/.emacs.el}, and byte-compile it. @xref{Byte
-Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual},
-for more information about compiling Emacs Lisp programs.
-
- If you are going to write actual Emacs Lisp programs that go beyond
-minor customization, you should read the @cite{Emacs Lisp Reference Manual}.
-@ifnottex
-@xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference
-Manual}.
-@end ifnottex
-
-@menu
-* Init Syntax:: Syntax of constants in Emacs Lisp.
-* Init Examples:: How to do some things with an init file.
-* Terminal Init:: Each terminal type can have an init file.
-* Find Init:: How Emacs finds the init file.
-* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file.
-@end menu
-
-@node Init Syntax
-@subsection Init File Syntax
-
- The @file{.emacs} file contains one or more Lisp function call
-expressions. Each of these consists of a function name followed by
-arguments, all surrounded by parentheses. For example, @code{(setq
-fill-column 60)} calls the function @code{setq} to set the variable
-@code{fill-column} (@pxref{Filling}) to 60.
-
- You can set any Lisp variable with @code{setq}, but with certain
-variables @code{setq} won't do what you probably want in the
-@file{.emacs} file. Some variables automatically become buffer-local
-when set with @code{setq}; what you want in @file{.emacs} is to set
-the default value, using @code{setq-default}. Some customizable minor
-mode variables do special things to enable the mode when you set them
-with Customize, but ordinary @code{setq} won't do that; to enable the
-mode in your @file{.emacs} file, call the minor mode command. The
-following section has examples of both of these methods.
-
- The second argument to @code{setq} is an expression for the new
-value of the variable. This can be a constant, a variable, or a
-function call expression. In @file{.emacs}, constants are used most
-of the time. They can be:
-
-@table @asis
-@item Numbers:
-Numbers are written in decimal, with an optional initial minus sign.
-
-@item Strings:
-@cindex Lisp string syntax
-@cindex string syntax
-Lisp string syntax is the same as C string syntax with a few extra
-features. Use a double-quote character to begin and end a string constant.
-
-In a string, you can include newlines and special characters literally.
-But often it is cleaner to use backslash sequences for them: @samp{\n}
-for newline, @samp{\b} for backspace, @samp{\r} for carriage return,
-@samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for
-escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or
-@samp{\@var{ooo}} for the character whose octal code is @var{ooo}.
-Backslash and double-quote are the only characters for which backslash
-sequences are mandatory.
-
-@samp{\C-} can be used as a prefix for a control character, as in
-@samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for
-a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for
-@kbd{Control-Meta-A}.@refill
-
-@xref{Init Non-ASCII}, for information about including
-non-@acronym{ASCII} in your init file.
-
-@item Characters:
-Lisp character constant syntax consists of a @samp{?} followed by
-either a character or an escape sequence starting with @samp{\}.
-Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
-strings and characters are not interchangeable in Lisp; some contexts
-require one and some contexts require the other.
-
-@xref{Init Non-ASCII}, for information about binding commands to
-keys which send non-@acronym{ASCII} characters.
-
-@item True:
-@code{t} stands for `true'.
-
-@item False:
-@code{nil} stands for `false'.
-
-@item Other Lisp objects:
-Write a single-quote (@code{'}) followed by the Lisp object you want.
-@end table
-
-@node Init Examples
-@subsection Init File Examples
-
- Here are some examples of doing certain commonly desired things with
-Lisp expressions:
-
-@itemize @bullet
-@item
-Make @key{TAB} in C mode just insert a tab if point is in the middle of a
-line.
-
-@example
-(setq c-tab-always-indent nil)
-@end example
-
-Here we have a variable whose value is normally @code{t} for `true'
-and the alternative is @code{nil} for `false'.
-
-@item
-Make searches case sensitive by default (in all buffers that do not
-override this).
-
-@example
-(setq-default case-fold-search nil)
-@end example
-
-This sets the default value, which is effective in all buffers that do
-not have local values for the variable. Setting @code{case-fold-search}
-with @code{setq} affects only the current buffer's local value, which
-is not what you probably want to do in an init file.
-
-@item
-@vindex user-mail-address
-Specify your own email address, if Emacs can't figure it out correctly.
-
-@example
-(setq user-mail-address "rumsfeld@@torture.gov")
-@end example
-
-Various Emacs packages that need your own email address use the value of
-@code{user-mail-address}.
-
-@item
-Make Text mode the default mode for new buffers.
-
-@example
-(setq default-major-mode 'text-mode)
-@end example
-
-Note that @code{text-mode} is used because it is the command for
-entering Text mode. The single-quote before it makes the symbol a
-constant; otherwise, @code{text-mode} would be treated as a variable
-name.
-
-@need 1500
-@item
-Set up defaults for the Latin-1 character set
-which supports most of the languages of Western Europe.
-
-@example
-(set-language-environment "Latin-1")
-@end example
-
-@need 1500
-@item
-Turn off Line Number mode, a global minor mode.
-
-@example
-(line-number-mode 0)
-@end example
-
-@need 1500
-@item
-Turn on Auto Fill mode automatically in Text mode and related modes.
-
-@example
-(add-hook 'text-mode-hook
- '(lambda () (auto-fill-mode 1)))
-@end example
-
-This shows how to add a hook function to a normal hook variable
-(@pxref{Hooks}). The function we supply is a list starting with
-@code{lambda}, with a single-quote in front of it to make it a list
-constant rather than an expression.
-
-It's beyond the scope of this manual to explain Lisp functions, but for
-this example it is enough to know that the effect is to execute
-@code{(auto-fill-mode 1)} when Text mode is entered. You can replace
-that with any other expression that you like, or with several
-expressions in a row.
-
-Emacs comes with a function named @code{turn-on-auto-fill} whose
-definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler
-way to write the above example is as follows:
-
-@example
-(add-hook 'text-mode-hook 'turn-on-auto-fill)
-@end example
-
-@item
-Load the installed Lisp library named @file{foo} (actually a file
-@file{foo.elc} or @file{foo.el} in a standard Emacs directory).
-
-@example
-(load "foo")
-@end example
-
-When the argument to @code{load} is a relative file name, not starting
-with @samp{/} or @samp{~}, @code{load} searches the directories in
-@code{load-path} (@pxref{Lisp Libraries}).
-
-@item
-Load the compiled Lisp file @file{foo.elc} from your home directory.
-
-@example
-(load "~/foo.elc")
-@end example
-
-Here an absolute file name is used, so no searching is done.
-
-@item
-@cindex loading Lisp libraries automatically
-@cindex autoload Lisp libraries
-Tell Emacs to find the definition for the function @code{myfunction}
-by loading a Lisp library named @file{mypackage} (i.e.@: a file
-@file{mypackage.elc} or @file{mypackage.el}):
-
-@example
-(autoload 'myfunction "mypackage" "Do what I say." t)
-@end example
-
-@noindent
-Here the string @code{"Do what I say."} is the function's
-documentation string. You specify it in the @code{autoload}
-definition so it will be available for help commands even when the
-package is not loaded. The last argument, @code{t}, indicates that
-this function is interactive; that is, it can be invoked interactively
-by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key.
-If the function is not interactive, omit the @code{t} or use
-@code{nil}.
-
-@item
-Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}
-(@pxref{Init Rebinding}).
-
-@example
-(global-set-key "\C-xl" 'make-symbolic-link)
-@end example
-
-or
-
-@example
-(define-key global-map "\C-xl" 'make-symbolic-link)
-@end example
-
-Note once again the single-quote used to refer to the symbol
-@code{make-symbolic-link} instead of its value as a variable.
-
-@item
-Do the same thing for Lisp mode only.
-
-@example
-(define-key lisp-mode-map "\C-xl" 'make-symbolic-link)
-@end example
-
-@item
-Redefine all keys which now run @code{next-line} in Fundamental mode
-so that they run @code{forward-line} instead.
-
-@findex substitute-key-definition
-@example
-(substitute-key-definition 'next-line 'forward-line
- global-map)
-@end example
-
-@item
-Make @kbd{C-x C-v} undefined.
-
-@example
-(global-unset-key "\C-x\C-v")
-@end example
-
-One reason to undefine a key is so that you can make it a prefix.
-Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a
-prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix
-definition.
-
-@item
-Make @samp{$} have the syntax of punctuation in Text mode.
-Note the use of a character constant for @samp{$}.
-
-@example
-(modify-syntax-entry ?\$ "." text-mode-syntax-table)
-@end example
-
-@item
-Enable the use of the command @code{narrow-to-region} without confirmation.
-
-@example
-(put 'narrow-to-region 'disabled nil)
-@end example
-
-@item
-Adjusting the configuration to various platforms and Emacs versions.
-
-Users typically want Emacs to behave the same on all systems, so the
-same init file is right for all platforms. However, sometimes it
-happens that a function you use for customizing Emacs is not available
-on some platforms or in older Emacs versions. To deal with that
-situation, put the customization inside a conditional that tests whether
-the function or facility is available, like this:
-
-@example
-(if (fboundp 'blink-cursor-mode)
- (blink-cursor-mode 0))
-
-(if (boundp 'coding-category-utf-8)
- (set-coding-priority '(coding-category-utf-8)))
-@end example
-
-@noindent
-You can also simply disregard the errors that occur if the
-function is not defined.
-
-@example
-(condition case ()
- (set-face-background 'region "grey75")
- (error nil))
-@end example
-
-A @code{setq} on a variable which does not exist is generally
-harmless, so those do not need a conditional.
-@end itemize
-
-@node Terminal Init
-@subsection Terminal-specific Initialization
-
- Each terminal type can have a Lisp library to be loaded into Emacs when
-it is run on that type of terminal. For a terminal type named
-@var{termtype}, the library is called @file{term/@var{termtype}} and it is
-found by searching the directories @code{load-path} as usual and trying the
-suffixes @samp{.elc} and @samp{.el}. Normally it appears in the
-subdirectory @file{term} of the directory where most Emacs libraries are
-kept.@refill
-
- The usual purpose of the terminal-specific library is to map the
-escape sequences used by the terminal's function keys onto more
-meaningful names, using @code{function-key-map}. See the file
-@file{term/lk201.el} for an example of how this is done. Many function
-keys are mapped automatically according to the information in the
-Termcap data base; the terminal-specific library needs to map only the
-function keys that Termcap does not specify.
-
- When the terminal type contains a hyphen, only the part of the name
-before the first hyphen is significant in choosing the library name.
-Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
-the library @file{term/aaa}. The code in the library can use
-@code{(getenv "TERM")} to find the full terminal type name.@refill
-
-@vindex term-file-prefix
- The library's name is constructed by concatenating the value of the
-variable @code{term-file-prefix} and the terminal type. Your @file{.emacs}
-file can prevent the loading of the terminal-specific library by setting
-@code{term-file-prefix} to @code{nil}.
-
-@vindex term-setup-hook
- Emacs runs the hook @code{term-setup-hook} at the end of
-initialization, after both your @file{.emacs} file and any
-terminal-specific library have been read in. Add hook functions to this
-hook if you wish to override part of any of the terminal-specific
-libraries and to define initializations for terminals that do not have a
-library. @xref{Hooks}.
-
-@node Find Init
-@subsection How Emacs Finds Your Init File
-
- Normally Emacs uses the environment variable @env{HOME}
-(@pxref{General Variables, HOME}) to find @file{.emacs}; that's what
-@samp{~} means in a file name. If @file{.emacs} is not found inside
-@file{~/} (nor @file{.emacs.el}), Emacs looks for
-@file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be
-byte-compiled).
-
- However, if you run Emacs from a shell started by @code{su}, Emacs
-tries to find your own @file{.emacs}, not that of the user you are
-currently pretending to be. The idea is that you should get your own
-editor customizations even if you are running as the super user.
-
- More precisely, Emacs first determines which user's init file to use.
-It gets your user name from the environment variables @env{LOGNAME} and
-@env{USER}; if neither of those exists, it uses effective user-ID.
-If that user name matches the real user-ID, then Emacs uses @env{HOME};
-otherwise, it looks up the home directory corresponding to that user
-name in the system's data base of users.
-@c LocalWords: backtab
-
-@node Init Non-ASCII
-@subsection Non-@acronym{ASCII} Characters in Init Files
-@cindex international characters in @file{.emacs}
-@cindex non-@acronym{ASCII} characters in @file{.emacs}
-@cindex non-@acronym{ASCII} keys, binding
-@cindex rebinding non-@acronym{ASCII} keys
-
- Language and coding systems may cause problems if your init file
-contains non-@acronym{ASCII} characters, such as accented letters, in
-strings or key bindings.
-
- If you want to use non-@acronym{ASCII} characters in your init file,
-you should put a @w{@samp{-*-coding: @var{coding-system}-*-}} tag on
-the first line of the init file, and specify a coding system that
-supports the character(s) in question. @xref{Recognize Coding}. This
-is because the defaults for decoding non-@acronym{ASCII} text might
-not yet be set up by the time Emacs reads those parts of your init
-file which use such strings, possibly leading Emacs to decode those
-strings incorrectly. You should then avoid adding Emacs Lisp code
-that modifies the coding system in other ways, such as calls to
-@code{set-language-environment}.
-
- To bind non-@acronym{ASCII} keys, you must use a vector (@pxref{Init
-Rebinding}). The string syntax cannot be used, since the
-non-@acronym{ASCII} characters will be interpreted as meta keys. For
-instance:
-
-@example
-(global-set-key [?@var{char}] 'some-function)
-@end example
-
-@noindent
-Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}.
-
- @strong{Warning:} if you change the keyboard encoding, or change
-between multibyte and unibyte mode, or anything that would alter which
-code @kbd{C-q} would insert for that character, this keybinding may
-stop working. It is therefore advisable to use one and only one
-coding system, for your init file as well as the files you edit. For
-example, don't mix the @samp{latin-1} and @samp{latin-9} coding
-systems.
-
-@ignore
- arch-tag: c68abddb-4410-4fb5-925f-63394e971d93
-@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 This is part of the Emacs manual.
-@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@c
-@c This file is included either in emacs-xtra.texi (when producing the
-@c printed version) or in the main Emacs manual (for the on-line version).
-@node Subdir Switches
-@section Subdirectory Switches in Dired
-
-You can insert subdirectories with specified @code{ls} switches in
-Dired buffers, using @kbd{C-u i}. You can change the @code{ls}
-switches of an already inserted subdirectory using @kbd{C-u l}.
-
-In Emacs versions 22.1 and later, Dired remembers the switches, so
-that reverting the buffer will not change them back to the main
-directory's switches. Deleting a subdirectory forgets about its
-switches.
-
-Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u})
-to reinsert or delete subdirectories, that were inserted with explicit
-switches, can bypass Dired's machinery for remembering (or forgetting)
-switches. Deleting a subdirectory using @code{dired-undo} does not
-forget its switches. When later reinserted using @kbd{i}, it will be
-reinserted using its old switches. Using @code{dired-undo} to
-reinsert a subdirectory that was deleted using the regular
-Dired commands (not @code{dired-undo}) will originally insert it with
-its old switches. However, reverting the buffer will relist it using
-the buffer's default switches. If any of this yields problems, you
-can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}.
-
-Dired does not remember the @code{R} switch. Inserting a subdirectory
-with switches that include the @code{R} switch is equivalent with
-inserting each of its subdirectories using all remaining switches.
-For instance, updating or killing a subdirectory that was inserted
-with the @code{R} switch will not update or kill its subdirectories.
-
-The buffer's default switches do not affect subdirectories that were
-inserted using explicitly specified switches. In particular,
-commands such as @kbd{s}, that change the buffer's switches do not
-affect such subdirectories. (They do affect subdirectories without
-explicitly assigned switches, however.)
-
-You can make Dired forget about all subdirectory switches and relist
-all subdirectories with the buffer's default switches using
-@kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer.
-
-@ignore
- arch-tag: e3865701-9179-4ffb-bc34-d321111c688d
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Dired, Calendar/Diary, Rmail, Top
-@chapter Dired, the Directory Editor
-@cindex Dired
-@cindex file management
-
- Dired makes an Emacs buffer containing a listing of a directory, and
-optionally some of its subdirectories as well. You can use the normal
-Emacs commands to move around in this buffer, and special Dired commands
-to operate on the files listed.
-
- The Dired buffer is ``read-only,'' and inserting text in it is not
-useful, so ordinary printing characters such as @kbd{d} and @kbd{x}
-are redefined for special Dired commands. Some Dired commands
-@dfn{mark} or @dfn{flag} the @dfn{current file} (that is, the file on
-the current line); other commands operate on the marked files or on
-the flagged files. You first mark certain files in order to operate
-on all of them with on command.
-
- The Dired-X package provides various extra features for Dired mode.
-@xref{Top, Dired-X,,dired-x, Dired Extra Version 2 User's Manual}.
-
-@menu
-* Enter: Dired Enter. How to invoke Dired.
-* Navigation: Dired Navigation. Special motion commands in the Dired buffer.
-* Deletion: Dired Deletion. Deleting files with Dired.
-* Flagging Many Files:: Flagging files based on their names.
-* Visit: Dired Visiting. Other file operations through Dired.
-* Marks vs Flags:: Flagging for deletion vs marking.
-* Operating on Files:: How to copy, rename, print, compress, etc.
- either one file or several files.
-* Shell Commands in Dired:: Running a shell command on the marked files.
-* Transforming File Names:: Using patterns to rename multiple files.
-* Comparison in Dired:: Running `diff' by way of Dired.
-* Subdirectories in Dired:: Adding subdirectories to the Dired buffer.
-@ifnottex
-* Subdir Switches:: Subdirectory switches in Dired.
-@end ifnottex
-* Subdirectory Motion:: Moving across subdirectories, and up and down.
-* Hiding Subdirectories:: Making subdirectories visible or invisible.
-* Updating: Dired Updating. Discarding lines for files of no interest.
-* Find: Dired and Find. Using `find' to choose the files for Dired.
-* Wdired:: Operating on files by editing the Dired buffer.
-* Image-Dired:: Viewing image thumbnails in Dired
-* Misc: Misc Dired Features. Various other features.
-@end menu
-
-@node Dired Enter
-@section Entering Dired
-
-@findex dired
-@kindex C-x d
-@vindex dired-listing-switches
- To invoke Dired, do @kbd{C-x d} or @kbd{M-x dired}. The command
-reads a directory name or wildcard file name pattern as a minibuffer
-argument to specify the files to list. @kbd{C-x C-f} given a
-directory name also invokes Dired. Where @code{dired} differs from
-@code{list-directory} is that it puts the buffer into Dired mode, so
-that the special commands of Dired are available.
-
- The variable @code{dired-listing-switches} specifies the options to
-give to @code{ls} for listing the directory; this string @emph{must}
-contain @samp{-l}. If you use a numeric prefix argument with the
-@code{dired} command, you can specify the @code{ls} switches with the
-minibuffer before you enter the directory specification. No matter
-how they are specified, the @code{ls} switches can include short
-options (that is, single characters) requiring no arguments, and long
-options (starting with @samp{--}) whose arguments are specified with
-@samp{=}.
-
- On MS-Windows and MS-DOS systems, Emacs @emph{emulates} @code{ls};
-see @ref{ls in Lisp}, for options and peculiarities of that emulation.
-
-
-@findex dired-other-window
-@kindex C-x 4 d
-@findex dired-other-frame
-@kindex C-x 5 d
- To display the Dired buffer in another window rather than in the
-selected window, use @kbd{C-x 4 d} (@code{dired-other-window}) instead
-of @kbd{C-x d}. @kbd{C-x 5 d} (@code{dired-other-frame}) uses a
-separate frame to display the Dired buffer.
-
-@node Dired Navigation
-@section Navigation in the Dired Buffer
-
-@kindex C-n @r{(Dired)}
-@kindex C-p @r{(Dired)}
- All the usual Emacs cursor motion commands are available in Dired
-buffers. The keys @kbd{C-n} and @kbd{C-p} are redefined to put the
-cursor at the beginning of the file name on the line, rather than at
-the beginning of the line.
-
-@kindex SPC @r{(Dired)}
- For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent
-to @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. (Moving by lines is
-so common in Dired that it deserves to be easy to type.) @key{DEL}
-(move up and unflag) is often useful simply for moving up.
-
-@findex dired-goto-file
-@kindex j @r{(Dired)}
- @kbd{j} (@code{dired-goto-file}) moves point to the line that
-describes a specified file or directory.
-
- Some additional navigation commands are available when the Dired
-buffer includes several directories. @xref{Subdirectory Motion}.
-
-@node Dired Deletion
-@section Deleting Files with Dired
-@cindex flagging files (in Dired)
-@cindex deleting files (in Dired)
-
- One of the most frequent uses of Dired is to first @dfn{flag} files for
-deletion, then delete the files that were flagged.
-
-@table @kbd
-@item d
-Flag this file for deletion.
-@item u
-Remove deletion flag on this line.
-@item @key{DEL}
-Move point to previous line and remove the deletion flag on that line.
-@item x
-Delete the files that are flagged for deletion.
-@end table
-
-@kindex d @r{(Dired)}
-@findex dired-flag-file-deletion
- You can flag a file for deletion by moving to the line describing
-the file and typing @kbd{d} (@code{dired-flag-file-deletion}). The
-deletion flag is visible as a @samp{D} at the beginning of the line.
-This command moves point to the next line, so that repeated @kbd{d}
-commands flag successive files. A numeric argument serves as a repeat
-count.
-
-@kindex u @r{(Dired deletion)}
-@kindex DEL @r{(Dired)}
- The reason for flagging files for deletion, rather than deleting
-files immediately, is to reduce the danger of deleting a file
-accidentally. Until you direct Dired to delete the flagged files, you
-can remove deletion flags using the commands @kbd{u} and @key{DEL}.
-@kbd{u} (@code{dired-unmark}) works just like @kbd{d}, but removes
-flags rather than making flags. @key{DEL}
-(@code{dired-unmark-backward}) moves upward, removing flags; it is
-like @kbd{u} with argument @minus{}1.
-
-@kindex x @r{(Dired)}
-@findex dired-do-flagged-delete
-@cindex expunging (Dired)
- To delete the flagged files, type @kbd{x}
-(@code{dired-do-flagged-delete}). (This is also known as
-@dfn{expunging}.) This command first displays a list of all the file
-names flagged for deletion, and requests confirmation with @kbd{yes}.
-If you confirm, Dired deletes the flagged files, then deletes their
-lines from the text of the Dired buffer. The Dired buffer, with
-somewhat fewer lines, remains selected.
-
- If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you
-return immediately to Dired, with the deletion flags still present in
-the buffer, and no files actually deleted.
-
-@cindex recursive deletion
-@vindex dired-recursive-deletes
- You can delete empty directories just like other files, but normally
-Dired cannot delete directories that are nonempty. If the variable
-@code{dired-recursive-deletes} is non-@code{nil}, then Dired can
-delete nonempty directories including all their contents. That can
-be somewhat risky.
-
-@node Flagging Many Files
-@section Flagging Many Files at Once
-@cindex flagging many files for deletion (in Dired)
-
-@table @kbd
-@item #
-Flag all auto-save files (files whose names start and end with @samp{#})
-for deletion (@pxref{Auto Save}).
-
-@item ~
-Flag all backup files (files whose names end with @samp{~}) for deletion
-(@pxref{Backup}).
-
-@item &
-Flag for deletion all files with certain kinds of names which suggest
-you could easily create those files again.
-
-@item .@: @r{(Period)}
-Flag excess numeric backup files for deletion. The oldest and newest
-few backup files of any one file are exempt; the middle ones are
-flagged.
-
-@item % d @var{regexp} @key{RET}
-Flag for deletion all files whose names match the regular expression
-@var{regexp}.
-@end table
-
- The @kbd{#}, @kbd{~}, @kbd{&}, and @kbd{.} commands flag many files for
-deletion, based on their file names. These commands are useful
-precisely because they do not themselves delete any files; you can
-remove the deletion flags from any flagged files that you really wish to
-keep.@refill
-
-@kindex & @r{(Dired)}
-@findex dired-flag-garbage-files
-@vindex dired-garbage-files-regexp
-@cindex deleting some backup files
- @kbd{&} (@code{dired-flag-garbage-files}) flags files whose names
-match the regular expression specified by the variable
-@code{dired-garbage-files-regexp}. By default, this matches certain
-files produced by @TeX{}, @samp{.bak} files, and the @samp{.orig} and
-@samp{.rej} files produced by @code{patch}.
-
-@kindex # @r{(Dired)}
-@findex dired-flag-auto-save-files
-@cindex deleting auto-save files
- @kbd{#} (@code{dired-flag-auto-save-files}) flags for deletion all
-files whose names look like auto-save files---that is, files whose
-names begin and end with @samp{#}. @xref{Auto Save}.
-
-@kindex ~ @r{(Dired)}
-@findex dired-flag-backup-files
- @kbd{~} (@code{dired-flag-backup-files}) flags for deletion all
-files whose names say they are backup files---that is, files whose
-names end in @samp{~}. @xref{Backup}.
-
-@kindex . @r{(Dired)}
-@vindex dired-kept-versions
-@findex dired-clean-directory
- @kbd{.} (period, @code{dired-clean-directory}) flags just some of the
-backup files for deletion: all but the oldest few and newest few backups
-of any one file. Normally @code{dired-kept-versions} (@strong{not}
-@code{kept-new-versions}; that applies only when saving) specifies the
-number of newest versions of each file to keep, and
-@code{kept-old-versions} specifies the number of oldest versions to
-keep.
-
- Period with a positive numeric argument, as in @kbd{C-u 3 .},
-specifies the number of newest versions to keep, overriding
-@code{dired-kept-versions}. A negative numeric argument overrides
-@code{kept-old-versions}, using minus the value of the argument to
-specify the number of oldest versions of each file to keep.
-
-@findex dired-flag-files-regexp
-@kindex % d @r{(Dired)}
- The @kbd{% d} command flags all files whose names match a specified
-regular expression (@code{dired-flag-files-regexp}). Only the
-non-directory part of the file name is used in matching. You can use
-@samp{^} and @samp{$} to anchor matches. You can exclude certain
-subdirectories from marking by hiding them while you use @kbd{% d}.
-@xref{Hiding Subdirectories}.
-
-@node Dired Visiting
-@section Visiting Files in Dired
-
- There are several Dired commands for visiting or examining the files
-listed in the Dired buffer. All of them apply to the current line's
-file; if that file is really a directory, these commands invoke Dired on
-that subdirectory (making a separate Dired buffer).
-
-@table @kbd
-@item f
-@kindex f @r{(Dired)}
-@findex dired-find-file
-Visit the file described on the current line, like typing @kbd{C-x C-f}
-and supplying that file name (@code{dired-find-file}). @xref{Visiting}.
-
-@item @key{RET}
-@itemx e
-@kindex RET @r{(Dired)}
-@kindex e @r{(Dired)}
-Equivalent to @kbd{f}.
-
-@ignore @c This command seems too risky to document at all.
-@item a
-@kindex a @r{(Dired)}
-@findex dired-find-alternate-file
-Like @kbd{f}, but replaces the contents of the Dired buffer with
-that of an alternate file or directory (@code{dired-find-alternate-file}).
-@end ignore
-
-@item o
-@kindex o @r{(Dired)}
-@findex dired-find-file-other-window
-Like @kbd{f}, but uses another window to display the file's buffer
-(@code{dired-find-file-other-window}). The Dired buffer remains visible
-in the first window. This is like using @kbd{C-x 4 C-f} to visit the
-file. @xref{Windows}.
-
-@item C-o
-@kindex C-o @r{(Dired)}
-@findex dired-display-file
-Visit the file described on the current line, and display the buffer in
-another window, but do not select that window (@code{dired-display-file}).
-
-@item Mouse-1
-@itemx Mouse-2
-@findex dired-mouse-find-file-other-window
-Visit the file named by the line you click on
-(@code{dired-mouse-find-file-other-window}). This uses another window
-to display the file, like the @kbd{o} command.
-
-@item v
-@kindex v @r{(Dired)}
-@findex dired-view-file
-View the file described on the current line, using @kbd{M-x view-file}
-(@code{dired-view-file}). Viewing a file with @code{view-file} is
-like visiting it, but is slanted toward moving around in the file
-conveniently and does not allow changing the file. @xref{Misc File
-Ops, View File, Miscellaneous File Operations}.
-
-@item ^
-@kindex ^ @r{(Dired)}
-@findex dired-up-directory
-Visit the parent directory of the current directory
-(@code{dired-up-directory}). This is equivalent to moving to the line
-for @file{..} and typing @kbd{f} there.
-@end table
-
-@node Marks vs Flags
-@section Dired Marks vs. Flags
-
-@cindex marking many files (in Dired)
- Instead of flagging a file with @samp{D}, you can @dfn{mark} the
-file with some other character (usually @samp{*}). Most Dired
-commands to operate on files use the files marked with @samp{*}. The
-only command that operates on flagged files is @kbd{x}, which expunges
-them.
-
- Here are some commands for marking with @samp{*}, for unmarking, and
-for operating on marks. (@xref{Dired Deletion}, for commands to flag
-and unflag files.)
-
-@table @kbd
-@item m
-@itemx * m
-@kindex m @r{(Dired)}
-@kindex * m @r{(Dired)}
-@findex dired-mark
-Mark the current file with @samp{*} (@code{dired-mark}). With a numeric
-argument @var{n}, mark the next @var{n} files starting with the current
-file. (If @var{n} is negative, mark the previous @minus{}@var{n}
-files.)
-
-@item * *
-@kindex * * @r{(Dired)}
-@findex dired-mark-executables
-@cindex marking executable files (in Dired)
-Mark all executable files with @samp{*}
-(@code{dired-mark-executables}). With a numeric argument, unmark all
-those files.
-
-@item * @@
-@kindex * @@ @r{(Dired)}
-@findex dired-mark-symlinks
-@cindex marking symbolic links (in Dired)
-Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}).
-With a numeric argument, unmark all those files.
-
-@item * /
-@kindex * / @r{(Dired)}
-@findex dired-mark-directories
-@cindex marking subdirectories (in Dired)
-Mark with @samp{*} all files which are directories, except for
-@file{.} and @file{..} (@code{dired-mark-directories}). With a numeric
-argument, unmark all those files.
-
-@item * s
-@kindex * s @r{(Dired)}
-@findex dired-mark-subdir-files
-Mark all the files in the current subdirectory, aside from @file{.}
-and @file{..} (@code{dired-mark-subdir-files}).
-
-@item u
-@itemx * u
-@kindex u @r{(Dired)}
-@kindex * u @r{(Dired)}
-@findex dired-unmark
-Remove any mark on this line (@code{dired-unmark}).
-
-@item @key{DEL}
-@itemx * @key{DEL}
-@kindex * DEL @r{(Dired)}
-@findex dired-unmark-backward
-@cindex unmarking files (in Dired)
-Move point to previous line and remove any mark on that line
-(@code{dired-unmark-backward}).
-
-@item * !
-@itemx U
-@kindex * ! @r{(Dired)}
-@kindex U @r{(Dired)}
-@findex dired-unmark-all-marks
-Remove all marks from all the files in this Dired buffer
-(@code{dired-unmark-all-marks}).
-
-@item * ? @var{markchar}
-@itemx M-@key{DEL}
-@kindex * ? @r{(Dired)}
-@kindex M-DEL @r{(Dired)}
-@findex dired-unmark-all-files
-Remove all marks that use the character @var{markchar}
-(@code{dired-unmark-all-files}). The argument is a single
-character---do not use @key{RET} to terminate it. See the description
-of the @kbd{* c} command below, which lets you replace one mark
-character with another.
-
-With a numeric argument, this command queries about each marked file,
-asking whether to remove its mark. You can answer @kbd{y} meaning yes,
-@kbd{n} meaning no, or @kbd{!} to remove the marks from the remaining
-files without asking about them.
-
-@item * C-n
-@itemx M-@}
-@findex dired-next-marked-file
-@kindex * C-n @r{(Dired)}
-@kindex M-@} @r{(Dired)}
-Move down to the next marked file (@code{dired-next-marked-file})
-A file is ``marked'' if it has any kind of mark.
-
-@item * C-p
-@itemx M-@{
-@findex dired-prev-marked-file
-@kindex * C-p @r{(Dired)}
-@kindex M-@{ @r{(Dired)}
-Move up to the previous marked file (@code{dired-prev-marked-file})
-
-@item t
-@itemx * t
-@kindex t @r{(Dired)}
-@kindex * t @r{(Dired)}
-@findex dired-toggle-marks
-@cindex toggling marks (in Dired)
-Toggle all marks (@code{dired-toggle-marks}): files marked with @samp{*}
-become unmarked, and unmarked files are marked with @samp{*}. Files
-marked in any other way are not affected.
-
-@item * c @var{old-markchar} @var{new-markchar}
-@kindex * c @r{(Dired)}
-@findex dired-change-marks
-Replace all marks that use the character @var{old-markchar} with marks
-that use the character @var{new-markchar} (@code{dired-change-marks}).
-This command is the primary way to create or use marks other than
-@samp{*} or @samp{D}. The arguments are single characters---do not use
-@key{RET} to terminate them.
-
-You can use almost any character as a mark character by means of this
-command, to distinguish various classes of files. If @var{old-markchar}
-is a space (@samp{ }), then the command operates on all unmarked files;
-if @var{new-markchar} is a space, then the command unmarks the files it
-acts on.
-
-To illustrate the power of this command, here is how to put @samp{D}
-flags on all the files that have no marks, while unflagging all those
-that already have @samp{D} flags:
-
-@example
-* c D t * c SPC D * c t SPC
-@end example
-
-This assumes that no files were already marked with @samp{t}.
-
-@item % m @var{regexp} @key{RET}
-@itemx * % @var{regexp} @key{RET}
-@findex dired-mark-files-regexp
-@kindex % m @r{(Dired)}
-@kindex * % @r{(Dired)}
-Mark (with @samp{*}) all files whose names match the regular expression
-@var{regexp} (@code{dired-mark-files-regexp}). This command is like
-@kbd{% d}, except that it marks files with @samp{*} instead of flagging
-with @samp{D}.
-
-Only the non-directory part of the file name is used in matching. Use
-@samp{^} and @samp{$} to anchor matches. You can exclude
-subdirectories by temporarily hiding them (@pxref{Hiding
-Subdirectories}).
-
-@item % g @var{regexp} @key{RET}
-@findex dired-mark-files-containing-regexp
-@kindex % g @r{(Dired)}
-@cindex finding files containing regexp matches (in Dired)
-Mark (with @samp{*}) all files whose @emph{contents} contain a match for
-the regular expression @var{regexp}
-(@code{dired-mark-files-containing-regexp}). This command is like
-@kbd{% m}, except that it searches the file contents instead of the file
-name.
-
-@item C-x u
-@itemx C-_
-@itemx C-/
-@kindex C-_ @r{(Dired)}
-@findex dired-undo
-Undo changes in the Dired buffer, such as adding or removing
-marks (@code{dired-undo}). @emph{This command does not revert the
-actual file operations, nor recover lost files!} It just undoes
-changes in the buffer itself.
-
-In some cases, using this after commands that operate on files can
-cause trouble. For example, after renaming one or more files,
-@code{dired-undo} restores the original names in the Dired buffer,
-which gets the Dired buffer out of sync with the actual contents of
-the directory.
-@end table
-
-@node Operating on Files
-@section Operating on Files
-@cindex operating on files in Dired
-
- This section describes the basic Dired commands to operate on one file
-or several files. All of these commands are capital letters; all of
-them use the minibuffer, either to read an argument or to ask for
-confirmation, before they act. All of them let you specify the
-files to manipulate in these ways:
-
-@itemize @bullet
-@item
-If you give the command a numeric prefix argument @var{n}, it operates
-on the next @var{n} files, starting with the current file. (If @var{n}
-is negative, the command operates on the @minus{}@var{n} files preceding
-the current line.)
-
-@item
-Otherwise, if some files are marked with @samp{*}, the command operates
-on all those files.
-
-@item
-Otherwise, the command operates on the current file only.
-@end itemize
-
-@noindent
-Certain other Dired commands, such as @kbd{!} and the @samp{%}
-commands, use the same conventions to decide which files to work on.
-
-@vindex dired-dwim-target
-@cindex two directories (in Dired)
- Commands which ask for a destination directory, such as those which
-copy and rename files or create links for them, try to guess the default
-target directory for the operation. Normally, they suggest the Dired
-buffer's default directory, but if the variable @code{dired-dwim-target}
-is non-@code{nil}, and if there is another Dired buffer displayed in the
-next window, that other buffer's directory is suggested instead.
-
- Here are the file-manipulating Dired commands that operate on files.
-
-@table @kbd
-@findex dired-do-copy
-@kindex C @r{(Dired)}
-@cindex copying files (in Dired)
-@item C @var{new} @key{RET}
-Copy the specified files (@code{dired-do-copy}). The argument @var{new}
-is the directory to copy into, or (if copying a single file) the new
-name. This is like the shell command @code{cp}.
-
-@vindex dired-copy-preserve-time
-If @code{dired-copy-preserve-time} is non-@code{nil}, then copying
-with this command preserves the modification time of the old file in
-the copy, like @samp{cp -p}.
-
-@vindex dired-recursive-copies
-@cindex recursive copying
-The variable @code{dired-recursive-copies} controls whether to copy
-directories recursively (like @samp{cp -r}). The default is
-@code{nil}, which means that directories cannot be copied.
-
-@item D
-@findex dired-do-delete
-@kindex D @r{(Dired)}
-Delete the specified files (@code{dired-do-delete}). This is like the
-shell command @code{rm}.
-
-Like the other commands in this section, this command operates on the
-@emph{marked} files, or the next @var{n} files. By contrast, @kbd{x}
-(@code{dired-do-flagged-delete}) deletes all @dfn{flagged} files.
-
-@findex dired-do-rename
-@kindex R @r{(Dired)}
-@cindex renaming files (in Dired)
-@cindex moving files (in Dired)
-@item R @var{new} @key{RET}
-Rename the specified files (@code{dired-do-rename}). If you rename a
-single file, the argument @var{new} is the new name of the file. If
-you rename several files, the argument @var{new} is the directory into
-which to move the files (this is like the shell command @code{mv}).
-
-Dired automatically changes the visited file name of buffers associated
-with renamed files so that they refer to the new names.
-
-@findex dired-do-hardlink
-@kindex H @r{(Dired)}
-@cindex hard links (in Dired)
-@item H @var{new} @key{RET}
-Make hard links to the specified files (@code{dired-do-hardlink}).
-This is like the shell command @code{ln}. The argument @var{new} is
-the directory to make the links in, or (if making just one link) the
-name to give the link.
-
-@findex dired-do-symlink
-@kindex S @r{(Dired)}
-@cindex symbolic links (creation in Dired)
-@item S @var{new} @key{RET}
-Make symbolic links to the specified files (@code{dired-do-symlink}).
-This is like @samp{ln -s}. The argument @var{new} is the directory to
-make the links in, or (if making just one link) the name to give the
-link.
-
-@findex dired-do-chmod
-@kindex M @r{(Dired)}
-@cindex changing file permissions (in Dired)
-@item M @var{modespec} @key{RET}
-Change the mode (also called ``permission bits'') of the specified files
-(@code{dired-do-chmod}). This uses the @code{chmod} program, so
-@var{modespec} can be any argument that @code{chmod} can handle.
-
-@findex dired-do-chgrp
-@kindex G @r{(Dired)}
-@cindex changing file group (in Dired)
-@item G @var{newgroup} @key{RET}
-Change the group of the specified files to @var{newgroup}
-(@code{dired-do-chgrp}).
-
-@findex dired-do-chown
-@kindex O @r{(Dired)}
-@cindex changing file owner (in Dired)
-@item O @var{newowner} @key{RET}
-Change the owner of the specified files to @var{newowner}
-(@code{dired-do-chown}). (On most systems, only the superuser can do
-this.)
-
-@vindex dired-chown-program
-The variable @code{dired-chown-program} specifies the name of the
-program to use to do the work (different systems put @code{chown} in
-different places).
-
-@findex dired-do-touch
-@kindex T @r{(Dired)}
-@cindex changing file time (in Dired)
-@item T @var{timestamp} @key{RET}
-Touch the specified files (@code{dired-do-touch}). This means
-updating their modification times to the present time. This is like
-the shell command @code{touch}.
-
-@findex dired-do-print
-@kindex P @r{(Dired)}
-@cindex printing files (in Dired)
-@item P @var{command} @key{RET}
-Print the specified files (@code{dired-do-print}). You must specify the
-command to print them with, but the minibuffer starts out with a
-suitable guess made using the variables @code{lpr-command} and
-@code{lpr-switches} (the same variables that @code{lpr-buffer} uses;
-@pxref{Printing}).
-
-@findex dired-do-compress
-@kindex Z @r{(Dired)}
-@cindex compressing files (in Dired)
-@item Z
-Compress the specified files (@code{dired-do-compress}). If the file
-appears to be a compressed file already, uncompress it instead.
-
-@findex dired-do-load
-@kindex L @r{(Dired)}
-@cindex loading several files (in Dired)
-@item L
-Load the specified Emacs Lisp files (@code{dired-do-load}).
-@xref{Lisp Libraries}.
-
-@findex dired-do-byte-compile
-@kindex B @r{(Dired)}
-@cindex byte-compiling several files (in Dired)
-@item B
-Byte compile the specified Emacs Lisp files
-(@code{dired-do-byte-compile}). @xref{Byte Compilation,, Byte
-Compilation, elisp, The Emacs Lisp Reference Manual}.
-
-@kindex A @r{(Dired)}
-@findex dired-do-search
-@cindex search multiple files (in Dired)
-@item A @var{regexp} @key{RET}
-Search all the specified files for the regular expression @var{regexp}
-(@code{dired-do-search}).
-
-This command is a variant of @code{tags-search}. The search stops at
-the first match it finds; use @kbd{M-,} to resume the search and find
-the next match. @xref{Tags Search}.
-
-@kindex Q @r{(Dired)}
-@findex dired-do-query-replace-regexp
-@cindex search and replace in multiple files (in Dired)
-@item Q @var{regexp} @key{RET} @var{to} @key{RET}
-Perform @code{query-replace-regexp} on each of the specified files,
-replacing matches for @var{regexp} with the string
-@var{to} (@code{dired-do-query-replace-regexp}).
-
-This command is a variant of @code{tags-query-replace}. If you exit the
-query replace loop, you can use @kbd{M-,} to resume the scan and replace
-more matches. @xref{Tags Search}.
-@end table
-
-@node Shell Commands in Dired
-@section Shell Commands in Dired
-@cindex shell commands, Dired
-
-@findex dired-do-shell-command
-@kindex ! @r{(Dired)}
-@kindex X @r{(Dired)}
-The Dired command @kbd{!} (@code{dired-do-shell-command}) reads a
-shell command string in the minibuffer and runs that shell command on
-all the specified files. (@kbd{X} is a synonym for @kbd{!}.) You can
-specify the files to operate on in the usual ways for Dired commands
-(@pxref{Operating on Files}).
-
- The working directory for the shell command is the top-level directory
-of the Dired buffer.
-
- There are two ways of applying a shell command to multiple files:
-
-@itemize @bullet
-@item
-If you use @samp{*} surrounded by whitespace in the shell command,
-then the command runs just once, with the list of file names
-substituted for the @samp{*}. The order of file names is the order of
-appearance in the Dired buffer.
-
-Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire
-list of file names, putting them into one tar file @file{foo.tar}.
-
-If you want to use @samp{*} as a shell wildcard with whitespace around
-it, write @samp{*""}. In the shell, this is equivalent to @samp{*};
-but since the @samp{*} is not surrounded by whitespace, Dired does
-not treat it specially.
-
-@item
-If the command string doesn't contain @samp{*} surrounded by
-whitespace, then it runs once @emph{for each file}. Normally the file
-name is added at the end.
-
-For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on each
-file.
-
-@item
-However, if the command string contains @samp{?} surrounded by
-whitespace, the current file name is substituted for @samp{?} (rather
-than added at the end). You can use @samp{?} this way more than once
-in the command, and the same file name replaces each occurrence.
-@end itemize
-
- To iterate over the file names in a more complicated fashion, use an
-explicit shell loop. For example, here is how to uuencode each file,
-making the output file name by appending @samp{.uu} to the input file
-name:
-
-@example
-for file in * ; do uuencode "$file" "$file" >"$file".uu; done
-@end example
-
- The @kbd{!} command does not attempt to update the Dired buffer to
-show new or modified files, because it doesn't understand shell
-commands, and does not know what files the shell command changed. Use
-the @kbd{g} command to update the Dired buffer (@pxref{Dired
-Updating}).
-
-@node Transforming File Names
-@section Transforming File Names in Dired
-
- This section describes Dired commands which alter file names in a
-systematic way. Each command operates on some or all of the marked
-files, using a new name made by transforming the existing name.
-
- Like the basic Dired file-manipulation commands (@pxref{Operating on
-Files}), the commands described here operate either on the next
-@var{n} files, or on all files marked with @samp{*}, or on the current
-file. (To mark files, use the commands described in @ref{Marks vs
-Flags}.)
-
- All of the commands described in this section work
-@emph{interactively}: they ask you to confirm the operation for each
-candidate file. Thus, you can select more files than you actually
-need to operate on (e.g., with a regexp that matches many files), and
-then filter the selected names by typing @kbd{y} or @kbd{n} when the
-command prompts for confirmation.
-
-@table @kbd
-@findex dired-upcase
-@kindex % u @r{(Dired)}
-@cindex upcase file names
-@item % u
-Rename each of the selected files to an upper-case name
-(@code{dired-upcase}). If the old file names are @file{Foo}
-and @file{bar}, the new names are @file{FOO} and @file{BAR}.
-
-@item % l
-@findex dired-downcase
-@kindex % l @r{(Dired)}
-@cindex downcase file names
-Rename each of the selected files to a lower-case name
-(@code{dired-downcase}). If the old file names are @file{Foo} and
-@file{bar}, the new names are @file{foo} and @file{bar}.
-
-@item % R @var{from} @key{RET} @var{to} @key{RET}
-@kindex % R @r{(Dired)}
-@findex dired-do-rename-regexp
-@itemx % C @var{from} @key{RET} @var{to} @key{RET}
-@kindex % C @r{(Dired)}
-@findex dired-do-copy-regexp
-@itemx % H @var{from} @key{RET} @var{to} @key{RET}
-@kindex % H @r{(Dired)}
-@findex dired-do-hardlink-regexp
-@itemx % S @var{from} @key{RET} @var{to} @key{RET}
-@kindex % S @r{(Dired)}
-@findex dired-do-symlink-regexp
-These four commands rename, copy, make hard links and make soft links,
-in each case computing the new name by regular-expression substitution
-from the name of the old file.
-@end table
-
- The four regular-expression substitution commands effectively
-perform a search-and-replace on the selected file names. They read
-two arguments: a regular expression @var{from}, and a substitution
-pattern @var{to}; they match each ``old'' file name against
-@var{from}, and then replace the matching part with @var{to}. You can
-use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to all or
-part of what the pattern matched in the old file name, as in
-@code{replace-regexp} (@pxref{Regexp Replace}). If the regular
-expression matches more than once in a file name, only the first match
-is replaced.
-
- For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each
-selected file by prepending @samp{x-} to its name. The inverse of this,
-removing @samp{x-} from the front of each file name, is also possible:
-one method is @kbd{% R ^x-\(.*\)$ @key{RET} \1 @key{RET}}; another is
-@kbd{% R ^x- @key{RET} @key{RET}}. (Use @samp{^} and @samp{$} to anchor
-matches that should span the whole file name.)
-
- Normally, the replacement process does not consider the files'
-directory names; it operates on the file name within the directory. If
-you specify a numeric argument of zero, then replacement affects the
-entire absolute file name including directory name. (A non-zero
-argument specifies the number of files to operate on.)
-
- You may want to select the set of files to operate on using the same
-regexp @var{from} that you will use to operate on them. To do this,
-mark those files with @kbd{% m @var{from} @key{RET}}, then use the
-same regular expression in the command to operate on the files. To
-make this more convenient, the @kbd{%} commands to operate on files
-use the last regular expression specified in any @kbd{%} command as a
-default.
-
-@node Comparison in Dired
-@section File Comparison with Dired
-@cindex file comparison (in Dired)
-@cindex compare files (in Dired)
-
- Here are two Dired commands that compare specified files using
-@code{diff}. They show the output in a buffer using Diff mode
-(@pxref{Comparing Files}).
-
-@table @kbd
-@item =
-@findex dired-diff
-@kindex = @r{(Dired)}
-Compare the current file (the file at point) with another file (the
-file at the mark) using the @code{diff} program (@code{dired-diff}).
-The file at the mark is the first argument of @code{diff}, and the
-file at point is the second argument. This refers to the ordinary
-Emacs mark, not Dired marks; use @kbd{C-@key{SPC}}
-(@code{set-mark-command}) to set the mark at the first file's line
-(@pxref{Setting Mark}).
-
-@findex dired-backup-diff
-@kindex M-= @r{(Dired)}
-@item M-=
-Compare the current file with its latest backup file
-(@code{dired-backup-diff}). If the current file is itself a backup,
-compare it with the file it is a backup of; this way, you can compare
-a file with any one of its backups.
-
-The backup file is the first file given to @code{diff}.
-@end table
-
-@node Subdirectories in Dired
-@section Subdirectories in Dired
-@cindex subdirectories in Dired
-@cindex expanding subdirectories in Dired
-
- A Dired buffer displays just one directory in the normal case;
-but you can optionally include its subdirectories as well.
-
- The simplest way to include multiple directories in one Dired buffer is
-to specify the options @samp{-lR} for running @code{ls}. (If you give a
-numeric argument when you run Dired, then you can specify these options
-in the minibuffer.) That produces a recursive directory listing showing
-all subdirectories at all levels.
-
- More often, you will want to show only specific subdirectories. You
-can do this with the @kbd{i} command:
-
-@table @kbd
-@findex dired-maybe-insert-subdir
-@kindex i @r{(Dired)}
-@item i
-@cindex inserted subdirectory (Dired)
-@cindex in-situ subdirectory (Dired)
-Insert the contents of a subdirectory later in the buffer.
-@end table
-
-Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line
-that describes a file which is a directory. It inserts the contents of
-that directory into the same Dired buffer, and moves there. Inserted
-subdirectory contents follow the top-level directory of the Dired
-buffer, just as they do in @samp{ls -lR} output.
-
-If the subdirectory's contents are already present in the buffer, the
-@kbd{i} command just moves to it.
-
-In either case, @kbd{i} sets the Emacs mark before moving, so @kbd{C-u
-C-@key{SPC}} takes you back to the old position in the buffer (the line
-describing that subdirectory).
-
-Use the @kbd{l} command (@code{dired-do-redisplay}) to update the
-subdirectory's contents. Use @kbd{C-u k} on the subdirectory header
-line to delete the subdirectory. @xref{Dired Updating}.
-
-
-
-
-@ifnottex
-@include dired-xtra.texi
-@end ifnottex
-
-@node Subdirectory Motion
-@section Moving Over Subdirectories
-
- When a Dired buffer lists subdirectories, you can use the page motion
-commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories
-(@pxref{Pages}).
-
-@cindex header line (Dired)
-@cindex directory header lines
- The following commands move across, up and down in the tree of
-directories within one Dired buffer. They move to @dfn{directory header
-lines}, which are the lines that give a directory's name, at the
-beginning of the directory's contents.
-
-@table @kbd
-@findex dired-next-subdir
-@kindex C-M-n @r{(Dired)}
-@item C-M-n
-Go to next subdirectory header line, regardless of level
-(@code{dired-next-subdir}).
-
-@findex dired-prev-subdir
-@kindex C-M-p @r{(Dired)}
-@item C-M-p
-Go to previous subdirectory header line, regardless of level
-(@code{dired-prev-subdir}).
-
-@findex dired-tree-up
-@kindex C-M-u @r{(Dired)}
-@item C-M-u
-Go up to the parent directory's header line (@code{dired-tree-up}).
-
-@findex dired-tree-down
-@kindex C-M-d @r{(Dired)}
-@item C-M-d
-Go down in the directory tree, to the first subdirectory's header line
-(@code{dired-tree-down}).
-
-@findex dired-prev-dirline
-@kindex < @r{(Dired)}
-@item <
-Move up to the previous directory-file line (@code{dired-prev-dirline}).
-These lines are the ones that describe a directory as a file in its
-parent directory.
-
-@findex dired-next-dirline
-@kindex > @r{(Dired)}
-@item >
-Move down to the next directory-file line (@code{dired-prev-dirline}).
-@end table
-
-@node Hiding Subdirectories
-@section Hiding Subdirectories
-
-@cindex hiding in Dired (Dired)
- @dfn{Hiding} a subdirectory means to make it invisible, except for its
-header line.
-
-@table @kbd
-@item $
-@findex dired-hide-subdir
-@kindex $ @r{(Dired)}
-Hide or reveal the subdirectory that point is in, and move point to the
-next subdirectory (@code{dired-hide-subdir}). A numeric argument serves
-as a repeat count.
-
-@item M-$
-@findex dired-hide-all
-@kindex M-$ @r{(Dired)}
-Hide all subdirectories in this Dired buffer, leaving only their header
-lines (@code{dired-hide-all}). Or, if any subdirectory is currently
-hidden, make all subdirectories visible again. You can use this command
-to get an overview in very deep directory trees or to move quickly to
-subdirectories far away.
-@end table
-
- Ordinary Dired commands never consider files inside a hidden
-subdirectory. For example, the commands to operate on marked files
-ignore files in hidden directories even if they are marked. Thus you
-can use hiding to temporarily exclude subdirectories from operations
-without having to remove the Dired marks on files in those
-subdirectories.
-
-@node Dired Updating
-@section Updating the Dired Buffer
-@cindex updating Dired buffer
-@cindex refreshing displayed files
-
- This section describes commands to update the Dired buffer to reflect
-outside (non-Dired) changes in the directories and files, and to delete
-part of the Dired buffer.
-
-@table @kbd
-@item g
-Update the entire contents of the Dired buffer (@code{revert-buffer}).
-
-@item l
-Update the specified files (@code{dired-do-redisplay}). You specify the
-files for @kbd{l} in the same way as for file operations.
-
-@item k
-Delete the specified @emph{file lines}---not the files, just the lines
-(@code{dired-do-kill-lines}).
-
-@item s
-Toggle between alphabetical order and date/time order
-(@code{dired-sort-toggle-or-edit}).
-
-@item C-u s @var{switches} @key{RET}
-Refresh the Dired buffer using @var{switches} as
-@code{dired-listing-switches}.
-@end table
-
-@kindex g @r{(Dired)}
-@findex revert-buffer @r{(Dired)}
- Type @kbd{g} (@code{revert-buffer}) to update the contents of the
-Dired buffer, based on changes in the files and directories listed.
-This preserves all marks except for those on files that have vanished.
-Hidden subdirectories are updated but remain hidden.
-
-@kindex l @r{(Dired)}
-@findex dired-do-redisplay
- To update only some of the files, type @kbd{l}
-(@code{dired-do-redisplay}). Like the Dired file-operating commands,
-this command operates on the next @var{n} files (or previous
-@minus{}@var{n} files), or on the marked files if any, or on the
-current file. Updating the files means reading their current status,
-then updating their lines in the buffer to indicate that status.
-
- If you use @kbd{l} on a subdirectory header line, it updates the
-contents of the corresponding subdirectory.
-
-@kindex k @r{(Dired)}
-@findex dired-do-kill-lines
- To delete the specified @emph{file lines} from the buffer---not
-delete the files---type @kbd{k} (@code{dired-do-kill-lines}). Like
-the file-operating commands, this command operates on the next @var{n}
-files, or on the marked files if any; but it does not operate on the
-current file as a last resort.
-
- If you use @kbd{k} with a numeric prefix argument to kill the line
-for a file that is a directory, which you have inserted in the Dired
-buffer as a subdirectory, it deletes that subdirectory from the buffer
-as well. Typing @kbd{C-u k} on the header line for a subdirectory
-also deletes the subdirectory from the Dired buffer.
-
- The @kbd{g} command brings back any individual lines that you have
-killed in this way, but not subdirectories---you must use @kbd{i} to
-reinsert a subdirectory.
-
-@cindex Dired sorting
-@cindex sorting Dired buffer
-@kindex s @r{(Dired)}
-@findex dired-sort-toggle-or-edit
- The files in a Dired buffers are normally listed in alphabetical order
-by file names. Alternatively Dired can sort them by date/time. The
-Dired command @kbd{s} (@code{dired-sort-toggle-or-edit}) switches
-between these two sorting modes. The mode line in a Dired buffer
-indicates which way it is currently sorted---by name, or by date.
-
- @kbd{C-u s @var{switches} @key{RET}} lets you specify a new value for
-@code{dired-listing-switches}.
-
-@node Dired and Find
-@section Dired and @code{find}
-@cindex @code{find} and Dired
-
- You can select a set of files for display in a Dired buffer more
-flexibly by using the @code{find} utility to choose the files.
-
-@findex find-name-dired
- To search for files with names matching a wildcard pattern use
-@kbd{M-x find-name-dired}. It reads arguments @var{directory} and
-@var{pattern}, and chooses all the files in @var{directory} or its
-subdirectories whose individual names match @var{pattern}.
-
- The files thus chosen are displayed in a Dired buffer, in which the
-ordinary Dired commands are available.
-
-@findex find-grep-dired
- If you want to test the contents of files, rather than their names,
-use @kbd{M-x find-grep-dired}. This command reads two minibuffer
-arguments, @var{directory} and @var{regexp}; it chooses all the files in
-@var{directory} or its subdirectories that contain a match for
-@var{regexp}. It works by running the programs @code{find} and
-@code{grep}. See also @kbd{M-x grep-find}, in @ref{Grep Searching}.
-Remember to write the regular expression for @code{grep}, not for Emacs.
-(An alternative method of showing files whose contents match a given
-regexp is the @kbd{% g @var{regexp}} command, see @ref{Marks vs Flags}.)
-
-@findex find-dired
- The most general command in this series is @kbd{M-x find-dired}, which
-lets you specify any condition that @code{find} can test. It takes two
-minibuffer arguments, @var{directory} and @var{find-args}; it runs
-@code{find} in @var{directory}, passing @var{find-args} to tell
-@code{find} what condition to test. To use this command, you need to
-know how to use @code{find}.
-
-@vindex find-ls-option
- The format of listing produced by these commands is controlled by the
-variable @code{find-ls-option}, whose default value specifies using
-options @samp{-ld} for @code{ls}. If your listings are corrupted, you
-may need to change the value of this variable.
-
-@findex locate
-@findex locate-with-filter
-@cindex file database (locate)
-@vindex locate-command
- The command @kbd{M-x locate} provides a similar interface to the
-@code{locate} program. @kbd{M-x locate-with-filter} is similar, but
-keeps only files whose names match a given regular expression.
-
- These buffers don't work entirely like ordinary Dired buffers: file
-operations work, but do not always automatically update the buffer.
-Reverting the buffer with @kbd{g} deletes all inserted subdirectories,
-and erases all flags and marks.
-
-@node Wdired
-@section Editing the Dired Buffer
-
-@cindex wdired mode
-@findex wdired-change-to-wdired-mode
- Wdired is a special mode that allows you to perform file operations
-by editing the Dired buffer directly (the ``W'' in ``Wdired'' stands
-for ``writable.'') To enter Wdired mode, type @kbd{C-x C-q} or @kbd{M-x
-wdired-change-to-wdired-mode} while in a Dired buffer. Alternatively,
-use @samp{Edit File Names} in the @samp{Immediate} menu bar menu.
-
-@findex wdired-finish-edit
- While in Wdired mode, you can rename files by editing the file names
-displayed in the Dired buffer. All the ordinary Emacs editing
-commands, including rectangle operations and @code{query-replace}, are
-available for this. Once you are done editing, type @kbd{C-c C-c}
-(@code{wdired-finish-edit}). This applies your changes and switches
-back to ordinary Dired mode.
-
- Apart from simply renaming files, you can move a file to another
-directory by typing in the new file name (either absolute or
-relative). To mark a file for deletion, delete the entire file name.
-To change the target of a symbolic link, edit the link target name
-which appears next to the link name.
-
- The rest of the text in the buffer, such as the file sizes and
-modification dates, is marked read-only, so you can't edit it.
-However, if you set @code{wdired-allow-to-change-permissions} to
-@code{t}, you can edit the file permissions. For example, you can
-change @samp{-rw-r--r--} to @samp{-rw-rw-rw-} to make a file
-world-writable. These changes also take effect when you type @kbd{C-c
-C-c}.
-
-@node Image-Dired
-@section Viewing Image Thumbnails in Dired
-@cindex image-dired mode
-@cindex image-dired
-
- Image-Dired is a facility for browsing image files. It provides viewing
-the images either as thumbnails or in full size, either inside Emacs
-or through an external viewer.
-
-@kindex C-t d @r{(Image-Dired)}
-@findex image-dired-display-thumbs
- To enter Image-Dired, mark the image files you want to look at in
-the Dired buffer, using @kbd{m} as usual. Then type @kbd{C-t d}
-(@code{image-dired-display-thumbs}). This creates and switches to a
-buffer containing image-dired, corresponding to the marked files.
-
- You can also enter Image-Dired directly by typing @kbd{M-x
-image-dired}. This prompts for a directory; specify one that has
-image files. This creates thumbnails for all the images in that
-directory, and displays them all in the ``thumbnail buffer.'' This
-takes a long time if the directory contains many image files, and it
-asks for confirmation if the number of image files exceeds
-@code{image-dired-show-all-from-dir-max-files}.
-
- With point in the thumbnail buffer, you can type @kbd{RET}
-(@code{image-dired-display-thumbnail-original-image}) to display a
-sized version of it in another window. This sizes the image to fit
-the window. Use the arrow keys to move around in the buffer. For
-easy browsing, use @kbd{SPC}
-(@code{image-dired-display-next-thumbnail-original}) to advance and
-display the next image. Typing @kbd{DEL}
-(@code{image-dired-display-previous-thumbnail-original}) backs up to
-the previous thumbnail and displays that instead.
-
-@vindex image-dired-external-viewer
- To view and the image in its original size, either provide a prefix
-argument (@kbd{C-u}) before pressing @kbd{RET}, or type
-@kbd{C-@key{RET}} (@code{image-dired-thumbnail-display-external}) to
-display the image in an external viewer. You must first configure
-@code{image-dired-external-viewer}.
-
- You can delete images through Image-Dired also. Type @kbd{d}
-(@code{image-dired-flag-thumb-original-file}) to flag the image file
-for deletion in the Dired buffer. You can also delete the thumbnail
-image from the thumbnail buffer with @kbd{C-d}
-(@code{image-dired-delete-char}).
-
- More advanced features include @dfn{image tags}, which are metadata
-used to categorize image files. The tags are stored in a plain text
-file configured by @code{image-dired-db-file}.
-
- To tag image files, mark them in the dired buffer (you can also mark
-files in Dired from the thumbnail buffer by typing @kbd{m}) and type
-@kbd{C-t t} (@code{image-dired-tag-files}). You will be prompted for
-a tag. To mark files having a certain tag, type @kbd{C-t f}
-(@code{image-dired-mark-tagged-files}). After marking image files
-with a certain tag, you can use @kbd{C-t d} to view them.
-
- You can also tag a file directly from the thumbnail buffer by typing
-@kbd{t t} and you can remove a tag by typing @kbd{t r}. There is also
-a special ``tag'' called ``comment'' for each file (it is not a tag in
-the exact same sense as the other tags, it is handled slightly
-different). That is used to enter a comment or description about the
-image. You comment a file from the thumbnail buffer by typing
-@kbd{c}. You will be prompted for a comment. Type @kbd{C-t c} to add
-a comment from Dired (@code{image-dired-dired-comment-files}).
-
- Image-Dired also provides simple image manipulation. In the
-thumbnail buffer, type @kbd{L} to rotate the original image 90 degrees
-anti clockwise, and @kbd{R} to rotate it 90 degrees clockwise. This
-rotation is lossless, and uses an external utility called JpegTRAN.
-
-@node Misc Dired Features
-@section Other Dired Features
-
-@kindex + @r{(Dired)}
-@findex dired-create-directory
- An unusual Dired file-operation command is @kbd{+}
-(@code{dired-create-directory}). This command reads a directory name,
-and creates the directory if it does not already exist.
-
-@cindex Adding to the kill ring in Dired.
-@kindex w @r{(Dired)}
-@findex dired-copy-filename-as-kill
- The @kbd{w} command (@code{dired-copy-filename-as-kill}) puts the
-names of the marked (or next @var{n}) files into the kill ring, as if
-you had killed them with @kbd{C-w}. The names are separated by a space.
-
- With a zero prefix argument, this uses the absolute file name of
-each marked file. With just @kbd{C-u} as the prefix argument, it uses
-file names relative to the Dired buffer's default directory. (This
-can still contain slashes if in a subdirectory.) As a special case,
-if point is on a directory headerline, @kbd{w} gives you the absolute
-name of that directory. Any prefix argument or marked files are
-ignored in this case.
-
- The main purpose of this command is so that you can yank the file
-names into arguments for other Emacs commands. It also displays what
-it added to the kill ring, so you can use it to display the list of
-currently marked files in the echo area.
-
-@findex dired-compare-directories
- The command @kbd{M-x dired-compare-directories} is used to compare
-the current Dired buffer with another directory. It marks all the files
-that are ``different'' between the two directories. It puts these marks
-in all Dired buffers where these files are listed, which of course includes
-the current buffer.
-
- The default comparison method (used if you type @key{RET} at the
-prompt) is to compare just the file names---each file name that does
-not appear in the other directory is ``different.'' You can specify
-more stringent comparisons by entering a Lisp expression, which can
-refer to the variables @code{size1} and @code{size2}, the respective
-file sizes; @code{mtime1} and @code{mtime2}, the last modification
-times in seconds, as floating point numbers; and @code{fa1} and
-@code{fa2}, the respective file attribute lists (as returned by the
-function @code{file-attributes}). This expression is evaluated for
-each pair of like-named files, and if the expression's value is
-non-@code{nil}, those files are considered ``different.''
-
- For instance, the sequence @code{M-x dired-compare-directories
-@key{RET} (> mtime1 mtime2) @key{RET}} marks files newer in this
-directory than in the other, and marks files older in the other
-directory than in this one. It also marks files with no counterpart,
-in both directories, as always.
-
-@cindex drag and drop, Dired
- On the X window system, Emacs supports the ``drag and drop''
-protocol. You can drag a file object from another program, and drop
-it onto a Dired buffer; this either moves, copies, or creates a link
-to the file in that directory. Precisely which action is taken is
-determined by the originating program. Dragging files out of a Dired
-buffer is currently not supported.
-
-@ignore
- arch-tag: d105f9b9-fc1b-4c5f-a949-9b2cf3ca2fc1
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Display, Search, Registers, Top
-@chapter Controlling the Display
-
- Since only part of a large buffer fits in the window, Emacs tries to
-show a part that is likely to be interesting. Display-control
-commands allow you to specify which part of the text you want to see,
-and how to display it. Many variables also affect the details of
-redisplay. Unless otherwise stated, the variables described in this
-chapter have their effect by customizing redisplay itself; therefore,
-their values only make a difference at the time of redisplay.
-
-@menu
-* Scrolling:: Commands to move text up and down in a window.
-* Auto Scrolling:: Redisplay scrolls text automatically when needed.
-* Horizontal Scrolling:: Moving text left and right in a window.
-* Follow Mode:: Follow mode lets two windows scroll as one.
-* Faces:: How to change the display style using faces.
-* Standard Faces:: Emacs' predefined faces.
-* Font Lock:: Minor mode for syntactic highlighting using faces.
-* Highlight Interactively:: Tell Emacs what text to highlight.
-* Fringes:: Enabling or disabling window fringes.
-* Displaying Boundaries:: Displaying top and bottom of the buffer.
-* Useless Whitespace:: Showing possibly-spurious trailing whitespace.
-* Selective Display:: Hiding lines with lots of indentation.
-* Optional Mode Line:: Optional mode line display features.
-* Text Display:: How text characters are normally displayed.
-* Cursor Display:: Features for displaying the cursor.
-* Line Truncation:: Truncating lines to fit the screen width instead
- of continuing them to multiple screen lines.
-* Display Custom:: Information on variables for customizing display.
-@end menu
-
-@node Scrolling
-@section Scrolling
-
- If a buffer contains text that is too large to fit entirely within a
-window that is displaying the buffer, Emacs shows a contiguous portion of
-the text. The portion shown always contains point.
-
-@cindex scrolling
- @dfn{Scrolling} means moving text up or down in the window so that
-different parts of the text are visible. Scrolling ``forward'' or
-``up'' means that text moves up, and new text appears at the bottom.
-Scrolling ``backward'' or ``down'' moves text down, and new text
-appears at the top.
-
- Scrolling happens automatically if you move point past the bottom or
-top of the window. You can also scroll explicitly with the commands
-in this section.
-
-@table @kbd
-@item C-l
-Clear screen and redisplay, scrolling the selected window to center
-point vertically within it (@code{recenter}).
-@item C-v
-Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
-@item @key{NEXT}
-@itemx @key{PAGEDOWN}
-Likewise, scroll forward.
-@item M-v
-Scroll backward (@code{scroll-down}).
-@item @key{PRIOR}
-@itemx @key{PAGEUP}
-Likewise, scroll backward.
-@item @var{arg} C-l
-Scroll so point is on line @var{arg} (@code{recenter}).
-@item C-M-l
-Scroll heuristically to bring useful information onto the screen
-(@code{reposition-window}).
-@end table
-
-@kindex C-l
-@findex recenter
- The most basic scrolling command is @kbd{C-l} (@code{recenter}) with
-no argument. It scrolls the selected window so that point is halfway
-down from the top of the window. On a text terminal, it also clears
-the screen and redisplays all windows. That is useful in case the
-screen is garbled (@pxref{Screen Garbled}).
-
-@kindex C-v
-@kindex M-v
-@kindex NEXT
-@kindex PRIOR
-@kindex PAGEDOWN
-@kindex PAGEUP
-@findex scroll-up
-@findex scroll-down
- To read the buffer a windowful at a time, use @kbd{C-v}
-(@code{scroll-up}) with no argument. This scrolls forward by nearly
-the whole window height. The effect is to take the two lines at the
-bottom of the window and put them at the top, followed by nearly a
-whole windowful of lines that were not previously visible. If point
-was in the text that scrolled off the top, it ends up at the new top
-of the window.
-
-@vindex next-screen-context-lines
- @kbd{M-v} (@code{scroll-down}) with no argument scrolls backward in
-a similar way, also with overlap. The number of lines of overlap that
-the @kbd{C-v} or @kbd{M-v} commands leave is controlled by the
-variable @code{next-screen-context-lines}; by default, it is 2. The
-function keys @key{NEXT} and @key{PRIOR}, or @key{PAGEDOWN} and
-@key{PAGEUP}, are equivalent to @kbd{C-v} and @kbd{M-v}.
-
- The commands @kbd{C-v} and @kbd{M-v} with a numeric argument scroll
-the text in the selected window up or down a few lines. @kbd{C-v}
-with an argument moves the text and point up, together, that many
-lines; it brings the same number of new lines into view at the bottom
-of the window. @kbd{M-v} with numeric argument scrolls the text
-downward, bringing that many new lines into view at the top of the
-window. @kbd{C-v} with a negative argument is like @kbd{M-v} and vice
-versa.
-
- The names of scroll commands are based on the direction that the
-text moves in the window. Thus, the command to scroll forward is
-called @code{scroll-up} because it moves the text upward on the
-screen. The keys @key{PAGEDOWN} and @key{PAGEUP} derive their names
-and customary meanings from a different convention that developed
-elsewhere; hence the strange result that @key{PAGEDOWN} runs
-@code{scroll-up}.
-
-@vindex scroll-preserve-screen-position
- Some users like the full-screen scroll commands to keep point at the
-same screen line. To enable this behavior, set the variable
-@code{scroll-preserve-screen-position} to a non-@code{nil} value. In
-this mode, when these commands would scroll the text around point off
-the screen, or within @code{scroll-margin} lines of the edge, they
-move point to keep the same vertical position within the window.
-This mode is convenient for browsing through a file by scrolling by
-screenfuls; if you come back to the screen where you started, point
-goes back to the line where it started. However, this mode is
-inconvenient when you move to the next screen in order to move point
-to the text there.
-
- Another way to do scrolling is with @kbd{C-l} with a numeric argument.
-@kbd{C-l} does not clear the screen when given an argument; it only scrolls
-the selected window. With a positive argument @var{n}, it repositions text
-to put point @var{n} lines down from the top. An argument of zero puts
-point on the very top line. Point does not move with respect to the text;
-rather, the text and point move rigidly on the screen. @kbd{C-l} with a
-negative argument puts point that many lines from the bottom of the window.
-For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u
-- 5 C-l} puts it five lines from the bottom. @kbd{C-u C-l} scrolls to put
-point at the center (vertically) of the selected window.
-
-@kindex C-M-l
-@findex reposition-window
- The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current
-window heuristically in a way designed to get useful information onto
-the screen. For example, in a Lisp file, this command tries to get the
-entire current defun onto the screen if possible.
-
-@node Auto Scrolling
-@section Automatic Scrolling
-
-@vindex scroll-conservatively
- Redisplay scrolls the buffer automatically when point moves out of
-the visible portion of the text. The purpose of automatic scrolling
-is to make point visible, but you can customize many aspects of how
-this is done.
-
- Normally, automatic scrolling centers point vertically within the
-window. However, if you set @code{scroll-conservatively} to a small
-number @var{n}, then if you move point just a little off the
-screen---less than @var{n} lines---then Emacs scrolls the text just
-far enough to bring point back on screen. By default,
-@code{scroll-conservatively} is@tie{}0.
-
-@cindex aggressive scrolling
-@vindex scroll-up-aggressively
-@vindex scroll-down-aggressively
- When the window does scroll by a longer distance, you can control
-how aggressively it scrolls, by setting the variables
-@code{scroll-up-aggressively} and @code{scroll-down-aggressively}.
-The value of @code{scroll-up-aggressively} should be either
-@code{nil}, or a fraction @var{f} between 0 and 1. A fraction
-specifies where on the screen to put point when scrolling upward.
-More precisely, when a window scrolls up because point is above the
-window start, the new start position is chosen to put point @var{f}
-part of the window height from the top. The larger @var{f}, the more
-aggressive the scrolling.
-
- @code{nil}, which is the default, scrolls to put point at the center.
-So it is equivalent to .5.
-
- Likewise, @code{scroll-down-aggressively} is used for scrolling
-down. The value, @var{f}, specifies how far point should be placed
-from the bottom of the window; thus, as with
-@code{scroll-up-aggressively}, a larger value is more aggressive.
-
-@vindex scroll-margin
- The variable @code{scroll-margin} restricts how close point can come
-to the top or bottom of a window. Its value is a number of screen
-lines; if point comes within that many lines of the top or bottom of the
-window, Emacs recenters the window. By default, @code{scroll-margin} is
-0.
-
-@node Horizontal Scrolling
-@section Horizontal Scrolling
-@cindex horizontal scrolling
-
- @dfn{Horizontal scrolling} means shifting all the lines sideways
-within a window---so that some of the text near the left margin is not
-displayed at all. When the text in a window is scrolled horizontally,
-text lines are truncated rather than continued (@pxref{Line
-Truncation}). Whenever a window shows truncated lines, Emacs
-automatically updates its horizontal scrolling whenever point moves
-off the left or right edge of the screen. You can also use these
-commands to do explicit horizontal scrolling.
-
-@table @kbd
-@item C-x <
-Scroll text in current window to the left (@code{scroll-left}).
-@item C-x >
-Scroll to the right (@code{scroll-right}).
-@end table
-
-@kindex C-x <
-@kindex C-x >
-@findex scroll-left
-@findex scroll-right
- The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected
-window to the left by @var{n} columns with argument @var{n}. This moves
-part of the beginning of each line off the left edge of the window.
-With no argument, it scrolls by almost the full width of the window (two
-columns less, to be precise).
-
- @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. The
-window cannot be scrolled any farther to the right once it is displayed
-normally (with each line starting at the window's left margin);
-attempting to do so has no effect. This means that you don't have to
-calculate the argument precisely for @w{@kbd{C-x >}}; any sufficiently large
-argument will restore the normal display.
-
- If you use those commands to scroll a window horizontally, that sets
-a lower bound for automatic horizontal scrolling. Automatic scrolling
-will continue to scroll the window, but never farther to the right
-than the amount you previously set by @code{scroll-left}.
-
-@vindex hscroll-margin
- The value of the variable @code{hscroll-margin} controls how close
-to the window's edges point is allowed to get before the window will
-be automatically scrolled. It is measured in columns. If the value
-is 5, then moving point within 5 columns of the edge causes horizontal
-scrolling away from that edge.
-
-@vindex hscroll-step
- The variable @code{hscroll-step} determines how many columns to
-scroll the window when point gets too close to the edge. If it's
-zero, horizontal scrolling centers point horizontally within the
-window. If it's a positive integer, it specifies the number of
-columns to scroll by. If it's a floating-point number, it specifies
-the fraction of the window's width to scroll by. The default is zero.
-
-@vindex auto-hscroll-mode
- To disable automatic horizontal scrolling, set the variable
-@code{auto-hscroll-mode} to @code{nil}.
-
-@node Follow Mode
-@section Follow Mode
-@cindex Follow mode
-@cindex mode, Follow
-@findex follow-mode
-@cindex windows, synchronizing
-@cindex synchronizing windows
-
- @dfn{Follow mode} is a minor mode that makes two windows, both
-showing the same buffer, scroll as a single tall ``virtual window.''
-To use Follow mode, go to a frame with just one window, split it into
-two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x
-follow-mode}. From then on, you can edit the buffer in either of the
-two windows, or scroll either one; the other window follows it.
-
- In Follow mode, if you move point outside the portion visible in one
-window and into the portion visible in the other window, that selects
-the other window---again, treating the two as if they were parts of
-one large window.
-
- To turn off Follow mode, type @kbd{M-x follow-mode} a second time.
-
-@node Faces
-@section Using Multiple Typefaces
-@cindex faces
-
- You can specify various styles for displaying text using
-@dfn{faces}. Each face can specify various @dfn{face attributes},
-such as the font family, the height, weight and slant of the
-characters, the foreground and background color, and underlining or
-overlining. A face does not have to specify all of these attributes;
-often it inherits most of them from another face.
-
- On graphical display, all the Emacs face attributes are meaningful.
-On a text-only terminal, only some of them work. Some text-only
-terminals support inverse video, bold, and underline attributes; some
-support colors. Text-only terminals generally do not support changing
-the height and width or the font family.
-
- Emacs uses faces automatically for highlighting, through the work of
-Font Lock mode. @xref{Font Lock}, for more information about Font
-Lock mode and syntactic highlighting. You can print out the buffer
-with the highlighting that appears on your screen using the command
-@code{ps-print-buffer-with-faces}. @xref{PostScript}.
-
- You control the appearance of a part of the text in the buffer by
-specifying the face or faces to use for it. The style of display used
-for any given character is determined by combining the attributes of
-all the applicable faces specified for that character. Any attribute
-that isn't specified by these faces is taken from the @code{default} face,
-whose attributes reflect the default settings of the frame itself.
-
- Enriched mode, the mode for editing formatted text, includes several
-commands and menus for specifying faces for text in the buffer.
-@xref{Format Faces}, for how to specify the font for text in the
-buffer. @xref{Format Colors}, for how to specify the foreground and
-background color.
-
-@cindex face colors, setting
-@findex set-face-foreground
-@findex set-face-background
- To alter the appearance of a face, use the customization buffer.
-@xref{Face Customization}. You can also use X resources to specify
-attributes of particular faces (@pxref{Resources}). Alternatively,
-you can change the foreground and background colors of a specific face
-with @kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}.
-These commands prompt in the minibuffer for a face name and a color
-name, with completion, and then set that face to use the specified
-color. Changing the colors of the @code{default} face also changes
-the foreground and background colors on all frames, both existing and
-those to be created in the future. (You can also set foreground and
-background colors for the current frame only; see @ref{Frame
-Parameters}.)
-
- If you want to alter the appearance of all Emacs frames, you need to
-customize the frame parameters in the variable
-@code{default-frame-alist}; see @ref{Creating Frames,
-default-frame-alist}.
-
- Emacs can correctly display variable-width fonts, but Emacs commands
-that calculate width and indentation do not know how to calculate
-variable widths. This can sometimes lead to incorrect results when
-you use variable-width fonts. In particular, indentation commands can
-give inconsistent results, so we recommend you avoid variable-width
-fonts for editing program source code. Filling will sometimes make
-lines too long or too short. We plan to address these issues in
-future Emacs versions.
-
-@node Standard Faces
-@section Standard Faces
-
-@findex list-faces-display
- To see what faces are currently defined, and what they look like,
-type @kbd{M-x list-faces-display}. It's possible for a given face to
-look different in different frames; this command shows the appearance
-in the frame in which you type it. With a prefix argument, this
-prompts for a regular expression, and displays only faces with names
-matching that regular expression.
-
- Here are the standard faces for specifying text appearance. You can
-apply them to specific text when you want the effects they produce.
-
-@table @code
-@item default
-This face is used for ordinary text that doesn't specify any face.
-@item bold
-This face uses a bold variant of the default font, if it has one.
-It's up to you to choose a default font that has a bold variant,
-if you want to use one.
-@item italic
-This face uses an italic variant of the default font, if it has one.
-@item bold-italic
-This face uses a bold italic variant of the default font, if it has one.
-@item underline
-This face underlines text.
-@item fixed-pitch
-This face forces use of a particular fixed-width font.
-@item variable-pitch
-This face forces use of a particular variable-width font. It's
-reasonable to customize this face to use a different variable-width font,
-if you like, but you should not make it a fixed-width font.
-@item shadow
-This face is used for making the text less noticeable than the surrounding
-ordinary text. Usually this can be achieved by using shades of gray in
-contrast with either black or white default foreground color.
-@end table
-
- Here's an incomplete list of faces used to highlight parts of the
-text temporarily for specific purposes. (Many other modes define
-their own faces for this purpose.)
-
-@table @code
-@item highlight
-This face is used for highlighting portions of text, in various modes.
-For example, mouse-sensitive text is highlighted using this face.
-@item isearch
-This face is used for highlighting the current Isearch match.
-@item query-replace
-This face is used for highlighting the current Query Replace match.
-@item lazy-highlight
-This face is used for lazy highlighting of Isearch and Query Replace
-matches other than the current one.
-@item region
-This face is used for displaying a selected region (when Transient Mark
-mode is enabled---see below).
-@item secondary-selection
-This face is used for displaying a secondary X selection (@pxref{Secondary
-Selection}).
-@item trailing-whitespace
-The face for highlighting excess spaces and tabs at the end of a line
-when @code{show-trailing-whitespace} is non-@code{nil}; see
-@ref{Useless Whitespace}.
-@item nobreak-space
-The face for displaying the character ``nobreak space.''
-@item escape-glyph
-The face for highlighting the @samp{\} or @samp{^} that indicates
-a control character. It's also used when @samp{\} indicates a
-nobreak space or nobreak (soft) hyphen.
-@end table
-
-@cindex @code{region} face
- When Transient Mark mode is enabled, the text of the region is
-highlighted when the mark is active. This uses the face named
-@code{region}; you can control the style of highlighting by changing the
-style of this face (@pxref{Face Customization}). @xref{Transient Mark},
-for more information about Transient Mark mode and activation and
-deactivation of the mark.
-
- These faces control the appearance of parts of the Emacs frame.
-They exist as faces to provide a consistent way to customize the
-appearance of these parts of the frame.
-
-@table @code
-@item mode-line
-@itemx modeline
-This face is used for the mode line of the currently selected window,
-and for menu bars when toolkit menus are not used. By default, it's
-drawn with shadows for a ``raised'' effect on graphical displays, and
-drawn as the inverse of the default face on non-windowed terminals.
-@code{modeline} is an alias for the @code{mode-line} face, for
-compatibility with old Emacs versions.
-@item mode-line-inactive
-Like @code{mode-line}, but used for mode lines of the windows other
-than the selected one (if @code{mode-line-in-non-selected-windows} is
-non-@code{nil}). This face inherits from @code{mode-line}, so changes
-in that face affect mode lines in all windows.
-@item mode-line-highlight
-Like @code{highlight}, but used for portions of text on mode lines.
-@item mode-line-buffer-id
-This face is used for buffer identification parts in the mode line.
-@item header-line
-Similar to @code{mode-line} for a window's header line, which appears
-at the top of a window just as the mode line appears at the bottom.
-Most windows do not have a header line---only some special modes, such
-Info mode, create one.
-@item vertical-border
-This face is used for the vertical divider between windows.
-By default this face inherits from the @code{mode-line-inactive} face
-on character terminals. On graphical displays the foreground color of
-this face is used for the vertical line between windows without
-scrollbars.
-@item minibuffer-prompt
-@cindex @code{minibuffer-prompt} face
-@vindex minibuffer-prompt-properties
-This face is used for the prompt strings displayed in the minibuffer.
-By default, Emacs automatically adds this face to the value of
-@code{minibuffer-prompt-properties}, which is a list of text
-properties used to display the prompt text. (This variable takes
-effect when you enter the minibuffer.)
-@item fringe
-@cindex @code{fringe} face
-The face for the fringes to the left and right of windows on graphic
-displays. (The fringes are the narrow portions of the Emacs frame
-between the text area and the window's right and left borders.)
-@xref{Fringes}.
-@item scroll-bar
-This face determines the visual appearance of the scroll bar.
-@xref{Scroll Bars}.
-@item border
-This face determines the color of the frame border.
-@item cursor
-This face determines the color of the cursor.
-@item mouse
-This face determines the color of the mouse pointer.
-@item tool-bar
-This face determines the color of tool bar icons. @xref{Tool Bars}.
-@item tooltip
-This face is used for tooltips. @xref{Tooltips}.
-@item menu
-@cindex menu bar appearance
-@cindex @code{menu} face, no effect if customized
-@cindex customization of @code{menu} face
-This face determines the colors and font of Emacs's menus. @xref{Menu
-Bars}. Setting the font of LessTif/Motif menus is currently not
-supported; attempts to set the font are ignored in this case.
-Likewise, attempts to customize this face in Emacs built with GTK and
-in the MS-Windows/Mac ports are ignored by the respective GUI toolkits;
-you need to use system-wide styles and options to change the
-appearance of the menus.
-@end table
-
-@node Font Lock
-@section Font Lock mode
-@cindex Font Lock mode
-@cindex mode, Font Lock
-@cindex syntax highlighting and coloring
-
- Font Lock mode is a minor mode, always local to a particular buffer,
-which highlights (or ``fontifies'') the buffer contents according to
-the syntax of the text you are editing. It can recognize comments and
-strings in most languages; in several languages, it can also recognize
-and properly highlight various other important constructs---for
-example, names of functions being defined or reserved keywords.
-Some special modes, such as Occur mode and Info mode, have completely
-specialized ways of assigning fonts for Font Lock mode.
-
-@findex font-lock-mode
- Font Lock mode is turned on by default in all modes which support it.
-You can toggle font-lock for each buffer with the command @kbd{M-x
-font-lock-mode}. Using a positive argument unconditionally turns Font
-Lock mode on, and a negative or zero argument turns it off.
-
-@findex global-font-lock-mode
-@vindex global-font-lock-mode
- If you do not wish Font Lock mode to be turned on by default,
-customize the variable @code{global-font-lock-mode} using the Customize
-interface (@pxref{Easy Customization}), or use the function
-@code{global-font-lock-mode} in your @file{.emacs} file, like this:
-
-@example
-(global-font-lock-mode 0)
-@end example
-
-@noindent
-This variable, like all the variables that control Font Lock mode,
-take effect whenever fontification is done; that is, potentially at
-any time.
-
-@findex turn-on-font-lock
- If you have disabled Global Font Lock mode, you can still enable Font
-Lock for specific major modes by adding the function
-@code{turn-on-font-lock} to the mode hooks (@pxref{Hooks}). For
-example, to enable Font Lock mode for editing C files, you can do this:
-
-@example
-(add-hook 'c-mode-hook 'turn-on-font-lock)
-@end example
-
- Font Lock mode uses several specifically named faces to do its job,
-including @code{font-lock-string-face}, @code{font-lock-comment-face},
-and others. The easiest way to find them all is to use @kbd{M-x
-customize-group @key{RET} font-lock-faces @key{RET}}. You can then
-use that customization buffer to customize the appearance of these
-faces. @xref{Face Customization}.
-
- You can also customize these faces using @kbd{M-x
-set-face-foreground} or @kbd{M-x set-face-background}. @xref{Faces}.
-
-@vindex font-lock-maximum-decoration
- The variable @code{font-lock-maximum-decoration} specifies the
-preferred level of fontification, for modes that provide multiple
-levels. Level 1 is the least amount of fontification; some modes
-support levels as high as 3. The normal default is ``as high as
-possible.'' You can specify an integer, which applies to all modes, or
-you can specify different numbers for particular major modes; for
-example, to use level 1 for C/C++ modes, and the default level
-otherwise, use this:
-
-@example
-(setq font-lock-maximum-decoration
- '((c-mode . 1) (c++-mode . 1)))
-@end example
-
-@vindex font-lock-maximum-size
- Fontification can be too slow for large buffers, so you can suppress
-it for buffers above a certain size. The variable
-@code{font-lock-maximum-size} specifies a buffer size, beyond which
-buffer fontification is suppressed.
-
-@c @w is used below to prevent a bad page-break.
-@vindex font-lock-beginning-of-syntax-function
-@cindex incorrect fontification
-@cindex parenthesis in column zero and fontification
-@cindex brace in column zero and fontification
- Comment and string fontification (or ``syntactic'' fontification)
-relies on analysis of the syntactic structure of the buffer text. For
-the sake of speed, some modes, including Lisp mode, rely on a special
-convention: an open-parenthesis or open-brace in the leftmost column
-always defines the @w{beginning} of a defun, and is thus always
-outside any string or comment. (@xref{Left Margin Paren}.) If you
-don't follow this convention, Font Lock mode can misfontify the text
-that follows an open-parenthesis or open-brace in the leftmost column
-that is inside a string or comment.
-
-@cindex slow display during scrolling
- The variable @code{font-lock-beginning-of-syntax-function} (always
-buffer-local) specifies how Font Lock mode can find a position
-guaranteed to be outside any comment or string. In modes which use the
-leftmost column parenthesis convention, the default value of the variable
-is @code{beginning-of-defun}---that tells Font Lock mode to use the
-convention. If you set this variable to @code{nil}, Font Lock no longer
-relies on the convention. This avoids incorrect results, but the price
-is that, in some cases, fontification for a changed text must rescan
-buffer text from the beginning of the buffer. This can considerably
-slow down redisplay while scrolling, particularly if you are close to
-the end of a large buffer.
-
-@findex font-lock-add-keywords
- Font Lock highlighting patterns already exist for many modes, but you
-may want to fontify additional patterns. You can use the function
-@code{font-lock-add-keywords}, to add your own highlighting patterns for
-a particular mode. For example, to highlight @samp{FIXME:} words in C
-comments, use this:
-
-@example
-(font-lock-add-keywords
- 'c-mode
- '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t)))
-@end example
-
-@findex font-lock-remove-keywords
- To remove keywords from the font-lock highlighting patterns, use the
-function @code{font-lock-remove-keywords}. @xref{Search-based
-Fontification,,, elisp, The Emacs Lisp Reference Manual}, for
-documentation of the format of this list.
-
-@cindex just-in-time (JIT) font-lock
-@cindex background syntax highlighting
- Fontifying large buffers can take a long time. To avoid large
-delays when a file is visited, Emacs fontifies only the visible
-portion of a buffer. As you scroll through the buffer, each portion
-that becomes visible is fontified as soon as it is displayed. The
-parts of the buffer that are not displayed are fontified
-``stealthily,'' in the background, i.e.@: when Emacs is idle. You can
-control this background fontification, also called @dfn{Just-In-Time}
-(or @dfn{JIT}) Lock, by customizing variables in the customization
-group @samp{jit-lock}. @xref{Specific Customization}.
-
-@node Highlight Interactively
-@section Interactive Highlighting
-@cindex highlighting by matching
-@cindex interactive highlighting
-@cindex Highlight Changes mode
-
-@findex highlight-changes-mode
- Use @kbd{M-x highlight-changes-mode} to enable (or disable)
-Highlight Changes mode, a minor mode that uses faces (colors,
-typically) to indicate which parts of the buffer were changed most
-recently.
-
-@cindex Hi Lock mode
-@findex hi-lock-mode
- Hi Lock mode highlights text that matches regular expressions you
-specify. For example, you might wish to see all the references to a
-certain variable in a program source file, highlight certain parts in
-a voluminous output of some program, or make certain names stand out
-in an article. Use the @kbd{M-x hi-lock-mode} command to enable (or
-disable) Hi Lock mode. To enable Hi Lock mode for all buffers, use
-@kbd{M-x global-hi-lock-mode} or place @code{(global-hi-lock-mode 1)}
-in your @file{.emacs} file.
-
- Hi Lock mode works like Font Lock mode (@pxref{Font Lock}), except
-that you specify explicitly the regular expressions to highlight. You
-control them with these commands:
-
-@table @kbd
-@item C-x w h @var{regexp} @key{RET} @var{face} @key{RET}
-@kindex C-x w h
-@findex highlight-regexp
-Highlight text that matches @var{regexp} using face @var{face}
-(@code{highlight-regexp}). The highlighting will remain as long as
-the buffer is loaded. For example, to highlight all occurrences of
-the word ``whim'' using the default face (a yellow background)
-@kbd{C-x w h whim @key{RET} @key{RET}}. Any face can be used for
-highlighting, Hi Lock provides several of its own and these are
-pre-loaded into a history list. While being prompted for a face use
-@kbd{M-p} and @kbd{M-n} to cycle through them.
-
-You can use this command multiple times, specifying various regular
-expressions to highlight in different ways.
-
-@item C-x w r @var{regexp} @key{RET}
-@kindex C-x w r
-@findex unhighlight-regexp
-Unhighlight @var{regexp} (@code{unhighlight-regexp}).
-
-If you invoke this from the menu, you select the expression to
-unhighlight from a list. If you invoke this from the keyboard, you
-use the minibuffer. It will show the most recently added regular
-expression; use @kbd{M-p} to show the next older expression and
-@kbd{M-n} to select the next newer expression. (You can also type the
-expression by hand, with completion.) When the expression you want to
-unhighlight appears in the minibuffer, press @kbd{@key{RET}} to exit
-the minibuffer and unhighlight it.
-
-@item C-x w l @var{regexp} @key{RET} @var{face} @key{RET}
-@kindex C-x w l
-@findex highlight-lines-matching-regexp
-@cindex lines, highlighting
-@cindex highlighting lines of text
-Highlight entire lines containing a match for @var{regexp}, using face
-@var{face} (@code{highlight-lines-matching-regexp}).
-
-@item C-x w b
-@kindex C-x w b
-@findex hi-lock-write-interactive-patterns
-Insert all the current highlighting regexp/face pairs into the buffer
-at point, with comment delimiters to prevent them from changing your
-program. (This key binding runs the
-@code{hi-lock-write-interactive-patterns} command.)
-
-These patterns are extracted from the comments, if appropriate, if you
-invoke @kbd{M-x hi-lock-find-patterns}, or if you visit the file while
-Hi Lock mode is enabled (since that runs @code{hi-lock-find-patterns}).
-
-@item C-x w i
-@kindex C-x w i
-@findex hi-lock-find-patterns
-Extract regexp/face pairs from comments in the current buffer
-(@code{hi-lock-find-patterns}). Thus, you can enter patterns
-interactively with @code{highlight-regexp}, store them into the file
-with @code{hi-lock-write-interactive-patterns}, edit them (perhaps
-including different faces for different parenthesized parts of the
-match), and finally use this command (@code{hi-lock-find-patterns}) to
-have Hi Lock highlight the edited patterns.
-
-@vindex hi-lock-file-patterns-policy
-The variable @code{hi-lock-file-patterns-policy} controls whether Hi
-Lock mode should automatically extract and highlight patterns found in
-a file when it is visited. Its value can be @code{nil} (never
-highlight), @code{t} (highlight the patterns), @code{ask} (query the
-user), or a function. If it is a function,
-@code{hi-lock-find-patterns} calls it with the patterns as argument;
-if the function returns non-@code{nil}, the patterns are used. The
-default is @code{nil}. Note that patterns are always highlighted if
-you call @code{hi-lock-find-patterns} directly, regardless of the
-value of this variable.
-
-@vindex hi-lock-exclude-modes
-Also, @code{hi-lock-find-patterns} does nothing if the current major
-mode's symbol is a member of the list @code{hi-lock-exclude-modes}.
-@end table
-
-@node Fringes
-@section Window Fringes
-@cindex fringes
-
- On a graphical display, each Emacs window normally has narrow
-@dfn{fringes} on the left and right edges. The fringes display
-indications about the text in the window.
-
- The most common use of the fringes is to indicate a continuation
-line, when one line of text is split into multiple lines on the
-screen. The left fringe shows a curving arrow for each screen line
-except the first, indicating that ``this is not the real beginning.''
-The right fringe shows a curving arrow for each screen line except the
-last, indicating that ``this is not the real end.''
-
- The fringes indicate line truncation with short horizontal arrows
-meaning ``there's more text on this line which is scrolled
-horizontally out of view;'' clicking the mouse on one of the arrows
-scrolls the display horizontally in the direction of the arrow. The
-fringes can also indicate other things, such as empty lines, or where a
-program you are debugging is executing (@pxref{Debuggers}).
-
-@findex set-fringe-style
-@findex fringe-mode
- You can enable and disable the fringes for all frames using
-@kbd{M-x fringe-mode}. To enable and disable the fringes
-for the selected frame, use @kbd{M-x set-fringe-style}.
-
-@node Displaying Boundaries
-@section Displaying Boundaries
-
-@vindex indicate-buffer-boundaries
- On a graphical display, Emacs can indicate the buffer boundaries in
-the fringes. It indicates the first line and the last line with
-angle images in the fringes. This can be combined with up and down
-arrow images which say whether it is possible to scroll the window up
-and down.
-
- The buffer-local variable @code{indicate-buffer-boundaries} controls
-how the buffer boundaries and window scrolling is indicated in the
-fringes. If the value is @code{left} or @code{right}, both angle and
-arrow bitmaps are displayed in the left or right fringe, respectively.
-
- If value is an alist, each element @code{(@var{indicator} .
-@var{position})} specifies the position of one of the indicators.
-The @var{indicator} must be one of @code{top}, @code{bottom},
-@code{up}, @code{down}, or @code{t} which specifies the default
-position for the indicators not present in the alist.
-The @var{position} is one of @code{left}, @code{right}, or @code{nil}
-which specifies not to show this indicator.
-
- For example, @code{((top . left) (t . right))} places the top angle
-bitmap in left fringe, the bottom angle bitmap in right fringe, and
-both arrow bitmaps in right fringe. To show just the angle bitmaps in
-the left fringe, but no arrow bitmaps, use @code{((top . left)
-(bottom . left))}.
-
-@vindex default-indicate-buffer-boundaries
- The value of the variable @code{default-indicate-buffer-boundaries}
-is the default value for @code{indicate-buffer-boundaries} in buffers
-that do not override it.
-
-@node Useless Whitespace
-@section Useless Whitespace
-
-@cindex trailing whitespace
-@cindex whitespace, trailing
-@vindex show-trailing-whitespace
- It is easy to leave unnecessary spaces at the end of a line, or
-empty lines at the end of a file, without realizing it. In most
-cases, this @dfn{trailing whitespace} has no effect, but there are
-special circumstances where it matters. It can also be a nuisance
-that the line has ``changed,'' when the change is just spaces added or
-removed at the end.
-
- You can make trailing whitespace at the end of a line visible on the
-screen by setting the buffer-local variable
-@code{show-trailing-whitespace} to @code{t}. Then Emacs displays
-trailing whitespace in the face @code{trailing-whitespace}.
-
- This feature does not apply when point is at the end of the line
-containing the whitespace. Strictly speaking, that is ``trailing
-whitespace'' nonetheless, but displaying it specially in that case
-looks ugly while you are typing in new text. In this special case,
-the location of point is enough to show you that the spaces are
-present.
-
-@findex delete-trailing-whitespace
- To delete all trailing whitespace within the current buffer's
-accessible portion (@pxref{Narrowing}), type @kbd{M-x
-delete-trailing-whitespace @key{RET}}. (This command does not remove
-the form-feed characters.)
-
-@vindex indicate-empty-lines
-@vindex default-indicate-empty-lines
-@cindex unused lines
-@cindex fringes, and unused line indication
- Emacs can indicate unused lines at the end of the window with a
-small image in the left fringe (@pxref{Fringes}). The image appears
-for window lines that do not correspond to any buffer text. Blank
-lines at the end of the buffer then stand out because they do not have
-this image in the fringe.
-
- To enable this feature, set the buffer-local variable
-@code{indicate-empty-lines} to a non-@code{nil} value. The default
-value of this variable is controlled by the variable
-@code{default-indicate-empty-lines}; by setting that variable, you
-can enable or disable this feature for all new buffers. (This feature
-currently doesn't work on text-only terminals.)
-
-@node Selective Display
-@section Selective Display
-@cindex selective display
-@findex set-selective-display
-@kindex C-x $
-
- Emacs has the ability to hide lines indented more than a certain number
-of columns (you specify how many columns). You can use this to get an
-overview of a part of a program.
-
- To hide lines in the current buffer, type @kbd{C-x $}
-(@code{set-selective-display}) with a numeric argument @var{n}. Then
-lines with at least @var{n} columns of indentation disappear from the
-screen. The only indication of their presence is that three dots
-(@samp{@dots{}}) appear at the end of each visible line that is
-followed by one or more hidden ones.
-
- The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as
-if they were not there.
-
- The hidden lines are still present in the buffer, and most editing
-commands see them as usual, so you may find point in the middle of the
-hidden text. When this happens, the cursor appears at the end of the
-previous line, after the three dots. If point is at the end of the
-visible line, before the newline that ends it, the cursor appears before
-the three dots.
-
- To make all lines visible again, type @kbd{C-x $} with no argument.
-
-@vindex selective-display-ellipses
- If you set the variable @code{selective-display-ellipses} to
-@code{nil}, the three dots do not appear at the end of a line that
-precedes hidden lines. Then there is no visible indication of the
-hidden lines. This variable becomes local automatically when set.
-
- See also @ref{Outline Mode} for another way to hide part of
-the text in a buffer.
-
-@node Optional Mode Line
-@section Optional Mode Line Features
-
-@cindex buffer size display
-@cindex display of buffer size
-@findex size-indication-mode
- The buffer percentage @var{pos} indicates the percentage of the
-buffer above the top of the window. You can additionally display the
-size of the buffer by typing @kbd{M-x size-indication-mode} to turn on
-Size Indication mode. The size will be displayed immediately
-following the buffer percentage like this:
-
-@example
-@var{POS} of @var{SIZE}
-@end example
-
-@noindent
-Here @var{SIZE} is the human readable representation of the number of
-characters in the buffer, which means that @samp{k} for 10^3, @samp{M}
-for 10^6, @samp{G} for 10^9, etc., are used to abbreviate.
-
-@cindex narrowing, and buffer size display
- If you have narrowed the buffer (@pxref{Narrowing}), the size of the
-accessible part of the buffer is shown.
-
-@cindex line number display
-@cindex display of line number
-@findex line-number-mode
- The current line number of point appears in the mode line when Line
-Number mode is enabled. Use the command @kbd{M-x line-number-mode} to
-turn this mode on and off; normally it is on. The line number appears
-after the buffer percentage @var{pos}, with the letter @samp{L} to
-indicate what it is.
-
-@cindex Column Number mode
-@cindex mode, Column Number
-@findex column-number-mode
- Similarly, you can display the current column number by turning on
-Column number mode with @kbd{M-x column-number-mode}. The column
-number is indicated by the letter @samp{C}. However, when both of
-these modes are enabled, the line and column numbers are displayed in
-parentheses, the line number first, rather than with @samp{L} and
-@samp{C}. For example: @samp{(561,2)}. @xref{Minor Modes}, for more
-information about minor modes and about how to use these commands.
-
-@cindex narrowing, and line number display
- If you have narrowed the buffer (@pxref{Narrowing}), the displayed
-line number is relative to the accessible portion of the buffer.
-Thus, it isn't suitable as an argument to @code{goto-line}. (Use
-@code{what-line} command to see the line number relative to the whole
-file.)
-
-@vindex line-number-display-limit
- If the buffer is very large (larger than the value of
-@code{line-number-display-limit}), then the line number doesn't appear.
-Emacs doesn't compute the line number when the buffer is large, because
-that would be too slow. Set it to @code{nil} to remove the limit.
-
-@vindex line-number-display-limit-width
- Line-number computation can also be slow if the lines in the buffer
-are too long. For this reason, Emacs normally doesn't display line
-numbers if the average width, in characters, of lines near point is
-larger than the value of the variable
-@code{line-number-display-limit-width}. The default value is 200
-characters.
-
-@findex display-time
-@cindex time (on mode line)
- Emacs can optionally display the time and system load in all mode
-lines. To enable this feature, type @kbd{M-x display-time} or customize
-the option @code{display-time-mode}. The information added to the mode
-line usually appears after the buffer name, before the mode names and
-their parentheses. It looks like this:
-
-@example
-@var{hh}:@var{mm}pm @var{l.ll}
-@end example
-
-@noindent
-@vindex display-time-24hr-format
-Here @var{hh} and @var{mm} are the hour and minute, followed always by
-@samp{am} or @samp{pm}. @var{l.ll} is the average number of running
-processes in the whole system recently. (Some fields may be missing if
-your operating system cannot support them.) If you prefer time display
-in 24-hour format, set the variable @code{display-time-24hr-format}
-to @code{t}.
-
-@cindex mail (on mode line)
-@vindex display-time-use-mail-icon
-@vindex display-time-mail-face
-@vindex display-time-mail-file
-@vindex display-time-mail-directory
- The word @samp{Mail} appears after the load level if there is mail
-for you that you have not read yet. On a graphical display you can use
-an icon instead of @samp{Mail} by customizing
-@code{display-time-use-mail-icon}; this may save some space on the mode
-line. You can customize @code{display-time-mail-face} to make the mail
-indicator prominent. Use @code{display-time-mail-file} to specify
-the mail file to check, or set @code{display-time-mail-directory}
-to specify the directory to check for incoming mail (any nonempty regular
-file in the directory is considered as ``newly arrived mail'').
-
-@cindex mode line, 3D appearance
-@cindex attributes of mode line, changing
-@cindex non-integral number of lines in a window
- By default, the mode line is drawn on graphics displays with
-3D-style highlighting, like that of a button when it is not being
-pressed. If you don't like this effect, you can disable the 3D
-highlighting of the mode line, by customizing the attributes of the
-@code{mode-line} face. @xref{Face Customization}.
-
-@cindex non-selected windows, mode line appearance
- By default, the mode line of nonselected windows is displayed in a
-different face, called @code{mode-line-inactive}. Only the selected
-window is displayed in the @code{mode-line} face. This helps show
-which window is selected. When the minibuffer is selected, since
-it has no mode line, the window from which you activated the minibuffer
-has its mode line displayed using @code{mode-line}; as a result,
-ordinary entry to the minibuffer does not change any mode lines.
-
-@vindex mode-line-in-non-selected-windows
- You can disable use of @code{mode-line-inactive} by setting variable
-@code{mode-line-in-non-selected-windows} to @code{nil}; then all mode
-lines are displayed in the @code{mode-line} face.
-
-@vindex eol-mnemonic-unix
-@vindex eol-mnemonic-dos
-@vindex eol-mnemonic-mac
-@vindex eol-mnemonic-undecided
- You can customize the mode line display for each of the end-of-line
-formats by setting each of the variables @code{eol-mnemonic-unix},
-@code{eol-mnemonic-dos}, @code{eol-mnemonic-mac}, and
-@code{eol-mnemonic-undecided} to the strings you prefer.
-
-@node Text Display
-@section How Text Is Displayed
-@cindex characters (in text)
-
- @acronym{ASCII} printing characters (octal codes 040 through 0176) in Emacs
-buffers are displayed with their graphics, as are non-ASCII multibyte
-printing characters (octal codes above 0400).
-
- Some @acronym{ASCII} control characters are displayed in special ways. The
-newline character (octal code 012) is displayed by starting a new line.
-The tab character (octal code 011) is displayed by moving to the next
-tab stop column (normally every 8 columns).
-
- Other @acronym{ASCII} control characters are normally displayed as a caret
-(@samp{^}) followed by the non-control version of the character; thus,
-control-A is displayed as @samp{^A}. The caret appears in face
-@code{escape-glyph}.
-
- Non-@acronym{ASCII} characters 0200 through 0237 (octal) are
-displayed with octal escape sequences; thus, character code 0230
-(octal) is displayed as @samp{\230}. The backslash appears in face
-@code{escape-glyph}.
-
-@vindex ctl-arrow
- If the variable @code{ctl-arrow} is @code{nil}, control characters in
-the buffer are displayed with octal escape sequences, except for newline
-and tab. Altering the value of @code{ctl-arrow} makes it local to the
-current buffer; until that time, the default value is in effect. The
-default is initially @code{t}.
-
- The display of character codes 0240 through 0377 (octal) may be
-either as escape sequences or as graphics. They do not normally occur
-in multibyte buffers, but if they do, they are displayed as Latin-1
-graphics. In unibyte mode, if you enable European display they are
-displayed using their graphics (assuming your terminal supports them),
-otherwise as escape sequences. @xref{Unibyte Mode}.
-
-@vindex nobreak-char-display
-@cindex no-break space, display
-@cindex no-break hyphen, display
-@cindex soft hyphen, display
- Some character sets define ``no-break'' versions of the space and
-hyphen characters, which are used where a line should not be broken.
-Emacs normally displays these characters with special faces
-(respectively, @code{nobreak-space} and @code{escape-glyph}) to
-distinguish them from ordinary spaces and hyphens. You can turn off
-this feature by setting the variable @code{nobreak-char-display} to
-@code{nil}. If you set the variable to any other value, that means to
-prefix these characters with an escape character.
-
-@vindex tab-width
-@vindex default-tab-width
- Normally, a tab character in the buffer is displayed as whitespace which
-extends to the next display tab stop position, and display tab stops come
-at intervals equal to eight spaces. The number of spaces per tab is
-controlled by the variable @code{tab-width}, which is made local by
-changing it. Note that how the tab character
-in the buffer is displayed has nothing to do with the definition of
-@key{TAB} as a command. The variable @code{tab-width} must have an
-integer value between 1 and 1000, inclusive. The variable
-@code{default-tab-width} controls the default value of this variable
-for buffers where you have not set it locally.
-
- You can customize the way any particular character code is displayed
-by means of a display table. @xref{Display Tables,, Display Tables,
-elisp, The Emacs Lisp Reference Manual}.
-
-@node Cursor Display
-@section Displaying the Cursor
-
-@findex blink-cursor-mode
-@vindex blink-cursor-alist
-@cindex cursor, locating visually
-@cindex cursor, blinking
- You can customize the cursor's color, and whether it blinks, using
-the @code{cursor} Custom group (@pxref{Easy Customization}). On
-a graphical display, the command @kbd{M-x blink-cursor-mode} enables
-or disables the blinking of the cursor. (On text terminals, the
-terminal itself blinks the cursor, and Emacs has no control over it.)
-You can control how the cursor appears when it blinks off by setting
-the variable @code{blink-cursor-alist}.
-
-@vindex visible-cursor
- Some text terminals offer two different cursors: the normal cursor
-and the very visible cursor, where the latter may be e.g. bigger or
-blinking. By default Emacs uses the very visible cursor, and switches
-to it when you start or resume Emacs. If the variable
-@code{visible-cursor} is @code{nil} when Emacs starts or resumes, it
-doesn't switch, so it uses the normal cursor.
-
-@cindex cursor in non-selected windows
-@vindex cursor-in-non-selected-windows
- Normally, the cursor appears in non-selected windows in the ``off''
-state, with the same appearance as when the blinking cursor blinks
-``off.'' For a box cursor, this is a hollow box; for a bar cursor,
-this is a thinner bar. To turn off cursors in non-selected windows,
-customize the variable @code{cursor-in-non-selected-windows} and assign
-it a @code{nil} value.
-
-@vindex x-stretch-cursor
-@cindex wide block cursor
- On graphical displays, Emacs can optionally draw the block cursor
-as wide as the character under the cursor---for example, if the cursor
-is on a tab character, it would cover the full width occupied by that
-tab character. To enable this feature, set the variable
-@code{x-stretch-cursor} to a non-@code{nil} value.
-
-@findex hl-line-mode
-@findex global-hl-line-mode
-@cindex highlight current line
- To make the cursor even more visible, you can use HL Line mode, a
-minor mode that highlights the line containing point. Use @kbd{M-x
-hl-line-mode} to enable or disable it in the current buffer. @kbd{M-x
-global-hl-line-mode} enables or disables the same mode globally.
-
-@node Line Truncation
-@section Truncation of Lines
-
-@cindex truncation
-@cindex line truncation, and fringes
- As an alternative to continuation, Emacs can display long lines by
-@dfn{truncation}. This means that all the characters that do not fit
-in the width of the screen or window do not appear at all. On
-graphical displays, a small straight arrow in the fringe indicates
-truncation at either end of the line. On text-only terminals, @samp{$}
-appears in the first column when there is text truncated to the left,
-and in the last column when there is text truncated to the right.
-
-@vindex truncate-lines
-@findex toggle-truncate-lines
- Horizontal scrolling automatically causes line truncation
-(@pxref{Horizontal Scrolling}). You can explicitly enable line
-truncation for a particular buffer with the command @kbd{M-x
-toggle-truncate-lines}. This works by locally changing the variable
-@code{truncate-lines}. If that variable is non-@code{nil}, long lines
-are truncated; if it is @code{nil}, they are continued onto multiple
-screen lines. Setting the variable @code{truncate-lines} in any way
-makes it local to the current buffer; until that time, the default
-value is in effect. The default value is normally @code{nil}.
-
-@c @vindex truncate-partial-width-windows @c Idx entry is in Split Windows.
- If the variable @code{truncate-partial-width-windows} is
-non-@code{nil}, it forces truncation rather than continuation in any
-window less than the full width of the screen or frame, regardless of
-the value of @code{truncate-lines}. For information about side-by-side
-windows, see @ref{Split Window}. See also @ref{Display,, Display,
-elisp, The Emacs Lisp Reference Manual}.
-
-@vindex overflow-newline-into-fringe
- If the variable @code{overflow-newline-into-fringe} is
-non-@code{nil} on a graphical display, then Emacs does not continue or
-truncate a line which is exactly as wide as the window. Instead, the
-newline overflows into the right fringe, and the cursor appears in the
-fringe when positioned on that newline.
-
-@node Display Custom
-@section Customization of Display
-
- This section describes variables (@pxref{Variables}) that you can
-change to customize how Emacs displays. Beginning users can skip
-it.
-@c the reason for that pxref is because an xref early in the
-@c ``echo area'' section leads here.
-
-@vindex inverse-video
- If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
-to invert all the lines of the display from what they normally are.
-
-@vindex visible-bell
- If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
-to make the whole screen blink when it would normally make an audible bell
-sound. This variable has no effect if your terminal does not have a way
-to make the screen blink.
-
-@vindex echo-keystrokes
- The variable @code{echo-keystrokes} controls the echoing of multi-character
-keys; its value is the number of seconds of pause required to cause echoing
-to start, or zero, meaning don't echo at all. The value takes effect when
-there is someting to echo. @xref{Echo Area}.
-
-@vindex baud-rate
- The variable @anchor{baud-rate}@code{baud-rate} holds the output
-speed of the terminal, as far as Emacs knows. Setting this variable
-does not change the speed of actual data transmission, but the value
-is used for calculations. On text-only terminals, it affects padding,
-and decisions about whether to scroll part of the screen or redraw it
-instead. It also affects the behavior of incremental search.
-
- On graphical displays, @code{baud-rate} is only used to determine
-how frequently to look for pending input during display updating. A
-higher value of @code{baud-rate} means that check for pending input
-will be done less frequently.
-
-@cindex hourglass pointer display
-@vindex hourglass-delay
- On graphical display, Emacs can optionally display the mouse pointer
-in a special shape to say that Emacs is busy. To turn this feature on
-or off, customize the group @code{cursor}. You can also control the
-amount of time Emacs must remain busy before the busy indicator is
-displayed, by setting the variable @code{hourglass-delay}.
-
-@vindex overline-margin
- On graphical display, this variables specifies the vertical position
-of an overline above the text, including the height of the overline
-itself (1 pixel). The default value is 2 pixels.
-
-@vindex x-underline-at-descent-line
- On graphical display, Emacs normally draws an underline at the
-baseline level of the font. If @code{x-underline-at-descent-line} is
-non-@code{nil}, Emacs draws the underline at the same height as the
-font's descent line.
-
-@findex tty-suppress-bold-inverse-default-colors
- On some text-only terminals, bold face and inverse video together
-result in text that is hard to read. Call the function
-@code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil}
-argument to suppress the effect of bold-face in this case.
-
-@vindex no-redraw-on-reenter
- On a text-only terminal, when you reenter Emacs after suspending, Emacs
-normally clears the screen and redraws the entire display. On some
-terminals with more than one page of memory, it is possible to arrange
-the termcap entry so that the @samp{ti} and @samp{te} strings (output
-to the terminal when Emacs is entered and exited, respectively) switch
-between pages of memory so as to use one page for Emacs and another
-page for other output. On such terminals, you might want to set the variable
-@code{no-redraw-on-reenter} non-@code{nil}; this tells Emacs to
-assume, when resumed, that the screen page it is using still contains
-what Emacs last wrote there.
-
-@ignore
- arch-tag: 2219f910-2ff0-4521-b059-1bd231a536c4
-@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 -*-texinfo-*-
-@comment %**start of header
-@setfilename ../info/emacs-xtra
-@settitle Specialized Emacs Features
-@syncodeindex fn cp
-@syncodeindex vr cp
-@syncodeindex ky cp
-@comment %**end of header
-
-@copying
-This manual describes specialized features of Emacs.
-
-Copyright @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
-* Emacs-Xtra: (emacs-xtra). Specialized Emacs features.
-@end direntry
-
-@titlepage
-@title Specialized Emacs Features
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-@contents
-
-@ifnottex
-@node Top
-@top Specialized Emacs Features
-
-@insertcopying
-
-@end ifnottex
-
-@menu
-* Introduction:: What documentation belongs here?
-@iftex
-* Picture Mode:: Editing pictures made up of characters using
- the quarter-plane screen model.
-
-* Autorevert:: Auto Reverting non-file buffers.
-* Subdir Switches:: Subdirectory switches in Dired.
-* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
-* Emerge:: A convenient way of merging two versions of a program.
-* Advanced VC Usage:: Advanced VC (version control) features.
-* Fortran:: Fortran mode and its special features.
-* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}).
-@end iftex
-* Index::
-@end menu
-
-@node Introduction
-@unnumbered Introduction
-
-This manual contains detailed information about various features that
-are too specialized to be included in the printed Emacs manual. It is
-intended to be readable by anyone having a basic knowledge of Emacs.
-However, certain sections may be intended for a more specialized
-audience, such as Elisp authors. This should be clearly pointed out
-at the beginning of these sections.
-
-Certain packages, or collections of related features, have their own
-manuals, separate from the main Emacs User's manual. This manual is
-intended as a complement, rather than an alternative, to reading those
-additional manuals; in a nutshell, it is a collection of smaller
-specialized features, too small or too obscure to justify their own
-manual.
-
-Sections intended specifically for Elisp programmers can follow the
-style of the Elisp manual. Other sections should follow the style of
-the Emacs manual.
-
-@iftex
-@c ``Picture Mode'' is a chapter, not a section, so it's outside @raisesections.
-@include picture-xtra.texi
-
-@raisesections
-@include arevert-xtra.texi
-
-@include dired-xtra.texi
-
-@include cal-xtra.texi
-
-@include emerge-xtra.texi
-
-@include vc-xtra.texi
-
-@include fortran-xtra.texi
-
-@include msdog-xtra.texi
-
-@lowersections
-@end iftex
-
-@node Index
-@unnumbered Index
-
-@printindex cp
-
-@bye
-
-@ignore
- arch-tag: 75c33f13-32c6-41b6-9537-847a312e2e49
-@end ignore
+++ /dev/null
-\input texinfo
-
-@setfilename ../info/emacs
-@settitle GNU Emacs Manual
-
-@c The edition number appears in several places in this file
-@set EDITION Sixteenth
-@set EMACSVER 23.0.50
-
-@copying
-This is the @value{EDITION} edition of the @cite{GNU Emacs Manual},@*
-updated for Emacs version @value{EMACSVER}.
-
-Copyright @copyright{} 1985, 1986, 1987, 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.''
-
-(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
-this GNU Manual. Buying copies from GNU Press supports the FSF in
-developing GNU and promoting software freedom.''
-@end quotation
-@end copying
-
-@dircategory Emacs
-@direntry
-* Emacs: (emacs). The extensible self-documenting text editor.
-@end direntry
-
-@c in general, keep the following line commented out, unless doing a
-@c copy of this manual that will be published. The manual should go
-@c onto the distribution in the full, 8.5 x 11" size.
-@c set smallbook
-
-@ifset smallbook
-@smallbook
-@end ifset
-
-@c per rms and peterb, use 10pt fonts for the main text, mostly to
-@c save on paper cost.
-@c Do this inside @tex for now, so current makeinfo does not complain.
-@tex
-@ifset smallbook
-@fonttextsize 10
-@set EMACSVER 22
-\global\let\urlcolor=\Black % don't print links in grayscale
-\global\let\linkcolor=\Black
-@end ifset
-\global\hbadness=6666 % don't worry about not-too-underfull boxes
-@end tex
-
-@defcodeindex op
-@synindex pg cp
-
-@iftex
-@kbdinputstyle code
-
-@shorttitlepage GNU Emacs Manual
-@end iftex
-
-@titlepage
-@sp 6
-@center @titlefont{GNU Emacs Manual}
-@sp 4
-@center @value{EDITION} Edition, Updated for Emacs Version @value{EMACSVER}.
-@sp 5
-@center Richard Stallman
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-
-@sp 2
-Published by the Free Software Foundation @*
-51 Franklin Street, Fifth Floor @*
-Boston, MA 02110-1301 USA @*
-ISBN 1-882114-86-8
-
-@sp 2
-Cover art by Etienne Suvasa.
-
-@end titlepage
-
-
-@summarycontents
-@contents
-
-
-@ifnottex
-@node Top, Distrib, (dir), (dir)
-@top The Emacs Editor
-
-Emacs is the extensible, customizable, self-documenting real-time
-display editor. This Info file describes how to edit with Emacs and
-some of how to customize it; it corresponds to GNU Emacs version
-@value{EMACSVER}.
-
-@ifinfo
-To learn more about the Info documentation system, type @kbd{h}, and
-Emacs will take you to a programmed instruction sequence for the Info
-commands.
-@end ifinfo
-
-For information on extending Emacs, see @ref{Top, Emacs Lisp,, elisp, The
-Emacs Lisp Reference Manual}.
-@end ifnottex
-
-@ignore
-These subcategories have been deleted for simplicity
-and to avoid conflicts.
-Completion
-Backup Files
-Auto-Saving: Protection Against Disasters
-Snapshots
-Text Mode
-Outline Mode
-@TeX{} Mode
-Formatted Text
-Shell Command History
-
-The ones for Dired and Rmail have had the items turned into :: items
-to avoid conflicts.
-Also Running Shell Commands from Emacs
-and Sending Mail and Registers and Minibuffer.
-@end ignore
-
-@menu
-* Distrib:: How to get the latest Emacs distribution.
-* Copying:: The GNU General Public License gives you permission
- to redistribute GNU Emacs on certain terms;
- it also explains that there is no warranty.
-* GNU Free Documentation License:: The license for this documentation.
-* Intro:: An introduction to Emacs concepts.
-* Glossary:: The glossary.
-* Antinews:: Information about Emacs version 21.
-* Mac OS:: Using Emacs in the Mac.
-* Microsoft Windows:: Using Emacs on Microsoft Windows and MS-DOS.
-* Manifesto:: What's GNU? Gnu's Not Unix!
-* Acknowledgments:: Major contributors to GNU Emacs.
-
-Indexes (each index contains a large menu)
-* Key Index:: An item for each standard Emacs key sequence.
-* Option Index:: An item for every command-line option.
-* Command Index:: An item for each command name.
-* Variable Index:: An item for each documented variable.
-* Concept Index:: An item for each concept.
-
-Important General Concepts
-* Screen:: How to interpret what you see on the screen.
-* User Input:: Kinds of input events (characters, buttons,
- function keys).
-* Keys:: Key sequences: what you type to request one
- editing action.
-* Commands:: Named functions run by key sequences to do editing.
-* Text Characters:: Character set for text (the contents of buffers
- and strings).
-* Entering Emacs:: Starting Emacs from the shell.
-* Exiting:: Stopping or killing Emacs.
-* Emacs Invocation:: Hairy startup options.
-
-Fundamental Editing Commands
-* Basic:: The most basic editing commands.
-* Minibuffer:: Entering arguments that are prompted for.
-* M-x:: Invoking commands by their names.
-* Help:: Commands for asking Emacs about its commands.
-
-Important Text-Changing Commands
-* Mark:: The mark: how to delimit a ``region'' of text.
-* Killing:: Killing (cutting) text.
-* Yanking:: Recovering killed text. Moving text. (Pasting.)
-* Accumulating Text:: Other ways of copying text.
-* Rectangles:: Operating on the text inside a rectangle on the screen.
-* Registers:: Saving a text string or a location in the buffer.
-* Display:: Controlling what text is displayed.
-* Search:: Finding or replacing occurrences of a string.
-* Fixit:: Commands especially useful for fixing typos.
-* Keyboard Macros:: A keyboard macro records a sequence of
- keystrokes to be replayed with a single command.
-
-Major Structures of Emacs
-* Files:: All about handling files.
-* Buffers:: Multiple buffers; editing several files at once.
-* Windows:: Viewing two pieces of text at once.
-* Frames:: Running the same Emacs session in multiple X windows.
-* International:: Using non-@acronym{ASCII} character sets (the MULE features).
-
-Advanced Features
-* Major Modes:: Text mode vs. Lisp mode vs. C mode ...
-* Indentation:: Editing the white space at the beginnings of lines.
-* Text:: Commands and modes for editing English.
-* Programs:: Commands and modes for editing programs.
-* Building:: Compiling, running and debugging programs.
-* Maintaining:: Features for maintaining large programs.
-* Abbrevs:: How to define text abbreviations to reduce
- the number of characters you must type.
-@ifnottex
-* Picture Mode:: Editing pictures made up of characters using
- the quarter-plane screen model.
-@end ifnottex
-* Sending Mail:: Sending mail in Emacs.
-* Rmail:: Reading mail in Emacs.
-* Dired:: You can ``edit'' a directory to manage files in it.
-* Calendar/Diary:: The calendar and diary facilities.
-* Gnus:: How to read netnews with Emacs.
-* Shell:: Executing shell commands from Emacs.
-* Emacs Server:: Using Emacs as an editing server for @code{mail}, etc.
-* Printing:: Printing hardcopies of buffers or regions.
-* Sorting:: Sorting lines, paragraphs or pages within Emacs.
-* Narrowing:: Restricting display and editing to a portion
- of the buffer.
-* Two-Column:: Splitting apart columns to edit them
- in side-by-side windows.
-* Editing Binary Files::Using Hexl mode to edit binary files.
-* Saving Emacs Sessions:: Saving Emacs state from one session to the next.
-* Recursive Edit:: A command can allow you to do editing
- "within the command". This is called a
- "recursive editing level".
-* Emulation:: Emulating some other editors with Emacs.
-* Hyperlinking:: Following links in buffers.
-* Dissociated Press:: Dissociating text for fun.
-* Amusements:: Various games and hacks.
-* Customization:: Modifying the behavior of Emacs.
-* X Resources:: X resources for customizing Emacs.
-
-Recovery from Problems
-* Quitting:: Quitting and aborting.
-* Lossage:: What to do if Emacs is hung or malfunctioning.
-* Bugs:: How and when to report a bug.
-* Contributing:: How to contribute improvements to Emacs.
-* Service:: How to get help for your own Emacs needs.
-
-@c Do NOT modify the following 3 lines! They must have this form to
-@c be correctly identified by `texinfo-multiple-files-update'. In
-@c particular, the detailed menu header line MUST be identical to the
-@c value of `texinfo-master-menu-header'. See texnfo-upd.el.
-
-@detailmenu
- --- The Detailed Node Listing ---
- ---------------------------------
-
-Here are some other nodes which are really inferiors of the ones
-already listed, mentioned here so you can get to them in one step:
-
-The Organization of the Screen
-
-* Point:: The place in the text where editing commands operate.
-* Echo Area:: Short messages appear at the bottom of the screen.
-* Mode Line:: Interpreting the mode line.
-* Menu Bar:: How to use the menu bar.
-
-Basic Editing Commands
-
-* Inserting Text:: Inserting text by simply typing it.
-* Moving Point:: How to move the cursor to the place where you want to
- change something.
-* Erasing:: Deleting and killing text.
-* Basic Undo:: Undoing recent changes in the text.
-* Basic Files:: Visiting, creating, and saving files.
-* Basic Help:: Asking what a character does.
-* Blank Lines:: Commands to make or delete blank lines.
-* Continuation Lines:: Lines too wide for the screen.
-* Position Info:: What page, line, row, or column is point on?
-* Arguments:: Numeric arguments for repeating a command.
-* Repeating:: A short-cut for repeating the previous command.
-
-The Minibuffer
-
-* Minibuffer File:: Entering file names with the minibuffer.
-* Minibuffer Edit:: How to edit in the minibuffer.
-* Completion:: An abbreviation facility for minibuffer input.
-* Minibuffer History:: Reusing recent minibuffer arguments.
-* Repetition:: Re-executing commands that used the minibuffer.
-
-Completion
-
-* Example: Completion Example. Examples of using completion.
-* Commands: Completion Commands. A list of completion commands.
-* Strict Completion:: Different types of completion.
-* Options: Completion Options. Options for completion.
-
-Help
-
-* Help Summary:: Brief list of all Help commands.
-* Key Help:: Asking what a key does in Emacs.
-* Name Help:: Asking about a command, variable or function name.
-* Apropos:: Asking what pertains to a given topic.
-* Help Mode:: Special features of Help mode and Help buffers.
-* Library Keywords:: Finding Lisp libraries by keywords (topics).
-* Language Help:: Help relating to international language support.
-* Misc Help:: Other help commands.
-* Help Files:: Commands to display pre-written help files.
-* Help Echo:: Help on active text and tooltips (`balloon help')
-
-The Mark and the Region
-
-* Setting Mark:: Commands to set the mark.
-* Transient Mark:: How to make Emacs highlight the region--
- when there is one.
-* Momentary Mark:: Enabling Transient Mark mode momentarily.
-* Using Region:: Summary of ways to operate on contents of the region.
-* Marking Objects:: Commands to put region around textual units.
-* Mark Ring:: Previous mark positions saved so you can go back there.
-* Global Mark Ring:: Previous mark positions in various buffers.
-
-Killing and Moving Text
-
-* Deletion:: Commands for deleting small amounts of text and
- blank areas.
-* Killing by Lines:: How to kill entire lines of text at one time.
-* Other Kill Commands:: Commands to kill large regions of text and
- syntactic units such as words and sentences.
-* CUA Bindings:: Using @kbd{C-x}, @kbd{C-c}, @kbd{C-v} for copy
- and paste, with enhanced rectangle support.
-
-Yanking
-
-* Kill Ring:: Where killed text is stored. Basic yanking.
-* Appending Kills:: Several kills in a row all yank together.
-* Earlier Kills:: Yanking something killed some time ago.
-
-Registers
-
-* RegPos:: Saving positions in registers.
-* RegText:: Saving text in registers.
-* RegRect:: Saving rectangles in registers.
-* RegConfig:: Saving window configurations in registers.
-* RegNumbers:: Numbers in registers.
-* RegFiles:: File names in registers.
-* Bookmarks:: Bookmarks are like registers, but persistent.
-
-Controlling the Display
-
-* Scrolling:: Moving text up and down in a window.
-* Auto Scrolling:: Redisplay scrolls text automatically when needed.
-* Horizontal Scrolling:: Moving text left and right in a window.
-* Follow Mode:: Follow mode lets two windows scroll as one.
-* Faces:: How to change the display style using faces.
-* Standard Faces:: Emacs' predefined faces.
-* Font Lock:: Minor mode for syntactic highlighting using faces.
-* Highlight Interactively:: Tell Emacs what text to highlight.
-* Fringes:: Enabling or disabling window fringes.
-* Displaying Boundaries:: Displaying top and bottom of the buffer.
-* Useless Whitespace:: Showing possibly-spurious trailing whitespace.
-* Selective Display:: Hiding lines with lots of indentation.
-* Optional Mode Line:: Optional mode line display features.
-* Text Display:: How text characters are normally displayed.
-* Cursor Display:: Features for displaying the cursor.
-* Line Truncation:: Truncating lines to fit the screen width instead
- of continuing them to multiple screen lines.
-* Display Custom:: Information on variables for customizing display.
-
-Searching and Replacement
-
-* Incremental Search:: Search happens as you type the string.
-* Nonincremental Search:: Specify entire string and then search.
-* Word Search:: Search for sequence of words.
-* Regexp Search:: Search for match for a regexp.
-* Regexps:: Syntax of regular expressions.
-* Regexp Backslash:: Regular expression constructs starting with `\'.
-* Regexp Example:: A complex regular expression explained.
-* Search Case:: To ignore case while searching, or not.
-* Replace:: Search, and replace some or all matches.
-* Other Repeating Search:: Operating on all matches for some regexp.
-
-Incremental Search
-
-* Basic Isearch:: Basic incremental search commands.
-* Repeat Isearch:: Searching for the same string again.
-* Error in Isearch:: When your string is not found.
-* Special Isearch:: Special input in incremental search.
-* Non-ASCII Isearch:: How to search for non-ASCII characters.
-* Isearch Yank:: Commands that grab text into the search string
- or else edit the search string.
-* Highlight Isearch:: Isearch highlights the other possible matches.
-* Isearch Scroll:: Scrolling during an incremental search.
-* Slow Isearch:: Incremental search features for slow terminals.
-
-Replacement Commands
-
-* Unconditional Replace:: Replacing all matches for a string.
-* Regexp Replace:: Replacing all matches for a regexp.
-* Replacement and Case:: How replacements preserve case of letters.
-* Query Replace:: How to use querying.
-
-Commands for Fixing Typos
-
-* Undo:: Full details of Emacs undo commands.
-* Kill Errors:: Commands to kill a batch of recently entered text.
-* Transpose:: Exchanging two characters, words, lines, lists...
-* Fixing Case:: Correcting case of last word entered.
-* Spelling:: Apply spelling checker to a word or a whole buffer.
-
-Keyboard Macros
-
-* Basic Keyboard Macro:: Defining and running keyboard macros.
-* Keyboard Macro Ring:: Where previous keyboard macros are saved.
-* Keyboard Macro Counter:: Inserting incrementing numbers in macros.
-* Keyboard Macro Query:: Making keyboard macros do different things each time.
-* Save Keyboard Macro:: Giving keyboard macros names; saving them in files.
-* Edit Keyboard Macro:: Editing keyboard macros.
-* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard
- macro.
-
-File Handling
-
-* File Names:: How to type and edit file-name arguments.
-* Visiting:: Visiting a file prepares Emacs to edit the file.
-* Saving:: Saving makes your changes permanent.
-* Reverting:: Reverting cancels all the changes not saved.
-* Autorevert:: Auto Reverting non-file buffers.
-* Auto Save:: Auto Save periodically protects against loss of data.
-* File Aliases:: Handling multiple names for one file.
-* Version Control:: Version control systems (RCS, CVS and SCCS).
-* Directories:: Creating, deleting, and listing file directories.
-* Comparing Files:: Finding where two files differ.
-* Diff Mode:: Editing diff output.
-* Misc File Ops:: Other things you can do on files.
-* Compressed Files:: Accessing compressed files.
-* File Archives:: Operating on tar, zip, jar etc. archive files.
-* Remote Files:: Accessing files on other sites.
-* Quoted File Names:: Quoting special characters in file names.
-* File Name Cache:: Completion against a list of files you often use.
-* File Conveniences:: Convenience Features for Finding Files.
-* Filesets:: Handling sets of files.
-
-Saving Files
-
-* Save Commands:: Commands for saving files.
-* Backup:: How Emacs saves the old version of your file.
-* Customize Save:: Customizing the saving of files.
-* Interlocking:: How Emacs protects against simultaneous editing
- of one file by two users.
-* File Shadowing:: Copying files to "shadows" automatically.
-* Time Stamps:: Emacs can update time stamps on saved files.
-
-Backup Files
-
-* One or Many: Numbered Backups. Whether to make one backup file or many.
-* Names: Backup Names. How backup files are named.
-* Deletion: Backup Deletion. Emacs deletes excess numbered backups.
-* Copying: Backup Copying. Backups can be made by copying or renaming.
-
-Auto-Saving: Protection Against Disasters
-
-* Files: Auto Save Files. The file where auto-saved changes are
- actually made until you save the file.
-* Control: Auto Save Control. Controlling when and how often to auto-save.
-* Recover:: Recovering text from auto-save files.
-
-Version Control
-
-* Introduction to VC:: How version control works in general.
-* VC Mode Line:: How the mode line shows version control status.
-* Basic VC Editing:: How to edit a file under version control.
-* Old Versions:: Examining and comparing old versions.
-* Secondary VC Commands:: The commands used a little less frequently.
-* Branches:: Multiple lines of development.
-* Remote Repositories:: Efficient access to remote CVS servers.
-* Snapshots:: Sets of file versions treated as a unit.
-* Miscellaneous VC:: Various other commands and features of VC.
-* Customizing VC:: Variables that change VC's behavior.
-
-Using Multiple Buffers
-
-* Select Buffer:: Creating a new buffer or reselecting an old one.
-* List Buffers:: Getting a list of buffers that exist.
-* Misc Buffer:: Renaming; changing read-onliness; copying text.
-* Kill Buffer:: Killing buffers you no longer need.
-* Several Buffers:: How to go through the list of all buffers
- and operate variously on several of them.
-* Indirect Buffers:: An indirect buffer shares the text of another buffer.
-* Buffer Convenience:: Convenience and customization features for
- buffer handling.
-
-Multiple Windows
-
-* Basic Window:: Introduction to Emacs windows.
-* Split Window:: New windows are made by splitting existing windows.
-* Other Window:: Moving to another window or doing something to it.
-* Pop Up Window:: Finding a file or buffer in another window.
-* Force Same Window:: Forcing certain buffers to appear in the selected
- window rather than in another window.
-* Change Window:: Deleting windows and changing their sizes.
-* Window Convenience:: Convenience functions for window handling.
-
-Frames and Graphical Displays
-
-* Cut and Paste:: Mouse commands for cut and paste.
-* Mouse References:: Using the mouse to select an item from a list.
-* Menu Mouse Clicks:: Mouse clicks that bring up menus.
-* Mode Line Mouse:: Mouse clicks on the mode line.
-* Creating Frames:: Creating additional Emacs frames with various contents.
-* Frame Commands:: Iconifying, deleting, and switching frames.
-* Speedbar:: How to make and use a speedbar frame.
-* Multiple Displays:: How one Emacs job can talk to several displays.
-* Special Buffer Frames:: You can make certain buffers have their own frames.
-* Frame Parameters:: Changing the colors and other modes of frames.
-* Scroll Bars:: How to enable and disable scroll bars; how to use them.
-* Wheeled Mice:: Using mouse wheels for scrolling.
-* Drag and Drop:: Using drag and drop to open files and insert text.
-* Menu Bars:: Enabling and disabling the menu bar.
-* Tool Bars:: Enabling and disabling the tool bar.
-* Dialog Boxes:: Controlling use of dialog boxes.
-* Tooltips:: Showing "tooltips", AKA "balloon help" for active text.
-* Mouse Avoidance:: Moving the mouse pointer out of the way.
-* Non-Window Terminals:: Multiple frames on terminals that show only one.
-* Text-Only Mouse:: Using the mouse in text-only terminals.
-
-International Character Set Support
-
-* International Chars:: Basic concepts of multibyte characters.
-* Enabling Multibyte:: Controlling whether to use multibyte characters.
-* Language Environments:: Setting things up for the language you use.
-* Input Methods:: Entering text characters not on your keyboard.
-* Select Input Method:: Specifying your choice of input methods.
-* Multibyte Conversion:: How single-byte characters convert to multibyte.
-* Coding Systems:: Character set conversion when you read and
- write files, and so on.
-* Recognize Coding:: How Emacs figures out which conversion to use.
-* Specify Coding:: Specifying a file's coding system explicitly.
-* Output Coding:: Choosing coding systems for output.
-* Text Coding:: Choosing conversion to use for file text.
-* Communication Coding:: Coding systems for interprocess communication.
-* File Name Coding:: Coding systems for file @emph{names}.
-* Terminal Coding:: Specifying coding systems for converting
- terminal input and output.
-* Fontsets:: Fontsets are collections of fonts
- that cover the whole spectrum of characters.
-* Defining Fontsets:: Defining a new fontset.
-* Undisplayable Characters::When characters don't display.
-* Unibyte Mode:: You can pick one European character set
- to use without multibyte characters.
-* Charsets:: How Emacs groups its internal character codes.
-
-Major Modes
-
-* Choosing Modes:: How major modes are specified or chosen.
-
-Indentation
-
-* Indentation Commands:: Various commands and techniques for indentation.
-* Tab Stops:: You can set arbitrary "tab stops" and then
- indent to the next tab stop when you want to.
-* Just Spaces:: You can request indentation using just spaces.
-
-Commands for Human Languages
-
-* Words:: Moving over and killing words.
-* Sentences:: Moving over and killing sentences.
-* Paragraphs:: Moving over paragraphs.
-* Pages:: Moving over pages.
-* Filling:: Filling or justifying text.
-* Case:: Changing the case of text.
-* Text Mode:: The major modes for editing text files.
-* Outline Mode:: Editing outlines.
-* TeX Mode:: Editing input to the formatter TeX.
-* HTML Mode:: Editing HTML, SGML, and XML files.
-* Nroff Mode:: Editing input to the formatter nroff.
-* Formatted Text:: Editing formatted text directly in WYSIWYG fashion.
-* Text Based Tables:: Editing text-based tables in WYSIWYG fashion.
-
-Filling Text
-
-* Auto Fill:: Auto Fill mode breaks long lines automatically.
-* Refill:: Keeping paragraphs filled.
-* Fill Commands:: Commands to refill paragraphs and center lines.
-* Fill Prefix:: Filling paragraphs that are indented
- or in a comment, etc.
-* Adaptive Fill:: How Emacs can determine the fill prefix automatically.
-* Longlines:: Editing text with very long lines.
-
-Outline Mode
-
-* Format: Outline Format. What the text of an outline looks like.
-* Motion: Outline Motion. Special commands for moving through
- outlines.
-* Visibility: Outline Visibility. Commands to control what is visible.
-* Views: Outline Views. Outlines and multiple views.
-* Foldout:: Folding means zooming in on outlines.
-
-@TeX{} Mode
-
-* Editing: TeX Editing. Special commands for editing in TeX mode.
-* LaTeX: LaTeX Editing. Additional commands for LaTeX input files.
-* Printing: TeX Print. Commands for printing part of a file with TeX.
-* Misc: TeX Misc. Customization of TeX mode, and related features.
-
-Editing Formatted Text
-
-* Requesting Formatted Text:: Entering and exiting Enriched mode.
-* Hard and Soft Newlines:: There are two different kinds of newlines.
-* Editing Format Info:: How to edit text properties.
-* Faces: Format Faces. Bold, italic, underline, etc.
-* Color: Format Colors. Changing the color of text.
-* Indent: Format Indentation. Changing the left and right margins.
-* Justification: Format Justification.
- Centering, setting text flush with the
- left or right margin, etc.
-* Other: Format Properties. The "special" text properties submenu.
-* Forcing Enriched Mode:: How to force use of Enriched mode.
-
-Editing Text-based Tables
-
-* Table Definition:: What is a text based table.
-* Table Creation:: How to create a table.
-* Table Recognition:: How to activate and deactivate tables.
-* Cell Commands:: Cell-oriented commands in a table.
-* Cell Justification:: Justifying cell contents.
-* Row Commands:: Manipulating rows of table cell.
-* Column Commands:: Manipulating columns of table cell.
-* Fixed Width Mode:: Fixing cell width.
-* Table Conversion:: Converting between plain text and tables.
-* Measuring Tables:: Analyzing table dimension.
-* Table Misc:: Table miscellany.
-
-Editing Programs
-
-* Program Modes:: Major modes for editing programs.
-* Defuns:: Commands to operate on major top-level parts
- of a program.
-* Program Indent:: Adjusting indentation to show the nesting.
-* Parentheses:: Commands that operate on parentheses.
-* Comments:: Inserting, killing, and aligning comments.
-* Documentation:: Getting documentation of functions you plan to call.
-* Hideshow:: Displaying blocks selectively.
-* Symbol Completion:: Completion on symbol names of your program or language.
-* Glasses:: Making identifiersLikeThis more readable.
-* Misc for Programs:: Other Emacs features useful for editing programs.
-* C Modes:: Special commands of C, C++, Objective-C,
- Java, and Pike modes.
-* Asm Mode:: Asm mode and its special features.
-* Fortran:: Fortran mode and its special features.
-
-Top-Level Definitions, or Defuns
-
-* Left Margin Paren:: An open-paren or similar opening delimiter
- starts a defun if it is at the left margin.
-* Moving by Defuns:: Commands to move over or mark a major definition.
-* Imenu:: Making buffer indexes as menus.
-* Which Function:: Which Function mode shows which function you are in.
-
-Indentation for Programs
-
-* Basic Indent:: Indenting a single line.
-* Multi-line Indent:: Commands to reindent many lines at once.
-* Lisp Indent:: Specifying how each Lisp function should be indented.
-* C Indent:: Extra features for indenting C and related modes.
-* Custom C Indent:: Controlling indentation style for C and related modes.
-
-Commands for Editing with Parentheses
-
-* Expressions:: Expressions with balanced parentheses.
-* Moving by Parens:: Commands for moving up, down and across
- in the structure of parentheses.
-* Matching:: Insertion of a close-delimiter flashes matching open.
-
-Manipulating Comments
-
-* Comment Commands:: Inserting, killing, and aligning comments.
-* Multi-Line Comments:: Commands for adding and editing multi-line comments.
-* Options for Comments::Customizing the comment features.
-
-Documentation Lookup
-
-* Info Lookup:: Looking up library functions and commands
- in Info files.
-* Man Page:: Looking up man pages of library functions and commands.
-* Lisp Doc:: Looking up Emacs Lisp functions, etc.
-
-C and Related Modes
-
-* Motion in C:: Commands to move by C statements, etc.
-* Electric C:: Colon and other chars can automatically reindent.
-* Hungry Delete:: A more powerful DEL command.
-* Other C Commands:: Filling comments, viewing expansion of macros,
- and other neat features.
-
-Compiling and Testing Programs
-
-* Compilation:: Compiling programs in languages other
- than Lisp (C, Pascal, etc.).
-* Compilation Mode:: The mode for visiting compiler errors.
-* Compilation Shell:: Customizing your shell properly
- for use in the compilation buffer.
-* Grep Searching:: Searching with grep.
-* Flymake:: Finding syntax errors on the fly.
-* Debuggers:: Running symbolic debuggers for non-Lisp programs.
-* Executing Lisp:: Various modes for editing Lisp programs,
- with different facilities for running
- the Lisp programs.
-* Lisp Libraries:: Creating Lisp programs to run in Emacs.
-* Lisp Eval:: Executing a single Lisp expression in Emacs.
-* Lisp Interaction:: Executing Lisp in an Emacs buffer.
-* External Lisp:: Communicating through Emacs with a separate Lisp.
-
-Running Debuggers Under Emacs
-
-* Starting GUD:: How to start a debugger subprocess.
-* Debugger Operation:: Connection between the debugger and source buffers.
-* Commands of GUD:: Key bindings for common commands.
-* GUD Customization:: Defining your own commands for GUD.
-* GDB Graphical Interface:: An enhanced mode that uses GDB features to
- implement a graphical debugging environment through
- Emacs.
-
-Maintaining Large Programs
-
-* Change Log:: Maintaining a change history for your program.
-* Format of ChangeLog:: What the change log file looks like.
-* Tags:: Go direct to any function in your program in one
- command. Tags remembers which file it is in.
-* Emerge:: A convenient way of merging two versions of a program.
-
-Tags Tables
-
-* Tag Syntax:: Tag syntax for various types of code and text files.
-* Create Tags Table:: Creating a tags table with @code{etags}.
-* Etags Regexps:: Create arbitrary tags using regular expressions.
-* Select Tags Table:: How to visit a tags table.
-* Find Tag:: Commands to find the definition of a specific tag.
-* Tags Search:: Using a tags table for searching and replacing.
-* List Tags:: Listing and finding tags defined in a file.
-
-Abbrevs
-
-* Abbrev Concepts:: Fundamentals of defined abbrevs.
-* Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
-* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
-* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
-* Saving Abbrevs:: Saving the entire list of abbrevs for another session.
-* Dynamic Abbrevs:: Abbreviations for words already in the buffer.
-* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling.
-
-@ifnottex
-Editing Pictures
-
-* Basic Picture:: Basic concepts and simple commands of Picture Mode.
-* Insert in Picture:: Controlling direction of cursor motion
- after "self-inserting" characters.
-* Tabs in Picture:: Various features for tab stops and indentation.
-* Rectangles in Picture:: Clearing and superimposing rectangles.
-@end ifnottex
-
-Sending Mail
-
-* Mail Format:: Format of the mail being composed.
-* Mail Headers:: Details of permitted mail header fields.
-* Mail Aliases:: Abbreviating and grouping mail addresses.
-* Mail Mode:: Special commands for editing mail being composed.
-* Mail Amusements:: Distract the NSA's attention; add a fortune to a msg.
-* Mail Methods:: Using alternative mail-composition methods.
-
-Reading Mail with Rmail
-
-* Rmail Basics:: Basic concepts of Rmail, and simple use.
-* Rmail Scrolling:: Scrolling through a message.
-* Rmail Motion:: Moving to another message.
-* Rmail Deletion:: Deleting and expunging messages.
-* Rmail Inbox:: How mail gets into the Rmail file.
-* Rmail Files:: Using multiple Rmail files.
-* Rmail Output:: Copying message out to files.
-* Rmail Labels:: Classifying messages by labeling them.
-* Rmail Attributes:: Certain standard labels, called attributes.
-* Rmail Reply:: Sending replies to messages you are viewing.
-* Rmail Summary:: Summaries show brief info on many messages.
-* Rmail Sorting:: Sorting messages in Rmail.
-* Rmail Display:: How Rmail displays a message; customization.
-* Rmail Coding:: How Rmail handles decoding character sets.
-* Rmail Editing:: Editing message text and headers in Rmail.
-* Rmail Digest:: Extracting the messages from a digest message.
-* Out of Rmail:: Converting an Rmail file to mailbox format.
-* Rmail Rot13:: Reading messages encoded in the rot13 code.
-* Movemail:: More details of fetching new mail.
-* Remote Mailboxes:: Retrieving Mail from Remote Mailboxes.
-* Other Mailbox Formats:: Retrieving Mail from Local Mailboxes in
- Various Formats
-
-Dired, the Directory Editor
-
-* Dired Enter:: How to invoke Dired.
-* Dired Navigation:: How to move in the Dired buffer.
-* Dired Deletion:: Deleting files with Dired.
-* Flagging Many Files:: Flagging files based on their names.
-* Dired Visiting:: Other file operations through Dired.
-* Marks vs Flags:: Flagging for deletion vs marking.
-* Operating on Files:: How to copy, rename, print, compress, etc.
- either one file or several files.
-* Shell Commands in Dired:: Running a shell command on the marked files.
-* Transforming File Names:: Using patterns to rename multiple files.
-* Comparison in Dired:: Running `diff' by way of Dired.
-* Subdirectories in Dired:: Adding subdirectories to the Dired buffer.
-* Subdir Switches:: Subdirectory switches in Dired.
-* Subdirectory Motion:: Moving across subdirectories, and up and down.
-* Hiding Subdirectories:: Making subdirectories visible or invisible.
-* Dired Updating:: Discarding lines for files of no interest.
-* Dired and Find:: Using `find' to choose the files for Dired.
-* Wdired:: Operating on files by editing the Dired buffer.
-* Image-Dired:: Viewing image thumbnails in Dired
-* Misc Dired Features:: Various other features.
-
-The Calendar and the Diary
-
-* Calendar Motion:: Moving through the calendar; selecting a date.
-* Scroll Calendar:: Bringing earlier or later months onto the screen.
-* Counting Days:: How many days are there between two dates?
-* General Calendar:: Exiting or recomputing the calendar.
-* Writing Calendar Files:: Writing calendars to files of various formats.
-* Holidays:: Displaying dates of holidays.
-* Sunrise/Sunset:: Displaying local times of sunrise and sunset.
-* Lunar Phases:: Displaying phases of the moon.
-* Other Calendars:: Converting dates to other calendar systems.
-* Diary:: Displaying events from your diary.
-* Appointments:: Reminders when it's time to do something.
-* Importing Diary:: Converting diary events to/from other formats.
-* Daylight Saving:: How to specify when daylight saving time is active.
-* Time Intervals:: Keeping track of time intervals.
-* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
-
-Movement in the Calendar
-
-* Calendar Unit Motion:: Moving by days, weeks, months, and years.
-* Move to Beginning or End:: Moving to start/end of weeks, months, and years.
-* Specified Dates:: Moving to the current date or another
- specific date.
-
-Conversion To and From Other Calendars
-
-* Calendar Systems:: The calendars Emacs understands
- (aside from Gregorian).
-* To Other Calendar:: Converting the selected date to various calendars.
-* From Other Calendar:: Moving to a date specified in another calendar.
-* Mayan Calendar:: Moving to a date specified in a Mayan calendar.
-
-The Diary
-
-* Displaying the Diary:: Viewing diary entries and associated calendar dates.
-* Format of Diary File:: Entering events in your diary.
-* Date Formats:: Various ways you can specify dates.
-* Adding to Diary:: Commands to create diary entries.
-* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
-
-Gnus
-
-* Buffers of Gnus:: The group, summary, and article buffers.
-* Gnus Startup:: What you should know about starting Gnus.
-* Summary of Gnus:: A short description of the basic Gnus commands.
-
-Running Shell Commands from Emacs
-
-* Single Shell:: How to run one shell command and return.
-* Interactive Shell:: Permanent shell taking input via Emacs.
-* Shell Mode:: Special Emacs commands used with permanent shell.
-* Shell Prompts:: Two ways to recognize shell prompts.
-* Shell History:: Repeating previous commands in a shell buffer.
-* Directory Tracking:: Keeping track when the subshell changes directory.
-* Shell Options:: Options for customizing Shell mode.
-* Terminal emulator:: An Emacs window as a terminal emulator.
-* Term Mode:: Special Emacs commands used in Term mode.
-* Paging in Term:: Paging in the terminal emulator.
-* Remote Host:: Connecting to another computer.
-
-Using Emacs as a Server
-
-* Invoking emacsclient:: Emacs client startup options.
-
-Printing Hard Copies
-
-* PostScript:: Printing buffers or regions as PostScript.
-* PostScript Variables:: Customizing the PostScript printing commands.
-* Printing Package:: An optional advanced printing interface.
-
-Hyperlinking and Navigation Features
-
-* Browse-URL:: Following URLs.
-* Goto-address:: Activating URLs.
-* FFAP:: Finding files etc. at point.
-
-Customization
-
-* Minor Modes:: Each minor mode is one feature you can turn on
- independently of any others.
-* Easy Customization:: Convenient way to browse and change user options.
-* Variables:: Many Emacs commands examine Emacs variables
- to decide what to do; by setting variables,
- you can control their functioning.
-* Key Bindings:: The keymaps say what command each key runs.
- By changing them, you can "redefine keys".
-* Syntax:: The syntax table controls how words and
- expressions are parsed.
-* Init File:: How to write common customizations in the
- @file{.emacs} file.
-
-Variables
-
-* Examining:: Examining or setting one variable's value.
-* Hooks:: Hook variables let you specify programs for parts
- of Emacs to run on particular occasions.
-* Locals:: Per-buffer values of variables.
-* File Variables:: How files can specify variable values.
-
-Customizing Key Bindings
-
-* Keymaps:: Generalities. The global keymap.
-* Prefix Keymaps:: Keymaps for prefix keys.
-* Local Keymaps:: Major and minor modes have their own keymaps.
-* Minibuffer Maps:: The minibuffer uses its own local keymaps.
-* Rebinding:: How to redefine one key's meaning conveniently.
-* Init Rebinding:: Rebinding keys with your init file, @file{.emacs}.
-* Function Keys:: Rebinding terminal function keys.
-* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on.
-* Mouse Buttons:: Rebinding mouse buttons in Emacs.
-* Disabling:: Disabling a command means confirmation is required
- before it can be executed. This is done to protect
- beginners from surprises.
-
-The Init File, @file{~/.emacs}
-
-* Init Syntax:: Syntax of constants in Emacs Lisp.
-* Init Examples:: How to do some things with an init file.
-* Terminal Init:: Each terminal type can have an init file.
-* Find Init:: How Emacs finds the init file.
-* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file.
-
-Dealing with Emacs Trouble
-
-* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete.
-* Stuck Recursive:: `[...]' in mode line around the parentheses.
-* Screen Garbled:: Garbage on the screen.
-* Text Garbled:: Garbage in the text.
-* Memory Full:: How to cope when you run out of memory.
-* After a Crash:: Recovering editing in an Emacs session that crashed.
-* Emergency Escape:: Emergency escape---
- What to do if Emacs stops responding.
-* Total Frustration:: When you are at your wits' end.
-
-Reporting Bugs
-
-* Bug Criteria:: Have you really found a bug?
-* Understanding Bug Reporting:: How to report a bug effectively.
-* Checklist:: Steps to follow for a good bug report.
-* Sending Patches:: How to send a patch for GNU Emacs.
-
-Command Line Arguments for Emacs Invocation
-
-* Action Arguments:: Arguments to visit files, load libraries,
- and call functions.
-* Initial Options:: Arguments that take effect while starting Emacs.
-* Command Example:: Examples of using command line arguments.
-* Resume Arguments:: Specifying arguments when you resume a running Emacs.
-* Environment:: Environment variables that Emacs uses.
-* Display X:: Changing the default display and using remote login.
-* Font X:: Choosing a font for text, under X.
-* Colors:: Choosing display colors.
-* Window Size X:: Start-up window size, under X.
-* Borders X:: Internal and external borders, under X.
-* Title X:: Specifying the initial frame's title.
-* Icons X:: Choosing what sort of icon to use, under X.
-* Misc X:: Other display options.
-
-Environment Variables
-
-* General Variables:: Environment variables that all versions of Emacs use.
-* Misc Variables:: Certain system specific variables.
-* MS-Windows Registry:: An alternative to the environment on MS-Windows.
-
-X Options and Resources
-
-* Resources:: Using X resources with Emacs (in general).
-* Table of Resources:: Table of specific X resources that affect Emacs.
-* Face Resources:: X resources for customizing faces.
-* Lucid Resources:: X resources for Lucid menus.
-* LessTif Resources:: X resources for LessTif and Motif menus.
-* GTK resources:: Resources for GTK widgets.
-
-Emacs and Mac OS
-
-* Mac Input:: Keyboard and mouse input on Mac.
-* Mac International:: International character sets on Mac.
-* Mac Environment Variables:: Setting environment variables for Emacs.
-* Mac Directories:: Volumes and directories on Mac.
-* Mac Font Specs:: Specifying fonts on Mac.
-* Mac Functions:: Mac-specific Lisp functions.
-
-Emacs and Microsoft Windows/MS-DOS
-
-* Text and Binary:: Text files use CRLF to terminate lines.
-* Windows Files:: File-name conventions on Windows.
-* ls in Lisp:: Emulation of @code{ls} for Dired.
-* Windows HOME:: Where Emacs looks for your @file{.emacs}.
-* Windows Keyboard:: Windows-specific keyboard features.
-* Windows Mouse:: Windows-specific mouse features.
-* Windows Processes:: Running subprocesses on Windows.
-* Windows Printing:: How to specify the printer on MS-Windows.
-* Windows Misc:: Miscellaneous Windows features.
-* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}).
-@end detailmenu
-@end menu
-
-@iftex
-@unnumbered Preface
-
- This manual documents the use and simple customization of the Emacs
-editor. Simple Emacs customizations do not require you to be a
-programmer, but if you are not interested in customizing, you can
-ignore the customization hints.
-
- This is primarily a reference manual, but can also be used as a
-primer. If you are new to Emacs, we recommend you start with
-the on-line, learn-by-doing tutorial, before reading the manual. To
-run the tutorial, start Emacs and type @kbd{C-h t}. The tutorial
-describes commands, tells you when to try them, and explains the
-results.
-
- On first reading, just skim chapters 1 and 2, which describe the
-notational conventions of the manual and the general appearance of the
-Emacs display screen. Note which questions are answered in these
-chapters, so you can refer back later. After reading chapter 4, you
-should practice the commands shown there. The next few chapters
-describe fundamental techniques and concepts that are used constantly.
-You need to understand them thoroughly, so experiment with them
-until you are fluent.
-
- Chapters 14 through 19 describe intermediate-level features that are
-useful for many kinds of editing. Chapter 20 and following chapters
-describe optional but useful features; read those chapters when you
-need them.
-
- Read the Trouble chapter if Emacs does not seem to be working
-properly. It explains how to cope with several common problems
-(@pxref{Lossage}), as well as when and how to report Emacs bugs
-(@pxref{Bugs}).
-
- To find the documentation of a particular command, look in the index.
-Keys (character commands) and command names have separate indexes.
-There is also a glossary, with a cross reference for each term.
-
- This manual is available as a printed book and also as an Info file.
-The Info file is for on-line perusal with the Info program, which is
-the principal means of accessing on-line documentation in the GNU
-system. Both the Emacs Info file and an Info reader are included with
-GNU Emacs. The Info file and the printed book contain substantially
-the same text and are generated from the same source files, which are
-also distributed with GNU Emacs.
-
- GNU Emacs is a member of the Emacs editor family. There are many
-Emacs editors, all sharing common principles of organization. For
-information on the underlying philosophy of Emacs and the lessons
-learned from its development, see @cite{Emacs, the Extensible,
-Customizable Self-Documenting Display Editor}, available from
-@url{ftp://publications.ai.mit.edu/ai-publications/pdf/AIM-519A.pdf}.
-
-This edition of the manual is intended for use with GNU Emacs
-installed on GNU and Unix systems. GNU Emacs can also be used on VMS,
-MS-DOS (also called MS-DOG), Microsoft Windows, and Macintosh systems.
-Those systems use different file name syntax; in addition, VMS and
-MS-DOS do not support all GNU Emacs features. @xref{Microsoft
-Windows}, for information about using Emacs on Windows.
-@xref{Mac OS}, for information about using Emacs on Macintosh. We
-don't try to describe VMS usage in this manual.
-@end iftex
-
-@node Distrib, Intro, Top, Top
-@unnumbered Distribution
-
-GNU Emacs is @dfn{free software}; this means that everyone is free to
-use it and free to redistribute it on certain conditions. GNU Emacs
-is not in the public domain; it is copyrighted and there are
-restrictions on its distribution, but these restrictions are designed
-to permit everything that a good cooperating citizen would want to do.
-What is not allowed is to try to prevent others from further sharing
-any version of GNU Emacs that they might get from you. The precise
-conditions are found in the GNU General Public License that comes with
-Emacs and also appears in this manual@footnote{This manual is itself
-covered by the GNU Free Documentation License. This license is
-similar in spirit to the General Public License, but is more suitable
-for documentation. @xref{GNU Free Documentation License}.}.
-@xref{Copying}.
-
-One way to get a copy of GNU Emacs is from someone else who has it.
-You need not ask for our permission to do so, or tell any one else;
-just copy it. If you have access to the Internet, you can get the
-latest distribution version of GNU Emacs by anonymous FTP; see
-@url{http://www.gnu.org/software/emacs} on our website for more
-information.
-
-You may also receive GNU Emacs when you buy a computer. Computer
-manufacturers are free to distribute copies on the same terms that apply to
-everyone else. These terms require them to give you the full sources,
-including whatever changes they may have made, and to permit you to
-redistribute the GNU Emacs received from them under the usual terms of the
-General Public License. In other words, the program must be free for you
-when you get it, not just free for the manufacturer.
-
-You can also order copies of GNU Emacs from the Free Software
-Foundation. This is a convenient and reliable way to get a copy; it is
-also a good way to help fund our work. We also sell hardcopy versions
-of this manual and @cite{An Introduction to Programming in Emacs Lisp},
-by Robert J. Chassell. You can find an order form on our web site at
-@url{http://www.gnu.org/order/order.html}. For further information,
-write to
-
-@display
-Free Software Foundation
-51 Franklin Street, Fifth Floor
-Boston, MA 02110-1301
-USA
-@end display
-
-The income from distribution fees goes to support the foundation's
-purpose: the development of new free software, and improvements to our
-existing programs including GNU Emacs.
-
-If you find GNU Emacs useful, please @strong{send a donation} to the
-Free Software Foundation to support our work. Donations to the Free
-Software Foundation are tax deductible in the US. If you use GNU Emacs
-at your workplace, please suggest that the company make a donation. If
-company policy is unsympathetic to the idea of donating to charity, you
-might instead suggest ordering a CD-ROM from the Foundation
-occasionally, or subscribing to periodic updates.
-
-@iftex
-@node Acknowledgments, Intro, Distrib, Top
-@unnumberedsec Acknowledgments
-
-Contributors to GNU Emacs include Jari Aalto, Per Abrahamsen, Tomas
-Abrahamsson, Jay K.@: Adams, Michael Albinus, Nagy Andras, Ralf
-Angeli, Joe Arceneaux, Miles Bader, David Bakhash, Juanma Barranquero,
-Eli Barzilay, Steven L.@: Baur, Jay Belanger, Alexander L.@: Belikoff,
-Boaz Ben-Zvi, Karl Berry, Anna M.@: Bigatti, Ray Blaak, Jim Blandy, Johan Bockg@aa{}rd,
-Per Bothner, Terrence Brannon, Frank Bresz, Peter Breton, Emmanuel
-Briot, Kevin Broadey, Vincent Broman, David M.@: Brown, Georges
-Brun-Cottan, Joe Buehler, W@l{}odek Bzyl, Bill Carpenter, Per
-Cederqvist, Hans Chalupsky, Chris Chase, Bob Chassell, Andrew Choi,
-Sacha Chua, James Clark, Mike Clarkson, Glynn Clements, Andrew
-Csillag, Doug Cutting, Mathias Dahl, Satyaki Das, Michael DeCorte,
-Gary Delp, Matthieu Devin, Eri Ding, Jan Dj@"{a}rv, Carsten Dominik,
-Scott Draves, Benjamin Drieu, Viktor Dukhovni, John Eaton, Rolf Ebert,
-Paul Eggert, Stephen Eglen, Torbj@"orn Einarsson, Tsugutomo Enami,
-Hans Henrik Eriksen, Michael Ernst, Ata Etemadi, Frederick Farnbach,
-Oscar Figueiredo, Fred Fish, Karl Fogel, Gary Foster, Romain
-Francoise, Noah Friedman, Andreas Fuchs, Hallvard Furuseth, Keith
-Gabryelski, Peter S.@: Galbraith, Kevin Gallagher, Kevin Gallo, Juan
-Le@'{o}n Lahoz Garc@'{@dotless{i}}a, Howard Gayle, Stephen Gildea, Julien
-Gilles, David Gillespie, Bob Glickstein, Deepak Goel, Boris Goldowsky,
-Michelangelo Grigni, Odd Gripenstam, Kai Gro@ss{}johann, Michael
-Gschwind, Henry Guillaume, Doug Gwyn, Ken'ichi Handa, Lars Hansen,
-Chris Hanson, K. Shane Hartman, John Heidemann, Jon K.@: Hellan,
-Jesper Harder, Markus Heritsch, Karl Heuer, Manabu Higashida, Anders
-Holst, Jeffrey C.@: Honig, Kurt Hornik, Tom Houlder, Joakim Hove,
-Denis Howe, Lars Ingebrigtsen, Andrew Innes, Seiichiro Inoue, Pavel
-Janik, Paul Jarc, Ulf Jasper, Michael K. Johnson, Kyle Jones, Terry
-Jones, Simon Josefsson, Arne J@o{}rgensen, Tomoji Kagatani, Brewster
-Kahle, Lute Kamstra, David Kastrup, David Kaufman, Henry Kautz, Taichi
-Kawabata, Howard Kaye, Michael Kifer, Richard King, Peter Kleiweg,
-Shuhei Kobayashi, Pavel Kobiakov, Larry K.@: Kolodney, David M.@:
-Koppelman, Koseki Yoshinori, Robert Krawitz, Sebastian Kremer, Ryszard
-Kubiak, Geoff Kuenning, David K@aa{}gedal, Daniel LaLiberte, Mario
-Lang, Aaron Larson, James R.@: Larus, Vinicius Jose Latorre, Werner
-Lemberg, Frederic Lepied, Peter Liljenberg, Lars Lindberg, Chris
-Lindblad, Anders Lindgren, Thomas Link, Juri Linkov, Francis Litterio,
-Emilio C. Lopes, Dave Love, Sascha L@"{u}decke, Eric Ludlam,Alan
-Mackenzie, Christopher J.@: Madsen, Neil M.@: Mager, Ken Manheimer,
-Bill Mann, Brian Marick, Simon Marshall, Bengt Martensson, Charlie
-Martin, Thomas May, Roland McGrath, Will Mengarini, David Megginson,
-Ben A. Mesander, Wayne Mesard, Brad Miller, Lawrence Mitchell, Richard
-Mlynarik, Gerd Moellmann, Stefan Monnier, Morioka Tomohiko, Keith
-Moore, Glenn Morris, Diane Murray, Sen Nagata, Erik Naggum, Thomas
-Neumann, Thien-Thi Nguyen, Mike Newton, Jurgen Nickelsen, Dan
-Nicolaescu, Hrvoje Niksic, Jeff Norden, Andrew Norman, Alexandre
-Oliva, Bob Olson, Michael Olson, Takaaki Ota, Pieter E.@: J.@: Pareit,
-David Pearson, Jeff Peck, Damon Anton Permezel, Tom Perrine, William
-M.@: Perry, Per Persson, Jens Petersen, Daniel Pfeiffer, Richard L.@:
-Pieri, Fred Pierresteguy, Christian Plaunt, David Ponce, Francesco
-A.@: Potorti, Michael D. Prange, Mukesh Prasad, Ken Raeburn, Marko
-Rahamaa, Ashwin Ram, Eric S. Raymond, Paul Reilly, Edward M. Reingold,
-Alex Rezinsky, Rob Riepel, David Reitter, Nick Roberts, Roland B.@:
-Roberts, John Robinson, Danny Roozendaal, William Rosenblatt,
-Guillermo J.@: Rozas, Martin Rudalics, Ivar Rummelhoff, Jason Rumney,
-Wolfgang Rupprecht, Kevin Ryde, James B. Salem, Masahiko Sato, Jorgen
-Schaefer, Holger Schauer, William Schelter, Ralph Schleicher, Gregor
-Schmid, Michael Schmidt, Ronald S. Schnell, Philippe Schnoebelen, Jan
-Schormann, Alex Schroeder, Stephen Schoef, Raymond Scholz, Randal
-Schwartz, Oliver Seidel, Manuel Serrano, Hovav Shacham, Stanislav
-Shalunov, Marc Shapiro, Richard Sharman, Olin Shivers, Espen Skoglund,
-Rick Sladkey, Lynn Slater, Chris Smith, David Smith, Paul D.@: Smith,
-Andre Spiegel, Michael Staats, William Sommerfeld, Michael Staats,
-Reiner Steib, Sam Steingold, Ake Stenhoff, Peter Stephenson, Ken
-Stevens, Jonathan Stigelman, Martin Stjernholm, Kim F.@: Storm, Steve
-Strassman, Olaf Sylvester, Naoto Takahashi, Steven Tamm, Jean-Philippe
-Theberge, Jens T.@: Berger Thielemann, Spencer Thomas, Jim Thompson,
-Luc Teirlinck, Tom Tromey, Enami Tsugutomo, Eli Tziperman, Daiki Ueno,
-Masanobu Umeda, Rajesh Vaidheeswarran, Neil W.@: Van Dyke, Didier
-Verna, Ulrik Vieth, Geoffrey Voelker, Johan Vromans, Inge Wallin, John
-Paul Wallington, Colin Walters, Barry Warsaw, Morten Welinder, Joseph
-Brian Wells, Rodney Whitby, John Wiegley, Ed Wilkinson, Mike Williams,
-Bill Wohler, Steven A. Wood, Dale R.@: Worley, Francis J.@: Wright,
-Felix S. T. Wu, Tom Wurgler, Katsumi Yamaoka, Masatake Yamato,
-Jonathan Yavner, Ryan Yeske, Chong Yidong, Ilya Zakharevich, Milan
-Zamazal, Victor Zandy, Eli Zaretskii, Jamie Zawinski, Shenghuo Zhu,
-Ian T.@: Zimmermann, Reto Zimmermann, Neal Ziring, Teodor Zlatanov,
-and Detlev Zundel.
-@end iftex
-
-@node Intro, Glossary, Distrib, Top
-@unnumbered Introduction
-
- You are reading about GNU Emacs, the GNU incarnation of the
-advanced, self-documenting, customizable, extensible editor Emacs.
-(The `G' in `GNU' is not silent.)
-
- We call Emacs advanced because it provides much more than simple
-insertion and deletion. It can control subprocesses, indent programs
-automatically, show two or more files at once, and edit formatted
-text. Emacs editing commands operate in terms of characters, words,
-lines, sentences, paragraphs, and pages, as well as expressions and
-comments in various programming languages.
-
- @dfn{Self-documenting} means that at any time you can type a special
-character, @kbd{Control-h}, to find out what your options are. You can
-also use it to find out what any command does, or to find all the commands
-that pertain to a topic. @xref{Help}.
-
- @dfn{Customizable} means that you can alter Emacs commands' behavior
-in simple ways. For example, if you use a programming language in
-which comments start with @samp{<**} and end with @samp{**>}, you can
-tell the Emacs comment manipulation commands to use those strings
-(@pxref{Comments}). Another sort of customization is rearrangement of
-the command set. For example, you can rebind the basic cursor motion
-commands (up, down, left and right) to any keys on the keyboard that
-you find comfortable. @xref{Customization}.
-
- @dfn{Extensible} means that you can go beyond simple customization
-and write entirely new commands---programs in the Lisp language to be
-run by Emacs's own Lisp interpreter. Emacs is an ``on-line
-extensible'' system, which means that it is divided into many
-functions that call each other, any of which can be redefined in the
-middle of an editing session. Almost any part of Emacs can be
-replaced without making a separate copy of all of Emacs. Most of the
-editing commands of Emacs are written in Lisp; the few exceptions
-could have been written in Lisp but use C instead for efficiency.
-Writing an extension is programming, but non-programmers can use it
-afterwards. @xref{Top, Emacs Lisp Intro, Preface, eintr, An
-Introduction to Programming in Emacs Lisp}, if you want to learn Emacs
-Lisp programming.
-
- When running on a graphical display, Emacs provides its own menus
-and convenient handling of mouse buttons. In addition, Emacs provides
-many of the benefits of a graphical display even on a text-only
-terminal. For instance, it can highlight parts of a file, display and
-edit several files at once, move text between files, and edit files
-while running shell commands.
-
-@include screen.texi
-@include commands.texi
-@include entering.texi
-@include basic.texi
-@include mini.texi
-@include m-x.texi
-@include help.texi
-@include mark.texi
-@include killing.texi
-@include regs.texi
-@include display.texi
-@include search.texi
-@include fixit.texi
-@include kmacro.texi
-@include files.texi
-@include buffers.texi
-@include windows.texi
-@include frames.texi
-@include mule.texi
-@include major.texi
-@include indent.texi
-@include text.texi
-@include programs.texi
-@include building.texi
-@include maintaining.texi
-@include abbrevs.texi
-@ifnottex
-@include picture-xtra.texi
-@end ifnottex
-@include sending.texi
-@include rmail.texi
-@include dired.texi
-@include calendar.texi
-@include misc.texi
-@include custom.texi
-@include trouble.texi
-
-@node Copying, GNU Free Documentation License, Service, Top
-@appendix GNU GENERAL PUBLIC LICENSE
-@include gpl.texi
-
-@node GNU Free Documentation License, Emacs Invocation, Copying, Top
-@appendix GNU Free Documentation License
-@include doclicense.texi
-
-@include cmdargs.texi
-@include xresources.texi
-
-@include anti.texi
-@include macos.texi
-@include msdog.texi
-@include gnu.texi
-@include glossary.texi
-@ifnottex
-@include ack.texi
-@end ifnottex
-
-@c The Option Index is produced only in the on-line version,
-@c because the index entries related to command-line options
-@c tend to point to the same pages and all begin with a dash.
-@c This, and the need to keep the node links consistent, are
-@c the reasons for the funky @iftex/@ifnottex dance below.
-@c The Option Index is _not_ before Key Index, because that
-@c would require changes in the glossary.texi's @node line.
-@c It is not after Concept Index for similar reasons.
-
-@iftex
-@node Key Index, Command Index, Glossary, Top
-@unnumbered Key (Character) Index
-@printindex ky
-@end iftex
-
-@ifnottex
-@node Key Index, Option Index, Glossary, Top
-@unnumbered Key (Character) Index
-@printindex ky
-
-@node Option Index, Command Index, Key Index, Top
-@unnumbered Command-Line Options Index
-@printindex op
-
-@node Command Index, Variable Index, Option Index, Top
-@unnumbered Command and Function Index
-@printindex fn
-@end ifnottex
-
-@iftex
-@node Command Index, Variable Index, Key Index, Top
-@unnumbered Command and Function Index
-@printindex fn
-@end iftex
-
-@node Variable Index, Concept Index, Command Index, Top
-@unnumbered Variable Index
-@printindex vr
-
-@node Concept Index, Acknowledgments, Variable Index, Top
-@unnumbered Concept Index
-@printindex cp
-
-@bye
-
-@ignore
- arch-tag: ed48740a-410b-46ea-9387-c9a9252a3392
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@c
-@c This file is included either in emacs-xtra.texi (when producing the
-@c printed version) or in the main Emacs manual (for the on-line version).
-@node Emerge
-@section Merging Files with Emerge
-@cindex Emerge
-@cindex merging files
-
- It's not unusual for programmers to get their signals crossed and
-modify the same program in two different directions. To recover from
-this confusion, you need to merge the two versions. Emerge makes this
-easier. For other ways to compare files, see
-@iftex
-@ref{Comparing Files,,, emacs, the Emacs Manual},
-@end iftex
-@ifnottex
-@ref{Comparing Files},
-@end ifnottex
-and @ref{Top, Ediff,, ediff, The Ediff Manual}.
-
-@menu
-* Overview of Emerge:: How to start Emerge. Basic concepts.
-* Submodes of Emerge:: Fast mode vs. Edit mode.
- Skip Prefers mode and Auto Advance mode.
-* State of Difference:: You do the merge by specifying state A or B
- for each difference.
-* Merge Commands:: Commands for selecting a difference,
- changing states of differences, etc.
-* Exiting Emerge:: What to do when you've finished the merge.
-* Combining in Emerge:: How to keep both alternatives for a difference.
-* Fine Points of Emerge:: Misc.
-@end menu
-
-@node Overview of Emerge
-@subsection Overview of Emerge
-
- To start Emerge, run one of these four commands:
-
-@table @kbd
-@item M-x emerge-files
-@findex emerge-files
-Merge two specified files.
-
-@item M-x emerge-files-with-ancestor
-@findex emerge-files-with-ancestor
-Merge two specified files, with reference to a common ancestor.
-
-@item M-x emerge-buffers
-@findex emerge-buffers
-Merge two buffers.
-
-@item M-x emerge-buffers-with-ancestor
-@findex emerge-buffers-with-ancestor
-Merge two buffers with reference to a common ancestor in a third
-buffer.
-@end table
-
-@cindex merge buffer (Emerge)
-@cindex A and B buffers (Emerge)
- The Emerge commands compare two files or buffers, and display the
-comparison in three buffers: one for each input text (the @dfn{A buffer}
-and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
-takes place. The merge buffer shows the full merged text, not just the
-differences. Wherever the two input texts differ, you can choose which
-one of them to include in the merge buffer.
-
- The Emerge commands that take input from existing buffers use only
-the accessible portions of those buffers, if they are narrowed.
-@iftex
-@xref{Narrowing,,, emacs, the Emacs Manual}.
-@end iftex
-@ifnottex
-@xref{Narrowing}.
-@end ifnottex
-
-
- If a common ancestor version is available, from which the two texts to
-be merged were both derived, Emerge can use it to guess which
-alternative is right. Wherever one current version agrees with the
-ancestor, Emerge presumes that the other current version is a deliberate
-change which should be kept in the merged version. Use the
-@samp{with-ancestor} commands if you want to specify a common ancestor
-text. These commands read three file or buffer names---variant A,
-variant B, and the common ancestor.
-
- After the comparison is done and the buffers are prepared, the
-interactive merging starts. You control the merging by typing special
-@dfn{merge commands} in the merge buffer (@pxref{Merge Commands}).
-For each run of differences between the input texts, you can choose
-which one of them to keep, or edit them both together.
-
- The merge buffer uses a special major mode, Emerge mode, with commands
-for making these choices. But you can also edit the buffer with
-ordinary Emacs commands.
-
- At any given time, the attention of Emerge is focused on one
-particular difference, called the @dfn{selected} difference. This
-difference is marked off in the three buffers like this:
-
-@example
-vvvvvvvvvvvvvvvvvvvv
-@var{text that differs}
-^^^^^^^^^^^^^^^^^^^^
-@end example
-
-@noindent
-Emerge numbers all the differences sequentially and the mode
-line always shows the number of the selected difference.
-
- Normally, the merge buffer starts out with the A version of the text.
-But when the A version of a difference agrees with the common ancestor,
-then the B version is initially preferred for that difference.
-
- Emerge leaves the merged text in the merge buffer when you exit. At
-that point, you can save it in a file with @kbd{C-x C-w}. If you give a
-numeric argument to @code{emerge-files} or
-@code{emerge-files-with-ancestor}, it reads the name of the output file
-using the minibuffer. (This is the last file name those commands read.)
-Then exiting from Emerge saves the merged text in the output file.
-
- Normally, Emerge commands save the output buffer in its file when you
-exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not
-save the output buffer, but you can save it yourself if you wish.
-
-@node Submodes of Emerge
-@subsection Submodes of Emerge
-
- You can choose between two modes for giving merge commands: Fast mode
-and Edit mode. In Fast mode, basic merge commands are single
-characters, but ordinary Emacs commands are disabled. This is
-convenient if you use only merge commands. In Edit mode, all merge
-commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
-commands are also available. This allows editing the merge buffer, but
-slows down Emerge operations.
-
- Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
-Fast mode. The mode line indicates Edit and Fast modes with @samp{E}
-and @samp{F}.
-
- Emerge has two additional submodes that affect how particular merge
-commands work: Auto Advance mode and Skip Prefers mode.
-
- If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
-advance to the next difference. This lets you go through the merge
-faster as long as you simply choose one of the alternatives from the
-input. The mode line indicates Auto Advance mode with @samp{A}.
-
- If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
-skip over differences in states prefer-A and prefer-B (@pxref{State of
-Difference}). Thus you see only differences for which neither version
-is presumed ``correct.'' The mode line indicates Skip Prefers mode with
-@samp{S}.
-
-@findex emerge-auto-advance-mode
-@findex emerge-skip-prefers-mode
- Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
-clear Auto Advance mode. Use @kbd{s s}
-(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
-These commands turn on the mode with a positive argument, turns it off
-with a negative or zero argument, and toggle the mode with no argument.
-
-@node State of Difference
-@subsection State of a Difference
-
- In the merge buffer, a difference is marked with lines of @samp{v} and
-@samp{^} characters. Each difference has one of these seven states:
-
-@table @asis
-@item A
-The difference is showing the A version. The @kbd{a} command always
-produces this state; the mode line indicates it with @samp{A}.
-
-@item B
-The difference is showing the B version. The @kbd{b} command always
-produces this state; the mode line indicates it with @samp{B}.
-
-@item default-A
-@itemx default-B
-The difference is showing the A or the B state by default, because you
-haven't made a choice. All differences start in the default-A state
-(and thus the merge buffer is a copy of the A buffer), except those for
-which one alternative is ``preferred'' (see below).
-
-When you select a difference, its state changes from default-A or
-default-B to plain A or B. Thus, the selected difference never has
-state default-A or default-B, and these states are never displayed in
-the mode line.
-
-The command @kbd{d a} chooses default-A as the default state, and @kbd{d
-b} chooses default-B. This chosen default applies to all differences
-which you haven't ever selected and for which no alternative is preferred.
-If you are moving through the merge sequentially, the differences you
-haven't selected are those following the selected one. Thus, while
-moving sequentially, you can effectively make the A version the default
-for some sections of the merge buffer and the B version the default for
-others by using @kbd{d a} and @kbd{d b} between sections.
-
-@item prefer-A
-@itemx prefer-B
-The difference is showing the A or B state because it is
-@dfn{preferred}. This means that you haven't made an explicit choice,
-but one alternative seems likely to be right because the other
-alternative agrees with the common ancestor. Thus, where the A buffer
-agrees with the common ancestor, the B version is preferred, because
-chances are it is the one that was actually changed.
-
-These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
-
-@item combined
-The difference is showing a combination of the A and B states, as a
-result of the @kbd{x c} or @kbd{x C} commands.
-
-Once a difference is in this state, the @kbd{a} and @kbd{b} commands
-don't do anything to it unless you give them a numeric argument.
-
-The mode line displays this state as @samp{comb}.
-@end table
-
-@node Merge Commands
-@subsection Merge Commands
-
- Here are the Merge commands for Fast mode; in Edit mode, precede them
-with @kbd{C-c C-c}:
-
-@table @kbd
-@item p
-Select the previous difference.
-
-@item n
-Select the next difference.
-
-@item a
-Choose the A version of this difference.
-
-@item b
-Choose the B version of this difference.
-
-@item C-u @var{n} j
-Select difference number @var{n}.
-
-@item .
-Select the difference containing point. You can use this command in the
-merge buffer or in the A or B buffer.
-
-@item q
-Quit---finish the merge.
-
-@item C-]
-Abort---exit merging and do not save the output.
-
-@item f
-Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.)
-
-@item e
-Go into Edit mode.
-
-@item l
-Recenter (like @kbd{C-l}) all three windows.
-
-@item -
-Specify part of a prefix numeric argument.
-
-@item @var{digit}
-Also specify part of a prefix numeric argument.
-
-@item d a
-Choose the A version as the default from here down in
-the merge buffer.
-
-@item d b
-Choose the B version as the default from here down in
-the merge buffer.
-
-@item c a
-Copy the A version of this difference into the kill ring.
-
-@item c b
-Copy the B version of this difference into the kill ring.
-
-@item i a
-Insert the A version of this difference at point.
-
-@item i b
-Insert the B version of this difference at point.
-
-@item m
-Put point and mark around the difference.
-
-@item ^
-Scroll all three windows down (like @kbd{M-v}).
-
-@item v
-Scroll all three windows up (like @kbd{C-v}).
-
-@item <
-Scroll all three windows left (like @kbd{C-x <}).
-
-@item >
-Scroll all three windows right (like @kbd{C-x >}).
-
-@item |
-Reset horizontal scroll on all three windows.
-
-@item x 1
-Shrink the merge window to one line. (Use @kbd{C-u l} to restore it
-to full size.)
-
-@item x c
-Combine the two versions of this difference (@pxref{Combining in
-Emerge}).
-
-@item x f
-Show the names of the files/buffers Emerge is operating on, in a Help
-window. (Use @kbd{C-u l} to restore windows.)
-
-@item x j
-Join this difference with the following one.
-(@kbd{C-u x j} joins this difference with the previous one.)
-
-@item x s
-Split this difference into two differences. Before you use this
-command, position point in each of the three buffers at the place where
-you want to split the difference.
-
-@item x t
-Trim identical lines off the top and bottom of the difference.
-Such lines occur when the A and B versions are
-identical but differ from the ancestor version.
-@end table
-
-@node Exiting Emerge
-@subsection Exiting Emerge
-
- The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
-the results into the output file if you specified one. It restores the
-A and B buffers to their proper contents, or kills them if they were
-created by Emerge and you haven't changed them. It also disables the
-Emerge commands in the merge buffer, since executing them later could
-damage the contents of the various buffers.
-
- @kbd{C-]} aborts the merge. This means exiting without writing the
-output file. If you didn't specify an output file, then there is no
-real difference between aborting and finishing the merge.
-
- If the Emerge command was called from another Lisp program, then its
-return value is @code{t} for successful completion, or @code{nil} if you
-abort.
-
-@node Combining in Emerge
-@subsection Combining the Two Versions
-
- Sometimes you want to keep @emph{both} alternatives for a particular
-difference. To do this, use @kbd{x c}, which edits the merge buffer
-like this:
-
-@example
-@group
-#ifdef NEW
-@var{version from A buffer}
-#else /* not NEW */
-@var{version from B buffer}
-#endif /* not NEW */
-@end group
-@end example
-
-@noindent
-@vindex emerge-combine-versions-template
-While this example shows C preprocessor conditionals delimiting the two
-alternative versions, you can specify the strings to use by setting
-the variable @code{emerge-combine-versions-template} to a string of your
-choice. In the string, @samp{%a} says where to put version A, and
-@samp{%b} says where to put version B. The default setting, which
-produces the results shown above, looks like this:
-
-@example
-@group
-"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
-@end group
-@end example
-
-@node Fine Points of Emerge
-@subsection Fine Points of Emerge
-
- During the merge, you mustn't try to edit the A and B buffers yourself.
-Emerge modifies them temporarily, but ultimately puts them back the way
-they were.
-
- You can have any number of merges going at once---just don't use any one
-buffer as input to more than one merge at once, since the temporary
-changes made in these buffers would get in each other's way.
-
- Starting Emerge can take a long time because it needs to compare the
-files fully. Emacs can't do anything else until @code{diff} finishes.
-Perhaps in the future someone will change Emerge to do the comparison in
-the background when the input files are large---then you could keep on
-doing other things with Emacs until Emerge is ready to accept
-commands.
-
-@vindex emerge-startup-hook
- After setting up the merge, Emerge runs the hook
-@code{emerge-startup-hook}.
-@iftex
-@xref{Hooks,,, emacs, the Emacs Manual}.
-@end iftex
-@ifnottex
-@xref{Hooks}.
-@end ifnottex
-
-@ignore
- arch-tag: cda63f09-9c5f-4ea1-adb9-4a820fdfb24e
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 2001, 2002, 2003,
-@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Entering Emacs, Exiting, Text Characters, Top
-@chapter Entering and Exiting Emacs
-@cindex entering Emacs
-@cindex starting Emacs
-
- The usual way to invoke Emacs is with the shell command
-@command{emacs}. Emacs clears the screen, then displays an initial
-help message and copyright notice. Some operating systems discard
-your type-ahead when Emacs starts up; they give Emacs no way to
-prevent this. On those systems, wait for Emacs to clear the screen
-before you start typing.
-
- From a shell window under the X Window System, run Emacs in the
-background with @command{emacs&}. This way, Emacs won't tie up the
-shell window, so you can use it to run other shell commands while
-Emacs is running. You can type Emacs commands as soon as you direct
-your keyboard input to an Emacs frame.
-
-@vindex initial-major-mode
- When Emacs starts up, it creates a buffer named @samp{*scratch*}.
-That's the buffer you start out in. The @samp{*scratch*} buffer uses
-Lisp Interaction mode; you can use it to type Lisp expressions and
-evaluate them. You can also ignore that capability and just write notes
-there. You can specify a different major mode for this buffer by
-setting the variable @code{initial-major-mode} in your init file.
-@xref{Init File}.
-
- It is possible to specify files to be visited, Lisp files to be
-loaded, and functions to be called through Emacs command-line
-arguments. @xref{Emacs Invocation}. The feature exists mainly for
-compatibility with other editors, and for scripts.
-
- Many editors are designed to edit one file. When done with that
-file, you exit the editor. The next time you want to edit a file, you
-must start the editor again. Working this way, it is convenient to
-use a command-line argument to say which file to edit.
-
- However, killing Emacs after editing one each and starting it afresh
-for the next file is both unnecessary and harmful, since it denies you
-the full power of Emacs. Emacs can visit more than one file in a
-single editing session, and that is the right way to use it. Exiting
-the Emacs session loses valuable accumulated context, such as the kill
-ring, registers, undo history, and mark ring. These features are
-useful for operating on multiple files, or even continuing to edit one
-file. If you kill Emacs after each file, you don't take advantage of
-them.
-
- The recommended way to use GNU Emacs is to start it only once, just
-after you log in, and do all your editing in the same Emacs session.
-Each time you edit a file, you visit it with the existing Emacs, which
-eventually has many files in it ready for editing. Usually you do not
-kill Emacs until you are about to log out. @xref{Files}, for more
-information on visiting more than one file.
-
- To edit a file from another program while Emacs is running, you can
-use the @command{emacsclient} helper program to open a file in the
-already running Emacs. @xref{Emacs Server}.
-
-@ifnottex
-@raisesections
-@end ifnottex
-
-@node Exiting, Basic, Entering Emacs, Top
-@section Exiting Emacs
-@cindex exiting
-@cindex killing Emacs
-@cindex suspending
-@cindex leaving Emacs
-@cindex quitting Emacs
-
- There are two commands for exiting Emacs, and three kinds of
-exiting: @dfn{iconifying} Emacs, @dfn{suspending} Emacs, and
-@dfn{killing} Emacs.
-
- @dfn{Iconifying} means replacing the Emacs frame with a small box or
-``icon'' on the screen. This is the usual way to exit Emacs when
-you're using a graphical display---if you bother to ``exit'' at all.
-(Just switching to another application is usually sufficient.)
-
- @dfn{Suspending} means stopping Emacs temporarily and returning
-control to its parent process (usually a shell), allowing you to
-resume editing later in the same Emacs job. This is the usual way to
-exit Emacs when running it on a text terminal.
-
- @dfn{Killing} Emacs means destroying the Emacs job. You can run Emacs
-again later, but you will get a fresh Emacs; there is no way to resume
-the same editing session after it has been killed.
-
-@table @kbd
-@item C-z
-Suspend Emacs (@code{suspend-emacs}) or iconify a frame
-(@code{iconify-or-deiconify-frame}).
-@item C-x C-c
-Kill Emacs (@code{save-buffers-kill-emacs}).
-@end table
-
-@kindex C-z
-@findex iconify-or-deiconify-frame
- On graphical displays, @kbd{C-z} runs the command
-@code{iconify-or-deiconify-frame}, which temporarily iconifies (or
-``minimizes'') the selected Emacs frame (@pxref{Frames}). You can
-then use the window manager to select some other application. (You
-could select another application without iconifying Emacs first, but
-getting the Emacs frame out of the way can make it more convenient to
-find the other application.)
-
-@findex suspend-emacs
- On a text terminal, @kbd{C-z} runs the command @code{suspend-emacs}.
-Suspending Emacs takes you back to the shell from which you invoked
-Emacs. You can resume Emacs with the shell command @command{%emacs}
-in most common shells. On systems that don't support suspending
-programs, @kbd{C-z} starts an inferior shell that communicates
-directly with the terminal, and Emacs waits until you exit the
-subshell. (The way to do that is probably with @kbd{C-d} or
-@command{exit}, but it depends on which shell you use.) On these
-systems, you can only get back to the shell from which Emacs was run
-(to log out, for example) when you kill Emacs.
-
-@vindex cannot-suspend
- Suspending can fail if you run Emacs under a shell that doesn't
-support suspendion of its subjobs, even if the system itself does
-support it. In such a case, you can set the variable
-@code{cannot-suspend} to a non-@code{nil} value to force @kbd{C-z} to
-start an inferior shell.
-
-@kindex C-x C-c
-@findex save-buffers-kill-emacs
- To exit and kill Emacs, type @kbd{C-x C-c}
-(@code{save-buffers-kill-emacs}). A two-character key is used to make
-it harder to type by accident. This command first offers to save any
-modified file-visiting buffers. If you do not save them all, it asks
-for confirmation with @kbd{yes} before killing Emacs, since any
-changes not saved now will be lost forever. Also, if any subprocesses are
-still running, @kbd{C-x C-c} asks for confirmation about them, since
-killing Emacs will also kill the subprocesses.
-
-@vindex confirm-kill-emacs
- If the value of the variable @code{confirm-kill-emacs} is
-non-@code{nil}, @kbd{C-x C-c} assumes that its value is a predicate
-function, and calls that function. If the result is non-@code{nil}, the
-session is killed, otherwise Emacs continues to run. One convenient
-function to use as the value of @code{confirm-kill-emacs} is the
-function @code{yes-or-no-p}. The default value of
-@code{confirm-kill-emacs} is @code{nil}.
-
- You can't resume an Emacs session after killing it. Emacs can,
-however, record certain session information when you kill it, such as
-which files you visited, so the next time you start Emacs it will try
-to visit the same files. @xref{Saving Emacs Sessions}.
-
- The operating system usually listens for certain special characters
-whose meaning is to kill or suspend the program you are running.
-@b{This operating system feature is turned off while you are in Emacs.}
-The meanings of @kbd{C-z} and @kbd{C-x C-c} as keys in Emacs were
-inspired by the use of @kbd{C-z} and @kbd{C-c} on several operating
-systems as the characters for stopping or killing a program, but that is
-their only relationship with the operating system. You can customize
-these keys to run any commands of your choice (@pxref{Keymaps}).
-
-@ifnottex
-@lowersections
-@end ifnottex
-
-@ignore
- arch-tag: df798d8b-f253-4113-b585-f528f078a944
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Files, Buffers, Keyboard Macros, Top
-@chapter File Handling
-@cindex files
-
- The operating system stores data permanently in named @dfn{files}, so
-most of the text you edit with Emacs comes from a file and is ultimately
-stored in a file.
-
- To edit a file, you must tell Emacs to read the file and prepare a
-buffer containing a copy of the file's text. This is called
-@dfn{visiting} the file. Editing commands apply directly to text in the
-buffer; that is, to the copy inside Emacs. Your changes appear in the
-file itself only when you @dfn{save} the buffer back into the file.
-
- In addition to visiting and saving files, Emacs can delete, copy,
-rename, and append to files, keep multiple versions of them, and operate
-on file directories.
-
-@menu
-* File Names:: How to type and edit file-name arguments.
-* Visiting:: Visiting a file prepares Emacs to edit the file.
-* Saving:: Saving makes your changes permanent.
-* Reverting:: Reverting cancels all the changes not saved.
-@ifnottex
-* Autorevert:: Auto Reverting non-file buffers.
-@end ifnottex
-* Auto Save:: Auto Save periodically protects against loss of data.
-* File Aliases:: Handling multiple names for one file.
-* Version Control:: Version control systems (RCS, CVS and SCCS).
-* Directories:: Creating, deleting, and listing file directories.
-* Comparing Files:: Finding where two files differ.
-* Diff Mode:: Mode for editing file differences.
-* Misc File Ops:: Other things you can do on files.
-* Compressed Files:: Accessing compressed files.
-* File Archives:: Operating on tar, zip, jar etc. archive files.
-* Remote Files:: Accessing files on other sites.
-* Quoted File Names:: Quoting special characters in file names.
-* File Name Cache:: Completion against a list of files you often use.
-* File Conveniences:: Convenience Features for Finding Files.
-* Filesets:: Handling sets of files.
-@end menu
-
-@node File Names
-@section File Names
-@cindex file names
-
- Most Emacs commands that operate on a file require you to specify the
-file name. (Saving and reverting are exceptions; the buffer knows which
-file name to use for them.) You enter the file name using the
-minibuffer (@pxref{Minibuffer}). @dfn{Completion} is available
-(@pxref{Completion}) to make it easier to specify long file names. When
-completing file names, Emacs ignores those whose file-name extensions
-appear in the variable @code{completion-ignored-extensions}; see
-@ref{Completion Options}.
-
- For most operations, there is a @dfn{default file name} which is used
-if you type just @key{RET} to enter an empty argument. Normally the
-default file name is the name of the file visited in the current buffer;
-this makes it easy to operate on that file with any of the Emacs file
-commands.
-
-@vindex default-directory
- Each buffer has a default directory which is normally the same as the
-directory of the file visited in that buffer. When you enter a file
-name without a directory, the default directory is used. If you specify
-a directory in a relative fashion, with a name that does not start with
-a slash, it is interpreted with respect to the default directory. The
-default directory is kept in the variable @code{default-directory},
-which has a separate value in every buffer.
-
-@findex cd
-@findex pwd
- The command @kbd{M-x pwd} displays the current buffer's default
-directory, and the command @kbd{M-x cd} sets it (to a value read using
-the minibuffer). A buffer's default directory changes only when the
-@code{cd} command is used. A file-visiting buffer's default directory
-is initialized to the directory of the file it visits. If you create
-a buffer with @kbd{C-x b}, its default directory is copied from that
-of the buffer that was current at the time.
-
- For example, if the default file name is @file{/u/rms/gnu/gnu.tasks}
-then the default directory is normally @file{/u/rms/gnu/}. If you
-type just @samp{foo}, which does not specify a directory, it is short
-for @file{/u/rms/gnu/foo}. @samp{../.login} would stand for
-@file{/u/rms/.login}. @samp{new/foo} would stand for the file name
-@file{/u/rms/gnu/new/foo}.
-
-@vindex insert-default-directory
- The default directory actually appears in the minibuffer when the
-minibuffer becomes active to read a file name. This serves two
-purposes: it @emph{shows} you what the default is, so that you can type
-a relative file name and know with certainty what it will mean, and it
-allows you to @emph{edit} the default to specify a different directory.
-This insertion of the default directory is inhibited if the variable
-@code{insert-default-directory} is set to @code{nil}.
-
- Note that it is legitimate to type an absolute file name after you
-enter the minibuffer, ignoring the presence of the default directory
-name as part of the text. The final minibuffer contents may look
-invalid, but that is not so. For example, if the minibuffer starts out
-with @samp{/usr/tmp/} and you add @samp{/x1/rms/foo}, you get
-@samp{/usr/tmp//x1/rms/foo}; but Emacs ignores everything through the
-first slash in the double slash; the result is @samp{/x1/rms/foo}.
-@xref{Minibuffer File}.
-
-@cindex home directory shorthand
- You can use @file{~/} in a file name to mean your home directory,
-or @file{~@var{user-id}/} to mean the home directory of a user whose
-login name is @code{user-id}@footnote{
-On MS-Windows and MS-DOS systems, where a user doesn't have a home
-directory, Emacs replaces @file{~/} with the value of the
-environment variable @code{HOME}; see @ref{General Variables}. On
-these systems, the @file{~@var{user-id}/} construct is supported only
-for the current user, i.e., only if @var{user-id} is the current
-user's login name.}.
-
-@cindex environment variables in file names
-@cindex expansion of environment variables
-@cindex @code{$} in file names
- @anchor{File Names with $}@samp{$} in a file name is used to
-substitute an environment variable. The environment variable name
-consists of all the alphanumeric characters after the @samp{$};
-alternatively, it can be enclosed in braces after the @samp{$}. For
-example, if you have used the shell command @command{export
-FOO=rms/hacks} to set up an environment variable named @env{FOO}, then
-you can use @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an
-abbreviation for @file{/u/rms/hacks/test.c}. If the environment
-variable is not defined, no substitution occurs: @file{/u/$notdefined}
-stands for itself (assuming the environment variable @env{notdefined}
-is not defined).
-
- Note that shell commands to set environment variables affect Emacs
-only when done before Emacs is started.
-
- To access a file with @samp{$} in its name, if the @samp{$} causes
-expansion, type @samp{$$}. This pair is converted to a single
-@samp{$} at the same time as variable substitution is performed for a
-single @samp{$}. Alternatively, quote the whole file name with
-@samp{/:} (@pxref{Quoted File Names}). File names which begin with a
-literal @samp{~} should also be quoted with @samp{/:}.
-
-@findex substitute-in-file-name
- The Lisp function that performs the @samp{$}-substitution is called
-@code{substitute-in-file-name}. The substitution is performed only on
-file names read as such using the minibuffer.
-
- You can include non-@acronym{ASCII} characters in file names if you set the
-variable @code{file-name-coding-system} to a non-@code{nil} value.
-@xref{File Name Coding}.
-
-@node Visiting
-@section Visiting Files
-@cindex visiting files
-@cindex open file
-
-@table @kbd
-@item C-x C-f
-Visit a file (@code{find-file}).
-@item C-x C-r
-Visit a file for viewing, without allowing changes to it
-(@code{find-file-read-only}).
-@item C-x C-v
-Visit a different file instead of the one visited last
-(@code{find-alternate-file}).
-@item C-x 4 f
-Visit a file, in another window (@code{find-file-other-window}). Don't
-alter what is displayed in the selected window.
-@item C-x 5 f
-Visit a file, in a new frame (@code{find-file-other-frame}). Don't
-alter what is displayed in the selected frame.
-@item M-x find-file-literally
-Visit a file with no conversion of the contents.
-@end table
-
-@cindex files, visiting and saving
-@cindex saving files
- @dfn{Visiting} a file means reading its contents into an Emacs
-buffer so you can edit them. Emacs makes a new buffer for each file
-that you visit. We often say that this buffer ``is visiting'' that
-file, or that the buffer's ``visited file'' is that file. Emacs
-constructs the buffer name from the file name by throwing away the
-directory, keeping just the name proper. For example, a file named
-@file{/usr/rms/emacs.tex} would get a buffer named @samp{emacs.tex}.
-If there is already a buffer with that name, Emacs constructs a unique
-name---the normal method is to append @samp{<2>}, @samp{<3>}, and so
-on, but you can select other methods (@pxref{Uniquify}).
-
- Each window's mode line shows the name of the buffer that is being displayed
-in that window, so you can always tell what buffer you are editing.
-
- The changes you make with editing commands are made in the Emacs
-buffer. They do not take effect in the file that you visited, or any
-permanent place, until you @dfn{save} the buffer. Saving the buffer
-means that Emacs writes the current contents of the buffer into its
-visited file. @xref{Saving}.
-
-@cindex modified (buffer)
- If a buffer contains changes that have not been saved, we say the
-buffer is @dfn{modified}. This is important because it implies that
-some changes will be lost if the buffer is not saved. The mode line
-displays two stars near the left margin to indicate that the buffer is
-modified.
-
-@kindex C-x C-f
-@findex find-file
- To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow
-the command with the name of the file you wish to visit, terminated by a
-@key{RET}.
-
- The file name is read using the minibuffer (@pxref{Minibuffer}), with
-defaulting and completion in the standard manner (@pxref{File Names}).
-While in the minibuffer, you can abort @kbd{C-x C-f} by typing
-@kbd{C-g}. File-name completion ignores certain file names; for more
-about this, see @ref{Completion Options}.
-
- Your confirmation that @kbd{C-x C-f} has completed successfully is
-the appearance of new text on the screen and a new buffer name in the
-mode line. If the specified file does not exist and you could not
-create it, or exists but you can't read it, then you get an error,
-with an error message displayed in the echo area.
-
- If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make
-another copy. It selects the existing buffer containing that file.
-However, before doing so, it checks whether the file itself has changed
-since you visited or saved it last. If the file has changed, Emacs offers
-to reread it.
-
-@vindex large-file-warning-threshold
-@cindex maximum buffer size exceeded, error message
- If you try to visit a file larger than
-@code{large-file-warning-threshold} (the default is 10000000, which is
-about 10 megabytes), Emacs will ask you for confirmation first. You
-can answer @kbd{y} to proceed with visiting the file. Note, however,
-that Emacs cannot visit files that are larger than the maximum Emacs
-buffer size, which is around 256 megabytes on 32-bit machines
-(@pxref{Buffers}). If you try, Emacs will display an error message
-saying that the maximum buffer size has been exceeded.
-
-@cindex file selection dialog
- On graphical displays there are two additional methods for
-visiting files. Firstly, when Emacs is built with a suitable GUI
-toolkit, commands invoked with the mouse (by clicking on the menu bar
-or tool bar) use the toolkit's standard File Selection dialog instead
-of prompting for the file name in the minibuffer. On Unix and
-GNU/Linux platforms, Emacs does that when built with GTK, LessTif, and
-Motif toolkits; on MS-Windows and Mac, the GUI version does that by default.
-For information on how to customize this, see @ref{Dialog Boxes}.
-
- Secondly, Emacs supports ``drag and drop''; dropping a file into an
-ordinary Emacs window visits the file using that window. However,
-dropping a file into a window displaying a Dired buffer moves or
-copies the file into the displayed directory. For details, see
-@ref{Drag and Drop}, and @ref{Misc Dired Features}.
-
-@cindex creating files
- What if you want to create a new file? Just visit it. Emacs displays
-@samp{(New file)} in the echo area, but in other respects behaves as if
-you had visited an existing empty file. If you make any changes and
-save them, the file is created.
-
- Emacs recognizes from the contents of a file which end-of-line
-convention it uses to separate lines---newline (used on GNU/Linux and
-on Unix), carriage-return linefeed (used on Microsoft systems), or
-just carriage-return (used on the Macintosh)---and automatically
-converts the contents to the normal Emacs convention, which is that
-the newline character separates lines. This is a part of the general
-feature of coding system conversion (@pxref{Coding Systems}), and
-makes it possible to edit files imported from different operating
-systems with equal convenience. If you change the text and save the
-file, Emacs performs the inverse conversion, changing newlines back
-into carriage-return linefeed or just carriage-return if appropriate.
-
-@vindex find-file-run-dired
- If the file you specify is actually a directory, @kbd{C-x C-f} invokes
-Dired, the Emacs directory browser, so that you can ``edit'' the contents
-of the directory (@pxref{Dired}). Dired is a convenient way to view, delete,
-or operate on the files in the directory. However, if the variable
-@code{find-file-run-dired} is @code{nil}, then it is an error to try
-to visit a directory.
-
- Files which are actually collections of other files, or @dfn{file
-archives}, are visited in special modes which invoke a Dired-like
-environment to allow operations on archive members. @xref{File
-Archives}, for more about these features.
-
-@cindex wildcard characters in file names
-@vindex find-file-wildcards
- If the file name you specify contains shell-style wildcard
-characters, Emacs visits all the files that match it. (On
-case-insensitive filesystems, Emacs matches the wildcards disregarding
-the letter case.) Wildcards include @samp{?}, @samp{*}, and
-@samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file
-name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted
-File Names}, for information on how to visit a file whose name
-actually contains wildcard characters. You can disable the wildcard
-feature by customizing @code{find-file-wildcards}.
-
- If you visit a file that the operating system won't let you modify,
-or that is marked read-only, Emacs makes the buffer read-only too, so
-that you won't go ahead and make changes that you'll have trouble
-saving afterward. You can make the buffer writable with @kbd{C-x C-q}
-(@code{toggle-read-only}). @xref{Misc Buffer}.
-
-@kindex C-x C-r
-@findex find-file-read-only
- If you want to visit a file as read-only in order to protect
-yourself from entering changes accidentally, visit it with the command
-@kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}.
-
-@kindex C-x C-v
-@findex find-alternate-file
- If you visit a nonexistent file unintentionally (because you typed the
-wrong file name), use the @kbd{C-x C-v} command
-(@code{find-alternate-file}) to visit the file you really wanted.
-@kbd{C-x C-v} is similar to @kbd{C-x C-f}, but it kills the current
-buffer (after first offering to save it if it is modified). When
-@kbd{C-x C-v} reads the file name to visit, it inserts the entire
-default file name in the buffer, with point just after the directory
-part; this is convenient if you made a slight error in typing the name.
-
-@kindex C-x 4 f
-@findex find-file-other-window
- @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
-except that the buffer containing the specified file is selected in another
-window. The window that was selected before @kbd{C-x 4 f} continues to
-show the same buffer it was already showing. If this command is used when
-only one window is being displayed, that window is split in two, with one
-window showing the same buffer as before, and the other one showing the
-newly requested file. @xref{Windows}.
-
-@kindex C-x 5 f
-@findex find-file-other-frame
- @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a
-new frame, or makes visible any existing frame showing the file you
-seek. This feature is available only when you are using a window
-system. @xref{Frames}.
-
-@findex find-file-literally
- If you wish to edit a file as a sequence of @acronym{ASCII} characters with no special
-encoding or conversion, use the @kbd{M-x find-file-literally} command.
-It visits a file, like @kbd{C-x C-f}, but does not do format conversion
-(@pxref{Formatted Text}), character code conversion (@pxref{Coding
-Systems}), or automatic uncompression (@pxref{Compressed Files}), and
-does not add a final newline because of @code{require-final-newline}.
-If you already have visited the same file in the usual (non-literal)
-manner, this command asks you whether to visit it literally instead.
-
-@vindex find-file-hook
-@vindex find-file-not-found-functions
- Two special hook variables allow extensions to modify the operation of
-visiting files. Visiting a file that does not exist runs the functions
-in the list @code{find-file-not-found-functions}; this variable holds a list
-of functions, and the functions are called one by one (with no
-arguments) until one of them returns non-@code{nil}. This is not a
-normal hook, and the name ends in @samp{-functions} rather than @samp{-hook}
-to indicate that fact.
-
- Successful visiting of any file, whether existing or not, calls the
-functions in the list @code{find-file-hook}, with no arguments.
-This variable is a normal hook. In the case of a nonexistent file, the
-@code{find-file-not-found-functions} are run first. @xref{Hooks}.
-
- There are several ways to specify automatically the major mode for
-editing the file (@pxref{Choosing Modes}), and to specify local
-variables defined for that file (@pxref{File Variables}).
-
-@node Saving
-@section Saving Files
-
- @dfn{Saving} a buffer in Emacs means writing its contents back into the file
-that was visited in the buffer.
-
-@menu
-* Save Commands:: Commands for saving files.
-* Backup:: How Emacs saves the old version of your file.
-* Customize Save:: Customizing the saving of files.
-* Interlocking:: How Emacs protects against simultaneous editing
- of one file by two users.
-* Shadowing: File Shadowing. Copying files to "shadows" automatically.
-* Time Stamps:: Emacs can update time stamps on saved files.
-@end menu
-
-@node Save Commands
-@subsection Commands for Saving Files
-
- These are the commands that relate to saving and writing files.
-
-@table @kbd
-@item C-x C-s
-Save the current buffer in its visited file on disk (@code{save-buffer}).
-@item C-x s
-Save any or all buffers in their visited files (@code{save-some-buffers}).
-@item M-~
-Forget that the current buffer has been changed (@code{not-modified}).
-With prefix argument (@kbd{C-u}), mark the current buffer as changed.
-@item C-x C-w
-Save the current buffer with a specified file name (@code{write-file}).
-@item M-x set-visited-file-name
-Change the file name under which the current buffer will be saved.
-@end table
-
-@kindex C-x C-s
-@findex save-buffer
- When you wish to save the file and make your changes permanent, type
-@kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s}
-displays a message like this:
-
-@example
-Wrote /u/rms/gnu/gnu.tasks
-@end example
-
-@noindent
-If the selected buffer is not modified (no changes have been made in it
-since the buffer was created or last saved), saving is not really done,
-because it would have no effect. Instead, @kbd{C-x C-s} displays a message
-like this in the echo area:
-
-@example
-(No changes need to be saved)
-@end example
-
-@kindex C-x s
-@findex save-some-buffers
- The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any
-or all modified buffers. It asks you what to do with each buffer. The
-possible responses are analogous to those of @code{query-replace}:
-
-@table @kbd
-@item y
-Save this buffer and ask about the rest of the buffers.
-@item n
-Don't save this buffer, but ask about the rest of the buffers.
-@item !
-Save this buffer and all the rest with no more questions.
-@c following generates acceptable underfull hbox
-@item @key{RET}
-Terminate @code{save-some-buffers} without any more saving.
-@item .
-Save this buffer, then exit @code{save-some-buffers} without even asking
-about other buffers.
-@item C-r
-View the buffer that you are currently being asked about. When you exit
-View mode, you get back to @code{save-some-buffers}, which asks the
-question again.
-@item d
-Diff the buffer against its corresponding file, so you can see
-what changes you would be saving.
-@item C-h
-Display a help message about these options.
-@end table
-
- @kbd{C-x C-c}, the key sequence to exit Emacs, invokes
-@code{save-some-buffers} and therefore asks the same questions.
-
-@kindex M-~
-@findex not-modified
- If you have changed a buffer but you do not want to save the changes,
-you should take some action to prevent it. Otherwise, each time you use
-@kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer by
-mistake. One thing you can do is type @kbd{M-~} (@code{not-modified}),
-which clears out the indication that the buffer is modified. If you do
-this, none of the save commands will believe that the buffer needs to be
-saved. (@samp{~} is often used as a mathematical symbol for `not'; thus
-@kbd{M-~} is `not', metafied.) You could also use
-@code{set-visited-file-name} (see below) to mark the buffer as visiting
-a different file name, one which is not in use for anything important.
-Alternatively, you can cancel all the changes made since the file was
-visited or saved, by reading the text from the file again. This is
-called @dfn{reverting}. @xref{Reverting}. (You could also undo all the
-changes by repeating the undo command @kbd{C-x u} until you have undone
-all the changes; but reverting is easier.) You can also kill the buffer.
-
-@findex set-visited-file-name
- @kbd{M-x set-visited-file-name} alters the name of the file that the
-current buffer is visiting. It reads the new file name using the
-minibuffer. Then it marks the buffer as visiting that file name, and
-changes the buffer name correspondingly. @code{set-visited-file-name}
-does not save the buffer in the newly visited file; it just alters the
-records inside Emacs in case you do save later. It also marks the
-buffer as ``modified'' so that @kbd{C-x C-s} in that buffer
-@emph{will} save.
-
-@kindex C-x C-w
-@findex write-file
- If you wish to mark the buffer as visiting a different file and save it
-right away, use @kbd{C-x C-w} (@code{write-file}). It is
-equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}
-(except that @kbd{C-x C-w} asks for confirmation if the file exists).
-@kbd{C-x C-s} used on a buffer that is not visiting a file has the
-same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
-buffer as visiting that file, and saves it there. The default file name in
-a buffer that is not visiting a file is made by combining the buffer name
-with the buffer's default directory (@pxref{File Names}).
-
- If the new file name implies a major mode, then @kbd{C-x C-w} switches
-to that major mode, in most cases. The command
-@code{set-visited-file-name} also does this. @xref{Choosing Modes}.
-
- If Emacs is about to save a file and sees that the date of the latest
-version on disk does not match what Emacs last read or wrote, Emacs
-notifies you of this fact, because it probably indicates a problem caused
-by simultaneous editing and requires your immediate attention.
-@xref{Interlocking,, Simultaneous Editing}.
-
-@node Backup
-@subsection Backup Files
-@cindex backup file
-@vindex make-backup-files
-@vindex vc-make-backup-files
-
- On most operating systems, rewriting a file automatically destroys all
-record of what the file used to contain. Thus, saving a file from Emacs
-throws away the old contents of the file---or it would, except that
-Emacs carefully copies the old contents to another file, called the
-@dfn{backup} file, before actually saving.
-
- For most files, the variable @code{make-backup-files} determines
-whether to make backup files. On most operating systems, its default
-value is @code{t}, so that Emacs does write backup files.
-
- For files managed by a version control system (@pxref{Version
-Control}), the variable @code{vc-make-backup-files} determines whether
-to make backup files. By default it is @code{nil}, since backup files
-are redundant when you store all the previous versions in a version
-control system.
-@iftex
-@xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}.
-@end iftex
-@ifnottex
-@xref{General VC Options}.
-@end ifnottex
-
-
- At your option, Emacs can keep either a single backup for each file,
-or make a series of numbered backup files for each file that you edit.
-
-@vindex backup-enable-predicate
-@vindex temporary-file-directory
-@vindex small-temporary-file-directory
- The default value of the @code{backup-enable-predicate} variable
-prevents backup files being written for files in the directories used
-for temporary files, specified by @code{temporary-file-directory} or
-@code{small-temporary-file-directory}.
-
- Emacs makes a backup for a file only the first time the file is saved
-from one buffer. No matter how many times you save a file, its backup file
-continues to contain the contents from before the file was visited.
-Normally this means that the backup file contains the contents from before
-the current editing session; however, if you kill the buffer and then visit
-the file again, a new backup file will be made by the next save.
-
- You can also explicitly request making another backup file from a
-buffer even though it has already been saved at least once. If you save
-the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made
-into a backup file if you save the buffer again. @kbd{C-u C-u C-x C-s}
-saves the buffer, but first makes the previous file contents into a new
-backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it makes a
-backup from the previous contents, and arranges to make another from the
-newly saved contents if you save again.
-
-@menu
-* One or Many: Numbered Backups. Whether to make one backup file or many.
-* Names: Backup Names. How backup files are named.
-* Deletion: Backup Deletion. Emacs deletes excess numbered backups.
-* Copying: Backup Copying. Backups can be made by copying or renaming.
-@end menu
-
-@node Numbered Backups
-@subsubsection Numbered Backups
-
-@vindex version-control
- The choice of single backup file or multiple numbered backup files
-is controlled by the variable @code{version-control}. Its possible
-values are:
-
-@table @code
-@item t
-Make numbered backups.
-@item nil
-Make numbered backups for files that have numbered backups already.
-Otherwise, make single backups.
-@item never
-Never make numbered backups; always make single backups.
-@end table
-
-@noindent
-The usual way to set this variable is globally, through your
-@file{.emacs} file or the customization buffer. However, you can set
-@code{version-control} locally in an individual buffer to control the
-making of backups for that buffer's file. For example, Rmail mode
-locally sets @code{version-control} to @code{never} to make sure that
-there is only one backup for an Rmail file. @xref{Locals}.
-
-@cindex @env{VERSION_CONTROL} environment variable
- If you set the environment variable @env{VERSION_CONTROL}, to tell
-various GNU utilities what to do with backup files, Emacs also obeys the
-environment variable by setting the Lisp variable @code{version-control}
-accordingly at startup. If the environment variable's value is @samp{t}
-or @samp{numbered}, then @code{version-control} becomes @code{t}; if the
-value is @samp{nil} or @samp{existing}, then @code{version-control}
-becomes @code{nil}; if it is @samp{never} or @samp{simple}, then
-@code{version-control} becomes @code{never}.
-
-@node Backup Names
-@subsubsection Single or Numbered Backups
-
- When Emacs makes a single backup file, its name is normally
-constructed by appending @samp{~} to the file name being edited; thus,
-the backup file for @file{eval.c} would be @file{eval.c~}.
-
-@vindex make-backup-file-name-function
-@vindex backup-directory-alist
- You can change this behavior by defining the variable
-@code{make-backup-file-name-function} to a suitable function.
-Alternatively you can customize the variable
-@code{backup-directory-alist} to specify that files matching certain
-patterns should be backed up in specific directories.
-
- A typical use is to add an element @code{("." . @var{dir})} to make
-all backups in the directory with absolute name @var{dir}; Emacs
-modifies the backup file names to avoid clashes between files with the
-same names originating in different directories. Alternatively,
-adding, say, @code{("." . ".~")} would make backups in the invisible
-subdirectory @file{.~} of the original file's directory. Emacs
-creates the directory, if necessary, to make the backup.
-
- If access control stops Emacs from writing backup files under the usual
-names, it writes the backup file as @file{%backup%~} in your home
-directory. Only one such file can exist, so only the most recently
-made such backup is available.
-
- If you choose to have a series of numbered backup files, backup file
-names contain @samp{.~}, the number, and another @samp{~} after the
-original file name. Thus, the backup files of @file{eval.c} would be
-called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way
-through names like @file{eval.c.~259~} and beyond. The variable
-@code{backup-directory-alist} applies to numbered backups just as
-usual.
-
-@node Backup Deletion
-@subsubsection Automatic Deletion of Backups
-
- To prevent excessive consumption of disk space, Emacs can delete numbered
-backup versions automatically. Generally Emacs keeps the first few backups
-and the latest few backups, deleting any in between. This happens every
-time a new backup is made.
-
-@vindex kept-old-versions
-@vindex kept-new-versions
- The two variables @code{kept-old-versions} and
-@code{kept-new-versions} control this deletion. Their values are,
-respectively, the number of oldest (lowest-numbered) backups to keep
-and the number of newest (highest-numbered) ones to keep, each time a
-new backup is made. The backups in the middle (excluding those oldest
-and newest) are the excess middle versions---those backups are
-deleted. These variables' values are used when it is time to delete
-excess versions, just after a new backup version is made; the newly
-made backup is included in the count in @code{kept-new-versions}. By
-default, both variables are 2.
-
-@vindex delete-old-versions
- If @code{delete-old-versions} is @code{t}, Emacs deletes the excess
-backup files silently. If it is @code{nil}, the default, Emacs asks
-you whether it should delete the excess backup versions. If it has
-any other value, then Emacs never automatically deletes backups.
-
- Dired's @kbd{.} (Period) command can also be used to delete old versions.
-@xref{Dired Deletion}.
-
-@node Backup Copying
-@subsubsection Copying vs.@: Renaming
-
- Backup files can be made by copying the old file or by renaming it.
-This makes a difference when the old file has multiple names (hard
-links). If the old file is renamed into the backup file, then the
-alternate names become names for the backup file. If the old file is
-copied instead, then the alternate names remain names for the file
-that you are editing, and the contents accessed by those names will be
-the new contents.
-
- The method of making a backup file may also affect the file's owner
-and group. If copying is used, these do not change. If renaming is used,
-you become the file's owner, and the file's group becomes the default
-(different operating systems have different defaults for the group).
-
- Having the owner change is usually a good idea, because then the owner
-always shows who last edited the file. Also, the owners of the backups
-show who produced those versions. Occasionally there is a file whose
-owner should not change; it is a good idea for such files to contain
-local variable lists to set @code{backup-by-copying-when-mismatch}
-locally (@pxref{File Variables}).
-
-@vindex backup-by-copying
-@vindex backup-by-copying-when-linked
-@vindex backup-by-copying-when-mismatch
-@vindex backup-by-copying-when-privileged-mismatch
-@cindex file ownership, and backup
-@cindex backup, and user-id
- The choice of renaming or copying is controlled by four variables.
-Renaming is the default choice. If the variable
-@code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise,
-if the variable @code{backup-by-copying-when-linked} is non-@code{nil},
-then copying is used for files that have multiple names, but renaming
-may still be used when the file being edited has only one name. If the
-variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then
-copying is used if renaming would cause the file's owner or group to
-change. @code{backup-by-copying-when-mismatch} is @code{t} by default
-if you start Emacs as the superuser. The fourth variable,
-@code{backup-by-copying-when-privileged-mismatch}, gives the highest
-numeric user-id for which @code{backup-by-copying-when-mismatch} will be
-forced on. This is useful when low-numbered user-ids are assigned to
-special system users, such as @code{root}, @code{bin}, @code{daemon},
-etc., which must maintain ownership of files.
-
- When a file is managed with a version control system (@pxref{Version
-Control}), Emacs does not normally make backups in the usual way for
-that file. But check-in and check-out are similar in some ways to
-making backups. One unfortunate similarity is that these operations
-typically break hard links, disconnecting the file name you visited from
-any alternate names for the same file. This has nothing to do with
-Emacs---the version control system does it.
-
-@node Customize Save
-@subsection Customizing Saving of Files
-
-@vindex require-final-newline
- If the value of the variable @code{require-final-newline} is
-@code{t}, saving or writing a file silently puts a newline at the end
-if there isn't already one there. If the value is @code{visit}, Emacs
-adds a newline at the end of any file that doesn't have one, just
-after it visits the file. (This marks the buffer as modified, and you
-can undo it.) If the value is @code{visit-save}, that means to add
-newlines both on visiting and on saving. If the value is @code{nil},
-Emacs leaves the end of the file unchanged; if it's neither @code{nil}
-nor @code{t}, Emacs asks you whether to add a newline. The default is
-@code{nil}.
-
-@vindex mode-require-final-newline
- Many major modes are designed for specific kinds of files that are
-always supposed to end in newlines. These major modes set the
-variable @code{require-final-newline} according to
-@code{mode-require-final-newline}. By setting the latter variable,
-you can control how these modes handle final newlines.
-
-@vindex write-region-inhibit-fsync
- When Emacs saves a file, it invokes the @code{fsync} system call to
-force the data immediately out to disk. This is important for safety
-if the system crashes or in case of power outage. However, it can be
-disruptive on laptops using power saving, because it requires the disk
-to spin up each time you save a file. Setting
-@code{write-region-inhibit-fsync} to a non-@code{nil} value disables
-this synchronization. Be careful---this means increased risk of data
-loss.
-
-@node Interlocking
-@subsection Protection against Simultaneous Editing
-
-@cindex file dates
-@cindex simultaneous editing
- Simultaneous editing occurs when two users visit the same file, both
-make changes, and then both save them. If nobody were informed that
-this was happening, whichever user saved first would later find that his
-changes were lost.
-
- On some systems, Emacs notices immediately when the second user starts
-to change the file, and issues an immediate warning. On all systems,
-Emacs checks when you save the file, and warns if you are about to
-overwrite another user's changes. You can prevent loss of the other
-user's work by taking the proper corrective action instead of saving the
-file.
-
-@findex ask-user-about-lock
-@cindex locking files
- When you make the first modification in an Emacs buffer that is
-visiting a file, Emacs records that the file is @dfn{locked} by you.
-(It does this by creating a symbolic link in the same directory with a
-different name.) Emacs removes the lock when you save the changes. The
-idea is that the file is locked whenever an Emacs buffer visiting it has
-unsaved changes.
-
-@cindex collision
- If you begin to modify the buffer while the visited file is locked by
-someone else, this constitutes a @dfn{collision}. When Emacs detects a
-collision, it asks you what to do, by calling the Lisp function
-@code{ask-user-about-lock}. You can redefine this function for the sake
-of customization. The standard definition of this function asks you a
-question and accepts three possible answers:
-
-@table @kbd
-@item s
-Steal the lock. Whoever was already changing the file loses the lock,
-and you gain the lock.
-@item p
-Proceed. Go ahead and edit the file despite its being locked by someone else.
-@item q
-Quit. This causes an error (@code{file-locked}), and the buffer
-contents remain unchanged---the modification you were trying to make
-does not actually take place.
-@end table
-
- Note that locking works on the basis of a file name; if a file has
-multiple names, Emacs does not realize that the two names are the same file
-and cannot prevent two users from editing it simultaneously under different
-names. However, basing locking on names means that Emacs can interlock the
-editing of new files that will not really exist until they are saved.
-
- Some systems are not configured to allow Emacs to make locks, and
-there are cases where lock files cannot be written. In these cases,
-Emacs cannot detect trouble in advance, but it still can detect the
-collision when you try to save a file and overwrite someone else's
-changes.
-
- If Emacs or the operating system crashes, this may leave behind lock
-files which are stale, so you may occasionally get warnings about
-spurious collisions. When you determine that the collision is spurious,
-just use @kbd{p} to tell Emacs to go ahead anyway.
-
- Every time Emacs saves a buffer, it first checks the last-modification
-date of the existing file on disk to verify that it has not changed since the
-file was last visited or saved. If the date does not match, it implies
-that changes were made in the file in some other way, and these changes are
-about to be lost if Emacs actually does save. To prevent this, Emacs
-displays a warning message and asks for confirmation before saving.
-Occasionally you will know why the file was changed and know that it does
-not matter; then you can answer @kbd{yes} and proceed. Otherwise, you should
-cancel the save with @kbd{C-g} and investigate the situation.
-
- The first thing you should do when notified that simultaneous editing
-has already taken place is to list the directory with @kbd{C-u C-x C-d}
-(@pxref{Directories}). This shows the file's current author. You
-should attempt to contact him to warn him not to continue editing.
-Often the next step is to save the contents of your Emacs buffer under a
-different name, and use @code{diff} to compare the two files.@refill
-
-@node File Shadowing
-@subsection Shadowing Files
-@cindex shadow files
-@cindex file shadows
-@findex shadow-initialize
-
-@table @kbd
-@item M-x shadow-initialize
-Set up file shadowing.
-@item M-x shadow-define-literal-group
-Declare a single file to be shared between sites.
-@item M-x shadow-define-regexp-group
-Make all files that match each of a group of files be shared between hosts.
-@item M-x shadow-define-cluster @key{RET} @var{name} @key{RET}
-Define a shadow file cluster @var{name}.
-@item M-x shadow-copy-files
-Copy all pending shadow files.
-@item M-x shadow-cancel
-Cancel the instruction to shadow some files.
-@end table
-
-You can arrange to keep identical @dfn{shadow} copies of certain files
-in more than one place---possibly on different machines. To do this,
-first you must set up a @dfn{shadow file group}, which is a set of
-identically-named files shared between a list of sites. The file
-group is permanent and applies to further Emacs sessions as well as
-the current one. Once the group is set up, every time you exit Emacs,
-it will copy the file you edited to the other files in its group. You
-can also do the copying without exiting Emacs, by typing @kbd{M-x
-shadow-copy-files}.
-
-To set up a shadow file group, use @kbd{M-x
-shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}.
-See their documentation strings for further information.
-
-Before copying a file to its shadows, Emacs asks for confirmation.
-You can answer ``no'' to bypass copying of this file, this time. If
-you want to cancel the shadowing permanently for a certain file, use
-@kbd{M-x shadow-cancel} to eliminate or change the shadow file group.
-
-A @dfn{shadow cluster} is a group of hosts that share directories, so
-that copying to or from one of them is sufficient to update the file
-on all of them. Each shadow cluster has a name, and specifies the
-network address of a primary host (the one we copy files to), and a
-regular expression that matches the host names of all the other hosts
-in the cluster. You can define a shadow cluster with @kbd{M-x
-shadow-define-cluster}.
-
-@node Time Stamps
-@subsection Updating Time Stamps Automatically
-@cindex time stamps
-@cindex modification dates
-@cindex locale, date format
-
-You can arrange to put a time stamp in a file, so that it will be updated
-automatically each time you edit and save the file. The time stamp
-has to be in the first eight lines of the file, and you should
-insert it like this:
-
-@example
-Time-stamp: <>
-@end example
-
-@noindent
-or like this:
-
-@example
-Time-stamp: " "
-@end example
-
-@findex time-stamp
- Then add the hook function @code{time-stamp} to the hook
-@code{before-save-hook}; that hook function will automatically update
-the time stamp, inserting the current date and time when you save the
-file. You can also use the command @kbd{M-x time-stamp} to update the
-time stamp manually. For other customizations, see the Custom group
-@code{time-stamp}. Note that non-numeric fields in the time stamp are
-formatted according to your locale setting (@pxref{Environment}).
-
-@node Reverting
-@section Reverting a Buffer
-@findex revert-buffer
-@cindex drastic changes
-@cindex reread a file
-
- If you have made extensive changes to a file and then change your mind
-about them, you can get rid of them by reading in the previous version
-of the file. To do this, use @kbd{M-x revert-buffer}, which operates on
-the current buffer. Since reverting a buffer unintentionally could lose
-a lot of work, you must confirm this command with @kbd{yes}.
-
- @code{revert-buffer} tries to position point in such a way that, if
-the file was edited only slightly, you will be at approximately the
-same piece of text after reverting as before. However, if you have made
-drastic changes, point may wind up in a totally different piece of text.
-
- Reverting marks the buffer as ``not modified'' until another change is
-made.
-
- Some kinds of buffers whose contents reflect data bases other than files,
-such as Dired buffers, can also be reverted. For them, reverting means
-recalculating their contents from the appropriate data base. Buffers
-created explicitly with @kbd{C-x b} cannot be reverted; @code{revert-buffer}
-reports an error when asked to do so.
-
-@vindex revert-without-query
- When you edit a file that changes automatically and frequently---for
-example, a log of output from a process that continues to run---it may be
-useful for Emacs to revert the file without querying you, whenever you
-visit the file again with @kbd{C-x C-f}.
-
- To request this behavior, set the variable @code{revert-without-query}
-to a list of regular expressions. When a file name matches one of these
-regular expressions, @code{find-file} and @code{revert-buffer} will
-revert it automatically if it has changed---provided the buffer itself
-is not modified. (If you have edited the text, it would be wrong to
-discard your changes.)
-
-@cindex Global Auto-Revert mode
-@cindex mode, Global Auto-Revert
-@cindex Auto-Revert mode
-@cindex mode, Auto-Revert
-@findex global-auto-revert-mode
-@findex auto-revert-mode
-@findex auto-revert-tail-mode
-
- You may find it useful to have Emacs revert files automatically when
-they change. Three minor modes are available to do this.
-
- @kbd{M-x global-auto-revert-mode} enables Global Auto-Revert mode,
-which periodically checks all file buffers and reverts when the
-corresponding file has changed. @kbd{M-x auto-revert-mode} enables a
-local version, Auto-Revert mode, which applies only to the current
-buffer.
-
- You can use Auto-Revert mode to ``tail'' a file such as a system
-log, so that changes made to that file by other programs are
-continuously displayed. To do this, just move the point to the end of
-the buffer, and it will stay there as the file contents change.
-However, if you are sure that the file will only change by growing at
-the end, use Auto-Revert Tail mode instead
-(@code{auto-revert-tail-mode}). It is more efficient for this.
-
-@vindex auto-revert-interval
- The variable @code{auto-revert-interval} controls how often to check
-for a changed file. Since checking a remote file is too slow, these
-modes do not check or revert remote files.
-
- @xref{VC Mode Line}, for Auto Revert peculiarities in buffers that
-visit files under version control.
-
-@ifnottex
-@include arevert-xtra.texi
-@end ifnottex
-
-@node Auto Save
-@section Auto-Saving: Protection Against Disasters
-@cindex Auto Save mode
-@cindex mode, Auto Save
-@cindex crashes
-
- Emacs saves all the visited files from time to time (based on counting
-your keystrokes) without being asked. This is called @dfn{auto-saving}.
-It prevents you from losing more than a limited amount of work if the
-system crashes.
-
- When Emacs determines that it is time for auto-saving, it considers
-each buffer, and each is auto-saved if auto-saving is enabled for it
-and it has been changed since the last time it was auto-saved. The
-message @samp{Auto-saving...} is displayed in the echo area during
-auto-saving, if any files are actually auto-saved. Errors occurring
-during auto-saving are caught so that they do not interfere with the
-execution of commands you have been typing.
-
-@menu
-* Files: Auto Save Files. The file where auto-saved changes are
- actually made until you save the file.
-* Control: Auto Save Control. Controlling when and how often to auto-save.
-* Recover:: Recovering text from auto-save files.
-@end menu
-
-@node Auto Save Files
-@subsection Auto-Save Files
-
- Auto-saving does not normally save in the files that you visited, because
-it can be very undesirable to save a program that is in an inconsistent
-state when you have made half of a planned change. Instead, auto-saving
-is done in a different file called the @dfn{auto-save file}, and the
-visited file is changed only when you request saving explicitly (such as
-with @kbd{C-x C-s}).
-
- Normally, the auto-save file name is made by appending @samp{#} to the
-front and rear of the visited file name. Thus, a buffer visiting file
-@file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that
-are not visiting files are auto-saved only if you request it explicitly;
-when they are auto-saved, the auto-save file name is made by appending
-@samp{#} to the front and rear of buffer name, then
-adding digits and letters at the end for uniqueness. For
-example, the @samp{*mail*} buffer in which you compose messages to be
-sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file
-names are made this way unless you reprogram parts of Emacs to do
-something different (the functions @code{make-auto-save-file-name} and
-@code{auto-save-file-name-p}). The file name to be used for auto-saving
-in a buffer is calculated when auto-saving is turned on in that buffer.
-
-@cindex auto-save for remote files
-@vindex auto-save-file-name-transforms
- The variable @code{auto-save-file-name-transforms} allows a degree
-of control over the auto-save file name. It lets you specify a series
-of regular expressions and replacements to transform the auto save
-file name. The default value puts the auto-save files for remote
-files (@pxref{Remote Files}) into the temporary file directory on the
-local machine.
-
- When you delete a substantial part of the text in a large buffer, auto
-save turns off temporarily in that buffer. This is because if you
-deleted the text unintentionally, you might find the auto-save file more
-useful if it contains the deleted text. To reenable auto-saving after
-this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x
-auto-save-mode}.
-
-@vindex auto-save-visited-file-name
- If you want auto-saving to be done in the visited file rather than
-in a separate auto-save file, set the variable
-@code{auto-save-visited-file-name} to a non-@code{nil} value. In this
-mode, there is no real difference between auto-saving and explicit
-saving.
-
-@vindex delete-auto-save-files
- A buffer's auto-save file is deleted when you save the buffer in its
-visited file. (You can inhibit this by setting the variable
-@code{delete-auto-save-files} to @code{nil}.) Changing the visited
-file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames
-any auto-save file to go with the new visited name.
-
-@node Auto Save Control
-@subsection Controlling Auto-Saving
-
-@vindex auto-save-default
-@findex auto-save-mode
- Each time you visit a file, auto-saving is turned on for that file's
-buffer if the variable @code{auto-save-default} is non-@code{nil} (but not
-in batch mode; @pxref{Entering Emacs}). The default for this variable is
-@code{t}, so auto-saving is the usual practice for file-visiting buffers.
-Auto-saving can be turned on or off for any existing buffer with the
-command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x
-auto-save-mode} turns auto-saving on with a positive argument, off with a
-zero or negative argument; with no argument, it toggles.
-
-@vindex auto-save-interval
- Emacs does auto-saving periodically based on counting how many characters
-you have typed since the last time auto-saving was done. The variable
-@code{auto-save-interval} specifies how many characters there are between
-auto-saves. By default, it is 300. Emacs doesn't accept values that are
-too small: if you customize @code{auto-save-interval} to a value less
-than 20, Emacs will behave as if the value is 20.
-
-@vindex auto-save-timeout
- Auto-saving also takes place when you stop typing for a while. The
-variable @code{auto-save-timeout} says how many seconds Emacs should
-wait before it does an auto save (and perhaps also a garbage
-collection). (The actual time period is longer if the current buffer is
-long; this is a heuristic which aims to keep out of your way when you
-are editing long buffers, in which auto-save takes an appreciable amount
-of time.) Auto-saving during idle periods accomplishes two things:
-first, it makes sure all your work is saved if you go away from the
-terminal for a while; second, it may avoid some auto-saving while you
-are actually typing.
-
- Emacs also does auto-saving whenever it gets a fatal error. This
-includes killing the Emacs job with a shell command such as @samp{kill
-%emacs}, or disconnecting a phone line or network connection.
-
-@findex do-auto-save
- You can request an auto-save explicitly with the command @kbd{M-x
-do-auto-save}.
-
-@node Recover
-@subsection Recovering Data from Auto-Saves
-
-@findex recover-file
- You can use the contents of an auto-save file to recover from a loss
-of data with the command @kbd{M-x recover-file @key{RET} @var{file}
-@key{RET}}. This visits @var{file} and then (after your confirmation)
-restores the contents from its auto-save file @file{#@var{file}#}.
-You can then save with @kbd{C-x C-s} to put the recovered text into
-@var{file} itself. For example, to recover file @file{foo.c} from its
-auto-save file @file{#foo.c#}, do:@refill
-
-@example
-M-x recover-file @key{RET} foo.c @key{RET}
-yes @key{RET}
-C-x C-s
-@end example
-
- Before asking for confirmation, @kbd{M-x recover-file} displays a
-directory listing describing the specified file and the auto-save file,
-so you can compare their sizes and dates. If the auto-save file
-is older, @kbd{M-x recover-file} does not offer to read it.
-
-@findex recover-session
- If Emacs or the computer crashes, you can recover all the files you
-were editing from their auto save files with the command @kbd{M-x
-recover-session}. This first shows you a list of recorded interrupted
-sessions. Move point to the one you choose, and type @kbd{C-c C-c}.
-
- Then @code{recover-session} asks about each of the files that were
-being edited during that session, asking whether to recover that file.
-If you answer @kbd{y}, it calls @code{recover-file}, which works in its
-normal fashion. It shows the dates of the original file and its
-auto-save file, and asks once again whether to recover that file.
-
- When @code{recover-session} is done, the files you've chosen to
-recover are present in Emacs buffers. You should then save them. Only
-this---saving them---updates the files themselves.
-
-@vindex auto-save-list-file-prefix
- Emacs records information about interrupted sessions for later
-recovery in files named
-@file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. All
-of this name except the @file{@var{pid}-@var{hostname}} part comes
-from the value of @code{auto-save-list-file-prefix}. You can record
-sessions in a different place by customizing that variable. If you
-set @code{auto-save-list-file-prefix} to @code{nil} in your
-@file{.emacs} file, sessions are not recorded for recovery.
-
-@node File Aliases
-@section File Name Aliases
-@cindex symbolic links (visiting)
-@cindex hard links (visiting)
-
- Symbolic links and hard links both make it possible for several file
-names to refer to the same file. Hard links are alternate names that
-refer directly to the file; all the names are equally valid, and no one
-of them is preferred. By contrast, a symbolic link is a kind of defined
-alias: when @file{foo} is a symbolic link to @file{bar}, you can use
-either name to refer to the file, but @file{bar} is the real name, while
-@file{foo} is just an alias. More complex cases occur when symbolic
-links point to directories.
-
-@vindex find-file-existing-other-name
-@vindex find-file-suppress-same-file-warnings
-
- Normally, if you visit a file which Emacs is already visiting under
-a different name, Emacs displays a message in the echo area and uses
-the existing buffer visiting that file. This can happen on systems
-that support hard or symbolic links, or if you use a long file name on
-a system that truncates long file names, or on a case-insensitive file
-system. You can suppress the message by setting the variable
-@code{find-file-suppress-same-file-warnings} to a non-@code{nil}
-value. You can disable this feature entirely by setting the variable
-@code{find-file-existing-other-name} to @code{nil}: then if you visit
-the same file under two different names, you get a separate buffer for
-each file name.
-
-@vindex find-file-visit-truename
-@cindex truenames of files
-@cindex file truenames
- If the variable @code{find-file-visit-truename} is non-@code{nil},
-then the file name recorded for a buffer is the file's @dfn{truename}
-(made by replacing all symbolic links with their target names), rather
-than the name you specify. Setting @code{find-file-visit-truename} also
-implies the effect of @code{find-file-existing-other-name}.
-
-@node Version Control
-@section Version Control
-@cindex version control
-
- @dfn{Version control systems} are packages that can record multiple
-versions of a source file, usually storing the unchanged parts of the
-file just once. Version control systems also record history information
-such as the creation time of each version, who created it, and a
-description of what was changed in that version.
-
- The Emacs version control interface is called VC. Its commands work
-with different version control systems---currently, it supports CVS,
-GNU Arch, RCS, Meta-CVS, Subversion, and SCCS. Of these, the GNU
-project distributes CVS, GNU Arch, and RCS; we recommend that you use
-either CVS or GNU Arch for your projects, and RCS for individual
-files. We also have free software to replace SCCS, known as CSSC; if
-you are using SCCS and don't want to make the incompatible change to
-RCS or CVS, you can switch to CSSC.
-
- VC is enabled by default in Emacs. To disable it, set the
-customizable variable @code{vc-handled-backends} to @code{nil}
-@iftex
-(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{Customizing VC}).
-@end ifnottex
-
-
-@menu
-* Introduction to VC:: How version control works in general.
-* VC Mode Line:: How the mode line shows version control status.
-* Basic VC Editing:: How to edit a file under version control.
-* Old Versions:: Examining and comparing old versions.
-* Secondary VC Commands:: The commands used a little less frequently.
-* Branches:: Multiple lines of development.
-@ifnottex
-* Remote Repositories:: Efficient access to remote CVS servers.
-* Snapshots:: Sets of file versions treated as a unit.
-* Miscellaneous VC:: Various other commands and features of VC.
-* Customizing VC:: Variables that change VC's behavior.
-@end ifnottex
-@end menu
-
-@node Introduction to VC
-@subsection Introduction to Version Control
-
- VC allows you to use a version control system from within Emacs,
-integrating the version control operations smoothly with editing. VC
-provides a uniform interface to version control, so that regardless of
-which version control system is in use, you can use it the same way.
-
- This section provides a general overview of version control, and
-describes the version control systems that VC supports. You can skip
-this section if you are already familiar with the version control system
-you want to use.
-
-@menu
-* Why Version Control?:: Understanding the problems it addresses
-* Version Systems:: Supported version control back-end systems.
-* VC Concepts:: Words and concepts related to version control.
-* Types of Log File:: The per-file VC log in contrast to the ChangeLog.
-@end menu
-
-@node Why Version Control?
-@subsubsection Understanding the problems it addresses
-
- Version control systems provide you with three important capabilities:
-reversibility, concurrency, and history.
-
- The most basic capability you get from a version-control system is
-reversibility, the ability to back up to a saved, known-good state when
-you discover that some modification you did was a mistake or a bad idea.
-
- Version-control systems also support concurrency, the ability to
-have many people modifying the same collection of code or documents
-knowing that conflicting modifications can be detected and resolved.
-
- Version-control systems give you the capability to attach a history
-to your data, explanatory comments about the intention behind each
-change to it. Even for a programmer working solo change histories
-are an important aid to memory; for a multi-person project they
-become a vitally important form of communication among developers.
-
-@node Version Systems
-@subsubsection Supported Version Control Systems
-
-@cindex back end (version control)
- VC currently works with six different version control systems or
-``back ends'': CVS, GNU Arch, RCS, Meta-CVS, Subversion, and SCCS.
-
-@cindex CVS
- CVS is a free version control system that is used for the majority
-of free software projects today. It allows concurrent multi-user
-development either locally or over the network. Some of its
-shortcomings, corrected by newer systems such as GNU Arch, are that it
-lacks atomic commits or support for renaming files. VC supports all
-basic editing operations under CVS, but for some less common tasks you
-still need to call CVS from the command line. Note also that before
-using CVS you must set up a repository, which is a subject too complex
-to treat here.
-
-@cindex GNU Arch
-@cindex Arch
- GNU Arch is a new version control system that is designed for
-distributed work. It differs in many ways from old well-known
-systems, such as CVS and RCS. It supports different transports for
-interoperating between users, offline operations, and it has good
-branching and merging features. It also supports atomic commits, and
-history of file renaming and moving. VC does not support all
-operations provided by GNU Arch, so you must sometimes invoke it from
-the command line, or use a specialized module.
-
-@cindex RCS
- RCS is the free version control system around which VC was initially
-built. The VC commands are therefore conceptually closest to RCS.
-Almost everything you can do with RCS can be done through VC. You
-cannot use RCS over the network though, and it only works at the level
-of individual files, rather than projects. You should use it if you
-want a simple, yet reliable tool for handling individual files.
-
-@cindex SVN
-@cindex Subversion
- Subversion is a free version control system designed to be similar
-to CVS but without CVS's problems. Subversion supports atomic commits,
-and versions directories, symbolic links, meta-data, renames, copies,
-and deletes. It can be used via http or via its own protocol.
-
-@cindex MCVS
-@cindex Meta-CVS
- Meta-CVS is another attempt to solve problems arising in CVS. It
-supports directory structure versioning, improved branching and
-merging, and use of symbolic links and meta-data in repositories.
-
-@cindex SCCS
- SCCS is a proprietary but widely used version control system. In
-terms of capabilities, it is the weakest of the six that VC supports.
-VC compensates for certain features missing in SCCS (snapshots, for
-example) by implementing them itself, but some other VC features, such
-as multiple branches, are not available with SCCS. Since SCCS is
-non-free, not respecting its users freedom, you should not use it;
-use its free replacement CSSC instead. But you should use CSSC only
-if for some reason you cannot use RCS, or one of the higher-level
-systems such as CVS or GNU Arch.
-
-In the following, we discuss mainly RCS, SCCS and CVS. Nearly
-everything said about CVS applies to GNU Arch, Subversion and Meta-CVS
-as well.
-
-@node VC Concepts
-@subsubsection Concepts of Version Control
-
-@cindex master file
-@cindex registered file
- When a file is under version control, we also say that it is
-@dfn{registered} in the version control system. Each registered file
-has a corresponding @dfn{master file} which represents the file's
-present state plus its change history---enough to reconstruct the
-current version or any earlier version. Usually the master file also
-records a @dfn{log entry} for each version, describing in words what was
-changed in that version.
-
-@cindex work file
-@cindex checking out files
- The file that is maintained under version control is sometimes called
-the @dfn{work file} corresponding to its master file. You edit the work
-file and make changes in it, as you would with an ordinary file. (With
-SCCS and RCS, you must @dfn{lock} the file before you start to edit it.)
-After you are done with a set of changes, you @dfn{check the file in},
-which records the changes in the master file, along with a log entry for
-them.
-
- To go beyond these basic concepts, you will need to understand three
-ways in which version-control systems can differ from each other. They
-can be locking or merging; they can be file-based or changeset-based;
-and they can be centralized or decentralized. VC handles all these
-choices, but they lead to differing behaviors which you will need
-to understand as you use it.
-
-@cindex locking versus merging
- A version control system typically has some mechanism to coordinate
-between users who want to change the same file. One method is
-@dfn{locking} (analogous to the locking that Emacs uses to detect
-simultaneous editing of a file, but distinct from it). In a locking
-system, such as SCCS, you must @dfn{lock} a file before you start to
-edit it. The other method is @dfn{merging}; the system tries to
-merge your changes with other people's changes when you check them in.
-
- With version control locking, work files are normally read-only so
-that you cannot change them. You ask the version control system to make
-a work file writable for you by locking it; only one user can do
-this at any given time. When you check in your changes, that unlocks
-the file, making the work file read-only again. This allows other users
-to lock the file to make further changes.
-
- By contrast, a merging system lets each user check out and modify a
-work file at any time. When you check in a a file, the system will
-attempt to merge your changes with any others checked into the
-repository since you checked out the file.
-
- Both locking and merging systems can have problems when multiple users
-try to modify the same file at the same time. Locking systems have
-@dfn{lock conflicts}; a user may try to check a file out and be unable
-to because it is locked. In merging systems, @dfn{merge conflicts}
-happen when you check in a change to a file that conflicts with a change
-checked in by someone else after your checkout. Both kinds of conflict
-have to be resolved by human judgment and communication.
-
- SCCS always uses locking. RCS is lock-based by default but can be told
-to operate in a merging style. CVS is merge-based by default but can
-be told to operate in a locking mode. Most later version-control
-systems, such as Subversion and GNU Arch, have been fundamentally
-merging-based rather than locking-based. This is because experience
-has shown that the merging-based approach is generally superior to
-the locking one, both in convenience to developers and in minimizing
-the number and severity of conflicts that actually occur.
-
- While it is rather unlikely that anyone will ever again build a
-fundamentally locking-based rather than merging-based version-control
-system in the future, merging-based version-systems sometimes have locks
-retrofitted onto them for reasons having nothing to do with technology.
-@footnote{Usually the control-freak instincts of managers.} For this
-reason, and to support older systems still in use, VC mode supports
-both locking and merging version control and tries to hide the differences
-between them as much as possible.
-
-@cindex files versus changesets.
- On SCCS, RCS, CVS, and other early version-control systems, checkins
-and other operations are @dfn{file-based}; each file has its own
-@dfn{master file} with its own comment- and revision history separate
-from that of all other files in the system. Later systems, beginning
-with Subversion, are @dfn{changeset-based}; a checkin may include
-changes to several files and that change set is treated as a unit by the
-system. Any comment associated with the change doesn't belong to any
-one file, but is attached to the changeset itself.
-
- Changeset-based version control is in general both more flexible and
-more powerful than file-based version control; usually, when a change to
-multiple files has to be backed out, it's good to be able to easily
-identify and remove all of it.
-
-@cindex centralized vs. decentralized
- Early version-control systems were designed around a @dfn{centralized}
-model in which each project has only one repository used by all
-developers. SCCS, RCS, CVS, and Subversion share this kind of model.
-It has two important problems. One is that a single repository is a
-single point of failure---if the repository server is down all work
-stops. The other is that you need to be connected live to the server to
-do checkins and checkouts; if you're offline, you can't work.
-
- Newer version-control systems like GNU Arch are @dfn{decentralized}.
-A project may have several different repositories, and these systems
-support a sort of super-merge between repositories that tries to
-reconcile their change histories. At the limit, each developer has
-his/her own repository, and repository merges replace checkin/commit
-operations.
-
- VC's job is to help you manage the traffic between your personal
-workfiles and a repository. Whether that repository is a single master
-or one of a network of peer repositories is not something VC has to care
-about. Thus, the difference between a centralized and a decentralized
-version-control system is invisible to VC mode.
-
-@iftex
-(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{CVS Options}).
-@end ifnottex
-
-
-@node Types of Log File
-@subsubsection Types of Log File
-@cindex types of log file
-@cindex log File, types of
-@cindex version control log
-
- Projects that use a revision control system can have @emph{two}
-types of log for changes. One is the per-file log maintained by the
-revision control system: each time you check in a change, you must
-fill out a @dfn{log entry} for the change (@pxref{Log Buffer}). This
-kind of log is called the @dfn{version control log}, also the
-@dfn{revision control log}, @dfn{RCS log}, or @dfn{CVS log}.
-
- The other kind of log is the file @file{ChangeLog} (@pxref{Change
-Log}). It provides a chronological record of all changes to a large
-portion of a program---typically one directory and its subdirectories.
-A small program would use one @file{ChangeLog} file; a large program
-may well merit a @file{ChangeLog} file in each major directory.
-@xref{Change Log}.
-
- A project maintained with version control can use just the per-file
-log, or it can use both kinds of logs. It can handle some files one
-way and some files the other way. Each project has its policy, which
-you should follow.
-
- When the policy is to use both, you typically want to write an entry
-for each change just once, then put it into both logs. You can write
-the entry in @file{ChangeLog}, then copy it to the log buffer when you
-check in the change. Or you can write the entry in the log buffer
-while checking in the change, and later use the @kbd{C-x v a} command
-to copy it to @file{ChangeLog}
-@iftex
-(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{Change Logs and VC}).
-@end ifnottex
-
-
-@node VC Mode Line
-@subsection Version Control and the Mode Line
-
- When you visit a file that is under version control, Emacs indicates
-this on the mode line. For example, @samp{RCS-1.3} says that RCS is
-used for that file, and the current version is 1.3.
-
- The character between the back-end name and the version number
-indicates the version control status of the file. @samp{-} means that
-the work file is not locked (if locking is in use), or not modified (if
-locking is not in use). @samp{:} indicates that the file is locked, or
-that it is modified. If the file is locked by some other user (for
-instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
-
-@vindex auto-revert-check-vc-info
- When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
-under version control, it updates the version control information in
-the mode line. However, Auto Revert mode may not properly update this
-information if the version control status changes without changes to
-the work file, from outside the current Emacs session. If you set
-@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates
-the version control status information every
-@code{auto-revert-interval} seconds, even if the work file itself is
-unchanged. The resulting CPU usage depends on the version control
-system, but is usually not excessive.
-
-@node Basic VC Editing
-@subsection Basic Editing under Version Control
-
- The principal VC command is an all-purpose command that performs
-either locking or check-in, depending on the situation.
-
-@table @kbd
-@itemx C-x v v
-Perform the next logical version control operation on this file.
-@end table
-
-@findex vc-next-action
-@kindex C-x v v
- The precise action of this command depends on the state of the file,
-and whether the version control system uses locking or not. SCCS and
-RCS normally use locking; CVS normally does not use locking.
-
-@findex vc-toggle-read-only
-@kindex C-x C-q @r{(Version Control)}
- As a special convenience that is particularly useful for files with
-locking, you can let Emacs check a file in or out whenever you change
-its read-only flag. This means, for example, that you cannot
-accidentally edit a file without properly checking it out first. To
-achieve this, bind the key @kbd{C-x C-q} to @kbd{vc-toggle-read-only}
-in your @file{~/.emacs} file. (@xref{Init Rebinding}.)
-
-@menu
-* VC with Locking:: RCS in its default mode, SCCS, and optionally CVS.
-* Without Locking:: Without locking: default mode for CVS.
-* Advanced C-x v v:: Advanced features available with a prefix argument.
-* Log Buffer:: Features available in log entry buffers.
-@end menu
-
-@node VC with Locking
-@subsubsection Basic Version Control with Locking
-
- If locking is used for the file (as with SCCS, and RCS in its default
-mode), @kbd{C-x v v} can either lock a file or check it in:
-
-@itemize @bullet
-@item
-If the file is not locked, @kbd{C-x v v} locks it, and
-makes it writable so that you can change it.
-
-@item
-If the file is locked by you, and contains changes, @kbd{C-x v v} checks
-in the changes. In order to do this, it first reads the log entry
-for the new version. @xref{Log Buffer}.
-
-@item
-If the file is locked by you, but you have not changed it since you
-locked it, @kbd{C-x v v} releases the lock and makes the file read-only
-again.
-
-@item
-If the file is locked by some other user, @kbd{C-x v v} asks you whether
-you want to ``steal the lock'' from that user. If you say yes, the file
-becomes locked by you, but a message is sent to the person who had
-formerly locked the file, to inform him of what has happened.
-@end itemize
-
- These rules also apply when you use CVS in locking mode, except
-that there is no such thing as stealing a lock.
-
-@node Without Locking
-@subsubsection Basic Version Control without Locking
-
- When there is no locking---the default for CVS---work files are always
-writable; you do not need to do anything before you begin to edit a
-file. The status indicator on the mode line is @samp{-} if the file is
-unmodified; it flips to @samp{:} as soon as you save any changes in the
-work file.
-
- Here is what @kbd{C-x v v} does when using CVS:
-
-@itemize @bullet
-@item
-If some other user has checked in changes into the master file, Emacs
-asks you whether you want to merge those changes into your own work
-file. You must do this before you can check in your own changes. (To
-pick up any recent changes from the master file @emph{without} trying
-to commit your own changes, type @kbd{C-x v m @key{RET}}.)
-@xref{Merging}.
-
-@item
-If there are no new changes in the master file, but you have made
-modifications in your work file, @kbd{C-x v v} checks in your changes.
-In order to do this, it first reads the log entry for the new version.
-@xref{Log Buffer}.
-
-@item
-If the file is not modified, the @kbd{C-x v v} does nothing.
-@end itemize
-
- These rules also apply when you use RCS in the mode that does not
-require locking, except that automatic merging of changes from the
-master file is not implemented. Unfortunately, this means that nothing
-informs you if another user has checked in changes in the same file
-since you began editing it, and when this happens, his changes will be
-effectively removed when you check in your version (though they will
-remain in the master file, so they will not be entirely lost). You must
-therefore verify that the current version is unchanged, before you
-check in your changes. We hope to eliminate this risk and provide
-automatic merging with RCS in a future Emacs version.
-
- In addition, locking is possible with RCS even in this mode, although
-it is not required; @kbd{C-x v v} with an unmodified file locks the
-file, just as it does with RCS in its normal (locking) mode.
-
-@node Advanced C-x v v
-@subsubsection Advanced Control in @kbd{C-x v v}
-
-@cindex version number to check in/out
- When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
-C-x v v}), it still performs the next logical version control
-operation, but accepts additional arguments to specify precisely how
-to do the operation.
-
-@itemize @bullet
-@item
-If the file is modified (or locked), you can specify the version
-number to use for the new version that you check in. This is one way
-to create a new branch (@pxref{Branches}).
-
-@item
-If the file is not modified (and unlocked), you can specify the
-version to select; this lets you start working from an older version,
-or on another branch. If you do not enter any version, that takes you
-to the highest version on the current branch; therefore @kbd{C-u C-x
-v v @key{RET}} is a convenient way to get the latest version of a file from
-the repository.
-
-@item
-@cindex specific version control system
-Instead of the version number, you can also specify the name of a
-version control system. This is useful when one file is being managed
-with two version control systems at the same time
-@iftex
-(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs
-Features}).
-@end iftex
-@ifnottex
-(@pxref{Local Version Control}).
-@end ifnottex
-
-@end itemize
-
-@node Log Buffer
-@subsubsection Features of the Log Entry Buffer
-
- When you check in changes, @kbd{C-x v v} first reads a log entry. It
-pops up a buffer called @samp{*VC-Log*} for you to enter the log entry.
-
- Sometimes the @samp{*VC-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{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.
-@iftex
-@xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features},
-@end iftex
-@ifnottex
-@xref{Change Logs and VC},
-@end ifnottex
-for the opposite way of working---generating ChangeLog entries from
-the revision control log.
-
- In the @samp{*VC-Log*} 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. (This can be a list of more than one file if
-you use VC Dired mode or PCL-CVS.
-@iftex
-@xref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features},
-@end iftex
-@ifnottex
-@xref{VC Dired Mode},
-@end ifnottex
-and @ref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs
-Front-End to CVS}.)
-
- When you have finished editing the log message, type @kbd{C-c C-c} to
-exit the buffer and commit the change.
-
- To abort check-in, just @strong{don't} type @kbd{C-c C-c} in that
-buffer. You can switch buffers and do other editing. As long as you
-don't try to check in another file, the entry you were editing remains
-in the @samp{*VC-Log*} buffer, and you can go back to that buffer at any
-time to complete the check-in.
-
- If you change several source files for the same reason, it is often
-convenient to specify the same log entry for many of the files. To do
-this, use the history of previous log entries. The commands @kbd{M-n},
-@kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just like the
-minibuffer history commands (except that these versions are used outside
-the minibuffer).
-
-@vindex vc-log-mode-hook
- Each time you check in a file, the log entry buffer is put into VC Log
-mode, which involves running two hooks: @code{text-mode-hook} and
-@code{vc-log-mode-hook}. @xref{Hooks}.
-
-@node Old Versions
-@subsection Examining And Comparing Old Versions
-
- One of the convenient features of version control is the ability
-to examine any version of a file, or compare two versions.
-
-@table @kbd
-@item C-x v ~ @var{version} @key{RET}
-Examine version @var{version} of the visited file, in a buffer of its
-own.
-
-@item C-x v =
-Compare the current buffer contents with the master version from which
-you started editing.
-
-@item C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET}
-Compare the specified two versions of @var{file}.
-
-@item C-x v g
-Display the file with per-line version information and using colors.
-@end table
-
-@findex vc-version-other-window
-@kindex C-x v ~
- To examine an old version in its entirety, visit the file and then type
-@kbd{C-x v ~ @var{version} @key{RET}} (@code{vc-version-other-window}).
-This puts the text of version @var{version} in a file named
-@file{@var{filename}.~@var{version}~}, and visits it in its own buffer
-in a separate window. (In RCS, you can also select an old version
-and create a branch from it. @xref{Branches}.)
-
-@findex vc-diff
-@kindex C-x v =
- It is usually more convenient to compare two versions of the file,
-with the command @kbd{C-x v =} (@code{vc-diff}). Plain @kbd{C-x v =}
-compares the current buffer contents (saving them in the file if
-necessary) with the master version from which you started editing the
-file (this is not necessarily the latest version of the file).
-@kbd{C-u C-x v =}, with a numeric argument, reads a file name and two
-version numbers, then compares those versions of the specified file.
-Both forms display the output in a special buffer in another window.
-
- You can specify a checked-in version by its number; an empty input
-specifies the current contents of the work file (which may be different
-from all the checked-in versions). You can also specify a snapshot name
-@iftex
-(@pxref{Snapshots,,,emacs-xtra, Specialized Emacs Features})
-@end iftex
-@ifnottex
-(@pxref{Snapshots})
-@end ifnottex
-instead of one or both version numbers.
-
- If you supply a directory name instead of the name of a registered
-file, this command compares the two specified versions of all registered
-files in that directory and its subdirectories.
-
-@vindex vc-diff-switches
-@vindex vc-rcs-diff-switches
- @kbd{C-x v =} works by running a variant of the @code{diff} utility
-designed to work with the version control system in use. When you
-invoke @code{diff} this way, in addition to the options specified by
-@code{diff-switches} (@pxref{Comparing Files}), it receives those
-specified by @code{vc-diff-switches}, plus those specified for the
-specific back end by @code{vc-@var{backend}-diff-switches}. For
-instance, when the version control back end is RCS, @code{diff} uses
-the options in @code{vc-rcs-diff-switches}. The
-@samp{vc@dots{}diff-switches} variables are @code{nil} by default.
-
- The buffer produced by @kbd{C-x v =} supports the commands of
-Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and
-@kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always
-find the corresponding locations in the current work file. (Older
-versions are not, in general, present as files on your disk.)
-
-@findex vc-annotate
-@kindex C-x v g
- For some back ends, you can display the file @dfn{annotated} with
-per-line version information and using colors to enhance the visual
-appearance, with the command @kbd{M-x vc-annotate}. It creates a new
-buffer (the ``annotate buffer'') displaying the file's text, with each
-part colored to show how old it is. Text colored red is new, blue means
-old, and intermediate colors indicate intermediate ages. By default,
-the color is scaled over the full range of ages, such that the oldest
-changes are blue, and the newest changes are red.
-
- When you give a prefix argument to this command, it uses the
-minibuffer to read two arguments: which version number to display and
-annotate (instead of the current file contents), and the time span in
-days the color range should cover.
-
- From the annotate buffer, these and other color scaling options are
-available from the @samp{VC-Annotate} menu. In this buffer, you can
-also use the following keys to browse the annotations of past revisions,
-view diffs, or view log entries:
-
-@table @kbd
-@item P
-Annotate the previous revision, that is to say, the revision before
-the one currently annotated. A numeric prefix argument is a repeat
-count, so @kbd{C-u 10 P} would take you back 10 revisions.
-
-@item N
-Annotate the next revision---the one after the revision currently
-annotated. A numeric prefix argument is a repeat count.
-
-@item J
-Annotate the revision indicated by the current line.
-
-@item A
-Annotate the revision before the one indicated by the current line.
-This is useful to see the state the file was in before the change on
-the current line was made.
-
-@item D
-Display the diff between the current line's revision and the previous
-revision. This is useful to see what the current line's revision
-actually changed in the file.
-
-@item L
-Show the log of the current line's revision. This is useful to see
-the author's description of the changes in the revision on the current
-line.
-
-@item W
-Annotate the workfile version--the one you are editing. If you used
-@kbd{P} and @kbd{N} to browse to other revisions, use this key to
-return to your current version.
-@end table
-
-@node Secondary VC Commands
-@subsection The Secondary Commands of VC
-
- This section explains the secondary commands of VC; those that you might
-use once a day.
-
-@menu
-* Registering:: Putting a file under version control.
-* VC Status:: Viewing the VC status of files.
-* VC Undo:: Canceling changes before or after check-in.
-@ifnottex
-* VC Dired Mode:: Listing files managed by version control.
-* VC Dired Commands:: Commands to use in a VC Dired buffer.
-@end ifnottex
-@end menu
-
-@node Registering
-@subsubsection Registering a File for Version Control
-
-@kindex C-x v i
-@findex vc-register
- You can put any file under version control by simply visiting it, and
-then typing @w{@kbd{C-x v i}} (@code{vc-register}).
-
-@table @kbd
-@item C-x v i
-Register the visited file for version control.
-@end table
-
- To register the file, Emacs must choose which version control system
-to use for it. If the file's directory already contains files
-registered in a version control system, Emacs uses that system. If
-there is more than one system in use for a directory, Emacs uses the
-one that appears first in @code{vc-handled-backends}
-@iftex
-(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{Customizing VC}).
-@end ifnottex
-On the other hand, if there are no files already registered, Emacs uses
-the first system from @code{vc-handled-backends} that could register
-the file (for example, you cannot register a file under CVS if its
-directory is not already part of a CVS tree); with the default value
-of @code{vc-handled-backends}, this means that Emacs uses RCS in this
-situation.
-
- If locking is in use, @kbd{C-x v i} leaves the file unlocked and
-read-only. Type @kbd{C-x v v} if you wish to start editing it. After
-registering a file with CVS, you must subsequently commit the initial
-version by typing @kbd{C-x v v}. Until you do that, the version
-appears as @samp{@@@@} in the mode line.
-
-@vindex vc-default-init-version
-@cindex initial version number to register
- The initial version number for a newly registered file is 1.1, by
-default. You can specify a different default by setting the variable
-@code{vc-default-init-version}, or you can give @kbd{C-x v i} a numeric
-argument; then it reads the initial version number for this particular
-file using the minibuffer.
-
-@vindex vc-initial-comment
- If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an
-initial comment to describe the purpose of this source file. Reading
-the initial comment works like reading a log entry (@pxref{Log Buffer}).
-
-@node VC Status
-@subsubsection VC Status Commands
-
-@table @kbd
-@item C-x v l
-Display version control state and change history.
-@end table
-
-@kindex C-x v l
-@findex vc-print-log
- To view the detailed version control status and history of a file,
-type @kbd{C-x v l} (@code{vc-print-log}). It displays the history of
-changes to the current file, including the text of the log entries. The
-output appears in a separate window. The point is centered at the
-revision of the file that is currently being visited.
-
- In the change log buffer, you can use the following keys to move
-between the logs of revisions and of files, to view past revisions, and
-to view diffs:
-
-@table @kbd
-@item p
-Move to the previous revision-item in the buffer. (Revision entries in the log
-buffer are usually in reverse-chronological order, so the previous
-revision-item usually corresponds to a newer revision.) A numeric
-prefix argument is a repeat count.
-
-@item n
-Move to the next revision-item (which most often corresponds to the
-previous revision of the file). A numeric prefix argument is a repeat
-count.
-
-@item P
-Move to the log of the previous file, when the logs of multiple files
-are in the log buffer
-@iftex
-(@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{VC Dired Mode}).
-@end ifnottex
-Otherwise, just move to the beginning of the log. A numeric prefix
-argument is a repeat count, so @kbd{C-u 10 P} would move backward 10
-files.
-
-@item N
-Move to the log of the next file, when the logs of multiple files are
-in the log buffer
-@iftex
-(@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{VC Dired Mode}).
-@end ifnottex
-It also takes a numeric prefix argument as a repeat count.
-
-@item f
-Visit the revision indicated at the current line, like typing @kbd{C-x
-v ~} and specifying this revision's number (@pxref{Old Versions}).
-
-@item d
-Display the diff (@pxref{Comparing Files}) between the revision
-indicated at the current line and the next earlier revision. This is
-useful to see what actually changed when the revision indicated on the
-current line was committed.
-@end table
-
-@node VC Undo
-@subsubsection Undoing Version Control Actions
-
-@table @kbd
-@item C-x v u
-Revert the buffer and the file to the version from which you started
-editing the file.
-
-@item C-x v c
-Remove the last-entered change from the master for the visited file.
-This undoes your last check-in.
-@end table
-
-@kindex C-x v u
-@findex vc-revert-buffer
- If you want to discard your current set of changes and revert to the
-version from which you started editing the file, use @kbd{C-x v u}
-(@code{vc-revert-buffer}). This leaves the file unlocked; if locking
-is in use, you must first lock the file again before you change it
-again. @kbd{C-x v u} requires confirmation, unless it sees that you
-haven't made any changes with respect to the master version.
-
- @kbd{C-x v u} is also the command to unlock a file if you lock it and
-then decide not to change it.
-
-@kindex C-x v c
-@findex vc-cancel-version
- To cancel a change that you already checked in, use @kbd{C-x v c}
-(@code{vc-cancel-version}). This command discards all record of the
-most recent checked-in version, but only if your work file corresponds
-to that version---you cannot use @kbd{C-x v c} to cancel a version
-that is not the latest on its branch. @kbd{C-x v c} also offers to
-revert your work file and buffer to the previous version (the one that
-precedes the version that is deleted).
-
- If you answer @kbd{no}, VC keeps your changes in the buffer, and locks
-the file. The no-revert option is useful when you have checked in a
-change and then discover a trivial error in it; you can cancel the
-erroneous check-in, fix the error, and check the file in again.
-
- When @kbd{C-x v c} does not revert the buffer, it unexpands all
-version control headers in the buffer instead
-@iftex
-(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{Version Headers}).
-@end ifnottex
-This is because the buffer no longer corresponds to any existing
-version. If you check it in again, the check-in process will expand
-the headers properly for the new version number.
-
- However, it is impossible to unexpand the RCS @samp{@w{$}Log$} header
-automatically. If you use that header feature, you have to unexpand it
-by hand---by deleting the entry for the version that you just canceled.
-
- Be careful when invoking @kbd{C-x v c}, as it is easy to lose a lot of
-work with it. To help you be careful, this command always requires
-confirmation with @kbd{yes}. Note also that this command is disabled
-under CVS, because canceling versions is very dangerous and discouraged
-with CVS.
-
-@ifnottex
-@c vc1-xtra.texi needs extra level of lowering.
-@lowersections
-@include vc1-xtra.texi
-@raisesections
-@end ifnottex
-
-@node Branches
-@subsection Multiple Branches of a File
-@cindex branch (version control)
-@cindex trunk (version control)
-
- One use of version control is to maintain multiple ``current''
-versions of a file. For example, you might have different versions of a
-program in which you are gradually adding various unfinished new
-features. Each such independent line of development is called a
-@dfn{branch}. VC allows you to create branches, switch between
-different branches, and merge changes from one branch to another.
-Please note, however, that branches are not supported for SCCS.
-
- A file's main line of development is usually called the @dfn{trunk}.
-The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At
-any such version, you can start an independent branch. A branch
-starting at version 1.2 would have version number 1.2.1.1, and consecutive
-versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4,
-and so on. If there is a second branch also starting at version 1.2, it
-would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.
-
-@cindex head version
- If you omit the final component of a version number, that is called a
-@dfn{branch number}. It refers to the highest existing version on that
-branch---the @dfn{head version} of that branch. The branches in the
-example above have branch numbers 1.2.1 and 1.2.2.
-
-@menu
-* Switching Branches:: How to get to another existing branch.
-* Creating Branches:: How to start a new branch.
-* Merging:: Transferring changes between branches.
-* Multi-User Branching:: Multiple users working at multiple branches
- in parallel.
-@end menu
-
-@node Switching Branches
-@subsubsection Switching between Branches
-
- To switch between branches, type @kbd{C-u C-x v v} and specify the
-version number you want to select. This version is then visited
-@emph{unlocked} (write-protected), so you can examine it before locking
-it. Switching branches in this way is allowed only when the file is not
-locked.
-
- You can omit the minor version number, thus giving only the branch
-number; this takes you to the head version on the chosen branch. If you
-only type @key{RET}, Emacs goes to the highest version on the trunk.
-
- After you have switched to any branch (including the main branch), you
-stay on it for subsequent VC commands, until you explicitly select some
-other branch.
-
-@node Creating Branches
-@subsubsection Creating New Branches
-
- To create a new branch from a head version (one that is the latest in
-the branch that contains it), first select that version if necessary,
-lock it with @kbd{C-x v v}, and make whatever changes you want. Then,
-when you check in the changes, use @kbd{C-u C-x v v}. This lets you
-specify the version number for the new version. You should specify a
-suitable branch number for a branch starting at the current version.
-For example, if the current version is 2.5, the branch number should be
-2.5.1, 2.5.2, and so on, depending on the number of existing branches at
-that point.
-
- To create a new branch at an older version (one that is no longer the
-head of a branch), first select that version (@pxref{Switching
-Branches}), then lock it with @kbd{C-x v v}. You'll be asked to
-confirm, when you lock the old version, that you really mean to create a
-new branch---if you say no, you'll be offered a chance to lock the
-latest version instead.
-
- Then make your changes and type @kbd{C-x v v} again to check in a new
-version. This automatically creates a new branch starting from the
-selected version. You need not specially request a new branch, because
-that's the only way to add a new version at a point that is not the head
-of a branch.
-
- After the branch is created, you ``stay'' on it. That means that
-subsequent check-ins create new versions on that branch. To leave the
-branch, you must explicitly select a different version with @kbd{C-u C-x
-v v}. To transfer changes from one branch to another, use the merge
-command, described in the next section.
-
-@node Merging
-@subsubsection Merging Branches
-
-@cindex merging changes
- When you have finished the changes on a certain branch, you will
-often want to incorporate them into the file's main line of development
-(the trunk). This is not a trivial operation, because development might
-also have proceeded on the trunk, so that you must @dfn{merge} the
-changes into a file that has already been changed otherwise. VC allows
-you to do this (and other things) with the @code{vc-merge} command.
-
-@table @kbd
-@item C-x v m (vc-merge)
-Merge changes into the work file.
-@end table
-
-@kindex C-x v m
-@findex vc-merge
- @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it
-into the current version of the work file. It firsts asks you in the
-minibuffer where the changes should come from. If you just type
-@key{RET}, Emacs merges any changes that were made on the same branch
-since you checked the file out (we call this @dfn{merging the news}).
-This is the common way to pick up recent changes from the repository,
-regardless of whether you have already changed the file yourself.
-
- You can also enter a branch number or a pair of version numbers in
-the minibuffer. Then @kbd{C-x v m} finds the changes from that
-branch, or the differences between the two versions you specified, and
-merges them into the current version of the current file.
-
- As an example, suppose that you have finished a certain feature on
-branch 1.3.1. In the meantime, development on the trunk has proceeded
-to version 1.5. To merge the changes from the branch to the trunk,
-first go to the head version of the trunk, by typing @kbd{C-u C-x v v
-@key{RET}}. Version 1.5 is now current. If locking is used for the file,
-type @kbd{C-x v v} to lock version 1.5 so that you can change it. Next,
-type @kbd{C-x v m 1.3.1 @key{RET}}. This takes the entire set of changes on
-branch 1.3.1 (relative to version 1.3, where the branch started, up to
-the last version on the branch) and merges it into the current version
-of the work file. You can now check in the changed file, thus creating
-version 1.6 containing the changes from the branch.
-
- It is possible to do further editing after merging the branch, before
-the next check-in. But it is usually wiser to check in the merged
-version, then lock it and make the further changes. This will keep
-a better record of the history of changes.
-
-@cindex conflicts
-@cindex resolving conflicts
- When you merge changes into a file that has itself been modified, the
-changes might overlap. We call this situation a @dfn{conflict}, and
-reconciling the conflicting changes is called @dfn{resolving a
-conflict}.
-
- Whenever conflicts occur during merging, VC detects them, tells you
-about them in the echo area, and asks whether you want help in merging.
-If you say yes, it starts an Ediff session (@pxref{Top,
-Ediff, Ediff, ediff, The Ediff Manual}).
-
- If you say no, the conflicting changes are both inserted into the
-file, surrounded by @dfn{conflict markers}. The example below shows how
-a conflict region looks; the file is called @samp{name} and the current
-master file version with user B's changes in it is 1.11.
-
-@c @w here is so CVS won't think this is a conflict.
-@smallexample
-@group
-@w{<}<<<<<< name
- @var{User A's version}
-=======
- @var{User B's version}
-@w{>}>>>>>> 1.11
-@end group
-@end smallexample
-
-@cindex vc-resolve-conflicts
- Then you can resolve the conflicts by editing the file manually. Or
-you can type @code{M-x vc-resolve-conflicts} after visiting the file.
-This starts an Ediff session, as described above. Don't forget to
-check in the merged version afterwards.
-
-@node Multi-User Branching
-@subsubsection Multi-User Branching
-
- It is often useful for multiple developers to work simultaneously on
-different branches of a file. CVS allows this by default; for RCS, it
-is possible if you create multiple source directories. Each source
-directory should have a link named @file{RCS} which points to a common
-directory of RCS master files. Then each source directory can have its
-own choice of selected versions, but all share the same common RCS
-records.
-
- This technique works reliably and automatically, provided that the
-source files contain RCS version headers
-@iftex
-(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{Version Headers}).
-@end ifnottex
-The headers enable Emacs to be sure, at all times, which version
-number is present in the work file.
-
- If the files do not have version headers, you must instead tell Emacs
-explicitly in each session which branch you are working on. To do this,
-first find the file, then type @kbd{C-u C-x v v} and specify the correct
-branch number. This ensures that Emacs knows which branch it is using
-during this particular editing session.
-
-@ifnottex
-@include vc2-xtra.texi
-@end ifnottex
-
-@node Directories
-@section File Directories
-
-@cindex file directory
-@cindex directory listing
- The file system groups files into @dfn{directories}. A @dfn{directory
-listing} is a list of all the files in a directory. Emacs provides
-commands to create and delete directories, and to make directory
-listings in brief format (file names only) and verbose format (sizes,
-dates, and authors included). Emacs also includes a directory browser
-feature called Dired; see @ref{Dired}.
-
-@table @kbd
-@item C-x C-d @var{dir-or-pattern} @key{RET}
-Display a brief directory listing (@code{list-directory}).
-@item C-u C-x C-d @var{dir-or-pattern} @key{RET}
-Display a verbose directory listing.
-@item M-x make-directory @key{RET} @var{dirname} @key{RET}
-Create a new directory named @var{dirname}.
-@item M-x delete-directory @key{RET} @var{dirname} @key{RET}
-Delete the directory named @var{dirname}. It must be empty,
-or you get an error.
-@end table
-
-@findex list-directory
-@kindex C-x C-d
- The command to display a directory listing is @kbd{C-x C-d}
-(@code{list-directory}). It reads using the minibuffer a file name
-which is either a directory to be listed or a wildcard-containing
-pattern for the files to be listed. For example,
-
-@example
-C-x C-d /u2/emacs/etc @key{RET}
-@end example
-
-@noindent
-lists all the files in directory @file{/u2/emacs/etc}. Here is an
-example of specifying a file name pattern:
-
-@example
-C-x C-d /u2/emacs/src/*.c @key{RET}
-@end example
-
- Normally, @kbd{C-x C-d} displays a brief directory listing containing
-just file names. A numeric argument (regardless of value) tells it to
-make a verbose listing including sizes, dates, and owners (like
-@samp{ls -l}).
-
-@vindex list-directory-brief-switches
-@vindex list-directory-verbose-switches
- The text of a directory listing is mostly obtained by running
-@code{ls} in an inferior process. Two Emacs variables control the
-switches passed to @code{ls}: @code{list-directory-brief-switches} is
-a string giving the switches to use in brief listings (@code{"-CF"} by
-default), and @code{list-directory-verbose-switches} is a string
-giving the switches to use in a verbose listing (@code{"-l"} by
-default).
-
-@vindex directory-free-space-program
-@vindex directory-free-space-args
- In verbose directory listings, Emacs adds information about the
-amount of free space on the disk that contains the directory. To do
-this, it runs the program specified by
-@code{directory-free-space-program} with arguments
-@code{directory-free-space-args}.
-
-@node Comparing Files
-@section Comparing Files
-@cindex comparing files
-
-@findex diff
-@vindex diff-switches
- The command @kbd{M-x diff} compares two files, displaying the
-differences in an Emacs buffer named @samp{*diff*}. It works by
-running the @code{diff} program, using options taken from the variable
-@code{diff-switches}. The value of @code{diff-switches} should be a
-string; the default is @code{"-c"} to specify a context diff.
-@xref{Top,, Diff, diff, Comparing and Merging Files}, for more
-information about @command{diff} output formats.
-
-@findex diff-backup
- The command @kbd{M-x diff-backup} compares a specified file with its most
-recent backup. If you specify the name of a backup file,
-@code{diff-backup} compares it with the source file that it is a backup
-of.
-
-@findex compare-windows
- The command @kbd{M-x compare-windows} compares the text in the
-current window with that in the next window. (For more information
-about windows in Emacs, @ref{Windows}.) Comparison starts at point in
-each window, after pushing each initial point value on the mark ring
-in its respective buffer. Then it moves point forward in each window,
-one character at a time, until it reaches characters that don't match.
-Then the command exits.
-
- If point in the two windows is followed by non-matching text when
-the command starts, @kbd{M-x compare-windows} tries heuristically to
-advance up to matching text in the two windows, and then exits. So if
-you use @kbd{M-x compare-windows} repeatedly, each time it either
-skips one matching range or finds the start of another.
-
-@vindex compare-ignore-case
-@vindex compare-ignore-whitespace
- With a numeric argument, @code{compare-windows} ignores changes in
-whitespace. If the variable @code{compare-ignore-case} is
-non-@code{nil}, the comparison ignores differences in case as well.
-If the variable @code{compare-ignore-whitespace} is non-@code{nil},
-@code{compare-windows} normally ignores changes in whitespace, and a
-prefix argument turns that off.
-
-@cindex Smerge mode
-@findex smerge-mode
-@cindex failed merges
-@cindex merges, failed
-@cindex comparing 3 files (@code{diff3})
- You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor
-mode for editing output from the @command{diff3} program. This is
-typically the result of a failed merge from a version control system
-``update'' outside VC, due to conflicting changes to a file. Smerge
-mode provides commands to resolve conflicts by selecting specific
-changes.
-
-@iftex
-@xref{Emerge,,, emacs-xtra, Specialized Emacs Features},
-@end iftex
-@ifnottex
-@xref{Emerge},
-@end ifnottex
-for the Emerge facility, which provides a powerful interface for
-merging files.
-
-@node Diff Mode
-@section Diff Mode
-@cindex Diff mode
-@findex diff-mode
-@cindex patches, editing
-
- Diff mode is used for the output of @kbd{M-x diff}; it is also
-useful for editing patches and comparisons produced by the
-@command{diff} program. To select Diff mode manually, type @kbd{M-x
-diff-mode}.
-
- One general feature of Diff mode is that manual edits to the patch
-automatically correct line numbers, including those in the hunk
-header, so that you can actually apply the edited patch. Diff mode
-treats each hunk location as an ``error message,'' so that you can use
-commands such as @kbd{C-x '} to visit the corresponding source
-locations. It also provides the following commands to navigate,
-manipulate and apply parts of patches:
-
-@table @kbd
-@item M-n
-Move to the next hunk-start (@code{diff-hunk-next}).
-
-@item M-p
-Move to the previous hunk-start (@code{diff-hunk-prev}).
-
-@item M-@}
-Move to the next file-start, in a multi-file patch
-(@code{diff-file-next}).
-
-@item M-@{
-Move to the previous file-start, in a multi-file patch
-(@code{diff-file-prev}).
-
-@item M-k
-Kill the hunk at point (@code{diff-hunk-kill}).
-
-@item M-K
-In a multi-file patch, kill the current file part.
-(@code{diff-file-kill}).
-
-@item C-c C-a
-Apply this hunk to its target file (@code{diff-apply-hunk}). With a
-prefix argument of @kbd{C-u}, revert this hunk.
-
-@item C-c C-c
-Go to the source corresponding to this hunk (@code{diff-goto-source}).
-
-@item C-c C-e
-Start an Ediff session with the patch (@code{diff-ediff-patch}).
-@xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.
-
-@item C-c C-n
-Restrict the view to the current hunk (@code{diff-restrict-view}).
-@xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the
-view to the current patch of a multiple file patch. To widen again,
-use @kbd{C-x n w}.
-
-@item C-c C-r
-Reverse the direction of comparison for the entire buffer
-(@code{diff-reverse-direction}).
-
-@item C-c C-s
-Split the hunk at point (@code{diff-split-hunk}). This is for
-manually editing patches, and only works with the unified diff format.
-
-@item C-c C-u
-Convert the entire buffer to unified format
-(@code{diff-context->unified}). With a prefix argument, convert
-unified format to context format. In Transient Mark mode, when the
-mark is active, this command operates only on the region.
-
-@item C-c C-w
-Refine the current hunk so that it disregards changes in whitespace
-(@code{diff-refine-hunk}).
-@end table
-
- @kbd{C-x 4 a} in Diff mode operates on behalf of the target file,
-but gets the function name from the patch itself. @xref{Change Log}.
-This is useful for making log entries for functions that are deleted
-by the patch.
-
-@node Misc File Ops
-@section Miscellaneous File Operations
-
- Emacs has commands for performing many other operations on files.
-All operate on one file; they do not accept wildcard file names.
-
-@findex view-file
-@cindex viewing
-@cindex View mode
-@cindex mode, View
- @kbd{M-x view-file} allows you to scan or read a file by sequential
-screenfuls. It reads a file name argument using the minibuffer. After
-reading the file into an Emacs buffer, @code{view-file} displays the
-beginning. You can then type @key{SPC} to scroll forward one windowful,
-or @key{DEL} to scroll backward. Various other commands are provided
-for moving around in the file, but none for changing it; type @kbd{?}
-while viewing for a list of them. They are mostly the same as normal
-Emacs cursor motion commands. To exit from viewing, type @kbd{q}.
-The commands for viewing are defined by a special minor mode called View
-mode.
-
- A related command, @kbd{M-x view-buffer}, views a buffer already present
-in Emacs. @xref{Misc Buffer}.
-
-@kindex C-x i
-@findex insert-file
- @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the
-contents of the specified file into the current buffer at point,
-leaving point unchanged before the contents and the mark after them.
-
-@findex insert-file-literally
- @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file},
-except the file is inserted ``literally'': it is treated as a sequence
-of @acronym{ASCII} characters with no special encoding or conversion,
-similar to the @kbd{M-x find-file-literally} command
-(@pxref{Visiting}).
-
-@findex write-region
- @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
-copies the contents of the region into the specified file. @kbd{M-x
-append-to-file} adds the text of the region to the end of the
-specified file. @xref{Accumulating Text}. The variable
-@code{write-region-inhibit-fsync} applies to these commands, as well
-as saving files; see @ref{Customize Save}.
-
-@findex delete-file
-@cindex deletion (of files)
- @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
-command in the shell. If you are deleting many files in one directory, it
-may be more convenient to use Dired (@pxref{Dired}).
-
-@findex rename-file
- @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
-the minibuffer, then renames file @var{old} as @var{new}. If the file name
-@var{new} already exists, you must confirm with @kbd{yes} or renaming is not
-done; this is because renaming causes the old meaning of the name @var{new}
-to be lost. If @var{old} and @var{new} are on different file systems, the
-file @var{old} is copied and deleted.
-
- If the argument @var{new} is just a directory name, the real new
-name is in that directory, with the same non-directory component as
-@var{old}. For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET}
-renames @file{~/foo} to @file{/tmp/foo}. The same rule applies to all
-the remaining commands in this section. All of them ask for
-confirmation when the new file name already exists, too.
-
-@findex add-name-to-file
-@cindex hard links (creation)
- The similar command @kbd{M-x add-name-to-file} is used to add an
-additional name to an existing file without removing its old name.
-The new name is created as a ``hard link'' to the existing file.
-The new name must belong on the same file system that the file is on.
-On MS-Windows, this command works only if the file resides in an NTFS
-file system. On MS-DOS, it works by copying the file.
-
-@findex copy-file
-@cindex copying files
- @kbd{M-x copy-file} reads the file @var{old} and writes a new file
-named @var{new} with the same contents.
-
-@findex make-symbolic-link
-@cindex symbolic links (creation)
- @kbd{M-x make-symbolic-link} reads two file names @var{target} and
-@var{linkname}, then creates a symbolic link named @var{linkname},
-which points at @var{target}. The effect is that future attempts to
-open file @var{linkname} will refer to whatever file is named
-@var{target} at the time the opening is done, or will get an error if
-the name @var{target} is nonexistent at that time. This command does
-not expand the argument @var{target}, so that it allows you to specify
-a relative name as the target of the link.
-
- Not all systems support symbolic links; on systems that don't
-support them, this command is not defined.
-
-@node Compressed Files
-@section Accessing Compressed Files
-@cindex compression
-@cindex uncompression
-@cindex Auto Compression mode
-@cindex mode, Auto Compression
-@pindex gzip
-
- Emacs automatically uncompresses compressed files when you visit
-them, and automatically recompresses them if you alter them and save
-them. Emacs recognizes compressed files by their file names. File
-names ending in @samp{.gz} indicate a file compressed with
-@code{gzip}. Other endings indicate other compression programs.
-
- Automatic uncompression and compression apply to all the operations in
-which Emacs uses the contents of a file. This includes visiting it,
-saving it, inserting its contents into a buffer, loading it, and byte
-compiling it.
-
-@findex auto-compression-mode
-@vindex auto-compression-mode
- To disable this feature, type the command @kbd{M-x
-auto-compression-mode}. You can disable it permanently by
-customizing the variable @code{auto-compression-mode}.
-
-@node File Archives
-@section File Archives
-@cindex mode, tar
-@cindex Tar mode
-@cindex file archives
-
- A file whose name ends in @samp{.tar} is normally an @dfn{archive}
-made by the @code{tar} program. Emacs views these files in a special
-mode called Tar mode which provides a Dired-like list of the contents
-(@pxref{Dired}). You can move around through the list just as you
-would in Dired, and visit the subfiles contained in the archive.
-However, not all Dired commands are available in Tar mode.
-
- If Auto Compression mode is enabled (@pxref{Compressed Files}), then
-Tar mode is used also for compressed archives---files with extensions
-@samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}.
-
- The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file
-into its own buffer. You can edit it there, and if you save the
-buffer, the edited version will replace the version in the Tar buffer.
-@kbd{v} extracts a file into a buffer in View mode. @kbd{o} extracts
-the file and displays it in another window, so you could edit the file
-and operate on the archive simultaneously. @kbd{d} marks a file for
-deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in
-Dired. @kbd{C} copies a file from the archive to disk and @kbd{R}
-renames a file within the archive. @kbd{g} reverts the buffer from
-the archive on disk.
-
- The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission
-bits, group, and owner, respectively.
-
- If your display supports colors and the mouse, moving the mouse
-pointer across a file name highlights that file name, indicating that
-you can click on it. Clicking @kbd{Mouse-2} on the highlighted file
-name extracts the file into a buffer and displays that buffer.
-
- Saving the Tar buffer writes a new version of the archive to disk with
-the changes you made to the components.
-
- You don't need the @code{tar} program to use Tar mode---Emacs reads
-the archives directly. However, accessing compressed archives
-requires the appropriate uncompression program.
-
-@cindex Archive mode
-@cindex mode, archive
-@cindex @code{arc}
-@cindex @code{jar}
-@cindex @code{zip}
-@cindex @code{lzh}
-@cindex @code{zoo}
-@pindex arc
-@pindex jar
-@pindex zip
-@pindex lzh
-@pindex zoo
-@cindex Java class archives
-@cindex unzip archives
- A separate but similar Archive mode is used for archives produced by
-the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip}, and
-@code{zoo}, which have extensions corresponding to the program names.
-Archive mode also works for those @code{exe} files that are
-self-extracting executables.
-
- The key bindings of Archive mode are similar to those in Tar mode,
-with the addition of the @kbd{m} key which marks a file for subsequent
-operations, and @kbd{M-@key{DEL}} which unmarks all the marked files.
-Also, the @kbd{a} key toggles the display of detailed file
-information, for those archive types where it won't fit in a single
-line. Operations such as renaming a subfile, or changing its mode or
-owner, are supported only for some of the archive formats.
-
- Unlike Tar mode, Archive mode runs the archiving program to unpack
-and repack archives. Details of the program names and their options
-can be set in the @samp{Archive} Customize group. However, you don't
-need these programs to look at the archive table of contents, only to
-extract or manipulate the subfiles in the archive.
-
-@node Remote Files
-@section Remote Files
-
-@cindex Tramp
-@cindex FTP
-@cindex remote file access
- You can refer to files on other machines using a special file name
-syntax:
-
-@example
-@group
-/@var{host}:@var{filename}
-/@var{user}@@@var{host}:@var{filename}
-/@var{user}@@@var{host}#@var{port}:@var{filename}
-/@var{method}:@var{user}@@@var{host}:@var{filename}
-/@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename}
-@end group
-@end example
-
-@noindent
-To carry out this request, Emacs uses either the FTP program or a
-remote-login program such as @command{ssh}, @command{rlogin}, or
-@command{telnet}. You can always specify in the file name which
-method to use---for example,
-@file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, whereas
-@file{/ssh:@var{user}@@@var{host}:@var{filename}} uses @command{ssh}.
-When you don't specify a method in the file name, Emacs chooses
-the method as follows:
-
-@enumerate
-@item
-If the host name starts with @samp{ftp.} (with dot), then Emacs uses
-FTP.
-@item
-If the user name is @samp{ftp} or @samp{anonymous}, then Emacs uses
-FTP.
-@item
-Otherwise, Emacs uses @command{ssh}.
-@end enumerate
-
-@noindent
-Remote file access through FTP is handled by the Ange-FTP package, which
-is documented in the following. Remote file access through the other
-methods is handled by the Tramp package, which has its own manual.
-@xref{Top, The Tramp Manual,, tramp, The Tramp Manual}.
-
-When the Ange-FTP package is used, Emacs logs in through FTP using your
-user name or the name @var{user}. It may ask you for a password from
-time to time; this is used for logging in on @var{host}. The form using
-@var{port} allows you to access servers running on a non-default TCP
-port.
-
-@cindex backups for remote files
-@vindex ange-ftp-make-backup-files
- If you want to disable backups for remote files, set the variable
-@code{ange-ftp-make-backup-files} to @code{nil}.
-
- By default, the auto-save files (@pxref{Auto Save Files}) for remote
-files are made in the temporary file directory on the local machine.
-This is achieved using the variable @code{auto-save-file-name-transforms}.
-
-@cindex ange-ftp
-@vindex ange-ftp-default-user
-@cindex user name for remote file access
- Normally, if you do not specify a user name in a remote file name,
-that means to use your own user name. But if you set the variable
-@code{ange-ftp-default-user} to a string, that string is used instead.
-
-@cindex anonymous FTP
-@vindex ange-ftp-generate-anonymous-password
- To visit files accessible by anonymous FTP, you use special user
-names @samp{anonymous} or @samp{ftp}. Passwords for these user names
-are handled specially. The variable
-@code{ange-ftp-generate-anonymous-password} controls what happens: if
-the value of this variable is a string, then that string is used as
-the password; if non-@code{nil} (the default), then the value of
-@code{user-mail-address} is used; if @code{nil}, then Emacs prompts
-you for a password as usual.
-
-@cindex firewall, and accessing remote files
-@cindex gateway, and remote file access with @code{ange-ftp}
-@vindex ange-ftp-smart-gateway
-@vindex ange-ftp-gateway-host
- Sometimes you may be unable to access files on a remote machine
-because a @dfn{firewall} in between blocks the connection for security
-reasons. If you can log in on a @dfn{gateway} machine from which the
-target files @emph{are} accessible, and whose FTP server supports
-gatewaying features, you can still use remote file names; all you have
-to do is specify the name of the gateway machine by setting the
-variable @code{ange-ftp-gateway-host}, and set
-@code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able
-to make remote file names work, but the procedure is complex. You can
-read the instructions by typing @kbd{M-x finder-commentary @key{RET}
-ange-ftp @key{RET}}.
-
-@vindex file-name-handler-alist
-@cindex disabling remote files
- You can entirely turn off the FTP file name feature by removing the
-entries @code{ange-ftp-completion-hook-function} and
-@code{ange-ftp-hook-function} from the variable
-@code{file-name-handler-alist}. You can turn off the feature in
-individual cases by quoting the file name with @samp{/:} (@pxref{Quoted
-File Names}).
-
-@node Quoted File Names
-@section Quoted File Names
-
-@cindex quoting file names
-@cindex file names, quote special characters
- You can @dfn{quote} an absolute file name to prevent special
-characters and syntax in it from having their special effects.
-The way to do this is to add @samp{/:} at the beginning.
-
- For example, you can quote a local file name which appears remote, to
-prevent it from being treated as a remote file name. Thus, if you have
-a directory named @file{/foo:} and a file named @file{bar} in it, you
-can refer to that file in Emacs as @samp{/:/foo:/bar}.
-
- @samp{/:} can also prevent @samp{~} from being treated as a special
-character for a user's home directory. For example, @file{/:/tmp/~hack}
-refers to a file whose name is @file{~hack} in directory @file{/tmp}.
-
- Quoting with @samp{/:} is also a way to enter in the minibuffer a
-file name that contains @samp{$}. In order for this to work, the
-@samp{/:} must be at the beginning of the minibuffer contents. (You
-can also double each @samp{$}; see @ref{File Names with $}.)
-
- You can also quote wildcard characters with @samp{/:}, for visiting.
-For example, @file{/:/tmp/foo*bar} visits the file
-@file{/tmp/foo*bar}.
-
- Another method of getting the same result is to enter
-@file{/tmp/foo[*]bar}, which is a wildcard specification that matches
-only @file{/tmp/foo*bar}. However, in many cases there is no need to
-quote the wildcard characters because even unquoted they give the
-right result. For example, if the only file name in @file{/tmp} that
-starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar},
-then specifying @file{/tmp/foo*bar} will visit only
-@file{/tmp/foo*bar}.
-
-@node File Name Cache
-@section File Name Cache
-
-@cindex file name caching
-@cindex cache of file names
-@pindex find
-@kindex C-@key{TAB}
-@findex file-cache-minibuffer-complete
- You can use the @dfn{file name cache} to make it easy to locate a
-file by name, without having to remember exactly where it is located.
-When typing a file name in the minibuffer, @kbd{C-@key{tab}}
-(@code{file-cache-minibuffer-complete}) completes it using the file
-name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the
-possible completions of what you had originally typed. (However, note
-that the @kbd{C-@key{tab}} character cannot be typed on most text-only
-terminals.)
-
- The file name cache does not fill up automatically. Instead, you
-load file names into the cache using these commands:
-
-@findex file-cache-add-directory
-@table @kbd
-@item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET}
-Add each file name in @var{directory} to the file name cache.
-@item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET}
-Add each file name in @var{directory} and all of its nested
-subdirectories to the file name cache.
-@item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET}
-Add each file name in @var{directory} and all of its nested
-subdirectories to the file name cache, using @command{locate} to find
-them all.
-@item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET}
-Add each file name in each directory listed in @var{variable}
-to the file name cache. @var{variable} should be a Lisp variable
-such as @code{load-path} or @code{exec-path}, whose value is a list
-of directory names.
-@item M-x file-cache-clear-cache @key{RET}
-Clear the cache; that is, remove all file names from it.
-@end table
-
- The file name cache is not persistent: it is kept and maintained
-only for the duration of the Emacs session. You can view the contents
-of the cache with the @code{file-cache-display} command.
-
-@node File Conveniences
-@section Convenience Features for Finding Files
-
- In this section, we introduce some convenient facilities for finding
-recently-opened files, reading file names from a buffer, and viewing
-image files.
-
-@findex recentf-mode
-@vindex recentf-mode
-@findex recentf-save-list
-@findex recentf-edit-list
- If you enable Recentf mode, with @kbd{M-x recentf-mode}, the
-@samp{File} menu includes a submenu containing a list of recently
-opened files. @kbd{M-x recentf-save-list} saves the current
-@code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list}
-edits it.
-
- The @kbd{M-x ffap} command generalizes @code{find-file} with more
-powerful heuristic defaults (@pxref{FFAP}), often based on the text at
-point. Partial Completion mode offers other features extending
-@code{find-file}, which can be used with @code{ffap}.
-@xref{Completion Options}.
-
-@findex image-mode
-@findex image-toggle-display
-@cindex images, viewing
- Visiting image files automatically selects Image mode. This major
-mode allows you to toggle between displaying the file as an image in
-the Emacs buffer, and displaying its underlying text representation,
-using the command @kbd{C-c C-c} (@code{image-toggle-display}). This
-works only when Emacs can display the specific image type. If the
-displayed image is wider or taller than the frame, the usual point
-motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts
-of the image to be displayed.
-
-@findex thumbs-mode
-@findex mode, thumbs
- See also the Image-Dired package (@pxref{Image-Dired}) for viewing
-images as thumbnails.
-
-@node Filesets
-@section Filesets
-@cindex filesets
-
-@findex filesets-init
- If you regularly edit a certain group of files, you can define them
-as a @dfn{fileset}. This lets you perform certain operations, such as
-visiting, @code{query-replace}, and shell commands on all the files
-at once. To make use of filesets, you must first add the expression
-@code{(filesets-init)} to your @file{.emacs} file (@pxref{Init File}).
-This adds a @samp{Filesets} menu to the menu bar.
-
-@findex filesets-add-buffer
-@findex filesets-remove-buffer
- The simplest way to define a fileset is by adding files to it one
-at a time. To add a file to fileset @var{name}, visit the file and
-type @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If
-there is no fileset @var{name}, this creates a new one, which
-initially creates only the current file. The command @kbd{M-x
-filesets-remove-buffer} removes the current file from a fileset.
-
- You can also edit the list of filesets directly, with @kbd{M-x
-filesets-edit} (or by choosing @samp{Edit Filesets} from the
-@samp{Filesets} menu). The editing is performed in a Customize buffer
-(@pxref{Easy Customization}). Filesets need not be a simple list of
-files---you can also define filesets using regular expression matching
-file names. Some examples of these more complicated filesets are
-shown in the Customize buffer. Remember to select @samp{Save for
-future sessions} if you want to use the same filesets in future Emacs
-sessions.
-
- You can use the command @kbd{M-x filesets-open} to visit all the
-files in a fileset, and @kbd{M-x filesets-close} to close them. Use
-@kbd{M-x filesets-run-cmd} to run a shell command on all the files in
-a fileset. These commands are also available from the @samp{Filesets}
-menu, where each existing fileset is represented by a submenu.
-
-@ignore
- arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Fixit, Keyboard Macros, Search, Top
-@chapter Commands for Fixing Typos
-@cindex typos, fixing
-@cindex mistakes, correcting
-
- In this chapter we describe the commands that are especially useful for
-the times when you catch a mistake in your text just after you have made
-it, or change your mind while composing text on the fly.
-
- The most fundamental command for correcting erroneous editing is the
-undo command, @kbd{C-x u} or @kbd{C-_} or @kbd{C-/}. This command
-undoes a single command (usually), a part of a command (in the case of
-@code{query-replace}), or several consecutive self-inserting
-characters. Consecutive repetitions of the undo command undo earlier
-and earlier changes, back to the limit of the undo information
-available. @xref{Undo}, for more information.
-
-@menu
-* Undo:: The Undo commands.
-* Kill Errors:: Commands to kill a batch of recently entered text.
-* Transpose:: Exchanging two characters, words, lines, lists...
-* Fixing Case:: Correcting case of last word entered.
-* Spelling:: Apply spelling checker to a word, or a whole file.
-@end menu
-
-@node Undo
-@section Undo
-@cindex undo
-@cindex changes, undoing
-
- The @dfn{undo} commands undo recent changes in the buffer's text.
-Each buffer records changes individually, and the undo command always
-applies to the current buffer. You can undo all the changes in a
-buffer for as far as back these records go. Usually each editing
-command makes a separate entry in the undo records, but some commands
-such as @code{query-replace} divide their changes into multiple
-entries for flexibility in undoing. Meanwhile, self-inserting
-characters are usually grouped to make undoing less tedious.
-
-@table @kbd
-@item C-x u
-@itemx C-_
-@itemx C-/
-Undo one entry in the current buffer's undo records (@code{undo}).
-@end table
-
-@kindex C-x u
-@kindex C-_
-@kindex C-/
-@findex undo
- To begin to undo, type the command @kbd{C-x u} (or its aliases,
-@kbd{C-_} or @kbd{C-/}). This undoes the most recent change in the
-buffer, and moves point back to where it was before that change.
-
- Consecutive repetitions of @kbd{C-x u} (or its aliases) undo earlier
-and earlier changes in the current buffer, back to the limit of the
-current buffer's undo records. If all the recorded changes have
-already been undone, the undo command just signals an error.
-
- If you notice that a buffer has been modified accidentally, the
-easiest way to recover is to type @kbd{C-_} repeatedly until the stars
-disappear from the front of the mode line. At this time, all the
-modifications you made have been canceled. Whenever an undo command
-makes the stars disappear from the mode line, it means that the buffer
-contents are the same as they were when the file was last read in or
-saved.
-
- If you do not remember whether you changed the buffer deliberately,
-type @kbd{C-_} once. When you see the last change you made undone, you
-will see whether it was an intentional change. If it was an accident,
-leave it undone. If it was deliberate, redo the change as described
-below.
-
-@findex undo-only
- Any command other than an undo command breaks the sequence of undo
-commands. Starting from that moment, the previous undo commands
-become ordinary changes that you can undo. Thus, to redo changes you
-have undone, type @kbd{C-f} or any other command that will harmlessly
-break the sequence of undoing, then type undo commands again. On the
-other hand, if you want to resume undoing, without redoing previous
-undo commands, use @kbd{M-x undo-only}. This is like @code{undo}, but
-will not redo changes you have just undone.
-
-@cindex selective undo
-@kindex C-u C-x u
- Ordinary undo applies to all changes made in the current buffer. You
-can also perform @dfn{selective undo}, limited to the region.
-
- To do this, specify the region you want, then run the @code{undo}
-command with a prefix argument (the value does not matter): @kbd{C-u
-C-x u} or @kbd{C-u C-_}. This undoes the most recent change in the
-region. To undo further changes in the same region, repeat the
-@code{undo} command (no prefix argument is needed). In Transient Mark
-mode (@pxref{Transient Mark}), any use of @code{undo} when there is an
-active region performs selective undo; you do not need a prefix
-argument.
-
- Some specialized buffers do not make undo records. Buffers
-whose names start with spaces never do; these buffers are used
-internally by Emacs and its extensions to hold text that users don't
-normally look at or edit.
-
-@vindex undo-limit
-@vindex undo-strong-limit
-@vindex undo-outer-limit
-@cindex undo limit
- When the undo records for a buffer becomes too large, Emacs
-discards the oldest undo records from time to time (during garbage
-collection). You can specify how much undo records to keep by
-setting three variables: @code{undo-limit}, @code{undo-strong-limit},
-and @code{undo-outer-limit}. Their values are expressed in units of
-bytes of space.
-
- The variable @code{undo-limit} sets a soft limit: Emacs keeps undo
-data for enough commands to reach this size, and perhaps exceed it,
-but does not keep data for any earlier commands beyond that. Its
-default value is 20000. The variable @code{undo-strong-limit} sets a
-stricter limit: a previous command (not the most recent one) which
-pushes the size past this amount is itself forgotten. The default
-value of @code{undo-strong-limit} is 30000.
-
- Regardless of the values of those variables, the most recent change
-is never discarded unless it gets bigger than @code{undo-outer-limit}
-(normally 3,000,000). At that point, Emacs discards the undo data and
-warns you about it. This is the only situation in which you cannot
-undo the last command. If this happens, you can increase the value of
-@code{undo-outer-limit} to make it even less likely to happen in the
-future. But if you didn't expect the command to create such large
-undo data, then it is probably a bug and you should report it.
-@xref{Bugs,, Reporting Bugs}.
-
- The reason the @code{undo} command has three key bindings, @kbd{C-x
-u}, @kbd{C-_} and @kbd{C-/}, is that it is worthy of a
-single-character key, but @kbd{C-x u} is more straightforward for
-beginners to remember and type. Meanwhile, @kbd{C--} on a text-only
-terminal is really @kbd{C-_}, which makes it a natural and easily
-typed binding for undoing.
-
-@node Kill Errors
-@section Killing Your Mistakes
-
-@table @kbd
-@item @key{DEL}
-Delete last character (@code{delete-backward-char}).
-@item M-@key{DEL}
-Kill last word (@code{backward-kill-word}).
-@item C-x @key{DEL}
-Kill to beginning of sentence (@code{backward-kill-sentence}).
-@end table
-
- The @key{DEL} character (@code{delete-backward-char}) is the most
-important correction command. It deletes the character before point.
-When @key{DEL} follows a self-inserting character command, you can think
-of it as canceling that command. However, avoid the confusion of thinking
-of @key{DEL} as a general way to cancel a command!
-
- When your mistake is longer than a couple of characters, it might be
-more convenient to use @kbd{M-@key{DEL}} or @kbd{C-x @key{DEL}}.
-@kbd{M-@key{DEL}} kills back to the start of the last word, and @kbd{C-x
-@key{DEL}} kills back to the start of the last sentence. @kbd{C-x
-@key{DEL}} is particularly useful when you change your mind about the
-phrasing of the text you are writing. @kbd{M-@key{DEL}} and @kbd{C-x
-@key{DEL}} save the killed text for @kbd{C-y} and @kbd{M-y} to
-retrieve. @xref{Yanking}.@refill
-
- @kbd{M-@key{DEL}} is often useful even when you have typed only a few
-characters wrong, if you know you are confused in your typing and aren't
-sure exactly what you typed. At such a time, you cannot correct with
-@key{DEL} except by looking at the screen to see what you did. Often it
-requires less thought to kill the whole word and start again.
-
-@node Transpose
-@section Transposing Text
-
-@table @kbd
-@item C-t
-Transpose two characters (@code{transpose-chars}).
-@item M-t
-Transpose two words (@code{transpose-words}).
-@item C-M-t
-Transpose two balanced expressions (@code{transpose-sexps}).
-@item C-x C-t
-Transpose two lines (@code{transpose-lines}).
-@end table
-
-@kindex C-t
-@findex transpose-chars
- The common error of transposing two characters can be fixed, when they
-are adjacent, with the @kbd{C-t} command (@code{transpose-chars}). Normally,
-@kbd{C-t} transposes the two characters on either side of point. When
-given at the end of a line, rather than transposing the last character of
-the line with the newline, which would be useless, @kbd{C-t} transposes the
-last two characters on the line. So, if you catch your transposition error
-right away, you can fix it with just a @kbd{C-t}. If you don't catch it so
-fast, you must move the cursor back between the two transposed
-characters before you type @kbd{C-t}. If you transposed a space with
-the last character of the word before it, the word motion commands are
-a good way of getting there. Otherwise, a reverse search (@kbd{C-r})
-is often the best way. @xref{Search}.
-
-@kindex C-x C-t
-@findex transpose-lines
-@kindex M-t
-@findex transpose-words
-@c Don't index C-M-t and transpose-sexps here, they are indexed in
-@c programs.texi, in the "List Commands" node.
-@c @kindex C-M-t
-@c @findex transpose-sexps
- @kbd{M-t} transposes the word before point with the word after point
-(@code{transpose-words}). It moves point forward over a word,
-dragging the word preceding or containing point forward as well. The
-punctuation characters between the words do not move. For example,
-@w{@samp{FOO, BAR}} transposes into @w{@samp{BAR, FOO}} rather than
-@samp{@w{BAR FOO,}}.
-
- @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for
-transposing two expressions (@pxref{Expressions}), and @kbd{C-x C-t}
-(@code{transpose-lines}) exchanges lines. They work like @kbd{M-t}
-except as regards what units of text they transpose.
-
- A numeric argument to a transpose command serves as a repeat count: it
-tells the transpose command to move the character (word, expression, line)
-before or containing point across several other characters (words,
-expressions, lines). For example, @kbd{C-u 3 C-t} moves the character before
-point forward across three other characters. It would change
-@samp{f@point{}oobar} into @samp{oobf@point{}ar}. This is equivalent to
-repeating @kbd{C-t} three times. @kbd{C-u - 4 M-t} moves the word
-before point backward across four words. @kbd{C-u - C-M-t} would cancel
-the effect of plain @kbd{C-M-t}.@refill
-
- A numeric argument of zero is assigned a special meaning (because
-otherwise a command with a repeat count of zero would do nothing): to
-transpose the character (word, expression, line) ending after point
-with the one ending after the mark.
-
-@node Fixing Case
-@section Case Conversion
-
-@table @kbd
-@item M-- M-l
-Convert last word to lower case. Note @kbd{Meta--} is Meta-minus.
-@item M-- M-u
-Convert last word to all upper case.
-@item M-- M-c
-Convert last word to lower case with capital initial.
-@end table
-
-@kindex M-@t{-} M-l
-@kindex M-@t{-} M-u
-@kindex M-@t{-} M-c
- A very common error is to type words in the wrong case. Because of this,
-the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a
-special feature when used with a negative argument: they do not move the
-cursor. As soon as you see you have mistyped the last word, you can simply
-case-convert it and go on typing. @xref{Case}.@refill
-
-@node Spelling
-@section Checking and Correcting Spelling
-@cindex spelling, checking and correcting
-@cindex checking spelling
-@cindex correcting spelling
-
- This section describes the commands to check the spelling of a single
-word or of a portion of a buffer. These commands work with the spelling
-checker programs Aspell and Ispell, which are not part of Emacs.
-@ifnottex
-@xref{Top, Aspell,, aspell, The Aspell Manual}.
-@end ifnottex
-
-@table @kbd
-@item M-x flyspell-mode
-Enable Flyspell mode, which highlights all misspelled words.
-@item M-x flyspell-prog-mode
-Enable Flyspell mode for comments and strings only.
-@item M-$
-Check and correct spelling of the word at point (@code{ispell-word}).
-@item M-@key{TAB}
-@itemx @key{ESC} @key{TAB}
-Complete the word before point based on the spelling dictionary
-(@code{ispell-complete-word}).
-@item M-x ispell
-Spell-check the active region or the current buffer.
-@item M-x ispell-buffer
-Check and correct spelling of each word in the buffer.
-@item M-x ispell-region
-Check and correct spelling of each word in the region.
-@item M-x ispell-message
-Check and correct spelling of each word in a draft mail message,
-excluding cited material.
-@item M-x ispell-change-dictionary @key{RET} @var{dict} @key{RET}
-Restart the Aspell or Ispell process, using @var{dict} as the dictionary.
-@item M-x ispell-kill-ispell
-Kill the Aspell or Ispell subprocess.
-@end table
-
-@cindex Flyspell mode
-@findex flyspell-mode
- Flyspell mode is a fully-automatic way to check spelling as you edit
-in Emacs. It operates by checking words as you change or insert them.
-When it finds a word that it does not recognize, it highlights that
-word. This does not interfere with your editing, but when you see the
-highlighted word, you can move to it and fix it. Type @kbd{M-x
-flyspell-mode} to enable or disable this mode in the current buffer.
-
- When Flyspell mode highlights a word as misspelled, you can click on
-it with @kbd{Mouse-2} to display a menu of possible corrections and
-actions. You can also correct the word by editing it manually in any
-way you like.
-
-@findex flyspell-prog-mode
-Flyspell Prog mode works just like ordinary Flyspell mode, except that
-it only checks words in comments and string constants. This feature
-is useful for editing programs. Type @kbd{M-x flyspell-prog-mode} to
-enable or disable this mode in the current buffer.
-
- The other Emacs spell-checking features check or look up words when
-you give an explicit command to do so.
-
-@kindex M-$
-@findex ispell-word
- To check the spelling of the word around or before point, and
-optionally correct it as well, use the command @kbd{M-$}
-(@code{ispell-word}). If the word is not correct, the command offers
-you various alternatives for what to do about it.
-
-@findex ispell-buffer
-@findex ispell-region
- To check the entire current buffer, use @kbd{M-x ispell-buffer}. Use
-@kbd{M-x ispell-region} to check just the current region. To check
-spelling in an email message you are writing, use @kbd{M-x
-ispell-message}; that command checks the whole buffer, except for
-material that is indented or appears to be cited from other messages.
-
-@findex ispell
-@cindex spell-checking the active region
- The @kbd{M-x ispell} command spell-checks the active region if the
-Transient Mark mode is on (@pxref{Transient Mark}), otherwise it
-spell-checks the current buffer.
-
- Each time these commands encounter an incorrect word, they ask you
-what to do. They display a list of alternatives, usually including
-several ``near-misses''---words that are close to the word being
-checked. Then you must type a single-character response. Here are
-the valid responses:
-
-@table @kbd
-@item @key{SPC}
-Skip this word---continue to consider it incorrect, but don't change it
-here.
-
-@item r @var{new} @key{RET}
-Replace the word (just this time) with @var{new}. (The replacement
-string will be rescanned for more spelling errors.)
-
-@item R @var{new} @key{RET}
-Replace the word with @var{new}, and do a @code{query-replace} so you
-can replace it elsewhere in the buffer if you wish. (The replacements
-will be rescanned for more spelling errors.)
-
-@item @var{digit}
-Replace the word (just this time) with one of the displayed
-near-misses. Each near-miss is listed with a digit; type that digit to
-select it.
-
-@item a
-Accept the incorrect word---treat it as correct, but only in this
-editing session.
-
-@item A
-Accept the incorrect word---treat it as correct, but only in this
-editing session and for this buffer.
-
-@item i
-Insert this word in your private dictionary file so that Aspell or Ispell will
-consider it correct from now on, even in future sessions.
-
-@item u
-Insert the lower-case version of this word in your private dic@-tion@-ary
-file.
-
-@item m
-Like @kbd{i}, but you can also specify dictionary completion
-information.
-
-@item l @var{word} @key{RET}
-Look in the dictionary for words that match @var{word}. These words
-become the new list of ``near-misses''; you can select one of them as
-the replacement by typing a digit. You can use @samp{*} in @var{word} as a
-wildcard.
-
-@item C-g
-Quit interactive spell checking, leaving point at the word that was
-being checked. You can restart checking again afterward with @kbd{C-u
-M-$}.
-
-@item X
-Same as @kbd{C-g}.
-
-@item x
-Quit interactive spell checking and move point back to where it was
-when you started spell checking.
-
-@item q
-Quit interactive spell checking and kill the Ispell subprocess.
-
-@item C-l
-Refresh the screen.
-
-@item C-z
-This key has its normal command meaning (suspend Emacs or iconify this
-frame).
-
-@item ?
-Show the list of options.
-@end table
-
-@findex ispell-complete-word
- The command @code{ispell-complete-word}, which is bound to the key
-@kbd{M-@key{TAB}} in Text mode and related modes, shows a list of
-completions based on spelling correction. Insert the beginning of a
-word, and then type @kbd{M-@key{TAB}}; the command displays a
-completion list window. (If your window manager intercepts
-@kbd{M-@key{TAB}}, type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.) To
-choose one of the completions listed, click @kbd{Mouse-2} or
-@kbd{Mouse-1} fast on it, or move the cursor there in the completions
-window and type @key{RET}. @xref{Text Mode}.
-
-@ignore
-@findex reload-ispell
- The first time you use any of the spell checking commands, it starts
-an Ispell subprocess. The first thing the subprocess does is read your
-private dictionary, which defaults to the file @file{~/ispell.words}.
-Words that you ``insert'' with the @kbd{i} command are added to that
-file, but not right away---only at the end of the interactive
-replacement procedure. Use the @kbd{M-x reload-ispell} command to
-reload your private dictionary if you edit the file outside of Ispell.
-@end ignore
-
-@cindex @code{ispell} program
-@findex ispell-kill-ispell
- Once started, the Aspell or Ispell subprocess continues to run
-(waiting for something to do), so that subsequent spell checking
-commands complete more quickly. If you want to get rid of the
-process, use @kbd{M-x ispell-kill-ispell}. This is not usually
-necessary, since the process uses no time except when you do spelling
-correction.
-
-@vindex ispell-dictionary
- Ispell and Aspell use two dictionaries together for spell checking: the
-standard dictionary and your private dictionary. The variable
-@code{ispell-dictionary} specifies the file name to use for the
-standard dictionary; a value of @code{nil} selects the default
-dictionary. The command @kbd{M-x ispell-change-dictionary} sets this
-variable and then restarts the subprocess, so that it will use
-a different standard dictionary.
-
-@vindex ispell-complete-word-dict
- Aspell and Ispell use a separate dictionary for word completion.
-The variable @code{ispell-complete-word-dict} specifies the file name
-of this dictionary. The completion dictionary must be different
-because it cannot use root and affix information. For some languages
-there is a spell checking dictionary but no word completion
-dictionary.
-
-@ignore
- arch-tag: 3359a443-96ed-448f-9f05-c8111ba8eac0
-@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 This is part of the Emacs manual.
-@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@c
-@c This file is included either in emacs-xtra.texi (when producing the
-@c printed version) or in the main Emacs manual (for the on-line version).
-@node Fortran
-@section Fortran Mode
-@cindex Fortran mode
-@cindex mode, Fortran
-
- Fortran mode provides special motion commands for Fortran statements
-and subprograms, and indentation commands that understand Fortran
-conventions of nesting, line numbers and continuation statements.
-Fortran mode has support for Auto Fill mode that breaks long lines into
-proper Fortran continuation lines.
-
- Special commands for comments are provided because Fortran comments
-are unlike those of other languages. Built-in abbrevs optionally save
-typing when you insert Fortran keywords.
-
- Use @kbd{M-x fortran-mode} to switch to this major mode. This
-command runs the hook @code{fortran-mode-hook}.
-@iftex
-@xref{Hooks,,, emacs, the Emacs Manual}.
-@end iftex
-@ifnottex
-@xref{Hooks}.
-@end ifnottex
-
-@cindex Fortran77 and Fortran90
-@findex f90-mode
-@findex fortran-mode
- Fortran mode is meant for editing Fortran77 ``fixed format'' (and also
-``tab format'') source code. For editing the modern Fortran90 or
-Fortran95 ``free format'' source code, use F90 mode (@code{f90-mode}).
-Emacs normally uses Fortran mode for files with extension @samp{.f},
-@samp{.F} or @samp{.for}, and F90 mode for the extension @samp{.f90} and
-@samp{.f95}. GNU Fortran supports both kinds of format.
-
-@menu
-* Motion: Fortran Motion. Moving point by statements or subprograms.
-* Indent: Fortran Indent. Indentation commands for Fortran.
-* Comments: Fortran Comments. Inserting and aligning comments.
-* Autofill: Fortran Autofill. Auto fill support for Fortran.
-* Columns: Fortran Columns. Measuring columns for valid Fortran.
-* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
-@end menu
-
-@node Fortran Motion
-@subsection Motion Commands
-
- In addition to the normal commands for moving by and operating on
-``defuns'' (Fortran subprograms---functions and subroutines, as well as
-modules for F90 mode), Fortran mode provides special commands to move by
-statements and other program units.
-
-@table @kbd
-@kindex C-c C-n @r{(Fortran mode)}
-@findex fortran-next-statement
-@findex f90-next-statement
-@item C-c C-n
-Move to the beginning of the next statement
-(@code{fortran-next-statement}/@code{f90-next-statement}).
-
-@kindex C-c C-p @r{(Fortran mode)}
-@findex fortran-previous-statement
-@findex f90-previous-statement
-@item C-c C-p
-Move to the beginning of the previous statement
-(@code{fortran-previous-statement}/@code{f90-previous-statement}).
-If there is no previous statement (i.e. if called from the first
-statement in the buffer), move to the start of the buffer.
-
-@kindex C-c C-e @r{(F90 mode)}
-@findex f90-next-block
-@item C-c C-e
-Move point forward to the start of the next code block
-(@code{f90-next-block}). A code block is a subroutine,
-@code{if}--@code{endif} statement, and so forth. This command exists
-for F90 mode only, not Fortran mode. With a numeric argument, this
-moves forward that many blocks.
-
-@kindex C-c C-a @r{(F90 mode)}
-@findex f90-previous-block
-@item C-c C-a
-Move point backward to the previous code block
-(@code{f90-previous-block}). This is like @code{f90-next-block}, but
-moves backwards.
-
-@kindex C-M-n @r{(Fortran mode)}
-@findex fortran-end-of-block
-@findex f90-end-of-block
-@item C-M-n
-Move to the end of the current code block
-(@code{fortran-end-of-block}/@code{f90-end-of-block}). With a numeric
-argument, move forward that number of blocks. The mark is set before
-moving point. The F90 mode version of this command checks for
-consistency of block types and labels (if present), but it does not
-check the outermost block since that may be incomplete.
-
-@kindex C-M-p @r{(Fortran mode)}
-@findex fortran-beginning-of-block
-@findex f90-beginning-of-block
-@item C-M-p
-Move to the start of the current code block
-(@code{fortran-beginning-of-block}/@code{f90-beginning-of-block}). This
-is like @code{fortran-end-of-block}, but moves backwards.
-@end table
-
-@node Fortran Indent
-@subsection Fortran Indentation
-
- Special commands and features are needed for indenting Fortran code in
-order to make sure various syntactic entities (line numbers, comment line
-indicators and continuation line flags) appear in the columns that are
-required for standard, fixed (or tab) format Fortran.
-
-@menu
-* Commands: ForIndent Commands. Commands for indenting and filling Fortran.
-* Contline: ForIndent Cont. How continuation lines indent.
-* Numbers: ForIndent Num. How line numbers auto-indent.
-* Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
-* Vars: ForIndent Vars. Variables controlling Fortran indent style.
-@end menu
-
-@node ForIndent Commands
-@subsubsection Fortran Indentation and Filling Commands
-
-@table @kbd
-@item C-M-j
-Break the current line at point and set up a continuation line
-(@code{fortran-split-line}).
-@item M-^
-Join this line to the previous line (@code{fortran-join-line}).
-@item C-M-q
-Indent all the lines of the subprogram point is in
-(@code{fortran-indent-subprogram}).
-@item M-q
-Fill a comment block or statement.
-@end table
-
-@kindex C-M-q @r{(Fortran mode)}
-@findex fortran-indent-subprogram
- The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command
-to reindent all the lines of the Fortran subprogram (function or
-subroutine) containing point.
-
-@kindex C-M-j @r{(Fortran mode)}
-@findex fortran-split-line
- The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits
-a line in the appropriate fashion for Fortran. In a non-comment line,
-the second half becomes a continuation line and is indented
-accordingly. In a comment line, both halves become separate comment
-lines.
-
-@kindex M-^ @r{(Fortran mode)}
-@kindex C-c C-d @r{(Fortran mode)}
-@findex fortran-join-line
- @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line},
-which joins a continuation line back to the previous line, roughly as
-the inverse of @code{fortran-split-line}. The point must be on a
-continuation line when this command is invoked.
-
-@kindex M-q @r{(Fortran mode)}
-@kbd{M-q} in Fortran mode fills the comment block or statement that
-point is in. This removes any excess statement continuations.
-
-@node ForIndent Cont
-@subsubsection Continuation Lines
-@cindex Fortran continuation lines
-
-@vindex fortran-continuation-string
- Most Fortran77 compilers allow two ways of writing continuation lines.
-If the first non-space character on a line is in column 5, then that
-line is a continuation of the previous line. We call this @dfn{fixed
-format}. (In GNU Emacs we always count columns from 0; but note that
-the Fortran standard counts from 1.) The variable
-@code{fortran-continuation-string} specifies what character to put in
-column 5. A line that starts with a tab character followed by any digit
-except @samp{0} is also a continuation line. We call this style of
-continuation @dfn{tab format}. (Fortran90 introduced ``free format,''
-with another style of continuation lines).
-
-@vindex indent-tabs-mode @r{(Fortran mode)}
-@vindex fortran-analyze-depth
-@vindex fortran-tab-mode-default
- Fortran mode can use either style of continuation line. When you
-enter Fortran mode, it tries to deduce the proper continuation style
-automatically from the buffer contents. It does this by scanning up to
-@code{fortran-analyze-depth} (default 100) lines from the start of the
-buffer. The first line that begins with either a tab character or six
-spaces determines the choice. If the scan fails (for example, if the
-buffer is new and therefore empty), the value of
-@code{fortran-tab-mode-default} (@code{nil} for fixed format, and
-non-@code{nil} for tab format) is used. @samp{/t} in the mode line
-indicates tab format is selected. Fortran mode sets the value of
-@code{indent-tabs-mode} accordingly.
-
- If the text on a line starts with the Fortran continuation marker
-@samp{$}, or if it begins with any non-whitespace character in column
-5, Fortran mode treats it as a continuation line. When you indent a
-continuation line with @key{TAB}, it converts the line to the current
-continuation style. When you split a Fortran statement with
-@kbd{C-M-j}, the continuation marker on the newline is created according
-to the continuation style.
-
- The setting of continuation style affects several other aspects of
-editing in Fortran mode. In fixed format mode, the minimum column
-number for the body of a statement is 6. Lines inside of Fortran
-blocks that are indented to larger column numbers always use only the
-space character for whitespace. In tab format mode, the minimum
-column number for the statement body is 8, and the whitespace before
-column 8 must always consist of one tab character.
-
-@node ForIndent Num
-@subsubsection Line Numbers
-
- If a number is the first non-whitespace in the line, Fortran
-indentation assumes it is a line number and moves it to columns 0
-through 4. (Columns always count from 0 in GNU Emacs.)
-
-@vindex fortran-line-number-indent
- Line numbers of four digits or less are normally indented one space.
-The variable @code{fortran-line-number-indent} controls this; it
-specifies the maximum indentation a line number can have. The default
-value of the variable is 1. Fortran mode tries to prevent line number
-digits passing column 4, reducing the indentation below the specified
-maximum if necessary. If @code{fortran-line-number-indent} has the
-value 5, line numbers are right-justified to end in column 4.
-
-@vindex fortran-electric-line-number
- Simply inserting a line number is enough to indent it according to
-these rules. As each digit is inserted, the indentation is recomputed.
-To turn off this feature, set the variable
-@code{fortran-electric-line-number} to @code{nil}.
-
-
-@node ForIndent Conv
-@subsubsection Syntactic Conventions
-
- Fortran mode assumes that you follow certain conventions that simplify
-the task of understanding a Fortran program well enough to indent it
-properly:
-
-@itemize @bullet
-@item
-Two nested @samp{do} loops never share a @samp{continue} statement.
-
-@item
-Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do}
-and others are written without embedded whitespace or line breaks.
-
-Fortran compilers generally ignore whitespace outside of string
-constants, but Fortran mode does not recognize these keywords if they
-are not contiguous. Constructs such as @samp{else if} or @samp{end do}
-are acceptable, but the second word should be on the same line as the
-first and not on a continuation line.
-@end itemize
-
-@noindent
-If you fail to follow these conventions, the indentation commands may
-indent some lines unaesthetically. However, a correct Fortran program
-retains its meaning when reindented even if the conventions are not
-followed.
-
-@node ForIndent Vars
-@subsubsection Variables for Fortran Indentation
-
-@vindex fortran-do-indent
-@vindex fortran-if-indent
-@vindex fortran-structure-indent
-@vindex fortran-continuation-indent
-@vindex fortran-check-all-num@dots{}
-@vindex fortran-minimum-statement-indent@dots{}
- Several additional variables control how Fortran indentation works:
-
-@table @code
-@item fortran-do-indent
-Extra indentation within each level of @samp{do} statement (default 3).
-
-@item fortran-if-indent
-Extra indentation within each level of @samp{if}, @samp{select case}, or
-@samp{where} statements (default 3).
-
-@item fortran-structure-indent
-Extra indentation within each level of @samp{structure}, @samp{union},
-@samp{map}, or @samp{interface} statements (default 3).
-
-@item fortran-continuation-indent
-Extra indentation for bodies of continuation lines (default 5).
-
-@item fortran-check-all-num-for-matching-do
-In Fortran77, a numbered @samp{do} statement is ended by any statement
-with a matching line number. It is common (but not compulsory) to use a
-@samp{continue} statement for this purpose. If this variable has a
-non-@code{nil} value, indenting any numbered statement must check for a
-@samp{do} that ends there. If you always end @samp{do} statements with
-a @samp{continue} line (or if you use the more modern @samp{enddo}),
-then you can speed up indentation by setting this variable to
-@code{nil}. The default is @code{nil}.
-
-@item fortran-blink-matching-if
-If this is @code{t}, indenting an @samp{endif} (or @samp{enddo}
-statement moves the cursor momentarily to the matching @samp{if} (or
-@samp{do}) statement to show where it is. The default is @code{nil}.
-
-@item fortran-minimum-statement-indent-fixed
-Minimum indentation for Fortran statements when using fixed format
-continuation line style. Statement bodies are never indented less than
-this much. The default is 6.
-
-@item fortran-minimum-statement-indent-tab
-Minimum indentation for Fortran statements for tab format continuation line
-style. Statement bodies are never indented less than this much. The
-default is 8.
-@end table
-
-The variables controlling the indentation of comments are described in
-the following section.
-
-@node Fortran Comments
-@subsection Fortran Comments
-
- The usual Emacs comment commands assume that a comment can follow a
-line of code. In Fortran77, the standard comment syntax requires an
-entire line to be just a comment. Therefore, Fortran mode replaces the
-standard Emacs comment commands and defines some new variables.
-
-@vindex fortran-comment-line-start
- Fortran mode can also handle the Fortran90 comment syntax where comments
-start with @samp{!} and can follow other text. Because only some Fortran77
-compilers accept this syntax, Fortran mode will not insert such comments
-unless you have said in advance to do so. To do this, set the variable
-@code{fortran-comment-line-start} to @samp{"!"}.
-
-@table @kbd
-@item M-;
-Align comment or insert new comment (@code{fortran-indent-comment}).
-
-@item C-x ;
-Applies to nonstandard @samp{!} comments only.
-
-@item C-c ;
-Turn all lines of the region into comments, or (with argument) turn them back
-into real code (@code{fortran-comment-region}).
-@end table
-
-@findex fortran-indent-comment
- @kbd{M-;} in Fortran mode is redefined as the command
-@code{fortran-indent-comment}. Like the usual @kbd{M-;} command, this
-recognizes any kind of existing comment and aligns its text appropriately;
-if there is no existing comment, a comment is inserted and aligned. But
-inserting and aligning comments are not the same in Fortran mode as in
-other modes.
-
- When a new comment must be inserted, if the current line is blank, a
-full-line comment is inserted. On a non-blank line, a nonstandard @samp{!}
-comment is inserted if you have said you want to use them. Otherwise a
-full-line comment is inserted on a new line before the current line.
-
- Nonstandard @samp{!} comments are aligned like comments in other
-languages, but full-line comments are different. In a standard full-line
-comment, the comment delimiter itself must always appear in column zero.
-What can be aligned is the text within the comment. You can choose from
-three styles of alignment by setting the variable
-@code{fortran-comment-indent-style} to one of these values:
-
-@vindex fortran-comment-indent-style
-@vindex fortran-comment-line-extra-indent
-@table @code
-@item fixed
-Align the text at a fixed column, which is the sum of
-@code{fortran-comment-line-extra-indent} and the minimum statement
-indentation. This is the default.
-
-The minimum statement indentation is
-@code{fortran-minimum-statement-indent-fixed} for fixed format
-continuation line style and @code{fortran-minimum-statement-indent-tab}
-for tab format style.
-
-@item relative
-Align the text as if it were a line of code, but with an additional
-@code{fortran-comment-line-extra-indent} columns of indentation.
-
-@item nil
-Don't move text in full-line comments automatically.
-@end table
-
-@vindex fortran-comment-indent-char
- In addition, you can specify the character to be used to indent within
-full-line comments by setting the variable
-@code{fortran-comment-indent-char} to the single-character string you want
-to use.
-
-@vindex fortran-directive-re
- Compiler directive lines, or preprocessor lines, have much the same
-appearance as comment lines. It is important, though, that such lines
-never be indented at all, no matter what the value of
-@code{fortran-comment-indent-style}. The variable
-@code{fortran-directive-re} is a regular expression that specifies which
-lines are directives. Matching lines are never indented, and receive
-distinctive font-locking.
-
- The normal Emacs comment command @kbd{C-x ;} has not been redefined. If
-you use @samp{!} comments, this command can be used with them. Otherwise
-it is useless in Fortran mode.
-
-@kindex C-c ; @r{(Fortran mode)}
-@findex fortran-comment-region
-@vindex fortran-comment-region
- The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
-lines of the region into comments by inserting the string @samp{C$$$} at
-the front of each one. With a numeric argument, it turns the region
-back into live code by deleting @samp{C$$$} from the front of each line
-in it. The string used for these comments can be controlled by setting
-the variable @code{fortran-comment-region}. Note that here we have an
-example of a command and a variable with the same name; these two uses
-of the name never conflict because in Lisp and in Emacs it is always
-clear from the context which one is meant.
-
-@node Fortran Autofill
-@subsection Auto Fill in Fortran Mode
-
- Fortran mode has specialized support for Auto Fill mode, which is a
-minor mode that automatically splits statements as you insert them
-when they become too wide. Splitting a statement involves making
-continuation lines using @code{fortran-continuation-string}
-(@pxref{ForIndent Cont}). This splitting happens when you type
-@key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran
-indentation commands. You activate Auto Fill in Fortran mode in the
-normal way.
-@iftex
-@xref{Auto Fill,,, emacs, the Emacs Manual}.
-@end iftex
-@ifnottex
-@xref{Auto Fill}.
-@end ifnottex
-
-@vindex fortran-break-before-delimiters
- Auto Fill breaks lines at spaces or delimiters when the lines get
-longer than the desired width (the value of @code{fill-column}). The
-delimiters (besides whitespace) that Auto Fill can break at are
-@samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, @samp{<}, @samp{>},
-and @samp{,}. The line break comes after the delimiter if the
-variable @code{fortran-break-before-delimiters} is @code{nil}.
-Otherwise (and by default), the break comes before the delimiter.
-
- To enable Auto Fill in all Fortran buffers, add
-@code{turn-on-auto-fill} to @code{fortran-mode-hook}.
-@iftex
-@xref{Hooks,,, emacs, the Emacs Manual}.
-@end iftex
-@ifnottex
-@xref{Hooks}.
-@end ifnottex
-
-@node Fortran Columns
-@subsection Checking Columns in Fortran
-
-@table @kbd
-@item C-c C-r
-Display a ``column ruler'' momentarily above the current line
-(@code{fortran-column-ruler}).
-@item C-c C-w
-Split the current window horizontally temporarily so that it is 72
-columns wide (@code{fortran-window-create-momentarily}). This may
-help you avoid making lines longer than the 72-character limit that
-some Fortran compilers impose.
-@item C-u C-c C-w
-Split the current window horizontally so that it is 72 columns wide
-(@code{fortran-window-create}). You can then continue editing.
-@item M-x fortran-strip-sequence-nos
-Delete all text in column 72 and beyond.
-@end table
-
-@kindex C-c C-r @r{(Fortran mode)}
-@findex fortran-column-ruler
- The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
-ruler momentarily above the current line. The comment ruler is two lines
-of text that show you the locations of columns with special significance in
-Fortran programs. Square brackets show the limits of the columns for line
-numbers, and curly brackets show the limits of the columns for the
-statement body. Column numbers appear above them.
-
- Note that the column numbers count from zero, as always in GNU Emacs.
-As a result, the numbers may be one less than those you are familiar
-with; but the positions they indicate in the line are standard for
-Fortran.
-
-@vindex fortran-column-ruler-fixed
-@vindex fortran-column-ruler-tabs
- The text used to display the column ruler depends on the value of the
-variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is
-@code{nil}, then the value of the variable
-@code{fortran-column-ruler-fixed} is used as the column ruler.
-Otherwise, the value of the variable @code{fortran-column-ruler-tab} is
-displayed. By changing these variables, you can change the column ruler
-display.
-
-@kindex C-c C-w @r{(Fortran mode)}
-@findex fortran-window-create-momentarily
- @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily
-splits the current window horizontally, making a window 72 columns
-wide, so you can see any lines that are too long. Type a space to
-restore the normal width.
-
-@kindex C-u C-c C-w @r{(Fortran mode)}
-@findex fortran-window-create
- You can also split the window horizontally and continue editing with
-the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x
-fortran-window-create}). By editing in this window you can
-immediately see when you make a line too wide to be correct Fortran.
-
-@findex fortran-strip-sequence-nos
- The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in
-column 72 and beyond, on all lines in the current buffer. This is the
-easiest way to get rid of old sequence numbers.
-
-@node Fortran Abbrev
-@subsection Fortran Keyword Abbrevs
-
- Fortran mode provides many built-in abbrevs for common keywords and
-declarations. These are the same sort of abbrev that you can define
-yourself. To use them, you must turn on Abbrev mode.
-@iftex
-@xref{Abbrevs,,, emacs, the Emacs Manual}.
-@end iftex
-@ifnottex
-@xref{Abbrevs}.
-@end ifnottex
-
- The built-in abbrevs are unusual in one way: they all start with a
-semicolon. You cannot normally use semicolon in an abbrev, but Fortran
-mode makes this possible by changing the syntax of semicolon to ``word
-constituent.''
-
- For example, one built-in Fortran abbrev is @samp{;c} for
-@samp{continue}. If you insert @samp{;c} and then insert a punctuation
-character such as a space or a newline, the @samp{;c} expands automatically
-to @samp{continue}, provided Abbrev mode is enabled.@refill
-
- Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
-Fortran abbrevs and what they stand for.
-
-@ignore
- arch-tag: 23ed7c36-1517-4646-9235-2d5ade5f06f6
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Frames, International, Windows, Top
-@chapter Frames and Graphical Displays
-@cindex frames
-
- When using a graphical display, you can create multiple windows at
-the system in a single Emacs session. Each system-level window that
-belongs to Emacs displays a @dfn{frame} which can contain one or
-several Emacs windows. A frame initially contains a single
-general-purpose Emacs window which you can subdivide vertically or
-horizontally into smaller windows. A frame normally contains its own
-echo area and minibuffer, but you can make frames that don't have
-these---they use the echo area and minibuffer of another frame.
-
- To avoid confusion, we reserve the word ``window'' for the
-subdivisions that Emacs implements, and never use it to refer to a
-frame.
-
- Editing you do in one frame affects the other frames. For
-instance, if you put text in the kill ring in one frame, you can yank it
-in another frame. If you exit Emacs through @kbd{C-x C-c} in one frame,
-it terminates all the frames. To delete just one frame, use @kbd{C-x 5
-0} (that is zero, not @kbd{o}).
-
- Emacs compiled for MS-DOS emulates some windowing functionality,
-so that you can use many of the features described in this chapter.
-@iftex
-@xref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}.
-@end iftex
-@ifnottex
-@xref{MS-DOS Mouse}.
-@end ifnottex
-
-@menu
-* Cut and Paste:: Mouse commands for cut and paste.
-* Mouse References:: Using the mouse to select an item from a list.
-* Menu Mouse Clicks:: Mouse clicks that bring up menus.
-* Mode Line Mouse:: Mouse clicks on the mode line.
-* Creating Frames:: Creating additional Emacs frames with various contents.
-* Frame Commands:: Iconifying, deleting, and switching frames.
-* Speedbar:: How to make and use a speedbar frame.
-* Multiple Displays:: How one Emacs job can talk to several displays.
-* Special Buffer Frames:: You can make certain buffers have their own frames.
-* Frame Parameters:: Changing the colors and other modes of frames.
-* Scroll Bars:: How to enable and disable scroll bars; how to use them.
-* Wheeled Mice:: Using mouse wheels for scrolling.
-* Drag and Drop:: Using drag and drop to open files and insert text.
-* Menu Bars:: Enabling and disabling the menu bar.
-* Tool Bars:: Enabling and disabling the tool bar.
-* Dialog Boxes:: Controlling use of dialog boxes.
-* Tooltips:: Displaying information at the current mouse position.
-* Mouse Avoidance:: Moving the mouse pointer out of the way.
-* Non-Window Terminals:: Multiple frames on terminals that show only one.
-* Text-Only Mouse:: Using the mouse in text-only terminals.
-@end menu
-
-@node Cut and Paste
-@section Killing and Yanking on Graphical Displays
-
- This section describes facilities for selecting a region, killing,
-and yanking using the mouse.
-
-@menu
-* Mouse Commands:: Moving, cutting, and pasting, with the mouse.
-* Cut/Paste Other App:: Transfering text between Emacs and other apps.
-* Word and Line Mouse:: Mouse commands for selecting whole words or lines.
-* Secondary Selection:: Cutting without altering point and mark.
-* Clipboard:: Using the clipboard for selections.
-@end menu
-
-@node Mouse Commands
-@subsection Mouse Commands for Editing
-@cindex mouse buttons (what they do)
-
- The mouse commands for selecting and copying a region are mostly
-compatible with the @code{xterm} program. You can use the same mouse
-commands for copying between Emacs and other window-based programs.
-Most of these commands also work in Emacs when you run it under an
-@code{xterm} terminal.
-
-@kindex DELETE @r{(and mouse selection)}
- If you select a region with any of these mouse commands, and then
-immediately afterward type the @key{DELETE} function key, it deletes the
-region that you selected. The @key{BACKSPACE} function key and the
-@acronym{ASCII} character @key{DEL} do not do this; if you type any other key
-in between the mouse command and @key{DELETE}, it does not do this.
-
-@findex mouse-set-region
-@findex mouse-set-point
-@findex mouse-yank-at-click
-@findex mouse-save-then-click
-@kindex Mouse-1
-@kindex Mouse-2
-@kindex Mouse-3
-@table @kbd
-@item Mouse-1
-Move point to where you click (@code{mouse-set-point}).
-This is normally the left button.
-
-@vindex x-mouse-click-focus-ignore-position
-Normally, Emacs does not distinguish between ordinary mouse clicks and
-clicks that select a frame. When you click on a frame to select it,
-that also changes the selected window and cursor position according to
-the mouse click position. On the X window system, you can change this
-behavior by setting the variable
-@code{x-mouse-click-focus-ignore-position} to @code{t}. Then the
-first click selects the frame, but does not affect the selected window
-or cursor position. If you click again in the same place, since that
-click will be in the selected frame, it will change the window or
-cursor position.
-
-@item Drag-Mouse-1
-Set the region to the text you select by dragging, and copy it to the
-kill ring (@code{mouse-set-region}). You can specify both ends of the
-region with this single command.
-
-@vindex mouse-scroll-min-lines
-If you move the mouse off the top or bottom of the window while
-dragging, the window scrolls at a steady rate until you move the mouse
-back into the window. This way, you can select regions that don't fit
-entirely on the screen. The number of lines scrolled per step depends
-on how far away from the window edge the mouse has gone; the variable
-@code{mouse-scroll-min-lines} specifies a minimum step size.
-
-@vindex mouse-drag-copy-region
-If the variable @code{mouse-drag-copy-region} is @code{nil}, this
-mouse command does not copy the selected region into the kill ring.
-
-@item Mouse-2
-Yank the last killed text, where you click (@code{mouse-yank-at-click}).
-This is normally the middle button.
-
-@item Mouse-3
-This command, @code{mouse-save-then-kill}, has several functions
-depending on where you click and the status of the region.
-
-The most basic case is when you click @kbd{Mouse-1} in one place and
-then @kbd{Mouse-3} in another. This selects the text between those two
-positions as the region. It also copies the new region to the kill
-ring, so that you can copy it to someplace else.
-
-If you click @kbd{Mouse-1} in the text, scroll with the scroll bar, and
-then click @kbd{Mouse-3}, it remembers where point was before scrolling
-(where you put it with @kbd{Mouse-1}), and uses that position as the
-other end of the region. This is so that you can select a region that
-doesn't fit entirely on the screen.
-
-More generally, if you do not have a highlighted region, @kbd{Mouse-3}
-selects the text between point and the click position as the region. It
-does this by setting the mark where point was, and moving point to where
-you click.
-
-If you have a highlighted region, or if the region was set just before
-by dragging button 1, @kbd{Mouse-3} adjusts the nearer end of the region
-by moving it to where you click. The adjusted region's text also
-replaces the old region's text in the kill ring.
-
-If you originally specified the region using a double or triple
-@kbd{Mouse-1}, so that the region is defined to consist of entire words
-or lines, then adjusting the region with @kbd{Mouse-3} also proceeds by
-entire words or lines.
-
-If you use @kbd{Mouse-3} a second time consecutively, at the same place,
-that kills the region already selected.
-@end table
-
- The simplest way to kill text with the mouse is to press @kbd{Mouse-1}
-at one end, then press @kbd{Mouse-3} twice at the other end.
-@xref{Killing}. To copy the text into the kill ring without deleting it
-from the buffer, press @kbd{Mouse-3} just once---or just drag across the
-text with @kbd{Mouse-1}. Then you can copy it elsewhere by yanking it.
-
-@vindex mouse-yank-at-point
- To yank the killed or copied text somewhere else, move the mouse there
-and press @kbd{Mouse-2}. @xref{Yanking}. However, if
-@code{mouse-yank-at-point} is non-@code{nil}, @kbd{Mouse-2} yanks at
-point. Then it does not matter where you click, or even which of the
-frame's windows you click on. The default value is @code{nil}. This
-variable also affects yanking the secondary selection.
-
-@cindex Delete Selection mode
-@cindex mode, Delete Selection
-@findex delete-selection-mode
- Many graphical applications follow the convention that insertion while text
-is selected deletes the selected text. You can make Emacs behave this
-way by enabling Delete Selection mode---with @kbd{M-x
-delete-selection-mode} or using Custom. Another effect of this mode
-is that @key{DEL}, @kbd{C-d} and some other keys, when a selection
-exists, will kill the whole selection. It also enables Transient Mark
-mode (@pxref{Transient Mark}).
-
-@node Cut/Paste Other App
-@subsection Cut and Paste with Other Window Applications
-
-@cindex cutting
-@cindex pasting
-@cindex X cutting and pasting
- To copy text to another windowing application, kill it or save it in
-the kill ring. Then use the ``paste'' or ``yank'' command of the
-other application to insert the text.
-
- To copy text from another windowing application, use its ``cut'' or
-``copy'' command to select the text you want. Then yank it in Emacs
-with @kbd{C-y} or @kbd{Mouse-2}.
-
-@cindex primary selection
-@cindex cut buffer
-@cindex selection, primary
-@vindex x-cut-buffer-max
- When Emacs puts text into the kill ring, or rotates text to the
-front of the kill ring, it sets the @dfn{primary selection} in the
-window system. This is how other windowing applications can access
-the text. On the X Window System, emacs also stores the text in the
-cut buffer, but only if the text is short enough (the value of
-@code{x-cut-buffer-max} specifies the maximum number of characters);
-putting long strings in the cut buffer can be slow.
-
- The commands to yank the first entry in the kill ring actually check
-first for a primary selection in another program; after that, they check
-for text in the cut buffer. If neither of those sources provides text
-to yank, the kill ring contents are used.
-
- The standard coding system for X Window System selections is
-@code{compound-text-with-extensions}. To specify another coding
-system for selections, use @kbd{C-x @key{RET} x} or @kbd{C-x @key{RET}
-X}. @xref{Communication Coding}.
-
-@node Word and Line Mouse
-@subsection Mouse Commands for Words and Lines
-
- These variants of @kbd{Mouse-1} select entire words or lines at a time.
-
-@table @kbd
-@item Double-Mouse-1
-This key sets the region around the word which you click on. If you
-click on a character with ``symbol'' syntax (such as underscore, in C
-mode), it sets the region around the symbol surrounding that character.
-
-If you click on a character with open-parenthesis or close-parenthesis
-syntax, it sets the region around the parenthetical grouping
-which that character starts or ends. If you click on a character with
-string-delimiter syntax (such as a singlequote or doublequote in C), it
-sets the region around the string constant (using heuristics to figure
-out whether that character is the beginning or the end of it).
-
-@item Double-Drag-Mouse-1
-This key selects a region made up of the words you drag across.
-
-@item Triple-Mouse-1
-This key sets the region around the line you click on.
-
-@item Triple-Drag-Mouse-1
-This key selects a region made up of the lines you drag across.
-@end table
-
-@node Secondary Selection
-@subsection Secondary Selection
-@cindex secondary selection
-
- The @dfn{secondary selection} is another way of selecting text using
-the X Window System. It does not use point or the mark, so you can
-use it to kill text without setting point or the mark.
-
-@table @kbd
-@findex mouse-set-secondary
-@kindex M-Drag-Mouse-1
-@item M-Drag-Mouse-1
-Set the secondary selection, with one end at the place where you press
-down the button, and the other end at the place where you release it
-(@code{mouse-set-secondary}). The highlighting appears and changes as
-you drag. You can control the appearance of the highlighting by
-customizing the @code{secondary-selection} face (@pxref{Face
-Customization}).
-
-If you move the mouse off the top or bottom of the window while
-dragging, the window scrolls at a steady rate until you move the mouse
-back into the window. This way, you can mark regions that don't fit
-entirely on the screen.
-
-This way of setting the secondary selection does not alter the kill ring.
-
-@findex mouse-start-secondary
-@kindex M-Mouse-1
-@item M-Mouse-1
-Set one endpoint for the @dfn{secondary selection}
-(@code{mouse-start-secondary}).
-
-@findex mouse-secondary-save-then-kill
-@kindex M-Mouse-3
-@item M-Mouse-3
-Make a secondary selection, using the place specified with @kbd{M-Mouse-1}
-as the other end (@code{mouse-secondary-save-then-kill}). This also
-puts the selected text in the kill ring. A second click at the same
-place kills the secondary selection just made.
-
-@findex mouse-yank-secondary
-@kindex M-Mouse-2
-@item M-Mouse-2
-Insert the secondary selection where you click
-(@code{mouse-yank-secondary}). This places point at the end of the
-yanked text.
-@end table
-
-Double or triple clicking of @kbd{M-Mouse-1} operates on words and
-lines, much like @kbd{Mouse-1}.
-
-If @code{mouse-yank-at-point} is non-@code{nil}, @kbd{M-Mouse-2} yanks
-at point. Then it does not matter precisely where you click, or even
-which of the frame's windows you click on. @xref{Mouse Commands}.
-
-@node Clipboard
-@subsection Using the Clipboard
-@cindex clipboard
-@vindex x-select-enable-clipboard
-@findex menu-bar-enable-clipboard
-@cindex OpenWindows
-@cindex Gnome
-
- Apart from the primary and secondary selection types, Emacs can
-handle the @dfn{clipboard} selection type which is used by some
-applications, particularly under OpenWindows and Gnome.
-
- The command @kbd{M-x menu-bar-enable-clipboard} makes the @code{Cut},
-@code{Paste} and @code{Copy} menu items, as well as the keys of the same
-names, all use the clipboard.
-
- You can customize the variable @code{x-select-enable-clipboard} to make
-the Emacs yank functions consult the clipboard before the primary
-selection, and to make the kill functions to store in the clipboard as
-well as the primary selection. Otherwise they do not access the
-clipboard at all. Using the clipboard is the default on MS-Windows and Mac,
-but not on other systems.
-
-@node Mouse References
-@section Following References with the Mouse
-@kindex Mouse-1 @r{(selection)}
-@kindex Mouse-2 @r{(selection)}
-
- Some read-only Emacs buffers include references you can follow, or
-commands you can activate. These include names of files, of buffers,
-of possible completions, of matches for a pattern, as well as the
-buttons in Help buffers and customization buffers. You can follow the
-reference or activate the command by moving point to it and typing
-@key{RET}. You can also do this with the mouse, using either
-@kbd{Mouse-1} or @kbd{Mouse-2}.
-
- Since yanking text into a read-only buffer is not allowed, these
-buffers generally define @kbd{Mouse-2} to follow a reference or
-activate a command. For example, if you click @kbd{Mouse-2} on a file
-name in a Dired buffer, you visit that file. If you click
-@kbd{Mouse-2} on an error message in the @samp{*Compilation*} buffer,
-you go to the source code for that error message. If you click
-@kbd{Mouse-2} on a completion in the @samp{*Completions*} buffer, you
-choose that completion.
-
- However, most applications use @kbd{Mouse-1} to do this sort of
-thing, so Emacs implements this too. If you click @kbd{Mouse-1}
-quickly on a reference or button, it follows or activates. If you
-click slowly, it moves point as usual. Dragging, meaning moving the
-mouse while it is held down, also has its usual behavior of setting
-the region.
-
-@vindex mouse-1-click-in-non-selected-windows
- Normally, the @kbd{Mouse-1} click behavior is performed on links in
-any window. The variable @code{mouse-1-click-in-non-selected-windows}
-controls whether @kbd{Mouse-1} has this behavior even in non-selected
-windows, or only in the selected window.
-
-@vindex mouse-highlight
- You can usually tell when @kbd{Mouse-1} and @kbd{Mouse-2} have this
-special sort of meaning because the sensitive text highlights when you
-move the mouse over it. The variable @code{mouse-highlight} controls
-whether to do this highlighting always (even when such text appears
-where the mouse already is), never, or only immediately after you move
-the mouse.
-
-@vindex mouse-1-click-follows-link
- In Emacs versions before 22, only @kbd{Mouse-2} follows links and
-@kbd{Mouse-1} always sets point. If you prefer this older behavior,
-set the variable @code{mouse-1-click-follows-link} to @code{nil}.
-This variable also lets you choose various other alternatives for
-following links with the mouse. Type @kbd{C-h v
-mouse-1-click-follows-link @key{RET}} for more details.
-
-@node Menu Mouse Clicks
-@section Mouse Clicks for Menus
-
- Several mouse clicks with the @key{CTRL} and @key{SHIFT} modifiers
-bring up menus.
-
-@table @kbd
-@item C-Mouse-1
-@kindex C-Mouse-1
-This menu is for selecting a buffer.
-
-The MSB (``mouse select buffer'') global minor mode makes this
-menu smarter and more customizable. @xref{Buffer Menus}.
-
-@item C-Mouse-2
-@kindex C-Mouse-2
-This menu is for specifying faces and other text properties
-for editing formatted text. @xref{Formatted Text}.
-
-@item C-Mouse-3
-@kindex C-Mouse-3
-This menu is mode-specific. For most modes if Menu-bar mode is on,
-this menu has the same items as all the mode-specific menu-bar menus
-put together. Some modes may specify a different menu for this
-button.@footnote{Some systems use @kbd{Mouse-3} for a mode-specific
-menu. We took a survey of users, and found they preferred to keep
-@kbd{Mouse-3} for selecting and killing regions. Hence the decision
-to use @kbd{C-Mouse-3} for this menu. To use @kbd{Mouse-3} instead,
-do @code{(global-set-key [mouse-3] 'mouse-popup-menubar-stuff)}.} If
-Menu-bar mode is off, this menu contains all the items which would be
-present in the menu bar---not just the mode-specific ones---so that
-you can access them without having to display the menu bar.
-
-@item S-Mouse-1
-This menu is for specifying the frame's default font.
-@end table
-
-@node Mode Line Mouse
-@section Mode Line Mouse Commands
-@cindex mode line, mouse
-@cindex mouse on mode line
-
- You can use mouse clicks on window mode lines to select and manipulate
-windows.
-
- Some areas of the mode line, such as the buffer name and the major
-mode name, have their own special mouse bindings. These areas are
-highlighted when you hold the mouse over them, and information about
-the special bindings will be displayed (@pxref{Tooltips}). This
-section's commands do not apply in those areas.
-
-@table @kbd
-@item Mouse-1
-@kindex Mouse-1 @r{(mode line)}
-@kbd{Mouse-1} on a mode line selects the window it belongs to. By
-dragging @kbd{Mouse-1} on the mode line, you can move it, thus
-changing the height of the windows above and below. Changing heights
-with the mouse in this way never deletes windows, it just refuses to
-make any window smaller than the minimum height.
-
-@item Mouse-2
-@kindex Mouse-2 @r{(mode line)}
-@kbd{Mouse-2} on a mode line expands that window to fill its frame.
-
-@item Mouse-3
-@kindex Mouse-3 @r{(mode line)}
-@kbd{Mouse-3} on a mode line deletes the window it belongs to. If the
-frame has only one window, it buries the current buffer instead, and
-switches to another buffer.
-
-@item C-Mouse-2
-@kindex C-mouse-2 @r{(mode line)}
-@kbd{C-Mouse-2} on a mode line splits the window above
-horizontally, above the place in the mode line where you click.
-@end table
-
-@kindex C-Mouse-2 @r{(scroll bar)}
-@kindex Mouse-1 @r{(scroll bar)}
- Using @kbd{Mouse-1} on the divider between two side-by-side mode
-lines, you can move the vertical boundary left or right. Using
-@kbd{C-Mouse-2} on a scroll bar splits the corresponding window
-vertically. @xref{Split Window}.
-
-@node Creating Frames
-@section Creating Frames
-@cindex creating frames
-
-@kindex C-x 5
- The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}, with parallel
-subcommands. The difference is that @kbd{C-x 5} commands create a new
-frame rather than just a new window in the selected frame (@pxref{Pop
-Up Window}). If an existing visible or iconified frame already displays
-the requested material, these commands use the existing frame, after
-raising or deiconifying as necessary.
-
- The various @kbd{C-x 5} commands differ in how they find or create the
-buffer to select:
-
-@table @kbd
-@item C-x 5 2
-@kindex C-x 5 2
-@findex make-frame-command
-Create a new frame (@code{make-frame-command}).
-@item C-x 5 b @var{bufname} @key{RET}
-Select buffer @var{bufname} in another frame. This runs
-@code{switch-to-buffer-other-frame}.
-@item C-x 5 f @var{filename} @key{RET}
-Visit file @var{filename} and select its buffer in another frame. This
-runs @code{find-file-other-frame}. @xref{Visiting}.
-@item C-x 5 d @var{directory} @key{RET}
-Select a Dired buffer for directory @var{directory} in another frame.
-This runs @code{dired-other-frame}. @xref{Dired}.
-@item C-x 5 m
-Start composing a mail message in another frame. This runs
-@code{mail-other-frame}. It is the other-frame variant of @kbd{C-x m}.
-@xref{Sending Mail}.
-@item C-x 5 .
-Find a tag in the current tag table in another frame. This runs
-@code{find-tag-other-frame}, the multiple-frame variant of @kbd{M-.}.
-@xref{Tags}.
-@item C-x 5 r @var{filename} @key{RET}
-@kindex C-x 5 r
-@findex find-file-read-only-other-frame
-Visit file @var{filename} read-only, and select its buffer in another
-frame. This runs @code{find-file-read-only-other-frame}.
-@xref{Visiting}.
-@end table
-
-@cindex default-frame-alist
-@cindex initial-frame-alist
-@cindex face customization, in @file{~/.emacs}
-@cindex color customization, in @file{~/.emacs}
- You can control the appearance of new frames you create by setting the
-frame parameters in @code{default-frame-alist}. You can use the
-variable @code{initial-frame-alist} to specify parameters that affect
-only the initial frame. @xref{Initial Parameters,,, elisp, The Emacs
-Lisp Reference Manual}, for more information.
-
-@cindex font (default)
- The easiest way to specify the principal font for all your Emacs
-frames is with an X resource (@pxref{Font X}), but you can also do it by
-modifying @code{default-frame-alist} to specify the @code{font}
-parameter, as shown here:
-
-@example
-(add-to-list 'default-frame-alist '(font . "10x20"))
-@end example
-
-@noindent
-Here's a similar example for specifying a foreground color:
-
-@example
-(add-to-list 'default-frame-alist '(foreground-color . "blue"))
-@end example
-
-@noindent
-By putting such customizations in your @file{~/.emacs} init file, you
-can control the appearance of all the frames Emacs creates, including
-the initial one.
-
-@node Frame Commands
-@section Frame Commands
-
- The following commands let you create, delete and operate on frames:
-
-@table @kbd
-@item C-z
-@kindex C-z @r{(X windows)}
-@findex iconify-or-deiconify-frame
-Iconify the selected Emacs frame (@code{iconify-or-deiconify-frame}).
-When typed on an Emacs frame's icon, deiconify instead.
-
-The normal meaning of @kbd{C-z}, to suspend Emacs, is not useful under
-a graphical display that allows multiple applications to operate
-simultaneously in their own windows, so Emacs gives @kbd{C-z} a
-different binding in that case.
-
-@item C-x 5 0
-@kindex C-x 5 0
-@findex delete-frame
-Delete the selected frame (@code{delete-frame}). This is not allowed if
-there is only one frame.
-
-@item C-x 5 o
-@kindex C-x 5 o
-@findex other-frame
-Select another frame, raise it, and warp the mouse to it so that it
-stays selected. If you repeat this command, it cycles through all the
-frames on your terminal.
-
-@item C-x 5 1
-@kindex C-x 5 1
-@findex delete-other-frames
-Delete all frames except the selected one.
-@end table
-
-@vindex focus-follows-mouse
- To make the command @kbd{C-x 5 o} work properly, you must tell Emacs
-how the system (or the window manager) generally handles
-focus-switching between windows. There are two possibilities: either
-simply moving the mouse onto a window selects it (gives it focus), or
-you have to click on it in a suitable way to do so. On X, this focus
-policy also affects whether the focus is given to a frame that Emacs
-raises. Unfortunately there is no way Emacs can find out
-automatically which way the system handles this, so you have to
-explicitly say, by setting the variable @code{focus-follows-mouse}.
-If just moving the mouse onto a window selects it, that variable
-should be @code{t}; if a click is necessary, the variable should be
-@code{nil}.
-
-The window manager that is part of MS-Windows always gives focus to a
-frame that raises, so this variable has no effect in the native
-MS-Windows build of Emacs.
-
-@node Speedbar
-@section Speedbar Frames
-@cindex speedbar
-
-@cindex attached frame (of speedbar)
- The @dfn{speedbar} is a special frame for conveniently navigating in
-or operating on another frame. The speedbar, when it exists, is
-always associated with a specific frame, called its @dfn{attached
-frame}; all speedbar operations act on that frame.
-
- Type @kbd{M-x speedbar} to create the speedbar and associate it with
-the current frame. To dismiss the speedbar, type @kbd{M-x speedbar}
-again, or select the speedbar and type @kbd{q}. (You can also delete
-the speedbar frame like any other Emacs frame.) If you wish to
-associate the speedbar with a different frame, dismiss it and call
-@kbd{M-x speedbar} from that frame.
-
- The speedbar can operate in various modes. Its default mode is
-@dfn{File Display} mode, which shows the files in the current
-directory of the selected window of the attached frame, one file per
-line. Clicking on a file name visits that file in the selected window
-of the attached frame, and clicking on a directory name shows that
-directory in the speedbar (@pxref{Mouse References}). Each line also
-has a box, @samp{[+]} or @samp{<+>}, that you can click on to
-@dfn{expand} the contents of that item. Expanding a directory adds
-the contents of that directory to the speedbar display, underneath the
-directory's own line. Expanding an ordinary file adds a list of the
-tags in that file to the speedbar display; you can click on a tag name
-to jump to that tag in the selected window of the attached frame.
-When a file or directory is expanded, the @samp{[+]} changes to
-@samp{[-]}; you can click on that box to @dfn{contract} the item,
-hiding its contents.
-
- You navigate through the speedbar using the keyboard, too. Typing
-@kbd{RET} while point is on a line in the speedbar is equivalent to
-clicking the item on the current line, and @kbd{SPC} expands or
-contracts the item. @kbd{U} displays the parent directory of the
-current directory. To copy, delete, or rename the file on the current
-line, type @kbd{C}, @kbd{D}, and @kbd{R} respectively. To create a
-new directory, type @kbd{M}.
-
- Another general-purpose speedbar mode is @dfn{Buffer Display} mode;
-in this mode, the speedbar displays a list of Emacs buffers. To
-switch to this mode, type @kbd{b} in the speedbar. To return to File
-Display mode, type @kbd{f}. You can also change the display mode by
-clicking @kbd{mouse-3} anywhere in the speedbar window (or
-@kbd{mouse-1} on the mode-line) and selecting @samp{Displays} in the
-pop-up menu.
-
- Some major modes, including Rmail mode, Info, and GUD, have
-specialized ways of putting useful items into the speedbar for you to
-select. For example, in Rmail mode, the speedbar shows a list of Rmail
-files, and lets you move the current message to another Rmail file by
-clicking on its @samp{<M>} box.
-
- For more details on using and programming the speedbar, @xref{Top,
-Speedbar,,speedbar, Speedbar Manual}.
-
-@node Multiple Displays
-@section Multiple Displays
-@cindex multiple displays
-
- A single Emacs can talk to more than one X display. Initially, Emacs
-uses just one display---the one specified with the @env{DISPLAY}
-environment variable or with the @samp{--display} option (@pxref{Initial
-Options}). To connect to another display, use the command
-@code{make-frame-on-display}:
-
-@findex make-frame-on-display
-@table @kbd
-@item M-x make-frame-on-display @key{RET} @var{display} @key{RET}
-Create a new frame on display @var{display}.
-@end table
-
- A single X server can handle more than one screen. When you open
-frames on two screens belonging to one server, Emacs knows they share a
-single keyboard, and it treats all the commands arriving from these
-screens as a single stream of input.
-
- When you open frames on different X servers, Emacs makes a separate
-input stream for each server. This way, two users can type
-simultaneously on the two displays, and Emacs will not garble their
-input. Each server also has its own selected frame. The commands you
-enter with a particular X server apply to that server's selected frame.
-
- Despite these features, people using the same Emacs job from different
-displays can still interfere with each other if they are not careful.
-For example, if any one types @kbd{C-x C-c}, that exits the Emacs job
-for all of them!
-
-@node Special Buffer Frames
-@section Special Buffer Frames
-
-@vindex special-display-buffer-names
- You can make certain chosen buffers, which Emacs normally displays
-in ``another window,'' appear in special frames of their own. To do
-this, set the variable @code{special-display-buffer-names} to a list
-of buffer names; any buffer whose name is in that list automatically
-gets a special frame, when an Emacs command wants to display it ``in
-another window.''
-
- For example, if you set the variable this way,
-
-@example
-(setq special-display-buffer-names
- '("*Completions*" "*grep*" "*tex-shell*"))
-@end example
-
-@noindent
-then completion lists, @code{grep} output and the @TeX{} mode shell
-buffer get individual frames of their own. These frames, and the
-windows in them, are never automatically split or reused for any other
-buffers. They continue to show the buffers they were created for,
-unless you alter them by hand. Killing the special buffer deletes its
-frame automatically.
-
-@vindex special-display-regexps
- More generally, you can set @code{special-display-regexps} to a list
-of regular expressions; then a buffer gets its own frame if its name
-matches any of those regular expressions. (Once again, this applies only
-to buffers that normally get displayed for you in ``another window.'')
-
-@vindex special-display-frame-alist
- The variable @code{special-display-frame-alist} specifies the frame
-parameters for these frames. It has a default value, so you don't need
-to set it.
-
- For those who know Lisp, an element of
-@code{special-display-buffer-names} or @code{special-display-regexps}
-can also be a list. Then the first element is the buffer name or
-regular expression; the rest of the list specifies how to create the
-frame. It can be an association list specifying frame parameter
-values; these values take precedence over parameter values specified
-in @code{special-display-frame-alist}. If you specify the symbol
-@code{same-window} as a ``frame parameter'' in this list, with a
-non-@code{nil} value, that means to use the selected window if
-possible. If you use the symbol @code{same-frame} as a ``frame
-parameter'' in this list, with a non-@code{nil} value, that means to
-use the selected frame if possible.
-
- Alternatively, the value can have this form:
-
-@example
-(@var{function} @var{args}...)
-@end example
-
-@noindent
-where @var{function} is a symbol. Then the frame is constructed by
-calling @var{function}; its first argument is the buffer, and its
-remaining arguments are @var{args}.
-
- An analogous feature lets you specify buffers which should be
-displayed in the selected window. @xref{Force Same Window}. The
-same-window feature takes precedence over the special-frame feature;
-therefore, if you add a buffer name to
-@code{special-display-buffer-names} and it has no effect, check to see
-whether that feature is also in use for the same buffer name.
-
-@node Frame Parameters
-@section Setting Frame Parameters
-@cindex Auto-Raise mode
-@cindex Auto-Lower mode
-
-@kindex S-Mouse-1
- You can specify the font and colors used for text display, and the
-colors for the frame borders, the cursor, and the mouse cursor, by
-customizing the faces @code{default}, @code{border}, @code{cursor} and
-@code{mouse}. @xref{Face Customization}. You can also set a frame's
-default font through a pop-up menu. Press @kbd{S-Mouse-1} to activate
-this menu.
-
- These commands are available for controlling the window management
-behavior of the selected frame.
-
-@table @kbd
-@findex auto-raise-mode
-@item M-x auto-raise-mode
-Toggle whether or not the selected frame should auto-raise. Auto-raise
-means that every time you move the mouse onto the frame, it raises the
-frame.
-
-Some window managers also implement auto-raise. If you enable
-auto-raise for Emacs frames in your window manager, it will work, but
-it is beyond Emacs' control, so @code{auto-raise-mode} has no effect
-on it.
-
-@findex auto-lower-mode
-@item M-x auto-lower-mode
-Toggle whether or not the selected frame should auto-lower.
-Auto-lower means that every time you move the mouse off the frame,
-the frame moves to the bottom of the stack on the screen.
-
-The command @code{auto-lower-mode} has no effect on auto-lower
-implemented by the window manager. To control that, you must use the
-appropriate window manager features.
-@end table
-
- In Emacs versions that use an X toolkit, the color-setting and
-font-setting functions don't affect menus and the menu bar, since they
-are displayed by their own widget classes. To change the appearance of
-the menus and menu bar, you must use X resources (@pxref{Resources}).
-@xref{Colors}, regarding colors. @xref{Font X}, regarding choice of
-font.
-
- Colors, fonts, and other attributes of the frame's display can also
-be customized by setting frame parameters in the variable
-@code{default-frame-alist} (@pxref{Creating Frames}). For a detailed
-description of frame parameters and customization, see @ref{Frame
-Parameters,,, elisp, The Emacs Lisp Reference Manual}.
-
-@node Scroll Bars
-@section Scroll Bars
-@cindex Scroll Bar mode
-@cindex mode, Scroll Bar
-
- On graphical displays, Emacs normally makes a @dfn{scroll bar} at
-the left of each Emacs window.@footnote{Placing it at the left is
-usually more useful with overlapping frames with text starting at the
-left margin.} The scroll bar runs the height of the window, and shows
-a moving rectangular inner box which represents the portion of the
-buffer currently displayed. The entire height of the scroll bar
-represents the entire length of the buffer.
-
- You can use @kbd{Mouse-2} (normally, the middle button) in the scroll
-bar to move or drag the inner box up and down. If you move it to the
-top of the scroll bar, you see the top of the buffer. If you move it to
-the bottom of the scroll bar, you see the bottom of the buffer.
-
- The left and right buttons in the scroll bar scroll by controlled
-increments. @kbd{Mouse-1} (normally, the left button) moves the line at
-the level where you click up to the top of the window. @kbd{Mouse-3}
-(normally, the right button) moves the line at the top of the window
-down to the level where you click. By clicking repeatedly in the same
-place, you can scroll by the same distance over and over.
-
- You can also click @kbd{C-Mouse-2} in the scroll bar to split a
-window vertically. The split occurs on the line where you click.
-
-@findex scroll-bar-mode
-@vindex scroll-bar-mode
- You can enable or disable Scroll Bar mode with the command @kbd{M-x
-scroll-bar-mode}. With no argument, it toggles the use of scroll
-bars. With an argument, it turns use of scroll bars on if and only if
-the argument is positive. This command applies to all frames,
-including frames yet to be created. Customize the variable
-@code{scroll-bar-mode} to control the use of scroll bars at startup.
-You can use it to specify that they are placed at the right of windows
-if you prefer that. You have to set this variable through the
-@samp{Customize} interface (@pxref{Easy Customization}), or it will
-not work properly.
-
- You can also use the X resource @samp{verticalScrollBars} to control
-the initial setting of Scroll Bar mode. @xref{Resources}.
-
-@findex toggle-scroll-bar
- To enable or disable scroll bars for just the selected frame, use the
-command @kbd{M-x toggle-scroll-bar}.
-
-@vindex scroll-bar-width
-@cindex width of the scroll bar
- You can control the scroll bar width by changing the value of the
-@code{scroll-bar-width} frame parameter.
-
-@node Wheeled Mice
-@section Scrolling With ``Wheeled'' Mice
-
-@cindex mouse wheel
-@cindex wheel, mouse
-@findex mouse-wheel-mode
-@cindex Mouse Wheel minor mode
-@cindex mode, Mouse Wheel
- Some mice have a ``wheel'' instead of a third button. You can
-usually click the wheel to act as either @kbd{Mouse-2} or
-@kbd{Mouse-3}, depending on the setup. You can also use the wheel to
-scroll windows instead of using the scroll bar or keyboard commands.
-Mouse wheel support only works if the system generates appropriate
-events; whenever possible, it is turned on by default. To toggle this
-feature, use @kbd{M-x mouse-wheel-mode}.
-
-@vindex mouse-wheel-follow-mouse
-@vindex mouse-wheel-scroll-amount
-@vindex mouse-wheel-progressive-speed
- The two variables @code{mouse-wheel-follow-mouse} and
-@code{mouse-wheel-scroll-amount} determine where and by how much
-buffers are scrolled. The variable
-@code{mouse-wheel-progressive-speed} determines whether the scroll
-speed is linked to how fast you move the wheel.
-
-@node Drag and Drop
-@section Drag and Drop
-@cindex drag and drop
-
- Emacs supports @dfn{drag and drop} using the mouse. For instance,
-dropping text onto an Emacs frame inserts the text where it is dropped.
-Dropping a file onto an Emacs frame visits that file. As a special
-case, dropping the file on a Dired buffer moves or copies the file
-(according to the conventions of the application it came from) into the
-directory displayed in that buffer.
-
-@vindex dnd-open-file-other-window
- Dropping a file normally visits it in the window you drop it on. If
-you prefer to visit the file in a new window in such cases, customize
-the variable @code{dnd-open-file-other-window}.
-
- The XDND and Motif drag and drop protocols, and the old KDE 1.x
-protocol, are currently supported.
-
-@node Menu Bars
-@section Menu Bars
-@cindex Menu Bar mode
-@cindex mode, Menu Bar
-@findex menu-bar-mode
-@vindex menu-bar-mode
-
- You can turn display of menu bars on or off with @kbd{M-x
-menu-bar-mode} or by customizing the variable @code{menu-bar-mode}.
-With no argument, this command toggles Menu Bar mode, a
-minor mode. With an argument, the command turns Menu Bar mode on if the
-argument is positive, off if the argument is not positive. You can use
-the X resource @samp{menuBarLines} to control the initial setting of
-Menu Bar mode. @xref{Resources}.
-
-@kindex C-Mouse-3 @r{(when menu bar is disabled)}
- Expert users often turn off the menu bar, especially on text-only
-terminals, where this makes one additional line available for text.
-If the menu bar is off, you can still pop up a menu of its contents
-with @kbd{C-Mouse-3} on a display which supports pop-up menus.
-@xref{Menu Mouse Clicks}.
-
- @xref{Menu Bar}, for information on how to invoke commands with the
-menu bar. @xref{X Resources}, for how to customize the menu bar
-menus' visual appearance.
-
-@node Tool Bars
-@section Tool Bars
-@cindex Tool Bar mode
-@cindex mode, Tool Bar
-@cindex icons, toolbar
-
- The @dfn{tool bar} is a line (or lines) of icons at the top of the
-Emacs window, just below the menu bar. You can click on these icons
-with the mouse to do various jobs.
-
- The global tool bar contains general commands. Some major modes
-define their own tool bars to replace it. A few ``special'' modes
-that are not designed for ordinary editing remove some items from the
-global tool bar.
-
- Tool bars work only on a graphical display. The tool bar uses colored
-XPM icons if Emacs was built with XPM support. Otherwise, the tool
-bar uses monochrome icons (PBM or XBM format).
-
-@findex tool-bar-mode
-@vindex tool-bar-mode
- You can turn display of tool bars on or off with @kbd{M-x
-tool-bar-mode} or by customizing the option @code{tool-bar-mode}.
-
-@node Dialog Boxes
-@section Using Dialog Boxes
-@cindex dialog boxes
-
-@vindex use-dialog-box
- A dialog box is a special kind of menu for asking you a yes-or-no
-question or some other special question. Many Emacs commands use a
-dialog box to ask a yes-or-no question, if you used the mouse to
-invoke the command to begin with.
-
- You can customize the variable @code{use-dialog-box} to suppress the
-use of dialog boxes. This also controls whether to use file selection
-windows (but those are not supported on all platforms).
-
-@vindex use-file-dialog
- A file selection window is a special kind of dialog box for asking
-for file names. You can customize the variable @code{use-file-dialog}
-to suppress the use of file selection windows, even if you still want
-other kinds of dialogs. This variable has no effect if you have
-suppressed all dialog boxes with the variable @code{use-dialog-box}.
-
-@vindex x-gtk-show-hidden-files
- For Gtk+ version 2.4 and newer, Emacs use the Gtk+ file chooser
-dialog. Emacs adds a toggle button that enables and disables showing
-of hidden files (files starting with a dot) in that dialog. The
-variable @code{x-gtk-show-hidden-files} controls whether to show
-hidden files by default.
-
-@vindex x-gtk-use-old-file-dialog
- For Gtk+ versions 2.4 through 2.10, you can select the old file
-dialog (@code{gtk-file-selector}) by setting the variable
-@code{x-gtk-use-old-file-dialog} to a non-@code{nil} value. If it is
-@code{nil}, Emacs uses @code{gtk-file-chooser}. If Emacs is built
-with a Gtk+ version that has only one file dialog, this variable has
-no effect.
-
-@vindex x-gtk-file-dialog-help-text
- Emacs adds help text to the Gtk+ file chooser dialog. The variable
-@code{x-gtk-file-dialog-help-text} specifies the text to add; if it is
-@code{nil}, that disables the added text.
-
-@node Tooltips
-@section Tooltips
-@cindex tooltips
-
- @dfn{Tooltips} are small windows that display text information at the
-current mouse position. They activate when there is a pause in mouse
-movement. There are two types of tooltip: help tooltips and GUD
-tooltips.
-
- @dfn{Help tooltips} typically display over text---including the mode
-line---but are also available for other parts of the Emacs frame, such
-as the tool bar and menu items.
-
-@findex tooltip-mode
- You can toggle display of help tooltips (Tooltip mode) with the
-command @kbd{M-x tooltip-mode}. When Tooltip mode is disabled, the
-help text is displayed in the echo area instead.
-
- @dfn{GUD tooltips} show values of variables. They are useful when
-you are debugging a program. @xref{Debugger Operation}.
-
-@vindex tooltip-delay
- The variables @code{tooltip-delay} specifies how long Emacs should
-wait before displaying a tooltip. For additional customization
-options for displaying tooltips, use @kbd{M-x customize-group
-@key{RET} tooltip @key{RET}}. @xref{X Resources}, for information on
-customizing the windows that display tooltips.
-
-@node Mouse Avoidance
-@section Mouse Avoidance
-@cindex avoiding mouse in the way of your typing
-@cindex mouse avoidance
-
-@vindex mouse-avoidance-mode
-Mouse Avoidance mode keeps the mouse pointer away from point, to avoid
-obscuring text you want to edit. Whenever it moves the mouse, it also
-raises the frame. To use Mouse Avoidance mode, customize the variable
-@code{mouse-avoidance-mode}. You can set this to various values to
-move the mouse in several ways:
-
-@table @code
-@item banish
-Move the mouse to the upper-right corner on any key-press;
-@item exile
-Move the mouse to the corner only if the cursor gets too close,
-and allow it to return once the cursor is out of the way;
-@item jump
-If the cursor gets too close to the mouse, displace the mouse
-a random distance & direction;
-@item animate
-As @code{jump}, but shows steps along the way for illusion of motion;
-@item cat-and-mouse
-The same as @code{animate};
-@item proteus
-As @code{animate}, but changes the shape of the mouse pointer too.
-@end table
-
-@findex mouse-avoidance-mode
-You can also use the command @kbd{M-x mouse-avoidance-mode} to enable
-the mode.
-
-@node Non-Window Terminals
-@section Non-Window Terminals
-@cindex non-window terminals
-@cindex single-frame terminals
-
- On a text-only terminal, Emacs can display only one Emacs frame at a
-time. However, you can still create multiple Emacs frames, and switch
-between them. Switching frames on these terminals is much like
-switching between different window configurations.
-
- Use @kbd{C-x 5 2} to create a new frame and switch to it; use @kbd{C-x
-5 o} to cycle through the existing frames; use @kbd{C-x 5 0} to delete
-the current frame.
-
- Each frame has a number to distinguish it. If your terminal can
-display only one frame at a time, the selected frame's number @var{n}
-appears near the beginning of the mode line, in the form
-@samp{F@var{n}}.
-
-@findex set-frame-name
-@findex select-frame-by-name
- @samp{F@var{n}} is in fact the frame's initial name. You can give
-frames more meaningful names if you wish, and you can select a frame
-by its name. Use the command @kbd{M-x set-frame-name @key{RET}
-@var{name} @key{RET}} to specify a new name for the selected frame,
-and use @kbd{M-x select-frame-by-name @key{RET} @var{name} @key{RET}}
-to select a frame according to its name. The name you specify appears
-in the mode line when the frame is selected.
-
-@node Text-Only Mouse
-@section Using a Mouse in Terminal Emulators
-@cindex mouse support
-@cindex terminal emulators, mouse support
-
-Some terminal emulators support mouse clicks in the terminal window.
-
-@cindex xterm
-In a terminal emulator which is compatible with @code{xterm},
-you can use @kbd{M-x xterm-mouse-mode} to give Emacs control over
-simple use of the mouse---basically, only non-modified single clicks
-are supported. The normal @code{xterm} mouse functionality for such
-clicks is still available by holding down the @kbd{SHIFT} key when you
-press the mouse button. Xterm Mouse mode is a global minor mode
-(@pxref{Minor Modes}). Repeating the command turns the mode off
-again.
-
-In the console on GNU/Linux, you can use @kbd{M-x t-mouse-mode}. You
-need to have the gpm package installed and running on your system in
-order for this to work.
-
-@ignore
- arch-tag: 7dcf3a31-a43b-45d4-a900-445b10d77e49
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Glossary, Key Index, Intro, Top
-@unnumbered Glossary
-
-@table @asis
-@item Abbrev
-An abbrev is a text string which expands into a different text string
-when present in the buffer. For example, you might define a few letters
-as an abbrev for a long phrase that you want to insert frequently.
-@xref{Abbrevs}.
-
-@item Aborting
-Aborting means getting out of a recursive edit (q.v.@:). The
-commands @kbd{C-]} and @kbd{M-x top-level} are used for this.
-@xref{Quitting}.
-
-@item Alt
-Alt is the name of a modifier bit which a keyboard input character may
-have. To make a character Alt, type it while holding down the @key{ALT}
-key. Such characters are given names that start with @kbd{Alt-}
-(usually written @kbd{A-} for short). (Note that many terminals have a
-key labeled @key{ALT} which is really a @key{META} key.) @xref{User
-Input, Alt}.
-
-@item Argument
-See `numeric argument.'
-
-@item @acronym{ASCII} character
-An @acronym{ASCII} character is either an @acronym{ASCII} control character or an @acronym{ASCII}
-printing character. @xref{User Input}.
-
-@item @acronym{ASCII} control character
-An @acronym{ASCII} control character is the Control version of an upper-case
-letter, or the Control version of one of the characters @samp{@@[\]^_?}.
-
-@item @acronym{ASCII} printing character
-@acronym{ASCII} printing characters include letters, digits, space, and these
-punctuation characters: @samp{!@@#$%^& *()_-+=|\~` @{@}[]:;"' <>,.?/}.
-
-@item Auto Fill Mode
-Auto Fill mode is a minor mode in which text that you insert is
-automatically broken into lines of a given maximum width.
-@xref{Filling}.
-
-@item Auto Saving
-Auto saving is the practice of saving the contents of an Emacs buffer in
-a specially-named file, so that the information will not be lost if the
-buffer is lost due to a system error or user error. @xref{Auto Save}.
-
-@item Autoloading
-Emacs automatically loads Lisp libraries when a Lisp program requests a
-function or a variable from those libraries. This is called
-`autoloading'. @xref{Lisp Libraries}.
-
-@item Backtrace
-A backtrace is a trace of a series of function calls showing how a
-program arrived to a certain point. It is used mainly for finding and
-correcting bugs (q.v.@:). Emacs can display a backtrace when it signals
-an error or when you type @kbd{C-g} (see `quitting'). @xref{Checklist}.
-
-@item Backup File
-A backup file records the contents that a file had before the current
-editing session. Emacs makes backup files automatically to help you
-track down or cancel changes you later regret making. @xref{Backup}.
-
-@item Balancing Parentheses
-Emacs can balance parentheses (or other matching delimiters) either
-manually or automatically. You do manual balancing with the commands
-to move over parenthetical groupings (@pxref{Moving by Parens}).
-Automatic balancing works by blinking or highlighting the delimiter
-that matches the one you just inserted (@pxref{Matching,,Matching
-Parens}).
-
-@item Balanced Expressions
-A balanced expression is a syntactically recognizable expression, such
-as a symbol, number, string constant, block, or parenthesized expression
-in C. @xref{Expressions,Balanced Expressions}.
-
-@item Balloon Help
-See `tooltips.'
-
-@item Base Buffer
-A base buffer is a buffer whose text is shared by an indirect buffer
-(q.v.@:).
-
-@item Bind
-To bind a key sequence means to give it a binding (q.v.@:).
-@xref{Rebinding}.
-
-@item Binding
-A key sequence gets its meaning in Emacs by having a binding, which is a
-command (q.v.@:), a Lisp function that is run when the user types that
-sequence. @xref{Commands,Binding}. Customization often involves
-rebinding a character to a different command function. The bindings of
-all key sequences are recorded in the keymaps (q.v.@:). @xref{Keymaps}.
-
-@item Blank Lines
-Blank lines are lines that contain only whitespace. Emacs has several
-commands for operating on the blank lines in the buffer.
-
-@item Bookmark
-Bookmarks are akin to registers (q.v.@:) in that they record positions
-in buffers to which you can return later. Unlike registers, bookmarks
-persist between Emacs sessions.
-
-@item Border
-A border is a thin space along the edge of the frame, used just for
-spacing, not for displaying anything. An Emacs frame has an ordinary
-external border, outside of everything including the menu bar, plus an
-internal border that surrounds the text windows and their scroll bars
-and separates them from the menu bar and tool bar. You can customize
-both borders with options and resources (@pxref{Borders X}). Borders
-are not the same as fringes (q.v.@:).
-
-@item Buffer
-The buffer is the basic editing unit; one buffer corresponds to one text
-being edited. You can have several buffers, but at any time you are
-editing only one, the `current buffer,' though several can be visible
-when you are using multiple windows (q.v.@:). Most buffers are visiting
-(q.v.@:) some file. @xref{Buffers}.
-
-@item Buffer Selection History
-Emacs keeps a buffer selection history which records how recently each
-Emacs buffer has been selected. This is used for choosing a buffer to
-select. @xref{Buffers}.
-
-@item Bug
-A bug is an incorrect or unreasonable behavior of a program, or
-inaccurate or confusing documentation. Emacs developers treat bug
-reports, both in Emacs code and its documentation, very seriously and
-ask you to report any bugs you find. @xref{Bugs}.
-
-@item Button Down Event
-A button down event is the kind of input event generated right away when
-you press down on a mouse button. @xref{Mouse Buttons}.
-
-@item By Default
-See `default.'
-
-@item Byte Compilation
-See `compilation.'
-
-@item @kbd{C-}
-@kbd{C-} in the name of a character is an abbreviation for Control.
-@xref{User Input,C-}.
-
-@item @kbd{C-M-}
-@kbd{C-M-} in the name of a character is an abbreviation for
-Control-Meta. @xref{User Input,C-M-}.
-
-@item Case Conversion
-Case conversion means changing text from upper case to lower case or
-vice versa. @xref{Case}, for the commands for case conversion.
-
-@item Character
-Characters form the contents of an Emacs buffer; see @ref{Text
-Characters}. Also, key sequences (q.v.@:) are usually made up of
-characters (though they may include other input events as well).
-@xref{User Input}.
-
-@item Character Set
-Emacs supports a number of character sets, each of which represents a
-particular alphabet or script. @xref{International}.
-
-@item Character Terminal
-See `text-only terminal.'
-
-@item Click Event
-A click event is the kind of input event generated when you press a
-mouse button and release it without moving the mouse. @xref{Mouse Buttons}.
-
-@item Clipboard
-A clipboard is a buffer provided by the window system for transferring
-text between applications. On the X Window system, the clipboard is
-provided in addition to the primary selection (q.v.@:); on MS-Windows and Mac,
-the clipboard is used @emph{instead} of the primary selection.
-@xref{Clipboard}.
-
-@item Coding System
-A coding system is an encoding for representing text characters in a
-file or in a stream of information. Emacs has the ability to convert
-text to or from a variety of coding systems when reading or writing it.
-@xref{Coding Systems}.
-
-@item Command
-A command is a Lisp function specially defined to be able to serve as a
-key binding in Emacs. When you type a key sequence (q.v.@:), its
-binding (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find
-the command to run. @xref{Commands}.
-
-@item Command History
-See `minibuffer history.'
-
-@item Command Name
-A command name is the name of a Lisp symbol which is a command
-(@pxref{Commands}). You can invoke any command by its name using
-@kbd{M-x} (@pxref{M-x,M-x,Running Commands by Name}).
-
-@item Comment
-A comment is text in a program which is intended only for humans reading
-the program, and which is marked specially so that it will be ignored
-when the program is loaded or compiled. Emacs offers special commands
-for creating, aligning and killing comments. @xref{Comments}.
-
-@item Common Lisp
-Common Lisp is a dialect of Lisp (q.v.@:) much larger and more powerful
-than Emacs Lisp. Emacs provides a subset of Common Lisp in the CL
-package. @xref{Top, Common Lisp, Overview, cl, Common Lisp Extensions}.
-
-@item Compilation
-Compilation is the process of creating an executable program from source
-code. Emacs has commands for compiling files of Emacs Lisp code
-(@pxref{Byte Compilation,,, elisp, the Emacs Lisp
-Reference Manual}) and programs in C and other languages
-(@pxref{Compilation}).
-
-@item Complete Key
-A complete key is a key sequence which fully specifies one action to be
-performed by Emacs. For example, @kbd{X} and @kbd{C-f} and @kbd{C-x m}
-are complete keys. Complete keys derive their meanings from being bound
-(q.v.@:) to commands (q.v.@:). Thus, @kbd{X} is conventionally bound to
-a command to insert @samp{X} in the buffer; @kbd{C-x m} is
-conventionally bound to a command to begin composing a mail message.
-@xref{Keys}.
-
-@item Completion
-Completion is what Emacs does when it automatically fills out an
-abbreviation for a name into the entire name. Completion is done for
-minibuffer (q.v.@:) arguments when the set of possible valid inputs
-is known; for example, on command names, buffer names, and
-file names. Completion occurs when @key{TAB}, @key{SPC} or @key{RET}
-is typed. @xref{Completion}.@refill
-
-@item Continuation Line
-When a line of text is longer than the width of the window, it
-takes up more than one screen line when displayed. We say that the
-text line is continued, and all screen lines used for it after the
-first are called continuation lines. @xref{Continuation Lines}.
-A related Emacs feature is `filling' (q.v.@:).
-
-@item Control Character
-A control character is a character that you type by holding down the
-@key{CTRL} key. Some control characters also have their own keys, so
-that you can type them without using @key{CTRL}. For example,
-@key{RET}, @key{TAB}, @key{ESC} and @key{DEL} are all control
-characters. @xref{User Input}.
-
-@item Copyleft
-A copyleft is a notice giving the public legal permission to
-redistribute and modify a program or other work of art, but requiring
-modified versions to carry similar permission. Copyright is normally
-used to keep users divided and helpless; with copyleft we turn that
-around to empower users and encourage them to cooperate.
-
-The particular form of copyleft used by the GNU project is called the
-GNU General Public License. @xref{Copying}.
-
-@item @key{CTRL}
-The @key{CTRL} or ``control'' key is what you hold down
-in order to enter a control character (q.v.).
-
-@item Current Buffer
-The current buffer in Emacs is the Emacs buffer on which most editing
-commands operate. You can select any Emacs buffer as the current one.
-@xref{Buffers}.
-
-@item Current Line
-The current line is the line that point is on (@pxref{Point}).
-
-@item Current Paragraph
-The current paragraph is the paragraph that point is in. If point is
-between two paragraphs, the current paragraph is the one that follows
-point. @xref{Paragraphs}.
-
-@item Current Defun
-The current defun is the defun (q.v.@:) that point is in. If point is
-between defuns, the current defun is the one that follows point.
-@xref{Defuns}.
-
-@item Cursor
-The cursor is the rectangle on the screen which indicates the position
-called point (q.v.@:) at which insertion and deletion takes place.
-The cursor is on or under the character that follows point. Often
-people speak of `the cursor' when, strictly speaking, they mean
-`point.' @xref{Point,Cursor}.
-
-@item Customization
-Customization is making minor changes in the way Emacs works. It is
-often done by setting variables (@pxref{Variables}) or faces
-(@pxref{Face Customization}), or by rebinding key sequences
-(@pxref{Keymaps}).
-
-@cindex cut and paste
-@item Cut and Paste
-See `killing' and `yanking.'
-
-@item Default Argument
-The default for an argument is the value that will be assumed if you
-do not specify one. When the minibuffer is used to read an argument,
-the default argument is used if you just type @key{RET}.
-@xref{Minibuffer}.
-
-@item Default
-A default is the value that is used for a certain purpose if and when
-you do not specify a value to use.
-
-@item Default Directory
-When you specify a file name that does not start with @samp{/} or @samp{~},
-it is interpreted relative to the current buffer's default directory.
-(On MS-Windows and MS-DOS, file names which start with a drive letter
-@samp{@var{x}:} are treated as absolute, not relative.)
-@xref{Minibuffer File,Default Directory}.
-
-@item Defun
-A defun is a major definition at the top level in a program. The name
-`defun' comes from Lisp, where most such definitions use the construct
-@code{defun}. @xref{Defuns}.
-
-@item @key{DEL}
-@key{DEL} is a character that runs the command to delete one character
-of text before the cursor. It is typically either the @key{DELETE}
-key or the @key{BACKSPACE} key, whichever one is easy to type.
-@xref{Erasing,DEL}.
-
-@item Deletion
-Deletion means erasing text without copying it into the kill ring
-(q.v.@:). The alternative is killing (q.v.@:). @xref{Killing,Deletion}.
-
-@item Deletion of Files
-Deleting a file means erasing it from the file system.
-@xref{Misc File Ops,Misc File Ops,Miscellaneous File Operations}.
-
-@item Deletion of Messages
-Deleting a message means flagging it to be eliminated from your mail
-file. Until you expunge (q.v.@:) the Rmail file, you can still undelete
-the messages you have deleted. @xref{Rmail Deletion}.
-
-@item Deletion of Windows
-Deleting a window means eliminating it from the screen. Other windows
-expand to use up the space. The deleted window can never come back,
-but no actual text is thereby lost. @xref{Windows}.
-
-@item Directory
-File directories are named collections in the file system, within which
-you can place individual files or subdirectories. @xref{Directories}.
-
-@item Dired
-Dired is the Emacs facility that displays the contents of a file
-directory and allows you to ``edit the directory,'' performing
-operations on the files in the directory. @xref{Dired}.
-
-@item Disabled Command
-A disabled command is one that you may not run without special
-confirmation. The usual reason for disabling a command is that it is
-confusing for beginning users. @xref{Disabling}.
-
-@item Down Event
-Short for `button down event' (q.v.@:).
-
-@item Drag Event
-A drag event is the kind of input event generated when you press a mouse
-button, move the mouse, and then release the button. @xref{Mouse
-Buttons}.
-
-@item Dribble File
-A dribble file is a file into which Emacs writes all the characters that
-you type on the keyboard. Dribble files are used to make a record
-for debugging Emacs bugs. Emacs does not make a dribble file unless you
-tell it to. @xref{Bugs}.
-
-@item Echo Area
-The echo area is the bottom line of the screen, used for echoing the
-arguments to commands, for asking questions, and showing brief messages
-(including error messages). The messages are stored in the buffer
-@samp{*Messages*} so you can review them later. @xref{Echo Area}.
-
-@item Echoing
-Echoing is acknowledging the receipt of input events by displaying
-them (in the echo area). Emacs never echoes single-character key
-sequences; longer key sequences echo only if you pause while typing
-them.
-
-@item Electric
-We say that a character is electric if it is normally self-inserting
-(q.v.@:), but the current major mode (q.v.@:) redefines it to do something
-else as well. For example, some programming language major modes define
-particular delimiter characters to reindent the line or insert one or
-more newlines in addition to self-insertion.
-
-@item End Of Line
-End of line is a character or a sequence of characters that indicate
-the end of a text line. On GNU and Unix systems, this is a newline
-(q.v.@:), but other systems have other conventions. @xref{Coding
-Systems,end-of-line}. Emacs can recognize several end-of-line
-conventions in files and convert between them.
-
-@item Environment Variable
-An environment variable is one of a collection of variables stored by
-the operating system, each one having a name and a value. Emacs can
-access environment variables set by its parent shell, and it can set
-variables in the environment it passes to programs it invokes.
-@xref{Environment}.
-
-@item EOL
-See `end of line.'
-
-@item Error
-An error occurs when an Emacs command cannot execute in the current
-circumstances. When an error occurs, execution of the command stops
-(unless the command has been programmed to do otherwise) and Emacs
-reports the error by displaying an error message (q.v.@:). Type-ahead
-is discarded. Then Emacs is ready to read another editing command.
-
-@item Error Message
-An error message is a single line of output displayed by Emacs when the
-user asks for something impossible to do (such as, killing text
-forward when point is at the end of the buffer). They appear in the
-echo area, accompanied by a beep.
-
-@item @key{ESC}
-@key{ESC} is a character used as a prefix for typing Meta characters on
-keyboards lacking a @key{META} key. Unlike the @key{META} key (which,
-like the @key{SHIFT} key, is held down while another character is
-typed), you press the @key{ESC} key as you would press a letter key, and
-it applies to the next character you type.
-
-@item Expression
-See `balanced expression.'
-
-@item Expunging
-Expunging an Rmail file or Dired buffer or a Gnus newsgroup buffer is an
-operation that truly discards the messages or files you have previously
-flagged for deletion.
-
-@item Face
-A face is a style of displaying characters. It specifies attributes
-such as font family and size, foreground and background colors,
-underline and strike-through, background stipple, etc. Emacs provides
-features to associate specific faces with portions of buffer text, in
-order to display that text as specified by the face attributes.
-@xref{Faces}.
-
-@item File Locking
-Emacs uses file locking to notice when two different users
-start to edit one file at the same time. @xref{Interlocking}.
-
-@item File Name
-A file name is a name that refers to a file. File names may be relative
-or absolute; the meaning of a relative file name depends on the current
-directory, but an absolute file name refers to the same file regardless
-of which directory is current. On GNU and Unix systems, an absolute
-file name starts with a slash (the root directory) or with @samp{~/} or
-@samp{~@var{user}/} (a home directory). On MS-Windows/MS-DOS, an
-absolute file name can also start with a drive letter and a colon
-@samp{@var{d}:}.
-
-Some people use the term ``pathname'' for file names, but we do not;
-we use the word ``path'' only in the term ``search path'' (q.v.@:).
-
-@item File-Name Component
-A file-name component names a file directly within a particular
-directory. On GNU and Unix systems, a file name is a sequence of
-file-name components, separated by slashes. For example, @file{foo/bar}
-is a file name containing two components, @samp{foo} and @samp{bar}; it
-refers to the file named @samp{bar} in the directory named @samp{foo} in
-the current directory. MS-DOS/MS-Windows file names can also use
-backslashes to separate components, as in @file{foo\bar}.
-
-@item Fill Prefix
-The fill prefix is a string that should be expected at the beginning
-of each line when filling is done. It is not regarded as part of the
-text to be filled. @xref{Filling}.
-
-@item Filling
-Filling text means shifting text between consecutive lines so that all
-the lines are approximately the same length. @xref{Filling}. Some
-other editors call this feature `line wrapping.'
-
-@item Font Lock
-Font Lock is a mode that highlights parts of buffer text according to
-its syntax. @xref{Font Lock}.
-
-@item Fontset
-A fontset is a named collection of fonts. A fontset specification lists
-character sets and which font to use to display each of them. Fontsets
-make it easy to change several fonts at once by specifying the name of a
-fontset, rather than changing each font separately. @xref{Fontsets}.
-
-@item Formatted Text
-Formatted text is text that displays with formatting information while
-you edit. Formatting information includes fonts, colors, and specified
-margins. @xref{Formatted Text}.
-
-@item Formfeed Character
-See `page.'
-
-@item Frame
-A frame is a rectangular cluster of Emacs windows. Emacs starts out
-with one frame, but you can create more. You can subdivide each frame
-into Emacs windows (q.v.@:). When you are using a window system
-(q.v.@:), all the frames can be visible at the same time.
-@xref{Frames}. Some other editors use the term ``window'' for this,
-but in Emacs a window means something else.
-
-@item Fringe
-On a graphical display (q.v.@:), there's a narrow portion of the
-frame (q.v.@:) between the text area and the window's border. Emacs
-displays the fringe using a special face (q.v.@:) called
-@code{fringe}. @xref{Faces,fringe}.
-
-@item FTP
-FTP is an acronym for File Transfer Protocol. Emacs uses an FTP client
-program to provide access to remote files (q.v.@:).
-
-@item Function Key
-A function key is a key on the keyboard that sends input but does not
-correspond to any character. @xref{Function Keys}.
-
-@item Global
-Global means ``independent of the current environment; in effect
-throughout Emacs.'' It is the opposite of local (q.v.@:). Particular
-examples of the use of `global' appear below.
-
-@item Global Abbrev
-A global definition of an abbrev (q.v.@:) is effective in all major
-modes that do not have local (q.v.@:) definitions for the same abbrev.
-@xref{Abbrevs}.
-
-@item Global Keymap
-The global keymap (q.v.@:) contains key bindings that are in effect
-except when overridden by local key bindings in a major mode's local
-keymap (q.v.@:). @xref{Keymaps}.
-
-@item Global Mark Ring
-The global mark ring records the series of buffers you have recently
-set a mark (q.v.@:) in. In many cases you can use this to backtrack
-through buffers you have been editing in, or in which you have found
-tags (see `tags table'). @xref{Global Mark Ring}.
-
-@item Global Substitution
-Global substitution means replacing each occurrence of one string by
-another string throughout a large amount of text. @xref{Replace}.
-
-@item Global Variable
-The global value of a variable (q.v.@:) takes effect in all buffers
-that do not have their own local (q.v.@:) values for the variable.
-@xref{Variables}.
-
-@item Graphic Character
-Graphic characters are those assigned pictorial images rather than
-just names. All the non-Meta (q.v.@:) characters except for the
-Control (q.v.@:) characters are graphic characters. These include
-letters, digits, punctuation, and spaces; they do not include
-@key{RET} or @key{ESC}. In Emacs, typing a graphic character inserts
-that character (in ordinary editing modes). @xref{Inserting Text}.
-
-@item Graphical Display
-A graphical display is one that can display images and multiple fonts.
-Usually it also has a window system (q.v.@:).
-
-@item Highlighting
-Highlighting text means displaying it with a different foreground and/or
-background color to make it stand out from the rest of the text in the
-buffer.
-
-Emacs uses highlighting in several ways. When you mark a region with
-the mouse, the region is always highlighted. Optionally Emacs can
-also highlight the region whenever it is active (@pxref{Transient
-Mark}). Incremental search also highlights matches (@pxref{Incremental
-Search}). See also `font lock'.
-
-@item Hardcopy
-Hardcopy means printed output. Emacs has commands for making printed
-listings of text in Emacs buffers. @xref{Printing}.
-
-@item @key{HELP}
-@key{HELP} is the Emacs name for @kbd{C-h} or @key{F1}. You can type
-@key{HELP} at any time to ask what options you have, or to ask what any
-command does. @xref{Help}.
-
-@item Help Echo
-Help echo is a short message displayed in the echo area when the mouse
-pointer is located on portions of display that require some
-explanations. Emacs displays help echo for menu items, parts of the
-mode line, tool-bar buttons, etc. On graphics displays, the messages
-can be displayed as tooltips (q.v.@:). @xref{Tooltips}.
-
-@item Hook
-A hook is a list of functions to be called on specific occasions, such
-as saving a buffer in a file, major mode activation, etc. By
-customizing the various hooks, you can modify Emacs's behavior without
-changing any of its code. @xref{Hooks}.
-
-@item Hyper
-Hyper is the name of a modifier bit which a keyboard input character may
-have. To make a character Hyper, type it while holding down the
-@key{HYPER} key. Such characters are given names that start with
-@kbd{Hyper-} (usually written @kbd{H-} for short). @xref{User Input,
-Hyper}.
-
-@item Iff
-``Iff'' means ``if and only if.'' This terminology comes from
-mathematics. Try to avoid using this term in documentation, since
-many are unfamiliar with it and mistake it for a typo.
-
-@item Inbox
-An inbox is a file in which mail is delivered by the operating system.
-Rmail transfers mail from inboxes to Rmail files (q.v.@:) in which the
-mail is then stored permanently or until explicitly deleted.
-@xref{Rmail Inbox}.
-
-@item Incremental Search
-Emacs provides an incremental search facility, whereby Emacs searches
-for the string as you type it. @xref{Incremental Search}.
-
-@item Indentation
-Indentation means blank space at the beginning of a line. Most
-programming languages have conventions for using indentation to
-illuminate the structure of the program, and Emacs has special
-commands to adjust indentation.
-@xref{Indentation}.
-
-@item Indirect Buffer
-An indirect buffer is a buffer that shares the text of another buffer,
-called its base buffer (q.v.@:). @xref{Indirect Buffers}.
-
-@item Info
-Info is the hypertext format used by the GNU project for writing
-documentation.
-
-@item Input Event
-An input event represents, within Emacs, one action taken by the user on
-the terminal. Input events include typing characters, typing function
-keys, pressing or releasing mouse buttons, and switching between Emacs
-frames. @xref{User Input}.
-
-@item Input Method
-An input method is a system for entering non-@acronym{ASCII} text characters by
-typing sequences of @acronym{ASCII} characters (q.v.@:). @xref{Input Methods}.
-
-@item Insertion
-Insertion means copying text into the buffer, either from the keyboard
-or from some other place in Emacs.
-
-@item Interlocking
-Interlocking is a feature for warning when you start to alter a file
-that someone else is already editing.
-@xref{Interlocking,Interlocking,Simultaneous Editing}.
-
-@item Isearch
-See `incremental search.'
-
-@item Justification
-Justification means adding extra spaces within lines of text to make
-them extend exactly to a specified width.
-@xref{Format Justification}.
-
-@item Keybinding
-See `binding.'
-
-@item Keyboard Macro
-Keyboard macros are a way of defining new Emacs commands from
-sequences of existing ones, with no need to write a Lisp program.
-@xref{Keyboard Macros}.
-
-@cindex keyboard shortcuts
-@item Keyboard Shortcut
-A keyboard shortcut is a key sequence (q.v.@:) which invokes a
-command. What some programs call ``assigning a keyboard shortcut,''
-Emacs calls ``binding a key sequence.'' See `binding.'
-
-@item Key Sequence
-A key sequence (key, for short) is a sequence of input events (q.v.@:)
-that are meaningful as a single unit. If the key sequence is enough to
-specify one action, it is a complete key (q.v.@:); if it is not enough,
-it is a prefix key (q.v.@:). @xref{Keys}.
-
-@item Keymap
-The keymap is the data structure that records the bindings (q.v.@:) of
-key sequences to the commands that they run. For example, the global
-keymap binds the character @kbd{C-n} to the command function
-@code{next-line}. @xref{Keymaps}.
-
-@item Keyboard Translation Table
-The keyboard translation table is an array that translates the character
-codes that come from the terminal into the character codes that make up
-key sequences.
-
-@item Kill Ring
-The kill ring is where all text you have killed recently is saved.
-You can reinsert any of the killed text still in the ring; this is
-called yanking (q.v.@:). @xref{Yanking}.
-
-@item Killing
-Killing means erasing text and saving it on the kill ring so it can be
-yanked (q.v.@:) later. Some other systems call this ``cutting.''
-Most Emacs commands that erase text perform killing, as opposed to
-deletion (q.v.@:). @xref{Killing}.
-
-@item Killing a Job
-Killing a job (such as, an invocation of Emacs) means making it cease
-to exist. Any data within it, if not saved in a file, is lost.
-@xref{Exiting}.
-
-@item Language Environment
-Your choice of language environment specifies defaults for the input
-method (q.v.@:) and coding system (q.v.@:). @xref{Language
-Environments}. These defaults are relevant if you edit non-@acronym{ASCII} text
-(@pxref{International}).
-
-@item Line Wrapping
-See `filling.'
-
-@item Lisp
-Lisp is a programming language. Most of Emacs is written in a dialect
-of Lisp, called Emacs Lisp, that is extended with special features which
-make it especially suitable for text editing tasks.
-
-@item List
-A list is, approximately, a text string beginning with an open
-parenthesis and ending with the matching close parenthesis. In C mode
-and other non-Lisp modes, groupings surrounded by other kinds of matched
-delimiters appropriate to the language, such as braces, are also
-considered lists. Emacs has special commands for many operations on
-lists. @xref{Moving by Parens}.
-
-@item Local
-Local means ``in effect only in a particular context''; the relevant
-kind of context is a particular function execution, a particular
-buffer, or a particular major mode. It is the opposite of `global'
-(q.v.@:). Specific uses of `local' in Emacs terminology appear below.
-
-@item Local Abbrev
-A local abbrev definition is effective only if a particular major mode
-is selected. In that major mode, it overrides any global definition
-for the same abbrev. @xref{Abbrevs}.
-
-@item Local Keymap
-A local keymap is used in a particular major mode; the key bindings
-(q.v.@:) in the current local keymap override global bindings of the
-same key sequences. @xref{Keymaps}.
-
-@item Local Variable
-A local value of a variable (q.v.@:) applies to only one buffer.
-@xref{Locals}.
-
-@item @kbd{M-}
-@kbd{M-} in the name of a character is an abbreviation for @key{META},
-one of the modifier keys that can accompany any character.
-@xref{User Input,M-}.
-
-@item @kbd{M-C-}
-@kbd{M-C-} in the name of a character is an abbreviation for
-Control-Meta; it means the same thing as @kbd{C-M-}. If your
-terminal lacks a real @key{META} key, you type a Control-Meta character by
-typing @key{ESC} and then typing the corresponding Control character.
-@xref{User Input,C-M-}.
-
-@item @kbd{M-x}
-@kbd{M-x} is the key sequence which is used to call an Emacs command by
-name. This is how you run commands that are not bound to key sequences.
-@xref{M-x,M-x,Running Commands by Name}.
-
-@item Mail
-Mail means messages sent from one user to another through the computer
-system, to be read at the recipient's convenience. Emacs has commands for
-composing and sending mail, and for reading and editing the mail you have
-received. @xref{Sending Mail}. @xref{Rmail}, for how to read mail.
-
-@item Mail Composition Method
-A mail composition method is a program runnable within Emacs for editing
-and sending a mail message. Emacs lets you select from several
-alternative mail composition methods. @xref{Mail Methods}.
-
-@item Major Mode
-The Emacs major modes are a mutually exclusive set of options, each of
-which configures Emacs for editing a certain sort of text. Ideally,
-each programming language has its own major mode. @xref{Major Modes}.
-
-@item Margin
-The space between the usable part of a window (including the
-fringe) and the window edge.
-
-@item Mark
-The mark points to a position in the text. It specifies one end of the
-region (q.v.@:), point being the other end. Many commands operate on
-all the text from point to the mark. Each buffer has its own mark.
-@xref{Mark}.
-
-@item Mark Ring
-The mark ring is used to hold several recent previous locations of the
-mark, just in case you want to move back to them. Each buffer has its
-own mark ring; in addition, there is a single global mark ring (q.v.@:).
-@xref{Mark Ring}.
-
-@item Menu Bar
-The menu bar is the line at the top of an Emacs frame. It contains
-words you can click on with the mouse to bring up menus, or you can use
-a keyboard interface to navigate it. @xref{Menu Bars}.
-
-@item Message
-See `mail.'
-
-@item Meta
-Meta is the name of a modifier bit which you can use in a command
-character. To enter a meta character, you hold down the @key{META}
-key while typing the character. We refer to such characters with
-names that start with @kbd{Meta-} (usually written @kbd{M-} for
-short). For example, @kbd{M-<} is typed by holding down @key{META}
-and at the same time typing @kbd{<} (which itself is done, on most
-terminals, by holding down @key{SHIFT} and typing @kbd{,}).
-@xref{User Input,Meta}.
-
-On some terminals, the @key{META} key is actually labeled @key{ALT}
-or @key{EDIT}.
-
-@item Meta Character
-A Meta character is one whose character code includes the Meta bit.
-
-@item Minibuffer
-The minibuffer is the window that appears when necessary inside the
-echo area (q.v.@:), used for reading arguments to commands.
-@xref{Minibuffer}.
-
-@item Minibuffer History
-The minibuffer history records the text you have specified in the past
-for minibuffer arguments, so you can conveniently use the same text
-again. @xref{Minibuffer History}.
-
-@item Minor Mode
-A minor mode is an optional feature of Emacs which can be switched on
-or off independently of all other features. Each minor mode has a
-command to turn it on or off. @xref{Minor Modes}.
-
-@item Minor Mode Keymap
-A minor mode keymap is a keymap that belongs to a minor mode and is
-active when that mode is enabled. Minor mode keymaps take precedence
-over the buffer's local keymap, just as the local keymap takes
-precedence over the global keymap. @xref{Keymaps}.
-
-@item Mode Line
-The mode line is the line at the bottom of each window (q.v.@:), giving
-status information on the buffer displayed in that window. @xref{Mode
-Line}.
-
-@item Modified Buffer
-A buffer (q.v.@:) is modified if its text has been changed since the
-last time the buffer was saved (or since when it was created, if it
-has never been saved). @xref{Saving}.
-
-@item Moving Text
-Moving text means erasing it from one place and inserting it in
-another. The usual way to move text is by killing (q.v.@:) it and then
-yanking (q.v.@:) it. @xref{Killing}.
-
-@item MULE
-MULE refers to the Emacs features for editing multilingual non-@acronym{ASCII} text
-using multibyte characters (q.v.@:). @xref{International}.
-
-@item Multibyte Character
-A multibyte character is a character that takes up several bytes in a
-buffer. Emacs uses multibyte characters to represent non-@acronym{ASCII} text,
-since the number of non-@acronym{ASCII} characters is much more than 256.
-@xref{International Chars, International Characters}.
-
-@item Named Mark
-A named mark is a register (q.v.@:) in its role of recording a
-location in text so that you can move point to that location.
-@xref{Registers}.
-
-@item Narrowing
-Narrowing means creating a restriction (q.v.@:) that limits editing in
-the current buffer to only a part of the text in the buffer. Text
-outside that part is inaccessible for editing until the boundaries are
-widened again, but it is still there, and saving the file saves it
-all. @xref{Narrowing}.
-
-@item Newline
-Control-J characters in the buffer terminate lines of text and are
-therefore also called newlines. @xref{Text Characters,Newline}.
-
-@cindex nil
-@cindex t
-@item @code{nil}
-@code{nil} is a value usually interpreted as a logical ``false.'' Its
-opposite is @code{t}, interpreted as ``true.''
-
-@item Numeric Argument
-A numeric argument is a number, specified before a command, to change
-the effect of the command. Often the numeric argument serves as a
-repeat count. @xref{Arguments}.
-
-@item Overwrite Mode
-Overwrite mode is a minor mode. When it is enabled, ordinary text
-characters replace the existing text after point rather than pushing
-it to the right. @xref{Minor Modes}.
-
-@item Page
-A page is a unit of text, delimited by formfeed characters (@acronym{ASCII}
-control-L, code 014) coming at the beginning of a line. Some Emacs
-commands are provided for moving over and operating on pages.
-@xref{Pages}.
-
-@item Paragraph
-Paragraphs are the medium-size unit of human-language text. There are
-special Emacs commands for moving over and operating on paragraphs.
-@xref{Paragraphs}.
-
-@item Parsing
-We say that certain Emacs commands parse words or expressions in the
-text being edited. Really, all they know how to do is find the other
-end of a word or expression. @xref{Syntax}.
-
-@item Point
-Point is the place in the buffer at which insertion and deletion
-occur. Point is considered to be between two characters, not at one
-character. The terminal's cursor (q.v.@:) indicates the location of
-point. @xref{Point}.
-
-@item Prefix Argument
-See `numeric argument.'
-
-@item Prefix Key
-A prefix key is a key sequence (q.v.@:) whose sole function is to
-introduce a set of longer key sequences. @kbd{C-x} is an example of
-prefix key; any two-character sequence starting with @kbd{C-x} is
-therefore a legitimate key sequence. @xref{Keys}.
-
-@item Primary Rmail File
-Your primary Rmail file is the file named @samp{RMAIL} in your home
-directory. That's where Rmail stores your incoming mail, unless you
-specify a different file name. @xref{Rmail}.
-
-@item Primary Selection
-The primary selection is one particular X selection (q.v.@:); it is the
-selection that most X applications use for transferring text to and from
-other applications.
-
-The Emacs kill commands set the primary selection and the yank command
-uses the primary selection when appropriate. @xref{Killing}.
-
-@item Prompt
-A prompt is text used to ask the user for input. Displaying a prompt
-is called prompting. Emacs prompts always appear in the echo area
-(q.v.@:). One kind of prompting happens when the minibuffer is used to
-read an argument (@pxref{Minibuffer}); the echoing which happens when
-you pause in the middle of typing a multi-character key sequence is also
-a kind of prompting (@pxref{Echo Area}).
-
-@item Query-Replace
-Query-replace is an interactive string replacement feature provided by
-Emacs. @xref{Query Replace}.
-
-@item Quitting
-Quitting means canceling a partially typed command or a running
-command, using @kbd{C-g} (or @kbd{C-@key{BREAK}} on MS-DOS). @xref{Quitting}.
-
-@item Quoting
-Quoting means depriving a character of its usual special significance.
-The most common kind of quoting in Emacs is with @kbd{C-q}. What
-constitutes special significance depends on the context and on
-convention. For example, an ``ordinary'' character as an Emacs command
-inserts itself; so in this context, a special character is any character
-that does not normally insert itself (such as @key{DEL}, for example),
-and quoting it makes it insert itself as if it were not special. Not
-all contexts allow quoting. @xref{Inserting Text,Quoting}.
-
-@item Quoting File Names
-Quoting a file name turns off the special significance of constructs
-such as @samp{$}, @samp{~} and @samp{:}. @xref{Quoted File Names}.
-
-@item Read-Only Buffer
-A read-only buffer is one whose text you are not allowed to change.
-Normally Emacs makes buffers read-only when they contain text which
-has a special significance to Emacs; for example, Dired buffers.
-Visiting a file that is write-protected also makes a read-only buffer.
-@xref{Buffers}.
-
-@item Rectangle
-A rectangle consists of the text in a given range of columns on a given
-range of lines. Normally you specify a rectangle by putting point at
-one corner and putting the mark at the diagonally opposite corner.
-@xref{Rectangles}.
-
-@item Recursive Editing Level
-A recursive editing level is a state in which part of the execution of
-a command involves asking you to edit some text. This text may
-or may not be the same as the text to which the command was applied.
-The mode line indicates recursive editing levels with square brackets
-(@samp{[} and @samp{]}). @xref{Recursive Edit}.
-
-@item Redisplay
-Redisplay is the process of correcting the image on the screen to
-correspond to changes that have been made in the text being edited.
-@xref{Screen,Redisplay}.
-
-@item Regexp
-See `regular expression.'
-
-@item Region
-The region is the text between point (q.v.@:) and the mark (q.v.@:).
-Many commands operate on the text of the region. @xref{Mark,Region}.
-
-@item Register
-Registers are named slots in which text or buffer positions or
-rectangles can be saved for later use. @xref{Registers}. A related
-Emacs feature is `bookmarks' (q.v.@:).
-
-@item Regular Expression
-A regular expression is a pattern that can match various text strings;
-for example, @samp{a[0-9]+} matches @samp{a} followed by one or more
-digits. @xref{Regexps}.
-
-@item Remote File
-A remote file is a file that is stored on a system other than your own.
-Emacs can access files on other computers provided that they are
-connected to the same network as your machine, and (obviously) that
-you have a supported method to gain access to those files.
-@xref{Remote Files}.
-
-@item Repeat Count
-See `numeric argument.'
-
-@item Replacement
-See `global substitution.'
-
-@item Restriction
-A buffer's restriction is the amount of text, at the beginning or the
-end of the buffer, that is temporarily inaccessible. Giving a buffer a
-nonzero amount of restriction is called narrowing (q.v.@:); removing
-a restriction is called widening (q.v.@:). @xref{Narrowing}.
-
-@item @key{RET}
-@key{RET} is a character that in Emacs runs the command to insert a
-newline into the text. It is also used to terminate most arguments
-read in the minibuffer (q.v.@:). @xref{User Input,Return}.
-
-@item Reverting
-Reverting means returning to the original state. Emacs lets you
-revert a buffer by re-reading its file from disk. @xref{Reverting}.
-
-@item Rmail File
-An Rmail file is a file containing text in a special format used by
-Rmail for storing mail. @xref{Rmail}.
-
-@item Saving
-Saving a buffer means copying its text into the file that was visited
-(q.v.@:) in that buffer. This is the way text in files actually gets
-changed by your Emacs editing. @xref{Saving}.
-
-@item Scroll Bar
-A scroll bar is a tall thin hollow box that appears at the side of a
-window. You can use mouse commands in the scroll bar to scroll the
-window. The scroll bar feature is supported only under windowing
-systems. @xref{Scroll Bars}.
-
-@item Scrolling
-Scrolling means shifting the text in the Emacs window so as to see a
-different part of the buffer. @xref{Scrolling}.
-
-@item Searching
-Searching means moving point to the next occurrence of a specified
-string or the next match for a specified regular expression.
-@xref{Search}.
-
-@item Search Path
-A search path is a list of directory names, to be used for searching for
-files for certain purposes. For example, the variable @code{load-path}
-holds a search path for finding Lisp library files. @xref{Lisp Libraries}.
-
-@item Secondary Selection
-The secondary selection is one particular X selection; some X
-applications can use it for transferring text to and from other
-applications. Emacs has special mouse commands for transferring text
-using the secondary selection. @xref{Secondary Selection}.
-
-@item Selected Frame
-The selected frame is the one your input currently operates on.
-@xref{Frames}.
-
-@item Selected Window
-The selected frame is the one your input currently operates on.
-@xref{Basic Window}.
-
-@item Selecting a Buffer
-Selecting a buffer means making it the current (q.v.@:) buffer.
-@xref{Select Buffer}.
-
-@item Selection
-Windowing systems allow an application program to specify
-selections whose values are text. A program can also read the
-selections that other programs have set up. This is the principal way
-of transferring text between window applications. Emacs has commands to
-work with the primary (q.v.@:) selection and the secondary (q.v.@:)
-selection, and also with the clipboard (q.v.@:).
-
-@item Self-Documentation
-Self-documentation is the feature of Emacs which can tell you what any
-command does, or give you a list of all commands related to a topic
-you specify. You ask for self-documentation with the help character,
-@kbd{C-h}. @xref{Help}.
-
-@item Self-Inserting Character
-A character is self-inserting if typing that character inserts that
-character in the buffer. Ordinary printing and whitespace characters
-are self-inserting in Emacs, except in certain special major modes.
-
-@item Sentences
-Emacs has commands for moving by or killing by sentences.
-@xref{Sentences}.
-
-@item Sexp
-A sexp (short for ``s-expression'') is the basic syntactic unit of
-Lisp in its textual form: either a list, or Lisp atom. Sexps are also
-the balanced expressions (q.v.@:) of the Lisp language; this is why
-the commands for editing balanced expressions have `sexp' in their
-name. @xref{Expressions,Sexps}.
-
-@item Simultaneous Editing
-Simultaneous editing means two users modifying the same file at once.
-Simultaneous editing, if not detected, can cause one user to lose his
-or her work. Emacs detects all cases of simultaneous editing, and
-warns one of the users to investigate.
-@xref{Interlocking,Interlocking,Simultaneous Editing}.
-
-@item @key{SPC}
-@key{SPC} is the space character, which you enter by pressing the
-space bar.
-
-@item Speedbar
-The speedbar is a special tall frame that provides fast access to Emacs
-buffers, functions within those buffers, Info nodes, and other
-interesting parts of text within Emacs. @xref{Speedbar}.
-
-@item Spell Checking
-Spell checking means checking correctness of the written form of each
-one of the words in a text. Emacs uses the Ispell spelling-checker
-program to check the spelling of parts of a buffer via a convenient user
-interface. @xref{Spelling}.
-
-@item String
-A string is a kind of Lisp data object which contains a sequence of
-characters. Many Emacs variables are intended to have strings as
-values. The Lisp syntax for a string consists of the characters in the
-string with a @samp{"} before and another @samp{"} after. A @samp{"}
-that is part of the string must be written as @samp{\"} and a @samp{\}
-that is part of the string must be written as @samp{\\}. All other
-characters, including newline, can be included just by writing them
-inside the string; however, backslash sequences as in C, such as
-@samp{\n} for newline or @samp{\241} using an octal character code, are
-allowed as well.
-
-@item String Substitution
-See `global substitution'.
-
-@item Syntax Highlighting
-See `font lock.'
-
-@item Syntax Table
-The syntax table tells Emacs which characters are part of a word,
-which characters balance each other like parentheses, etc.
-@xref{Syntax}.
-
-@item Super
-Super is the name of a modifier bit which a keyboard input character may
-have. To make a character Super, type it while holding down the
-@key{SUPER} key. Such characters are given names that start with
-@kbd{Super-} (usually written @kbd{s-} for short). @xref{User Input,
-Super}.
-
-@item Suspending
-Suspending Emacs means stopping it temporarily and returning control
-to its parent process, which is usually a shell. Unlike killing a job
-(q.v.@:), you can later resume the suspended Emacs job without losing
-your buffers, unsaved edits, undo history, etc. @xref{Exiting}.
-
-@item @key{TAB}
-@key{TAB} is the tab character. In Emacs it is typically used for
-indentation or completion.
-
-@item Tags Table
-A tags table is a file that serves as an index to the function
-definitions in one or more other files. @xref{Tags}.
-
-@item Termscript File
-A termscript file contains a record of all characters sent by Emacs to
-the terminal. It is used for tracking down bugs in Emacs redisplay.
-Emacs does not make a termscript file unless you tell it to.
-@xref{Bugs}.
-
-@item Text
-`Text' has two meanings (@pxref{Text}):
-
-@itemize @bullet
-@item
-Data consisting of a sequence of characters, as opposed to binary
-numbers, executable programs, and the like. The basic contents of an
-Emacs buffer (aside from the text properties, q.v.@:) are always text
-in this sense.
-@item
-Data consisting of written human language, as opposed to programs,
-or following the stylistic conventions of human language.
-@end itemize
-
-@item Text-only Terminal
-A text-only terminal is a display that is limited to displaying text in
-character units. Such a terminal cannot control individual pixels it
-displays. Emacs supports a subset of display features on text-only
-terminals.
-
-@item Text Properties
-Text properties are annotations recorded for particular characters in
-the buffer. Images in the buffer are recorded as text properties;
-they also specify formatting information. @xref{Editing Format Info}.
-
-@item Tool Bar
-The tool bar is a line (sometimes multiple lines) of icons at the top
-of an Emacs frame. Clicking on one of these icons executes a command.
-You can think of this as a graphical relative of the menu bar (q.v.@:).
-@xref{Tool Bars}.
-
-@item Tooltips
-Tooltips are small windows displaying a help echo (q.v.@:) text that
-explains parts of the display, lists useful options available via mouse
-clicks, etc. @xref{Tooltips}.
-
-@item Top Level
-Top level is the normal state of Emacs, in which you are editing the
-text of the file you have visited. You are at top level whenever you
-are not in a recursive editing level (q.v.@:) or the minibuffer
-(q.v.@:), and not in the middle of a command. You can get back to top
-level by aborting (q.v.@:) and quitting (q.v.@:). @xref{Quitting}.
-
-@item Transposition
-Transposing two units of text means putting each one into the place
-formerly occupied by the other. There are Emacs commands to transpose
-two adjacent characters, words, balanced expressions (q.v.@:) or lines
-(@pxref{Transpose}).
-
-@item Truncation
-Truncating text lines in the display means leaving out any text on a
-line that does not fit within the right margin of the window
-displaying it. See also `continuation line.'
-@xref{Continuation Lines,Truncation}.
-
-@item TTY
-See `text-only terminal.'
-
-@item Undoing
-Undoing means making your previous editing go in reverse, bringing
-back the text that existed earlier in the editing session.
-@xref{Undo}.
-
-@item User Option
-A user option is a face (q.v.@:) or a variable (q.v.@:) that exists so
-that you can customize Emacs by setting it to a new value.
-@xref{Easy Customization}.
-
-@item Variable
-A variable is an object in Lisp that can store an arbitrary value.
-Emacs uses some variables for internal purposes, and has others (known
-as `user options' (q.v.@:)) just so that you can set their values to
-control the behavior of Emacs. The variables used in Emacs that you
-are likely to be interested in are listed in the Variables Index in
-this manual (@pxref{Variable Index}). @xref{Variables}, for
-information on variables.
-
-@item Version Control
-Version control systems keep track of multiple versions of a source file.
-They provide a more powerful alternative to keeping backup files (q.v.@:).
-@xref{Version Control}.
-
-@item Visiting
-Visiting a file means loading its contents into a buffer (q.v.@:)
-where they can be edited. @xref{Visiting}.
-
-@item Whitespace
-Whitespace is any run of consecutive formatting characters (space,
-tab, newline, and backspace).
-
-@item Widening
-Widening is removing any restriction (q.v.@:) on the current buffer;
-it is the opposite of narrowing (q.v.@:). @xref{Narrowing}.
-
-@item Window
-Emacs divides a frame (q.v.@:) into one or more windows, each of which
-can display the contents of one buffer (q.v.@:) at any time.
-@xref{Screen}, for basic information on how Emacs uses the screen.
-@xref{Windows}, for commands to control the use of windows. Some
-other editors use the term ``window'' for what we call a `frame'
-(q.v.@:) in Emacs.
-
-@item Window System
-A window system is software that operates on a graphical display
-(q.v.@:), to subdivide the screen so that multiple applications can
-have their] own windows at the same time. All modern operating systems
-include a window system.
-
-@item Word Abbrev
-See `abbrev.'
-
-@item Word Search
-Word search is searching for a sequence of words, considering the
-punctuation between them as insignificant. @xref{Word Search}.
-
-@item WYSIWYG
-WYSIWYG stands for ``What you see is what you get.'' Emacs generally
-provides WYSIWYG editing for files of characters; in Enriched mode
-(@pxref{Formatted Text}), it provides WYSIWYG editing for files that
-include text formatting information.
-
-@item Yanking
-Yanking means reinserting text previously killed. It can be used to
-undo a mistaken kill, or for copying or moving text. Some other
-systems call this ``pasting.'' @xref{Yanking}.
-@end table
-
-@ignore
- arch-tag: 0dd53ce1-5f09-4ac2-b13b-cf22b0f28d23
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1995, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
-@ifclear justgnu
-@node Manifesto,, Microsoft Windows, Top
-@unnumbered The GNU Manifesto
-@end ifclear
-@ifset justgnu
-Copyright @copyright{} 1985, 1993, 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.
-
-@node Top
-@top The GNU Manifesto
-@end ifset
-
-@quotation
-The GNU Manifesto which appears below was written by Richard Stallman at
-the beginning of the GNU project, to ask for participation and support.
-For the first few years, it was updated in minor ways to account for
-developments, but now it seems best to leave it unchanged as most people
-have seen it.
-
-Since that time, we have learned about certain common misunderstandings
-that different wording could help avoid. Footnotes added in 1993 help
-clarify these points.
-
-For up-to-date information about available GNU software, please see
-our web site, @uref{http://www.gnu.org}. For software tasks and other
-ways to contribute, see @uref{http://www.gnu.org/help}.
-@end quotation
-
-@unnumberedsec What's GNU? Gnu's Not Unix!
-
-GNU, which stands for Gnu's Not Unix, is the name for the complete
-Unix-compatible software system which I am writing so that I can give it
-away free to everyone who can use it.@footnote{The wording here was
-careless. The intention was that nobody would have to pay for
-@emph{permission} to use the GNU system. But the words don't make this
-clear, and people often interpret them as saying that copies of GNU
-should always be distributed at little or no charge. That was never the
-intent; later on, the manifesto mentions the possibility of companies
-providing the service of distribution for a profit. Subsequently I have
-learned to distinguish carefully between ``free'' in the sense of
-freedom and ``free'' in the sense of price. Free software is software
-that users have the freedom to distribute and change. Some users may
-obtain copies at no charge, while others pay to obtain copies---and if
-the funds help support improving the software, so much the better. The
-important thing is that everyone who has a copy has the freedom to
-cooperate with others in using it.} Several other volunteers are helping
-me. Contributions of time, money, programs and equipment are greatly
-needed.
-
-So far we have an Emacs text editor with Lisp for writing editor commands,
-a source level debugger, a yacc-compatible parser generator, a linker, and
-around 35 utilities. A shell (command interpreter) is nearly completed. A
-new portable optimizing C compiler has compiled itself and may be released
-this year. An initial kernel exists but many more features are needed to
-emulate Unix. When the kernel and compiler are finished, it will be
-possible to distribute a GNU system suitable for program development. We
-will use @TeX{} as our text formatter, but an nroff is being worked on. We
-will use the free, portable X window system as well. After this we will
-add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of
-other things, plus on-line documentation. We hope to supply, eventually,
-everything useful that normally comes with a Unix system, and more.
-
-GNU will be able to run Unix programs, but will not be identical to Unix.
-We will make all improvements that are convenient, based on our experience
-with other operating systems. In particular, we plan to have longer
-file names, file version numbers, a crashproof file system, file name
-completion perhaps, terminal-independent display support, and perhaps
-eventually a Lisp-based window system through which several Lisp programs
-and ordinary Unix programs can share a screen. Both C and Lisp will be
-available as system programming languages. We will try to support UUCP,
-MIT Chaosnet, and Internet protocols for communication.
-
-GNU is aimed initially at machines in the 68000/16000 class with virtual
-memory, because they are the easiest machines to make it run on. The extra
-effort to make it run on smaller machines will be left to someone who wants
-to use it on them.
-
-To avoid horrible confusion, please pronounce the `G' in the word `GNU'
-when it is the name of this project.
-
-@unnumberedsec Why I Must Write GNU
-
-I consider that the golden rule requires that if I like a program I must
-share it with other people who like it. Software sellers want to divide
-the users and conquer them, making each user agree not to share with
-others. I refuse to break solidarity with other users in this way. I
-cannot in good conscience sign a nondisclosure agreement or a software
-license agreement. For years I worked within the Artificial Intelligence
-Lab to resist such tendencies and other inhospitalities, but eventually
-they had gone too far: I could not remain in an institution where such
-things are done for me against my will.
-
-So that I can continue to use computers without dishonor, I have decided to
-put together a sufficient body of free software so that I will be able to
-get along without any software that is not free. I have resigned from the
-AI lab to deny MIT any legal excuse to prevent me from giving GNU away.
-
-@unnumberedsec Why GNU Will Be Compatible with Unix
-
-Unix is not my ideal system, but it is not too bad. The essential features
-of Unix seem to be good ones, and I think I can fill in what Unix lacks
-without spoiling them. And a system compatible with Unix would be
-convenient for many other people to adopt.
-
-@unnumberedsec How GNU Will Be Available
-
-GNU is not in the public domain. Everyone will be permitted to modify and
-redistribute GNU, but no distributor will be allowed to restrict its
-further redistribution. That is to say, proprietary modifications will not
-be allowed. I want to make sure that all versions of GNU remain free.
-
-@unnumberedsec Why Many Other Programmers Want to Help
-
-I have found many other programmers who are excited about GNU and want to
-help.
-
-Many programmers are unhappy about the commercialization of system
-software. It may enable them to make more money, but it requires them to
-feel in conflict with other programmers in general rather than feel as
-comrades. The fundamental act of friendship among programmers is the
-sharing of programs; marketing arrangements now typically used essentially
-forbid programmers to treat others as friends. The purchaser of software
-must choose between friendship and obeying the law. Naturally, many decide
-that friendship is more important. But those who believe in law often do
-not feel at ease with either choice. They become cynical and think that
-programming is just a way of making money.
-
-By working on and using GNU rather than proprietary programs, we can be
-hospitable to everyone and obey the law. In addition, GNU serves as an
-example to inspire and a banner to rally others to join us in sharing.
-This can give us a feeling of harmony which is impossible if we use
-software that is not free. For about half the programmers I talk to, this
-is an important happiness that money cannot replace.
-
-@unnumberedsec How You Can Contribute
-
-I am asking computer manufacturers for donations of machines and money.
-I'm asking individuals for donations of programs and work.
-
-One consequence you can expect if you donate machines is that GNU will run
-on them at an early date. The machines should be complete, ready to use
-systems, approved for use in a residential area, and not in need of
-sophisticated cooling or power.
-
-I have found very many programmers eager to contribute part-time work for
-GNU. For most projects, such part-time distributed work would be very hard
-to coordinate; the independently-written parts would not work together.
-But for the particular task of replacing Unix, this problem is absent. A
-complete Unix system contains hundreds of utility programs, each of which
-is documented separately. Most interface specifications are fixed by Unix
-compatibility. If each contributor can write a compatible replacement for
-a single Unix utility, and make it work properly in place of the original
-on a Unix system, then these utilities will work right when put together.
-Even allowing for Murphy to create a few unexpected problems, assembling
-these components will be a feasible task. (The kernel will require closer
-communication and will be worked on by a small, tight group.)
-
-If I get donations of money, I may be able to hire a few people full or
-part time. The salary won't be high by programmers' standards, but I'm
-looking for people for whom building community spirit is as important as
-making money. I view this as a way of enabling dedicated people to devote
-their full energies to working on GNU by sparing them the need to make a
-living in another way.
-
-@unnumberedsec Why All Computer Users Will Benefit
-
-Once GNU is written, everyone will be able to obtain good system
-software free, just like air.@footnote{This is another place I failed to
-distinguish carefully between the two different meanings of ``free.''
-The statement as it stands is not false---you can get copies of GNU
-software at no charge, from your friends or over the net. But it does
-suggest the wrong idea.}
-
-This means much more than just saving everyone the price of a Unix license.
-It means that much wasteful duplication of system programming effort will
-be avoided. This effort can go instead into advancing the state of the
-art.
-
-Complete system sources will be available to everyone. As a result, a user
-who needs changes in the system will always be free to make them himself,
-or hire any available programmer or company to make them for him. Users
-will no longer be at the mercy of one programmer or company which owns the
-sources and is in sole position to make changes.
-
-Schools will be able to provide a much more educational environment by
-encouraging all students to study and improve the system code. Harvard's
-computer lab used to have the policy that no program could be installed on
-the system if its sources were not on public display, and upheld it by
-actually refusing to install certain programs. I was very much inspired by
-this.
-
-Finally, the overhead of considering who owns the system software and what
-one is or is not entitled to do with it will be lifted.
-
-Arrangements to make people pay for using a program, including licensing of
-copies, always incur a tremendous cost to society through the cumbersome
-mechanisms necessary to figure out how much (that is, which programs) a
-person must pay for. And only a police state can force everyone to obey
-them. Consider a space station where air must be manufactured at great
-cost: charging each breather per liter of air may be fair, but wearing the
-metered gas mask all day and all night is intolerable even if everyone can
-afford to pay the air bill. And the TV cameras everywhere to see if you
-ever take the mask off are outrageous. It's better to support the air
-plant with a head tax and chuck the masks.
-
-Copying all or parts of a program is as natural to a programmer as
-breathing, and as productive. It ought to be as free.
-
-@unnumberedsec Some Easily Rebutted Objections to GNU's Goals
-
-@quotation
-``Nobody will use it if it is free, because that means they can't rely
-on any support.''
-
-``You have to charge for the program to pay for providing the
-support.''
-@end quotation
-
-If people would rather pay for GNU plus service than get GNU free without
-service, a company to provide just service to people who have obtained GNU
-free ought to be profitable.@footnote{Several such companies now exist.}
-
-We must distinguish between support in the form of real programming work
-and mere handholding. The former is something one cannot rely on from a
-software vendor. If your problem is not shared by enough people, the
-vendor will tell you to get lost.
-
-If your business needs to be able to rely on support, the only way is to
-have all the necessary sources and tools. Then you can hire any available
-person to fix your problem; you are not at the mercy of any individual.
-With Unix, the price of sources puts this out of consideration for most
-businesses. With GNU this will be easy. It is still possible for there to
-be no available competent person, but this problem cannot be blamed on
-distribution arrangements. GNU does not eliminate all the world's problems,
-only some of them.
-
-Meanwhile, the users who know nothing about computers need handholding:
-doing things for them which they could easily do themselves but don't know
-how.
-
-Such services could be provided by companies that sell just hand-holding
-and repair service. If it is true that users would rather spend money and
-get a product with service, they will also be willing to buy the service
-having got the product free. The service companies will compete in quality
-and price; users will not be tied to any particular one. Meanwhile, those
-of us who don't need the service should be able to use the program without
-paying for the service.
-
-@quotation
-``You cannot reach many people without advertising,
-and you must charge for the program to support that.''
-
-``It's no use advertising a program people can get free.''
-@end quotation
-
-There are various forms of free or very cheap publicity that can be used to
-inform numbers of computer users about something like GNU. But it may be
-true that one can reach more microcomputer users with advertising. If this
-is really so, a business which advertises the service of copying and
-mailing GNU for a fee ought to be successful enough to pay for its
-advertising and more. This way, only the users who benefit from the
-advertising pay for it.
-
-On the other hand, if many people get GNU from their friends, and such
-companies don't succeed, this will show that advertising was not really
-necessary to spread GNU. Why is it that free market advocates don't
-want to let the free market decide this?@footnote{The Free Software
-Foundation raises most of its funds from a distribution service,
-although it is a charity rather than a company. If @emph{no one}
-chooses to obtain copies by ordering from the FSF, it will be unable
-to do its work. But this does not mean that proprietary restrictions
-are justified to force every user to pay. If a small fraction of all
-the users order copies from the FSF, that is sufficient to keep the FSF
-afloat. So we ask users to choose to support us in this way. Have you
-done your part?}
-
-@quotation
-``My company needs a proprietary operating system
-to get a competitive edge.''
-@end quotation
-
-GNU will remove operating system software from the realm of competition.
-You will not be able to get an edge in this area, but neither will your
-competitors be able to get an edge over you. You and they will compete in
-other areas, while benefiting mutually in this one. If your business is
-selling an operating system, you will not like GNU, but that's tough on
-you. If your business is something else, GNU can save you from being
-pushed into the expensive business of selling operating systems.
-
-I would like to see GNU development supported by gifts from many
-manufacturers and users, reducing the cost to each.@footnote{A group of
-computer companies recently pooled funds to support maintenance of the
-GNU C Compiler.}
-
-@quotation
-``Don't programmers deserve a reward for their creativity?''
-@end quotation
-
-If anything deserves a reward, it is social contribution. Creativity can
-be a social contribution, but only in so far as society is free to use the
-results. If programmers deserve to be rewarded for creating innovative
-programs, by the same token they deserve to be punished if they restrict
-the use of these programs.
-
-@quotation
-``Shouldn't a programmer be able to ask for a reward for his creativity?''
-@end quotation
-
-There is nothing wrong with wanting pay for work, or seeking to maximize
-one's income, as long as one does not use means that are destructive. But
-the means customary in the field of software today are based on
-destruction.
-
-Extracting money from users of a program by restricting their use of it is
-destructive because the restrictions reduce the amount and the ways that
-the program can be used. This reduces the amount of wealth that humanity
-derives from the program. When there is a deliberate choice to restrict,
-the harmful consequences are deliberate destruction.
-
-The reason a good citizen does not use such destructive means to become
-wealthier is that, if everyone did so, we would all become poorer from the
-mutual destructiveness. This is Kantian ethics; or, the Golden Rule.
-Since I do not like the consequences that result if everyone hoards
-information, I am required to consider it wrong for one to do so.
-Specifically, the desire to be rewarded for one's creativity does not
-justify depriving the world in general of all or part of that creativity.
-
-@quotation
-``Won't programmers starve?''
-@end quotation
-
-I could answer that nobody is forced to be a programmer. Most of us cannot
-manage to get any money for standing on the street and making faces. But
-we are not, as a result, condemned to spend our lives standing on the
-street making faces, and starving. We do something else.
-
-But that is the wrong answer because it accepts the questioner's implicit
-assumption: that without ownership of software, programmers cannot possibly
-be paid a cent. Supposedly it is all or nothing.
-
-The real reason programmers will not starve is that it will still be
-possible for them to get paid for programming; just not paid as much as
-now.
-
-Restricting copying is not the only basis for business in software. It is
-the most common basis because it brings in the most money. If it were
-prohibited, or rejected by the customer, software business would move to
-other bases of organization which are now used less often. There are
-always numerous ways to organize any kind of business.
-
-Probably programming will not be as lucrative on the new basis as it is
-now. But that is not an argument against the change. It is not considered
-an injustice that sales clerks make the salaries that they now do. If
-programmers made the same, that would not be an injustice either. (In
-practice they would still make considerably more than that.)
-
-@quotation
-``Don't people have a right to control how their creativity is used?''
-@end quotation
-
-``Control over the use of one's ideas'' really constitutes control over
-other people's lives; and it is usually used to make their lives more
-difficult.
-
-People who have studied the issue of intellectual property
-rights@footnote{In the 80s I had not yet realized how confusing it was
-to speak of ``the issue'' of ``intellectual property.'' That term is
-obviously biased; more subtle is the fact that it lumps together
-various disparate laws which raise very different issues. Nowadays I
-urge people to reject the term ``intellectual property'' entirely,
-lest it lead others to suppose that those laws form one coherent
-issue. The way to be clear is to discuss patents, copyrights, and
-trademarks separately. See
-@uref{http://www.gnu.org/philosophy/not-ipr.xhtml} for more
-explanation of how this term spreads confusion and bias.} carefully
-(such as lawyers) say that there is no intrinsic right to intellectual
-property. The kinds of supposed intellectual property rights that the
-government recognizes were created by specific acts of legislation for
-specific purposes.
-
-For example, the patent system was established to encourage inventors to
-disclose the details of their inventions. Its purpose was to help society
-rather than to help inventors. At the time, the life span of 17 years for
-a patent was short compared with the rate of advance of the state of the
-art. Since patents are an issue only among manufacturers, for whom the
-cost and effort of a license agreement are small compared with setting up
-production, the patents often do not do much harm. They do not obstruct
-most individuals who use patented products.
-
-The idea of copyright did not exist in ancient times, when authors
-frequently copied other authors at length in works of non-fiction. This
-practice was useful, and is the only way many authors' works have survived
-even in part. The copyright system was created expressly for the purpose
-of encouraging authorship. In the domain for which it was
-invented---books, which could be copied economically only on a printing
-press---it did little harm, and did not obstruct most of the individuals
-who read the books.
-
-All intellectual property rights are just licenses granted by society
-because it was thought, rightly or wrongly, that society as a whole would
-benefit by granting them. But in any particular situation, we have to ask:
-are we really better off granting such license? What kind of act are we
-licensing a person to do?
-
-The case of programs today is very different from that of books a hundred
-years ago. The fact that the easiest way to copy a program is from one
-neighbor to another, the fact that a program has both source code and
-object code which are distinct, and the fact that a program is used rather
-than read and enjoyed, combine to create a situation in which a person who
-enforces a copyright is harming society as a whole both materially and
-spiritually; in which a person should not do so regardless of whether the
-law enables him to.
-
-@quotation
-``Competition makes things get done better.''
-@end quotation
-
-The paradigm of competition is a race: by rewarding the winner, we
-encourage everyone to run faster. When capitalism really works this way,
-it does a good job; but its defenders are wrong in assuming it always works
-this way. If the runners forget why the reward is offered and become
-intent on winning, no matter how, they may find other strategies---such as,
-attacking other runners. If the runners get into a fist fight, they will
-all finish late.
-
-Proprietary and secret software is the moral equivalent of runners in a
-fist fight. Sad to say, the only referee we've got does not seem to
-object to fights; he just regulates them (``For every ten yards you run,
-you can fire one shot''). He really ought to break them up, and penalize
-runners for even trying to fight.
-
-@quotation
-``Won't everyone stop programming without a monetary incentive?''
-@end quotation
-
-Actually, many people will program with absolutely no monetary incentive.
-Programming has an irresistible fascination for some people, usually the
-people who are best at it. There is no shortage of professional musicians
-who keep at it even though they have no hope of making a living that way.
-
-But really this question, though commonly asked, is not appropriate to the
-situation. Pay for programmers will not disappear, only become less. So
-the right question is, will anyone program with a reduced monetary
-incentive? My experience shows that they will.
-
-For more than ten years, many of the world's best programmers worked at the
-Artificial Intelligence Lab for far less money than they could have had
-anywhere else. They got many kinds of non-monetary rewards: fame and
-appreciation, for example. And creativity is also fun, a reward in itself.
-
-Then most of them left when offered a chance to do the same interesting
-work for a lot of money.
-
-What the facts show is that people will program for reasons other than
-riches; but if given a chance to make a lot of money as well, they will
-come to expect and demand it. Low-paying organizations do poorly in
-competition with high-paying ones, but they do not have to do badly if the
-high-paying ones are banned.
-
-@quotation
-``We need the programmers desperately. If they demand that we
-stop helping our neighbors, we have to obey.''
-@end quotation
-
-You're never so desperate that you have to obey this sort of demand.
-Remember: millions for defense, but not a cent for tribute!
-
-@quotation
-``Programmers need to make a living somehow.''
-@end quotation
-
-In the short run, this is true. However, there are plenty of ways that
-programmers could make a living without selling the right to use a program.
-This way is customary now because it brings programmers and businessmen the
-most money, not because it is the only way to make a living. It is easy to
-find other ways if you want to find them. Here are a number of examples.
-
-A manufacturer introducing a new computer will pay for the porting of
-operating systems onto the new hardware.
-
-The sale of teaching, hand-holding and maintenance services could also
-employ programmers.
-
-People with new ideas could distribute programs as
-freeware@footnote{Subsequently we have discovered the need to
-distinguish between ``free software'' and ``freeware''. The term
-``freeware'' means software you are free to redistribute, but usually
-you are not free to study and change the source code, so most of it is
-not free software. See
-@uref{http://www.gnu.org/philosophy/words-to-avoid.html} for more
-explanation.}, asking for donations from satisfied users, or selling
-hand-holding services. I have met people who are already working this
-way successfully.
-
-Users with related needs can form users' groups, and pay dues. A group
-would contract with programming companies to write programs that the
-group's members would like to use.
-
-All sorts of development can be funded with a Software Tax:
-
-@quotation
-Suppose everyone who buys a computer has to pay x percent of
-the price as a software tax. The government gives this to
-an agency like the NSF to spend on software development.
-
-But if the computer buyer makes a donation to software development
-himself, he can take a credit against the tax. He can donate to
-the project of his own choosing---often, chosen because he hopes to
-use the results when it is done. He can take a credit for any amount
-of donation up to the total tax he had to pay.
-
-The total tax rate could be decided by a vote of the payers of
-the tax, weighted according to the amount they will be taxed on.
-
-The consequences:
-
-@itemize @bullet
-@item
-The computer-using community supports software development.
-@item
-This community decides what level of support is needed.
-@item
-Users who care which projects their share is spent on
-can choose this for themselves.
-@end itemize
-@end quotation
-
-In the long run, making programs free is a step toward the post-scarcity
-world, where nobody will have to work very hard just to make a living.
-People will be free to devote themselves to activities that are fun, such
-as programming, after spending the necessary ten hours a week on required
-tasks such as legislation, family counseling, robot repair and asteroid
-prospecting. There will be no need to be able to make a living from
-programming.
-
-We have already greatly reduced the amount of work that the whole society
-must do for its actual productivity, but only a little of this has
-translated itself into leisure for workers because much nonproductive
-activity is required to accompany productive activity. The main causes of
-this are bureaucracy and isometric struggles against competition. Free
-software will greatly reduce these drains in the area of software
-production. We must do this, in order for technical gains in productivity
-to translate into less work for us.
-
-@ignore
- arch-tag: 21eb38f8-6fa0-480a-91cd-f3dab7148542
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Help, Mark, M-x, Top
-@chapter Help
-@kindex Help
-@cindex help
-@cindex self-documentation
-@findex help-command
-@kindex C-h
-@kindex F1
-
- Emacs provides extensive help features, all accessible through the
-@dfn{help character}, @kbd{C-h}. This is a prefix key that is used
-for commands that display documentation; the next character you type
-should be a @dfn{help options}, to ask for a particular kind of help.
-You can cancel the @kbd{C-h} command with @kbd{C-g}. The function key
-@key{F1} is equivalent to @kbd{C-h}.
-
-@kindex C-h C-h
-@findex help-for-help
- @kbd{C-h} itself is one of the help options; @kbd{C-h C-h} displays
-a list of help options, with a brief description of each one
-(@code{help-for-help}). You can scroll the list with @key{SPC} and
-@key{DEL}, then type the help option you want. To cancel, type
-@kbd{C-g}.
-
- @kbd{C-h} or @key{F1} means ``help'' in various other contexts as
-well. For instance, you can type them after a prefix key to display
-list of the keys that can follow the prefix key. (A few prefix keys
-don't support @kbd{C-h} in this way, because they define other
-meanings for it, but they all support @key{F1} for help.)
-
- Most help buffers use a special major mode, Help mode, which lets
-you scroll conveniently with @key{SPC} and @key{DEL}. You can also
-follow hyperlinks to URLs, and to other facilities including Info
-nodes and customization buffers. @xref{Help Mode}.
-
-@cindex searching documentation efficiently
-@cindex looking for a subject in documentation
- If you are looking for a certain feature, but don't know what it is
-called or where to look, we recommend three methods. First, try an
-apropos command, then try searching the manual index, then look in the
-FAQ and the package keywords.
-
-@table @kbd
-@item C-h a @var{topics} @key{RET}
-This searches for commands whose names match the argument
-@var{topics}. The argument can be a keyword, a list of keywords, or a
-regular expression (@pxref{Regexps}). This command displays all the
-matches in a new buffer. @xref{Apropos}.
-
-@item C-h i d m emacs @key{RET} i @var{topic} @key{RET}
-This searches for @var{topic} in the indices of the on-line Emacs
-manual, and displays the first match found. Press @kbd{,} to see
-subsequent matches. You can use a regular expression as @var{topic}.
-
-@item C-h i d m emacs @key{RET} s @var{topic} @key{RET}
-Similar, but searches the @emph{text} of the manual rather than the
-indices.
-
-@item C-h C-f
-This displays the Emacs FAQ. You can use the Info commands
-to browse it.
-
-@item C-h p
-This displays the available Emacs packages based on keywords.
-@xref{Library Keywords}.
-@end table
-
-@menu
-* Help Summary:: Brief list of all Help commands.
-* Key Help:: Asking what a key does in Emacs.
-* Name Help:: Asking about a command, variable or function name.
-* Apropos:: Asking what pertains to a given topic.
-* Help Mode:: Special features of Help mode and Help buffers.
-* Library Keywords:: Finding Lisp libraries by keywords (topics).
-* Language Help:: Help relating to international language support.
-* Misc Help:: Other help commands.
-* Help Files:: Commands to display pre-written help files.
-* Help Echo:: Help on active text and tooltips (`balloon help')
-@end menu
-
-@iftex
-@node Help Summary
-@end iftex
-@ifnottex
-@node Help Summary
-@section Help Summary
-@end ifnottex
-
- Here is a summary of the Emacs interactive help commands. (The
-character that follows @kbd{C-h} is the ``help option.'') @xref{Help
-Files}, for other help commands that display fixed files of
-information.
-
-@table @kbd
-@item C-h a @var{topics} @key{RET}
-Display a list of commands whose names match @var{topics}
-(@code{apropos-command}; @pxref{Apropos}).
-@item C-h b
-Display all active key bindings; minor mode bindings first, then those
-of the major mode, then global bindings (@code{describe-bindings}).
-@item C-h c @var{key}
-Given a key sequence @var{key}, show the name of the command that it
-runs (@code{describe-key-briefly}). Here @kbd{c} stands for
-``character.'' For more extensive information on @var{key}, use
-@kbd{C-h k}.
-@item C-h d @var{topics} @key{RET}
-Display the commands and variables whose documentation matches
-@var{topics} (@code{apropos-documentation}).
-@item C-h e
-Display the @code{*Messages*} buffer
-(@code{view-echo-area-messages}).
-@item C-h f @var{function} @key{RET}
-Display documentation on the Lisp function named @var{function}
-(@code{describe-function}). Since commands are Lisp functions,
-this works for commands too.
-@item C-h h
-Display the @file{HELLO} file, which shows examples of various character
-sets.
-@item C-h i
-Run Info, the GNU documentation browser (@code{info}).
-The complete Emacs manual is available on-line in Info.
-@item C-h k @var{key}
-Display the name and documentation of the command that @var{key} runs
-(@code{describe-key}).
-@item C-h l
-Display a description of the last 100 characters you typed
-(@code{view-lossage}).
-@item C-h m
-Display documentation of the current major mode (@code{describe-mode}).
-@item C-h p
-Find packages by topic keyword (@code{finder-by-keyword}).
-@item C-h s
-Display the current contents of the syntax table, with an explanation of
-what they mean (@code{describe-syntax}). @xref{Syntax}.
-@item C-h t
-Enter the Emacs interactive tutorial (@code{help-with-tutorial}).
-@item C-h v @var{var} @key{RET}
-Display the documentation of the Lisp variable @var{var}
-(@code{describe-variable}).
-@item C-h w @var{command} @key{RET}
-Show which keys run the command named @var{command} (@code{where-is}).
-@item C-h C @var{coding} @key{RET}
-Describe the coding system @var{coding}
-(@code{describe-coding-system}).
-@item C-h C @key{RET}
-Describe the coding systems currently in use.
-@item C-h I @var{method} @key{RET}
-Describe the input method @var{method} (@code{describe-input-method}).
-@item C-h L @var{language-env} @key{RET}
-Display information on the character sets, coding systems, and input
-methods used in language environment @var{language-env}
-(@code{describe-language-environment}).
-@item C-h F @var{function} @key{RET}
-Enter Info and goes to the node that documents the Emacs function
-@var{function} (@code{Info-goto-emacs-command-node}).
-@item C-h K @var{key}
-Enter Info and goes to the node that documents the key sequence
-@var{key} (@code{Info-goto-emacs-key-command-node}).
-@item C-h S @var{symbol} @key{RET}
-Display the Info documentation on symbol @var{symbol} according to the
-programming language you are editing (@code{info-lookup-symbol}).
-@item C-h .
-Display the help message for a special text area, if point is in one
-(@code{display-local-help}). (These include, for example, links in
-@samp{*Help*} buffers.)
-@end table
-
-@node Key Help
-@section Documentation for a Key
-
-@kindex C-h c
-@findex describe-key-briefly
- The help commands to get information about a key sequence are
-@kbd{C-h c} and @w{@kbd{C-h k}}. @kbd{C-h c @var{key}} displays in
-the echo area the name of the command that @var{key} is bound to. For
-example, @kbd{C-h c C-f} displays @samp{forward-char}. Since command
-names are chosen to describe what the commands do, this gives you a
-very brief description of what @var{key} does.
-
-@kindex C-h k
-@findex describe-key
- @kbd{C-h k @var{key}} is similar but gives more information: it
-displays the documentation string of the command as well as its name.
-It displays this information in a window, since it may not fit in the
-echo area.
-
-@kindex C-h K
-@findex Info-goto-emacs-key-command-node
- To find the documentation of a key sequence @var{key}, type @kbd{C-h
-K @var{key}}. This displays the appropriate manual section which
-contains the documentation of @var{key}.
-
- @kbd{C-h c}, @kbd{C-h k} and @kbd{C-h K} work for any sort of key
-sequences, including function keys, menus, and mouse events. For
-instance, after @kbd{C-h k} you can select a menu item from the menu
-bar, to view the documentation string of the command it runs.
-
-@kindex C-h w
-@findex where-is
- @kbd{C-h w @var{command} @key{RET}} lists the keys that are bound to
-@var{command}. It displays the list in the echo area. If it says the
-command is not on any key, that means you must use @kbd{M-x} to run
-it. @kbd{C-h w} runs the command @code{where-is}.
-
-@node Name Help
-@section Help by Command or Variable Name
-
-@kindex C-h f
-@findex describe-function
- @kbd{C-h f @var{function} @key{RET}} (@code{describe-function})
-displays the documentation of Lisp function @var{function}, in a
-window. Since commands are Lisp functions, you can use this method to
-view the documentation of any command whose name you know. For
-example,
-
-@example
-C-h f auto-fill-mode @key{RET}
-@end example
-
-@noindent
-displays the documentation of @code{auto-fill-mode}. This is the only
-way to get the documentation of a command that is not bound to any key
-(one which you would normally run using @kbd{M-x}).
-
- @kbd{C-h f} is also useful for Lisp functions that you use in a Lisp
-program. For example, if you have just written the expression
-@code{(make-vector len)} and want to check that you are using
-@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}.
-Because @kbd{C-h f} allows all function names, not just command names,
-you may find that some of your favorite completion abbreviations that
-work in @kbd{M-x} don't work in @kbd{C-h f}. An abbreviation that is
-unique among command names may not be unique among all function names.
-
- If you type @kbd{C-h f @key{RET}}, it describes the function called
-by the innermost Lisp expression in the buffer around point,
-@emph{provided} that function name is a valid, defined Lisp function.
-(That name appears as the default while you enter the argument.) For
-example, if point is located following the text @samp{(make-vector
-(car x)}, the innermost list containing point is the one that starts
-with @samp{(make-vector}, so @kbd{C-h f @key{RET}} will describe the
-function @code{make-vector}.
-
- @kbd{C-h f} is also useful just to verify that you spelled a
-function name correctly. If the minibuffer prompt for @kbd{C-h f}
-shows the function name from the buffer as the default, it means that
-name is defined as a Lisp function. Type @kbd{C-g} to cancel the
-@kbd{C-h f} command if you don't really want to view the
-documentation.
-
-@kindex C-h v
-@findex describe-variable
- @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but
-describes Lisp variables instead of Lisp functions. Its default is
-the Lisp symbol around or before point, if that is the name of a
-defined Lisp variable. @xref{Variables}.
-
- Help buffers that describe Emacs variables and functions normally
-have hyperlinks to the corresponding source definition, if you have
-the source files installed. (@xref{Hyperlinking}.) If you know Lisp
-(or C), this provides the ultimate documentation. If you don't know
-Lisp, you should learn it. (The Introduction to Emacs Lisp
-Programming, available from the FSF through fsf.org, is a good way to
-get started.) If Emacs feels you are just @emph{using} it, treating
-it as an object program, its feelings may be hurt. For real intimacy,
-read the Emacs source code.
-
-@kindex C-h F
-@findex Info-goto-emacs-command-node
- To find a function's documentation in a manual, use @kbd{C-h F}
-(@code{Info-goto-emacs-command-node}). This knows about various
-manuals, not just the Emacs manual, and finds the right one.
-
-@node Apropos
-@section Apropos
-
- The @dfn{apropos} commands answer questions like, ``What are the
-commands for working with files?'' More precisely, you specify an
-@dfn{apropos pattern}, which means either a word, a list of words, or
-a regular expression. Each apropos command displays a list of items
-that match the pattern, in a separate buffer.
-
-@table @kbd
-@item C-h a @var{pattern} @key{RET}
-Search for commands whose names match @var{pattern}.
-
-@item M-x apropos @key{RET} @var{pattern} @key{RET}
-Search for functions and variables whose names match @var{pattern}.
-Both interactive functions (commands) and noninteractive functions can
-be found by this command.
-
-@item M-x apropos-variable @key{RET} @var{pattern} @key{RET}
-Search for user-option variables whose names match @var{pattern}.
-
-@item M-x apropos-value @key{RET} @var{pattern} @key{RET}
-Search for functions whose definitions @var{pattern}, and variables
-whose values match @var{pattern}.
-
-@item C-h d @var{pattern} @key{RET}
-Search for functions and variables whose @strong{documentation
-strings} match @var{pattern}.
-@end table
-
-@kindex C-h a
-@findex apropos-command
-@cindex apropos
- The simplest kind of apropos pattern is one word. Anything which
-contains that word matches the pattern. Thus, to find the commands
-that work on files, type @kbd{C-h a file @key{RET}}. This displays a
-list of all command names that contain @samp{file}, including
-@code{copy-file}, @code{find-file}, and so on. Each command name
-comes with a brief description and a list of keys you can currently
-invoke it with. In our example, it would say that you can invoke
-@code{find-file} by typing @kbd{C-x C-f}.
-
- The @kbd{a} in @kbd{C-h a} stands for ``Apropos''; @kbd{C-h a}
-runs the command @code{apropos-command}. This command normally checks
-only commands (interactive functions); if you specify a prefix
-argument, it checks noninteractive functions as well.
-
- For more information about a function definition, variable or symbol
-property listed in the apropos buffer, you can click on it with
-@kbd{Mouse-1} or @kbd{Mouse-2}, or move there and type @key{RET}.
-
- When you specify more than one word in the apropos pattern, a name
-must contain at least two of the words in order to match. Thus, if
-you are looking for commands to kill a chunk of text before point, you
-could try @kbd{C-h a kill back backward behind before @key{RET}}. The
-real command name @code{kill-backward} will match that; if there were
-a command @code{kill-text-before}, it would also match, since it
-contains two of the specified words.
-
- For even greater flexibility, you can specify a regular expression
-(@pxref{Regexps}). An apropos pattern is interpreted as a regular
-expression if it contains any of the regular expression special
-characters, @samp{^$*+?.\[}.
-
- Following the conventions for naming Emacs commands, here are some
-words that you'll find useful in apropos patterns. By using them in
-@kbd{C-h a}, you will also get a feel for the naming conventions.
-
-@quotation
-char, line, word, sentence, paragraph, region, page, sexp, list, defun,
-rect, buffer, frame, window, face, file, dir, register, mode, beginning, end,
-forward, backward, next, previous, up, down, search, goto, kill, delete,
-mark, insert, yank, fill, indent, case, change, set, what, list, find,
-view, describe, default.
-@end quotation
-
-@findex apropos
- Use @kbd{M-x apropos} instead of @kbd{C-h a} to list all the Lisp
-symbols that match an apropos pattern, not just the symbols that are
-commands. This command does not list key bindings by default; specify
-a numeric argument if you want it to list them.
-
-@findex apropos-variable
- Use @kbd{M-x apropos-variable} to list user-customizable variables
-that match an apropos pattern. If you specify a prefix argument, it
-lists all matching variables.
-
-@kindex C-h d
-@findex apropos-documentation
- The @code{apropos-documentation} command is like @code{apropos}
-except that it searches documentation strings instead of symbol names
-for matches.
-
-@findex apropos-value
- The @code{apropos-value} command is like @code{apropos} except that
-it searches variables' values for matches for the apropos pattern.
-With a prefix argument, it also checks symbols' function definitions
-and property lists.
-
-@vindex apropos-do-all
- If the variable @code{apropos-do-all} is non-@code{nil}, the apropos
-commands always behave as if they had been given a prefix argument.
-
-@vindex apropos-sort-by-scores
-@cindex apropos search results, order by score
- By default, apropos lists the search results in alphabetical order.
-If the variable @code{apropos-sort-by-scores} is non-@code{nil}, the
-apropos commands try to guess the relevance of each result, and
-display the most relevant ones first.
-
-@vindex apropos-documentation-sort-by-scores
- By default, apropos lists the search results for
-@code{apropos-documentation} in order of relevance of the match. If
-the variable @code{apropos-documentation-sort-by-scores} is
-@code{nil}, apropos lists the symbols found in alphabetical order.
-
-@node Help Mode
-@section Help Mode Commands
-
- Help buffers provide the same commands as View mode (@pxref{Misc File
-Ops}), plus a few special commands of their own.
-
-@table @kbd
-@item @key{SPC}
-Scroll forward.
-@item @key{DEL}
-Scroll backward.
-@item @key{RET}
-Follow a cross reference at point.
-@item @key{TAB}
-Move point forward to the next cross reference.
-@item S-@key{TAB}
-Move point back to the previous cross reference.
-@item Mouse-1
-@itemx Mouse-2
-Follow a cross reference that you click on.
-@item C-c C-c
-Show all documentation about the symbol at point.
-@end table
-
- When a function name (@pxref{M-x,, Running Commands by Name}),
-variable name (@pxref{Variables}), or face name (@pxref{Faces})
-appears in the documentation, it normally appears inside paired
-single-quotes. To view the documentation of that command, variable or
-face, you can click on the name with @kbd{Mouse-1} or @kbd{Mouse-2},
-or move point there and type @key{RET}. Use @kbd{C-c C-b} to retrace
-your steps.
-
-@cindex URL, viewing in help
-@cindex help, viewing web pages
-@cindex viewing web pages in help
-@cindex web pages, viewing in help
-@findex browse-url
- You can follow cross references to URLs (web pages) also. This uses
-the @code{browse-url} command to view the page in the browser you
-choose. @xref{Browse-URL}.
-
-@kindex @key{TAB} @r{(Help mode)}
-@findex help-next-ref
-@kindex S-@key{TAB} @r{(Help mode)}
-@findex help-previous-ref
- There are convenient commands to move point to cross references in
-the help text. @key{TAB} (@code{help-next-ref}) moves point down to
-the next cross reference. @kbd{S-@key{TAB}} moves up to the previous
-cross reference (@code{help-previous-ref}).
-
- To view all documentation about any symbol name that appears in the
-text, move point to the symbol name and type @kbd{C-c C-c}
-(@code{help-follow-symbol}). This shows all available documentation
-about the symbol as a variable, function and/or face. As above, use
-@kbd{C-c C-b} to retrace your steps.
-
-@node Library Keywords
-@section Keyword Search for Lisp Libraries
-
-@kindex C-h p
-@findex finder-by-keyword
-The @kbd{C-h p} command lets you search the standard Emacs Lisp
-libraries by topic keywords. Here is a partial list of keywords you can
-use:
-
-@multitable {convenience} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
-@item abbrev@tab abbreviation handling, typing shortcuts, macros.
-@item bib@tab code related to the @code{bib} bibliography processor.
-@item c@tab support for the C language and related languages.
-@item calendar@tab calendar and time management support.
-@item comm@tab communications, networking, remote access to files.
-@item convenience@tab convenience features for faster editing.
-@item data@tab support for editing files of data.
-@item docs@tab support for Emacs documentation.
-@item emulations@tab emulations of other editors.
-@item extensions@tab Emacs Lisp language extensions.
-@item faces@tab support for multiple fonts.
-@item files@tab support for editing and manipulating files.
-@item frames@tab support for Emacs frames and window systems.
-@item games@tab games, jokes and amusements.
-@item hardware@tab support for interfacing with exotic hardware.
-@item help@tab support for on-line help systems.
-@item hypermedia@tab support for links between text or other media types.
-@item i18n@tab internationalization and alternate character-set support.
-@item internal@tab code for Emacs internals, build process, defaults.
-@item languages@tab specialized modes for editing programming languages.
-@item lisp@tab Lisp support, including Emacs Lisp.
-@item local@tab code local to your site.
-@item maint@tab maintenance aids for the Emacs development group.
-@item mail@tab modes for electronic-mail handling.
-@item matching@tab various sorts of searching and matching.
-@item mouse@tab mouse support.
-@item multimedia@tab images and sound support.
-@item news@tab support for netnews reading and posting.
-@item oop@tab support for object-oriented programming.
-@item outlines@tab support for hierarchical outlining.
-@item processes@tab process, subshell, compilation, and job control support.
-@item terminals@tab support for terminal types.
-@item tex@tab supporting code for the @TeX{} formatter.
-@item tools@tab programming tools.
-@item unix@tab front-ends/assistants for, or emulators of, UNIX-like features.
-@item wp@tab word processing.
-@end multitable
-
-@node Language Help
-@section Help for International Language Support
-
- You can use the command @kbd{C-h L}
-(@code{describe-language-environment}) to get information about a
-specific language environment. @xref{Language Environments}. This
-tells you which languages this language environment supports. It also
-lists the character sets, coding systems, and input methods that work
-with this language environment, and finally shows some sample text to
-illustrate scripts.
-
- The command @kbd{C-h h} (@code{view-hello-file}) displays the file
-@file{etc/HELLO}, which shows how to say ``hello'' in many languages.
-
- The command @kbd{C-h I} (@code{describe-input-method}) describes an
-input method---either a specified input method, or by default the
-input method currently in use. @xref{Input Methods}.
-
- The command @kbd{C-h C} (@code{describe-coding-system}) describes
-coding systems---either a specified coding system, or the ones
-currently in use. @xref{Coding Systems}.
-
-@node Misc Help
-@section Other Help Commands
-
-@kindex C-h i
-@findex info
-@cindex Info
-@cindex manuals, on-line
-@cindex on-line manuals
- @kbd{C-h i} (@code{info}) runs the Info program, which browses
-structured documentation files. The entire Emacs manual is available
-within Info, along with many other manuals for the GNU system. Type
-@kbd{h} after entering Info to run a tutorial on using Info.
-
-@cindex find Info manual by its file name
- With a numeric argument @var{n}, @kbd{C-h i} selects the Info buffer
-@samp{*info*<@var{n}>}. This is useful if you want to browse multiple
-Info manuals simultaneously. If you specify just @kbd{C-u} as the
-prefix argument, @kbd{C-h i} prompts for the name of a documentation
-file, so you can browse a file which doesn't have an entry in the
-top-level Info menu.
-
- The help commands @kbd{C-h F @var{function} @key{RET}} and @kbd{C-h
-K @var{key}}, described above, enter Info and go straight to the
-documentation of @var{function} or @var{key}.
-
-@kindex C-h S
-@findex info-lookup-symbol
- When editing a program, if you have an Info version of the manual
-for the programming language, you can use @kbd{C-h S}
-(@code{info-lookup-symbol}) to find symbol (keyword, function or
-variable) in the proper manual. The details of how this command works
-depend on the major mode.
-
-@kindex C-h l
-@findex view-lossage
- If something surprising happens, and you are not sure what you
-typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} displays
-the last 100 characters you typed in Emacs. If you see commands that
-you don't know, you can use @kbd{C-h c} to find out what they do.
-
-@kindex C-h e
-@findex view-echo-area-messages
- To review recent echo area messages, use @kbd{C-h e}
-(@code{view-echo-area-messages}). This displays the buffer
-@code{*Messages*}, where those messages are kept.
-
-@kindex C-h m
-@findex describe-mode
- Each Emacs major mode typically redefines a few keys and makes other
-changes in how editing works. @kbd{C-h m} (@code{describe-mode})
-displays documentation on the current major mode, which normally
-describes the commands and features that are changed in this mode.
-
-@kindex C-h b
-@findex describe-bindings
- @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
-(@code{describe-syntax}) show other information about the current
-environment within Emacs. @kbd{C-h b} displays a list of all the key
-bindings now in effect: first the local bindings of the current minor
-modes, then the local bindings defined by the current major mode, and
-finally the global bindings (@pxref{Key Bindings}). @kbd{C-h s}
-displays the contents of the syntax table, with explanations of each
-character's syntax (@pxref{Syntax}).
-
- You can get a list of subcommands for a particular prefix key by
-typing @kbd{C-h} after the prefix key. (There are a few prefix keys
-for which this does not work---those that provide their own bindings
-for @kbd{C-h}. One of these is @key{ESC}, because @kbd{@key{ESC} C-h}
-is actually @kbd{C-M-h}, which marks a defun.)
-
-@node Help Files
-@section Help Files
-
- The Emacs help commands described above display dynamic help based
-on the current state within Emacs, or refer to manuals. Other help
-commands display pre-written, static help files. These commands all
-have the form @kbd{C-h C-@var{char}}; that is, @kbd{C-h} followed by a
-control character.
-
-@kindex C-h C-c
-@findex describe-copying
-@kindex C-h C-d
-@findex describe-distribution
-@kindex C-h C-e
-@findex view-emacs-problems
-@kindex C-h C-f
-@findex view-emacs-FAQ
-@kindex C-h C-n
-@findex view-emacs-news
-@kindex C-h C-p
-@findex describe-project
-@kindex C-h C-t
-@findex view-emacs-todo
-@kindex C-h C-w
-@findex describe-no-warranty
-
-@table @kbd
-@item C-h C-c
-Display the Emacs copying conditions (@code{describe-copying}).
-These are the rules under which you can copy and redistribute Emacs.
-@item C-h C-d
-Display how to download or order the latest version of
-Emacs and other GNU software (@code{describe-distribution}).
-@item C-h C-e
-Display the list of known Emacs problems, sometimes with suggested
-workarounds (@code{view-emacs-problems}).
-@item C-h C-f
-Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}).
-@item C-h C-n
-Display the Emacs ``news'' file, which lists new features in the most
-recent version of Emacs (@code{view-emacs-news}).
-@item C-h C-p
-Display general information about the GNU Project
-(@code{describe-project}).
-@item C-h C-t
-Display the Emacs to-do list (@code{view-todo}).
-@item C-h C-w
-Display the full details on the complete absence of warranty for GNU
-Emacs (@code{describe-no-warranty}).
-@end table
-
-@node Help Echo
-@section Help on Active Text and Tooltips
-
-@cindex tooltips
-@cindex balloon help
- When a region of text is ``active,'' so that you can select it with
-the mouse or a key like @kbd{RET}, it often has associated help text.
-For instance, most parts of the mode line have help text. On
-graphical displays, the help text is displayed as a ``tooltip''
-(sometimes known as ``balloon help''), when you move the mouse over
-the active text. @xref{Tooltips}. On some systems, it is shown in
-the echo area. On text-only terminals, if Emacs cannot follow the
-mouse, it cannot show the help text on mouse-over.
-
-@kindex C-h .
-@findex display-local-help
-@vindex help-at-pt-display-when-idle
- You can also access text region help info using the keyboard. The
-command @kbd{C-h .} (@code{display-local-help}) displays any help text
-associated with the text at point, using the echo area. If you want
-help text to be displayed automatically whenever it is available at
-point, set the variable @code{help-at-pt-display-when-idle} to
-@code{t}.
-
-@ignore
- arch-tag: 6f33ab62-bc75-4367-8057-fd67cc15c3a1
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Indentation, Text, Major Modes, Top
-@chapter Indentation
-@cindex indentation
-@cindex columns (indentation)
-
- This chapter describes the Emacs commands that add, remove, or
-adjust indentation.
-
-@table @kbd
-@item @key{TAB}
-Indent the current line ``appropriately'' in a mode-dependent fashion.
-@item @kbd{C-j}
-Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
-@item M-^
-Merge the previous and the current line (@code{delete-indentation}).
-This would cancel the effect of a preceding @kbd{C-j}.
-@item C-M-o
-Split the current line at point; text on the line after point becomes a
-new line indented to the same column where point is located
-(@code{split-line}).
-@item M-m
-Move (forward or back) to the first nonblank character on the current
-line (@code{back-to-indentation}).
-@item C-M-\
-Indent lines in the region to the same column (@code{indent-region}).
-@item C-x @key{TAB}
-Shift lines in the region rigidly right or left (@code{indent-rigidly}).
-@item M-i
-Indent from point to the next prespecified tab stop column
-(@code{tab-to-tab-stop}).
-@item M-x indent-relative
-Indent from point to under an indentation point in the previous line.
-@end table
-
- Emacs supports four general categories of operations that could all
-be called `indentation':
-
-@enumerate
-@item
-Insert a tab character. You can type @kbd{C-q @key{TAB}} to do this.
-
-A tab character is displayed as a stretch of whitespace which extends
-to the next display tab stop position, and the default width of a tab
-stop is eight. @xref{Text Display}, for more details.
-
-@item
-Insert whitespace up to the next tab stop. You can set tab stops at
-your choice of column positions, then type @kbd{M-i} to advance to the
-next tab stop. The default tab stop settings have a tab stop every
-eight columns, which means by default @kbd{M-i} inserts a tab
-character. To set the tab stops, use @kbd{M-x edit-tab-stops}.
-
-@item
-Align a line with the previous line. More precisely, the command
-@kbd{M-x indent-relative} indents the current line under the beginning
-of some word in the previous line. In Fundamental mode and in Text
-mode, @key{TAB} runs the command @code{indent-relative}.
-
-@item
-The most sophisticated method is @dfn{syntax-driven indentation}.
-Most programming languages have an indentation convention. For Lisp
-code, lines are indented according to their nesting in parentheses. C
-code uses the same general idea, but many details are different.
-
-@kindex TAB
-Type @key{TAB} to do syntax-driven indentation, in a mode that
-supports it. It realigns the current line according with the syntax
-of the preceding lines. No matter where in the line you are when you
-type @key{TAB}, it aligns the line as a whole.
-@end enumerate
-
- Normally, most of the above methods insert an optimal mix of tabs and
-spaces to align to the desired column. @xref{Just Spaces}, for how to
-disable use of tabs. However, @kbd{C-q @key{TAB}} always inserts a
-tab, even when tabs are disabled for the indentation commands.
-
-@menu
-* Indentation Commands:: Various commands and techniques for indentation.
-* Tab Stops:: You can set arbitrary "tab stops" and then
- indent to the next tab stop when you want to.
-* Just Spaces:: You can request indentation using just spaces.
-@end menu
-
-@node Indentation Commands, Tab Stops, Indentation, Indentation
-@section Indentation Commands and Techniques
-
-@kindex M-m
-@findex back-to-indentation
- To move over the indentation on a line, do @kbd{M-m}
-(@code{back-to-indentation}). This command, given anywhere on a line,
-positions point at the first nonblank character on the line, if any,
-or else at the end of the line.
-
- To insert an indented line before the current line, do @kbd{C-a C-o
-@key{TAB}}. To make an indented line after the current line, use
-@kbd{C-e C-j}.
-
- If you just want to insert a tab character in the buffer, you can type
-@kbd{C-q @key{TAB}}.
-
-@kindex C-M-o
-@findex split-line
- @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
-the line vertically down, so that the current line becomes two lines.
-@kbd{C-M-o} first moves point forward over any spaces and tabs. Then it
-inserts after point a newline and enough indentation to reach the same
-column point is on. Point remains before the inserted newline; in this
-regard, @kbd{C-M-o} resembles @kbd{C-o}.
-
-@kindex M-^
-@findex delete-indentation
- To join two lines cleanly, use the @kbd{M-^}
-(@code{delete-indentation}) command. It deletes the indentation at
-the front of the current line, and the line boundary as well,
-replacing them with a single space. As a special case (useful for
-Lisp code) the single space is omitted if the characters to be joined
-are consecutive open parentheses or closing parentheses, or if the
-junction follows another newline. To delete just the indentation of a
-line, go to the beginning of the line and use @kbd{M-\}
-(@code{delete-horizontal-space}), which deletes all spaces and tabs
-around the cursor.
-
- If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it
-appears after the newline that is deleted. @xref{Fill Prefix}.
-
-@kindex C-M-\
-@kindex C-x TAB
-@findex indent-region
-@findex indent-rigidly
- There are also commands for changing the indentation of several lines
-at once. They apply to all the lines that begin in the region.
-@kbd{C-M-\} (@code{indent-region}) indents each line in the ``usual''
-way, as if you had typed @key{TAB} at the beginning of the line. A
-numeric argument specifies the column to indent to, and each line is
-shifted left or right so that its first nonblank character appears in
-that column. @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of
-the lines in the region right by its argument (left, for negative
-arguments). The whole group of lines moves rigidly sideways, which is
-how the command gets its name.
-
-@cindex remove indentation
- To remove all indentation from all of the lines in the region,
-invoke @kbd{C-x @key{TAB}} with a large negative argument, such as
--1000.
-
-@findex indent-relative
- @kbd{M-x indent-relative} indents at point based on the previous line
-(actually, the last nonempty line). It inserts whitespace at point, moving
-point, until it is underneath the next indentation point in the previous line.
-An indentation point is the end of a sequence of whitespace or the end of
-the line. If point is farther right than any indentation point in the
-previous line, @code{indent-relative} runs @code{tab-to-tab-stop}
-@ifnottex
-(@pxref{Tab Stops}),
-@end ifnottex
-@iftex
-(see next section),
-@end iftex
-unless it is called with a numeric argument, in which case it does
-nothing.
-
- @xref{Format Indentation}, for another way of specifying the
-indentation for part of your text.
-
-@node Tab Stops, Just Spaces, Indentation Commands, Indentation
-@section Tab Stops
-
-@cindex tab stops
-@cindex using tab stops in making tables
-@cindex tables, indentation for
-@kindex M-i
-@findex tab-to-tab-stop
- For typing in tables, you can use @kbd{M-i} (@code{tab-to-tab-stop}).
-This command inserts indentation before point, enough to reach the
-next tab stop column.
-
-@findex edit-tab-stops
-@findex edit-tab-stops-note-changes
-@kindex C-c C-c @r{(Edit Tab Stops)}
-@vindex tab-stop-list
- You can specify the tab stops used by @kbd{M-i}. They are stored in a
-variable called @code{tab-stop-list}, as a list of column-numbers in
-increasing order.
-
- The convenient way to set the tab stops is with @kbd{M-x
-edit-tab-stops}, which creates and selects a buffer containing a
-description of the tab stop settings. You can edit this buffer to
-specify different tab stops, and then type @kbd{C-c C-c} to make those
-new tab stops take effect. The buffer uses Overwrite mode
-(@pxref{Minor Modes}). @code{edit-tab-stops} records which buffer was
-current when you invoked it, and stores the tab stops back in that
-buffer; normally all buffers share the same tab stops and changing
-them in one buffer affects all, but if you happen to make
-@code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in
-that buffer will edit the local settings.
-
- Here is what the text representing the tab stops looks like for ordinary
-tab stops every eight columns.
-
-@example
- : : : : : :
-0 1 2 3 4
-0123456789012345678901234567890123456789012345678
-To install changes, type C-c C-c
-@end example
-
- The first line contains a colon at each tab stop. The remaining lines
-are present just to help you see where the colons are and know what to do.
-
- Note that the tab stops that control @code{tab-to-tab-stop} have nothing
-to do with displaying tab characters in the buffer. @xref{Text Display},
-for more information on that.
-
-@node Just Spaces,, Tab Stops, Indentation
-@section Tabs vs. Spaces
-
-@vindex indent-tabs-mode
- Emacs normally uses both tabs and spaces to indent lines. If you
-prefer, all indentation can be made from spaces only. To request
-this, set @code{indent-tabs-mode} to @code{nil}. This is a per-buffer
-variable, so altering the variable affects only the current buffer,
-but there is a default value which you can change as well.
-@xref{Locals}.
-
- A tab is not always displayed in the same way. By default, tabs are
-eight columns wide, but some people like to customize their tools to
-use a different tab width. So by using spaces only, you can make sure
-that your file looks the same regardless of the tab width setting.
-
-@findex tabify
-@findex untabify
- There are also commands to convert tabs to spaces or vice versa, always
-preserving the columns of all nonblank text. @kbd{M-x tabify} scans the
-region for sequences of spaces, and converts sequences of at least two
-spaces to tabs if that can be done without changing indentation. @kbd{M-x
-untabify} changes all tabs in the region to appropriate numbers of spaces.
-
-@ignore
- arch-tag: acc07de7-ae11-4ee8-a159-cb59c473f0fb
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-
-@node Killing, Yanking, Mark, Top
-@chapter Killing and Moving Text
-
-@ifnottex
-@raisesections
-@end ifnottex
-
- @dfn{Killing} means erasing text and copying it into the @dfn{kill
-ring}, from which you can bring it back into the buffer by
-@dfn{yanking} it. (Some systems use the terms ``cutting'' and
-``pasting'' for these operations.) This is the most common way of
-moving or copying text within Emacs. Killing and yanking is very safe
-because Emacs remembers several recent kills, not just the last one.
-It is versatile, because the many commands for killing syntactic units
-can also be used for moving those units. But there are other ways of
-copying text for special purposes.
-
-@iftex
-@section Deletion and Killing
-@end iftex
-
-@cindex killing text
-@cindex cutting text
-@cindex deletion
- Most commands which erase text from the buffer save it in the kill
-ring. These commands are known as @dfn{kill} commands. The commands
-that erase text but do not save it in the kill ring are known as
-@dfn{delete} commands. The @kbd{C-x u} (@code{undo}) command
-(@pxref{Undo}) can undo both kill and delete commands; the importance
-of the kill ring is that you can also yank the text in a different
-place or places. Emacs has only one kill ring for all buffers, so you
-can kill text in one buffer and yank it in another buffer.
-
- The delete commands include @kbd{C-d} (@code{delete-char}) and
-@key{DEL} (@code{delete-backward-char}), which delete only one
-character at a time, and those commands that delete only spaces or
-newlines. Commands that can erase significant amounts of nontrivial
-data generally do a kill operation instead. The commands' names and
-individual descriptions use the words @samp{kill} and @samp{delete} to
-say which kind of operation they perform.
-
-@vindex kill-read-only-ok
-@cindex read-only text, killing
- You cannot kill read-only text, since such text does not allow any
-kind of modification. But some users like to use the kill commands to
-copy read-only text into the kill ring, without actually changing it.
-Therefore, the kill commands work specially in a read-only buffer:
-they move over text, and copy it to the kill ring, without actually
-deleting it from the buffer. Normally, kill commands beep and display
-an error message when this happens. But if you set the variable
-@code{kill-read-only-ok} to a non-@code{nil} value, they just print a
-message in the echo area to explain why the text has not been erased.
-
- You can also use the mouse to kill and yank. @xref{Cut and Paste}.
-
-@menu
-* Deletion:: Commands for deleting small amounts of text and
- blank areas.
-* Killing by Lines:: How to kill entire lines of text at one time.
-* Other Kill Commands:: Commands to kill large regions of text and
- syntactic units such as words and sentences.
-@end menu
-
-@need 1500
-@node Deletion
-@subsection Deletion
-@findex delete-backward-char
-@findex delete-char
-
- Deletion means erasing text and not saving it in the kill ring. For
-the most part, the Emacs commands that delete text are those that
-erase just one character or only whitespace.
-
-@table @kbd
-@item C-d
-@itemx @key{DELETE}
-Delete next character (@code{delete-char}). If your keyboard has a
-@key{DELETE} function key (usually located in the edit keypad), Emacs
-binds it to @code{delete-char} as well.
-@item @key{DEL}
-@itemx @key{BS}
-Delete previous character (@code{delete-backward-char}).
-@item M-\
-Delete spaces and tabs around point (@code{delete-horizontal-space}).
-@item M-@key{SPC}
-Delete spaces and tabs around point, leaving one space
-(@code{just-one-space}).
-@item C-x C-o
-Delete blank lines around the current line (@code{delete-blank-lines}).
-@item M-^
-Join two lines by deleting the intervening newline, along with any
-indentation following it (@code{delete-indentation}).
-@end table
-
-@kindex DEL
-@kindex C-d
- The most basic delete commands are @kbd{C-d} (@code{delete-char}) and
-@key{DEL} (@code{delete-backward-char}). @kbd{C-d} deletes the
-character after point, the one the cursor is ``on top of.'' This
-doesn't move point. @key{DEL} deletes the character before the cursor,
-and moves point back. You can delete newlines like any other characters
-in the buffer; deleting a newline joins two lines. Actually, @kbd{C-d}
-and @key{DEL} aren't always delete commands; when given arguments, they
-kill instead, since they can erase more than one character this way.
-
-@kindex BACKSPACE
-@kindex BS
-@kindex DELETE
- Every keyboard has a large key which is a short distance above the
-@key{RET} or @key{ENTER} key and is normally used for erasing what you
-have typed. It may be labeled @key{DEL}, @key{BACKSPACE}, @key{BS},
-@key{DELETE}, or even with a left arrow. Regardless of the label on
-the key, in Emacs it called @key{DEL}, and it should delete one
-character backwards.
-
- Many keyboards (including standard PC keyboards) have a
-@key{BACKSPACE} key a short ways above @key{RET} or @key{ENTER}, and a
-@key{DELETE} key elsewhere. In that case, the @key{BACKSPACE} key is
-@key{DEL}, and the @key{DELETE} key is equivalent to @kbd{C-d}---or it
-should be.
-
- Why do we say ``or it should be''? When Emacs starts up using a
-graphical display, it determines automatically which key or keys should be
-equivalent to @key{DEL}. As a result, @key{BACKSPACE} and/or @key{DELETE}
-keys normally do the right things. But in some unusual cases Emacs
-gets the wrong information from the system. If these keys don't do
-what they ought to do, you need to tell Emacs which key to use for
-@key{DEL}. @xref{DEL Does Not Delete}, for how to do this.
-
-@findex normal-erase-is-backspace-mode
- On most text-only terminals, Emacs cannot tell which keys the
-keyboard really has, so it follows a uniform plan which may or may not
-fit your keyboard. The uniform plan is that the @acronym{ASCII} @key{DEL}
-character deletes, and the @acronym{ASCII} @key{BS} (backspace) character asks
-for help (it is the same as @kbd{C-h}). If this is not right for your
-keyboard, such as if you find that the key which ought to delete backwards
-enters Help instead, see @ref{DEL Does Not Delete}.
-
-@kindex M-\
-@findex delete-horizontal-space
-@kindex M-SPC
-@findex just-one-space
- The other delete commands are those which delete only whitespace
-characters: spaces, tabs and newlines. @kbd{M-\}
-(@code{delete-horizontal-space}) deletes all the spaces and tab
-characters before and after point. With a prefix argument, this only
-deletes spaces and tab characters before point. @kbd{M-@key{SPC}}
-(@code{just-one-space}) does likewise but leaves a single space after
-point, regardless of the number of spaces that existed previously
-(even if there were none before). With a numeric argument @var{n}, it
-leaves @var{n} spaces after point.
-
- @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines
-after the current line. If the current line is blank, it deletes all
-blank lines preceding the current line as well (leaving one blank line,
-the current line). On a solitary blank line, it deletes that line.
-
- @kbd{M-^} (@code{delete-indentation}) joins the current line and the
-previous line, by deleting a newline and all surrounding spaces, usually
-leaving a single space. @xref{Indentation,M-^}.
-
-@node Killing by Lines
-@subsection Killing by Lines
-
-@table @kbd
-@item C-k
-Kill rest of line or one or more lines (@code{kill-line}).
-@item C-S-backspace
-Kill an entire line at once (@code{kill-whole-line})
-@end table
-
-@kindex C-k
-@findex kill-line
- The simplest kill command is @kbd{C-k}. If given at the beginning of
-a line, it kills all the text on the line, leaving it blank. When used
-on a blank line, it kills the whole line including its newline. To kill
-an entire non-blank line, go to the beginning and type @kbd{C-k} twice.
-
- More generally, @kbd{C-k} kills from point up to the end of the line,
-unless it is at the end of a line. In that case it kills the newline
-following point, thus merging the next line into the current one.
-Spaces and tabs that you can't see at the end of the line are ignored
-when deciding which case applies, so if point appears to be at the end
-of the line, you can be sure @kbd{C-k} will kill the newline.
-
- When @kbd{C-k} is given a positive argument, it kills that many lines
-and the newlines that follow them (however, text on the current line
-before point is not killed). With a negative argument @minus{}@var{n}, it
-kills @var{n} lines preceding the current line (together with the text
-on the current line before point). Thus, @kbd{C-u - 2 C-k} at the front
-of a line kills the two previous lines.
-
- @kbd{C-k} with an argument of zero kills the text before point on the
-current line.
-
-@vindex kill-whole-line
- If the variable @code{kill-whole-line} is non-@code{nil}, @kbd{C-k} at
-the very beginning of a line kills the entire line including the
-following newline. This variable is normally @code{nil}.
-
-@kindex C-S-backspace
-@findex kill-whole-line
- @kbd{C-S-backspace} (@code{kill-whole-line}) will kill a whole line
-including its newline regardless of the position of point within the
-line. Note that many character terminals will prevent you from typing
-the key sequence @kbd{C-S-backspace}.
-
-@node Other Kill Commands
-@subsection Other Kill Commands
-@findex kill-region
-@kindex C-w
-
-@table @kbd
-@item C-w
-Kill region (from point to the mark) (@code{kill-region}).
-@item M-d
-Kill word (@code{kill-word}). @xref{Words}.
-@item M-@key{DEL}
-Kill word backwards (@code{backward-kill-word}).
-@item C-x @key{DEL}
-Kill back to beginning of sentence (@code{backward-kill-sentence}).
-@xref{Sentences}.
-@item M-k
-Kill to end of sentence (@code{kill-sentence}).
-@item C-M-k
-Kill the following balanced expression (@code{kill-sexp}). @xref{Expressions}.
-@item M-z @var{char}
-Kill through the next occurrence of @var{char} (@code{zap-to-char}).
-@end table
-
- The most general kill command is @kbd{C-w} (@code{kill-region}),
-which kills everything between point and the mark. With this command,
-you can kill any contiguous sequence of characters, if you first set
-the region around them.
-
-@kindex M-z
-@findex zap-to-char
- A convenient way of killing is combined with searching: @kbd{M-z}
-(@code{zap-to-char}) reads a character and kills from point up to (and
-including) the next occurrence of that character in the buffer. A
-numeric argument acts as a repeat count. A negative argument means to
-search backward and kill text before point.
-
- Other syntactic units can be killed: words, with @kbd{M-@key{DEL}}
-and @kbd{M-d} (@pxref{Words}); balanced expressions, with @kbd{C-M-k}
-(@pxref{Expressions}); and sentences, with @kbd{C-x @key{DEL}} and
-@kbd{M-k} (@pxref{Sentences}).@refill
-
-@node Yanking, Accumulating Text, Killing, Top
-@section Yanking
-@cindex moving text
-@cindex copying text
-@cindex kill ring
-@cindex yanking
-@cindex pasting
-
- @dfn{Yanking} means reinserting text previously killed. This is what
-some systems call ``pasting.'' The usual way to move or copy text is to
-kill it and then yank it elsewhere one or more times. This is very safe
-because Emacs remembers many recent kills, not just the last one.
-
-@table @kbd
-@item C-y
-Yank last killed text (@code{yank}).
-@item M-y
-Replace text just yanked with an earlier batch of killed text
-(@code{yank-pop}).
-@item M-w
-Save region as last killed text without actually killing it
-(@code{kill-ring-save}). Some systems call this ``copying.''
-@item C-M-w
-Append next kill to last batch of killed text (@code{append-next-kill}).
-@end table
-
- On graphical displays with window systems, if there is a current
-selection in some other application, and you selected it more recently
-than you killed any text in Emacs, @kbd{C-y} copies the selection
-instead of text killed within Emacs.
-
-@menu
-* Kill Ring:: Where killed text is stored. Basic yanking.
-* Appending Kills:: Several kills in a row all yank together.
-* Earlier Kills:: Yanking something killed some time ago.
-@end menu
-
-@node Kill Ring
-@subsection The Kill Ring
-
- All killed text is recorded in the @dfn{kill ring}, a list of blocks of
-text that have been killed. There is only one kill ring, shared by all
-buffers, so you can kill text in one buffer and yank it in another buffer.
-This is the usual way to move text from one file to another.
-(@xref{Accumulating Text}, for some other ways.)
-
-@kindex C-y
-@findex yank
- The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent
-kill. It leaves the cursor at the end of the text. It sets the mark at
-the beginning of the text. @xref{Mark}.
-
- @kbd{C-u C-y} leaves the cursor in front of the text, and sets the
-mark after it. This happens only if the argument is specified with just
-a @kbd{C-u}, precisely. Any other sort of argument, including @kbd{C-u}
-and digits, specifies an earlier kill to yank (@pxref{Earlier Kills}).
-
-@cindex yanking and text properties
-@vindex yank-excluded-properties
- The yank commands discard certain text properties from the text that
-is yanked, those that might lead to annoying results. For instance,
-they discard text properties that respond to the mouse or specify key
-bindings. The variable @code{yank-excluded-properties} specifies the
-properties to discard. Yanking of register contents and rectangles
-also discard these properties.
-
-@kindex M-w
-@findex kill-ring-save
- To copy a block of text, you can use @kbd{M-w}
-(@code{kill-ring-save}), which copies the region into the kill ring
-without removing it from the buffer. This is approximately equivalent
-to @kbd{C-w} followed by @kbd{C-x u}, except that @kbd{M-w} does not
-alter the undo history and does not temporarily change the screen.
-
-@node Appending Kills
-@subsection Appending Kills
-
-@cindex appending kills in the ring
-@cindex television
- Normally, each kill command pushes a new entry onto the kill ring.
-However, two or more kill commands in a row combine their text into a
-single entry, so that a single @kbd{C-y} yanks all the text as a unit,
-just as it was before it was killed.
-
- Thus, if you want to yank text as a unit, you need not kill all of it
-with one command; you can keep killing line after line, or word after
-word, until you have killed it all, and you can still get it all back at
-once.
-
- Commands that kill forward from point add onto the end of the previous
-killed text. Commands that kill backward from point add text onto the
-beginning. This way, any sequence of mixed forward and backward kill
-commands puts all the killed text into one entry without rearrangement.
-Numeric arguments do not break the sequence of appending kills. For
-example, suppose the buffer contains this text:
-
-@example
-This is a line @point{}of sample text.
-@end example
-
-@noindent
-with point shown by @point{}. If you type @kbd{M-d M-@key{DEL} M-d
-M-@key{DEL}}, killing alternately forward and backward, you end up with
-@samp{a line of sample} as one entry in the kill ring, and @samp{This
-is@ @ text.} in the buffer. (Note the double space between @samp{is}
-and @samp{text}, which you can clean up with @kbd{M-@key{SPC}} or
-@kbd{M-q}.)
-
- Another way to kill the same text is to move back two words with
-@kbd{M-b M-b}, then kill all four words forward with @kbd{C-u M-d}.
-This produces exactly the same results in the buffer and in the kill
-ring. @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all going
-backward; once again, the result is the same. The text in the kill ring
-entry always has the same order that it had in the buffer before you
-killed it.
-
-@kindex C-M-w
-@findex append-next-kill
- If a kill command is separated from the last kill command by other
-commands (not just numeric arguments), it starts a new entry on the kill
-ring. But you can force it to append by first typing the command
-@kbd{C-M-w} (@code{append-next-kill}) right before it. The @kbd{C-M-w}
-tells the following command, if it is a kill command, to append the text
-it kills to the last killed text, instead of starting a new entry. With
-@kbd{C-M-w}, you can kill several separated pieces of text and
-accumulate them to be yanked back in one place.@refill
-
- A kill command following @kbd{M-w} does not append to the text that
-@kbd{M-w} copied into the kill ring.
-
-@node Earlier Kills
-@subsection Yanking Earlier Kills
-
-@cindex yanking previous kills
-@kindex M-y
-@findex yank-pop
- To recover killed text that is no longer the most recent kill, use the
-@kbd{M-y} command (@code{yank-pop}). It takes the text previously
-yanked and replaces it with the text from an earlier kill. So, to
-recover the text of the next-to-the-last kill, first use @kbd{C-y} to
-yank the last kill, and then use @kbd{M-y} to replace it with the
-previous kill. @kbd{M-y} is allowed only after a @kbd{C-y} or another
-@kbd{M-y}.
-
- You can understand @kbd{M-y} in terms of a ``last yank'' pointer which
-points at an entry in the kill ring. Each time you kill, the ``last
-yank'' pointer moves to the newly made entry at the front of the ring.
-@kbd{C-y} yanks the entry which the ``last yank'' pointer points to.
-@kbd{M-y} moves the ``last yank'' pointer to a different entry, and the
-text in the buffer changes to match. Enough @kbd{M-y} commands can move
-the pointer to any entry in the ring, so you can get any entry into the
-buffer. Eventually the pointer reaches the end of the ring; the next
-@kbd{M-y} loops back around to the first entry again.
-
- @kbd{M-y} moves the ``last yank'' pointer around the ring, but it does
-not change the order of the entries in the ring, which always runs from
-the most recent kill at the front to the oldest one still remembered.
-
- @kbd{M-y} can take a numeric argument, which tells it how many entries
-to advance the ``last yank'' pointer by. A negative argument moves the
-pointer toward the front of the ring; from the front of the ring, it
-moves ``around'' to the last entry and continues forward from there.
-
- Once the text you are looking for is brought into the buffer, you can
-stop doing @kbd{M-y} commands and it will stay there. It's just a copy
-of the kill ring entry, so editing it in the buffer does not change
-what's in the ring. As long as no new killing is done, the ``last
-yank'' pointer remains at the same place in the kill ring, so repeating
-@kbd{C-y} will yank another copy of the same previous kill.
-
- If you know how many @kbd{M-y} commands it would take to find the
-text you want, you can yank that text in one step using @kbd{C-y} with
-a numeric argument. @kbd{C-y} with an argument restores the text from
-the specified kill ring entry, counting back from the most recent as
-1. Thus, @kbd{C-u 2 C-y} gets the next-to-the-last block of killed
-text---it is equivalent to @kbd{C-y M-y}. @kbd{C-y} with a numeric
-argument starts counting from the ``last yank'' pointer, and sets the
-``last yank'' pointer to the entry that it yanks.
-
-@vindex kill-ring-max
- The length of the kill ring is controlled by the variable
-@code{kill-ring-max}; no more than that many blocks of killed text are
-saved.
-
-@vindex kill-ring
- The actual contents of the kill ring are stored in a variable named
-@code{kill-ring}; you can view the entire contents of the kill ring with
-the command @kbd{C-h v kill-ring}.
-
-@node Accumulating Text, Rectangles, Yanking, Top
-@section Accumulating Text
-@findex append-to-buffer
-@findex prepend-to-buffer
-@findex copy-to-buffer
-@findex append-to-file
-
-@cindex accumulating scattered text
- Usually we copy or move text by killing it and yanking it, but there
-are other convenient methods for copying one block of text in many
-places, or for copying many scattered blocks of text into one place. To
-copy one block to many places, store it in a register
-(@pxref{Registers}). Here we describe the commands to accumulate
-scattered pieces of text into a buffer or into a file.
-
-@table @kbd
-@item M-x append-to-buffer
-Append region to the contents of a specified buffer.
-@item M-x prepend-to-buffer
-Prepend region to the contents of a specified buffer.
-@item M-x copy-to-buffer
-Copy region into a specified buffer, deleting that buffer's old contents.
-@item M-x insert-buffer
-Insert the contents of a specified buffer into current buffer at point.
-@item M-x append-to-file
-Append region to the contents of a specified file, at the end.
-@end table
-
- To accumulate text into a buffer, use @kbd{M-x append-to-buffer}.
-This reads a buffer name, then inserts a copy of the region into the
-buffer specified. If you specify a nonexistent buffer,
-@code{append-to-buffer} creates the buffer. The text is inserted
-wherever point is in that buffer. If you have been using the buffer for
-editing, the copied text goes into the middle of the text of the buffer,
-starting from wherever point happens to be at that moment.
-
- Point in that buffer is left at the end of the copied text, so
-successive uses of @code{append-to-buffer} accumulate the text in the
-specified buffer in the same order as they were copied. Strictly
-speaking, @code{append-to-buffer} does not always append to the text
-already in the buffer---it appends only if point in that buffer is at the end.
-However, if @code{append-to-buffer} is the only command you use to alter
-a buffer, then point is always at the end.
-
- @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer}
-except that point in the other buffer is left before the copied text, so
-successive prependings add text in reverse order. @kbd{M-x
-copy-to-buffer} is similar, except that any existing text in the other
-buffer is deleted, so the buffer is left containing just the text newly
-copied into it.
-
- To retrieve the accumulated text from another buffer, use the
-command @kbd{M-x insert-buffer}; this too takes @var{buffername} as an
-argument. It inserts a copy of the whole text in buffer
-@var{buffername} into the current buffer at point, and sets the mark
-after the inserted text. Alternatively, you can select the other
-buffer for editing, then copy text from it by killing.
-@xref{Buffers}, for background information on buffers.
-
- Instead of accumulating text within Emacs, in a buffer, you can append
-text directly into a file with @kbd{M-x append-to-file}, which takes
-@var{filename} as an argument. It adds the text of the region to the end
-of the specified file. The file is changed immediately on disk.
-
- You should use @code{append-to-file} only with files that are
-@emph{not} being visited in Emacs. Using it on a file that you are
-editing in Emacs would change the file behind Emacs's back, which
-can lead to losing some of your editing.
-
-@node Rectangles, CUA Bindings, Accumulating Text, Top
-@section Rectangles
-@cindex rectangle
-@cindex columns (and rectangles)
-@cindex killing rectangular areas of text
-
- The rectangle commands operate on rectangular areas of the text: all
-the characters between a certain pair of columns, in a certain range of
-lines. Commands are provided to kill rectangles, yank killed rectangles,
-clear them out, fill them with blanks or text, or delete them. Rectangle
-commands are useful with text in multicolumn formats, and for changing
-text into or out of such formats.
-
-@cindex mark rectangle
- When you must specify a rectangle for a command to work on, you do it
-by putting the mark at one corner and point at the opposite corner. The
-rectangle thus specified is called the @dfn{region-rectangle} because
-you control it in much the same way as the region is controlled. But
-remember that a given combination of point and mark values can be
-interpreted either as a region or as a rectangle, depending on the
-command that uses them.
-
- If point and the mark are in the same column, the rectangle they
-delimit is empty. If they are in the same line, the rectangle is one
-line high. This asymmetry between lines and columns comes about
-because point (and likewise the mark) is between two columns, but within
-a line.
-
-@table @kbd
-@item C-x r k
-Kill the text of the region-rectangle, saving its contents as the
-``last killed rectangle'' (@code{kill-rectangle}).
-@item C-x r d
-Delete the text of the region-rectangle (@code{delete-rectangle}).
-@item C-x r y
-Yank the last killed rectangle with its upper left corner at point
-(@code{yank-rectangle}).
-@item C-x r o
-Insert blank space to fill the space of the region-rectangle
-(@code{open-rectangle}). This pushes the previous contents of the
-region-rectangle rightward.
-@item C-x r c
-Clear the region-rectangle by replacing all of its contents with spaces
-(@code{clear-rectangle}).
-@item M-x delete-whitespace-rectangle
-Delete whitespace in each of the lines on the specified rectangle,
-starting from the left edge column of the rectangle.
-@item C-x r t @var{string} @key{RET}
-Replace rectangle contents with @var{string} on each line
-(@code{string-rectangle}).
-@item M-x string-insert-rectangle @key{RET} @var{string} @key{RET}
-Insert @var{string} on each line of the rectangle.
-@end table
-
- The rectangle operations fall into two classes: commands for
-deleting and inserting rectangles, and commands for blank rectangles.
-
-@kindex C-x r k
-@kindex C-x r d
-@findex kill-rectangle
-@findex delete-rectangle
- There are two ways to get rid of the text in a rectangle: you can
-discard the text (delete it) or save it as the ``last killed''
-rectangle. The commands for these two ways are @kbd{C-x r d}
-(@code{delete-rectangle}) and @kbd{C-x r k} (@code{kill-rectangle}). In
-either case, the portion of each line that falls inside the rectangle's
-boundaries is deleted, causing any following text on the line to
-move left into the gap.
-
- Note that ``killing'' a rectangle is not killing in the usual sense; the
-rectangle is not stored in the kill ring, but in a special place that
-can only record the most recent rectangle killed. This is because yanking
-a rectangle is so different from yanking linear text that different yank
-commands have to be used. It is hard to define yank-popping for rectangles,
-so we do not try.
-
-@kindex C-x r y
-@findex yank-rectangle
- To yank the last killed rectangle, type @kbd{C-x r y}
-(@code{yank-rectangle}). Yanking a rectangle is the opposite of killing
-one. Point specifies where to put the rectangle's upper left corner.
-The rectangle's first line is inserted there, the rectangle's second
-line is inserted at the same horizontal position, but one line
-vertically down, and so on. The number of lines affected is determined
-by the height of the saved rectangle.
-
- You can convert single-column lists into double-column lists using
-rectangle killing and yanking; kill the second half of the list as a
-rectangle and then yank it beside the first line of the list.
-@xref{Two-Column}, for another way to edit multi-column text.
-
- You can also copy rectangles into and out of registers with @kbd{C-x r
-r @var{r}} and @kbd{C-x r i @var{r}}. @xref{RegRect,,Rectangle
-Registers}.
-
-@kindex C-x r o
-@findex open-rectangle
-@kindex C-x r c
-@findex clear-rectangle
- There are two commands you can use for making blank rectangles:
-@kbd{C-x r c} (@code{clear-rectangle}) which blanks out existing text,
-and @kbd{C-x r o} (@code{open-rectangle}) which inserts a blank
-rectangle. Clearing a rectangle is equivalent to deleting it and then
-inserting a blank rectangle of the same size.
-
-@findex delete-whitespace-rectangle
- The command @kbd{M-x delete-whitespace-rectangle} deletes horizontal
-whitespace starting from a particular column. This applies to each of
-the lines in the rectangle, and the column is specified by the left
-edge of the rectangle. The right edge of the rectangle does not make
-any difference to this command.
-
-@kindex C-x r t
-@findex string-rectangle
- The command @kbd{C-x r t} (@code{string-rectangle}) replaces the
-contents of a region-rectangle with a string on each line. The
-string's width need not be the same as the width of the rectangle. If
-the string's width is less, the text after the rectangle shifts left;
-if the string is wider than the rectangle, the text after the
-rectangle shifts right.
-
-@findex string-insert-rectangle
- The command @kbd{M-x string-insert-rectangle} is similar to
-@code{string-rectangle}, but inserts the string on each line,
-shifting the original text to the right.
-
-@node CUA Bindings, Registers, Rectangles, Top
-@section CUA Bindings
-@findex cua-mode
-@vindex cua-mode
-@cindex CUA key bindings
-@vindex cua-enable-cua-keys
- The command @kbd{M-x cua-mode} sets up key bindings that are
-compatible with the Common User Access (CUA) system used in many other
-applications. @kbd{C-x} means cut (kill), @kbd{C-c} copy, @kbd{C-v}
-paste (yank), and @kbd{C-z} undo. Standard Emacs commands like
-@kbd{C-x C-c} still work, because @kbd{C-x} and @kbd{C-c} only take
-effect when the mark is active (and the region is highlighted).
-However, if you don't want to override these bindings in Emacs at all,
-set @code{cua-enable-cua-keys} to @code{nil}.
-
- In CUA mode, using @kbd{Shift} together with the movement keys
-activates and highlights the region over which they move. The
-standard (unshifted) movement keys deactivate the mark, and typed text
-replaces the active region as in Delete-Selection mode
-(@pxref{Mouse Commands}).
-
- To enter an Emacs command like @kbd{C-x C-f} while the mark is
-active, use one of the following methods: either hold @kbd{Shift}
-together with the prefix key, e.g. @kbd{S-C-x C-f}, or quickly type
-the prefix key twice, e.g. @kbd{C-x C-x C-f}.
-
-@cindex rectangle highlighting
- CUA mode provides enhanced rectangle support with visible
-rectangle highlighting. Use @kbd{C-RET} to start a rectangle,
-extend it using the movement commands, and cut or copy it using
-@kbd{C-x} or @kbd{C-c}. @kbd{RET} moves the cursor to the next
-(clockwise) corner of the rectangle, so you can easily expand it in
-any direction. Normal text you type is inserted to the left or right
-of each line in the rectangle (on the same side as the cursor).
-
- With CUA you can easily copy text and rectangles into and out of
-registers by providing a one-digit numeric prefix to the kill, copy,
-and yank commands, e.g. @kbd{C-1 C-c} copies the region into register
-@code{1}, and @kbd{C-2 C-v} yanks the contents of register @code{2}.
-
-@cindex global mark
- CUA mode also has a global mark feature which allows easy moving and
-copying of text between buffers. Use @kbd{C-S-SPC} to toggle the
-global mark on and off. When the global mark is on, all text that you
-kill or copy is automatically inserted at the global mark, and text
-you type is inserted at the global mark rather than at the current
-position.
-
- For example, to copy words from various buffers into a word list in
-a given buffer, set the global mark in the target buffer, then
-navigate to each of the words you want in the list, mark it (e.g. with
-@kbd{S-M-f}), copy it to the list with @kbd{C-c} or @kbd{M-w}, and
-insert a newline after the word in the target list by pressing
-@key{RET}.
-
-@ifnottex
-@lowersections
-@end ifnottex
-
-@ignore
- arch-tag: d8da8f96-0928-449a-816e-ff2d3497866c
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Keyboard Macros, Files, Fixit, Top
-@chapter Keyboard Macros
-@cindex defining keyboard macros
-@cindex keyboard macro
-
- In this chapter we describe how to record a sequence of editing
-commands so you can repeat it conveniently later.
-
- A @dfn{keyboard macro} is a command defined by an Emacs user to stand for
-another sequence of keys. For example, if you discover that you are
-about to type @kbd{C-n M-d C-d} forty times, you can speed your work by
-defining a keyboard macro to do @kbd{C-n M-d C-d}, and then executing
-it 39 more times.
-
- You define a keyboard macro by executing and recording the commands
-which are its definition. Put differently, as you define a keyboard
-macro, the definition is being executed for the first time. This way,
-you can see the effects of your commands, so that you don't have to
-figure them out in your head. When you close the definition, the
-keyboard macro is defined and also has been, in effect, executed once.
-You can then do the whole thing over again by invoking the macro.
-
- Keyboard macros differ from ordinary Emacs commands in that they are
-written in the Emacs command language rather than in Lisp. This makes it
-easier for the novice to write them, and makes them more convenient as
-temporary hacks. However, the Emacs command language is not powerful
-enough as a programming language to be useful for writing anything
-intelligent or general. For such things, Lisp must be used.
-
-@menu
-* Basic Keyboard Macro:: Defining and running keyboard macros.
-* Keyboard Macro Ring:: Where previous keyboard macros are saved.
-* Keyboard Macro Counter:: Inserting incrementing numbers in macros.
-* Keyboard Macro Query:: Making keyboard macros do different things each time.
-* Save Keyboard Macro:: Giving keyboard macros names; saving them in files.
-* Edit Keyboard Macro:: Editing keyboard macros.
-* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard
- macro.
-@end menu
-
-@node Basic Keyboard Macro
-@section Basic Use
-
-@table @kbd
-@item @key{F3}
-@itemx C-x (
-Start defining a keyboard macro (@code{kmacro-start-macro}).
-@item @key{F4}
-If a keyboard macro is being defined, end the definition; otherwise,
-execute the most recent keyboard macro
-(@code{kmacro-end-or-call-macro}).
-@item C-x )
-End the definition of a keyboard macro (@code{kmacro-end-macro}).
-@item C-x e
-Execute the most recent keyboard macro (@code{kmacro-end-and-call-macro}).
-First end the definition of the keyboard macro, if currently defining it.
-To immediately execute the keyboard macro again, just repeat the @kbd{e}.
-@item C-u C-x (
-Re-execute last keyboard macro, then add more keys to its definition.
-@item C-u C-u C-x (
-Add more keys to the last keyboard macro without re-executing it.
-@item C-x C-k r
-Run the last keyboard macro on each line that begins in the region
-(@code{apply-macro-to-region-lines}).
-@end table
-
-@kindex F3
-@kindex F4
-@kindex C-x (
-@kindex C-x )
-@kindex C-x e
-@findex kmacro-start-macro
-@findex kmacro-end-macro
-@findex kmacro-end-and-call-macro
- To start defining a keyboard macro, type the @kbd{F3} or @kbd{C-x (} command
-(@code{kmacro-start-macro}). From then on, your keys continue to be
-executed, but also become part of the definition of the macro. @samp{Def}
-appears in the mode line to remind you of what is going on. When you are
-finished, the @kbd{F4} or @kbd{C-x )} command (@code{kmacro-end-macro}) terminates the
-definition (without becoming part of it!). For example,
-
-@example
-C-x ( M-f foo C-x )
-@end example
-
-@noindent
-defines a macro to move forward a word and then insert @samp{foo}.
-
- The macro thus defined can be invoked again with the @kbd{C-x e}
-command (@code{kmacro-end-and-call-macro}), which may be given a
-repeat count as a numeric argument to execute the macro many times.
-If you enter @kbd{C-x e} while defining a macro, the macro is
-terminated and executed immediately.
-
- After executing the macro with @kbd{C-x e}, you can use @kbd{e}
-repeatedly to immediately repeat the macro one or more times. For example,
-
-@example
-C-x ( xyz C-x e e e
-@end example
-
-@noindent
-inserts @samp{xyzxyzxyzxyz} in the current buffer.
-
- @kbd{C-x )} can also be given a repeat count as an argument, in
-which case it repeats the macro that many times right after defining
-it, but defining the macro counts as the first repetition (since it is
-executed as you define it). Therefore, giving @kbd{C-x )} an argument
-of 4 executes the macro immediately 3 additional times. An argument
-of zero to @kbd{C-x e} or @kbd{C-x )} means repeat the macro
-indefinitely (until it gets an error or you type @kbd{C-g} or, on
-MS-DOS, @kbd{C-@key{BREAK}}).
-
- The key @key{F4} is like a combination of @kbd{C-x )} and @kbd{C-x
-e}. If you're defining a macro, @key{F4} ends the definition.
-Otherwise it executes the last macro. For example,
-
-@example
-F3 xyz F4 F4 F4
-@end example
-
-@noindent
-inserts @samp{xyzxyzxyz} in the current buffer.
-
- If you wish to repeat an operation at regularly spaced places in the
-text, define a macro and include as part of the macro the commands to move
-to the next place you want to use it. For example, if you want to change
-each line, you should position point at the start of a line, and define a
-macro to change that line and leave point at the start of the next line.
-Then repeating the macro will operate on successive lines.
-
- When a command reads an argument with the minibuffer, your
-minibuffer input becomes part of the macro along with the command. So
-when you replay the macro, the command gets the same argument as
-when you entered the macro. For example,
-
-@example
-C-x ( C-a C-@key{SPC} C-n M-w C-x b f o o @key{RET} C-y C-x b @key{RET} C-x )
-@end example
-
-@noindent
-defines a macro that copies the current line into the buffer
-@samp{foo}, then returns to the original buffer.
-
- You can use function keys in a keyboard macro, just like keyboard
-keys. You can even use mouse events, but be careful about that: when
-the macro replays the mouse event, it uses the original mouse position
-of that event, the position that the mouse had while you were defining
-the macro. The effect of this may be hard to predict. (Using the
-current mouse position would be even less predictable.)
-
- One thing that sometimes works badly in a keyboard macro is the
-command @kbd{C-M-c} (@code{exit-recursive-edit}). When this command
-exits a recursive edit that started within the macro, it works as
-you'd expect. But if it exits a recursive edit that started before
-you invoked the keyboard macro, it also necessarily exits the keyboard
-macro as part of the process.
-
- After you have terminated the definition of a keyboard macro, you can add
-to the end of its definition by typing @kbd{C-u F3} or @kbd{C-u C-x (}.
-This is equivalent
-to plain @kbd{C-x (} followed by retyping the whole definition so far. As
-a consequence it re-executes the macro as previously defined.
-
- You can also add to the end of the definition of the last keyboard
-macro without re-executing it by typing @kbd{C-u C-u C-x (}.
-
- The variable @code{kmacro-execute-before-append} specifies whether
-a single @kbd{C-u} prefix causes the existing macro to be re-executed
-before appending to it.
-
-@findex apply-macro-to-region-lines
-@kindex C-x C-k r
- The command @kbd{C-x C-k r} (@code{apply-macro-to-region-lines})
-repeats the last defined keyboard macro on each line that begins in
-the region. It does this line by line, by moving point to the
-beginning of the line and then executing the macro.
-
-@node Keyboard Macro Ring
-@section The Keyboard Macro Ring
-
- All defined keyboard macros are recorded in the ``keyboard macro ring,''
-a list of sequences of keys. There is only one keyboard macro ring,
-shared by all buffers.
-
-@table @kbd
-@item C-x C-k C-k
-Execute the keyboard macro at the head of the ring (@code{kmacro-end-or-call-macro-repeat}).
-@item C-x C-k C-n
-Rotate the keyboard macro ring to the next macro (defined earlier)
-(@code{kmacro-cycle-ring-next}).
-@item C-x C-k C-p
-Rotate the keyboard macro ring to the previous macro (defined later)
-(@code{kmacro-cycle-ring-previous}).
-@end table
-
- All commands which operate on the keyboard macro ring use the
-same @kbd{C-x C-k} prefix. Most of these commands can be executed and
-repeated immediately after each other without repeating the @kbd{C-x
-C-k} prefix. For example,
-
-@example
-C-x C-k C-p C-p C-k C-k C-k C-n C-n C-k C-p C-k C-d
-@end example
-
-@noindent
-will rotate the keyboard macro ring to the ``second previous'' macro,
-execute the resulting head macro three times, rotate back to the
-original head macro, execute that once, rotate to the ``previous''
-macro, execute that, and finally delete it from the macro ring.
-
-@findex kmacro-end-or-call-macro-repeat
-@kindex C-x C-k C-k
- The command @kbd{C-x C-k C-k} (@code{kmacro-end-or-call-macro-repeat})
-executes the keyboard macro at the head of the macro ring. You can
-repeat the macro immediately by typing another @kbd{C-k}, or you can
-rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}.
-
- When a keyboard macro is being defined, @kbd{C-x C-k C-k} behaves like
-@kbd{C-x )} except that, immediately afterward, you can use most key
-bindings of this section without the @kbd{C-x C-k} prefix. For
-instance, another @kbd{C-k} will re-execute the macro.
-
-@findex kmacro-cycle-ring-next
-@kindex C-x C-k C-n
-@findex kmacro-cycle-ring-previous
-@kindex C-x C-k C-p
- The commands @kbd{C-x C-k C-n} (@code{kmacro-cycle-ring-next}) and
-@kbd{C-x C-k C-p} (@code{kmacro-cycle-ring-previous}) rotate the
-macro ring, bringing the next or previous keyboard macro to the head
-of the macro ring. The definition of the new head macro is displayed
-in the echo area. You can continue to rotate the macro ring
-immediately by repeating just @kbd{C-n} and @kbd{C-p} until the
-desired macro is at the head of the ring. To execute the new macro
-ring head immediately, just type @kbd{C-k}.
-
- Note that Emacs treats the head of the macro ring as the ``last
-defined keyboard macro.'' For instance, @kbd{C-x e} will execute that
-macro, and @kbd{C-x C-k n} will give it a name.
-
-@ignore @c This interface is too kludgy
- @c and the functionality duplicates the functionality above -- rms.
-@findex kmacro-view-macro-repeat
-@kindex C-x C-k C-v
- The command @kbd{C-x C-k C-v} (@code{kmacro-view-macro-repeat})
-displays the last keyboard macro, or when repeated (with @kbd{C-v}),
-it displays the previous macro on the macro ring, just like @kbd{C-x
-C-k C-p}, but without actually rotating the macro ring. If you enter
-@kbd{C-k} immediately after displaying a macro from the ring, that
-macro is executed, but still without altering the macro ring.
-
- So while e.g. @kbd{C-x C-k C-p C-p C-p C-k C-k} makes the 3rd previous
-macro the current macro and executes it twice, @kbd{C-x C-k C-v C-v
-C-v C-k C-k} will display and execute the 3rd previous macro once and
-then the current macro once.
-@end ignore
-
-@ignore @c This is just too much feeping creaturism.
- @c If you are reusing certain macros enough to want these,
- @c you should give then names. -- rms
-@findex kmacro-delete-ring-head
-@kindex C-x C-k C-d
-
- The command @kbd{C-x C-k C-d} (@code{kmacro-delete-ring-head})
-removes and deletes the macro currently at the head of the macro
-ring. You can use this to delete a macro that didn't work as
-expected, or which you don't need anymore.
-
-@findex kmacro-swap-ring
-@kindex C-x C-k C-t
-
- The command @kbd{C-x C-k C-t} (@code{kmacro-swap-ring})
-interchanges the head of the macro ring with the previous element on
-the macro ring.
-
-@findex kmacro-call-ring-2nd-repeat
-@kindex C-x C-k C-l
-
- The command @kbd{C-x C-k C-l} (@code{kmacro-call-ring-2nd-repeat})
-executes the previous (rather than the head) element on the macro ring.
-@end ignore
-
-@vindex kmacro-ring-max
- The maximum number of macros stored in the keyboard macro ring is
-determined by the customizable variable @code{kmacro-ring-max}.
-
-@node Keyboard Macro Counter
-@section The Keyboard Macro Counter
-
-@table @kbd
-@item C-x C-k C-i
-Insert the keyboard macro counter value in the buffer
-(@code{kmacro-insert-counter}).
-@item C-x C-k C-c
-Set the keyboard macro counter (@code{kmacro-set-counter}).
-@item C-x C-k C-a
-Add the prefix arg to the keyboard macro counter (@code{kmacro-add-counter}).
-@item C-x C-k C-f
-Specify the format for inserting the keyboard macro counter
-(@code{kmacro-set-format}).
-@end table
-
- Each keyboard macro has an associated counter. Normally, the
-macro counter is initialized to 0 when you start defining the macro,
-and incremented by 1 after each insertion of the counter value;
-that is, if you insert the macro counter twice while defining the
-macro, the counter will increase by 2 on each repetition of the macro.
-
-@findex kmacro-insert-counter
-@kindex C-x C-k C-i
- The command @kbd{C-x C-k C-i} (@code{kmacro-insert-counter}) inserts
-the current value of the current keyboard macro's counter, and
-increments the counter by 1. You can use a numeric prefix argument to
-specify a different increment. If you just specify a @kbd{C-u}
-prefix, then the increment is zero, so it repeats the last inserted
-counter value. For example, if you enter the following sequence while
-defining a macro
-
-@example
-C-x C-k C-i C-x C-k C-i C-u C-x C-k C-i C-x C-k C-i
-@end example
-
-@noindent
-it inserts @samp{0112} in the buffer. The next two iterations
-of the macro will insert @samp{3445} and @samp{6778}.
-
- This command usually only makes sense while defining a keyboard
-macro. But its behavior when no keyboard macro is being defined or
-executed is predictable: it inserts and increments the counter of the
-macro at the head of the keyboard macro ring.
-
-@findex kmacro-set-counter
-@kindex C-x C-k C-c
- The command @kbd{C-x C-k C-c} (@code{kmacro-set-counter}) sets the
-current macro counter to the value of the numeric argument. If you use
-it inside the macro, it operates on each repetition of the macro. If
-you specify just @kbd{C-u} as the prefix, while executing the macro,
-that resets the counter to the value it had at the beginning of the
-current repetition of the macro (undoing any increments so far in this
-repetition).
-
-@findex kmacro-add-counter
-@kindex C-x C-k C-a
- The command @kbd{C-x C-k C-a} (@code{kmacro-add-counter}) adds the
-prefix argument to the current macro counter. With just @kbd{C-u} as
-argument, it resets the counter to the last value inserted by any
-keyboard macro. (Normally, when you use this, the last insertion
-will be in the same macro and it will be the same counter.)
-
-@findex kmacro-set-format
-@kindex C-x C-k C-f
- The command @kbd{C-x C-k C-f} (@code{kmacro-set-format}) prompts for
-the format to use when inserting the macro counter. The default
-format is @samp{%d}, which means to insert the number in decimal
-without any padding. You can exit with empty minibuffer to reset the
-format to this default. You can specify any format string that the
-@code{format} function accepts and that makes sense with a single
-integer extra argument (@pxref{Formatting Strings,,, elisp, The Emacs
-Lisp Reference Manual}). Do not put the format string inside double
-quotes when you insert it in the minibuffer.
-
- If you use this command while no keyboard macro is being defined or
-executed, the new format affects all subsequent macro definitions.
-Existing macros continue to use the format in effect when they were
-defined. If you set the format while defining a keyboard macro, this
-affects the macro being defined from that point on, but it does not
-affect subsequent macros. Execution of the macro will, at each step,
-use the format in effect at that step during its definition. Changes
-to the macro format during execution of a macro, like the
-corresponding changes during its definition, have no effect on
-subsequent macros.
-
- The format set by @kbd{C-x C-k C-f} does not affect insertion of
-numbers stored in registers.
-
-@node Keyboard Macro Query
-@section Executing Macros with Variations
-
-@table @kbd
-@item C-x q
-When this point is reached during macro execution, ask for confirmation
-(@code{kbd-macro-query}).
-@end table
-
-@kindex C-x q
-@findex kbd-macro-query
- Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect
-similar to that of @code{query-replace}, where the macro asks you each
-time around whether to make a change. While defining the macro,
-type @kbd{C-x q} at the point where you want the query to occur. During
-macro definition, the @kbd{C-x q} does nothing, but when you run the
-macro later, @kbd{C-x q} asks you interactively whether to continue.
-
- The valid responses when @kbd{C-x q} asks are @key{SPC} (or @kbd{y}),
-@key{DEL} (or @kbd{n}), @key{RET} (or @kbd{q}), @kbd{C-l} and @kbd{C-r}.
-The answers are the same as in @code{query-replace}, though not all of
-the @code{query-replace} options are meaningful.
-
- These responses include @key{SPC} to continue, and @key{DEL} to skip
-the remainder of this repetition of the macro and start right away with
-the next repetition. @key{RET} means to skip the remainder of this
-repetition and cancel further repetitions. @kbd{C-l} redraws the screen
-and asks you again for a character to say what to do.
-
- @kbd{C-r} enters a recursive editing level, in which you can perform
-editing which is not part of the macro. When you exit the recursive
-edit using @kbd{C-M-c}, you are asked again how to continue with the
-keyboard macro. If you type a @key{SPC} at this time, the rest of the
-macro definition is executed. It is up to you to leave point and the
-text in a state such that the rest of the macro will do what you
-want.@refill
-
- @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument,
-performs a completely different function. It enters a recursive edit
-reading input from the keyboard, both when you type it during the
-definition of the macro, and when it is executed from the macro. During
-definition, the editing you do inside the recursive edit does not become
-part of the macro. During macro execution, the recursive edit gives you
-a chance to do some particularized editing on each repetition.
-@xref{Recursive Edit}.
-
- Another way to vary the behavior of a keyboard macro is to use a
-register as a counter, incrementing it on each repetition of the macro.
-@xref{RegNumbers}.
-
-@node Save Keyboard Macro
-@section Naming and Saving Keyboard Macros
-
-@table @kbd
-@item C-x C-k n
-Give a command name (for the duration of the Emacs session) to the most
-recently defined keyboard macro (@code{kmacro-name-last-macro}).
-@item C-x C-k b
-Bind the most recently defined keyboard macro to a key sequence (for
-the duration of the session) (@code{kmacro-bind-to-key}).
-@item M-x insert-kbd-macro
-Insert in the buffer a keyboard macro's definition, as Lisp code.
-@end table
-
-@cindex saving keyboard macros
-@findex kmacro-name-last-macro
-@kindex C-x C-k n
- If you wish to save a keyboard macro for later use, you can give it
-a name using @kbd{C-x C-k n} (@code{kmacro-name-last-macro}).
-This reads a name as an argument using the minibuffer and defines that
-name to execute the last keyboard macro, in its current form. (If you
-later add to the definition of this macro, that does not alter the
-name's definition as a macro.) The macro name is a Lisp symbol, and
-defining it in this way makes it a valid command name for calling with
-@kbd{M-x} or for binding a key to with @code{global-set-key}
-(@pxref{Keymaps}). If you specify a name that has a prior definition
-other than a keyboard macro, an error message is shown and nothing is
-changed.
-
-@cindex binding keyboard macros
-@findex kmacro-bind-to-key
-@kindex C-x C-k b
- You can also bind the last keyboard macro (in its current form) to a
-key, using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the
-key sequence you want to bind. You can bind to any key sequence in
-the global keymap, but since most key sequences already have other
-bindings, you should select the key sequence carefully. If you try to
-bind to a key sequence with an existing binding (in any keymap), this
-command asks you for confirmation before replacing the existing binding.
-
- To avoid problems caused by overriding existing bindings, the key
-sequences @kbd{C-x C-k 0} through @kbd{C-x C-k 9} and @kbd{C-x C-k A}
-through @kbd{C-x C-k Z} are reserved for your own keyboard macro
-bindings. In fact, to bind to one of these key sequences, you only
-need to type the digit or letter rather than the whole key sequences.
-For example,
-
-@example
-C-x C-k b 4
-@end example
-
-@noindent
-will bind the last keyboard macro to the key sequence @kbd{C-x C-k 4}.
-
-@findex insert-kbd-macro
- Once a macro has a command name, you can save its definition in a file.
-Then it can be used in another editing session. First, visit the file
-you want to save the definition in. Then use this command:
-
-@example
-M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
-@end example
-
-@noindent
-This inserts some Lisp code that, when executed later, will define the
-same macro with the same definition it has now. (You need not
-understand Lisp code to do this, because @code{insert-kbd-macro} writes
-the Lisp code for you.) Then save the file. You can load the file
-later with @code{load-file} (@pxref{Lisp Libraries}). If the file you
-save in is your init file @file{~/.emacs} (@pxref{Init File}) then the
-macro will be defined each time you run Emacs.
-
- If you give @code{insert-kbd-macro} a numeric argument, it makes
-additional Lisp code to record the keys (if any) that you have bound
-to @var{macroname}, so that the macro will be reassigned the same keys
-when you load the file.
-
-@node Edit Keyboard Macro
-@section Editing a Keyboard Macro
-
-@table @kbd
-@item C-x C-k C-e
-Edit the last defined keyboard macro (@code{kmacro-edit-macro}).
-@item C-x C-k e @var{name} @key{RET}
-Edit a previously defined keyboard macro @var{name} (@code{edit-kbd-macro}).
-@item C-x C-k l
-Edit the last 100 keystrokes as a keyboard macro
-(@code{kmacro-edit-lossage}).
-@end table
-
-@findex kmacro-edit-macro
-@kindex C-x C-k C-e
-@kindex C-x C-k RET
- You can edit the last keyboard macro by typing @kbd{C-x C-k C-e} or
-@kbd{C-x C-k RET} (@code{kmacro-edit-macro}). This formats the macro
-definition in a buffer and enters a specialized major mode for editing
-it. Type @kbd{C-h m} once in that buffer to display details of how to
-edit the macro. When you are finished editing, type @kbd{C-c C-c}.
-
-@findex edit-kbd-macro
-@kindex C-x C-k e
- You can edit a named keyboard macro or a macro bound to a key by typing
-@kbd{C-x C-k e} (@code{edit-kbd-macro}). Follow that with the
-keyboard input that you would use to invoke the macro---@kbd{C-x e} or
-@kbd{M-x @var{name}} or some other key sequence.
-
-@findex kmacro-edit-lossage
-@kindex C-x C-k l
- You can edit the last 100 keystrokes as a macro by typing
-@kbd{C-x C-k l} (@code{kmacro-edit-lossage}).
-
-@node Keyboard Macro Step-Edit
-@section Stepwise Editing a Keyboard Macro
-
-@findex kmacro-step-edit-macro
-@kindex C-x C-k SPC
- You can interactively replay and edit the last keyboard
-macro, one command at a time, by typing @kbd{C-x C-k SPC}
-(@code{kmacro-step-edit-macro}). Unless you quit the macro using
-@kbd{q} or @kbd{C-g}, the edited macro replaces the last macro on the
-macro ring.
-
- This macro editing feature shows the last macro in the minibuffer
-together with the first (or next) command to be executed, and prompts
-you for an action. You can enter @kbd{?} to get a summary of your
-options. These actions are available:
-
-@itemize @bullet{}
-@item
-@kbd{SPC} and @kbd{y} execute the current command, and advance to the
-next command in the keyboard macro.
-@item
-@kbd{n}, @kbd{d}, and @kbd{DEL} skip and delete the current command.
-@item
-@kbd{f} skips the current command in this execution of the keyboard
-macro, but doesn't delete it from the macro.
-@item
-@kbd{@key{TAB}} executes the current command, as well as all similar
-commands immediately following the current command; for example, @key{TAB}
-may be used to insert a sequence of characters (corresponding to a
-sequence of @code{self-insert-command} commands).
-@item
-@kbd{c} continues execution (without further editing) until the end of
-the keyboard macro. If execution terminates normally, the edited
-macro replaces the original keyboard macro.
-@item
-@kbd{C-k} skips and deletes the rest of the keyboard macro,
-terminates step-editing, and replaces the original keyboard macro
-with the edited macro.
-@item
-@kbd{q} and @kbd{C-g} cancels the step-editing of the keyboard macro;
-discarding any changes made to the keyboard macro.
-@item
-@kbd{i KEY... C-j} reads and executes a series of key sequences (not
-including the final @kbd{C-j}), and inserts them before the current
-command in the keyboard macro, without advancing over the current
-command.
-@item
-@kbd{I KEY...} reads one key sequence, executes it, and inserts it
-before the current command in the keyboard macro, without advancing
-over the current command.
-@item
-@kbd{r KEY... C-j} reads and executes a series of key sequences (not
-including the final @kbd{C-j}), and replaces the current command in
-the keyboard macro with them, advancing over the inserted key
-sequences.
-@item
-@kbd{R KEY...} reads one key sequence, executes it, and replaces the
-current command in the keyboard macro with that key sequence,
-advancing over the inserted key sequence.
-@item
-@kbd{a KEY... C-j} executes the current command, then reads and
-executes a series of key sequences (not including the final
-@kbd{C-j}), and inserts them after the current command in the keyboard
-macro; it then advances over the current command and the inserted key
-sequences.
-@item
-@kbd{A KEY... C-j} executes the rest of the commands in the keyboard
-macro, then reads and executes a series of key sequences (not
-including the final @kbd{C-j}), and appends them at the end of the
-keyboard macro; it then terminates the step-editing and replaces the
-original keyboard macro with the edited macro.
-@end itemize
-
-@ignore
- arch-tag: c1b0dd3b-3159-4c08-928f-52e763953e9c
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node M-x, Help, Minibuffer, Top
-@chapter Running Commands by Name
-
- Every Emacs command has a name that you can use to run it. For
-convenience, many commands also have key bindings. You can run those
-commands by typing the keys, or run them by name. Most Emacs commands
-have no key bindings, so the only way to run them is by name.
-(@xref{Key Bindings}, for how to set up key bindings.)
-
- By convention, a command name consists of one or more words,
-separated by hyphens; for example, @code{auto-fill-mode} or
-@code{manual-entry}. Command names mostly use complete English words
-to make them easier to remember.
-
-@kindex M-x
- To run a command by name, start with @kbd{M-x}, type the command
-name, then terminate it with @key{RET}. @kbd{M-x} uses the minibuffer
-to read the command name. The string @samp{M-x} appears at the
-beginning of the minibuffer as a @dfn{prompt} to remind you to enter a
-command name to be run. @key{RET} exits the minibuffer and runs the
-command. @xref{Minibuffer}, for more information on the minibuffer.
-
- You can use completion to enter the command name. For example,
-to invoke the command @code{forward-char}, you can type
-
-@example
-M-x forward-char @key{RET}
-@end example
-
-@noindent
-or
-
-@example
-M-x forw @key{TAB} c @key{RET}
-@end example
-
-@noindent
-Note that @code{forward-char} is the same command that you invoke with
-the key @kbd{C-f}. The existence of a key binding does not stop you
-from running the command by name.
-
- To cancel the @kbd{M-x} and not run a command, type @kbd{C-g} instead
-of entering the command name. This takes you back to command level.
-
- To pass a numeric argument to the command you are invoking with
-@kbd{M-x}, specify the numeric argument before @kbd{M-x}. The
-argument value appears in the prompt while the command name is being
-read, and finally @kbd{M-x} passes the argument to that command.
-
-@vindex suggest-key-bindings
- When the command you run with @kbd{M-x} has a key binding, Emacs
-mentions this in the echo area after running the command. For
-example, if you type @kbd{M-x forward-word}, the message says that you
-can run the same command by typing @kbd{M-f}. You can turn off these
-messages by setting the variable @code{suggest-key-bindings} to
-@code{nil}.
-
- In this manual, when we speak of running a command by name, we often
-omit the @key{RET} that terminates the name. Thus we might say
-@kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode
-@key{RET}}. We mention the @key{RET} only for emphasis, such as when
-the command is followed by arguments.
-
-@findex execute-extended-command
- @kbd{M-x} works by running the command
-@code{execute-extended-command}, which is responsible for reading the
-name of another command and invoking it.
-
-@ignore
- arch-tag: b67bff53-9628-4666-b94e-eda972a7ba56
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 2000, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Mac OS, Microsoft Windows, Antinews, Top
-@appendix Emacs and Mac OS
-@cindex Mac OS
-@cindex Macintosh
-
- This section briefly describes the peculiarities of using Emacs
-under Mac OS with native window system support. For Mac OS X, Emacs
-can be built either without window system support, with X11, or with
-Carbon API. This section only applies to the Carbon build. For Mac
-OS Classic, Emacs can be built with or without Carbon API, and this
-section applies to either of them because they run on the native
-window system.
-
- Emacs built on Mac OS X supports most of its major features except
-display support of PostScript images. The following features of Emacs
-are not supported on Mac OS Classic: unexec (@code{dump-emacs}),
-asynchronous subprocesses (@code{start-process}), and networking
-(@code{open-network-stream}). As a result, packages such as Gnus,
-GUD, and Comint do not work. Synchronous subprocesses
-(@code{call-process}) are supported on non-Carbon build, but
-specially-crafted external programs are needed. Since external
-programs to handle commands such as @code{print-buffer} and
-@code{diff} are not available on Mac OS Classic, they are not
-supported. Non-Carbon build on Mac OS Classic does not support some
-features such as file dialogs, drag-and-drop, and Unicode menus.
-
-@menu
-* Input: Mac Input. Keyboard and mouse input on Mac.
-* Intl: Mac International. International character sets on Mac.
-* Env: Mac Environment Variables. Setting environment variables for Emacs.
-* Directories: Mac Directories. Volumes and directories on Mac.
-* Font: Mac Font Specs. Specifying fonts on Mac.
-* Functions: Mac Functions. Mac-specific Lisp functions.
-@end menu
-
-@node Mac Input
-@section Keyboard and Mouse Input on Mac
-@cindex Meta (Mac OS)
-@cindex keyboard coding (Mac OS)
-
-@vindex mac-control-modifier
-@vindex mac-command-modifier
-@vindex mac-option-modifier
-@vindex mac-function-modifier
- On Mac, Emacs can use @key{control}, @key{command}, @key{option}, and
-laptop @key{function} keys as any of Emacs modifier keys except
-@key{SHIFT} (i.e., @key{ALT}, @key{CTRL}, @key{HYPER}, @key{META}, and
-@key{SUPER}). The assignment is controlled by the variables
-@code{mac-control-modifier}, @code{mac-command-modifier},
-@code{mac-option-modifier}, and @code{mac-function-modifier}. The value
-for each of these variables can be one of the following symbols:
-@code{alt}, @code{control}, @code{hyper}, @code{meta}, @code{super}, and
-@code{nil} (no particular assignment). By default, the @key{control}
-key works as @key{CTRL}, and the @key{command} key as @key{META}.
-
- For the @key{option} key, if @code{mac-option-modifier} is set to
-@code{nil}, which is the default, the key works as the normal
-@key{option} key, i.e., dead-key processing will work. This is useful
-for entering non-@acronym{ASCII} Latin characters directly from the
-Mac keyboard, for example.
-
- Emacs recognizes the setting in the Keyboard control panel (Mac OS
-Classic) or the International system preference pane (Mac OS X) and
-supports international and alternative keyboard layouts (e.g., Dvorak).
-Selecting one of the layouts from the keyboard layout pull-down menu
-will affect how the keys typed on the keyboard are interpreted.
-
-@vindex mac-pass-command-to-system
-@vindex mac-pass-control-to-system
- Mac OS intercepts and handles certain key combinations (e.g.,
-@key{command}-@key{SPC} for switching input languages). These will not
-be passed to Emacs. One can disable this interception by setting
-@code{mac-pass-command-to-system} or @code{mac-pass-control-to-system}
-to @code{nil}.
-
-@vindex mac-emulate-three-button-mouse
- Especially for one-button mice, the multiple button feature can be
-emulated by setting @code{mac-emulate-three-button-mouse} to @code{t}
-or @code{reverse}. If set to @code{t} (@code{reverse}, respectively),
-pressing the mouse button with the @key{option} key is recognized as
-the second (third) button, and that with the @key{command} key is
-recognized as the third (second) button.
-
-@vindex mac-wheel-button-is-mouse-2
- For multi-button mice, the wheel button and the secondary button are
-recognized as the second and the third button, respectively. If
-@code{mac-wheel-button-is-mouse-2} is set to @code{nil}, their roles
-are exchanged.
-
-@node Mac International
-@section International Character Set Support on Mac
-@cindex Mac Roman coding system
-@cindex clipboard support (Mac OS)
-
- Mac uses non-standard encodings for the upper 128 single-byte
-characters. They also deviate from the ISO 2022 standard by using
-character codes in the range 128-159. The coding systems
-@code{mac-roman}, @code{mac-centraleurroman}, and @code{mac-cyrillic}
-are used to represent these Mac encodings.
-
- You can use input methods provided either by LEIM (@pxref{Input
-Methods}) or Mac OS to enter international characters. To use the
-former, see the International Character Set Support section of the
-manual (@pxref{International}).
-
- Emacs on Mac OS automatically changes the value of
-@code{keyboard-coding-system} according to the current keyboard
-layout. So users don't need to set it manually, and even if set, it
-will be changed when the keyboard layout change is detected next time.
-
- The Mac clipboard and the Emacs kill ring (@pxref{Killing}) are
-synchronized by default: you can yank a piece of text and paste it
-into another Mac application, or cut or copy one in another Mac
-application and yank it into a Emacs buffer. This feature can be
-disabled by setting @code{x-select-enable-clipboard} to @code{nil}.
-One can still do copy and paste with another application from the Edit
-menu.
-
- On Mac, the role of the coding system for selection that is set by
-@code{set-selection-coding-system} (@pxref{Communication Coding}) is
-two-fold. First, it is used as a preferred coding system for the
-traditional text flavor that does not specify any particular encodings
-and is mainly used by applications on Mac OS Classic. Second, it
-specifies the intermediate encoding for the UTF-16 text flavor that is
-mainly used by applications on Mac OS X.
-
- When pasting UTF-16 text data from the clipboard, it is first
-converted to the encoding specified by the selection coding system
-using the converter in the Mac OS system, and then decoded into the
-Emacs internal encoding using the converter in Emacs. If the first
-conversion failed, then the UTF-16 data is directly converted to Emacs
-internal encoding using the converter in Emacs. Copying UTF-16 text
-to the clipboard goes through the inverse path. The reason for this
-two-pass decoding is to avoid subtle differences in Unicode mappings
-between the Mac OS system and Emacs such as various kinds of hyphens,
-and to minimize users' customization. For example, users that mainly
-use Latin characters would prefer Greek characters to be decoded into
-the @code{mule-unicode-0100-24ff} charset, but Japanese users would
-prefer them to be decoded into the @code{japanese-jisx0208} charset.
-Since the coding system for selection is automatically set according
-to the system locale setting, users usually don't have to set it
-manually.
-
- The default language environment (@pxref{Language Environments}) is
-set according to the locale setting at the startup time. On Mac OS,
-the locale setting is consulted in the following order:
-
-@enumerate
-@item
-Environment variables @env{LC_ALL}, @env{LC_CTYPE} and @env{LANG} as
-in other systems.
-
-@item
-Preference @code{AppleLocale} that is set by default on Mac OS X 10.3
-and later.
-
-@item
-Preference @code{AppleLanguages} that is set by default on Mac OS X
-10.1 and later.
-
-@item
-Variable @code{mac-system-locale} that is derived from the system
-language and region codes. This variable is available on all
-supported Mac OS versions including Mac OS Classic.
-@end enumerate
-
- The default values of almost all variables about coding systems are
-also set according to the language environment. So usually you don't
-have to customize these variables manually.
-
-@node Mac Environment Variables
-@section Environment Variables and Command Line Arguments.
-@cindex environment variables (Mac OS)
-
- On Mac OS X, when Emacs is run in a terminal, it inherits the values
-of environment variables from the shell from which it is invoked.
-However, when it is run from the Finder as a GUI application, it only
-inherits environment variable values defined in the file
-@file{~/.MacOSX/environment.plist} that affects all the applications
-invoked from the Finder or the @command{open} command.
-
- Command line arguments are specified like
-
-@example
-/Applications/Emacs.app/Contents/MacOS/Emacs -g 80x25 &
-@end example
-
-@noindent
-if Emacs is installed at @file{/Applications/Emacs.app}. If Emacs is
-invoked like this, then it also inherits the values of environment
-variables from the shell from which it is invoked.
-
- On Mac OS Classic, environment variables and command line arguments
-for Emacs can be set by modifying the @samp{STR#} resources 128 and
-129, respectively. A common environment variable that one may want to
-set is @samp{HOME}.
-
- The way to set an environment variable is by adding a string of the
-form
-
-@example
-ENV_VAR=VALUE
-@end example
-
-@noindent
-to resource @samp{STR#} number 128 using @code{ResEdit}. To set up the
-program to use unibyte characters exclusively, for example, add the
-string
-
-@example
-EMACS_UNIBYTE=1
-@end example
-
-@cindex Mac Preferences
- Although Emacs on Mac does not support X resources (@pxref{X
-Resources}) directly, one can use the Preferences system in place of X
-resources. For example, adding the line
-
-@example
-Emacs.cursorType: bar
-@end example
-
-@noindent
-to @file{~/.Xresources} in X11 corresponds to the execution of
-
-@example
-defaults write org.gnu.Emacs Emacs.cursorType bar
-@end example
-
-@noindent
-on Mac OS X. One can use boolean or numeric values as well as string
-values as follows:
-
-@example
-defaults write org.gnu.Emacs Emacs.toolBar -bool false
-defaults write org.gnu.Emacs Emacs.lineSpacing -int 3
-@end example
-
-@noindent
-Try @kbd{M-x man RET defaults RET} for the usage of the
-@command{defaults} command. Alternatively, if you have Developer
-Tools installed on Mac OS X, you can use Property List Editor to edit
-the file @file{~/Library/Preferences/org.gnu.Emacs.plist}.
-
-
-@node Mac Directories
-@section Volumes and Directories on Mac
-@cindex file names (Mac OS)
-
- This node applies to Mac OS Classic only.
-
- The directory structure in Mac OS Classic is seen by Emacs as
-
-@example
-/@var{volumename}/@var{filename}
-@end example
-
-So when Emacs requests a file name, doing file name completion on
-@file{/} will display all volumes on the system. You can use @file{..}
-to go up a directory level.
-
- On Mac OS Classic, to access files and folders on the desktop, look
-in the folder @file{Desktop Folder} in your boot volume (this folder
-is usually invisible in the Mac @code{Finder}).
-
- On Mac OS Classic, Emacs creates the Mac folder
-@file{:Preferences:Emacs:} in the @file{System Folder} and uses it as
-the temporary directory. Emacs maps the directory name @file{/tmp/}
-to that. Therefore it is best to avoid naming a volume @file{tmp}.
-If everything works correctly, the program should leave no files in it
-when it exits. You should be able to set the environment variable
-@code{TMPDIR} to use another directory but this folder will still be
-created.
-
-
-@node Mac Font Specs
-@section Specifying Fonts on Mac
-@cindex font names (Mac OS)
-
- It is rare that you need to specify a font name in Emacs; usually
-you specify face attributes instead. For example, you can use 14pt
-Courier by customizing the default face attributes for all frames:
-
-@lisp
-(set-face-attribute 'default nil
- :family "courier" :height 140)
-@end lisp
-
-@noindent
-Alternatively, an interactive one is also available
-(@pxref{Face Customization}).
-
-But when you do need to specify a font name in Emacs on Mac, use a
-standard X font name:
-
-@smallexample
--@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}
-@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset}
-@end smallexample
-
-@noindent
-@xref{Font X}. Wildcards are supported as they are on X.
-
- Emacs on Mac OS Classic uses QuickDraw Text routines for drawing texts
-by default. Emacs on Mac OS X uses @acronym{ATSUI, Apple Type Services
-for Unicode Imaging} as well as QuickDraw Text, and most of the
-characters other than Chinese, Japanese, and Korean ones are drawn using
-the former by default.
-
- @acronym{ATSUI}-compatible fonts have maker name @code{apple} and
-charset @code{iso10646-1}. For example, 12-point Monaco can be specified
-by the name:
-
-@example
--apple-monaco-medium-r-normal--12-*-*-*-*-*-iso10646-1
-@end example
-
-Note that these names must be specified using a format containing all
-14 @samp{-}s (not by
-@samp{-apple-monaco-medium-r-normal--12-*-iso10646-1}, for instance),
-because every @acronym{ATSUI}-compatible font is a scalable one.
-
- QuickDraw Text fonts have maker name @code{apple} and various charset
-names other than @code{iso10646-1}. Native Apple fonts in Mac Roman
-encoding has charset @code{mac-roman}. You can specify a
-@code{mac-roman} font for @acronym{ASCII} characters like
-
-@smalllisp
-(add-to-list
- 'default-frame-alist
- '(font . "-apple-monaco-medium-r-normal--13-*-*-*-*-*-mac-roman"))
-@end smalllisp
-
-@noindent
-but that does not extend to ISO-8859-1: specifying a @code{mac-roman}
-font for Latin-1 characters introduces wrong glyphs.
-
- Native Apple Traditional Chinese, Simplified Chinese, Japanese,
-Korean, Central European, Cyrillic, Symbol, and Dingbats fonts have
-the charsets @samp{big5-0}, @samp{gb2312.1980-0},
-@samp{jisx0208.1983-sjis} and @samp{jisx0201.1976-0},
-@samp{ksc5601.1989-0}, @samp{mac-centraleurroman},
-@samp{mac-cyrillic}, @samp{mac-symbol}, and @samp{mac-dingbats},
-respectively.
-
- The use of @code{create-fontset-from-fontset-spec} (@pxref{Defining
-Fontsets}) for defining fontsets often results in wrong ones especially
-when using only OS-bundled QuickDraw Text fonts. The recommended way to
-use them is to create a fontset using
-@code{create-fontset-from-mac-roman-font}:
-
-@lisp
-(create-fontset-from-mac-roman-font
- "-apple-courier-medium-r-normal--13-*-*-*-*-*-mac-roman"
- nil "foo")
-@end lisp
-
-@noindent
-and then optionally specifying Chinese, Japanese, or Korean font
-families using @code{set-fontset-font}:
-
-@lisp
-(set-fontset-font "fontset-foo"
- 'chinese-gb2312 '("song" . "gb2312.1980-0"))
-@end lisp
-
- Single-byte fonts converted from GNU fonts in BDF format, which are not
-in the Mac Roman encoding, have foundry, family, and character sets
-encoded in the names of their font suitcases. E.g., the font suitcase
-@samp{ETL-Fixed-ISO8859-1} contains fonts which can be referred to by
-the name @samp{-ETL-fixed-*-iso8859-1}.
-
-@vindex mac-allow-anti-aliasing
- Mac OS X 10.2 or later can use two types of text renderings: Quartz 2D
-(aka Core Graphics) and QuickDraw. By default, Emacs uses the former on
-such versions. It can be changed by setting
-@code{mac-allow-anti-aliasing} to @code{t} (Quartz 2D) or @code{nil}
-(QuickDraw). Both @acronym{ATSUI} and QuickDraw Text drawings are
-affected by the value of this variable.
-
- Appearance of text in small sizes will also be affected by the ``Turn
-off text smoothing for font sizes @var{n} and smaller'' setting in the
-General pane (Mac OS X 10.1 or 10.2) or in the Appearance pane (10.3 or
-later) of the System Preferences. This threshold can alternatively be
-set just for Emacs (i.e., not as the system-wide setting) using the
-@command{defaults} command:
-
-@example
-defaults write org.gnu.Emacs AppleAntiAliasingThreshold @var{n}
-@end example
-
-
-@node Mac Functions
-@section Mac-Specific Lisp Functions
-@cindex Lisp functions specific to Mac OS
-
-@findex do-applescript
- The function @code{do-applescript} takes a string argument,
-executes it as an AppleScript command, and returns the result as a
-string.
-
-@findex mac-file-name-to-posix
-@findex posix-file-name-to-mac
- The function @code{mac-file-name-to-posix} takes a Mac file name and
-returns the GNU or Unix equivalent. The function
-@code{posix-file-name-to-mac} performs the opposite conversion. They
-are useful for constructing AppleScript commands to be passed to
-@code{do-applescript}.
-
-@findex mac-set-file-creator
-@findex mac-get-file-creator
-@findex mac-set-file-type
-@findex mac-get-file-type
- The functions @code{mac-set-file-creator},
-@code{mac-get-file-creator}, @code{mac-set-file-type}, and
-@code{mac-get-file-type} can be used to set and get creator and file
-codes.
-
-@findex mac-get-preference
- The function @code{mac-get-preference} returns the preferences value
-converted to a Lisp object for a specified key and application.
-
-@ignore
- arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Maintaining, Abbrevs, Building, Top
-@chapter Maintaining Large Programs
-
- This chapter describes Emacs features for maintaining large
-programs. The version control features (@pxref{Version Control}) are
-also particularly useful for this purpose.
-
-@menu
-* Change Log:: Maintaining a change history for your program.
-* Format of ChangeLog:: What the change log file looks like.
-* Tags:: Go direct to any function in your program in one
- command. Tags remembers which file it is in.
-@ifnottex
-* Emerge:: A convenient way of merging two versions of a program.
-@end ifnottex
-@end menu
-
-@node Change Log
-@section Change Logs
-
- A change log file contains a chronological record of when and why you
-have changed a program, consisting of a sequence of entries describing
-individual changes. Normally it is kept in a file called
-@file{ChangeLog} in the same directory as the file you are editing, or
-one of its parent directories. A single @file{ChangeLog} file can
-record changes for all the files in its directory and all its
-subdirectories.
-
-@cindex change log
-@kindex C-x 4 a
-@findex add-change-log-entry-other-window
- The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
-file for the file you are editing
-(@code{add-change-log-entry-other-window}). If that file is actually
-a backup file, it makes an entry appropriate for the file's
-parent---that is useful for making log entries for functions that
-have been deleted in the current version.
-
- @kbd{C-x 4 a} visits the change log file and creates a new entry
-unless the most recent entry is for today's date and your name. It
-also creates a new item for the current file. For many languages, it
-can even guess the name of the function or other object that was
-changed.
-
-@vindex add-log-keep-changes-together
- When the variable @code{add-log-keep-changes-together} is
-non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
-rather than starting a new item.
-
-@vindex add-log-always-start-new-record
- If @code{add-log-always-start-new-record} is non-@code{nil},
-@kbd{C-x 4 a} always makes a new entry, even if the last entry
-was made by you and on the same date.
-
-@vindex change-log-version-info-enabled
-@vindex change-log-version-number-regexp-list
-@cindex file version in change log entries
- If the value of the variable @code{change-log-version-info-enabled}
-is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
-change log entry. It finds the version number by searching the first
-ten percent of the file, using regular expressions from the variable
-@code{change-log-version-number-regexp-list}.
-
-@cindex Change Log mode
-@findex change-log-mode
- The change log file is visited in Change Log mode. In this major
-mode, each bunch of grouped items counts as one paragraph, and each
-entry is considered a page. This facilitates editing the entries.
-@kbd{C-j} and auto-fill indent each new line like the previous line;
-this is convenient for entering the contents of an entry.
-
-@findex change-log-merge
- You can use the command @kbd{M-x change-log-merge} to merge other
-log files into a buffer in Change Log Mode, preserving the date
-ordering of entries.
-
- Version control systems are another way to keep track of changes in your
-program and keep a change log. @xref{Log Buffer}.
-
-@node Format of ChangeLog
-@section Format of ChangeLog
-
- A change log entry starts with a header line that contains the current
-date, your name, and your email address (taken from the variable
-@code{add-log-mailing-address}). Aside from these header lines, every
-line in the change log starts with a space or a tab. The bulk of the
-entry consists of @dfn{items}, each of which starts with a line starting
-with whitespace and a star. Here are two entries, both dated in May
-1993, with two items and one item respectively.
-
-@iftex
-@medbreak
-@end iftex
-@smallexample
-1993-05-25 Richard Stallman <rms@@gnu.org>
-
- * man.el: Rename symbols `man-*' to `Man-*'.
- (manual-entry): Make prompt string clearer.
-
- * simple.el (blink-matching-paren-distance):
- Change default to 12,000.
-
-1993-05-24 Richard Stallman <rms@@gnu.org>
-
- * vc.el (minor-mode-map-alist): Don't use it if it's void.
- (vc-cancel-version): Doc fix.
-@end smallexample
-
- One entry can describe several changes; each change should have its
-own item, or its own line in an item. Normally there should be a
-blank line between items. When items are related (parts of the same
-change, in different places), group them by leaving no blank line
-between them.
-
- You should put a copyright notice and permission notice at the
-end of the change log file. Here is an example:
-
-@smallexample
-Copyright 1997, 1998 Free Software Foundation, Inc.
-Copying and distribution of this file, with or without modification, are
-permitted provided the copyright notice and this notice are preserved.
-@end smallexample
-
-@noindent
-Of course, you should substitute the proper years and copyright holder.
-
-@node Tags
-@section Tags Tables
-@cindex tags table
-
- A @dfn{tags table} is a description of how a multi-file program is
-broken up into files. It lists the names of the component files and the
-names and positions of the functions (or other named subunits) in each
-file. Grouping the related files makes it possible to search or replace
-through all the files with one command. Recording the function names
-and positions makes possible the @kbd{M-.} command which finds the
-definition of a function by looking up which of the files it is in.
-
- Tags tables are stored in files called @dfn{tags table files}. The
-conventional name for a tags table file is @file{TAGS}.
-
- Each entry in the tags table records the name of one tag, the name of the
-file that the tag is defined in (implicitly), and the position in that
-file of the tag's definition. When a file parsed by @code{etags} is
-generated from a different source file, like a C file generated from a
-Cweb source file, the tags of the parsed file reference the source
-file.
-
- Just what names from the described files are recorded in the tags table
-depends on the programming language of the described file. They
-normally include all file names, functions and subroutines, and may
-also include global variables, data types, and anything else
-convenient. Each name recorded is called a @dfn{tag}.
-
-@cindex C++ class browser, tags
-@cindex tags, C++
-@cindex class browser, C++
-@cindex Ebrowse
- See also the Ebrowse facility, which is tailored for C++.
-@xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.
-
-@menu
-* Tag Syntax:: Tag syntax for various types of code and text files.
-* Create Tags Table:: Creating a tags table with @code{etags}.
-* Etags Regexps:: Create arbitrary tags using regular expressions.
-* Select Tags Table:: How to visit a tags table.
-* Find Tag:: Commands to find the definition of a specific tag.
-* Tags Search:: Using a tags table for searching and replacing.
-* List Tags:: Listing and finding tags defined in a file.
-@end menu
-
-@node Tag Syntax
-@subsection Source File Tag Syntax
-
- Here is how tag syntax is defined for the most popular languages:
-
-@itemize @bullet
-@item
-In C code, any C function or typedef is a tag, and so are definitions of
-@code{struct}, @code{union} and @code{enum}.
-@code{#define} macro definitions, @code{#undef} and @code{enum}
-constants are also
-tags, unless you specify @samp{--no-defines} when making the tags table.
-Similarly, global variables are tags, unless you specify
-@samp{--no-globals}, and so are struct members, unless you specify
-@samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines}
-and @samp{--no-members} can make the tags table file much smaller.
-
-You can tag function declarations and external variables in addition
-to function definitions by giving the @samp{--declarations} option to
-@code{etags}.
-
-@item
-In C++ code, in addition to all the tag constructs of C code, member
-functions are also recognized; member variables are also recognized,
-unless you use the @samp{--no-members} option. Tags for variables and
-functions in classes are named @samp{@var{class}::@var{variable}} and
-@samp{@var{class}::@var{function}}. @code{operator} definitions have
-tag names like @samp{operator+}.
-
-@item
-In Java code, tags include all the constructs recognized in C++, plus
-the @code{interface}, @code{extends} and @code{implements} constructs.
-Tags for variables and functions in classes are named
-@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
-
-@item
-In La@TeX{} text, the argument of any of the commands @code{\chapter},
-@code{\section}, @code{\subsection}, @code{\subsubsection},
-@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
-@code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
-@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
-@code{\newenvironment} or @code{\renewenvironment} is a tag.@refill
-
-Other commands can make tags as well, if you specify them in the
-environment variable @env{TEXTAGS} before invoking @code{etags}. The
-value of this environment variable should be a colon-separated list of
-command names. For example,
-
-@example
-TEXTAGS="mycommand:myothercommand"
-export TEXTAGS
-@end example
-
-@noindent
-specifies (using Bourne shell syntax) that the commands
-@samp{\mycommand} and @samp{\myothercommand} also define tags.
-
-@item
-In Lisp code, any function defined with @code{defun}, any variable
-defined with @code{defvar} or @code{defconst}, and in general the first
-argument of any expression that starts with @samp{(def} in column zero is
-a tag.
-
-@item
-In Scheme code, tags include anything defined with @code{def} or with a
-construct whose name starts with @samp{def}. They also include variables
-set with @code{set!} at top level in the file.
-@end itemize
-
- Several other languages are also supported:
-
-@itemize @bullet
-
-@item
-In Ada code, functions, procedures, packages, tasks and types are
-tags. Use the @samp{--packages-only} option to create tags for
-packages only.
-
-In Ada, the same name can be used for different kinds of entity
-(e.g.@:, for a procedure and for a function). Also, for things like
-packages, procedures and functions, there is the spec (i.e.@: the
-interface) and the body (i.e.@: the implementation). To make it
-easier to pick the definition you want, Ada tag name have suffixes
-indicating the type of entity:
-
-@table @samp
-@item /b
-package body.
-@item /f
-function.
-@item /k
-task.
-@item /p
-procedure.
-@item /s
-package spec.
-@item /t
-type.
-@end table
-
- Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
-directly to the body of the package @code{bidule}, while @kbd{M-x
-find-tag @key{RET} bidule @key{RET}} will just search for any tag
-@code{bidule}.
-
-@item
-In assembler code, labels appearing at the beginning of a line,
-followed by a colon, are tags.
-
-@item
-In Bison or Yacc input files, each rule defines as a tag the nonterminal
-it constructs. The portions of the file that contain C code are parsed
-as C code.
-
-@item
-In Cobol code, tags are paragraph names; that is, any word starting in
-column 8 and followed by a period.
-
-@item
-In Erlang code, the tags are the functions, records and macros defined
-in the file.
-
-@item
-In Fortran code, functions, subroutines and block data are tags.
-
-@item
-In HTML input files, the tags are the @code{title} and the @code{h1},
-@code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors
-and all occurrences of @code{id=}.
-
-@item
-In Lua input files, all functions are tags.
-
-@item
-In makefiles, targets are tags; additionally, variables are tags
-unless you specify @samp{--no-globals}.
-
-@item
-In Objective C code, tags include Objective C definitions for classes,
-class categories, methods and protocols. Tags for variables and
-functions in classes are named @samp{@var{class}::@var{variable}} and
-@samp{@var{class}::@var{function}}.
-
-@item
-In Pascal code, the tags are the functions and procedures defined in
-the file.
-
-@item
-In Perl code, the tags are the packages, subroutines and variables
-defined by the @code{package}, @code{sub}, @code{my} and @code{local}
-keywords. Use @samp{--globals} if you want to tag global variables.
-Tags for subroutines are named @samp{@var{package}::@var{sub}}. The
-name for subroutines defined in the default package is
-@samp{main::@var{sub}}.
-
-@item
-In PHP code, tags are functions, classes and defines. Vars are tags
-too, unless you use the @samp{--no-members} option.
-
-@item
-In PostScript code, the tags are the functions.
-
-@item
-In Prolog code, tags are predicates and rules at the beginning of
-line.
-
-@item
-In Python code, @code{def} or @code{class} at the beginning of a line
-generate a tag.
-@end itemize
-
- You can also generate tags based on regexp matching (@pxref{Etags
-Regexps}) to handle other formats and languages.
-
-@node Create Tags Table
-@subsection Creating Tags Tables
-@cindex @code{etags} program
-
- The @code{etags} program is used to create a tags table file. It knows
-the syntax of several languages, as described in
-@iftex
-the previous section.
-@end iftex
-@ifnottex
-@ref{Tag Syntax}.
-@end ifnottex
-Here is how to run @code{etags}:
-
-@example
-etags @var{inputfiles}@dots{}
-@end example
-
-@noindent
-The @code{etags} program reads the specified files, and writes a tags
-table named @file{TAGS} in the current working directory.
-
- If the specified files don't exist, @code{etags} looks for
-compressed versions of them and uncompresses them to read them. Under
-MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
-if it is given @samp{mycode.c} on the command line and @file{mycode.c}
-does not exist.
-
- @code{etags} recognizes the language used in an input file based on
-its file name and contents. You can specify the language with the
-@samp{--language=@var{name}} option, described below.
-
- If the tags table data become outdated due to changes in the files
-described in the table, the way to update the tags table is the same
-way it was made in the first place. If the tags table fails to record
-a tag, or records it for the wrong file, then Emacs cannot possibly
-find its definition until you update the tags table. However, if the
-position recorded in the tags table becomes a little bit wrong (due to
-other editing), the worst consequence is a slight delay in finding the
-tag. Even if the stored position is very far wrong, Emacs will still
-find the tag, after searching most of the file for it. That delay is
-hardly noticeable with today's computers.
-
- Thus, there is no need to update the tags table after each edit.
-You should update a tags table when you define new tags that you want
-to have listed, or when you move tag definitions from one file to
-another, or when changes become substantial.
-
- One tags table can virtually include another. Specify the included
-tags file name with the @samp{--include=@var{file}} option when
-creating the file that is to include it. The latter file then acts as
-if it covered all the source files specified in the included file, as
-well as the files it directly contains.
-
- If you specify the source files with relative file names when you run
-@code{etags}, the tags file will contain file names relative to the
-directory where the tags file was initially written. This way, you can
-move an entire directory tree containing both the tags file and the
-source files, and the tags file will still refer correctly to the source
-files. If the tags file is in @file{/dev}, however, the file names are
-made relative to the current working directory. This is useful, for
-example, when writing the tags to @file{/dev/stdout}.
-
- When using a relative file name, it should not be a symbolic link
-pointing to a tags file in a different directory, because this would
-generally render the file names invalid.
-
- If you specify absolute file names as arguments to @code{etags}, then
-the tags file will contain absolute file names. This way, the tags file
-will still refer to the same files even if you move it, as long as the
-source files remain in the same place. Absolute file names start with
-@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
-
- When you want to make a tags table from a great number of files, you
-may have problems listing them on the command line, because some systems
-have a limit on its length. The simplest way to circumvent this limit
-is to tell @code{etags} to read the file names from its standard input,
-by typing a dash in place of the file names, like this:
-
-@smallexample
-find . -name "*.[chCH]" -print | etags -
-@end smallexample
-
- Use the option @samp{--language=@var{name}} to specify the language
-explicitly. You can intermix these options with file names; each one
-applies to the file names that follow it. Specify
-@samp{--language=auto} to tell @code{etags} to resume guessing the
-language from the file names and file contents. Specify
-@samp{--language=none} to turn off language-specific processing
-entirely; then @code{etags} recognizes tags by regexp matching alone
-(@pxref{Etags Regexps}).
-
- The option @samp{--parse-stdin=@var{file}} is mostly useful when
-calling @code{etags} from programs. It can be used (only once) in
-place of a file name on the command line. @code{Etags} will read from
-standard input and mark the produced tags as belonging to the file
-@var{file}.
-
- @samp{etags --help} outputs the list of the languages @code{etags}
-knows, and the file name rules for guessing the language. It also prints
-a list of all the available @code{etags} options, together with a short
-explanation. If followed by one or more @samp{--language=@var{lang}}
-options, it outputs detailed information about how tags are generated for
-@var{lang}.
-
-@node Etags Regexps
-@subsection Etags Regexps
-
- The @samp{--regex} option provides a general way of recognizing tags
-based on regexp matching. You can freely intermix this option with
-file names, and each one applies to the source files that follow it.
-If you specify multiple @samp{--regex} options, all of them are used
-in parallel. The syntax is:
-
-@smallexample
---regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
-@end smallexample
-
- The essential part of the option value is @var{tagregexp}, the
-regexp for matching tags. It is always used anchored, that is, it
-only matches at the beginning of a line. If you want to allow
-indented tags, use a regexp that matches initial whitespace; start it
-with @samp{[ \t]*}.
-
- In these regular expressions, @samp{\} quotes the next character, and
-all the GCC character escape sequences are supported (@samp{\a} for
-bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
-escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
-carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).
-
- Ideally, @var{tagregexp} should not match more characters than are
-needed to recognize what you want to tag. If the syntax requires you
-to write @var{tagregexp} so it matches more characters beyond the tag
-itself, you should add a @var{nameregexp}, to pick out just the tag.
-This will enable Emacs to find tags more accurately and to do
-completion on tag names more reliably. You can find some examples
-below.
-
- The @var{modifiers} are a sequence of zero or more characters that
-modify the way @code{etags} does the matching. A regexp with no
-modifiers is applied sequentially to each line of the input file, in a
-case-sensitive way. The modifiers and their meanings are:
-
-@table @samp
-@item i
-Ignore case when matching this regexp.
-@item m
-Match this regular expression against the whole file, so that
-multi-line matches are possible.
-@item s
-Match this regular expression against the whole file, and allow
-@samp{.} in @var{tagregexp} to match newlines.
-@end table
-
- The @samp{-R} option cancels all the regexps defined by preceding
-@samp{--regex} options. It too applies to the file names following
-it. Here's an example:
-
-@smallexample
-etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
- bar.ber -R --lang=lisp los.er
-@end smallexample
-
-@noindent
-Here @code{etags} chooses the parsing language for @file{voo.doo} and
-@file{bar.ber} according to their contents. @code{etags} also uses
-@var{reg1} to recognize additional tags in @file{voo.doo}, and both
-@var{reg1} and @var{reg2} to recognize additional tags in
-@file{bar.ber}. @var{reg1} is checked against each line of
-@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
-@var{reg2} is checked against the whole @file{bar.ber} file,
-permitting multi-line matches, in a case-sensitive way. @code{etags}
-uses only the Lisp tags rules, with no user-specified regexp matching,
-to recognize tags in @file{los.er}.
-
- You can restrict a @samp{--regex} option to match only files of a
-given language by using the optional prefix @var{@{language@}}.
-(@samp{etags --help} prints the list of languages recognized by
-@code{etags}.) This is particularly useful when storing many
-predefined regular expressions for @code{etags} in a file. The
-following example tags the @code{DEFVAR} macros in the Emacs source
-files, for the C language only:
-
-@smallexample
---regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
-@end smallexample
-
-@noindent
-When you have complex regular expressions, you can store the list of
-them in a file. The following option syntax instructs @code{etags} to
-read two files of regular expressions. The regular expressions
-contained in the second file are matched without regard to case.
-
-@smallexample
---regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
-@end smallexample
-
-@noindent
-A regex file for @code{etags} contains one regular expression per
-line. Empty lines, and lines beginning with space or tab are ignored.
-When the first character in a line is @samp{@@}, @code{etags} assumes
-that the rest of the line is the name of another file of regular
-expressions; thus, one such file can include another file. All the
-other lines are taken to be regular expressions. If the first
-non-whitespace text on the line is @samp{--}, that line is a comment.
-
- For example, we can create a file called @samp{emacs.tags} with the
-following contents:
-
-@smallexample
- -- This is for GNU Emacs C source files
-@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
-@end smallexample
-
-@noindent
-and then use it like this:
-
-@smallexample
-etags --regex=@@emacs.tags *.[ch] */*.[ch]
-@end smallexample
-
- Here are some more examples. The regexps are quoted to protect them
-from shell interpretation.
-
-@itemize @bullet
-
-@item
-Tag Octave files:
-
-@smallexample
-etags --language=none \
- --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
- --regex='/###key \(.*\)/\1/' \
- --regex='/[ \t]*global[ \t].*/' \
- *.m
-@end smallexample
-
-@noindent
-Note that tags are not generated for scripts, so that you have to add
-a line by yourself of the form @samp{###key @var{scriptname}} if you
-want to jump to it.
-
-@item
-Tag Tcl files:
-
-@smallexample
-etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
-@end smallexample
-
-@item
-Tag VHDL files:
-
-@smallexample
-etags --language=none \
- --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
- --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
- \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
-@end smallexample
-@end itemize
-
-@node Select Tags Table
-@subsection Selecting a Tags Table
-
-@vindex tags-file-name
-@findex visit-tags-table
- Emacs has at any time one @dfn{selected} tags table, and all the
-commands for working with tags tables use the selected one. To select
-a tags table, type @kbd{M-x visit-tags-table}, which reads the tags
-table file name as an argument, with @file{TAGS} in the default
-directory as the default.
-
- Emacs does not actually read in the tags table contents until you
-try to use them; all @code{visit-tags-table} does is store the file
-name in the variable @code{tags-file-name}, and setting the variable
-yourself is just as good. The variable's initial value is @code{nil};
-that value tells all the commands for working with tags tables that
-they must ask for a tags table file name to use.
-
- Using @code{visit-tags-table} when a tags table is already loaded
-gives you a choice: you can add the new tags table to the current list
-of tags tables, or start a new list. The tags commands use all the tags
-tables in the current list. If you start a new list, the new tags table
-is used @emph{instead} of others. If you add the new table to the
-current list, it is used @emph{as well as} the others.
-
-@vindex tags-table-list
- You can specify a precise list of tags tables by setting the variable
-@code{tags-table-list} to a list of strings, like this:
-
-@c keep this on two lines for formatting in smallbook
-@example
-@group
-(setq tags-table-list
- '("~/emacs" "/usr/local/lib/emacs/src"))
-@end group
-@end example
-
-@noindent
-This tells the tags commands to look at the @file{TAGS} files in your
-@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
-directory. The order depends on which file you are in and which tags
-table mentions that file, as explained above.
-
- Do not set both @code{tags-file-name} and @code{tags-table-list}.
-
-@node Find Tag
-@subsection Finding a Tag
-
- The most important thing that a tags table enables you to do is to find
-the definition of a specific tag.
-
-@table @kbd
-@item M-.@: @var{tag} @key{RET}
-Find first definition of @var{tag} (@code{find-tag}).
-@item C-u M-.
-Find next alternate definition of last tag specified.
-@item C-u - M-.
-Go back to previous tag found.
-@item C-M-. @var{pattern} @key{RET}
-Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
-@item C-u C-M-.
-Find the next tag whose name matches the last pattern used.
-@item C-x 4 .@: @var{tag} @key{RET}
-Find first definition of @var{tag}, but display it in another window
-(@code{find-tag-other-window}).
-@item C-x 5 .@: @var{tag} @key{RET}
-Find first definition of @var{tag}, and create a new frame to select the
-buffer (@code{find-tag-other-frame}).
-@item M-*
-Pop back to where you previously invoked @kbd{M-.} and friends.
-@end table
-
-@kindex M-.
-@findex find-tag
- @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
-a specified tag. It searches through the tags table for that tag, as a
-string, and then uses the tags table info to determine the file that the
-definition is in and the approximate character position in the file of
-the definition. Then @code{find-tag} visits that file, moves point to
-the approximate character position, and searches ever-increasing
-distances away to find the tag definition.
-
- If an empty argument is given (just type @key{RET}), the balanced
-expression in the buffer before or around point is used as the
-@var{tag} argument. @xref{Expressions}.
-
- You don't need to give @kbd{M-.} the full name of the tag; a part
-will do. This is because @kbd{M-.} finds tags in the table which
-contain @var{tag} as a substring. However, it prefers an exact match
-to a substring match. To find other tags that match the same
-substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
-M-.}; this does not read a tag name, but continues searching the tags
-table's text for another tag containing the same substring last used.
-If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
-alternative to @kbd{C-u M-.}.
-
-@kindex C-x 4 .
-@findex find-tag-other-window
-@kindex C-x 5 .
-@findex find-tag-other-frame
- Like most commands that can switch buffers, @code{find-tag} has a
-variant that displays the new buffer in another window, and one that
-makes a new frame for it. The former is @w{@kbd{C-x 4 .}}, which invokes
-the command @code{find-tag-other-window}. The latter is @w{@kbd{C-x 5 .}},
-which invokes @code{find-tag-other-frame}.
-
- To move back to places you've found tags recently, use @kbd{C-u -
-M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
-command can take you to another buffer. @w{@kbd{C-x 4 .}} with a negative
-argument finds the previous tag location in another window.
-
-@kindex M-*
-@findex pop-tag-mark
-@vindex find-tag-marker-ring-length
- As well as going back to places you've found tags recently, you can go
-back to places @emph{from where} you found them. Use @kbd{M-*}, which
-invokes the command @code{pop-tag-mark}, for this. Typically you would
-find and study the definition of something with @kbd{M-.} and then
-return to where you were with @kbd{M-*}.
-
- Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
-a depth determined by the variable @code{find-tag-marker-ring-length}.
-
-@findex find-tag-regexp
-@kindex C-M-.
- The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
-match a specified regular expression. It is just like @kbd{M-.} except
-that it does regexp matching instead of substring matching.
-
-@node Tags Search
-@subsection Searching and Replacing with Tags Tables
-@cindex search and replace in multiple files
-@cindex multiple-file search and replace
-
- The commands in this section visit and search all the files listed
-in the selected tags table, one by one. For these commands, the tags
-table serves only to specify a sequence of files to search. These
-commands scan the list of tags tables starting with the first tags
-table (if any) that describes the current file, proceed from there to
-the end of the list, and then scan from the beginning of the list
-until they have covered all the tables in the list.
-
-@table @kbd
-@item M-x tags-search @key{RET} @var{regexp} @key{RET}
-Search for @var{regexp} through the files in the selected tags
-table.
-@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
-Perform a @code{query-replace-regexp} on each file in the selected tags table.
-@item M-,
-Restart one of the commands above, from the current location of point
-(@code{tags-loop-continue}).
-@end table
-
-@findex tags-search
- @kbd{M-x tags-search} reads a regexp using the minibuffer, then
-searches for matches in all the files in the selected tags table, one
-file at a time. It displays the name of the file being searched so you
-can follow its progress. As soon as it finds an occurrence,
-@code{tags-search} returns.
-
-@kindex M-,
-@findex tags-loop-continue
- Having found one match, you probably want to find all the rest. To find
-one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
-@code{tags-search}. This searches the rest of the current buffer, followed
-by the remaining files of the tags table.@refill
-
-@findex tags-query-replace
- @kbd{M-x tags-query-replace} performs a single
-@code{query-replace-regexp} through all the files in the tags table. It
-reads a regexp to search for and a string to replace with, just like
-ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
-tags-search}, but repeatedly, processing matches according to your
-input. @xref{Replace}, for more information on query replace.
-
-@vindex tags-case-fold-search
-@cindex case-sensitivity and tags search
- You can control the case-sensitivity of tags search commands by
-customizing the value of the variable @code{tags-case-fold-search}. The
-default is to use the same setting as the value of
-@code{case-fold-search} (@pxref{Search Case}).
-
- It is possible to get through all the files in the tags table with a
-single invocation of @kbd{M-x tags-query-replace}. But often it is
-useful to exit temporarily, which you can do with any input event that
-has no special query replace meaning. You can resume the query replace
-subsequently by typing @kbd{M-,}; this command resumes the last tags
-search or replace command that you did.
-
- The commands in this section carry out much broader searches than the
-@code{find-tag} family. The @code{find-tag} commands search only for
-definitions of tags that match your substring or regexp. The commands
-@code{tags-search} and @code{tags-query-replace} find every occurrence
-of the regexp, as ordinary search commands and replace commands do in
-the current buffer.
-
- These commands create buffers only temporarily for the files that they
-have to search (those which are not already visited in Emacs buffers).
-Buffers in which no match is found are quickly killed; the others
-continue to exist.
-
- It may have struck you that @code{tags-search} is a lot like
-@code{grep}. You can also run @code{grep} itself as an inferior of
-Emacs and have Emacs show you the matching lines one by one.
-@xref{Grep Searching}.
-
-@node List Tags
-@subsection Tags Table Inquiries
-
-@table @kbd
-@item M-x list-tags @key{RET} @var{file} @key{RET}
-Display a list of the tags defined in the program file @var{file}.
-@item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
-Display a list of all tags matching @var{regexp}.
-@end table
-
-@findex list-tags
- @kbd{M-x list-tags} reads the name of one of the files described by
-the selected tags table, and displays a list of all the tags defined in
-that file. The ``file name'' argument is really just a string to
-compare against the file names recorded in the tags table; it is read as
-a string rather than as a file name. Therefore, completion and
-defaulting are not available, and you must enter the file name the same
-way it appears in the tags table. Do not include a directory as part of
-the file name unless the file name recorded in the tags table includes a
-directory.
-
-@findex tags-apropos
-@vindex tags-apropos-verbose
- @kbd{M-x tags-apropos} is like @code{apropos} for tags
-(@pxref{Apropos}). It finds all the tags in the selected tags table
-whose entries match @var{regexp}, and displays them. If the variable
-@code{tags-apropos-verbose} is non-@code{nil}, it displays the names
-of the tags files together with the tag names.
-
-@vindex tags-tag-face
-@vindex tags-apropos-additional-actions
- You can customize the appearance of the output by setting the
-variable @code{tags-tag-face} to a face. You can display additional
-output with @kbd{M-x tags-apropos} by customizing the variable
-@code{tags-apropos-additional-actions}---see its documentation for
-details.
-
- You can also use the collection of tag names to complete a symbol
-name in the buffer. @xref{Symbol Completion}.
-
-@ifnottex
-@include emerge-xtra.texi
-@end ifnottex
-
-@ignore
- arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Major Modes, Indentation, International, Top
-@chapter Major Modes
-@cindex major modes
-@cindex mode, major
-@kindex TAB @r{(and major modes)}
-@kindex DEL @r{(and major modes)}
-@kindex C-j @r{(and major modes)}
-
- Emacs provides many alternative @dfn{major modes}, each of which
-customizes Emacs for editing text of a particular sort. The major modes
-are mutually exclusive, and each buffer has one major mode at any time.
-The mode line normally shows the name of the current major mode, in
-parentheses (@pxref{Mode Line}).
-
- The least specialized major mode is called @dfn{Fundamental mode}.
-This mode has no mode-specific redefinitions or variable settings, so
-that each Emacs command behaves in its most general manner, and each
-user option variable is in its default state. For editing text of a
-specific type that Emacs knows about, such as Lisp code or English
-text, you should switch to the appropriate major mode, such as Lisp
-mode or Text mode.
-
- Selecting a major mode changes the meanings of a few keys to become
-more specifically adapted to the language being edited. The ones that
-are changed frequently are @key{TAB}, @key{DEL}, and @kbd{C-j}. The
-prefix key @kbd{C-c} normally contains mode-specific commands. In
-addition, the commands which handle comments use the mode to determine
-how comments are to be delimited. Many major modes redefine the
-syntactical properties of characters appearing in the buffer.
-@xref{Syntax}.
-
- The major modes fall into three major groups. The first group
-contains modes for normal text, either plain or with mark-up. It
-includes Text mode, HTML mode, SGML mode, @TeX{} mode and Outline
-mode. The second group contains modes for specific programming
-languages. These include Lisp mode (which has several variants), C
-mode, Fortran mode, and others. The remaining major modes are not
-intended for use on users' files; they are used in buffers created for
-specific purposes by Emacs, such as Dired mode for buffers made by
-Dired (@pxref{Dired}), Mail mode for buffers made by @kbd{C-x m}
-(@pxref{Sending Mail}), and Shell mode for buffers used for
-communicating with an inferior shell process (@pxref{Interactive
-Shell}).
-
- Most programming-language major modes specify that only blank lines
-separate paragraphs. This is to make the paragraph commands useful.
-(@xref{Paragraphs}.) They also cause Auto Fill mode to use the
-definition of @key{TAB} to indent the new lines it creates. This is
-because most lines in a program are usually indented
-(@pxref{Indentation}).
-
-@menu
-* Choosing Modes:: How major modes are specified or chosen.
-@end menu
-
-@node Choosing Modes,,Major Modes,Major Modes
-@section How Major Modes are Chosen
-
-@cindex choosing a major mode
- You can select a major mode explicitly for the current buffer, but
-most of the time Emacs determines which mode to use based on the file
-name or on special text in the file.
-
- To explicitly select a new major, you use an @kbd{M-x} command.
-Take the name of a major mode and add @code{-mode} to get the name of
-the command to select that mode. Thus, you can enter Lisp mode by
-executing @kbd{M-x lisp-mode}.
-
-@vindex auto-mode-alist
- When you visit a file, Emacs usually chooses the right major mode based
-on the file's name. For example, files whose names end in @samp{.c} are
-edited in C mode. The correspondence between file names and major modes is
-controlled by the variable @code{auto-mode-alist}. Its value is a list in
-which each element has this form,
-
-@example
-(@var{regexp} . @var{mode-function})
-@end example
-
-@noindent
-or this form,
-
-@example
-(@var{regexp} @var{mode-function} @var{flag})
-@end example
-
-@noindent
-For example, one element normally found in the list has the form
-@code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C
-mode for files whose names end in @file{.c}. (Note that @samp{\\} is
-needed in Lisp syntax to include a @samp{\} in the string, which must
-be used to suppress the special meaning of @samp{.} in regexps.) If
-the element has the form @code{(@var{regexp} @var{mode-function}
-@var{flag})} and @var{flag} is non-@code{nil}, then after calling
-@var{mode-function}, Emacs discards the suffix that matched
-@var{regexp} and searches the list again for another match.
-
-@vindex magic-mode-alist
- Sometimes the major mode is determined from the way the file's text
-begins. The variable @code{magic-mode-alist} controls this. Its value
-is a list of elements of these forms:
-
-@example
-(@var{regexp} . @var{mode-function})
-(@var{match-function} . @var{mode-function})
-@end example
-
-@noindent
-The first form looks like an element of @code{auto-mode-alist}, but it
-doesn't work the same: this @var{regexp} is matched against the text
-at the start of the buffer, not against the file name. Likewise, the
-second form calls @var{match-function} at the beginning of the buffer,
-and if the function returns non-@code{nil}, the @var{mode-function} is
-called. @code{magic-mode-alist} takes priority over
-@code{auto-mode-alist}.
-
- You can specify the major mode to use for editing a certain file by
-special text in the first nonblank line of the file. The
-mode name should appear in this line both preceded and followed by
-@samp{-*-}. Other text may appear on the line as well. For example,
-
-@example
-;-*-Lisp-*-
-@end example
-
-@noindent
-tells Emacs to use Lisp mode. Such an explicit specification overrides
-any defaults based on the file name. Note how the semicolon is used
-to make Lisp treat this line as a comment.
-
- Another format of mode specification is
-
-@example
--*- mode: @var{modename};-*-
-@end example
-
-@noindent
-which allows you to specify local variables as well, like this:
-
-@example
--*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
-@end example
-
-@noindent
-@xref{File Variables}, for more information about this.
-
-@vindex auto-mode-case-fold
- On systems with case-insensitive file names, only a single
-case-insensitive search through the @code{auto-mode-alist} is made.
-On other systems, Emacs normally performs a single case-sensitive
-search through the alist, but if you set this variable to a
-non-@code{nil} value, Emacs will perform a second case-insensitive
-search if the first search fails.
-
-@vindex interpreter-mode-alist
- When a file's contents begin with @samp{#!}, it can serve as an
-executable shell command, which works by running an interpreter named on
-the file's first line. The rest of the file is used as input to the
-interpreter.
-
- When you visit such a file in Emacs, if the file's name does not
-specify a major mode, Emacs uses the interpreter name on the first line
-to choose a mode. If the first line is the name of a recognized
-interpreter program, such as @samp{perl} or @samp{tcl}, Emacs uses a
-mode appropriate for programs for that interpreter. The variable
-@code{interpreter-mode-alist} specifies the correspondence between
-interpreter program names and major modes.
-
- When the first line starts with @samp{#!}, you cannot (on many
-systems) use the @samp{-*-} feature on the first line, because the
-system would get confused when running the interpreter. So Emacs looks
-for @samp{-*-} on the second line in such files as well as on the
-first line.
-
-@vindex default-major-mode
- When you visit a file that does not specify a major mode to use, or
-when you create a new buffer with @kbd{C-x b}, the variable
-@code{default-major-mode} specifies which major mode to use. Normally
-its value is the symbol @code{fundamental-mode}, which specifies
-Fundamental mode. If @code{default-major-mode} is @code{nil}, the major
-mode is taken from the previously current buffer.
-
-@findex normal-mode
- If you change the major mode of a buffer, you can go back to the major
-mode Emacs would choose automatically: use the command @kbd{M-x
-normal-mode} to do this. This is the same function that
-@code{find-file} calls to choose the major mode. It also processes
-the file's @samp{-*-} line or local variables list (if any).
-@xref{File Variables}.
-
-@vindex change-major-mode-with-file-name
- The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to
-a new major mode if the new file name implies a mode (@pxref{Saving}).
-(@kbd{C-x C-s} does this too, if the buffer wasn't visiting a file.)
-However, this does not happen if the buffer contents specify a major
-mode, and certain ``special'' major modes do not allow the mode to
-change. You can turn off this mode-changing feature by setting
-@code{change-major-mode-with-file-name} to @code{nil}.
-
-@ignore
- arch-tag: f2558800-cf32-4839-8acb-7d3b4df2a155
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Mark, Killing, Help, Top
-@chapter The Mark and the Region
-@cindex mark
-@cindex setting a mark
-@cindex region
-
- Many Emacs commands operate on an arbitrary contiguous part of the
-current buffer. To specify the text for such a command to operate on,
-you set @dfn{the mark} at one end of it, and move point to the other
-end. The text between point and the mark is called @dfn{the region}.
-Emacs highlights the region whenever there is one, if you enable
-Transient Mark mode (@pxref{Transient Mark}).
-
- Certain Emacs commands set the mark; other editing commands do not
-affect it, so the mark remains where you set it last. Each Emacs
-buffer has its own mark, and setting the mark in one buffer has no
-effect on other buffers' marks. When you return to a buffer that was
-current earlier, its mark is at the same place as before.
-
- The ends of the region are always point and the mark. It doesn't
-matter which of them was put in its current place first, or which one
-comes earlier in the text---the region starts from point or the mark
-(whichever comes first), and ends at point or the mark (whichever
-comes last). Every time you move point, or set the mark in a new
-place, the region changes.
-
- Many commands that insert text, such as @kbd{C-y} (@code{yank}) and
-@kbd{M-x insert-buffer}, position point and the mark at opposite ends
-of the inserted text, so that the region consists of the text just
-inserted.
-
- Aside from delimiting the region, the mark is also useful for
-remembering a spot that you may want to go back to. To make this
-feature more useful, each buffer remembers 16 previous locations of the
-mark in the @dfn{mark ring}.
-
-@menu
-* Setting Mark:: Commands to set the mark.
-* Transient Mark:: How to make Emacs highlight the region--
- when there is one.
-* Momentary Mark:: Enabling Transient Mark mode momentarily.
-* Using Region:: Summary of ways to operate on contents of the region.
-* Marking Objects:: Commands to put region around textual units.
-* Mark Ring:: Previous mark positions saved so you can go back there.
-* Global Mark Ring:: Previous mark positions in various buffers.
-@end menu
-
-@node Setting Mark
-@section Setting the Mark
-
- Here are some commands for setting the mark:
-
-@table @kbd
-@item C-@key{SPC}
-Set the mark where point is (@code{set-mark-command}).
-@item C-@@
-The same.
-@item C-x C-x
-Interchange mark and point (@code{exchange-point-and-mark}).
-@item Drag-Mouse-1
-Set point and the mark around the text you drag across.
-@item Mouse-3
-Set the mark where point is, then move point to where you click
-(@code{mouse-save-then-kill}).
-@end table
-
- For example, suppose you wish to convert part of the buffer to
-upper case, using the @kbd{C-x C-u} (@code{upcase-region}) command,
-which operates on the text in the region. You can first go to the
-beginning of the text to be capitalized, type @kbd{C-@key{SPC}} to put
-the mark there, move to the end, and then type @kbd{C-x C-u}. Or, you
-can set the mark at the end of the text, move to the beginning, and then
-type @kbd{C-x C-u}.
-
-@kindex C-SPC
-@findex set-mark-command
- The most common way to set the mark is with the @kbd{C-@key{SPC}} command
-(@code{set-mark-command}). This sets the mark where point is. Then you
-can move point away, leaving the mark behind.
-
- There are two ways to set the mark with the mouse. You can drag mouse
-button one across a range of text; that puts point where you release the
-mouse button, and sets the mark at the other end of that range. Or you
-can click mouse button three, which sets the mark at point (like
-@kbd{C-@key{SPC}}) and then moves point where you clicked (like
-@kbd{Mouse-1}).
-
- Using the mouse to mark a region copies the region into the kill
-ring in addition to setting the mark; that gives behavior consistent
-with other window-driven applications. If you don't want to modify
-the kill ring, you must use keyboard commands to set the mark.
-@xref{Mouse Commands}.
-
-@kindex C-x C-x
-@findex exchange-point-and-mark
- When Emacs was developed, terminals had only one cursor, so Emacs
-does not show where the mark is located--you have to remember. If you
-enable Transient Mark mode (see below), then the region is highlighted
-when it is active; you can tell mark is at the other end of the
-highlighted region. But this only applies when the mark is active.
-
- The usual solution to this problem is to set the mark and then use
-it soon, before you forget where it is. Alternatively, you can see
-where the mark is with the command @kbd{C-x C-x}
-(@code{exchange-point-and-mark}) which puts the mark where point was
-and point where the mark was. The extent of the region is unchanged,
-but the cursor and point are now at the previous position of the mark.
-In Transient Mark mode, this command also reactivates the mark.
-
- @kbd{C-x C-x} is also useful when you are satisfied with the position
-of point but want to move the other end of the region (where the mark
-is); do @kbd{C-x C-x} to put point at that end of the region, and then
-move it. Using @kbd{C-x C-x} a second time, if necessary, puts the mark at
-the new position with point back at its original position.
-
- For more facilities that allow you to go to previously set marks, see
-@ref{Mark Ring}.
-
-@kindex C-@@
- There is no such character as @kbd{C-@key{SPC}} in @acronym{ASCII};
-when you type @key{SPC} while holding down @key{CTRL} on a text
-terminal, what you get is the character @kbd{C-@@}. This key is also
-bound to @code{set-mark-command}--so unless you are unlucky enough to
-have a text terminal where typing @kbd{C-@key{SPC}} does not produce
-@kbd{C-@@}, you might as well think of this character as
-@kbd{C-@key{SPC}}.
-
-@node Transient Mark
-@section Transient Mark Mode
-@cindex mode, Transient Mark
-@cindex Transient Mark mode
-@cindex highlighting region
-@cindex region highlighting
-
- On a terminal that supports colors, Emacs has the ability to
-highlight the current region. But normally it does not. Why not?
-
- In the normal mode of use, every command that sets the mark also
-activates it, and nothing ever deactivates it. Thus, once you have
-set the mark in a buffer, there is @emph{always} a region in that
-buffer. Highlighting the region all the time would be a nuisance. So
-normally Emacs highlights the region only immediately after you have
-selected one with the mouse.
-
- If you want region highlighting, you can use Transient Mark mode.
-This is a more rigid mode of operation in which the region ``lasts''
-only until you use it; operating on the region text deactivates the
-mark, so there is no region any more. Therefore, you must explicitly
-set up a region for each command that uses one.
-
- When Transient Mark mode is enabled, Emacs highlights the region,
-whenever there is a region. In Transient Mark mode, most of the time
-there is no region; therefore, highlighting the region when it exists
-is useful and not annoying.
-
-@findex transient-mark-mode
- To enable Transient Mark mode, type @kbd{M-x transient-mark-mode}.
-This command toggles the mode; you can use the same command to turn
-the mode off again.
-
- Here are the details of Transient Mark mode:
-
-@itemize @bullet
-@item
-To set the mark, type @kbd{C-@key{SPC}} (@code{set-mark-command}).
-This makes the mark active and thus begins highlighting of the region.
-As you move point, you will see the highlighted region grow and
-shrink.
-
-@item
-The mouse commands for specifying the mark also make it active. So do
-keyboard commands whose purpose is to specify a region, including
-@kbd{M-@@}, @kbd{C-M-@@}, @kbd{M-h}, @kbd{C-M-h}, @kbd{C-x C-p}, and
-@kbd{C-x h}.
-
-@item
-You can tell that the mark is active because the region is highlighted.
-
-@item
-When the mark is active, you can execute commands that operate on the
-region, such as killing, indenting, or writing to a file.
-
-@item
-Any change to the buffer, such as inserting or deleting a character,
-deactivates the mark. This means any subsequent command that operates
-on a region will get an error and refuse to operate. You can make the
-region active again by typing @kbd{C-x C-x}.
-
-@item
-If Delete Selection mode is also enabled, some commands delete the
-region when used while the mark is active. @xref{Mouse Commands}.
-
-@item
-Quitting with @kbd{C-g} deactivates the mark.
-
-@item
-Commands like @kbd{M->} and @kbd{C-s}, that ``leave the mark behind'' in
-addition to some other primary purpose, do not activate the new mark.
-You can activate the new region by executing @kbd{C-x C-x}
-(@code{exchange-point-and-mark}).
-
-@item
-Commands that normally set the mark before moving long distances (like
-@kbd{M-<} and @kbd{C-s}) do not alter the mark in Transient Mark mode
-when the mark is active.
-
-@item
-Some commands operate on the region if a region is active. For
-instance, @kbd{C-x u} in Transient Mark mode operates on the region,
-when there is a region. (Outside Transient Mark mode, you must type
-@kbd{C-u C-x u} if you want it to operate on the region.)
-@xref{Undo}. Other commands that act this way are identified in their
-own documentation.
-@end itemize
-
- The highlighting of the region uses the @code{region} face; you can
-customize the appearance of the highlighted region by changing this
-face. @xref{Face Customization}.
-
-@vindex highlight-nonselected-windows
- When multiple windows show the same buffer, they can have different
-regions, because they can have different values of point (though they
-all share one common mark position). Ordinarily, only the selected
-window highlights its region (@pxref{Windows}). However, if the
-variable @code{highlight-nonselected-windows} is non-@code{nil}, then
-each window highlights its own region (provided that Transient Mark mode
-is enabled and the mark in the window's buffer is active).
-
-@vindex mark-even-if-inactive
- If the variable @code{mark-even-if-inactive} is non-@code{nil} in
-Transient Mark mode, then commands can use the mark and the region
-even when it is inactive. Region highlighting appears and disappears
-just as it normally does in Transient Mark mode, but the mark doesn't
-really go away when the highlighting disappears, so you can still use
-region commands.
-
-@cindex Zmacs mode
- Transient Mark mode is also sometimes known as ``Zmacs mode''
-because the Zmacs editor on the MIT Lisp Machine handled the mark in a
-similar way.
-
-@node Momentary Mark
-@section Using Transient Mark Mode Momentarily
-
- If you don't like Transient Mark mode in general, you might still
-want to use it once in a while. To do this, type @kbd{C-@key{SPC}
-C-@key{SPC}} or @kbd{C-u C-x C-x}. These commands set or activate the
-mark, and enable Transient Mark mode only until the mark is
-deactivated.
-
-@table @kbd
-@item C-@key{SPC} C-@key{SPC}
-@kindex C-@key{SPC} C-@key{SPC}
-Set the mark at point (like plain @kbd{C-@key{SPC}}), and enable
-Transient Mark mode just once until the mark is deactivated. (This is
-not really a separate command; you are using the @kbd{C-@key{SPC}}
-command twice.)
-
-@item C-u C-x C-x
-@kindex C-u C-x C-x
-Activate the mark without changing it; enable Transient Mark mode just
-once, until the mark is deactivated. (This is the @kbd{C-x C-x}
-command, @code{exchange-point-and-mark}, with a prefix argument.)
-@end table
-
- One of the secondary features of Transient Mark mode is that certain
-commands operate only on the region, when there is an active region.
-If you don't use Transient Mark mode, the region once set never
-becomes inactive, so there is no way for these commands to make such a
-distinction. Enabling Transient Mark mode momentarily gives you a way
-to use these commands on the region.
-
- Momentary use of Transient Mark mode is also a way to highlight the
-region for the time being.
-
-@node Using Region
-@section Operating on the Region
-
-@cindex operations on a marked region
- Once you have a region and the mark is active, here are some of the
-ways you can operate on the region:
-
-@itemize @bullet
-@item
-Kill it with @kbd{C-w} (@pxref{Killing}).
-@item
-Save it in a register with @kbd{C-x r s} (@pxref{Registers}).
-@item
-Save it in a buffer or a file (@pxref{Accumulating Text}).
-@item
-Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} (@pxref{Case}).
-@item
-Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}).
-@item
-Fill it as text with @kbd{M-x fill-region} (@pxref{Filling}).
-@item
-Print hardcopy with @kbd{M-x print-region} (@pxref{Printing}).
-@item
-Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}).
-@item
-Undo changes within it using @kbd{C-u C-x u} (@pxref{Undo}).
-@end itemize
-
- Most commands that operate on the text in the region have the word
-@code{region} in their names.
-
-@node Marking Objects
-@section Commands to Mark Textual Objects
-
-@cindex marking sections of text
- Here are the commands for placing point and the mark around a textual
-object such as a word, list, paragraph or page.
-
-@table @kbd
-@item M-@@
-Set mark after end of next word (@code{mark-word}). This command and
-the following one do not move point.
-@item C-M-@@
-Set mark after end of following balanced expression (@code{mark-sexp}).
-@item M-h
-Put region around current paragraph (@code{mark-paragraph}).
-@item C-M-h
-Put region around current defun (@code{mark-defun}).
-@item C-x h
-Put region around the entire buffer (@code{mark-whole-buffer}).
-@item C-x C-p
-Put region around current page (@code{mark-page}).
-@end table
-
-@kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next
-word, while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the
-next balanced expression (@pxref{Expressions}). These commands handle
-arguments just like @kbd{M-f} and @kbd{C-M-f}. Repeating these
-commands extends the region. For example, you can type either
-@kbd{C-u 2 M-@@} or @kbd{M-@@ M-@@} to mark the next two words. These
-commands also extend the region in Transient Mark mode, regardless of
-the last command.
-
-@kindex C-x h
-@findex mark-whole-buffer
- Other commands set both point and mark, to delimit an object in the
-buffer. For example, @kbd{M-h} (@code{mark-paragraph}) moves point to
-the beginning of the paragraph that surrounds or follows point, and
-puts the mark at the end of that paragraph (@pxref{Paragraphs}). It
-prepares the region so you can indent, case-convert, or kill a whole
-paragraph. With a prefix argument, if the argument's value is positive,
-@kbd{M-h} marks that many paragraphs starting with the one surrounding
-point. If the prefix argument is @minus{}@var{n}, @kbd{M-h} also
-marks @var{n} paragraphs, running back form the one surrounding point.
-In that last case, point moves forward to the end of that paragraph,
-and the mark goes at the start of the region. Repeating the @kbd{M-h}
-command extends the region to subsequent paragraphs.
-
- @kbd{C-M-h} (@code{mark-defun}) similarly puts point before, and the
-mark after, the current (or following) major top-level definition, or
-defun (@pxref{Moving by Defuns}). Repeating @kbd{C-M-h} extends
-the region to subsequent defuns.
-
- @kbd{C-x C-p} (@code{mark-page}) puts point before the current page,
-and mark at the end (@pxref{Pages}). The mark goes after the
-terminating page delimiter (to include it in the region), while point
-goes after the preceding page delimiter (to exclude it). A numeric
-argument specifies a later page (if positive) or an earlier page (if
-negative) instead of the current page.
-
- Finally, @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire
-buffer as the region, by putting point at the beginning and the mark at
-the end. (In some programs this is called ``select all.'')
-
- In Transient Mark mode, all of these commands activate the mark.
-
-@node Mark Ring
-@section The Mark Ring
-
-@kindex C-u C-SPC
-@cindex mark ring
-@kindex C-u C-@@
- Aside from delimiting the region, the mark is also useful for
-remembering a spot that you may want to go back to. To make this
-feature more useful, each buffer remembers 16 previous locations of the
-mark, in the @dfn{mark ring}. Commands that set the mark also push the
-old mark onto this ring. To return to a marked location, use @kbd{C-u
-C-@key{SPC}} (or @kbd{C-u C-@@}); this is the command
-@code{set-mark-command} given a numeric argument. It moves point to
-where the mark was, and restores the mark from the ring of former
-marks.
-
-@vindex set-mark-command-repeat-pop
- If you set @code{set-mark-command-repeat-pop} to non-@code{nil},
-then when you repeat the character @kbd{C-@key{SPC}} after typing
-@kbd{C-u C-@key{SPC}}, each repetition moves point to a previous mark
-position from the ring. The mark positions you move through in this
-way are not lost; they go to the end of the ring.
-
- Each buffer has its own mark ring. All editing commands use the current
-buffer's mark ring. In particular, @kbd{C-u C-@key{SPC}} always stays in
-the same buffer.
-
- Many commands that can move long distances, such as @kbd{M-<}
-(@code{beginning-of-buffer}), start by setting the mark and saving the
-old mark on the mark ring. This is to make it easier for you to move
-back later. Searches set the mark if they move point. However, in
-Transient Mark mode, these commands do not set the mark when the mark
-is already active. You can tell when a command sets the mark because
-it displays @samp{Mark set} in the echo area.
-
- If you want to move back to the same place over and over, the mark
-ring may not be convenient enough. If so, you can record the position
-in a register for later retrieval (@pxref{RegPos,, Saving Positions in
-Registers}).
-
-@vindex mark-ring-max
- The variable @code{mark-ring-max} specifies the maximum number of
-entries to keep in the mark ring. If that many entries exist and
-another one is pushed, the earliest one in the list is discarded. Repeating
-@kbd{C-u C-@key{SPC}} cycles through the positions currently in the
-ring.
-
-@vindex mark-ring
- The variable @code{mark-ring} holds the mark ring itself, as a list of
-marker objects, with the most recent first. This variable is local in
-every buffer.
-
-@node Global Mark Ring
-@section The Global Mark Ring
-@cindex global mark ring
-
- In addition to the ordinary mark ring that belongs to each buffer,
-Emacs has a single @dfn{global mark ring}. It records a sequence of
-buffers in which you have recently set the mark, so you can go back
-to those buffers.
-
- Setting the mark always makes an entry on the current buffer's mark
-ring. If you have switched buffers since the previous mark setting, the
-new mark position makes an entry on the global mark ring also. The
-result is that the global mark ring records a sequence of buffers that
-you have been in, and, for each buffer, a place where you set the mark.
-
-@kindex C-x C-@key{SPC}
-@findex pop-global-mark
- The command @kbd{C-x C-@key{SPC}} (@code{pop-global-mark}) jumps to
-the buffer and position of the latest entry in the global ring. It also
-rotates the ring, so that successive uses of @kbd{C-x C-@key{SPC}} take
-you to earlier and earlier buffers.
-
-@ignore
- arch-tag: f35e4d82-911b-4cfc-a3d7-3c87b2abba20
-@end ignore
+++ /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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Minibuffer, M-x, Basic, Top
-@chapter The Minibuffer
-@cindex minibuffer
-
- The @dfn{minibuffer} is where Emacs commands read complicated
-arguments (anything more a single number). We call it the
-``minibuffer'' because it's a special-purpose buffer with a small
-amount of screen space. Minibuffer arguments can be file names,
-buffer names, Lisp function names, Emacs command names, Lisp
-expressions, and many other things---whatever the command wants to
-read. You can use the usual Emacs editing commands in the minibuffer
-to edit the argument text.
-
-@cindex prompt
- When the minibuffer is in use, it appears in the echo area, with a
-cursor. The minibuffer display starts with a @dfn{prompt} in a
-distinct color; it says what kind of input is expected and how it will
-be used. Often the prompt is derived from the name of the command
-that is reading the argument. The prompt normally ends with a colon.
-
-@cindex default argument
- Sometimes a @dfn{default argument} appears in the prompt, inside
-parentheses before the colon. The default will be used as the
-argument value if you just type @key{RET}. For example, commands that
-read buffer names show a buffer name as the default. You can type
-@key{RET} to operate on that default buffer.
-
- The simplest way to enter a minibuffer argument is to type the text,
-then @key{RET} to exit the minibuffer. You can cancel the minibuffer,
-and the command that wants the argument, by typing @kbd{C-g}.
-
- Since the minibuffer appears in the echo area, it can conflict with
-other uses of the echo area. Here is how Emacs handles such
-conflicts:
-
-@itemize @bullet
-@item
-An error occurs while the minibuffer is active.
-
-The error message hides the minibuffer for a few seconds, or until you
-type something. Then the minibuffer comes back.
-
-@item
-A command such as @kbd{C-x =} needs to display a message in the echo
-area.
-
-The message hides the minibuffer for a few seconds, or until you type
-something. Then the minibuffer comes back.
-
-@item
-Keystrokes don't echo while the minibuffer is in use.
-@end itemize
-
-@menu
-* File: Minibuffer File. Entering file names with the minibuffer.
-* Edit: Minibuffer Edit. How to edit in the minibuffer.
-* Completion:: An abbreviation facility for minibuffer input.
-* Minibuffer History:: Reusing recent minibuffer arguments.
-* Repetition:: Re-executing commands that used the minibuffer.
-@end menu
-
-@node Minibuffer File
-@section Minibuffers for File Names
-
- When you use the minibuffer to enter a file name, it starts out with
-some initial text---the @dfn{default directory}, ending in a slash.
-The file you specify will be in this directory unless you alter or
-replace it.
-
-@c Separate paragraph to clean up ugly page break--rms
-@need 1500
- For example, if the minibuffer starts out with these contents:
-
-@example
-Find File: /u2/emacs/src/
-@end example
-
-@noindent
-(where @samp{Find File:@: } is the prompt), and you type
-@kbd{buffer.c} as input, that specifies the file
-@file{/u2/emacs/src/buffer.c}. You can specify the parent directory
-by adding @file{..}; thus, if you type @kbd{../lisp/simple.el}, you
-will get @file{/u2/emacs/lisp/simple.el}. Alternatively, you can use
-@kbd{M-@key{DEL}} to kill the directory names you don't want
-(@pxref{Words}).
-
- You can kill the entire default with @kbd{C-a C-k}, but there's no
-need to do that. It's easier to ignore the default, and enter an
-absolute file name starting with a slash or a tilde after the default
-directory. For example, to specify @file{/etc/termcap}, just type
-that name:
-
-@example
-Find File: /u2/emacs/src//etc/termcap
-@end example
-
-@noindent
-@cindex // in file name
-@cindex double slash in file name
-@cindex slashes repeated in file name
-@findex file-name-shadow-mode
-GNU Emacs interprets a double slash (which is not normally useful in
-file names) as, ``ignore everything before the second slash in the
-pair.'' In the example above. @samp{/u2/emacs/src/} is ignored, so
-you get @file{/etc/termcap}. The ignored part of the file name is
-dimmed if the terminal allows it; to disable this dimming, turn off
-File Name Shadow mode (a minor mode) with the command
-@kbd{M-x file-name-shadow-mode}.
-
- If the variable @code{insert-default-directory} is @code{nil}, the
-default directory is never inserted in the minibuffer---so the
-minibuffer starts out empty. Nonetheless, relative file name
-arguments are still interpreted based on the same default directory.
-
-@node Minibuffer Edit
-@section Editing in the Minibuffer
-
- The minibuffer is an Emacs buffer (albeit a peculiar one), and the
-usual Emacs commands are available for editing the argument text.
-
- Since @key{RET} in the minibuffer is defined to exit the minibuffer,
-you can't use it to insert a newline in the minibuffer. To do that,
-type @kbd{C-o} or @kbd{C-q C-j}. (The newline character is really the
-@acronym{ASCII} character control-J.)
-
- The minibuffer has its own window, which normally has space in the
-frame at all times, but it only acts like an Emacs window when the
-minibuffer is active. When active, this window is much like any other
-Emacs window; for instance, you can switch to another window (with
-@kbd{C-x o}), edit text there, then return to the minibuffer window to
-finish the argument. You can even kill text in another window, return
-to the minibuffer window, and then yank the text into the argument.
-@xref{Windows}.
-
-@cindex height of minibuffer
-@cindex size of minibuffer
-@cindex growing minibuffer
-@cindex resizing minibuffer
- There are some restrictions on the minibuffer window, however: you
-cannot kill it, or split it, or switch buffers in it---the minibuffer
-and its window are permanently attached.
-
-@vindex resize-mini-windows
- The minibuffer window expands vertically as necessary to hold the
-text that you put in the minibuffer. If @code{resize-mini-windows} is
-@code{t} (the default), the window always resizes as needed by its
-contents. If its value is the symbol @code{grow-only}, the window
-grows automatically as needed, but shrinks (back to the normal size)
-only when the minibuffer becomes inactive. If its value is
-@code{nil}, you have to adjust the height yourself.
-
-@vindex max-mini-window-height
- The variable @code{max-mini-window-height} controls the maximum
-height for resizing the minibuffer window: a floating-point number
-specifies a fraction of the frame's height; an integer specifies the
-maximum number of lines; @code{nil} means do not resize the minibuffer
-window automatically. The default value is 0.25.
-
- The @kbd{C-M-v} command in the minibuffer scrolls the help text from
-commands that display help text of any sort in another window.
-@kbd{M-@key{PAGEUP}} and @kbd{M-@key{PAGEDOWN}} also operate on that
-help text. This is especially useful with long lists of possible
-completions. @xref{Other Window}.
-
-@vindex enable-recursive-minibuffers
- Emacs normally disallows most commands that use the minibuffer while
-the minibuffer is active. (Entering the minibuffer from the
-minibuffer can be confusing.) To allow such commands in the
-minibuffer, set the variable @code{enable-recursive-minibuffers} to
-@code{t}.
-
-@node Completion
-@section Completion
-@cindex completion
-
- Some arguments allow @dfn{completion} to enter their value. This
-means that after you type part of the argument, Emacs can fill in the
-rest, or some of it, based on what you have typed so far.
-
- When completion is available, certain keys---@key{TAB}, @key{RET},
-and @key{SPC}---are rebound to complete the text in the minibuffer
-before point into a longer string chosen from a set of @dfn{completion
-alternatives} provided by the command that requested the argument.
-(@key{SPC} does not do completion in reading file names, because it is
-common to use spaces in file names on some systems.) @kbd{?} displays
-a list of the possible completions at any time.
-
- For example, @kbd{M-x} uses the minibuffer to read the name of a
-command, so it provides a list of all Emacs command names for
-completion candidates. The completion keys match the minibuffer text
-against these candidates, find any additional name characters implied
-by the text already present in the minibuffer, and add those
-characters. This makes it possible to type @kbd{M-x ins @key{SPC} b
-@key{RET}} instead of @kbd{M-x insert-buffer @key{RET}}, for example.
-
- Case is significant in completion when it is significant in the
-argument you are entering (buffer names, file names, command names,
-for instance). Thus, @samp{fo} does not complete to @samp{Foo}.
-Completion ignores case distinctions for certain arguments in which
-case does not matter.
-
- Completion acts only on the text before point. If there is text in
-the minibuffer after point---i.e., if you move point backward after
-typing some text into the minibuffer---it remains unchanged.
-
-@menu
-* Example: Completion Example. Examples of using completion.
-* Commands: Completion Commands. A list of completion commands.
-* Strict Completion:: Different types of completion.
-* Options: Completion Options. Options for completion.
-@end menu
-
-@node Completion Example
-@subsection Completion Example
-
-@kindex TAB @r{(completion)}
- A concrete example may help here. If you type @kbd{M-x au
-@key{TAB}}, the @key{TAB} looks for alternatives (in this case,
-command names) that start with @samp{au}. There are several,
-including @code{auto-fill-mode} and @code{auto-save-mode}, but they
-all begin with @code{auto-}, so the @samp{au} in the minibuffer
-completes to @samp{auto-}.
-
- If you type @key{TAB} again immediately, it cannot determine the
-next character; it could be any of @samp{cfilrs}. So it does not add
-any characters; instead, @key{TAB} displays a list of all possible
-completions in another window.
-
- Now type @kbd{f @key{TAB}}. This @key{TAB} sees @samp{auto-f}. The
-only command name starting with that is @code{auto-fill-mode}, so
-completion fills in the rest of that. You have been able to enter
-@samp{auto-fill-mode} by typing just @kbd{au @key{TAB} f @key{TAB}}.
-
-@node Completion Commands
-@subsection Completion Commands
-
- Here is a list of the completion commands defined in the minibuffer
-when completion is allowed.
-
-@table @kbd
-@item @key{TAB}
-@findex minibuffer-complete
-Complete the text before point in the minibuffer as much as possible
-(@code{minibuffer-complete}).
-@item @key{SPC}
-Complete up to one word from the minibuffer text before point
-(@code{minibuffer-complete-word}). @key{SPC} for completion is not
-available when entering a file name, since file names often include
-spaces.
-@item @key{RET}
-Submit the text in the minibuffer as the argument, possibly completing
-first as described
-@iftex
-in the next subsection (@code{minibuffer-complete-and-exit}).
-@end iftex
-@ifnottex
-in the next node (@code{minibuffer-complete-and-exit}). @xref{Strict
-Completion}.
-@end ifnottex
-@item ?
-Display a list of possible completions of the text before point
-(@code{minibuffer-completion-help}).
-@end table
-
-@kindex SPC
-@findex minibuffer-complete-word
- @key{SPC} completes like @key{TAB}, but only up to the next hyphen
-or space. If you have @samp{auto-f} in the minibuffer and type
-@key{SPC}, it finds that the completion is @samp{auto-fill-mode}, but
-it only inserts @samp{ill-}, giving @samp{auto-fill-}. Another
-@key{SPC} at this point completes all the way to
-@samp{auto-fill-mode}. The command that implements this behavior is
-called @code{minibuffer-complete-word}.
-
- When you display a list of possible completions, you can choose
-one from it:
-
-@table @kbd
-@findex mouse-choose-completion
-@item Mouse-1
-@itemx Mouse-2
-Clicking mouse button 1 or 2 on a completion possibility chooses that
-completion (@code{mouse-choose-completion}). You must click in the
-list of completions, not in the minibuffer.
-
-@findex switch-to-completions
-@item @key{PRIOR}
-@itemx M-v
-Typing @key{PRIOR} or @key{PAGE-UP}, or @kbd{M-v}, while in the
-minibuffer, selects the window showing the completion list buffer
-(@code{switch-to-completions}). This paves the way for using the
-commands below. (Selecting that window in other ways has the same
-effect.)
-
-@findex choose-completion
-@item @key{RET}
-Typing @key{RET} @emph{in the completion list buffer} chooses the
-completion that point is in or next to (@code{choose-completion}). To
-use this command, you must first switch to the completion list window.
-
-@findex next-completion
-@item @key{RIGHT}
-Typing the right-arrow key @key{RIGHT} @emph{in the completion list
-buffer} moves point to the following completion possibility
-(@code{next-completion}).
-
-@findex previous-completion
-@item @key{LEFT}
-Typing the left-arrow key @key{LEFT} @emph{in the completion list
-buffer} moves point to the previous completion possibility
-(@code{previous-completion}).
-@end table
-
-@node Strict Completion
-@subsection Strict Completion
-
- There are three different ways that @key{RET} can do completion,
-depending on how the argument will be used.
-
-@itemize @bullet
-@item
-@dfn{Strict} completion accepts only known completion candidates. For
-example, when @kbd{C-x k} reads the name of a buffer to kill, only the
-name of an existing buffer makes sense. In strict completion,
-@key{RET} refuses to exit if the text in the minibuffer does not
-complete to an exact match.
-
-@item
-@dfn{Cautious} completion is similar to strict completion, except that
-@key{RET} exits only if the text is an already exact match.
-Otherwise, @key{RET} does not exit, but it does complete the text. If
-that completes to an exact match, a second @key{RET} will exit.
-
-Cautious completion is used for reading file names for files that must
-already exist, for example.
-
-@item
-@dfn{Permissive} completion allows any input; the completion
-candidates are just suggestions. For example, when @kbd{C-x C-f}
-reads the name of a file to visit, any file name is allowed, including
-nonexistent file (in case you want to create a file). In permissive
-completion, @key{RET} does not complete, it just submits the argument
-as you have entered it.
-@end itemize
-
- The completion commands display a list of all possible completions
-whenever they can't determine even one more character by completion.
-Also, typing @kbd{?} explicitly requests such a list. You can scroll
-the list with @kbd{C-M-v} (@pxref{Other Window}).
-
-@node Completion Options
-@subsection Completion Options
-
-@vindex completion-ignored-extensions
-@cindex ignored file names, in completion
- When completing file names, certain file names are usually ignored.
-The variable @code{completion-ignored-extensions} contains a list of
-strings; a file name ending in any of those strings is ignored as a
-completion candidate. The standard value of this variable has several
-elements including @code{".o"}, @code{".elc"}, @code{".dvi"} and
-@code{"~"}. The effect is that, for example, @samp{foo} can complete
-to @samp{foo.c} even though @samp{foo.o} exists as well. However, if
-@emph{all} the possible completions end in ``ignored'' strings, then
-they are not ignored. Displaying a list of possible completions
-disregards @code{completion-ignored-extensions}; it shows them all.
-
- If an element of @code{completion-ignored-extensions} ends in a
-slash (@file{/}), it's a subdirectory name; then that directory and
-its contents are ignored. Elements of
-@code{completion-ignored-extensions} which do not end in a slash are
-ordinary file names, and do not apply to names of directories.
-
-@vindex completion-auto-help
- If @code{completion-auto-help} is set to @code{nil}, the completion
-commands never display a list of possibilities; you must type @kbd{?}
-to display the list.
-
-@cindex Partial Completion mode
-@vindex partial-completion-mode
-@findex partial-completion-mode
- Partial Completion mode implements a more powerful kind of
-completion that can complete multiple words in parallel. For example,
-it can complete the command name abbreviation @code{p-b} into
-@code{print-buffer} if no other command starts with two words whose
-initials are @samp{p} and @samp{b}.
-
- To enable this mode, use @kbd{M-x partial-completion-mode}, or
-customize the variable @code{partial-completion-mode}. This mode
-binds special partial completion commands to @key{TAB}, @key{SPC},
-@key{RET}, and @kbd{?} in the minibuffer. The usual completion
-commands are available on @kbd{M-@key{TAB}} (or @kbd{C-M-i}),
-@kbd{M-@key{SPC}}, @kbd{M-@key{RET}} and @kbd{M-?}.
-
- Partial completion of directories in file names uses @samp{*} to
-indicate the places for completion; thus, @file{/u*/b*/f*} might
-complete to @file{/usr/bin/foo}. For remote files, partial completion
-enables completion of methods, user names and host names.
-@xref{Remote Files}.
-
-@vindex PC-include-file-path
-@vindex PC-disable-includes
- Partial Completion mode also extends @code{find-file} so that
-@samp{<@var{include}>} looks for the file named @var{include} in the
-directories in the path @code{PC-include-file-path}. If you set
-@code{PC-disable-includes} to non-@code{nil}, this feature is
-disabled.
-
-@cindex Icomplete mode
-@findex icomplete-mode
- Icomplete mode presents a constantly-updated display that tells you
-what completions are available for the text you've entered so far. The
-command to enable or disable this minor mode is @kbd{M-x
-icomplete-mode}.
-
-@node Minibuffer History
-@section Minibuffer History
-@cindex minibuffer history
-@cindex history of minibuffer input
-
- Every argument that you enter with the minibuffer is saved on a
-@dfn{minibuffer history list} so you can easily use it again later.
-Special commands fetch the text of an earlier argument into the
-minibuffer, replacing the old minibuffer contents. You can think of
-them as moving through the history of previous arguments.
-
-@table @kbd
-@item @key{UP}
-@itemx M-p
-Move to the previous item in the minibuffer history, an earlier argument
-(@code{previous-history-element}).
-@item @key{DOWN}
-@itemx M-n
-Move to the next item in the minibuffer history
-(@code{next-history-element}).
-@item M-r @var{regexp} @key{RET}
-Move to an earlier item in the minibuffer history that
-matches @var{regexp} (@code{previous-matching-history-element}).
-@item M-s @var{regexp} @key{RET}
-Move to a later item in the minibuffer history that matches
-@var{regexp} (@code{next-matching-history-element}).
-@end table
-
-@kindex M-p @r{(minibuffer history)}
-@kindex M-n @r{(minibuffer history)}
-@findex next-history-element
-@findex previous-history-element
- To move through the minibuffer history list one item at a time, use
-@kbd{M-p} or up-arrow (@code{previous-history-element}) to fetch the
-next earlier minibuffer input, and use @kbd{M-n} or down-arrow
-(@code{next-history-element}) to fetch the next later input. These
-commands don't move the cursor, they pull different saved strings into
-the minibuffer. But you can think of them as ``moving'' through the
-history list.
-
- The input that you fetch from the history entirely replaces the
-contents of the minibuffer. To use it again unchanged, just type
-@key{RET}. You can also edit the text before you reuse it; this does
-not change the history element that you ``moved'' to, but your new
-argument does go at the end of the history list in its own right.
-
- For many minibuffer arguments there is a ``default'' value. You can
-insert the default value into the minibuffer as text by using
-@kbd{M-n}. You can think of this as moving ``into the future'' in the
-history.
-
-@findex previous-matching-history-element
-@findex next-matching-history-element
-@kindex M-r @r{(minibuffer history)}
-@kindex M-s @r{(minibuffer history)}
- There are also commands to search forward or backward through the
-history; they search for history elements that match a regular
-expression. @kbd{M-r} (@code{previous-matching-history-element})
-searches older elements in the history, while @kbd{M-s}
-(@code{next-matching-history-element}) searches newer elements. These
-commands are unusual; they use the minibuffer to read the regular
-expression even though they are invoked from the minibuffer. As with
-incremental searching, an upper-case letter in the regular expression
-makes the search case-sensitive (@pxref{Search Case}).
-
-@ignore
- We may change the precise way these commands read their arguments.
-Perhaps they will search for a match for the string given so far in the
-minibuffer; perhaps they will search for a literal match rather than a
-regular expression match; perhaps they will only accept matches at the
-beginning of a history element; perhaps they will read the string to
-search for incrementally like @kbd{C-s}. To find out what interface is
-actually available, type @kbd{C-h f previous-matching-history-element}.
-@end ignore
-
- All uses of the minibuffer record your input on a history list, but
-there are separate history lists for different kinds of arguments.
-For example, there is a list for file names, used by all the commands
-that read file names. (As a special feature, this history list
-records the absolute file name, even if the name you entered was not
-absolute.)
-
- There are several other specific history lists, including one for
-buffer names, one for arguments of commands like @code{query-replace},
-one used by @kbd{M-x} for command names, and one used by
-@code{compile} for compilation commands. Finally, there is one
-``miscellaneous'' history list that most minibuffer arguments use.
-
-@vindex history-length
- The variable @code{history-length} specifies the maximum length of a
-minibuffer history list; adding a new element deletes the oldest
-element if the list gets too long. If the value of
-@code{history-length} is @code{t}, though, there is no maximum length.
-
-@vindex history-delete-duplicates
- The variable @code{history-delete-duplicates} specifies whether to
-delete duplicates in history. If it is @code{t}, adding a new element
-deletes from the list all other elements that are equal to it.
-
-@node Repetition
-@section Repeating Minibuffer Commands
-@cindex command history
-@cindex history of commands
-
- Every command that uses the minibuffer once is recorded on a special
-history list, the @dfn{command history}, together with the values of
-its arguments, so that you can repeat the entire command. In
-particular, every use of @kbd{M-x} is recorded there, since @kbd{M-x}
-uses the minibuffer to read the command name.
-
-@findex list-command-history
-@table @kbd
-@item C-x @key{ESC} @key{ESC}
-Re-execute a recent minibuffer command from the command history
- (@code{repeat-complex-command}).
-@item M-x list-command-history
-Display the entire command history, showing all the commands
-@kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first.
-@end table
-
-@kindex C-x ESC ESC
-@findex repeat-complex-command
- @kbd{C-x @key{ESC} @key{ESC}} is used to re-execute a recent command
-that used the minibuffer. With no argument, it repeats the last such
-command. A numeric argument specifies which command to repeat; 1
-means the last one, 2 the previous, and so on.
-
- @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command
-into a Lisp expression and then entering a minibuffer initialized with
-the text for that expression. Even if you don't understand Lisp
-syntax, it will probably be obvious which command is displayed for
-repetition. If you type just @key{RET}, that repeats the command
-unchanged. You can also change the command by editing the Lisp
-expression before you execute it. The repeated command is added to
-the front of the command history unless it is identical to the most
-recently item.
-
- Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you can
-use the minibuffer history commands (@kbd{M-p}, @kbd{M-n}, @kbd{M-r},
-@kbd{M-s}; @pxref{Minibuffer History}) to move through the history list
-of saved entire commands. After finding the desired previous command,
-you can edit its expression as usual and then repeat it by typing
-@key{RET}.
-
-@vindex isearch-resume-in-command-history
- Incremental search does not, strictly speaking, use the minibuffer.
-Therefore, although it behaves like a complex command, it normally
-does not appear in the history list for @kbd{C-x @key{ESC} @key{ESC}}.
-You can make incremental search commands appear in the history by
-setting @code{isearch-resume-in-command-history} to a non-@code{nil}
-value. @xref{Incremental Search}.
-
-@vindex command-history
- The list of previous minibuffer-using commands is stored as a Lisp
-list in the variable @code{command-history}. Each element is a Lisp
-expression which describes one command and its arguments. Lisp programs
-can re-execute a command by calling @code{eval} with the
-@code{command-history} element.
-
-@ignore
- arch-tag: ba913cfd-b70e-400f-b663-22b2c309227f
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@iftex
-@chapter Miscellaneous Commands
-
- This chapter contains several brief topics that do not fit anywhere
-else: reading netnews, running shell commands and shell subprocesses,
-using a single shared Emacs for utilities that expect to run an editor
-as a subprocess, printing hardcopy, sorting text, narrowing display to
-part of the buffer, editing double-column files and binary files,
-saving an Emacs session for later resumption, following hyperlinks,
-browsing images, emulating other editors, and various diversions and
-amusements.
-
-@end iftex
-
-@ifnottex
-@raisesections
-@end ifnottex
-
-@node Gnus, Shell, Calendar/Diary, Top
-@section Gnus
-@cindex Gnus
-@cindex reading netnews
-
-Gnus is an Emacs package primarily designed for reading and posting
-Usenet news. It can also be used to read and respond to messages from a
-number of other sources---mail, remote directories, digests, and so on.
-
-Here we introduce Gnus and describe several basic features.
-@ifnottex
-For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}.
-@end ifnottex
-@iftex
-For full details on Gnus, type @kbd{M-x info} and then select the Gnus
-manual.
-@end iftex
-
-@findex gnus
-To start Gnus, type @kbd{M-x gnus @key{RET}}.
-
-@menu
-* Buffers of Gnus:: The group, summary, and article buffers.
-* Gnus Startup:: What you should know about starting Gnus.
-* Summary of Gnus:: A short description of the basic Gnus commands.
-@end menu
-
-@node Buffers of Gnus
-@subsection Gnus Buffers
-
-Unlike most Emacs packages, Gnus uses several buffers to display
-information and to receive commands. The three Gnus buffers users use
-most are the @dfn{group buffer}, the @dfn{summary buffer} and the
-@dfn{article buffer}.
-
-The @dfn{group buffer} contains a list of newsgroups. This is the
-first buffer Gnus displays when it starts up. It normally displays
-only the groups to which you subscribe and that contain unread
-articles. Use this buffer to select a specific group.
-
-The @dfn{summary buffer} lists one line for each article in a single
-group. By default, the author, the subject and the line number are
-displayed for each article, but this is customizable, like most aspects
-of Gnus display. The summary buffer is created when you select a group
-in the group buffer, and is killed when you exit the group. Use this
-buffer to select an article.
-
-The @dfn{article buffer} displays the article. In normal Gnus usage,
-you see this buffer but you don't select it---all useful
-article-oriented commands work in the summary buffer. But you can
-select the article buffer, and execute all Gnus commands from that
-buffer, if you want to.
-
-@node Gnus Startup
-@subsection When Gnus Starts Up
-
-At startup, Gnus reads your @file{.newsrc} news initialization file
-and attempts to communicate with the local news server, which is a
-repository of news articles. The news server need not be the same
-computer you are logged in on.
-
-If you start Gnus and connect to the server, but do not see any
-newsgroups listed in the group buffer, type @kbd{L} or @kbd{A k} to get
-a listing of all the groups. Then type @kbd{u} to toggle
-subscription to groups.
-
-The first time you start Gnus, Gnus subscribes you to a few selected
-groups. All other groups start out as @dfn{killed groups} for you; you
-can list them with @kbd{A k}. All new groups that subsequently come to
-exist at the news server become @dfn{zombie groups} for you; type @kbd{A
-z} to list them. You can subscribe to a group shown in these lists
-using the @kbd{u} command.
-
-When you quit Gnus with @kbd{q}, it automatically records in your
-@file{.newsrc} and @file{.newsrc.eld} initialization files the
-subscribed or unsubscribed status of all groups. You should normally
-not edit these files manually, but you may if you know how.
-
-@node Summary of Gnus
-@subsection Summary of Gnus Commands
-
-Reading news is a two-step process:
-
-@enumerate
-@item
-Choose a group in the group buffer.
-
-@item
-Select articles from the summary buffer. Each article selected is
-displayed in the article buffer in a large window, below the summary
-buffer in its small window.
-@end enumerate
-
- Each Gnus buffer has its own special commands; the meanings of any
-given key in the various Gnus buffers are usually analogous, even if
-not identical. Here are commands for the group and summary buffers:
-
-@table @kbd
-@kindex q @r{(Gnus Group mode)}
-@findex gnus-group-exit
-@item q
-In the group buffer, update your @file{.newsrc} initialization file
-and quit Gnus.
-
-In the summary buffer, exit the current group and return to the
-group buffer. Thus, typing @kbd{q} twice quits Gnus.
-
-@kindex L @r{(Gnus Group mode)}
-@findex gnus-group-list-all-groups
-@item L
-In the group buffer, list all the groups available on your news
-server (except those you have killed). This may be a long list!
-
-@kindex l @r{(Gnus Group mode)}
-@findex gnus-group-list-groups
-@item l
-In the group buffer, list only the groups to which you subscribe and
-which contain unread articles.
-
-@kindex u @r{(Gnus Group mode)}
-@findex gnus-group-unsubscribe-current-group
-@cindex subscribe groups
-@cindex unsubscribe groups
-@item u
-In the group buffer, unsubscribe from (or subscribe to) the group listed
-in the line that point is on. When you quit Gnus by typing @kbd{q},
-Gnus lists in your @file{.newsrc} file which groups you have subscribed
-to. The next time you start Gnus, you won't see this group,
-because Gnus normally displays only subscribed-to groups.
-
-@kindex C-k @r{(Gnus)}
-@findex gnus-group-kill-group
-@item C-k
-In the group buffer, ``kill'' the current line's group---don't
-even list it in @file{.newsrc} from now on. This affects future
-Gnus sessions as well as the present session.
-
-When you quit Gnus by typing @kbd{q}, Gnus writes information
-in the file @file{.newsrc} describing all newsgroups except those you
-have ``killed.''
-
-@kindex SPC @r{(Gnus)}
-@findex gnus-group-read-group
-@item @key{SPC}
-In the group buffer, select the group on the line under the cursor
-and display the first unread article in that group.
-
-@need 1000
-In the summary buffer,
-
-@itemize @bullet
-@item
-Select the article on the line under the cursor if none is selected.
-
-@item
-Scroll the text of the selected article (if there is one).
-
-@item
-Select the next unread article if at the end of the current article.
-@end itemize
-
-Thus, you can move through all the articles by repeatedly typing @key{SPC}.
-
-@kindex DEL @r{(Gnus)}
-@item @key{DEL}
-In the group buffer, move point to the previous group containing
-unread articles.
-
-@findex gnus-summary-prev-page
-In the summary buffer, scroll the text of the article backwards.
-
-@kindex n @r{(Gnus)}
-@findex gnus-group-next-unread-group
-@findex gnus-summary-next-unread-article
-@item n
-Move point to the next unread group, or select the next unread article.
-
-@kindex p @r{(Gnus)}
-@findex gnus-group-prev-unread-group
-@findex gnus-summary-prev-unread-article
-@item p
-Move point to the previous unread group, or select the previous
-unread article.
-
-@kindex C-n @r{(Gnus Group mode)}
-@findex gnus-group-next-group
-@kindex C-p @r{(Gnus Group mode)}
-@findex gnus-group-prev-group
-@kindex C-n @r{(Gnus Summary mode)}
-@findex gnus-summary-next-subject
-@kindex C-p @r{(Gnus Summary mode)}
-@findex gnus-summary-prev-subject
-@item C-n
-@itemx C-p
-Move point to the next or previous item, even if it is marked as read.
-This does not select the article or group on that line.
-
-@kindex s @r{(Gnus Summary mode)}
-@findex gnus-summary-isearch-article
-@item s
-In the summary buffer, do an incremental search of the current text in
-the article buffer, just as if you switched to the article buffer and
-typed @kbd{C-s}.
-
-@kindex M-s @r{(Gnus Summary mode)}
-@findex gnus-summary-search-article-forward
-@item M-s @var{regexp} @key{RET}
-In the summary buffer, search forward for articles containing a match
-for @var{regexp}.
-
-@end table
-
-@ignore
-@node Where to Look
-@subsection Where to Look Further
-
-@c Too many references to the name of the manual if done with xref in TeX!
-Gnus is powerful and customizable. Here are references to a few
-@ifnottex
-additional topics:
-
-@end ifnottex
-@iftex
-additional topics in @cite{The Gnus Manual}:
-
-@itemize @bullet
-@item
-Follow discussions on specific topics.@*
-See section ``Threading.''
-
-@item
-Read digests. See section ``Document Groups.''
-
-@item
-Refer to and jump to the parent of the current article.@*
-See section ``Finding the Parent.''
-
-@item
-Refer to articles by using Message-IDs included in the messages.@*
-See section ``Article Keymap.''
-
-@item
-Save articles. See section ``Saving Articles.''
-
-@item
-Have Gnus score articles according to various criteria, like author
-name, subject, or string in the body of the articles.@*
-See section ``Scoring.''
-
-@item
-Send an article to a newsgroup.@*
-See section ``Composing Messages.''
-@end itemize
-@end iftex
-@ifnottex
-@itemize @bullet
-@item
-Follow discussions on specific topics.@*
-@xref{Threading, , Reading Based on Conversation Threads,
-gnus, The Gnus Manual}.
-
-@item
-Read digests. @xref{Document Groups, , , gnus, The Gnus Manual}.
-
-@item
-Refer to and jump to the parent of the current article.@*
-@xref{Finding the Parent, , , gnus, The Gnus Manual}.
-
-@item
-Refer to articles by using Message-IDs included in the messages.@*
-@xref{Article Keymap, , , gnus, The Gnus Manual}.
-
-@item
-Save articles. @xref{Saving Articles, , , gnus, The Gnus Manual}.
-
-@item
-Have Gnus score articles according to various criteria, like author
-name, subject, or string in the body of the articles.@*
-@xref{Scoring, , , gnus, The Gnus Manual}.
-
-@item
-Send an article to a newsgroup.@*
-@xref{Composing Messages, , , gnus, The Gnus Manual}.
-@end itemize
-@end ifnottex
-@end ignore
-
-@node Shell, Emacs Server, Gnus, Top
-@section Running Shell Commands from Emacs
-@cindex subshell
-@cindex shell commands
-
- Emacs has commands for passing single command lines to inferior shell
-processes; it can also run a shell interactively with input and output
-to an Emacs buffer named @samp{*shell*} or run a shell inside a terminal
-emulator window.
-
-@table @kbd
-@item M-! @var{cmd} @key{RET}
-Run the shell command line @var{cmd} and display the output
-(@code{shell-command}).
-@item M-| @var{cmd} @key{RET}
-Run the shell command line @var{cmd} with region contents as input;
-optionally replace the region with the output
-(@code{shell-command-on-region}).
-@item M-x shell
-Run a subshell with input and output through an Emacs buffer.
-You can then give commands interactively.
-@item M-x term
-Run a subshell with input and output through an Emacs buffer.
-You can then give commands interactively.
-Full terminal emulation is available.
-@end table
-
- @kbd{M-x eshell} invokes a shell implemented entirely in Emacs. It
-is documented in a separate manual. @xref{Top,Eshell,Eshell, eshell,
-Eshell: The Emacs Shell}.
-
-@menu
-* Single Shell:: How to run one shell command and return.
-* Interactive Shell:: Permanent shell taking input via Emacs.
-* Shell Mode:: Special Emacs commands used with permanent shell.
-* Shell Prompts:: Two ways to recognize shell prompts.
-* History: Shell History. Repeating previous commands in a shell buffer.
-* Directory Tracking:: Keeping track when the subshell changes directory.
-* Options: Shell Options. Options for customizing Shell mode.
-* Terminal emulator:: An Emacs window as a terminal emulator.
-* Term Mode:: Special Emacs commands used in Term mode.
-* Paging in Term:: Paging in the terminal emulator.
-* Remote Host:: Connecting to another computer.
-@end menu
-
-@node Single Shell
-@subsection Single Shell Commands
-
-@kindex M-!
-@findex shell-command
- @kbd{M-!} (@code{shell-command}) reads a line of text using the
-minibuffer and executes it as a shell command in a subshell made just
-for that command. Standard input for the command comes from the null
-device. If the shell command produces any output, the output appears
-either in the echo area (if it is short), or in an Emacs buffer named
-@samp{*Shell Command Output*}, which is displayed in another window
-but not selected (if the output is long).
-
- For instance, one way to decompress a file @file{foo.gz} from Emacs
-is to type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command
-normally creates the file @file{foo} and produces no terminal output.
-
- A numeric argument, as in @kbd{M-1 M-!}, says to insert terminal
-output into the current buffer instead of a separate buffer. It puts
-point before the output, and sets the mark after the output. For
-instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the
-uncompressed equivalent of @file{foo.gz} into the current buffer.
-
- If the shell command line ends in @samp{&}, it runs asynchronously.
-For a synchronous shell command, @code{shell-command} returns the
-command's exit status (0 means success), when it is called from a Lisp
-program. You do not get any status information for an asynchronous
-command, since it hasn't finished yet when @code{shell-command} returns.
-
-@kindex M-|
-@findex shell-command-on-region
- @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but
-passes the contents of the region as the standard input to the shell
-command, instead of no input. With a numeric argument, meaning insert
-the output in the current buffer, it deletes the old region and the
-output replaces it as the contents of the region. It returns the
-command's exit status, like @kbd{M-!}.
-
- One use for @kbd{M-|} is to run @code{gpg} to see what keys are in
-the buffer. For instance, if the buffer contains a GPG key, type
-@kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents to
-the @code{gpg} program. That program will ignore everything except
-the encoded keys, and will output a list of the keys the buffer
-contains.
-
-@vindex shell-file-name
- Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify
-the shell to use. This variable is initialized based on your
-@env{SHELL} environment variable when Emacs is started. If the file
-name is relative, Emacs searches the directories in the list
-@code{exec-path}; this list is initialized based on the environment
-variable @env{PATH} when Emacs is started. Your @file{.emacs} file
-can override either or both of these default initializations.
-
- Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete,
-unless you end the command with @samp{&} to make it asynchronous. To
-stop waiting, type @kbd{C-g} to quit; that terminates the shell
-command with the signal @code{SIGINT}---the same signal that @kbd{C-c}
-normally generates in the shell. Emacs then waits until the command
-actually terminates. If the shell command doesn't stop (because it
-ignores the @code{SIGINT} signal), type @kbd{C-g} again; this sends
-the command a @code{SIGKILL} signal which is impossible to ignore.
-
- Asynchronous commands ending in @samp{&} feed their output into
-the buffer @samp{*Async Shell Command*}. Output arrives in that
-buffer regardless of whether it is visible in a window.
-
- To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command
-@kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}.
-
-@vindex shell-command-default-error-buffer
- Error output from these commands is normally intermixed with the
-regular output. But if the variable
-@code{shell-command-default-error-buffer} has a string as value, and
-it's the name of a buffer, @kbd{M-!} and @kbd{M-|} insert error output
-before point in that buffer.
-
-@node Interactive Shell
-@subsection Interactive Inferior Shell
-
-@findex shell
- To run a subshell interactively, putting its typescript in an Emacs
-buffer, use @kbd{M-x shell}. This creates (or reuses) a buffer named
-@samp{*shell*} and runs a subshell with input coming from and output going
-to that buffer. That is to say, any ``terminal output'' from the subshell
-goes into the buffer, advancing point, and any ``terminal input'' for
-the subshell comes from text in the buffer. To give input to the subshell,
-go to the end of the buffer and type the input, terminated by @key{RET}.
-
- Emacs does not wait for the subshell to do anything. You can switch
-windows or buffers and edit them while the shell is waiting, or while it is
-running a command. Output from the subshell waits until Emacs has time to
-process it; this happens whenever Emacs is waiting for keyboard input or
-for time to elapse.
-
-@cindex @code{comint-highlight-input} face
-@cindex @code{comint-highlight-prompt} face
- Input lines, once you submit them, are displayed using the face
-@code{comint-highlight-input}, and prompts are displayed using the
-face @code{comint-highlight-prompt}. This makes it easier to see
-previous input lines in the buffer. @xref{Faces}.
-
- To make multiple subshells, you can invoke @kbd{M-x shell} with a
-prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer
-name and create (or reuse) a subshell in that buffer. You can also
-rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then
-create a new @samp{*shell*} buffer using plain @kbd{M-x shell}.
-Subshells in different buffers run independently and in parallel.
-
-@vindex explicit-shell-file-name
-@cindex environment variables for subshells
-@cindex @env{ESHELL} environment variable
-@cindex @env{SHELL} environment variable
- The file name used to load the subshell is the value of the variable
-@code{explicit-shell-file-name}, if that is non-@code{nil}. Otherwise,
-the environment variable @env{ESHELL} is used, or the environment
-variable @env{SHELL} if there is no @env{ESHELL}. If the file name
-specified is relative, the directories in the list @code{exec-path} are
-searched; this list is initialized based on the environment variable
-@env{PATH} when Emacs is started. Your @file{.emacs} file can override
-either or both of these default initializations.
-
- Emacs sends the new shell the contents of the file
-@file{~/.emacs_@var{shellname}} as input, if it exists, where
-@var{shellname} is the name of the file that the shell was loaded
-from. For example, if you use bash, the file sent to it is
-@file{~/.emacs_bash}. If this file is not found, Emacs tries to fallback
-on @file{~/.emacs.d/init_@var{shellname}.sh}.
-
- To specify a coding system for the shell, you can use the command
-@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}. You can
-also change the coding system for a running subshell by typing
-@kbd{C-x @key{RET} p} in the shell buffer. @xref{Communication
-Coding}.
-
-@cindex @env{INSIDE_EMACS} environment variable
- Emacs sets the envitonment variable @env{INSIDE_EMACS} to @code{t}
-in the subshell. Programs can check this variable to determine
-whether they are running inside an Emacs subshell.
-
-@cindex @env{EMACS} environment variable
- Emacs also sets the @env{EMACS} environment variable to @code{t} if
-it is not already defined. @strong{Warning:} This environment
-variable is deprecated. Programs that check this variable should be
-changed to check @env{INSIDE_EMACS} instead.
-
-@node Shell Mode
-@subsection Shell Mode
-@cindex Shell mode
-@cindex mode, Shell
-
- Shell buffers use Shell mode, which defines several special keys
-attached to the @kbd{C-c} prefix. They are chosen to resemble the usual
-editing and job control characters present in shells that are not under
-Emacs, except that you must type @kbd{C-c} first. Here is a complete list
-of the special key bindings of Shell mode:
-
-@table @kbd
-@item @key{RET}
-@kindex RET @r{(Shell mode)}
-@findex comint-send-input
-At end of buffer send line as input; otherwise, copy current line to
-end of buffer and send it (@code{comint-send-input}). Copying a line
-in this way omits any prompt at the beginning of the line (text output
-by programs preceding your input). @xref{Shell Prompts}, for how
-Shell mode recognizes prompts.
-
-@item @key{TAB}
-@kindex TAB @r{(Shell mode)}
-@findex comint-dynamic-complete
-Complete the command name or file name before point in the shell buffer
-(@code{comint-dynamic-complete}). @key{TAB} also completes history
-references (@pxref{History References}) and environment variable names.
-
-@vindex shell-completion-fignore
-@vindex comint-completion-fignore
-The variable @code{shell-completion-fignore} specifies a list of file
-name extensions to ignore in Shell mode completion. The default
-setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to
-ignore file names ending in @samp{~}, @samp{#} or @samp{%}. Other
-related Comint modes use the variable @code{comint-completion-fignore}
-instead.
-
-@item M-?
-@kindex M-? @r{(Shell mode)}
-@findex comint-dynamic-list-filename@dots{}
-Display temporarily a list of the possible completions of the file name
-before point in the shell buffer
-(@code{comint-dynamic-list-filename-completions}).
-
-@item C-d
-@kindex C-d @r{(Shell mode)}
-@findex comint-delchar-or-maybe-eof
-Either delete a character or send @acronym{EOF}
-(@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell
-buffer, @kbd{C-d} sends @acronym{EOF} to the subshell. Typed at any other
-position in the buffer, @kbd{C-d} deletes a character as usual.
-
-@item C-c C-a
-@kindex C-c C-a @r{(Shell mode)}
-@findex comint-bol-or-process-mark
-Move to the beginning of the line, but after the prompt if any
-(@code{comint-bol-or-process-mark}). If you repeat this command twice
-in a row, the second time it moves back to the process mark, which is
-the beginning of the input that you have not yet sent to the subshell.
-(Normally that is the same place---the end of the prompt on this
-line---but after @kbd{C-c @key{SPC}} the process mark may be in a
-previous line.)
-
-@item C-c @key{SPC}
-Accumulate multiple lines of input, then send them together. This
-command inserts a newline before point, but does not send the preceding
-text as input to the subshell---at least, not yet. Both lines, the one
-before this newline and the one after, will be sent together (along with
-the newline that separates them), when you type @key{RET}.
-
-@item C-c C-u
-@kindex C-c C-u @r{(Shell mode)}
-@findex comint-kill-input
-Kill all text pending at end of buffer to be sent as input
-(@code{comint-kill-input}). If point is not at end of buffer,
-this only kills the part of this text that precedes point.
-
-@item C-c C-w
-@kindex C-c C-w @r{(Shell mode)}
-Kill a word before point (@code{backward-kill-word}).
-
-@item C-c C-c
-@kindex C-c C-c @r{(Shell mode)}
-@findex comint-interrupt-subjob
-Interrupt the shell or its current subjob if any
-(@code{comint-interrupt-subjob}). This command also kills
-any shell input pending in the shell buffer and not yet sent.
-
-@item C-c C-z
-@kindex C-c C-z @r{(Shell mode)}
-@findex comint-stop-subjob
-Stop the shell or its current subjob if any (@code{comint-stop-subjob}).
-This command also kills any shell input pending in the shell buffer and
-not yet sent.
-
-@item C-c C-\
-@findex comint-quit-subjob
-@kindex C-c C-\ @r{(Shell mode)}
-Send quit signal to the shell or its current subjob if any
-(@code{comint-quit-subjob}). This command also kills any shell input
-pending in the shell buffer and not yet sent.
-
-@item C-c C-o
-@kindex C-c C-o @r{(Shell mode)}
-@findex comint-delete-output
-Delete the last batch of output from a shell command
-(@code{comint-delete-output}). This is useful if a shell command spews
-out lots of output that just gets in the way. This command used to be
-called @code{comint-kill-output}.
-
-@item C-c C-s
-@kindex C-c C-s @r{(Shell mode)}
-@findex comint-write-output
-Write the last batch of output from a shell command to a file
-(@code{comint-write-output}). With a prefix argument, the file is
-appended to instead. Any prompt at the end of the output is not
-written.
-
-@item C-c C-r
-@itemx C-M-l
-@kindex C-c C-r @r{(Shell mode)}
-@kindex C-M-l @r{(Shell mode)}
-@findex comint-show-output
-Scroll to display the beginning of the last batch of output at the top
-of the window; also move the cursor there (@code{comint-show-output}).
-
-@item C-c C-e
-@kindex C-c C-e @r{(Shell mode)}
-@findex comint-show-maximum-output
-Scroll to put the end of the buffer at the bottom of the window
-(@code{comint-show-maximum-output}).
-
-@item C-c C-f
-@kindex C-c C-f @r{(Shell mode)}
-@findex shell-forward-command
-@vindex shell-command-regexp
-Move forward across one shell command, but not beyond the current line
-(@code{shell-forward-command}). The variable @code{shell-command-regexp}
-specifies how to recognize the end of a command.
-
-@item C-c C-b
-@kindex C-c C-b @r{(Shell mode)}
-@findex shell-backward-command
-Move backward across one shell command, but not beyond the current line
-(@code{shell-backward-command}).
-
-@item M-x dirs
-Ask the shell what its current directory is, so that Emacs can agree
-with the shell.
-
-@item M-x send-invisible @key{RET} @var{text} @key{RET}
-@findex send-invisible
-Send @var{text} as input to the shell, after reading it without
-echoing. This is useful when a shell command runs a program that asks
-for a password.
-
-Please note that Emacs will not echo passwords by default. If you
-really want them to be echoed, evaluate the following Lisp
-expression:
-
-@example
-(remove-hook 'comint-output-filter-functions
- 'comint-watch-for-password-prompt)
-@end example
-
-@item M-x comint-continue-subjob
-@findex comint-continue-subjob
-Continue the shell process. This is useful if you accidentally suspend
-the shell process.@footnote{You should not suspend the shell process.
-Suspending a subjob of the shell is a completely different matter---that
-is normal practice, but you must use the shell to continue the subjob;
-this command won't do it.}
-
-@item M-x comint-strip-ctrl-m
-@findex comint-strip-ctrl-m
-Discard all control-M characters from the current group of shell output.
-The most convenient way to use this command is to make it run
-automatically when you get output from the subshell. To do that,
-evaluate this Lisp expression:
-
-@example
-(add-hook 'comint-output-filter-functions
- 'comint-strip-ctrl-m)
-@end example
-
-@item M-x comint-truncate-buffer
-@findex comint-truncate-buffer
-This command truncates the shell buffer to a certain maximum number of
-lines, specified by the variable @code{comint-buffer-maximum-size}.
-Here's how to do this automatically each time you get output from the
-subshell:
-
-@example
-(add-hook 'comint-output-filter-functions
- 'comint-truncate-buffer)
-@end example
-@end table
-
-@cindex Comint mode
-@cindex mode, Comint
- Shell mode is a derivative of Comint mode, a general-purpose mode for
-communicating with interactive subprocesses. Most of the features of
-Shell mode actually come from Comint mode, as you can see from the
-command names listed above. The special features of Shell mode include
-the directory tracking feature, and a few user commands.
-
- Other Emacs features that use variants of Comint mode include GUD
-(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}).
-
-@findex comint-run
- You can use @kbd{M-x comint-run} to execute any program of your choice
-in a subprocess using unmodified Comint mode---without the
-specializations of Shell mode.
-
-@node Shell Prompts
-@subsection Shell Prompts
-
-@vindex shell-prompt-pattern
-@vindex comint-prompt-regexp
-@vindex comint-use-prompt-regexp
-@cindex prompt, shell
- A prompt is text output by a program to show that it is ready to
-accept new user input. Normally, Comint mode (and thus Shell mode)
-considers the prompt to be any text output by a program at the
-beginning of an input line. However, if the variable
-@code{comint-use-prompt-regexp} is non-@code{nil}, then Comint mode
-uses a regular expression to recognize prompts. In Shell mode,
-@code{shell-prompt-pattern} specifies the regular expression.
-
- The value of @code{comint-use-prompt-regexp} also affects many
-motion and paragraph commands. If the value is non-@code{nil}, the
-general Emacs motion commands behave as they normally do in buffers
-without special text properties. However, if the value is @code{nil},
-the default, then Comint mode divides the buffer into two types of
-``fields'' (ranges of consecutive characters having the same
-@code{field} text property): input and output. Prompts are part of
-the output. Most Emacs motion commands do not cross field boundaries,
-unless they move over multiple lines. For instance, when point is in
-input on the same line as a prompt, @kbd{C-a} puts point at the
-beginning of the input if @code{comint-use-prompt-regexp} is
-@code{nil} and at the beginning of the line otherwise.
-
- In Shell mode, only shell prompts start new paragraphs. Thus, a
-paragraph consists of a prompt and the input and output that follow
-it. However, if @code{comint-use-prompt-regexp} is @code{nil}, the
-default, most paragraph commands do not cross field boundaries. This
-means that prompts, ranges of input, and ranges of non-prompt output
-behave mostly like separate paragraphs; with this setting, numeric
-arguments to most paragraph commands yield essentially undefined
-behavior. For the purpose of finding paragraph boundaries, Shell mode
-uses @code{shell-prompt-pattern}, regardless of
-@code{comint-use-prompt-regexp}.
-
-@node Shell History
-@subsection Shell Command History
-
- Shell buffers support three ways of repeating earlier commands. You
-can use keys like those used for the minibuffer history; these work
-much as they do in the minibuffer, inserting text from prior commands
-while point remains always at the end of the buffer. You can move
-through the buffer to previous inputs in their original place, then
-resubmit them or copy them to the end. Or you can use a
-@samp{!}-style history reference.
-
-@menu
-* Ring: Shell Ring. Fetching commands from the history list.
-* Copy: Shell History Copying. Moving to a command and then copying it.
-* History References:: Expanding @samp{!}-style history references.
-@end menu
-
-@node Shell Ring
-@subsubsection Shell History Ring
-
-@table @kbd
-@findex comint-previous-input
-@kindex M-p @r{(Shell mode)}
-@item M-p
-@itemx C-@key{UP}
-Fetch the next earlier old shell command.
-
-@kindex M-n @r{(Shell mode)}
-@findex comint-next-input
-@item M-n
-@itemx C-@key{DOWN}
-Fetch the next later old shell command.
-
-@kindex M-r @r{(Shell mode)}
-@kindex M-s @r{(Shell mode)}
-@findex comint-previous-matching-input
-@findex comint-next-matching-input
-@item M-r @var{regexp} @key{RET}
-@itemx M-s @var{regexp} @key{RET}
-Search backwards or forwards for old shell commands that match @var{regexp}.
-
-@item C-c C-x
-@kindex C-c C-x @r{(Shell mode)}
-@findex comint-get-next-from-history
-Fetch the next subsequent command from the history.
-
-@item C-c .
-@kindex C-c . @r{(Shell mode)}
-@findex comint-input-previous-argument
-Fetch one argument from an old shell command.
-
-@item C-c C-l
-@kindex C-c C-l @r{(Shell mode)}
-@findex comint-dynamic-list-input-ring
-Display the buffer's history of shell commands in another window
-(@code{comint-dynamic-list-input-ring}).
-@end table
-
- Shell buffers provide a history of previously entered shell commands. To
-reuse shell commands from the history, use the editing commands @kbd{M-p},
-@kbd{M-n}, @kbd{M-r} and @kbd{M-s}. These work just like the minibuffer
-history commands except that they operate on the text at the end of the
-shell buffer, where you would normally insert text to send to the shell.
-
- @kbd{M-p} fetches an earlier shell command to the end of the shell
-buffer. Successive use of @kbd{M-p} fetches successively earlier
-shell commands, each replacing any text that was already present as
-potential shell input. @kbd{M-n} does likewise except that it finds
-successively more recent shell commands from the buffer.
-@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like
-@kbd{M-n}.
-
- The history search commands @kbd{M-r} and @kbd{M-s} read a regular
-expression and search through the history for a matching command. Aside
-from the choice of which command to fetch, they work just like @kbd{M-p}
-and @kbd{M-n}. If you enter an empty regexp, these commands reuse the
-same regexp used last time.
-
- When you find the previous input you want, you can resubmit it by
-typing @key{RET}, or you can edit it first and then resubmit it if you
-wish. Any partial input you were composing before navigating the
-history list is restored when you go to the beginning or end of the
-history ring.
-
- Often it is useful to reexecute several successive shell commands that
-were previously executed in sequence. To do this, first find and
-reexecute the first command of the sequence. Then type @kbd{C-c C-x};
-that will fetch the following command---the one that follows the command
-you just repeated. Then type @key{RET} to reexecute this command. You
-can reexecute several successive commands by typing @kbd{C-c C-x
-@key{RET}} over and over.
-
- The command @kbd{C-c .}@: (@code{comint-input-previous-argument})
-copies an individual argument from a previous command, like @kbd{ESC
-.} in Bash. The simplest use copies the last argument from the
-previous shell command. With a prefix argument @var{n}, it copies the
-@var{n}th argument instead. Repeating @kbd{C-c .} copies from an
-earlier shell command instead, always using the same value of @var{n}
-(don't give a prefix argument when you repeat the @kbd{C-c .}
-command).
-
- These commands get the text of previous shell commands from a special
-history list, not from the shell buffer itself. Thus, editing the shell
-buffer, or even killing large parts of it, does not affect the history
-that these commands access.
-
-@vindex shell-input-ring-file-name
- Some shells store their command histories in files so that you can
-refer to commands from previous shell sessions. Emacs reads
-the command history file for your chosen shell, to initialize its own
-command history. The file name is @file{~/.bash_history} for bash,
-@file{~/.sh_history} for ksh, and @file{~/.history} for other shells.
-
-@node Shell History Copying
-@subsubsection Shell History Copying
-
-@table @kbd
-@kindex C-c C-p @r{(Shell mode)}
-@findex comint-previous-prompt
-@item C-c C-p
-Move point to the previous prompt (@code{comint-previous-prompt}).
-
-@kindex C-c C-n @r{(Shell mode)}
-@findex comint-next-prompt
-@item C-c C-n
-Move point to the following prompt (@code{comint-next-prompt}).
-
-@kindex C-c RET @r{(Shell mode)}
-@findex comint-copy-old-input
-@item C-c @key{RET}
-Copy the input command which point is in, inserting the copy at the end
-of the buffer (@code{comint-copy-old-input}). This is useful if you
-move point back to a previous command. After you copy the command, you
-can submit the copy as input with @key{RET}. If you wish, you can
-edit the copy before resubmitting it. If you use this command on an
-output line, it copies that line to the end of the buffer.
-
-@item Mouse-2
-If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy
-the old input command that you click on, inserting the copy at the end
-of the buffer (@code{comint-insert-input}). If
-@code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is
-not over old input, just yank as usual.
-@end table
-
- Moving to a previous input and then copying it with @kbd{C-c
-@key{RET}} or @kbd{Mouse-2} produces the same results---the same
-buffer contents---that you would get by using @kbd{M-p} enough times
-to fetch that previous input from the history list. However, @kbd{C-c
-@key{RET}} copies the text from the buffer, which can be different
-from what is in the history list if you edit the input text in the
-buffer after it has been sent.
-
-@node History References
-@subsubsection Shell History References
-@cindex history reference
-
- Various shells including csh and bash support @dfn{history
-references} that begin with @samp{!} and @samp{^}. Shell mode
-recognizes these constructs, and can perform the history substitution
-for you.
-
- If you insert a history reference and type @key{TAB}, this searches
-the input history for a matching command, performs substitution if
-necessary, and places the result in the buffer in place of the history
-reference. For example, you can fetch the most recent command
-beginning with @samp{mv} with @kbd{! m v @key{TAB}}. You can edit the
-command if you wish, and then resubmit the command to the shell by
-typing @key{RET}.
-
-@vindex comint-input-autoexpand
-@findex comint-magic-space
- Shell mode can optionally expand history references in the buffer
-when you send them to the shell. To request this, set the variable
-@code{comint-input-autoexpand} to @code{input}. You can make
-@key{SPC} perform history expansion by binding @key{SPC} to the
-command @code{comint-magic-space}.
-
- Shell mode recognizes history references when they follow a prompt.
-@xref{Shell Prompts}, for how Shell mode recognizes prompts.
-
-@node Directory Tracking
-@subsection Directory Tracking
-@cindex directory tracking
-
-@vindex shell-pushd-regexp
-@vindex shell-popd-regexp
-@vindex shell-cd-regexp
- Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd}
-commands given to the inferior shell, so it can keep the
-@samp{*shell*} buffer's default directory the same as the shell's
-working directory. It recognizes these commands syntactically, by
-examining lines of input that are sent.
-
- If you use aliases for these commands, you can tell Emacs to
-recognize them also. For example, if the value of the variable
-@code{shell-pushd-regexp} matches the beginning of a shell command
-line, that line is regarded as a @code{pushd} command. Change this
-variable when you add aliases for @samp{pushd}. Likewise,
-@code{shell-popd-regexp} and @code{shell-cd-regexp} are used to
-recognize commands with the meaning of @samp{popd} and @samp{cd}.
-These commands are recognized only at the beginning of a shell command
-line.
-
-@ignore @c This seems to have been deleted long ago.
-@vindex shell-set-directory-error-hook
- If Emacs gets an error while trying to handle what it believes is a
-@samp{cd}, @samp{pushd} or @samp{popd} command, it runs the hook
-@code{shell-set-directory-error-hook} (@pxref{Hooks}).
-@end ignore
-
-@findex dirs
- If Emacs gets confused about changes in the current directory of the
-subshell, use the command @kbd{M-x dirs} to ask the shell what its
-current directory is. This command works for shells that support the
-most common command syntax; it may not work for unusual shells.
-
-@findex dirtrack-mode
- You can also use @kbd{M-x dirtrack-mode} to enable (or disable) an
-alternative and more aggressive method of tracking changes in the
-current directory.
-
-@node Shell Options
-@subsection Shell Mode Options
-
-@vindex comint-scroll-to-bottom-on-input
- If the variable @code{comint-scroll-to-bottom-on-input} is
-non-@code{nil}, insertion and yank commands scroll the selected window
-to the bottom before inserting. The default is @code{nil}.
-
-@vindex comint-scroll-show-maximum-output
- If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then
-arrival of output when point is at the end tries to scroll the last
-line of text to the bottom line of the window, showing as much useful
-text as possible. (This mimics the scrolling behavior of most
-terminals.) The default is @code{t}.
-
-@vindex comint-move-point-for-output
- By setting @code{comint-move-point-for-output}, you can opt for
-having point jump to the end of the buffer whenever output arrives---no
-matter where in the buffer point was before. If the value is
-@code{this}, point jumps in the selected window. If the value is
-@code{all}, point jumps in each window that shows the Comint buffer. If
-the value is @code{other}, point jumps in all nonselected windows that
-show the current buffer. The default value is @code{nil}, which means
-point does not jump to the end.
-
-@vindex comint-prompt-read-only
- If you set @code{comint-prompt-read-only}, the prompts in the Comint
-buffer are read-only.
-
-@vindex comint-input-ignoredups
- The variable @code{comint-input-ignoredups} controls whether successive
-identical inputs are stored in the input history. A non-@code{nil}
-value means to omit an input that is the same as the previous input.
-The default is @code{nil}, which means to store each input even if it is
-equal to the previous input.
-
-@vindex comint-completion-addsuffix
-@vindex comint-completion-recexact
-@vindex comint-completion-autolist
- Three variables customize file name completion. The variable
-@code{comint-completion-addsuffix} controls whether completion inserts a
-space or a slash to indicate a fully completed file or directory name
-(non-@code{nil} means do insert a space or slash).
-@code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB}
-to choose the shortest possible completion if the usual Emacs completion
-algorithm cannot add even a single character.
-@code{comint-completion-autolist}, if non-@code{nil}, says to list all
-the possible completions whenever completion is not exact.
-
-@vindex shell-completion-execonly
- Command completion normally considers only executable files.
-If you set @code{shell-completion-execonly} to @code{nil},
-it considers nonexecutable files as well.
-
-@findex shell-pushd-tohome
-@findex shell-pushd-dextract
-@findex shell-pushd-dunique
- You can configure the behavior of @samp{pushd}. Variables control
-whether @samp{pushd} behaves like @samp{cd} if no argument is given
-(@code{shell-pushd-tohome}), pop rather than rotate with a numeric
-argument (@code{shell-pushd-dextract}), and only add directories to the
-directory stack if they are not already on it
-(@code{shell-pushd-dunique}). The values you choose should match the
-underlying shell, of course.
-
- If you want Shell mode to handle color output from shell commands,
-you can enable ANSI Color mode. Here is how to do this:
-
-@example
-(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)
-@end example
-
-@node Terminal emulator
-@subsection Emacs Terminal Emulator
-@findex term
-
- To run a subshell in a terminal emulator, putting its typescript in
-an Emacs buffer, use @kbd{M-x term}. This creates (or reuses) a
-buffer named @samp{*terminal*}, and runs a subshell with input coming
-from your keyboard, and output going to that buffer.
-
- The terminal emulator uses Term mode, which has two input modes. In
-line mode, Term basically acts like Shell mode; see @ref{Shell Mode}.
-
- In char mode, each character is sent directly to the inferior
-subshell, as ``terminal input.'' Any ``echoing'' of your input is the
-responsibility of the subshell. The sole exception is the terminal
-escape character, which by default is @kbd{C-c} (@pxref{Term Mode}).
-Any ``terminal output'' from the subshell goes into the buffer,
-advancing point.
-
- Some programs (such as Emacs itself) need to control the appearance
-on the terminal screen in detail. They do this by sending special
-control codes. The exact control codes needed vary from terminal to
-terminal, but nowadays most terminals and terminal emulators
-(including @code{xterm}) understand the ANSI-standard (VT100-style)
-escape sequences. Term mode recognizes these escape sequences, and
-handles each one appropriately, changing the buffer so that the
-appearance of the window matches what it would be on a real terminal.
-You can actually run Emacs inside an Emacs Term window.
-
- The file name used to load the subshell is determined the same way
-as for Shell mode. To make multiple terminal emulators, rename the
-buffer @samp{*terminal*} to something different using @kbd{M-x
-rename-uniquely}, just as with Shell mode.
-
- Unlike Shell mode, Term mode does not track the current directory by
-examining your input. But some shells can tell Term what the current
-directory is. This is done automatically by @code{bash} version 1.15
-and later.
-
-@node Term Mode
-@subsection Term Mode
-@cindex Term mode
-@cindex mode, Term
-
- The terminal emulator uses Term mode, which has two input modes. In
-line mode, Term basically acts like Shell mode; see @ref{Shell Mode}.
-In char mode, each character is sent directly to the inferior
-subshell, except for the Term escape character, normally @kbd{C-c}.
-
- To switch between line and char mode, use these commands:
-
-@table @kbd
-@kindex C-c C-j @r{(Term mode)}
-@findex term-char-mode
-@item C-c C-j
-Switch to line mode. Do nothing if already in line mode.
-
-@kindex C-c C-k @r{(Term mode)}
-@findex term-line-mode
-@item C-c C-k
-Switch to char mode. Do nothing if already in char mode.
-@end table
-
- The following commands are only available in char mode:
-
-@table @kbd
-@item C-c C-c
-Send a literal @key{C-c} to the sub-shell.
-
-@item C-c @var{char}
-This is equivalent to @kbd{C-x @var{char}} in normal Emacs. For
-example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which
-is normally @samp{other-window}.
-@end table
-
-@node Paging in Term
-@subsection Page-At-A-Time Output
-@cindex page-at-a-time
-
- Term mode has a page-at-a-time feature. When enabled it makes
-output pause at the end of each screenful.
-
-@table @kbd
-@kindex C-c C-q @r{(Term mode)}
-@findex term-pager-toggle
-@item C-c C-q
-Toggle the page-at-a-time feature. This command works in both line
-and char modes. When page-at-a-time is enabled, the mode-line
-displays the word @samp{page}.
-@end table
-
- With page-at-a-time enabled, whenever Term receives more than a
-screenful of output since your last input, it pauses, displaying
-@samp{**MORE**} in the mode-line. Type @key{SPC} to display the next
-screenful of output. Type @kbd{?} to see your other options. The
-interface is similar to the @code{more} program.
-
-@node Remote Host
-@subsection Remote Host Shell
-@cindex remote host
-@cindex connecting to remote host
-@cindex Telnet
-@cindex Rlogin
-
- You can login to a remote computer, using whatever commands you
-would from a regular terminal (e.g.@: using the @code{telnet} or
-@code{rlogin} commands), from a Term window.
-
- A program that asks you for a password will normally suppress
-echoing of the password, so the password will not show up in the
-buffer. This will happen just as if you were using a real terminal,
-if the buffer is in char mode. If it is in line mode, the password is
-temporarily visible, but will be erased when you hit return. (This
-happens automatically; there is no special password processing.)
-
- When you log in to a different machine, you need to specify the type
-of terminal you're using, by setting the @env{TERM} environment
-variable in the environment for the remote login command. (If you use
-bash, you do that by writing the variable assignment before the remote
-login command, without separating comma.) Terminal types @samp{ansi}
-or @samp{vt100} will work on most systems.
-
-@c If you are talking to a Bourne-compatible
-@c shell, and your system understands the @env{TERMCAP} variable,
-@c you can use the command @kbd{M-x shell-send-termcap}, which
-@c sends a string specifying the terminal type and size.
-@c (This command is also useful after the window has changed size.)
-
-@c You can of course run @samp{gdb} on that remote computer. One useful
-@c trick: If you invoke gdb with the @code{--fullname} option,
-@c it will send special commands to Emacs that will cause Emacs to
-@c pop up the source files you're debugging. This will work
-@c whether or not gdb is running on a different computer than Emacs,
-@c as long as Emacs can access the source files specified by gdb.
-
-@ignore
- You cannot log in to a remote computer using the Shell mode.
-@c (This will change when Shell is re-written to use Term.)
-Instead, Emacs provides two commands for logging in to another computer
-and communicating with it through an Emacs buffer using Comint mode:
-
-@table @kbd
-@item M-x telnet @key{RET} @var{hostname} @key{RET}
-Set up a Telnet connection to the computer named @var{hostname}.
-@item M-x rlogin @key{RET} @var{hostname} @key{RET}
-Set up an Rlogin connection to the computer named @var{hostname}.
-@end table
-
-@findex telnet
- Use @kbd{M-x telnet} to set up a Telnet connection to another
-computer. (Telnet is the standard Internet protocol for remote login.)
-It reads the host name of the other computer as an argument with the
-minibuffer. Once the connection is established, talking to the other
-computer works like talking to a subshell: you can edit input with the
-usual Emacs commands, and send it a line at a time by typing @key{RET}.
-The output is inserted in the Telnet buffer interspersed with the input.
-
-@findex rlogin
-@vindex rlogin-explicit-args
- Use @kbd{M-x rlogin} to set up an Rlogin connection. Rlogin is
-another remote login communication protocol, essentially much like the
-Telnet protocol but incompatible with it, and supported only by certain
-systems. Rlogin's advantages are that you can arrange not to have to
-give your user name and password when communicating between two machines
-you frequently use, and that you can make an 8-bit-clean connection.
-(To do that in Emacs, set @code{rlogin-explicit-args} to @code{("-8")}
-before you run Rlogin.)
-
- @kbd{M-x rlogin} sets up the default file directory of the Emacs
-buffer to access the remote host via FTP (@pxref{File Names}), and it
-tracks the shell commands that change the current directory, just like
-Shell mode.
-
-@findex rlogin-directory-tracking-mode
- There are two ways of doing directory tracking in an Rlogin
-buffer---either with remote directory names
-@file{/@var{host}:@var{dir}/} or with local names (that works if the
-``remote'' machine shares file systems with your machine of origin).
-You can use the command @code{rlogin-directory-tracking-mode} to switch
-modes. No argument means use remote directory names, a positive
-argument means use local names, and a negative argument means turn
-off directory tracking.
-
-@end ignore
-
-@node Emacs Server, Printing, Shell, Top
-@section Using Emacs as a Server
-@pindex emacsclient
-@cindex Emacs as a server
-@cindex server, using Emacs as
-@cindex @env{EDITOR} environment variable
-
- Various programs such as @code{mail} can invoke your choice of editor
-to edit a particular piece of text, such as a message that you are
-sending. By convention, most of these programs use the environment
-variable @env{EDITOR} to specify which editor to run. If you set
-@env{EDITOR} to @samp{emacs}, they invoke Emacs---but in an
-inconvenient fashion, by starting a new, separate Emacs process. This
-is inconvenient because it takes time and because the new Emacs process
-doesn't share the buffers with any existing Emacs process.
-
- You can arrange to use your existing Emacs process as the editor for
-programs like @code{mail} by using the Emacs client program and the
-server that is part of Emacs. Here is how.
-
-@cindex @env{TEXEDIT} environment variable
-@findex server-start
- First, the preparations. Within Emacs, call the function
-@code{server-start}. (Your @file{.emacs} init file can do this
-automatically if you add the expression @code{(server-start)} to it,
-see @ref{Init File}.) Then, outside Emacs, set the @env{EDITOR}
-environment variable to @samp{emacsclient}. (Note that some programs
-use a different environment variable; for example, to make @TeX{} use
-@samp{emacsclient}, you should set the @env{TEXEDIT} environment
-variable to @samp{emacsclient +%d %s}.)
-
-@pindex emacs.bash
-@cindex Bash command to use Emacs server
- As an alternative to using @code{emacsclient}, the file
-@file{etc/emacs.bash} defines a Bash command @code{edit} which will
-communicate with a running Emacs session, or start one if none exist.
-
-@kindex C-x #
-@findex server-edit
- Now, whenever any program invokes your specified @env{EDITOR}
-program, the effect is to send a message to your principal Emacs telling
-it to visit a file. (That's what the program @code{emacsclient} does.)
-Emacs displays the buffer immediately and you can immediately begin
-editing it in the already running Emacs session.
-
- When you've finished editing that buffer, type @kbd{C-x #}
-(@code{server-edit}). This saves the file and sends a message back to
-the @code{emacsclient} program telling it to exit. The programs that
-use @env{EDITOR} wait for the ``editor'' (actually, @code{emacsclient})
-to exit. @kbd{C-x #} also checks for other pending external requests
-to edit various files, and selects the next such file.
-
- You can switch to a server buffer manually if you wish; you don't
-have to arrive at it with @kbd{C-x #}. But @kbd{C-x #} is the way to
-say that you are finished with one.
-
-@vindex server-kill-new-buffers
-@vindex server-temp-file-regexp
- Finishing with a server buffer also kills the buffer, unless it
-already existed in the Emacs session before the server asked to create
-it. However, if you set @code{server-kill-new-buffers} to @code{nil},
-then a different criterion is used: finishing with a server buffer
-kills it if the file name matches the regular expression
-@code{server-temp-file-regexp}. This is set up to distinguish certain
-``temporary'' files.
-
-@vindex server-window
- If you set the variable @code{server-window} to a window or a frame,
-@kbd{C-x #} displays the server buffer in that window or in that frame.
-
-@vindex server-name
- You can run multiple Emacs servers on the same machine by giving
-each one a unique ``server name'', using the variable
-@code{server-name}. For example, @kbd{M-x set-variable @key{RET}
-server-name @key{RET} foo @key{RET}} sets the server name to
-@samp{foo}. The @code{emacsclient} program can specify a server by
-name using the @samp{-s} option. @xref{Invoking emacsclient}.
-
- While @code{mail} or another application is waiting for
-@code{emacsclient} to finish, @code{emacsclient} does not read terminal
-input. So the terminal that @code{mail} was using is effectively
-blocked for the duration. In order to edit with your principal Emacs,
-you need to be able to use it without using that terminal. There are
-three ways to do this:
-
-@itemize @bullet
-@item
-Using a window system, run @code{mail} and the principal Emacs in two
-separate windows. While @code{mail} is waiting for @code{emacsclient},
-the window where it was running is blocked, but you can use Emacs by
-switching windows.
-
-@item
-Using virtual terminals, run @code{mail} in one virtual terminal
-and run Emacs in another.
-
-@item
-Use Shell mode or Term mode in Emacs to run the other program such as
-@code{mail}; then, @code{emacsclient} blocks only the subshell under
-Emacs, and you can still use Emacs to edit the file.
-@end itemize
-
- If you run @code{emacsclient} with the option @samp{--no-wait}, it
-returns immediately without waiting for you to ``finish'' the buffer
-in Emacs. Note that server buffers created in this way are not killed
-automatically when you finish with them.
-
-@menu
-* Invoking emacsclient:: Emacs client startup options.
-@end menu
-
-@node Invoking emacsclient,, Emacs Server, Emacs Server
-@subsection Invoking @code{emacsclient}
-@cindex @code{emacsclient} invocation and options
-
- To run the @code{emacsclient} program, specify file names as arguments,
-and optionally line numbers as well, like this:
-
-@example
-emacsclient @r{@{}@r{[}+@var{line}@r{[}@var{column}@r{]}@r{]} @var{filename}@r{@}}@dots{}
-@end example
-
-@noindent
-This tells Emacs to visit each of the specified files; if you specify a
-line number for a certain file, Emacs moves to that line in the file.
-If you specify a column number as well, Emacs puts point on that column
-in the line.
-
- Ordinarily, @code{emacsclient} does not return until you use the
-@kbd{C-x #} command on each of these buffers. When that happens,
-Emacs sends a message to the @code{emacsclient} program telling it to
-return.
-
- If you invoke @code{emacsclient} for more than one file, the
-additional client buffers are buried at the bottom of the buffer list
-(@pxref{Buffers}). If you call @kbd{C-x #} after you are done editing
-a client buffer, the next client buffer is automatically selected.
-
- But if you use the option @samp{-n} or @samp{--no-wait} when running
-@code{emacsclient}, then it returns immediately. (You can take as
-long as you like to edit the files in Emacs.)
-
- The option @samp{-a @var{command}} or
-@samp{--alternate-editor=@var{command}} specifies a command to run if
-@code{emacsclient} fails to contact Emacs. This is useful when
-running @code{emacsclient} in a script. For example, the following
-setting for the @env{EDITOR} environment variable will always give you
-an editor, even if no Emacs server is running:
-
-@example
-EDITOR="emacsclient --alternate-editor emacs +%d %s"
-@end example
-
-@noindent
-@cindex @env{ALTERNATE_EDITOR} environment variable
-The environment variable @env{ALTERNATE_EDITOR} has the same effect, with
-the value of the @samp{--alternate-editor} option taking precedence.
-
-If you use several displays, you can tell Emacs on which display to
-open the given files with the @samp{-d @var{display}} or
-@samp{--display=@var{display}} option to @code{emacsclient}. This is
-handy when connecting from home to an Emacs session running on your
-machine at your workplace.
-
-If there is more than one Emacs server running, you can specify a
-server name with the @samp{-s @var{name}} or
-@samp{--socket-name=@var{name}} option to @code{emacsclient}. (This
-option is not supported on MS-Windows.)
-
-You can also use @code{emacsclient} to execute any piece of Emacs Lisp
-code, using the @samp{-e} or @samp{--eval} option. When this option
-is given, the rest of the arguments is interpreted as a list of
-expressions to evaluate, not a list of files to visit.
-
-@cindex @env{EMACS_SERVER_FILE} environment variable
-When you start the Emacs server (by calling @code{server-start}),
-Emacs creates a file with information about TCP connection to the
-server: the host where Emacs is running, the port where it is
-listening, and an authentication string. @code{emacsclient} uses this
-information if it needs to connect to the server via TCP. By default,
-the file goes in the @file{~/.emacs.d/server/} directory@footnote{On
-MS-Windows, if @env{HOME} is not set or the TCP configuration file
-cannot be found there, Emacs also looks for the file in the
-@file{.emacs.d/server/} subdirectory of the directory pointed to by
-the @env{APPDATA} environment variable.}. You can specify the file
-name to use with the @samp{-f @var{file}} or
-@samp{--server-file=@var{file}} options, or by setting
-@env{EMACS_SERVER_FILE} environment variable to the file name.
-
-@node Printing, Sorting, Emacs Server, Top
-@section Printing Hard Copies
-@cindex hardcopy
-@cindex printing
-
- Emacs provides commands for printing hard copies of either an entire
-buffer or just part of one, with or without page headers. You can
-invoke the printing commands directly, as detailed in the following
-section, or using the @samp{File} menu on the menu bar. See also the
-hardcopy commands of Dired (@pxref{Misc File Ops}) and the diary
-(@pxref{Displaying the Diary}).
-
-@table @kbd
-@item M-x print-buffer
-Print hardcopy of current buffer with page headings containing the file
-name and page number.
-@item M-x lpr-buffer
-Print hardcopy of current buffer without page headings.
-@item M-x print-region
-Like @code{print-buffer} but print only the current region.
-@item M-x lpr-region
-Like @code{lpr-buffer} but print only the current region.
-@end table
-
-@findex print-buffer
-@findex print-region
-@findex lpr-buffer
-@findex lpr-region
-@vindex lpr-switches
- The hardcopy commands (aside from the PostScript commands) pass extra
-switches to the @code{lpr} program based on the value of the variable
-@code{lpr-switches}. Its value should be a list of strings, each string
-an option starting with @samp{-}. For example, to specify a line width
-of 80 columns for all the printing you do in Emacs, set
-@code{lpr-switches} like this:
-
-@example
-(setq lpr-switches '("-w80"))
-@end example
-
-@vindex printer-name
- You can specify the printer to use by setting the variable
-@code{printer-name}.
-
-@vindex lpr-headers-switches
-@vindex lpr-commands
-@vindex lpr-add-switches
- The variable @code{lpr-command} specifies the name of the printer
-program to run; the default value depends on your operating system type.
-On most systems, the default is @code{"lpr"}. The variable
-@code{lpr-headers-switches} similarly specifies the extra switches to
-use to make page headers. The variable @code{lpr-add-switches} controls
-whether to supply @samp{-T} and @samp{-J} options (suitable for
-@code{lpr}) to the printer program: @code{nil} means don't add them.
-@code{lpr-add-switches} should be @code{nil} if your printer program is
-not compatible with @code{lpr}.
-
-@menu
-* PostScript:: Printing buffers or regions as PostScript.
-* PostScript Variables:: Customizing the PostScript printing commands.
-* Printing Package:: An optional advanced printing interface.
-@end menu
-
-@node PostScript, PostScript Variables,, Printing
-@section PostScript Hardcopy
-
- These commands convert buffer contents to PostScript,
-either printing it or leaving it in another Emacs buffer.
-
-@table @kbd
-@item M-x ps-print-buffer
-Print hardcopy of the current buffer in PostScript form.
-@item M-x ps-print-region
-Print hardcopy of the current region in PostScript form.
-@item M-x ps-print-buffer-with-faces
-Print hardcopy of the current buffer in PostScript form, showing the
-faces used in the text by means of PostScript features.
-@item M-x ps-print-region-with-faces
-Print hardcopy of the current region in PostScript form, showing the
-faces used in the text.
-@item M-x ps-spool-buffer
-Generate PostScript for the current buffer text.
-@item M-x ps-spool-region
-Generate PostScript for the current region.
-@item M-x ps-spool-buffer-with-faces
-Generate PostScript for the current buffer, showing the faces used.
-@item M-x ps-spool-region-with-faces
-Generate PostScript for the current region, showing the faces used.
-@item M-x handwrite
-Generates/prints PostScript for the current buffer as if handwritten.
-@end table
-
-@findex ps-print-region
-@findex ps-print-buffer
-@findex ps-print-region-with-faces
-@findex ps-print-buffer-with-faces
- The PostScript commands, @code{ps-print-buffer} and
-@code{ps-print-region}, print buffer contents in PostScript form. One
-command prints the entire buffer; the other, just the region. The
-corresponding @samp{-with-faces} commands,
-@code{ps-print-buffer-with-faces} and @code{ps-print-region-with-faces},
-use PostScript features to show the faces (fonts and colors) in the text
-properties of the text being printed.
-
- If you are using a color display, you can print a buffer of program
-code with color highlighting by turning on Font-Lock mode in that
-buffer, and using @code{ps-print-buffer-with-faces}.
-
-@findex ps-spool-region
-@findex ps-spool-buffer
-@findex ps-spool-region-with-faces
-@findex ps-spool-buffer-with-faces
- The commands whose names have @samp{spool} instead of @samp{print}
-generate the PostScript output in an Emacs buffer instead of sending
-it to the printer.
-
-@findex handwrite
-@cindex handwriting
-@kbd{M-x handwrite} is more frivolous. It generates a PostScript
-rendition of the current buffer as a cursive handwritten document. It
-can be customized in group @code{handwrite}. This function only
-supports ISO 8859-1 characters.
-
-@ifnottex
- The following section describes variables for customizing these commands.
-@end ifnottex
-
-@node PostScript Variables, Printing Package, PostScript, Printing
-@section Variables for PostScript Hardcopy
-
-@vindex ps-lpr-command
-@vindex ps-lpr-switches
-@vindex ps-printer-name
- All the PostScript hardcopy commands use the variables
-@code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print
-the output. @code{ps-lpr-command} specifies the command name to run,
-@code{ps-lpr-switches} specifies command line options to use, and
-@code{ps-printer-name} specifies the printer. If you don't set the
-first two variables yourself, they take their initial values from
-@code{lpr-command} and @code{lpr-switches}. If @code{ps-printer-name}
-is @code{nil}, @code{printer-name} is used.
-
-@vindex ps-print-header
- The variable @code{ps-print-header} controls whether these commands
-add header lines to each page---set it to @code{nil} to turn headers
-off.
-
-@cindex color emulation on black-and-white printers
-@vindex ps-print-color-p
- If your printer doesn't support colors, you should turn off color
-processing by setting @code{ps-print-color-p} to @code{nil}. By
-default, if the display supports colors, Emacs produces hardcopy output
-with color information; on black-and-white printers, colors are emulated
-with shades of gray. This might produce illegible output, even if your
-screen colors only use shades of gray.
-
-@vindex ps-use-face-background
- By default, PostScript printing ignores the background colors of the
-faces, unless the variable @code{ps-use-face-background} is
-non-@code{nil}. This is to avoid unwanted interference with the zebra
-stripes and background image/text.
-
-@vindex ps-paper-type
-@vindex ps-page-dimensions-database
- The variable @code{ps-paper-type} specifies which size of paper to
-format for; legitimate values include @code{a4}, @code{a3},
-@code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger},
-@code{legal}, @code{letter}, @code{letter-small}, @code{statement},
-@code{tabloid}. The default is @code{letter}. You can define
-additional paper sizes by changing the variable
-@code{ps-page-dimensions-database}.
-
-@vindex ps-landscape-mode
- The variable @code{ps-landscape-mode} specifies the orientation of
-printing on the page. The default is @code{nil}, which stands for
-``portrait'' mode. Any non-@code{nil} value specifies ``landscape''
-mode.
-
-@vindex ps-number-of-columns
- The variable @code{ps-number-of-columns} specifies the number of
-columns; it takes effect in both landscape and portrait mode. The
-default is 1.
-
-@vindex ps-font-family
-@vindex ps-font-size
-@vindex ps-font-info-database
- The variable @code{ps-font-family} specifies which font family to use
-for printing ordinary text. Legitimate values include @code{Courier},
-@code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and
-@code{Times}. The variable @code{ps-font-size} specifies the size of
-the font for ordinary text. It defaults to 8.5 points.
-
-@vindex ps-multibyte-buffer
-@cindex Intlfonts for PostScript printing
-@cindex fonts for PostScript printing
- Emacs supports more scripts and characters than a typical PostScript
-printer. Thus, some of the characters in your buffer might not be
-printable using the fonts built into your printer. You can augment
-the fonts supplied with the printer with those from the GNU Intlfonts
-package, or you can instruct Emacs to use Intlfonts exclusively. The
-variable @code{ps-multibyte-buffer} controls this: the default value,
-@code{nil}, is appropriate for printing @acronym{ASCII} and Latin-1
-characters; a value of @code{non-latin-printer} is for printers which
-have the fonts for @acronym{ASCII}, Latin-1, Japanese, and Korean
-characters built into them. A value of @code{bdf-font} arranges for
-the BDF fonts from the Intlfonts package to be used for @emph{all}
-characters. Finally, a value of @code{bdf-font-except-latin}
-instructs the printer to use built-in fonts for @acronym{ASCII} and Latin-1
-characters, and Intlfonts BDF fonts for the rest.
-
-@vindex bdf-directory-list
- To be able to use the BDF fonts, Emacs needs to know where to find
-them. The variable @code{bdf-directory-list} holds the list of
-directories where Emacs should look for the fonts; the default value
-includes a single directory @file{/usr/local/share/emacs/fonts/bdf}.
-
- Many other customization variables for these commands are defined and
-described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}.
-
-@node Printing Package,, PostScript Variables, Printing
-@section Printing Package
-@cindex Printing package
-
- The basic Emacs facilities for printing hardcopy can be extended
-using the Printing package. This provides an easy-to-use interface
-for choosing what to print, previewing PostScript files before
-printing, and setting various printing options such as print headers,
-landscape or portrait modes, duplex modes, and so forth. On GNU/Linux
-or Unix systems, the Printing package relies on the @file{gs} and
-@file{gv} utilities, which are distributed as part of the GhostScript
-program. On MS-Windows, the @file{gstools} port of Ghostscript can be
-used.
-
-@findex pr-interface
- To use the Printing package, add @code{(require 'printing)} to your
-init file (@pxref{Init File}), followed by @code{(pr-update-menus)}.
-This function replaces the usual printing commands in the menu bar
-with a @samp{Printing} submenu that contains various printing options.
-You can also type @kbd{M-x pr-interface RET}; this creates a
-@samp{*Printing Interface*} buffer, similar to a customization buffer,
-where you can set the printing options. After selecting what and how
-to print, you start the print job using the @samp{Print} button (click
-@kbd{mouse-2} on it, or move point over it and type @kbd{RET}). For
-further information on the various options, use the @samp{Interface
-Help} button.
-
-@node Sorting, Narrowing, Printing, Top
-@section Sorting Text
-@cindex sorting
-
- Emacs provides several commands for sorting text in the buffer. All
-operate on the contents of the region.
-They divide the text of the region into many @dfn{sort records},
-identify a @dfn{sort key} for each record, and then reorder the records
-into the order determined by the sort keys. The records are ordered so
-that their keys are in alphabetical order, or, for numeric sorting, in
-numeric order. In alphabetic sorting, all upper-case letters `A' through
-`Z' come before lower-case `a', in accord with the @acronym{ASCII} character
-sequence.
-
- The various sort commands differ in how they divide the text into sort
-records and in which part of each record is used as the sort key. Most of
-the commands make each line a separate sort record, but some commands use
-paragraphs or pages as sort records. Most of the sort commands use each
-entire sort record as its own sort key, but some use only a portion of the
-record as the sort key.
-
-@findex sort-lines
-@findex sort-paragraphs
-@findex sort-pages
-@findex sort-fields
-@findex sort-numeric-fields
-@vindex sort-numeric-base
-@table @kbd
-@item M-x sort-lines
-Divide the region into lines, and sort by comparing the entire
-text of a line. A numeric argument means sort into descending order.
-
-@item M-x sort-paragraphs
-Divide the region into paragraphs, and sort by comparing the entire
-text of a paragraph (except for leading blank lines). A numeric
-argument means sort into descending order.
-
-@item M-x sort-pages
-Divide the region into pages, and sort by comparing the entire
-text of a page (except for leading blank lines). A numeric
-argument means sort into descending order.
-
-@item M-x sort-fields
-Divide the region into lines, and sort by comparing the contents of
-one field in each line. Fields are defined as separated by
-whitespace, so the first run of consecutive non-whitespace characters
-in a line constitutes field 1, the second such run constitutes field
-2, etc.
-
-Specify which field to sort by with a numeric argument: 1 to sort by
-field 1, etc. A negative argument means count fields from the right
-instead of from the left; thus, minus 1 means sort by the last field.
-If several lines have identical contents in the field being sorted, they
-keep the same relative order that they had in the original buffer.
-
-@item M-x sort-numeric-fields
-Like @kbd{M-x sort-fields} except the specified field is converted
-to an integer for each line, and the numbers are compared. @samp{10}
-comes before @samp{2} when considered as text, but after it when
-considered as a number. By default, numbers are interpreted according
-to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or
-@samp{0} are interpreted as hexadecimal and octal, respectively.
-
-@item M-x sort-columns
-Like @kbd{M-x sort-fields} except that the text within each line
-used for comparison comes from a fixed range of columns. See below
-for an explanation.
-
-@item M-x reverse-region
-Reverse the order of the lines in the region. This is useful for
-sorting into descending order by fields or columns, since those sort
-commands do not have a feature for doing that.
-@end table
-
- For example, if the buffer contains this:
-
-@smallexample
-On systems where clash detection (locking of files being edited) is
-implemented, Emacs also checks the first time you modify a buffer
-whether the file has changed on disk since it was last visited or
-saved. If it has, you are asked to confirm that you want to change
-the buffer.
-@end smallexample
-
-@noindent
-applying @kbd{M-x sort-lines} to the entire buffer produces this:
-
-@smallexample
-On systems where clash detection (locking of files being edited) is
-implemented, Emacs also checks the first time you modify a buffer
-saved. If it has, you are asked to confirm that you want to change
-the buffer.
-whether the file has changed on disk since it was last visited or
-@end smallexample
-
-@noindent
-where the upper-case @samp{O} sorts before all lower-case letters. If
-you use @kbd{C-u 2 M-x sort-fields} instead, you get this:
-
-@smallexample
-implemented, Emacs also checks the first time you modify a buffer
-saved. If it has, you are asked to confirm that you want to change
-the buffer.
-On systems where clash detection (locking of files being edited) is
-whether the file has changed on disk since it was last visited or
-@end smallexample
-
-@noindent
-where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer},
-@samp{systems} and @samp{the}.
-
-@findex sort-columns
- @kbd{M-x sort-columns} requires more explanation. You specify the
-columns by putting point at one of the columns and the mark at the other
-column. Because this means you cannot put point or the mark at the
-beginning of the first line of the text you want to sort, this command
-uses an unusual definition of ``region'': all of the line point is in is
-considered part of the region, and so is all of the line the mark is in,
-as well as all the lines in between.
-
- For example, to sort a table by information found in columns 10 to 15,
-you could put the mark on column 10 in the first line of the table, and
-point on column 15 in the last line of the table, and then run
-@code{sort-columns}. Equivalently, you could run it with the mark on
-column 15 in the first line and point on column 10 in the last line.
-
- This can be thought of as sorting the rectangle specified by point and
-the mark, except that the text on each line to the left or right of the
-rectangle moves along with the text inside the rectangle.
-@xref{Rectangles}.
-
-@vindex sort-fold-case
- Many of the sort commands ignore case differences when comparing, if
-@code{sort-fold-case} is non-@code{nil}.
-
-@node Narrowing, Two-Column, Sorting, Top
-@section Narrowing
-@cindex widening
-@cindex restriction
-@cindex narrowing
-@cindex accessible portion
-
- @dfn{Narrowing} means focusing in on some portion of the buffer,
-making the rest temporarily inaccessible. The portion which you can
-still get to is called the @dfn{accessible portion}. Canceling the
-narrowing, which makes the entire buffer once again accessible, is
-called @dfn{widening}. The bounds of narrowing in effect in a buffer
-are called the buffer's @dfn{restriction}.
-
- Narrowing can make it easier to concentrate on a single subroutine or
-paragraph by eliminating clutter. It can also be used to limit the
-range of operation of a replace command or repeating keyboard macro.
-
-@table @kbd
-@item C-x n n
-Narrow down to between point and mark (@code{narrow-to-region}).
-@item C-x n w
-Widen to make the entire buffer accessible again (@code{widen}).
-@item C-x n p
-Narrow down to the current page (@code{narrow-to-page}).
-@item C-x n d
-Narrow down to the current defun (@code{narrow-to-defun}).
-@end table
-
- When you have narrowed down to a part of the buffer, that part appears
-to be all there is. You can't see the rest, you can't move into it
-(motion commands won't go outside the accessible part), you can't change
-it in any way. However, it is not gone, and if you save the file all
-the inaccessible text will be saved. The word @samp{Narrow} appears in
-the mode line whenever narrowing is in effect.
-
-@kindex C-x n n
-@findex narrow-to-region
- The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}).
-It sets the current buffer's restrictions so that the text in the current
-region remains accessible, but all text before the region or after the
-region is inaccessible. Point and mark do not change.
-
-@kindex C-x n p
-@findex narrow-to-page
-@kindex C-x n d
-@findex narrow-to-defun
- Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow
-down to the current page. @xref{Pages}, for the definition of a page.
-@kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun
-containing point (@pxref{Defuns}).
-
-@kindex C-x n w
-@findex widen
- The way to cancel narrowing is to widen with @kbd{C-x n w}
-(@code{widen}). This makes all text in the buffer accessible again.
-
- You can get information on what part of the buffer you are narrowed down
-to using the @kbd{C-x =} command. @xref{Position Info}.
-
- Because narrowing can easily confuse users who do not understand it,
-@code{narrow-to-region} is normally a disabled command. Attempting to use
-this command asks for confirmation and gives you the option of enabling it;
-if you enable the command, confirmation will no longer be required for
-it. @xref{Disabling}.
-
-@node Two-Column, Editing Binary Files, Narrowing, Top
-@section Two-Column Editing
-@cindex two-column editing
-@cindex splitting columns
-@cindex columns, splitting
-
- Two-column mode lets you conveniently edit two side-by-side columns of
-text. It uses two side-by-side windows, each showing its own
-buffer.
-
- There are three ways to enter two-column mode:
-
-@table @asis
-@item @kbd{@key{F2} 2} or @kbd{C-x 6 2}
-@kindex F2 2
-@kindex C-x 6 2
-@findex 2C-two-columns
-Enter two-column mode with the current buffer on the left, and on the
-right, a buffer whose name is based on the current buffer's name
-(@code{2C-two-columns}). If the right-hand buffer doesn't already
-exist, it starts out empty; the current buffer's contents are not
-changed.
-
-This command is appropriate when the current buffer is empty or contains
-just one column and you want to add another column.
-
-@item @kbd{@key{F2} s} or @kbd{C-x 6 s}
-@kindex F2 s
-@kindex C-x 6 s
-@findex 2C-split
-Split the current buffer, which contains two-column text, into two
-buffers, and display them side by side (@code{2C-split}). The current
-buffer becomes the left-hand buffer, but the text in the right-hand
-column is moved into the right-hand buffer. The current column
-specifies the split point. Splitting starts with the current line and
-continues to the end of the buffer.
-
-This command is appropriate when you have a buffer that already contains
-two-column text, and you wish to separate the columns temporarily.
-
-@item @kbd{@key{F2} b @var{buffer} @key{RET}}
-@itemx @kbd{C-x 6 b @var{buffer} @key{RET}}
-@kindex F2 b
-@kindex C-x 6 b
-@findex 2C-associate-buffer
-Enter two-column mode using the current buffer as the left-hand buffer,
-and using buffer @var{buffer} as the right-hand buffer
-(@code{2C-associate-buffer}).
-@end table
-
- @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which
-is a string that appears on each line between the two columns. You can
-specify the width of the separator with a numeric argument to
-@kbd{@key{F2} s}; that many characters, before point, constitute the
-separator string. By default, the width is 1, so the column separator
-is the character before point.
-
- When a line has the separator at the proper place, @kbd{@key{F2} s}
-puts the text after the separator into the right-hand buffer, and
-deletes the separator. Lines that don't have the column separator at
-the proper place remain unsplit; they stay in the left-hand buffer, and
-the right-hand buffer gets an empty line to correspond. (This is the
-way to write a line that ``spans both columns while in two-column
-mode'': write it in the left-hand buffer, and put an empty line in the
-right-hand buffer.)
-
-@kindex F2 RET
-@kindex C-x 6 RET
-@findex 2C-newline
- The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}}
-(@code{2C-newline}) inserts a newline in each of the two buffers at
-corresponding positions. This is the easiest way to add a new line to
-the two-column text while editing it in split buffers.
-
-@kindex F2 1
-@kindex C-x 6 1
-@findex 2C-merge
- When you have edited both buffers as you wish, merge them with
-@kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the
-text from the right-hand buffer as a second column in the other buffer.
-To go back to two-column editing, use @kbd{@key{F2} s}.
-
-@kindex F2 d
-@kindex C-x 6 d
-@findex 2C-dissociate
- Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers,
-leaving each as it stands (@code{2C-dissociate}). If the other buffer,
-the one not current when you type @kbd{@key{F2} d}, is empty,
-@kbd{@key{F2} d} kills it.
-
-@node Editing Binary Files, Saving Emacs Sessions, Two-Column, Top
-@section Editing Binary Files
-
-@cindex Hexl mode
-@cindex mode, Hexl
-@cindex editing binary files
-@cindex hex editing
- There is a special major mode for editing binary files: Hexl mode. To
-use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit
-the file. This command converts the file's contents to hexadecimal and
-lets you edit the translation. When you save the file, it is converted
-automatically back to binary.
-
- You can also use @kbd{M-x hexl-mode} to translate an existing buffer
-into hex. This is useful if you visit a file normally and then discover
-it is a binary file.
-
- Ordinary text characters overwrite in Hexl mode. This is to reduce
-the risk of accidentally spoiling the alignment of data in the file.
-There are special commands for insertion. Here is a list of the
-commands of Hexl mode:
-
-@c I don't think individual index entries for these commands are useful--RMS.
-@table @kbd
-@item C-M-d
-Insert a byte with a code typed in decimal.
-
-@item C-M-o
-Insert a byte with a code typed in octal.
-
-@item C-M-x
-Insert a byte with a code typed in hex.
-
-@item C-x [
-Move to the beginning of a 1k-byte ``page.''
-
-@item C-x ]
-Move to the end of a 1k-byte ``page.''
-
-@item M-g
-Move to an address specified in hex.
-
-@item M-j
-Move to an address specified in decimal.
-
-@item C-c C-c
-Leave Hexl mode, going back to the major mode this buffer had before you
-invoked @code{hexl-mode}.
-@end table
-
-@noindent
-Other Hexl commands let you insert strings (sequences) of binary
-bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a
-hexl-@key{RET}} for details.
-
-
-@node Saving Emacs Sessions, Recursive Edit, Editing Binary Files, Top
-@section Saving Emacs Sessions
-@cindex saving sessions
-@cindex restore session
-@cindex remember editing session
-@cindex reload files
-@cindex desktop
-
- Use the desktop library to save the state of Emacs from one session
-to another. Once you save the Emacs @dfn{desktop}---the buffers,
-their file names, major modes, buffer positions, and so on---then
-subsequent Emacs sessions reload the saved desktop.
-
-@findex desktop-save
-@vindex desktop-save-mode
- You can save the desktop manually with the command @kbd{M-x
-desktop-save}. You can also enable automatic saving of the desktop
-when you exit Emacs, and automatic restoration of the last saved
-desktop when Emacs starts: use the Customization buffer (@pxref{Easy
-Customization}) to set @code{desktop-save-mode} to @code{t} for future
-sessions, or add this line in your @file{~/.emacs} file:
-
-@example
-(desktop-save-mode 1)
-@end example
-
-@findex desktop-change-dir
-@findex desktop-revert
- If you turn on @code{desktop-save-mode} in your @file{~/.emacs},
-then when Emacs starts, it looks for a saved desktop in the current
-directory. Thus, you can have separate saved desktops in different
-directories, and the starting directory determines which one Emacs
-reloads. You can save the current desktop and reload one saved in
-another directory by typing @kbd{M-x desktop-change-dir}. Typing
-@kbd{M-x desktop-revert} reverts to the desktop previously reloaded.
-
- Specify the option @samp{--no-desktop} on the command line when you
-don't want it to reload any saved desktop. This turns off
-@code{desktop-save-mode} for the current session. Starting Emacs with
-the @samp{--no-init-file} option also disables desktop reloading,
-since it bypasses the @file{.emacs} init file, where
-@code{desktop-save-mode} is usually turned on.
-
-@vindex desktop-restore-eager
- By default, all the buffers in the desktop are restored at one go.
-However, this may be slow if there are a lot of buffers in the
-desktop. You can specify the maximum number of buffers to restore
-immediately with the variable @code{desktop-restore-eager}; the
-remaining buffers are restored ``lazily,'' when Emacs is idle.
-
-@findex desktop-clear
-@vindex desktop-globals-to-clear
-@vindex desktop-clear-preserve-buffers-regexp
- Type @kbd{M-x desktop-clear} to empty the Emacs desktop. This kills
-all buffers except for internal ones, and clears the global variables
-listed in @code{desktop-globals-to-clear}. If you want this to
-preserve certain buffers, customize the variable
-@code{desktop-clear-preserve-buffers-regexp}, whose value is a regular
-expression matching the names of buffers not to kill.
-
- If you want to save minibuffer history from one session to
-another, use the @code{savehist} library.
-
-@node Recursive Edit, Emulation, Saving Emacs Sessions, Top
-@section Recursive Editing Levels
-@cindex recursive editing level
-@cindex editing level, recursive
-
- A @dfn{recursive edit} is a situation in which you are using Emacs
-commands to perform arbitrary editing while in the middle of another
-Emacs command. For example, when you type @kbd{C-r} inside of a
-@code{query-replace}, you enter a recursive edit in which you can change
-the current buffer. On exiting from the recursive edit, you go back to
-the @code{query-replace}.
-
-@kindex C-M-c
-@findex exit-recursive-edit
-@cindex exiting recursive edit
- @dfn{Exiting} the recursive edit means returning to the unfinished
-command, which continues execution. The command to exit is @kbd{C-M-c}
-(@code{exit-recursive-edit}).
-
- You can also @dfn{abort} the recursive edit. This is like exiting,
-but also quits the unfinished command immediately. Use the command
-@kbd{C-]} (@code{abort-recursive-edit}) to do this. @xref{Quitting}.
-
- The mode line shows you when you are in a recursive edit by displaying
-square brackets around the parentheses that always surround the major and
-minor mode names. Every window's mode line shows this in the same way,
-since being in a recursive edit is true of Emacs as a whole rather than
-any particular window or buffer.
-
- It is possible to be in recursive edits within recursive edits. For
-example, after typing @kbd{C-r} in a @code{query-replace}, you may type a
-command that enters the debugger. This begins a recursive editing level
-for the debugger, within the recursive editing level for @kbd{C-r}.
-Mode lines display a pair of square brackets for each recursive editing
-level currently in progress.
-
- Exiting the inner recursive edit (such as with the debugger @kbd{c}
-command) resumes the command running in the next level up. When that
-command finishes, you can then use @kbd{C-M-c} to exit another recursive
-editing level, and so on. Exiting applies to the innermost level only.
-Aborting also gets out of only one level of recursive edit; it returns
-immediately to the command level of the previous recursive edit. If you
-wish, you can then abort the next recursive editing level.
-
- Alternatively, the command @kbd{M-x top-level} aborts all levels of
-recursive edits, returning immediately to the top-level command reader.
-
- The text being edited inside the recursive edit need not be the same text
-that you were editing at top level. It depends on what the recursive edit
-is for. If the command that invokes the recursive edit selects a different
-buffer first, that is the buffer you will edit recursively. In any case,
-you can switch buffers within the recursive edit in the normal manner (as
-long as the buffer-switching keys have not been rebound). You could
-probably do all the rest of your editing inside the recursive edit,
-visiting files and all. But this could have surprising effects (such as
-stack overflow) from time to time. So remember to exit or abort the
-recursive edit when you no longer need it.
-
- In general, we try to minimize the use of recursive editing levels in
-GNU Emacs. This is because they constrain you to ``go back'' in a
-particular order---from the innermost level toward the top level. When
-possible, we present different activities in separate buffers so that
-you can switch between them as you please. Some commands switch to a
-new major mode which provides a command to switch back. These
-approaches give you more flexibility to go back to unfinished tasks in
-the order you choose.
-
-@node Emulation, Hyperlinking, Recursive Edit, Top
-@section Emulation
-@cindex emulating other editors
-@cindex other editors
-@cindex EDT
-@cindex vi
-@cindex PC key bindings
-@cindex scrolling all windows
-@cindex PC selection
-@cindex Motif key bindings
-@cindex Macintosh key bindings
-@cindex WordStar
-
- GNU Emacs can be programmed to emulate (more or less) most other
-editors. Standard facilities can emulate these:
-
-@table @asis
-@item CRiSP/Brief (PC editor)
-@findex crisp-mode
-@vindex crisp-override-meta-x
-@findex scroll-all-mode
-@cindex CRiSP mode
-@cindex Brief emulation
-@cindex emulation of Brief
-@cindex mode, CRiSP
-You can turn on key bindings to emulate the CRiSP/Brief editor with
-@kbd{M-x crisp-mode}. Note that this rebinds @kbd{M-x} to exit Emacs
-unless you set the variable @code{crisp-override-meta-x}. You can
-also use the command @kbd{M-x scroll-all-mode} or set the variable
-@code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature
-(scrolling all windows together).
-
-@item EDT (DEC VMS editor)
-@findex edt-emulation-on
-@findex edt-emulation-off
-Turn on EDT emulation with the command @kbd{M-x edt-emulation-on},
-while @kbd{M-x edt-emulation-off} restores normal Emacs command
-bindings.
-
-Most of the EDT emulation commands are keypad keys, and most standard
-Emacs key bindings are still available. The EDT emulation rebindings
-are done in the global keymap, so there is no problem switching
-buffers or major modes while in EDT emulation.
-
-@item TPU (DEC VMS editor)
-@findex tpu-edt-on
-@cindex TPU
-@kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT.
-
-@item vi (Berkeley editor)
-@findex viper-mode
-Viper is the newest emulator for vi. It implements several levels of
-emulation; level 1 is closest to vi itself, while level 5 departs
-somewhat from strict emulation to take advantage of the capabilities of
-Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you
-the rest of the way and ask for the emulation level. @inforef{Top,
-Viper, viper}.
-
-@item vi (another emulator)
-@findex vi-mode
-@kbd{M-x vi-mode} enters a major mode that replaces the previously
-established major mode. All of the vi commands that, in real vi, enter
-``input'' mode are programmed instead to return to the previous major
-mode. Thus, ordinary Emacs serves as vi's ``input'' mode.
-
-Because vi emulation works through major modes, it does not work
-to switch buffers during emulation. Return to normal Emacs first.
-
-If you plan to use vi emulation much, you probably want to bind a key
-to the @code{vi-mode} command.
-
-@item vi (alternate emulator)
-@findex vip-mode
-@kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi
-more thoroughly than @kbd{M-x vi-mode}. ``Input'' mode in this emulator
-is changed from ordinary Emacs so you can use @key{ESC} to go back to
-emulated vi command mode. To get from emulated vi command mode back to
-ordinary Emacs, type @kbd{C-z}.
-
-This emulation does not work through major modes, and it is possible
-to switch buffers in various ways within the emulator. It is not
-so necessary to assign a key to the command @code{vip-mode} as
-it is with @code{vi-mode} because terminating insert mode does
-not use it.
-
-@inforef{Top, VIP, vip}, for full information.
-
-@item WordStar (old wordprocessor)
-@findex wordstar-mode
-@kbd{M-x wordstar-mode} provides a major mode with WordStar-like
-key bindings.
-@end table
-
-@node Hyperlinking, Dissociated Press, Emulation, Top
-@section Hyperlinking and Navigation Features
-
-@cindex hyperlinking
-@cindex navigation
- Various modes documented elsewhere have hypertext features so that
-you can follow links, usually by clicking @kbd{Mouse-2} on the link or
-typing @key{RET} while point is on the link. Clicking @kbd{Mouse-1}
-quickly on the link also follows it. (Hold @kbd{Mouse-1} for longer
-if you want to set point instead.)
-
- Info mode, Help mode and the Dired-like modes are examples of modes
-that have links in the buffer. The Tags facility links between uses
-and definitions in source files, see @ref{Tags}. Imenu provides
-navigation amongst items indexed in the current buffer, see
-@ref{Imenu}. Info-lookup provides mode-specific lookup of definitions
-in Info indexes, see @ref{Documentation}. Speedbar maintains a frame
-in which links to files, and locations in files are displayed, see
-@ref{Speedbar}.
-
- Other non-mode-specific facilities described in this section enable
-following links from the current buffer in a context-sensitive
-fashion.
-
-@menu
-* Browse-URL:: Following URLs.
-* Goto-address:: Activating URLs.
-* FFAP:: Finding files etc. at point.
-@end menu
-
-@node Browse-URL
-@subsection Following URLs
-@cindex World Wide Web
-@cindex Web
-@findex browse-url
-@findex browse-url-at-point
-@findex browse-url-at-mouse
-@cindex Browse-URL
-@cindex URLs
-
-@table @kbd
-@item M-x browse-url @key{RET} @var{url} @key{RET}
-Load a URL into a Web browser.
-@end table
-
-The Browse-URL package provides facilities for following URLs specifying
-links on the World Wide Web. Usually this works by invoking a web
-browser, but you can, for instance, arrange to invoke @code{compose-mail}
-from @samp{mailto:} URLs.
-
- The general way to use this feature is to type @kbd{M-x browse-url},
-which displays a specified URL. If point is located near a plausible
-URL, that URL is used as the default. Other commands are available
-which you might like to bind to keys, such as
-@code{browse-url-at-point} and @code{browse-url-at-mouse}.
-
-@vindex browse-url-browser-function
- You can customize Browse-URL's behavior via various options in the
-@code{browse-url} Customize group, particularly
-@code{browse-url-browser-function}. You can invoke actions dependent
-on the type of URL by defining @code{browse-url-browser-function} as
-an association list. The package's commentary available via @kbd{C-h
-p} under the @samp{hypermedia} keyword provides more information.
-Packages with facilities for following URLs should always go through
-Browse-URL, so that the customization options for Browse-URL will
-affect all browsing in Emacs.
-
-@node Goto-address
-@subsection Activating URLs
-@findex goto-address
-@cindex Goto-address
-@cindex URLs, activating
-
-@table @kbd
-@item M-x goto-address
-Activate URLs and e-mail addresses in the current buffer.
-@end table
-
- You can make URLs in the current buffer active with @kbd{M-x
-goto-address}. This finds all the URLs in the buffer, and establishes
-bindings for @kbd{Mouse-2} and @kbd{C-c @key{RET}} on them. After
-activation, if you click on a URL with @kbd{Mouse-2}, or move to a URL
-and type @kbd{C-c @key{RET}}, that will display the web page that the URL
-specifies. For a @samp{mailto} URL, it sends mail instead, using your
-selected mail-composition method (@pxref{Mail Methods}).
-
- It can be useful to add @code{goto-address} to mode hooks and the
-hooks used to display an incoming message.
-@code{rmail-show-message-hook} is the appropriate hook for Rmail, and
-@code{mh-show-mode-hook} for MH-E. This is not needed for Gnus,
-which has a similar feature of its own.
-
-
-@node FFAP
-@subsection Finding Files and URLs at Point
-@findex find-file-at-point
-@findex ffap
-@findex dired-at-point
-@findex ffap-next
-@findex ffap-menu
-@cindex finding file at point
-
- FFAP mode replaces certain key bindings for finding files, including
-@kbd{C-x C-f}, with commands that provide more sensitive defaults.
-These commands behave like the ordinary ones when given a prefix
-argument. Otherwise, they get the default file name or URL from the
-text around point. If what is found in the buffer has the form of a
-URL rather than a file name, the commands use @code{browse-url} to
-view it.
-
- This feature is useful for following references in mail or news
-buffers, @file{README} files, @file{MANIFEST} files, and so on. The
-@samp{ffap} package's commentary available via @kbd{C-h p} under the
-@samp{files} keyword and the @code{ffap} Custom group provide details.
-
-@cindex FFAP minor mode
-@findex ffap-mode
- You can turn on FFAP minor mode by calling @code{ffap-bindings} to
-make the following key bindings and to install hooks for using
-@code{ffap} in Rmail, Gnus and VM article buffers.
-
-@table @kbd
-@item C-x C-f @var{filename} @key{RET}
-@kindex C-x C-f @r{(FFAP)}
-Find @var{filename}, guessing a default from text around point
-(@code{find-file-at-point}).
-@item C-x C-r
-@kindex C-x C-r @r{(FFAP)}
-@code{ffap-read-only}, analogous to @code{find-file-read-only}.
-@item C-x C-v
-@kindex C-x C-v @r{(FFAP)}
-@code{ffap-alternate-file}, analogous to @code{find-alternate-file}.
-@item C-x d @var{directory} @key{RET}
-@kindex C-x d @r{(FFAP)}
-Start Dired on @var{directory}, defaulting to the directory name at
-point (@code{dired-at-point}).
-@item C-x C-d
-@code{ffap-list-directory}, analogous to @code{list-directory}.
-@item C-x 4 f
-@kindex C-x 4 f @r{(FFAP)}
-@code{ffap-other-window}, analogous to @code{find-file-other-window}.
-@item C-x 4 r
-@code{ffap-read-only-other-window}, analogous to
-@code{find-file-read-only-other-window}.
-@item C-x 4 d
-@code{ffap-dired-other-window}, analogous to @code{dired-other-window}.
-@item C-x 5 f
-@kindex C-x 5 f @r{(FFAP)}
-@code{ffap-other-frame}, analogous to @code{find-file-other-frame}.
-@item C-x 5 r
-@code{ffap-read-only-other-frame}, analogous to
-@code{find-file-read-only-other-frame}.
-@item C-x 5 d
-@code{ffap-dired-other-frame}, analogous to @code{dired-other-frame}.
-@item M-x ffap-next
-Search buffer for next file name or URL, then find that file or URL.
-@item S-Mouse-3
-@kindex S-Mouse-3 @r{(FFAP)}
-@code{ffap-at-mouse} finds the file guessed from text around the position
-of a mouse click.
-@item C-S-Mouse-3
-@kindex C-S-Mouse-3 @r{(FFAP)}
-Display a menu of files and URLs mentioned in current buffer, then
-find the one you select (@code{ffap-menu}).
-@end table
-
-@node Dissociated Press, Amusements, Hyperlinking, Top
-@section Dissociated Press
-
-@findex dissociated-press
- @kbd{M-x dissociated-press} is a command for scrambling a file of text
-either word by word or character by character. Starting from a buffer of
-straight English, it produces extremely amusing output. The input comes
-from the current Emacs buffer. Dissociated Press writes its output in a
-buffer named @samp{*Dissociation*}, and redisplays that buffer after every
-couple of lines (approximately) so you can read the output as it comes out.
-
- Dissociated Press asks every so often whether to continue generating
-output. Answer @kbd{n} to stop it. You can also stop at any time by
-typing @kbd{C-g}. The dissociation output remains in the
-@samp{*Dissociation*} buffer for you to copy elsewhere if you wish.
-
-@cindex presidentagon
- Dissociated Press operates by jumping at random from one point in the
-buffer to another. In order to produce plausible output rather than
-gibberish, it insists on a certain amount of overlap between the end of
-one run of consecutive words or characters and the start of the next.
-That is, if it has just output `president' and then decides to jump
-to a different point in the file, it might spot the `ent' in `pentagon'
-and continue from there, producing `presidentagon'.@footnote{This
-dissociword actually appeared during the Vietnam War, when it was very
-appropriate. Bush has made it appropriate again.} Long sample texts
-produce the best results.
-
-@cindex againformation
- A positive argument to @kbd{M-x dissociated-press} tells it to operate
-character by character, and specifies the number of overlap characters. A
-negative argument tells it to operate word by word, and specifies the number
-of overlap words. In this mode, whole words are treated as the elements to
-be permuted, rather than characters. No argument is equivalent to an
-argument of two. For your againformation, the output goes only into the
-buffer @samp{*Dissociation*}. The buffer you start with is not changed.
-
-@cindex Markov chain
-@cindex ignoriginal
-@cindex techniquitous
- Dissociated Press produces results fairly like those of a Markov
-chain based on a frequency table constructed from the sample text. It
-is, however, an independent, ignoriginal invention. Dissociated Press
-techniquitously copies several consecutive characters from the sample
-between random choices, whereas a Markov chain would choose randomly
-for each word or character. This makes for more plausible sounding
-results, and runs faster.
-
-@cindex outragedy
-@cindex buggestion
-@cindex properbose
-@cindex mustatement
-@cindex developediment
-@cindex userenced
- It is a mustatement that too much use of Dissociated Press can be a
-developediment to your real work, sometimes to the point of outragedy.
-And keep dissociwords out of your documentation, if you want it to be well
-userenced and properbose. Have fun. Your buggestions are welcome.
-
-@node Amusements, Customization, Dissociated Press, Top
-@section Other Amusements
-@cindex boredom
-@findex hanoi
-@findex yow
-@findex gomoku
-@cindex tower of Hanoi
-
- If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are
-considerably bored, give it a numeric argument. If you are very, very
-bored, try an argument of 9. Sit back and watch.
-
-@cindex Go Moku
- If you want a little more personal involvement, try @kbd{M-x gomoku},
-which plays the game Go Moku with you.
-
-@findex blackbox
-@findex mpuz
-@findex 5x5
-@cindex puzzles
- @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are puzzles.
-@code{blackbox} challenges you to determine the location of objects
-inside a box by tomography. @code{mpuz} displays a multiplication
-puzzle with letters standing for digits in a code that you must
-guess---to guess a value, type a letter and then the digit you think it
-stands for. The aim of @code{5x5} is to fill in all the squares.
-
-@findex decipher
-@cindex ciphers
-@cindex cryptanalysis
-@kbd{M-x decipher} helps you to cryptanalyze a buffer which is encrypted
-in a simple monoalphabetic substitution cipher.
-
-@findex dunnet
- @kbd{M-x dunnet} runs an adventure-style exploration game, which is
-a bigger sort of puzzle.
-
-@findex lm
-@cindex landmark game
-@kbd{M-x lm} runs a relatively non-participatory game in which a robot
-attempts to maneuver towards a tree at the center of the window based on
-unique olfactory cues from each of the four directions.
-
-@findex life
-@cindex Life
-@kbd{M-x life} runs Conway's ``Life'' cellular automaton.
-
-@findex morse-region
-@findex unmorse-region
-@cindex Morse code
-@cindex --/---/.-./.../.
-@kbd{M-x morse-region} converts text in a region to Morse code and
-@kbd{M-x unmorse-region} converts it back. No cause for remorse.
-
-@findex pong
-@cindex Pong game
-@kbd{M-x pong} plays a Pong-like game, bouncing the ball off opposing
-bats.
-
-@findex solitaire
-@cindex solitaire
-@kbd{M-x solitaire} plays a game of solitaire in which you jump pegs
-across other pegs.
-
-@findex studlify-region
-@cindex StudlyCaps
-@kbd{M-x studlify-region} studlify-cases the region, producing
-text like this:
-
-@example
-M-x stUdlIfY-RegioN stUdlIfY-CaSeS thE region.
-@end example
-
-@findex tetris
-@cindex Tetris
-@findex snake
-@cindex Snake
-@kbd{M-x tetris} runs an implementation of the well-known Tetris game.
-Likewise, @kbd{M-x snake} provides an implementation of Snake.
-
- When you are frustrated, try the famous Eliza program. Just do
-@kbd{M-x doctor}. End each input by typing @key{RET} twice.
-
-@cindex Zippy
- When you are feeling strange, type @kbd{M-x yow}.
-
-@findex zone
-The command @kbd{M-x zone} plays games with the display when Emacs is
-idle.
-
-@ifnottex
-@lowersections
-@end ifnottex
-
-@ignore
- arch-tag: 8f094220-c0d5-4e9e-af7d-3e0da8187474
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@c
-@c This file is included either in emacs-xtra.texi (when producing the
-@c printed version) or in the main Emacs manual (for the on-line version).
-@node MS-DOS
-@section Emacs and MS-DOS
-@cindex MS-DOG
-@cindex MS-DOS peculiarities
-
- This section briefly describes the peculiarities of using Emacs on
-the MS-DOS ``operating system'' (also known as ``MS-DOG'').
-@iftex
-Information about Emacs and Microsoft's current operating system
-Windows (also known as ``Losedows) is in the main Emacs manual
-(@pxref{Microsoft Systems,,, emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-Information about peculiarities common to MS-DOS and Microsoft's
-current operating systems Windows (also known as ``Losedows) is in
-@ref{Microsoft Windows}.
-@end ifnottex
-
- If you build Emacs for MS-DOS, the binary will also run on Windows
-3.X, Windows NT, Windows 9X/ME, Windows 2000/XP, or OS/2 as a DOS
-application; all of this chapter applies for all of those systems, if
-you use an Emacs that was built for MS-DOS.
-
-@iftex
- @xref{Text and Binary,,,emacs, the Emacs Manual}, for information
-@end iftex
-@ifnottex
- @xref{Text and Binary}, for information
-@end ifnottex
-about Emacs' special handling of text files under MS-DOS (and Windows).
-
-@menu
-* Keyboard: MS-DOS Keyboard. Keyboard conventions on MS-DOS.
-* Mouse: MS-DOS Mouse. Mouse conventions on MS-DOS.
-* Display: MS-DOS Display. Fonts, frames and display size on MS-DOS.
-* Files: MS-DOS File Names. File name conventions on MS-DOS.
-* Printing: MS-DOS Printing. Printing specifics on MS-DOS.
-* I18N: MS-DOS and MULE. Support for internationalization on MS-DOS.
-* Processes: MS-DOS Processes. Running subprocesses on MS-DOS.
-@end menu
-
-@node MS-DOS Keyboard
-@subsection Keyboard Usage on MS-DOS
-
-@kindex DEL @r{(MS-DOS)}
-@kindex BS @r{(MS-DOS)}
- The key that is called @key{DEL} in Emacs (because that's how it is
-designated on most workstations) is known as @key{BS} (backspace) on a
-PC. That is why the PC-specific terminal initialization remaps the
-@key{BS} key to act as @key{DEL}; the @key{DELETE} key is remapped to act
-as @kbd{C-d} for the same reasons.
-
-@kindex C-g @r{(MS-DOS)}
-@kindex C-BREAK @r{(MS-DOS)}
-@cindex quitting on MS-DOS
- Emacs built for MS-DOS recognizes @kbd{C-@key{BREAK}} as a quit
-character, just like @kbd{C-g}. This is because Emacs cannot detect
-that you have typed @kbd{C-g} until it is ready for more input. As a
-consequence, you cannot use @kbd{C-g} to stop a running command
-@iftex
-(@pxref{Quitting,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Quitting}).
-@end ifnottex
-By contrast, @kbd{C-@key{BREAK}} @emph{is} detected as soon as you
-type it (as @kbd{C-g} is on other systems), so it can be used to stop
-a running command and for emergency escape
-@iftex
-(@pxref{Emergency Escape,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Emergency Escape}).
-@end ifnottex
-
-@cindex Meta (under MS-DOS)
-@cindex Hyper (under MS-DOS)
-@cindex Super (under MS-DOS)
-@vindex dos-super-key
-@vindex dos-hyper-key
- The PC keyboard maps use the left @key{ALT} key as the @key{META} key.
-You have two choices for emulating the @key{SUPER} and @key{HYPER} keys:
-choose either the right @key{CTRL} key or the right @key{ALT} key by
-setting the variables @code{dos-hyper-key} and @code{dos-super-key} to 1
-or 2 respectively. If neither @code{dos-super-key} nor
-@code{dos-hyper-key} is 1, then by default the right @key{ALT} key is
-also mapped to the @key{META} key. However, if the MS-DOS international
-keyboard support program @file{KEYB.COM} is installed, Emacs will
-@emph{not} map the right @key{ALT} to @key{META}, since it is used for
-accessing characters like @kbd{~} and @kbd{@@} on non-US keyboard
-layouts; in this case, you may only use the left @key{ALT} as @key{META}
-key.
-
-@kindex C-j @r{(MS-DOS)}
-@vindex dos-keypad-mode
- The variable @code{dos-keypad-mode} is a flag variable that controls
-what key codes are returned by keys in the numeric keypad. You can also
-define the keypad @key{ENTER} key to act like @kbd{C-j}, by putting the
-following line into your @file{_emacs} file:
-
-@smallexample
-;; @r{Make the @key{ENTER} key from the numeric keypad act as @kbd{C-j}.}
-(define-key function-key-map [kp-enter] [?\C-j])
-@end smallexample
-
-@node MS-DOS Mouse
-@subsection Mouse Usage on MS-DOS
-
-@cindex mouse support under MS-DOS
- Emacs on MS-DOS supports a mouse (on the default terminal only).
-The mouse commands work as documented, including those that use menus
-and the menu bar
-@iftex
-(@pxref{Menu Bar,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Menu Bar}).
-@end ifnottex
- Scroll bars don't work in MS-DOS Emacs. PC mice usually have only
-two buttons; these act as @kbd{Mouse-1} and @kbd{Mouse-2}, but if you
-press both of them together, that has the effect of @kbd{Mouse-3}. If
-the mouse does have 3 buttons, Emacs detects that at startup, and all
-the 3 buttons function normally, as on X.
-
- Help strings for menu-bar and pop-up menus are displayed in the echo
-area when the mouse pointer moves across the menu items. Highlighting
-of mouse-sensitive text
-@iftex
-(@pxref{Mouse References,,,emacs, the Emacs Manual})
-@end iftex
-@ifnottex
-(@pxref{Mouse References})
-@end ifnottex
-is also supported.
-
-@cindex mouse, set number of buttons
-@findex msdos-set-mouse-buttons
- Some versions of mouse drivers don't report the number of mouse
-buttons correctly. For example, mice with a wheel report that they
-have 3 buttons, but only 2 of them are passed to Emacs; the clicks on
-the wheel, which serves as the middle button, are not passed. In
-these cases, you can use the @kbd{M-x msdos-set-mouse-buttons} command
-to tell Emacs how many mouse buttons to expect. You could make such a
-setting permanent by adding this fragment to your @file{_emacs} init
-file:
-
-@example
-;; @r{Treat the mouse like a 2-button mouse.}
-(msdos-set-mouse-buttons 2)
-@end example
-
-@cindex Windows clipboard support
- Emacs built for MS-DOS supports clipboard operations when it runs on
-Windows. Commands that put text on the kill ring, or yank text from
-the ring, check the Windows clipboard first, just as Emacs does on the
-X Window System
-@iftex
-(@pxref{Mouse Commands,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Mouse Commands}).
-@end ifnottex
-Only the primary selection and the cut buffer are supported by MS-DOS
-Emacs on Windows; the secondary selection always appears as empty.
-
- Due to the way clipboard access is implemented by Windows, the
-length of text you can put into the clipboard is limited by the amount
-of free DOS memory that is available to Emacs. Usually, up to 620KB of
-text can be put into the clipboard, but this limit depends on the system
-configuration and is lower if you run Emacs as a subprocess of
-another program. If the killed text does not fit, Emacs outputs a
-message saying so, and does not put the text into the clipboard.
-
- Null characters also cannot be put into the Windows clipboard. If the
-killed text includes null characters, Emacs does not put such text into
-the clipboard, and displays in the echo area a message to that effect.
-
-@vindex dos-display-scancodes
- The variable @code{dos-display-scancodes}, when non-@code{nil},
-directs Emacs to display the @acronym{ASCII} value and the keyboard scan code of
-each keystroke; this feature serves as a complement to the
-@code{view-lossage} command, for debugging.
-
-@node MS-DOS Display
-@subsection Display on MS-DOS
-@cindex faces under MS-DOS
-@cindex fonts, emulating under MS-DOS
-
- Display on MS-DOS cannot use font variants, like bold or italic, but
-it does support multiple faces, each of which can specify a foreground
-and a background color. Therefore, you can get the full functionality
-of Emacs packages that use fonts (such as @code{font-lock}, Enriched
-Text mode, and others) by defining the relevant faces to use different
-colors. Use the @code{list-colors-display} command
-@iftex
-(@pxref{Frame Parameters,,,emacs, the Emacs Manual})
-@end iftex
-@ifnottex
-(@pxref{Frame Parameters})
-@end ifnottex
-and the @code{list-faces-display} command
-@iftex
-(@pxref{Faces,,,emacs, the Emacs Manual})
-@end iftex
-@ifnottex
-(@pxref{Faces})
-@end ifnottex
-to see what colors and faces are available and what they look like.
-
- @xref{MS-DOS and MULE}, later in this chapter, for information on
-how Emacs displays glyphs and characters that aren't supported by the
-native font built into the DOS display.
-
-@cindex cursor shape on MS-DOS
- When Emacs starts, it changes the cursor shape to a solid box. This
-is for compatibility with other systems, where the box cursor is the
-default in Emacs. This default shape can be changed to a bar by
-specifying the @code{cursor-type} parameter in the variable
-@code{default-frame-alist}
-@iftex
-(@pxref{Creating Frames,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Creating Frames}).
-@end ifnottex
-The MS-DOS terminal doesn't support a vertical-bar cursor,
-so the bar cursor is horizontal, and the @code{@var{width}} parameter,
-if specified by the frame parameters, actually determines its height.
-For this reason, the @code{bar} and @code{hbar} cursor types produce
-the same effect on MS-DOS. As an extension, the bar cursor
-specification can include the starting scan line of the cursor as well
-as its width, like this:
-
-@example
- '(cursor-type bar @var{width} . @var{start})
-@end example
-
-@noindent
-In addition, if the @var{width} parameter is negative, the cursor bar
-begins at the top of the character cell.
-
-@cindex frames on MS-DOS
- The MS-DOS terminal can only display a single frame at a time. The
-Emacs frame facilities work on MS-DOS much as they do on text-only
-terminals
-@iftex
-(@pxref{Frames,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Frames}).
-@end ifnottex
-When you run Emacs from a DOS window on MS-Windows, you can make the
-visible frame smaller than the full screen, but Emacs still cannot
-display more than a single frame at a time.
-
-@cindex frame size under MS-DOS
-@findex mode4350
-@findex mode25
- The @code{mode4350} command switches the display to 43 or 50
-lines, depending on your hardware; the @code{mode25} command switches
-to the default 80x25 screen size.
-
- By default, Emacs only knows how to set screen sizes of 80 columns by
-25, 28, 35, 40, 43 or 50 rows. However, if your video adapter has
-special video modes that will switch the display to other sizes, you can
-have Emacs support those too. When you ask Emacs to switch the frame to
-@var{n} rows by @var{m} columns dimensions, it checks if there is a
-variable called @code{screen-dimensions-@var{n}x@var{m}}, and if so,
-uses its value (which must be an integer) as the video mode to switch
-to. (Emacs switches to that video mode by calling the BIOS @code{Set
-Video Mode} function with the value of
-@code{screen-dimensions-@var{n}x@var{m}} in the @code{AL} register.)
-For example, suppose your adapter will switch to 66x80 dimensions when
-put into video mode 85. Then you can make Emacs support this screen
-size by putting the following into your @file{_emacs} file:
-
-@example
-(setq screen-dimensions-66x80 85)
-@end example
-
- Since Emacs on MS-DOS can only set the frame size to specific
-supported dimensions, it cannot honor every possible frame resizing
-request. When an unsupported size is requested, Emacs chooses the next
-larger supported size beyond the specified size. For example, if you
-ask for 36x80 frame, you will get 40x80 instead.
-
- The variables @code{screen-dimensions-@var{n}x@var{m}} are used only
-when they exactly match the specified size; the search for the next
-larger supported size ignores them. In the above example, even if your
-VGA supports 38x80 dimensions and you define a variable
-@code{screen-dimensions-38x80} with a suitable value, you will still get
-40x80 screen when you ask for a 36x80 frame. If you want to get the
-38x80 size in this case, you can do it by setting the variable named
-@code{screen-dimensions-36x80} with the same video mode value as
-@code{screen-dimensions-38x80}.
-
- Changing frame dimensions on MS-DOS has the effect of changing all the
-other frames to the new dimensions.
-
-@node MS-DOS File Names
-@subsection File Names on MS-DOS
-@cindex file names under MS-DOS
-@cindex init file, default name under MS-DOS
-
- On MS-DOS, file names are case-insensitive and limited to eight
-characters, plus optionally a period and three more characters. Emacs
-knows enough about these limitations to handle file names that were
-meant for other operating systems. For instance, leading dots
-@samp{.} in file names are invalid in MS-DOS, so Emacs transparently
-converts them to underscores @samp{_}; thus your default init file
-@iftex
-(@pxref{Init File,,,emacs, the Emacs Manual})
-@end iftex
-@ifnottex
-(@pxref{Init File})
-@end ifnottex
-is called @file{_emacs} on MS-DOS. Excess characters before or after
-the period are generally ignored by MS-DOS itself; thus, if you visit
-the file @file{LongFileName.EvenLongerExtension}, you will silently
-get @file{longfile.eve}, but Emacs will still display the long file
-name on the mode line. Other than that, it's up to you to specify
-file names which are valid under MS-DOS; the transparent conversion as
-described above only works on file names built into Emacs.
-
-@cindex backup file names on MS-DOS
- The above restrictions on the file names on MS-DOS make it almost
-impossible to construct the name of a backup file
-@iftex
-(@pxref{Backup Names,,,emacs, the Emacs Manual})
-@end iftex
-@ifnottex
-(@pxref{Backup Names})
-@end ifnottex
-without losing some of the original file name characters. For
-example, the name of a backup file for @file{docs.txt} is
-@file{docs.tx~} even if single backup is used.
-
-@cindex file names under Windows 95/NT
-@cindex long file names in DOS box under Windows 95/NT
- If you run Emacs as a DOS application under Windows 9X, Windows ME, or
-Windows 2000/XP, you can turn on support for long file names. If you do
-that, Emacs doesn't truncate file names or convert them to lower case;
-instead, it uses the file names that you specify, verbatim. To enable
-long file name support, set the environment variable @env{LFN} to
-@samp{y} before starting Emacs. Unfortunately, Windows NT doesn't allow
-DOS programs to access long file names, so Emacs built for MS-DOS will
-only see their short 8+3 aliases.
-
-@cindex @env{HOME} directory under MS-DOS
- MS-DOS has no notion of home directory, so Emacs on MS-DOS pretends
-that the directory where it is installed is the value of the @env{HOME}
-environment variable. That is, if your Emacs binary,
-@file{emacs.exe}, is in the directory @file{c:/utils/emacs/bin}, then
-Emacs acts as if @env{HOME} were set to @samp{c:/utils/emacs}. In
-particular, that is where Emacs looks for the init file @file{_emacs}.
-With this in mind, you can use @samp{~} in file names as an alias for
-the home directory, as you would on GNU or Unix. You can also set
-@env{HOME} variable in the environment before starting Emacs; its
-value will then override the above default behavior.
-
- Emacs on MS-DOS handles the directory name @file{/dev} specially,
-because of a feature in the emulator libraries of DJGPP that pretends
-I/O devices have names in that directory. We recommend that you avoid
-using an actual directory named @file{/dev} on any disk.
-
-@node MS-DOS Printing
-@subsection Printing and MS-DOS
-
- Printing commands, such as @code{lpr-buffer}
-@iftex
-(@pxref{Printing,,,emacs, the Emacs Manual}) and @code{ps-print-buffer}
-(@pxref{PostScript,,,emacs, the Emacs Manual})
-@end iftex
-@ifnottex
-(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript})
-@end ifnottex
-can work on MS-DOS by sending the output to one of the printer ports,
-if a Posix-style @code{lpr} program is unavailable. The same Emacs
-variables control printing on all systems, but in some cases they have
-different default values on MS-DOS.
-
-@iftex
-@xref{Windows Printing,,,emacs, the Emacs Manual},
-@end iftex
-@ifnottex
-@xref{Windows Printing},
-@end ifnottex
-for details about setting up printing to a networked printer.
-
- Some printers expect DOS codepage encoding of non-@acronym{ASCII} text, even
-though they are connected to a Windows machine which uses a different
-encoding for the same locale. For example, in the Latin-1 locale, DOS
-uses codepage 850 whereas Windows uses codepage 1252. @xref{MS-DOS and
-MULE}. When you print to such printers from Windows, you can use the
-@kbd{C-x RET c} (@code{universal-coding-system-argument}) command before
-@kbd{M-x lpr-buffer}; Emacs will then convert the text to the DOS
-codepage that you specify. For example, @kbd{C-x RET c cp850-dos RET
-M-x lpr-region RET} will print the region while converting it to the
-codepage 850 encoding. You may need to create the @code{cp@var{nnn}}
-coding system with @kbd{M-x codepage-setup}.
-
-@vindex dos-printer
-@vindex dos-ps-printer
- For backwards compatibility, the value of @code{dos-printer}
-(@code{dos-ps-printer}), if it has a value, overrides the value of
-@code{printer-name} (@code{ps-printer-name}), on MS-DOS.
-
-
-@node MS-DOS and MULE
-@subsection International Support on MS-DOS
-@cindex international support @r{(MS-DOS)}
-
- Emacs on MS-DOS supports the same international character sets as it
-does on GNU, Unix and other platforms
-@iftex
-(@pxref{International,,,emacs, the Emacs Manual}),
-@end iftex
-@ifnottex
-(@pxref{International}),
-@end ifnottex
-including coding systems for converting between the different
-character sets. However, due to incompatibilities between
-MS-DOS/MS-Windows and other systems, there are several DOS-specific
-aspects of this support that you should be aware of. This section
-describes these aspects.
-
- The description below is largely specific to the MS-DOS port of
-Emacs, especially where it talks about practical implications for
-Emacs users. For other operating systems, see the @file{code-pages.el}
-package, which implements support for MS-DOS- and MS-Windows-specific
-encodings for all platforms other than MS-DOS.
-
-@table @kbd
-@item M-x dos-codepage-setup
-Set up Emacs display and coding systems as appropriate for the current
-DOS codepage.
-
-@item M-x codepage-setup
-Create a coding system for a certain DOS codepage.
-@end table
-
-@cindex codepage, MS-DOS
-@cindex DOS codepages
- MS-DOS is designed to support one character set of 256 characters at
-any given time, but gives you a variety of character sets to choose
-from. The alternative character sets are known as @dfn{DOS codepages}.
-Each codepage includes all 128 @acronym{ASCII} characters, but the other 128
-characters (codes 128 through 255) vary from one codepage to another.
-Each DOS codepage is identified by a 3-digit number, such as 850, 862,
-etc.
-
- In contrast to X, which lets you use several fonts at the same time,
-MS-DOS normally doesn't allow use of several codepages in a single
-session. MS-DOS was designed to load a single codepage at system
-startup, and require you to reboot in order to change
-it@footnote{Normally, one particular codepage is burnt into the
-display memory, while other codepages can be installed by modifying
-system configuration files, such as @file{CONFIG.SYS}, and rebooting.
-While there is third-party software that allows changing the codepage
-without rebooting, we describe here how a stock MS-DOS system
-behaves.}. Much the same limitation applies when you run DOS
-executables on other systems such as MS-Windows.
-
-@cindex unibyte operation @r{(MS-DOS)}
- If you invoke Emacs on MS-DOS with the @samp{--unibyte} option
-@iftex
-(@pxref{Initial Options,,,emacs, the Emacs Manual}),
-@end iftex
-@ifnottex
-(@pxref{Initial Options}),
-@end ifnottex
-Emacs does not perform any conversion of non-@acronym{ASCII}
-characters. Instead, it reads and writes any non-@acronym{ASCII}
-characters verbatim, and sends their 8-bit codes to the display
-verbatim. Thus, unibyte Emacs on MS-DOS supports the current
-codepage, whatever it may be, but cannot even represent any other
-characters.
-
-@vindex dos-codepage
- For multibyte operation on MS-DOS, Emacs needs to know which
-characters the chosen DOS codepage can display. So it queries the
-system shortly after startup to get the chosen codepage number, and
-stores the number in the variable @code{dos-codepage}. Some systems
-return the default value 437 for the current codepage, even though the
-actual codepage is different. (This typically happens when you use the
-codepage built into the display hardware.) You can specify a different
-codepage for Emacs to use by setting the variable @code{dos-codepage} in
-your init file.
-
-@cindex language environment, automatic selection on @r{MS-DOS}
- Multibyte Emacs supports only certain DOS codepages: those which can
-display Far-Eastern scripts, like the Japanese codepage 932, and those
-that encode a single ISO 8859 character set.
-
- The Far-Eastern codepages can directly display one of the MULE
-character sets for these countries, so Emacs simply sets up to use the
-appropriate terminal coding system that is supported by the codepage.
-The special features described in the rest of this section mostly
-pertain to codepages that encode ISO 8859 character sets.
-
- For the codepages which correspond to one of the ISO character sets,
-Emacs knows the character set name based on the codepage number. Emacs
-automatically creates a coding system to support reading and writing
-files that use the current codepage, and uses this coding system by
-default. The name of this coding system is @code{cp@var{nnn}}, where
-@var{nnn} is the codepage number.@footnote{The standard Emacs coding
-systems for ISO 8859 are not quite right for the purpose, because
-typically the DOS codepage does not match the standard ISO character
-codes. For example, the letter @samp{@,{c}} (@samp{c} with cedilla) has
-code 231 in the standard Latin-1 character set, but the corresponding
-DOS codepage 850 uses code 135 for this glyph.}
-
-@cindex mode line @r{(MS-DOS)}
- All the @code{cp@var{nnn}} coding systems use the letter @samp{D}
-(for ``DOS'') as their mode-line mnemonic. Since both the terminal
-coding system and the default coding system for file I/O are set to
-the proper @code{cp@var{nnn}} coding system at startup, it is normal
-for the mode line on MS-DOS to begin with @samp{-DD\-}.
-@iftex
-@xref{Mode Line,,,emacs, the Emacs Manual}.
-@end iftex
-@ifnottex
-@xref{Mode Line}.
-@end ifnottex
-Far-Eastern DOS terminals do not use the @code{cp@var{nnn}} coding
-systems, and thus their initial mode line looks like the Emacs
-default.
-
- Since the codepage number also indicates which script you are using,
-Emacs automatically runs @code{set-language-environment} to select the
-language environment for that script
-@iftex
-(@pxref{Language Environments,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Language Environments}).
-@end ifnottex
-
- If a buffer contains a character belonging to some other ISO 8859
-character set, not the one that the chosen DOS codepage supports, Emacs
-displays it using a sequence of @acronym{ASCII} characters. For example, if the
-current codepage doesn't have a glyph for the letter @samp{@`o} (small
-@samp{o} with a grave accent), it is displayed as @samp{@{`o@}}, where
-the braces serve as a visual indication that this is a single character.
-(This may look awkward for some non-Latin characters, such as those from
-Greek or Hebrew alphabets, but it is still readable by a person who
-knows the language.) Even though the character may occupy several
-columns on the screen, it is really still just a single character, and
-all Emacs commands treat it as one.
-
-@cindex IBM graphics characters (MS-DOS)
-@cindex box-drawing characters (MS-DOS)
-@cindex line-drawing characters (MS-DOS)
- Not all characters in DOS codepages correspond to ISO 8859
-characters---some are used for other purposes, such as box-drawing
-characters and other graphics. Emacs maps these characters to two
-special character sets called @code{eight-bit-control} and
-@code{eight-bit-graphic}, and displays them as their IBM glyphs.
-However, you should be aware that other systems might display these
-characters differently, so you should avoid them in text that might be
-copied to a different operating system, or even to another DOS machine
-that uses a different codepage.
-
-@vindex dos-unsupported-character-glyph
- Emacs supports many other characters sets aside from ISO 8859, but it
-cannot display them on MS-DOS. So if one of these multibyte characters
-appears in a buffer, Emacs on MS-DOS displays them as specified by the
-@code{dos-unsupported-character-glyph} variable; by default, this glyph
-is an empty triangle. Use the @kbd{C-u C-x =} command to display the
-actual code and character set of such characters.
-@iftex
-@xref{Position Info,,,emacs, the Emacs Manual}.
-@end iftex
-@ifnottex
-@xref{Position Info}.
-@end ifnottex
-
-@findex codepage-setup
- By default, Emacs defines a coding system to support the current
-codepage. To define a coding system for some other codepage (e.g., to
-visit a file written on a DOS machine in another country), use the
-@kbd{M-x codepage-setup} command. It prompts for the 3-digit code of
-the codepage, with completion, then creates the coding system for the
-specified codepage. You can then use the new coding system to read and
-write files, but you must specify it explicitly for the file command
-when you want to use it
-@iftex
-(@pxref{Text Coding,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Text Coding}).
-@end ifnottex
-
- These coding systems are also useful for visiting a file encoded using
-a DOS codepage, using Emacs running on some other operating system.
-
-@cindex MS-Windows codepages
- MS-Windows provides its own codepages, which are different from the
-DOS codepages for the same locale. For example, DOS codepage 850
-supports the same character set as Windows codepage 1252; DOS codepage
-855 supports the same character set as Windows codepage 1251, etc.
-The MS-Windows version of Emacs uses the current codepage for display
-when invoked with the @samp{-nw} option. Support for codepages in the
-Windows port of Emacs is part of the @file{code-pages.el} package.
-
-@node MS-DOS Processes
-@subsection Subprocesses on MS-DOS
-
-@cindex compilation under MS-DOS
-@cindex inferior processes under MS-DOS
-@findex compile @r{(MS-DOS)}
-@findex grep @r{(MS-DOS)}
- Because MS-DOS is a single-process ``operating system,''
-asynchronous subprocesses are not available. In particular, Shell
-mode and its variants do not work. Most Emacs features that use
-asynchronous subprocesses also don't work on MS-DOS, including
-Shell mode and GUD. When in doubt, try and see; commands that
-don't work output an error message saying that asynchronous processes
-aren't supported.
-
- Compilation under Emacs with @kbd{M-x compile}, searching files with
-@kbd{M-x grep} and displaying differences between files with @kbd{M-x
-diff} do work, by running the inferior processes synchronously. This
-means you cannot do any more editing until the inferior process
-finishes.
-
- Spell checking also works, by means of special support for synchronous
-invocation of the @code{ispell} program. This is slower than the
-asynchronous invocation on other platforms
-
- Instead of the Shell mode, which doesn't work on MS-DOS, you can use
-the @kbd{M-x eshell} command. This invokes the Eshell package that
-implements a Posix-like shell entirely in Emacs Lisp.
-
- By contrast, Emacs compiled as a native Windows application
-@strong{does} support asynchronous subprocesses.
-@iftex
-@xref{Windows Processes,,,emacs, the Emacs Manual}.
-@end iftex
-@ifnottex
-@xref{Windows Processes}.
-@end ifnottex
-
-@cindex printing under MS-DOS
- Printing commands, such as @code{lpr-buffer}
-@iftex
-(@pxref{Printing,,,emacs, the Emacs Manual}) and
-@code{ps-print-buffer} (@pxref{PostScript,,,emacs, the Emacs Manual}),
-work in MS-DOS by sending the output to one of the printer ports.
-@xref{MS-DOS Printing,,,emacs, the Emacs Manual}.
-@end iftex
-@ifnottex
-(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript}),
-work in MS-DOS by sending the output to one of the printer ports.
-@xref{MS-DOS Printing}.
-@end ifnottex
-
- When you run a subprocess synchronously on MS-DOS, make sure the
-program terminates and does not try to read keyboard input. If the
-program does not terminate on its own, you will be unable to terminate
-it, because MS-DOS provides no general way to terminate a process.
-Pressing @kbd{C-c} or @kbd{C-@key{BREAK}} might sometimes help in these
-cases.
-
- Accessing files on other machines is not supported on MS-DOS. Other
-network-oriented commands such as sending mail, Web browsing, remote
-login, etc., don't work either, unless network access is built into
-MS-DOS with some network redirector.
-
-@cindex directory listing on MS-DOS
-@vindex dired-listing-switches @r{(MS-DOS)}
- Dired on MS-DOS uses the @code{ls-lisp} package where other
-platforms use the system @code{ls} command. Therefore, Dired on
-MS-DOS supports only some of the possible options you can mention in
-the @code{dired-listing-switches} variable. The options that work are
-@samp{-A}, @samp{-a}, @samp{-c}, @samp{-i}, @samp{-r}, @samp{-S},
-@samp{-s}, @samp{-t}, and @samp{-u}.
-
-@ignore
- arch-tag: 868d50ff-07f8-4a13-a807-dab6f1cdb431
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Microsoft Windows, Manifesto, Mac OS, Top
-@appendix Emacs and Microsoft Windows/MS-DOS
-@cindex Microsoft Windows
-@cindex MS-Windows, Emacs peculiarities
-
- This section describes peculiarities of using Emacs on Microsoft
-Windows. Some of these peculiarities are also relevant to Microsoft's
-older MS-DOS ``operating system'' (also known as ``MS-DOG'').
-However, Emacs features that are relevant @emph{only} to MS-DOS are
-described in a separate
-@iftex
-manual (@pxref{MS-DOS,,, emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-section (@pxref{MS-DOS}).
-@end ifnottex
-
-
- The behavior of Emacs on MS-Windows is reasonably similar to what is
-documented in the rest of the manual, including support for long file
-names, multiple frames, scroll bars, mouse menus, and subprocesses.
-However, a few special considerations apply, and they are described
-here.
-
-@menu
-* Text and Binary:: Text files use CRLF to terminate lines.
-* Windows Files:: File-name conventions on Windows.
-* ls in Lisp:: Emulation of @code{ls} for Dired.
-* Windows HOME:: Where Emacs looks for your @file{.emacs}.
-* Windows Keyboard:: Windows-specific keyboard features.
-* Windows Mouse:: Windows-specific mouse features.
-* Windows Processes:: Running subprocesses on Windows.
-* Windows Printing:: How to specify the printer on MS-Windows.
-* Windows Misc:: Miscellaneous Windows features.
-@ifnottex
-* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}).
-@end ifnottex
-@end menu
-
-@node Text and Binary
-@section Text Files and Binary Files
-@cindex text and binary files on MS-DOS/MS-Windows
-
- GNU Emacs uses newline characters to separate text lines. This is the
-convention used on GNU, Unix, and other Posix-compliant systems.
-
-@cindex end-of-line conversion on MS-DOS/MS-Windows
- By contrast, MS-DOS and MS-Windows normally use carriage-return linefeed,
-a two-character sequence, to separate text lines. (Linefeed is the same
-character as newline.) Therefore, convenient editing of typical files
-with Emacs requires conversion of these end-of-line (EOL) sequences.
-And that is what Emacs normally does: it converts carriage-return
-linefeed into newline when reading files, and converts newline into
-carriage-return linefeed when writing files. The same mechanism that
-handles conversion of international character codes does this conversion
-also (@pxref{Coding Systems}).
-
-@cindex cursor location, on MS-DOS
-@cindex point location, on MS-DOS
- One consequence of this special format-conversion of most files is
-that character positions as reported by Emacs (@pxref{Position Info}) do
-not agree with the file size information known to the operating system.
-
- In addition, if Emacs recognizes from a file's contents that it uses
-newline rather than carriage-return linefeed as its line separator, it
-does not perform EOL conversion when reading or writing that file.
-Thus, you can read and edit files from GNU and Unix systems on MS-DOS
-with no special effort, and they will retain their Unix-style
-end-of-line convention after you edit them.
-
- The mode line indicates whether end-of-line translation was used for
-the current buffer. If MS-DOS end-of-line translation is in use for the
-buffer, the MS-Windows build of Emacs displays a backslash @samp{\} after
-the coding system mnemonic near the beginning of the mode line
-(@pxref{Mode Line}). If no EOL translation was performed, the string
-@samp{(Unix)} is displayed instead of the backslash, to alert you that the
-file's EOL format is not the usual carriage-return linefeed.
-
-@cindex DOS-to-Unix conversion of files
- To visit a file and specify whether it uses DOS-style or Unix-style
-end-of-line, specify a coding system (@pxref{Text Coding}). For
-example, @kbd{C-x @key{RET} c unix @key{RET} C-x C-f foobar.txt}
-visits the file @file{foobar.txt} without converting the EOLs; if some
-line ends with a carriage-return linefeed pair, Emacs will display
-@samp{^M} at the end of that line. Similarly, you can direct Emacs to
-save a buffer in a specified EOL format with the @kbd{C-x @key{RET} f}
-command. For example, to save a buffer with Unix EOL format, type
-@kbd{C-x @key{RET} f unix @key{RET} C-x C-s}. If you visit a file
-with DOS EOL conversion, then save it with Unix EOL format, that
-effectively converts the file to Unix EOL style, like @code{dos2unix}.
-
-@cindex untranslated file system
-@findex add-untranslated-filesystem
- When you use NFS, Samba, or some other similar method to access file
-systems that reside on computers using GNU or Unix systems, Emacs
-should not perform end-of-line translation on any files in these file
-systems---not even when you create a new file. To request this,
-designate these file systems as @dfn{untranslated} file systems by
-calling the function @code{add-untranslated-filesystem}. It takes one
-argument: the file system name, including a drive letter and
-optionally a directory. For example,
-
-@example
-(add-untranslated-filesystem "Z:")
-@end example
-
-@noindent
-designates drive Z as an untranslated file system, and
-
-@example
-(add-untranslated-filesystem "Z:\\foo")
-@end example
-
-@noindent
-designates directory @file{\foo} on drive Z as an untranslated file
-system.
-
- Most often you would use @code{add-untranslated-filesystem} in your
-@file{.emacs} file, or in @file{site-start.el} so that all the users at
-your site get the benefit of it.
-
-@findex remove-untranslated-filesystem
- To countermand the effect of @code{add-untranslated-filesystem}, use
-the function @code{remove-untranslated-filesystem}. This function takes
-one argument, which should be a string just like the one that was used
-previously with @code{add-untranslated-filesystem}.
-
- Designating a file system as untranslated does not affect character
-set conversion, only end-of-line conversion. Essentially, it directs
-Emacs to create new files with the Unix-style convention of using
-newline at the end of a line. @xref{Coding Systems}.
-
-@vindex file-name-buffer-file-type-alist
-@cindex binary files, on MS-DOS/MS-Windows
- Some kinds of files should not be converted at all, because their
-contents are not really text. Therefore, Emacs on MS-Windows distinguishes
-certain files as @dfn{binary files}. (This distinction is not part of
-MS-Windows; it is made by Emacs only.) Binary files include executable
-programs, compressed archives, etc. Emacs uses the file name to decide
-whether to treat a file as binary: the variable
-@code{file-name-buffer-file-type-alist} defines the file-name patterns
-that indicate binary files. If a file name matches one of the patterns
-for binary files (those whose associations are of the type
-@code{(@var{pattern} . t)}, Emacs reads and writes that file using the
-@code{no-conversion} coding system (@pxref{Coding Systems}) which turns
-off @emph{all} coding-system conversions, not only the EOL conversion.
-@code{file-name-buffer-file-type-alist} also includes file-name patterns
-for files which are known to be Windows-style text files with
-carriage-return linefeed EOL format, such as @file{CONFIG.SYS}; Emacs
-always writes those files with Windows-style EOLs.
-
- If a file which belongs to an untranslated file system matches one of
-the file-name patterns in @code{file-name-buffer-file-type-alist}, the
-EOL conversion is determined by @code{file-name-buffer-file-type-alist}.
-
-@node Windows Files
-@section File Names on MS-Windows
-@cindex file names on MS-Windows
-
- MS-Windows and MS-DOS normally use a backslash, @samp{\}, to
-separate name units within a file name, instead of the slash used on
-other systems. Emacs on MS-DOS/MS-Windows permits use of either slash or
-backslash, and also knows about drive letters in file names.
-
-@cindex file-name completion, on MS-Windows
- On MS-DOS/MS-Windows, file names are case-insensitive, so Emacs by
-default ignores letter-case in file names during completion.
-
-@vindex w32-get-true-file-attributes
- If the variable @code{w32-get-true-file-attributes} is
-non-@code{nil} (the default), Emacs tries to determine the accurate
-link counts for files. This option is only useful on NTFS volumes,
-and it considerably slows down Dired and other features, so use it
-only on fast machines.
-
-@node ls in Lisp
-@section Emulation of @code{ls} on MS-Windows
-@cindex Dired, and MS-Windows/MS-DOS
-@cindex @code{ls} emulation
-
- Dired normally uses the external program @code{ls} (or its close
-work-alike) to produce the directory listing displayed in Dired
-buffers (@pxref{Dired}). However, MS-Windows and MS-DOS systems don't
-come with such a program, although several ports of @sc{gnu} @code{ls}
-are available. Therefore, Emacs on those systems @emph{emulates}
-@code{ls} in Lisp, by using the @file{ls-lisp.el} package. While
-@file{ls-lisp.el} provides a reasonably full emulation of @code{ls},
-there are some options and features peculiar to that emulation;
-@iftex
-for more details, see the documentation of the variables whose names
-begin with @code{ls-lisp}.
-@end iftex
-@ifnottex
-they are described in this section.
-
- The @code{ls} emulation supports many of the @code{ls} switches, but
-it doesn't support all of them. Here's the list of the switches it
-does support: @option{-A}, @option{-a}, @option{-B}, @option{-C},
-@option{-c}, @option{-i}, @option{-G}, @option{-g}, @option{-R},
-@option{-r}, @option{-S}, @option{-s}, @option{-t}, @option{-U},
-@option{-u}, and @option{-X}. The @option{-F} switch is partially
-supported (it appends the character that classifies the file, but does
-not prevent symlink following).
-
-@vindex ls-lisp-use-insert-directory-program
- On MS-Windows and MS-DOS, @file{ls-lisp.el} is preloaded when Emacs
-is built, so the Lisp emulation of @code{ls} is always used on those
-platforms. If you have a ported @code{ls}, setting
-@code{ls-lisp-use-insert-directory-program} to a non-@code{nil} value
-will revert to using an external program named by the variable
-@code{insert-directory-program}.
-
-@vindex ls-lisp-ignore-case
- By default, @file{ls-lisp.el} uses a case-sensitive sort order for
-the directory listing it produces; this is so the listing looks the
-same as on other platforms. If you wish that the files be sorted in
-case-insensitive order, set the variable @code{ls-lisp-ignore-case} to
-a non-@code{nil} value.
-
-@vindex ls-lisp-dirs-first
- By default, files and subdirectories are sorted together, to emulate
-the behavior of @code{ls}. However, native MS-Windows/MS-DOS file
-managers list the directories before the files; if you want that
-behavior, customize the option @code{ls-lisp-dirs-first} to a
-non-@code{nil} value.
-
-@vindex ls-lisp-verbosity
- The variable @code{ls-lisp-verbosity} controls the file attributes
-that @file{ls-lisp.el} displays. The value should be a list that
-contains one or more of the symbols @code{links}, @code{uid}, and
-@code{gid}. @code{links} means display the count of different file
-names that are associated with (a.k.a.@: @dfn{links to}) the file's
-data; this is only useful on NTFS volumes. @code{uid} means display
-the numerical identifier of the user who owns the file. @code{gid}
-means display the numerical identifier of the file owner's group. The
-default value is @code{(links uid gid)} i.e.@: all the 3 optional
-attributes are displayed.
-
-@vindex ls-lisp-emulation
- The variable @code{ls-lisp-emulation} controls the flavour of the
-@code{ls} emulation by setting the defaults for the 3 options
-described above: @code{ls-lisp-ignore-case},
-@code{ls-lisp-dirs-first}, and @code{ls-lisp-verbosity}. The value of
-this option can be one of the following symbols:
-
-@table @code
-@item GNU
-@itemx nil
-Emulate @sc{gnu} systems; this is the default. This sets
-@code{ls-lisp-ignore-case} and @code{ls-lisp-dirs-first} to
-@code{nil}, and @code{ls-lisp-verbosity} to @code{(links uid gid)}.
-@item UNIX
-Emulate Unix systems. Like @code{GNU}, but sets
-@code{ls-lisp-verbosity} to @code{(links uid)}.
-@item MacOS
-Emulate MacOS. Sets @code{ls-lisp-ignore-case} to @code{t}, and
-@code{ls-lisp-dirs-first} and @code{ls-lisp-verbosity} to @code{nil}.
-@item MS-Windows
-Emulate MS-Windows. Sets @code{ls-lisp-ignore-case} and
-@code{ls-lisp-dirs-first} to @code{t}, and @code{ls-lisp-verbosity} to
-@code{(links)} on Windows NT/2K/XP/2K3 and to @code{nil} on Windows 9X.
-Note that the default emulation is @emph{not} @code{MS-Windows}, even
-on Windows, since many users of Emacs on those platforms prefer the
-@sc{gnu} defaults.
-@end table
-
-@noindent
-Any other value of @code{ls-lisp-emulation} means the same as
-@code{GNU}. Note that this option needs to be set @emph{before}
-@file{ls-lisp.el} is loaded, which means that on MS-Windows and MS-DOS
-you will have to set the value from your @file{.emacs} file and then
-restart Emacs, since @file{ls-lisp.el} is preloaded.
-
-@vindex ls-lisp-support-shell-wildcards
- The variable @code{ls-lisp-support-shell-wildcards} controls how
-file-name patterns are supported: if it is non-@code{nil} (the
-default), they are treated as shell-style wildcards; otherwise they
-are treated as Emacs regular expressions.
-
-@vindex ls-lisp-format-time-list
- The variable @code{ls-lisp-format-time-list} defines how to format
-the date and time of files. @emph{The value of this variable is
-ignored}, unless Emacs cannot determine the current locale. (However,
-if the value of @code{ls-lisp-use-localized-time-format} is
-non-@code{nil}, Emacs obeys @code{ls-lisp-format-time-list} even if
-the current locale is available; see below.)
-
-The value of @code{ls-lisp-format-time-list} is a list of 2 strings.
-The first string is used if the file was modified within the current
-year, while the second string is used for older files. In each of
-these two strings you can use @samp{%}-sequences to substitute parts
-of the time. For example:
-@lisp
-("%b %e %H:%M" "%b %e %Y")
-@end lisp
-
-@noindent
-Note that the strings substituted for these @samp{%}-sequences depend
-on the current locale. @xref{Time Parsing,,, elisp, The Emacs Lisp
-Reference Manual}, for more about format time specs.
-
-@vindex ls-lisp-use-localized-time-format
- Normally, Emacs formats the file time stamps in either traditional
-or ISO-style time format. However, if the value of the variable
-@code{ls-lisp-use-localized-time-format} is non-@code{nil}, Emacs
-formats file time stamps according to what
-@code{ls-lisp-format-time-list} specifies. The @samp{%}-sequences in
-@code{ls-lisp-format-time-list} produce locale-dependent month and day
-names, which might cause misalignment of columns in Dired display.
-@end ifnottex
-
-@node Windows HOME
-@section HOME Directory on MS-Windows
-@cindex @code{HOME} directory on MS-Windows
-
- The Windows equivalent of the @code{HOME} directory is the
-@dfn{user-specific application data directory}. The actual location
-depends on your Windows version and system configuration; typical values
-are @file{C:\Documents and Settings\@var{username}\Application Data} on
-Windows 2K/XP and later, and either @file{C:\WINDOWS\Application Data}
-or @file{C:\WINDOWS\Profiles\@var{username}\Application Data} on the
-older Windows 9X/ME systems.
-
-@cindex init file @file{.emacs} on MS-Windows
- The home directory is where your init file @file{.emacs} is stored.
-When Emacs starts, it first checks whether the environment variable
-@env{HOME} is set. If it is, it looks for the init file in the
-directory pointed by @env{HOME}. If @env{HOME} is not defined, Emacs
-checks for an existing @file{.emacs} file in @file{C:\}, the root
-directory of drive @file{C:}@footnote{
-The check in @file{C:\} is in preference to the application data
-directory for compatibility with older versions of Emacs, which didn't
-check the application data directory.
-}. If there's no such file in @file{C:\}, Emacs next uses the Windows
-system calls to find out the exact location of your application data
-directory. If that fails as well, Emacs falls back to @file{C:\}.
-
- Whatever the final place is, Emacs sets the value of the @env{HOME}
-environment variable to point to it, and it will use that location for
-other files and directories it normally creates in the user's home
-directory.
-
- You can always find out where Emacs thinks is your home directory's
-location by typing @kbd{C-x d ~/ @key{RET}}. This should present the
-list of files in the home directory, and show its full name on the
-first line. Likewise, to visit your init file, type @kbd{C-x C-f
-~/.emacs @key{RET}}.
-
-@cindex @file{_emacs} init file, MS-Windows
- Because MS-DOS does not allow file names with leading dots, and
-because older Windows systems made it hard to create files with such
-names, the Windows port of Emacs supports an alternative name
-@file{_emacs} as a fallback, if such a file exists in the home
-directory, whereas @file{.emacs} does not.
-
-@node Windows Keyboard
-@section Keyboard Usage on MS-Windows
-@cindex keyboard, MS-Windows
-
- This section describes the Windows-specific features related to
-keyboard input in Emacs.
-
-@cindex MS-Windows keyboard shortcuts
- Many key combinations (known as ``keyboard shortcuts'') that have
-conventional uses in MS-Windows programs conflict with traditional
-Emacs key bindings. (These Emacs key bindings were established years
-before Microsoft was founded.) Examples of conflicts include
-@kbd{C-c}, @kbd{C-x}, @kbd{C-z}, @kbd{C-a}, and @kbd{W-@key{SPC}}.
-You can redefine some of them with meanings more like the MS-Windows
-meanings by enabling CUA Mode (@pxref{CUA Bindings}).
-
-@kindex F10 @r{(MS-Windows)}
-@cindex menu bar access using keyboard @r{(MS-Windows)}
- The @key{F10} key on Windows activates the menu bar in a way that
-makes it possible to use the menus without a mouse. In this mode, the
-arrow keys traverse the menus, @key{RET} selects a highlighted menu
-item, and @key{ESC} closes the menu.
-
-@iftex
-@inforef{Windows Keyboard, , emacs}, for information about additional
-Windows-specific variables in this category.
-@end iftex
-@ifnottex
-@vindex w32-alt-is-meta
-@cindex @code{Alt} key (MS-Windows)
- By default, the key labeled @key{Alt} is mapped as the @key{META}
-key. If you wish it to produce the @code{Alt} modifier instead, set
-the variable @code{w32-alt-is-meta} to a @code{nil} value.
-
-@vindex w32-capslock-is-shiftlock
- By default, the @key{CapsLock} key only affects normal character
-keys (it converts lower-case characters to their upper-case
-variants). However, if you set the variable
-@code{w32-capslock-is-shiftlock} to a non-@code{nil} value, the
-@key{CapsLock} key will affect non-character keys as well, as if you
-pressed the @key{Shift} key while typing the non-character key.
-
-@vindex w32-enable-caps-lock
- If the variable @code{w32-enable-caps-lock} is set to a @code{nil}
-value, the @key{CapsLock} key produces the symbol @code{capslock}
-instead of the shifted version of they keys. The default value is
-@code{t}.
-
-@vindex w32-enable-num-lock
-@cindex keypad keys (MS-Windows)
- Similarly, if @code{w32-enable-num-lock} is @code{nil}, the
-@key{NumLock} key will produce the symbol @code{kp-numlock}. The
-default is @code{t}, which causes @key{NumLock} to work as expected:
-toggle the meaning of the keys on the numeric keypad.
-@end ifnottex
-
-@vindex w32-apps-modifier
- The variable @code{w32-apps-modifier} controls the effect of the
-@key{Apps} key (usually located between the right @key{Alt} and the
-right @key{Ctrl} keys). Its value can be one of the symbols
-@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control},
-or @code{shift} for the respective modifier, or @code{nil} to appear
-as the key @code{apps}. The default is @code{nil}.
-
-@vindex w32-lwindow-modifier
-@vindex w32-rwindow-modifier
-@vindex w32-scroll-lock-modifier
- The variable @code{w32-lwindow-modifier} determines the effect of
-the left Windows key (usually labeled with @key{start} and the Windows
-logo). If its value is @code{nil} (the default), the key will produce
-the symbol @code{lwindow}. Setting it to one of the symbols
-@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control},
-or @code{shift} will produce the respective modifier. A similar
-variable @code{w32-rwindow-modifier} controls the effect of the right
-Windows key, and @code{w32-scroll-lock-modifier} does the same for the
-@key{ScrLock} key. If these variables are set to @code{nil}, the
-right Windows key produces the symbol @code{rwindow} and @key{ScrLock}
-produces the symbol @code{scroll}.
-
-@vindex w32-pass-alt-to-system
-@cindex Windows system menu
-@cindex @code{Alt} key invokes menu (Windows)
- Emacs compiled as a native Windows application normally turns off
-the Windows feature that tapping the @key{ALT} key invokes the Windows
-menu. The reason is that the @key{ALT} serves as @key{META} in Emacs.
-When using Emacs, users often press the @key{META} key temporarily and
-then change their minds; if this has the effect of bringing up the
-Windows menu, it alters the meaning of subsequent commands. Many
-users find this frustrating.
-
- You can re-enable Windows' default handling of tapping the @key{ALT}
-key by setting @code{w32-pass-alt-to-system} to a non-@code{nil}
-value.
-
-@ifnottex
-@vindex w32-pass-lwindow-to-system
-@vindex w32-pass-rwindow-to-system
- The variables @code{w32-pass-lwindow-to-system} and
-@code{w32-pass-rwindow-to-system} determine whether the respective
-keys are passed to Windows or swallowed by Emacs. If the value is
-@code{nil}, the respective key is silently swallowed by Emacs,
-otherwise it is passed to Windows. The default is @code{t} for both
-of these variables. Passing each of these keys to Windows produces
-its normal effect: for example, @kbd{@key{Lwindow}} opens the
-@code{Start} menu, etc.@footnote{
-Some combinations of the ``Windows'' keys with other keys are caught
-by Windows at low level in a way that Emacs currently cannot prevent.
-For example, @kbd{@key{Lwindow} r} always pops up the Windows
-@samp{Run} dialog. Customizing the value of
-@code{w32-phantom-key-code} might help in some cases, though.}
-
-@vindex w32-recognize-altgr
-@kindex AltGr @r{(MS-Windows)}
-@cindex AltGr key (MS-Windows)
- The variable @code{w32-recognize-altgr} controls whether the
-@key{AltGr} key (if it exists on your keyboard), or its equivalent,
-the combination of the right @key{Alt} and left @key{Ctrl} keys
-pressed together, is recognized as the @key{AltGr} key. The default
-is @code{t}, which means these keys produce @code{AltGr}; setting it
-to @code{nil} causes @key{AltGr} or the equivalent key combination to
-be interpreted as the combination of @key{CTRL} and @key{META}
-modifiers.
-@end ifnottex
-
-@node Windows Mouse
-@section Mouse Usage on MS-Windows
-@cindex mouse, and MS-Windows
-
- This section describes the Windows-specific variables related to
-mouse.
-
-@vindex w32-mouse-button-tolerance
-@cindex simulation of middle mouse button
- The variable @code{w32-mouse-button-tolerance} specifies the
-time interval, in milliseconds, for faking middle mouse button press
-on 2-button mice. If both mouse buttons are depressed within this
-time interval, Emacs generates a middle mouse button click event
-instead of a double click on one of the buttons.
-
-@vindex w32-pass-extra-mouse-buttons-to-system
- If the variable @code{w32-pass-extra-mouse-buttons-to-system} is
-non-@code{nil}, Emacs passes the fourth and fifth mouse buttons to
-Windows.
-
-@vindex w32-swap-mouse-buttons
- The variable @code{w32-swap-mouse-buttons} controls which of the 3
-mouse buttons generates the @kbd{mouse-2} events. When it is
-@code{nil} (the default), the middle button generates @kbd{mouse-2}
-and the right button generates @kbd{mouse-3} events. If this variable
-is non-@code{nil}, the roles of these two buttons are reversed.
-
-@node Windows Processes
-@section Subprocesses on Windows 9X/ME and Windows NT/2K/XP
-@cindex subprocesses on MS-Windows
-
-@cindex DOS applications, running from Emacs
- Emacs compiled as a native Windows application (as opposed to the DOS
-version) includes full support for asynchronous subprocesses.
-In the Windows version, synchronous and asynchronous subprocesses work
-fine on both
-Windows 9X/ME and Windows NT/2K/XP as long as you run only 32-bit Windows
-applications. However, when you run a DOS application in a subprocess,
-you may encounter problems or be unable to run the application at all;
-and if you run two DOS applications at the same time in two
-subprocesses, you may have to reboot your system.
-
-Since the standard command interpreter (and most command line utilities)
-on Windows 9X are DOS applications, these problems are significant when
-using that system. But there's nothing we can do about them; only
-Microsoft can fix them.
-
-If you run just one DOS application subprocess, the subprocess should
-work as expected as long as it is ``well-behaved'' and does not perform
-direct screen access or other unusual actions. If you have a CPU
-monitor application, your machine will appear to be 100% busy even when
-the DOS application is idle, but this is only an artifact of the way CPU
-monitors measure processor load.
-
-You must terminate the DOS application before you start any other DOS
-application in a different subprocess. Emacs is unable to interrupt or
-terminate a DOS subprocess. The only way you can terminate such a
-subprocess is by giving it a command that tells its program to exit.
-
-If you attempt to run two DOS applications at the same time in separate
-subprocesses, the second one that is started will be suspended until the
-first one finishes, even if either or both of them are asynchronous.
-
-@cindex kill DOS application
-If you can go to the first subprocess, and tell it to exit, the second
-subprocess should continue normally. However, if the second subprocess
-is synchronous, Emacs itself will be hung until the first subprocess
-finishes. If it will not finish without user input, then you have no
-choice but to reboot if you are running on Windows 9X. If you are
-running on Windows NT/2K/XP, you can use a process viewer application to kill
-the appropriate instance of NTVDM instead (this will terminate both DOS
-subprocesses).
-
-If you have to reboot Windows 9X in this situation, do not use the
-@code{Shutdown} command on the @code{Start} menu; that usually hangs the
-system. Instead, type @kbd{CTL-ALT-@key{DEL}} and then choose
-@code{Shutdown}. That usually works, although it may take a few minutes
-to do its job.
-
-@vindex w32-quote-process-args
- The variable @code{w32-quote-process-args} controls how Emacs quotes
-the process arguments. Non-@code{nil} means quote with the @code{"}
-character. If the value is a character, use that character to escape
-any quote characters that appear; otherwise chose a suitable escape
-character based on the type of the program.
-
-@ifnottex
-@findex w32-shell-execute
- The function @code{w32-shell-execute} can be useful for writing
-customized commands that run MS-Windows applications registered to
-handle a certain standard Windows operation for a specific type of
-document or file. This function is a wrapper around the Windows
-@code{ShellExecute} API. See the MS-Windows API documentation for
-more details.
-@end ifnottex
-
-@node Windows Printing
-@section Printing and MS-Windows
-
- Printing commands, such as @code{lpr-buffer} (@pxref{Printing}) and
-@code{ps-print-buffer} (@pxref{PostScript}) work in MS-DOS and
-MS-Windows by sending the output to one of the printer ports, if a
-Posix-style @code{lpr} program is unavailable. The same Emacs
-variables control printing on all systems, but in some cases they have
-different default values on MS-DOS and MS-Windows.
-
- Emacs on Windows automatically determines your default printer and
-sets the variable @var{printer-name} to that printer's name. But in
-some rare cases this can fail, or you may wish to use a different
-printer from within Emacs. The rest of this section explains how to
-tell Emacs which printer to use.
-
-@vindex printer-name@r{, (MS-DOS/MW-Windows)}
- If you want to use your local printer, then set the Lisp variable
-@code{lpr-command} to @code{""} (its default value on Windows) and
-@code{printer-name} to the name of the printer port---for example,
-@code{"PRN"}, the usual local printer port or @code{"LPT2"}, or
-@code{"COM1"} for a serial printer. You can also set
-@code{printer-name} to a file name, in which case ``printed'' output
-is actually appended to that file. If you set @code{printer-name} to
-@code{"NUL"}, printed output is silently discarded (sent to the system
-null device).
-
- You can also use a printer shared by another machine by setting
-@code{printer-name} to the UNC share name for that printer---for
-example, @code{"//joes_pc/hp4si"}. (It doesn't matter whether you use
-forward slashes or backslashes here.) To find out the names of shared
-printers, run the command @samp{net view} from the command prompt to
-obtain a list of servers, and @samp{net view @var{server-name}} to see
-the names of printers (and directories) shared by that server.
-Alternatively, click the @samp{Network Neighborhood} icon on your
-desktop, and look for machines which share their printers via the
-network.
-
-@cindex @samp{net use}, and printing on MS-Windows
-@cindex networked printers (MS-Windows)
- If the printer doesn't appear in the output of @samp{net view}, or
-if setting @code{printer-name} to the UNC share name doesn't produce a
-hardcopy on that printer, you can use the @samp{net use} command to
-connect a local print port such as @code{"LPT2"} to the networked
-printer. For example, typing @kbd{net use LPT2: \\joes_pc\hp4si}@footnote{
-Note that the @samp{net use} command requires the UNC share name to be
-typed with the Windows-style backslashes, while the value of
-@code{printer-name} can be set with either forward- or backslashes.}
-causes Windows to @dfn{capture} the @code{LPT2} port and redirect the
-printed material to the printer connected to the machine @code{joes_pc}.
-After this command, setting @code{printer-name} to @code{"LPT2"}
-should produce the hardcopy on the networked printer.
-
- With some varieties of Windows network software, you can instruct
-Windows to capture a specific printer port such as @code{"LPT2"}, and
-redirect it to a networked printer via the @w{@code{Control
-Panel->Printers}} applet instead of @samp{net use}.
-
- If you set @code{printer-name} to a file name, it's best to use an
-absolute file name. Emacs changes the working directory according to
-the default directory of the current buffer, so if the file name in
-@code{printer-name} is relative, you will end up with several such
-files, each one in the directory of the buffer from which the printing
-was done.
-
- If the value of @code{printer-name} is correct, but printing does
-not produce the hardcopy on your printer, it is possible that your
-printer does not support printing plain text (some cheap printers omit
-this functionality). In that case, try the PostScript print commands,
-described below.
-
-@findex print-buffer @r{(MS-DOS)}
-@findex print-region @r{(MS-DOS)}
-@vindex lpr-headers-switches @r{(MS-DOS)}
- The commands @code{print-buffer} and @code{print-region} call the
-@code{pr} program, or use special switches to the @code{lpr} program, to
-produce headers on each printed page. MS-DOS and MS-Windows don't
-normally have these programs, so by default, the variable
-@code{lpr-headers-switches} is set so that the requests to print page
-headers are silently ignored. Thus, @code{print-buffer} and
-@code{print-region} produce the same output as @code{lpr-buffer} and
-@code{lpr-region}, respectively. If you do have a suitable @code{pr}
-program (for example, from GNU Coreutils), set
-@code{lpr-headers-switches} to @code{nil}; Emacs will then call
-@code{pr} to produce the page headers, and print the resulting output as
-specified by @code{printer-name}.
-
-@vindex print-region-function @r{(MS-DOS)}
-@cindex lpr usage under MS-DOS
-@vindex lpr-command @r{(MS-DOS)}
-@vindex lpr-switches @r{(MS-DOS)}
- Finally, if you do have an @code{lpr} work-alike, you can set the
-variable @code{lpr-command} to @code{"lpr"}. Then Emacs will use
-@code{lpr} for printing, as on other systems. (If the name of the
-program isn't @code{lpr}, set @code{lpr-command} to specify where to
-find it.) The variable @code{lpr-switches} has its standard meaning
-when @code{lpr-command} is not @code{""}. If the variable
-@code{printer-name} has a string value, it is used as the value for the
-@code{-P} option to @code{lpr}, as on Unix.
-
-@findex ps-print-buffer @r{(MS-DOS)}
-@findex ps-spool-buffer @r{(MS-DOS)}
-@vindex ps-printer-name @r{(MS-DOS)}
-@vindex ps-lpr-command @r{(MS-DOS)}
-@vindex ps-lpr-switches @r{(MS-DOS)}
- A parallel set of variables, @code{ps-lpr-command},
-@code{ps-lpr-switches}, and @code{ps-printer-name} (@pxref{PostScript
-Variables}), defines how PostScript files should be printed. These
-variables are used in the same way as the corresponding variables
-described above for non-PostScript printing. Thus, the value of
-@code{ps-printer-name} is used as the name of the device (or file) to
-which PostScript output is sent, just as @code{printer-name} is used
-for non-PostScript printing. (There are two distinct sets of
-variables in case you have two printers attached to two different
-ports, and only one of them is a PostScript printer.)
-
- The default value of the variable @code{ps-lpr-command} is @code{""},
-which causes PostScript output to be sent to the printer port specified
-by @code{ps-printer-name}, but @code{ps-lpr-command} can also be set to
-the name of a program which will accept PostScript files. Thus, if you
-have a non-PostScript printer, you can set this variable to the name of
-a PostScript interpreter program (such as Ghostscript). Any switches
-that need to be passed to the interpreter program are specified using
-@code{ps-lpr-switches}. (If the value of @code{ps-printer-name} is a
-string, it will be added to the list of switches as the value for the
-@code{-P} option. This is probably only useful if you are using
-@code{lpr}, so when using an interpreter typically you would set
-@code{ps-printer-name} to something other than a string so it is
-ignored.)
-
- For example, to use Ghostscript for printing on the system's default
-printer, put this in your @file{.emacs} file:
-
-@example
-(setq ps-printer-name t)
-(setq ps-lpr-command "D:/gs6.01/bin/gswin32c.exe")
-(setq ps-lpr-switches '("-q" "-dNOPAUSE" "-dBATCH"
- "-sDEVICE=mswinpr2"
- "-sPAPERSIZE=a4"))
-@end example
-
-@noindent
-(This assumes that Ghostscript is installed in the
-@file{D:/gs6.01} directory.)
-
-@node Windows Misc
-@section Miscellaneous Windows-specific features
-
- This section describes miscellaneous Windows-specific features.
-
-@vindex w32-use-visible-system-caret
-@cindex screen reader software, MS-Windows
- The variable @code{w32-use-visible-system-caret} is a flag that
-determines whether to make the system caret visible. The default is
-@code{nil}, which means Emacs draws its own cursor to indicate the
-position of point. A non-@code{nil} value means Emacs will indicate
-point location by the system caret; this facilitates use of screen
-reader software. When this variable is non-@code{nil}, other
-variables affecting the cursor display have no effect.
-
-@iftex
-@inforef{Windows Misc, , emacs}, for information about additional
-Windows-specific variables in this category.
-@end iftex
-
-@ifnottex
-@vindex w32-grab-focus-on-raise
-@cindex frame focus policy, MS-Windows
- The variable @code{w32-grab-focus-on-raise}, if set to a
-non-@code{nil} value causes a frame to grab focus when it is raised.
-The default is @code{t}, which fits well with the Windows default
-click-to-focus policy.
-
-@vindex w32-list-proportional-fonts
- The variable @code{w32-list-proportional-fonts} controls whether
-proportional fonts are included in the font selection dialog. If its
-value is non-@code{nil}, these fonts will be included. The default is
-@code{nil}.
-@end ifnottex
-
-@ifnottex
-@include msdog-xtra.texi
-@end ifnottex
-
-@ignore
- arch-tag: f39d2590-5dcc-4318-88d9-0eb73ca10fa2
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1997, 1999, 2000, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node International, Major Modes, Frames, Top
-@chapter International Character Set Support
-@cindex MULE
-@cindex international scripts
-@cindex multibyte characters
-@cindex encoding of characters
-
-@cindex Celtic
-@cindex Chinese
-@cindex Cyrillic
-@cindex Czech
-@cindex Devanagari
-@cindex Hindi
-@cindex Marathi
-@cindex Ethiopic
-@cindex German
-@cindex Greek
-@cindex Hebrew
-@cindex IPA
-@cindex Japanese
-@cindex Korean
-@cindex Lao
-@cindex Latin
-@cindex Polish
-@cindex Romanian
-@cindex Slovak
-@cindex Slovenian
-@cindex Thai
-@cindex Tibetan
-@cindex Turkish
-@cindex Vietnamese
-@cindex Dutch
-@cindex Spanish
- Emacs supports a wide variety of international character sets,
-including European and Vietnamese variants of the Latin alphabet, as
-well as Cyrillic, Devanagari (for Hindi and Marathi), Ethiopic, Greek,
-Han (for Chinese and Japanese), Hangul (for Korean), Hebrew, IPA,
-Kannada, Lao, Malayalam, Tamil, Thai, Tibetan, and Vietnamese scripts.
-Emacs also supports various encodings of these characters used by
-other internationalized software, such as word processors and mailers.
-
- Emacs allows editing text with international characters by supporting
-all the related activities:
-
-@itemize @bullet
-@item
-You can visit files with non-@acronym{ASCII} characters, save non-@acronym{ASCII} text, and
-pass non-@acronym{ASCII} text between Emacs and programs it invokes (such as
-compilers, spell-checkers, and mailers). Setting your language
-environment (@pxref{Language Environments}) takes care of setting up the
-coding systems and other options for a specific language or culture.
-Alternatively, you can specify how Emacs should encode or decode text
-for each command; see @ref{Text Coding}.
-
-@item
-You can display non-@acronym{ASCII} characters encoded by the various
-scripts. This works by using appropriate fonts on graphics displays
-(@pxref{Defining Fontsets}), and by sending special codes to text-only
-displays (@pxref{Terminal Coding}). If some characters are displayed
-incorrectly, refer to @ref{Undisplayable Characters}, which describes
-possible problems and explains how to solve them.
-
-@item
-You can insert non-@acronym{ASCII} characters or search for them. To do that,
-you can specify an input method (@pxref{Select Input Method}) suitable
-for your language, or use the default input method set up when you set
-your language environment. If
-your keyboard can produce non-@acronym{ASCII} characters, you can select an
-appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs
-will accept those characters. Latin-1 characters can also be input by
-using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}.
-
-On X Window systems, your locale should be set to an appropriate value
-to make sure Emacs interprets keyboard input correctly; see
-@ref{Language Environments, locales}.
-@end itemize
-
- The rest of this chapter describes these issues in detail.
-
-@menu
-* International Chars:: Basic concepts of multibyte characters.
-* Enabling Multibyte:: Controlling whether to use multibyte characters.
-* Language Environments:: Setting things up for the language you use.
-* Input Methods:: Entering text characters not on your keyboard.
-* Select Input Method:: Specifying your choice of input methods.
-* Multibyte Conversion:: How single-byte characters convert to multibyte.
-* Coding Systems:: Character set conversion when you read and
- write files, and so on.
-* Recognize Coding:: How Emacs figures out which conversion to use.
-* Specify Coding:: Specifying a file's coding system explicitly.
-* Output Coding:: Choosing coding systems for output.
-* Text Coding:: Choosing conversion to use for file text.
-* Communication Coding:: Coding systems for interprocess communication.
-* File Name Coding:: Coding systems for file @emph{names}.
-* Terminal Coding:: Specifying coding systems for converting
- terminal input and output.
-* Fontsets:: Fontsets are collections of fonts
- that cover the whole spectrum of characters.
-* Defining Fontsets:: Defining a new fontset.
-* Undisplayable Characters:: When characters don't display.
-* Unibyte Mode:: You can pick one European character set
- to use without multibyte characters.
-* Charsets:: How Emacs groups its internal character codes.
-@end menu
-
-@node International Chars
-@section Introduction to International Character Sets
-
- The users of international character sets and scripts have
-established many more-or-less standard coding systems for storing
-files. Emacs internally uses a single multibyte character encoding,
-so that it can intermix characters from all these scripts in a single
-buffer or string. This encoding represents each non-@acronym{ASCII}
-character as a sequence of bytes in the range 0200 through 0377.
-Emacs translates between the multibyte character encoding and various
-other coding systems when reading and writing files, when exchanging
-data with subprocesses, and (in some cases) in the @kbd{C-q} command
-(@pxref{Multibyte Conversion}).
-
-@kindex C-h h
-@findex view-hello-file
-@cindex undisplayable characters
-@cindex @samp{?} in display
- The command @kbd{C-h h} (@code{view-hello-file}) displays the file
-@file{etc/HELLO}, which shows how to say ``hello'' in many languages.
-This illustrates various scripts. If some characters can't be
-displayed on your terminal, they appear as @samp{?} or as hollow boxes
-(@pxref{Undisplayable Characters}).
-
- Keyboards, even in the countries where these character sets are used,
-generally don't have keys for all the characters in them. So Emacs
-supports various @dfn{input methods}, typically one for each script or
-language, to make it convenient to type them.
-
-@kindex C-x RET
- The prefix key @kbd{C-x @key{RET}} is used for commands that pertain
-to multibyte characters, coding systems, and input methods.
-
-@node Enabling Multibyte
-@section Enabling Multibyte Characters
-
- By default, Emacs starts in multibyte mode, because that allows you to
-use all the supported languages and scripts without limitations.
-
-@cindex turn multibyte support on or off
- You can enable or disable multibyte character support, either for
-Emacs as a whole, or for a single buffer. When multibyte characters
-are disabled in a buffer, we call that @dfn{unibyte mode}. Then each
-byte in that buffer represents a character, even codes 0200 through
-0377.
-
- The old features for supporting the European character sets, ISO
-Latin-1 and ISO Latin-2, work in unibyte mode as they did in Emacs 19
-and also work for the other ISO 8859 character sets. However, there
-is no need to turn off multibyte character support to use ISO Latin;
-the Emacs multibyte character set includes all the characters in these
-character sets, and Emacs can translate automatically to and from the
-ISO codes.
-
- To edit a particular file in unibyte representation, visit it using
-@code{find-file-literally}. @xref{Visiting}. To convert a buffer in
-multibyte representation into a single-byte representation of the same
-characters, the easiest way is to save the contents in a file, kill the
-buffer, and find the file again with @code{find-file-literally}. You
-can also use @kbd{C-x @key{RET} c}
-(@code{universal-coding-system-argument}) and specify @samp{raw-text} as
-the coding system with which to find or save a file. @xref{Text
-Coding}. Finding a file as @samp{raw-text} doesn't disable format
-conversion, uncompression and auto mode selection as
-@code{find-file-literally} does.
-
-@vindex enable-multibyte-characters
-@vindex default-enable-multibyte-characters
- To turn off multibyte character support by default, start Emacs with
-the @samp{--unibyte} option (@pxref{Initial Options}), or set the
-environment variable @env{EMACS_UNIBYTE}. You can also customize
-@code{enable-multibyte-characters} or, equivalently, directly set the
-variable @code{default-enable-multibyte-characters} to @code{nil} in
-your init file to have basically the same effect as @samp{--unibyte}.
-
-@findex toggle-enable-multibyte-characters
- To convert a unibyte session to a multibyte session, set
-@code{default-enable-multibyte-characters} to @code{t}. Buffers which
-were created in the unibyte session before you turn on multibyte support
-will stay unibyte. You can turn on multibyte support in a specific
-buffer by invoking the command @code{toggle-enable-multibyte-characters}
-in that buffer.
-
-@cindex Lisp files, and multibyte operation
-@cindex multibyte operation, and Lisp files
-@cindex unibyte operation, and Lisp files
-@cindex init file, and non-@acronym{ASCII} characters
-@cindex environment variables, and non-@acronym{ASCII} characters
- With @samp{--unibyte}, multibyte strings are not created during
-initialization from the values of environment variables,
-@file{/etc/passwd} entries etc.@: that contain non-@acronym{ASCII} 8-bit
-characters.
-
- Emacs normally loads Lisp files as multibyte, regardless of whether
-you used @samp{--unibyte}. This includes the Emacs initialization file,
-@file{.emacs}, and the initialization files of Emacs packages such as
-Gnus. However, you can specify unibyte loading for a particular Lisp
-file, by putting @w{@samp{-*-unibyte: t;-*-}} in a comment on the first
-line (@pxref{File Variables}). Then that file is always loaded as
-unibyte text, even if you did not start Emacs with @samp{--unibyte}.
-The motivation for these conventions is that it is more reliable to
-always load any particular Lisp file in the same way. However, you can
-load a Lisp file as unibyte, on any one occasion, by typing @kbd{C-x
-@key{RET} c raw-text @key{RET}} immediately before loading it.
-
- The mode line indicates whether multibyte character support is
-enabled in the current buffer. If it is, there are two or more
-characters (most often two dashes) near the beginning of the mode
-line, before the indication of the visited file's end-of-line
-convention (colon, backslash, etc.). When multibyte characters
-are not enabled, nothing precedes the colon except a single dash.
-@xref{Mode Line}, for more details about this.
-
-@node Language Environments
-@section Language Environments
-@cindex language environments
-
- All supported character sets are supported in Emacs buffers whenever
-multibyte characters are enabled; there is no need to select a
-particular language in order to display its characters in an Emacs
-buffer. However, it is important to select a @dfn{language environment}
-in order to set various defaults. The language environment really
-represents a choice of preferred script (more or less) rather than a
-choice of language.
-
- The language environment controls which coding systems to recognize
-when reading text (@pxref{Recognize Coding}). This applies to files,
-incoming mail, netnews, and any other text you read into Emacs. It may
-also specify the default coding system to use when you create a file.
-Each language environment also specifies a default input method.
-
-@findex set-language-environment
-@vindex current-language-environment
- To select a language environment, you can customize the variable
-@code{current-language-environment} or use the command @kbd{M-x
-set-language-environment}. It makes no difference which buffer is
-current when you use this command, because the effects apply globally to
-the Emacs session. The supported language environments include:
-
-@cindex Euro sign
-@cindex UTF-8
-@quotation
-ASCII, Belarusian, Brazilian Portuguese, Bulgarian, Chinese-BIG5,
-Chinese-CNS, Chinese-EUC-TW, Chinese-GB, Croatian, Cyrillic-ALT,
-Cyrillic-ISO, Cyrillic-KOI8, Czech, Devanagari, Dutch, English,
-Esperanto, Ethiopic, French, Georgian, German, Greek, Hebrew, IPA,
-Italian, Japanese, Kannada, Korean, Lao, Latin-1, Latin-2, Latin-3,
-Latin-4, Latin-5, Latin-6, Latin-7, Latin-8 (Celtic), Latin-9 (updated
-Latin-1 with the Euro sign), Latvian, Lithuanian, Malayalam, Polish,
-Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Tajik, Tamil,
-Thai, Tibetan, Turkish, UTF-8 (for a setup which prefers Unicode
-characters and files encoded in UTF-8), Ukrainian, Vietnamese, Welsh,
-and Windows-1255 (for a setup which prefers Cyrillic characters and
-files encoded in Windows-1255).
-@tex
-\hbadness=10000\par % just avoid underfull hbox warning
-@end tex
-@end quotation
-
-@cindex fonts for various scripts
-@cindex Intlfonts package, installation
- To display the script(s) used by your language environment on a
-graphical display, you need to have a suitable font. If some of the
-characters appear as empty boxes, you should install the GNU Intlfonts
-package, which includes fonts for most supported scripts.@footnote{If
-you run Emacs on X, you need to inform the X server about the location
-of the newly installed fonts with the following commands:
-
-@example
- xset fp+ /usr/local/share/emacs/fonts
- xset fp rehash
-@end example
-}
-@xref{Fontsets}, for more details about setting up your fonts.
-
-@findex set-locale-environment
-@vindex locale-language-names
-@vindex locale-charset-language-names
-@cindex locales
- Some operating systems let you specify the character-set locale you
-are using by setting the locale environment variables @env{LC_ALL},
-@env{LC_CTYPE}, or @env{LANG}.@footnote{If more than one of these is
-set, the first one that is nonempty specifies your locale for this
-purpose.} During startup, Emacs looks up your character-set locale's
-name in the system locale alias table, matches its canonical name
-against entries in the value of the variables
-@code{locale-charset-language-names} and @code{locale-language-names},
-and selects the corresponding language environment if a match is found.
-(The former variable overrides the latter.) It also adjusts the display
-table and terminal coding system, the locale coding system, the
-preferred coding system as needed for the locale, and---last but not
-least---the way Emacs decodes non-@acronym{ASCII} characters sent by your keyboard.
-
- If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG}
-environment variables while running Emacs, you may want to invoke the
-@code{set-locale-environment} function afterwards to readjust the
-language environment from the new locale.
-
-@vindex locale-preferred-coding-systems
- The @code{set-locale-environment} function normally uses the preferred
-coding system established by the language environment to decode system
-messages. But if your locale matches an entry in the variable
-@code{locale-preferred-coding-systems}, Emacs uses the corresponding
-coding system instead. For example, if the locale @samp{ja_JP.PCK}
-matches @code{japanese-shift-jis} in
-@code{locale-preferred-coding-systems}, Emacs uses that encoding even
-though it might normally use @code{japanese-iso-8bit}.
-
- You can override the language environment chosen at startup with
-explicit use of the command @code{set-language-environment}, or with
-customization of @code{current-language-environment} in your init
-file.
-
-@kindex C-h L
-@findex describe-language-environment
- To display information about the effects of a certain language
-environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env}
-@key{RET}} (@code{describe-language-environment}). This tells you
-which languages this language environment is useful for, and lists the
-character sets, coding systems, and input methods that go with it. It
-also shows some sample text to illustrate scripts used in this
-language environment. If you give an empty input for @var{lang-env},
-this command describes the chosen language environment.
-
-@vindex set-language-environment-hook
- You can customize any language environment with the normal hook
-@code{set-language-environment-hook}. The command
-@code{set-language-environment} runs that hook after setting up the new
-language environment. The hook functions can test for a specific
-language environment by checking the variable
-@code{current-language-environment}. This hook is where you should
-put non-default settings for specific language environment, such as
-coding systems for keyboard input and terminal output, the default
-input method, etc.
-
-@vindex exit-language-environment-hook
- Before it starts to set up the new language environment,
-@code{set-language-environment} first runs the hook
-@code{exit-language-environment-hook}. This hook is useful for undoing
-customizations that were made with @code{set-language-environment-hook}.
-For instance, if you set up a special key binding in a specific language
-environment using @code{set-language-environment-hook}, you should set
-up @code{exit-language-environment-hook} to restore the normal binding
-for that key.
-
-@node Input Methods
-@section Input Methods
-
-@cindex input methods
- An @dfn{input method} is a kind of character conversion designed
-specifically for interactive input. In Emacs, typically each language
-has its own input method; sometimes several languages which use the same
-characters can share one input method. A few languages support several
-input methods.
-
- The simplest kind of input method works by mapping @acronym{ASCII} letters
-into another alphabet; this allows you to use one other alphabet
-instead of @acronym{ASCII}. The Greek and Russian input methods
-work this way.
-
- A more powerful technique is composition: converting sequences of
-characters into one letter. Many European input methods use composition
-to produce a single non-@acronym{ASCII} letter from a sequence that consists of a
-letter followed by accent characters (or vice versa). For example, some
-methods convert the sequence @kbd{a'} into a single accented letter.
-These input methods have no special commands of their own; all they do
-is compose sequences of printing characters.
-
- The input methods for syllabic scripts typically use mapping followed
-by composition. The input methods for Thai and Korean work this way.
-First, letters are mapped into symbols for particular sounds or tone
-marks; then, sequences of these which make up a whole syllable are
-mapped into one syllable sign.
-
- Chinese and Japanese require more complex methods. In Chinese input
-methods, first you enter the phonetic spelling of a Chinese word (in
-input method @code{chinese-py}, among others), or a sequence of
-portions of the character (input methods @code{chinese-4corner} and
-@code{chinese-sw}, and others). One input sequence typically
-corresponds to many possible Chinese characters. You select the one
-you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n},
-@kbd{C-p}, and digits, which have special meanings in this situation.
-
- The possible characters are conceptually arranged in several rows,
-with each row holding up to 10 alternatives. Normally, Emacs displays
-just one row at a time, in the echo area; @code{(@var{i}/@var{j})}
-appears at the beginning, to indicate that this is the @var{i}th row
-out of a total of @var{j} rows. Type @kbd{C-n} or @kbd{C-p} to
-display the next row or the previous row.
-
- Type @kbd{C-f} and @kbd{C-b} to move forward and backward among
-the alternatives in the current row. As you do this, Emacs highlights
-the current alternative with a special color; type @code{C-@key{SPC}}
-to select the current alternative and use it as input. The
-alternatives in the row are also numbered; the number appears before
-the alternative. Typing a digit @var{n} selects the @var{n}th
-alternative of the current row and uses it as input.
-
- @key{TAB} in these Chinese input methods displays a buffer showing
-all the possible characters at once; then clicking @kbd{Mouse-2} on
-one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b},
-@kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they
-do the highlighting in the buffer showing the possible characters,
-rather than in the echo area.
-
- In Japanese input methods, first you input a whole word using
-phonetic spelling; then, after the word is in the buffer, Emacs
-converts it into one or more characters using a large dictionary. One
-phonetic spelling corresponds to a number of different Japanese words;
-to select one of them, use @kbd{C-n} and @kbd{C-p} to cycle through
-the alternatives.
-
- Sometimes it is useful to cut off input method processing so that the
-characters you have just entered will not combine with subsequent
-characters. For example, in input method @code{latin-1-postfix}, the
-sequence @kbd{e '} combines to form an @samp{e} with an accent. What if
-you want to enter them as separate characters?
-
- One way is to type the accent twice; this is a special feature for
-entering the separate letter and accent. For example, @kbd{e ' '} gives
-you the two characters @samp{e'}. Another way is to type another letter
-after the @kbd{e}---something that won't combine with that---and
-immediately delete it. For example, you could type @kbd{e e @key{DEL}
-'} to get separate @samp{e} and @samp{'}.
-
- Another method, more general but not quite as easy to type, is to use
-@kbd{C-\ C-\} between two characters to stop them from combining. This
-is the command @kbd{C-\} (@code{toggle-input-method}) used twice.
-@ifnottex
-@xref{Select Input Method}.
-@end ifnottex
-
-@cindex incremental search, input method interference
- @kbd{C-\ C-\} is especially useful inside an incremental search,
-because it stops waiting for more characters to combine, and starts
-searching for what you have already entered.
-
- To find out how to input the character after point using the current
-input method, type @kbd{C-u C-x =}. @xref{Position Info}.
-
-@vindex input-method-verbose-flag
-@vindex input-method-highlight-flag
- The variables @code{input-method-highlight-flag} and
-@code{input-method-verbose-flag} control how input methods explain
-what is happening. If @code{input-method-highlight-flag} is
-non-@code{nil}, the partial sequence is highlighted in the buffer (for
-most input methods---some disable this feature). If
-@code{input-method-verbose-flag} is non-@code{nil}, the list of
-possible characters to type next is displayed in the echo area (but
-not when you are in the minibuffer).
-
-@node Select Input Method
-@section Selecting an Input Method
-
-@table @kbd
-@item C-\
-Enable or disable use of the selected input method.
-
-@item C-x @key{RET} C-\ @var{method} @key{RET}
-Select a new input method for the current buffer.
-
-@item C-h I @var{method} @key{RET}
-@itemx C-h C-\ @var{method} @key{RET}
-@findex describe-input-method
-@kindex C-h I
-@kindex C-h C-\
-Describe the input method @var{method} (@code{describe-input-method}).
-By default, it describes the current input method (if any). This
-description should give you the full details of how to use any
-particular input method.
-
-@item M-x list-input-methods
-Display a list of all the supported input methods.
-@end table
-
-@findex set-input-method
-@vindex current-input-method
-@kindex C-x RET C-\
- To choose an input method for the current buffer, use @kbd{C-x
-@key{RET} C-\} (@code{set-input-method}). This command reads the
-input method name from the minibuffer; the name normally starts with the
-language environment that it is meant to be used with. The variable
-@code{current-input-method} records which input method is selected.
-
-@findex toggle-input-method
-@kindex C-\
- Input methods use various sequences of @acronym{ASCII} characters to
-stand for non-@acronym{ASCII} characters. Sometimes it is useful to
-turn off the input method temporarily. To do this, type @kbd{C-\}
-(@code{toggle-input-method}). To reenable the input method, type
-@kbd{C-\} again.
-
- If you type @kbd{C-\} and you have not yet selected an input method,
-it prompts for you to specify one. This has the same effect as using
-@kbd{C-x @key{RET} C-\} to specify an input method.
-
- When invoked with a numeric argument, as in @kbd{C-u C-\},
-@code{toggle-input-method} always prompts you for an input method,
-suggesting the most recently selected one as the default.
-
-@vindex default-input-method
- Selecting a language environment specifies a default input method for
-use in various buffers. When you have a default input method, you can
-select it in the current buffer by typing @kbd{C-\}. The variable
-@code{default-input-method} specifies the default input method
-(@code{nil} means there is none).
-
- In some language environments, which support several different input
-methods, you might want to use an input method different from the
-default chosen by @code{set-language-environment}. You can instruct
-Emacs to select a different default input method for a certain
-language environment, if you wish, by using
-@code{set-language-environment-hook} (@pxref{Language Environments,
-set-language-environment-hook}). For example:
-
-@lisp
-(defun my-chinese-setup ()
- "Set up my private Chinese environment."
- (if (equal current-language-environment "Chinese-GB")
- (setq default-input-method "chinese-tonepy")))
-(add-hook 'set-language-environment-hook 'my-chinese-setup)
-@end lisp
-
-@noindent
-This sets the default input method to be @code{chinese-tonepy}
-whenever you choose a Chinese-GB language environment.
-
-@findex quail-set-keyboard-layout
- Some input methods for alphabetic scripts work by (in effect)
-remapping the keyboard to emulate various keyboard layouts commonly used
-for those scripts. How to do this remapping properly depends on your
-actual keyboard layout. To specify which layout your keyboard has, use
-the command @kbd{M-x quail-set-keyboard-layout}.
-
-@findex quail-show-key
- You can use the command @kbd{M-x quail-show-key} to show what key (or
-key sequence) to type in order to input the character following point,
-using the selected keyboard layout. The command @kbd{C-u C-x =} also
-shows that information in addition to the other information about the
-character.
-
-@findex list-input-methods
- To see a list of all the supported input methods, type @kbd{M-x
-list-input-methods}. The list gives information about each input
-method, including the string that stands for it in the mode line.
-
-@node Multibyte Conversion
-@section Unibyte and Multibyte Non-@acronym{ASCII} characters
-
- When multibyte characters are enabled, character codes 0240 (octal)
-through 0377 (octal) are not really legitimate in the buffer. The valid
-non-@acronym{ASCII} printing characters have codes that start from 0400.
-
- If you type a self-inserting character in the range 0240 through
-0377, or if you use @kbd{C-q} to insert one, Emacs assumes you
-intended to use one of the ISO Latin-@var{n} character sets, and
-converts it to the Emacs code representing that Latin-@var{n}
-character. You select @emph{which} ISO Latin character set to use
-through your choice of language environment
-@iftex
-(see above).
-@end iftex
-@ifnottex
-(@pxref{Language Environments}).
-@end ifnottex
-If you do not specify a choice, the default is Latin-1.
-
- If you insert a character in the range 0200 through 0237, which
-forms the @code{eight-bit-control} character set, it is inserted
-literally. You should normally avoid doing this since buffers
-containing such characters have to be written out in either the
-@code{emacs-mule} or @code{raw-text} coding system, which is usually
-not what you want.
-
-@node Coding Systems
-@section Coding Systems
-@cindex coding systems
-
- Users of various languages have established many more-or-less standard
-coding systems for representing them. Emacs does not use these coding
-systems internally; instead, it converts from various coding systems to
-its own system when reading data, and converts the internal coding
-system to other coding systems when writing data. Conversion is
-possible in reading or writing files, in sending or receiving from the
-terminal, and in exchanging data with subprocesses.
-
- Emacs assigns a name to each coding system. Most coding systems are
-used for one language, and the name of the coding system starts with the
-language name. Some coding systems are used for several languages;
-their names usually start with @samp{iso}. There are also special
-coding systems @code{no-conversion}, @code{raw-text} and
-@code{emacs-mule} which do not convert printing characters at all.
-
-@cindex international files from DOS/Windows systems
- A special class of coding systems, collectively known as
-@dfn{codepages}, is designed to support text encoded by MS-Windows and
-MS-DOS software. The names of these coding systems are
-@code{cp@var{nnnn}}, where @var{nnnn} is a 3- or 4-digit number of the
-codepage. You can use these encodings just like any other coding
-system; for example, to visit a file encoded in codepage 850, type
-@kbd{C-x @key{RET} c cp850 @key{RET} C-x C-f @var{filename}
-@key{RET}}@footnote{
-In the MS-DOS port of Emacs, you need to create a @code{cp@var{nnn}}
-coding system with @kbd{M-x codepage-setup}, before you can use it.
-@iftex
-@xref{MS-DOS and MULE,,,emacs-extra,Specialized Emacs Features}.
-@end iftex
-@ifnottex
-@xref{MS-DOS and MULE}.
-@end ifnottex
-}.
-
- In addition to converting various representations of non-@acronym{ASCII}
-characters, a coding system can perform end-of-line conversion. Emacs
-handles three different conventions for how to separate lines in a file:
-newline, carriage-return linefeed, and just carriage-return.
-
-@table @kbd
-@item C-h C @var{coding} @key{RET}
-Describe coding system @var{coding}.
-
-@item C-h C @key{RET}
-Describe the coding systems currently in use.
-
-@item M-x list-coding-systems
-Display a list of all the supported coding systems.
-@end table
-
-@kindex C-h C
-@findex describe-coding-system
- The command @kbd{C-h C} (@code{describe-coding-system}) displays
-information about particular coding systems, including the end-of-line
-conversion specified by those coding systems. You can specify a coding
-system name as the argument; alternatively, with an empty argument, it
-describes the coding systems currently selected for various purposes,
-both in the current buffer and as the defaults, and the priority list
-for recognizing coding systems (@pxref{Recognize Coding}).
-
-@findex list-coding-systems
- To display a list of all the supported coding systems, type @kbd{M-x
-list-coding-systems}. The list gives information about each coding
-system, including the letter that stands for it in the mode line
-(@pxref{Mode Line}).
-
-@cindex end-of-line conversion
-@cindex line endings
-@cindex MS-DOS end-of-line conversion
-@cindex Macintosh end-of-line conversion
- Each of the coding systems that appear in this list---except for
-@code{no-conversion}, which means no conversion of any kind---specifies
-how and whether to convert printing characters, but leaves the choice of
-end-of-line conversion to be decided based on the contents of each file.
-For example, if the file appears to use the sequence carriage-return
-linefeed to separate lines, DOS end-of-line conversion will be used.
-
- Each of the listed coding systems has three variants which specify
-exactly what to do for end-of-line conversion:
-
-@table @code
-@item @dots{}-unix
-Don't do any end-of-line conversion; assume the file uses
-newline to separate lines. (This is the convention normally used
-on Unix and GNU systems.)
-
-@item @dots{}-dos
-Assume the file uses carriage-return linefeed to separate lines, and do
-the appropriate conversion. (This is the convention normally used on
-Microsoft systems.@footnote{It is also specified for MIME @samp{text/*}
-bodies and in other network transport contexts. It is different
-from the SGML reference syntax record-start/record-end format which
-Emacs doesn't support directly.})
-
-@item @dots{}-mac
-Assume the file uses carriage-return to separate lines, and do the
-appropriate conversion. (This is the convention normally used on the
-Macintosh system.)
-@end table
-
- These variant coding systems are omitted from the
-@code{list-coding-systems} display for brevity, since they are entirely
-predictable. For example, the coding system @code{iso-latin-1} has
-variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and
-@code{iso-latin-1-mac}.
-
-@cindex @code{undecided}, coding system
- The coding systems @code{unix}, @code{dos}, and @code{mac} are
-aliases for @code{undecided-unix}, @code{undecided-dos}, and
-@code{undecided-mac}, respectively. These coding systems specify only
-the end-of-line conversion, and leave the character code conversion to
-be deduced from the text itself.
-
- The coding system @code{raw-text} is good for a file which is mainly
-@acronym{ASCII} text, but may contain byte values above 127 which are
-not meant to encode non-@acronym{ASCII} characters. With
-@code{raw-text}, Emacs copies those byte values unchanged, and sets
-@code{enable-multibyte-characters} to @code{nil} in the current buffer
-so that they will be interpreted properly. @code{raw-text} handles
-end-of-line conversion in the usual way, based on the data
-encountered, and has the usual three variants to specify the kind of
-end-of-line conversion to use.
-
- In contrast, the coding system @code{no-conversion} specifies no
-character code conversion at all---none for non-@acronym{ASCII} byte values and
-none for end of line. This is useful for reading or writing binary
-files, tar files, and other files that must be examined verbatim. It,
-too, sets @code{enable-multibyte-characters} to @code{nil}.
-
- The easiest way to edit a file with no conversion of any kind is with
-the @kbd{M-x find-file-literally} command. This uses
-@code{no-conversion}, and also suppresses other Emacs features that
-might convert the file contents before you see them. @xref{Visiting}.
-
- The coding system @code{emacs-mule} means that the file contains
-non-@acronym{ASCII} characters stored with the internal Emacs encoding. It
-handles end-of-line conversion based on the data encountered, and has
-the usual three variants to specify the kind of end-of-line conversion.
-
-@findex unify-8859-on-decoding-mode
-@anchor{Character Translation}
- The @dfn{character translation} feature can modify the effect of
-various coding systems, by changing the internal Emacs codes that
-decoding produces. For instance, the command
-@code{unify-8859-on-decoding-mode} enables a mode that ``unifies'' the
-Latin alphabets when decoding text. This works by converting all
-non-@acronym{ASCII} Latin-@var{n} characters to either Latin-1 or
-Unicode characters. This way it is easier to use various
-Latin-@var{n} alphabets together. (In a future Emacs version we hope
-to move towards full Unicode support and complete unification of
-character sets.)
-
-@vindex enable-character-translation
- If you set the variable @code{enable-character-translation} to
-@code{nil}, that disables all character translation (including
-@code{unify-8859-on-decoding-mode}).
-
-@node Recognize Coding
-@section Recognizing Coding Systems
-
- Emacs tries to recognize which coding system to use for a given text
-as an integral part of reading that text. (This applies to files
-being read, output from subprocesses, text from X selections, etc.)
-Emacs can select the right coding system automatically most of the
-time---once you have specified your preferences.
-
- Some coding systems can be recognized or distinguished by which byte
-sequences appear in the data. However, there are coding systems that
-cannot be distinguished, not even potentially. For example, there is no
-way to distinguish between Latin-1 and Latin-2; they use the same byte
-values with different meanings.
-
- Emacs handles this situation by means of a priority list of coding
-systems. Whenever Emacs reads a file, if you do not specify the coding
-system to use, Emacs checks the data against each coding system,
-starting with the first in priority and working down the list, until it
-finds a coding system that fits the data. Then it converts the file
-contents assuming that they are represented in this coding system.
-
- The priority list of coding systems depends on the selected language
-environment (@pxref{Language Environments}). For example, if you use
-French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use
-Czech, you probably want Latin-2 to be preferred. This is one of the
-reasons to specify a language environment.
-
-@findex prefer-coding-system
- However, you can alter the coding system priority list in detail
-with the command @kbd{M-x prefer-coding-system}. This command reads
-the name of a coding system from the minibuffer, and adds it to the
-front of the priority list, so that it is preferred to all others. If
-you use this command several times, each use adds one element to the
-front of the priority list.
-
- If you use a coding system that specifies the end-of-line conversion
-type, such as @code{iso-8859-1-dos}, what this means is that Emacs
-should attempt to recognize @code{iso-8859-1} with priority, and should
-use DOS end-of-line conversion when it does recognize @code{iso-8859-1}.
-
-@vindex file-coding-system-alist
- Sometimes a file name indicates which coding system to use for the
-file. The variable @code{file-coding-system-alist} specifies this
-correspondence. There is a special function
-@code{modify-coding-system-alist} for adding elements to this list. For
-example, to read and write all @samp{.txt} files using the coding system
-@code{chinese-iso-8bit}, you can execute this Lisp expression:
-
-@smallexample
-(modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit)
-@end smallexample
-
-@noindent
-The first argument should be @code{file}, the second argument should be
-a regular expression that determines which files this applies to, and
-the third argument says which coding system to use for these files.
-
-@vindex inhibit-eol-conversion
-@cindex DOS-style end-of-line display
- Emacs recognizes which kind of end-of-line conversion to use based on
-the contents of the file: if it sees only carriage-returns, or only
-carriage-return linefeed sequences, then it chooses the end-of-line
-conversion accordingly. You can inhibit the automatic use of
-end-of-line conversion by setting the variable @code{inhibit-eol-conversion}
-to non-@code{nil}. If you do that, DOS-style files will be displayed
-with the @samp{^M} characters visible in the buffer; some people
-prefer this to the more subtle @samp{(DOS)} end-of-line type
-indication near the left edge of the mode line (@pxref{Mode Line,
-eol-mnemonic}).
-
-@vindex inhibit-iso-escape-detection
-@cindex escape sequences in files
- By default, the automatic detection of coding system is sensitive to
-escape sequences. If Emacs sees a sequence of characters that begin
-with an escape character, and the sequence is valid as an ISO-2022
-code, that tells Emacs to use one of the ISO-2022 encodings to decode
-the file.
-
- However, there may be cases that you want to read escape sequences
-in a file as is. In such a case, you can set the variable
-@code{inhibit-iso-escape-detection} to non-@code{nil}. Then the code
-detection ignores any escape sequences, and never uses an ISO-2022
-encoding. The result is that all escape sequences become visible in
-the buffer.
-
- The default value of @code{inhibit-iso-escape-detection} is
-@code{nil}. We recommend that you not change it permanently, only for
-one specific operation. That's because many Emacs Lisp source files
-in the Emacs distribution contain non-@acronym{ASCII} characters encoded in the
-coding system @code{iso-2022-7bit}, and they won't be
-decoded correctly when you visit those files if you suppress the
-escape sequence detection.
-
-@vindex auto-coding-alist
-@vindex auto-coding-regexp-alist
-@vindex auto-coding-functions
- The variables @code{auto-coding-alist},
-@code{auto-coding-regexp-alist} and @code{auto-coding-functions} are
-the strongest way to specify the coding system for certain patterns of
-file names, or for files containing certain patterns; these variables
-even override @samp{-*-coding:-*-} tags in the file itself. Emacs
-uses @code{auto-coding-alist} for tar and archive files, to prevent it
-from being confused by a @samp{-*-coding:-*-} tag in a member of the
-archive and thinking it applies to the archive file as a whole.
-Likewise, Emacs uses @code{auto-coding-regexp-alist} to ensure that
-RMAIL files, whose names in general don't match any particular
-pattern, are decoded correctly. One of the builtin
-@code{auto-coding-functions} detects the encoding for XML files.
-
-@vindex rmail-decode-mime-charset
- When you get new mail in Rmail, each message is translated
-automatically from the coding system it is written in, as if it were a
-separate file. This uses the priority list of coding systems that you
-have specified. If a MIME message specifies a character set, Rmail
-obeys that specification, unless @code{rmail-decode-mime-charset} is
-@code{nil}.
-
-@vindex rmail-file-coding-system
- For reading and saving Rmail files themselves, Emacs uses the coding
-system specified by the variable @code{rmail-file-coding-system}. The
-default value is @code{nil}, which means that Rmail files are not
-translated (they are read and written in the Emacs internal character
-code).
-
-@node Specify Coding
-@section Specifying a File's Coding System
-
- If Emacs recognizes the encoding of a file incorrectly, you can
-reread the file using the correct coding system by typing @kbd{C-x
-@key{RET} r @var{coding-system} @key{RET}}. To see what coding system
-Emacs actually used to decode the file, look at the coding system
-mnemonic letter near the left edge of the mode line (@pxref{Mode
-Line}), or type @kbd{C-h C @key{RET}}.
-
-@vindex coding
- You can specify the coding system for a particular file in the file
-itself, using the @w{@samp{-*-@dots{}-*-}} construct at the beginning,
-or a local variables list at the end (@pxref{File Variables}). You do
-this by defining a value for the ``variable'' named @code{coding}.
-Emacs does not really have a variable @code{coding}; instead of
-setting a variable, this uses the specified coding system for the
-file. For example, @samp{-*-mode: C; coding: latin-1;-*-} specifies
-use of the Latin-1 coding system, as well as C mode. When you specify
-the coding explicitly in the file, that overrides
-@code{file-coding-system-alist}.
-
- If you add the character @samp{!} at the end of the coding system
-name in @code{coding}, it disables any character translation
-(@pxref{Character Translation}) while decoding the file. This is
-useful when you need to make sure that the character codes in the
-Emacs buffer will not vary due to changes in user settings; for
-instance, for the sake of strings in Emacs Lisp source files.
-
-@node Output Coding
-@section Choosing Coding Systems for Output
-
-@vindex buffer-file-coding-system
- Once Emacs has chosen a coding system for a buffer, it stores that
-coding system in @code{buffer-file-coding-system}. That makes it the
-default for operations that write from this buffer into a file, such
-as @code{save-buffer} and @code{write-region}. You can specify a
-different coding system for further file output from the buffer using
-@code{set-buffer-file-coding-system} (@pxref{Text Coding}).
-
- You can insert any character Emacs supports into any Emacs buffer,
-but most coding systems can only handle a subset of these characters.
-Therefore, you can insert characters that cannot be encoded with the
-coding system that will be used to save the buffer. For example, you
-could start with an @acronym{ASCII} file and insert a few Latin-1
-characters into it, or you could edit a text file in Polish encoded in
-@code{iso-8859-2} and add some Russian words to it. When you save
-that buffer, Emacs cannot use the current value of
-@code{buffer-file-coding-system}, because the characters you added
-cannot be encoded by that coding system.
-
- When that happens, Emacs tries the most-preferred coding system (set
-by @kbd{M-x prefer-coding-system} or @kbd{M-x
-set-language-environment}), and if that coding system can safely
-encode all of the characters in the buffer, Emacs uses it, and stores
-its value in @code{buffer-file-coding-system}. Otherwise, Emacs
-displays a list of coding systems suitable for encoding the buffer's
-contents, and asks you to choose one of those coding systems.
-
- If you insert the unsuitable characters in a mail message, Emacs
-behaves a bit differently. It additionally checks whether the
-most-preferred coding system is recommended for use in MIME messages;
-if not, Emacs tells you that the most-preferred coding system is not
-recommended and prompts you for another coding system. This is so you
-won't inadvertently send a message encoded in a way that your
-recipient's mail software will have difficulty decoding. (You can
-still use an unsuitable coding system if you type its name in response
-to the question.)
-
-@vindex sendmail-coding-system
- When you send a message with Mail mode (@pxref{Sending Mail}), Emacs has
-four different ways to determine the coding system to use for encoding
-the message text. It tries the buffer's own value of
-@code{buffer-file-coding-system}, if that is non-@code{nil}. Otherwise,
-it uses the value of @code{sendmail-coding-system}, if that is
-non-@code{nil}. The third way is to use the default coding system for
-new files, which is controlled by your choice of language environment,
-if that is non-@code{nil}. If all of these three values are @code{nil},
-Emacs encodes outgoing mail using the Latin-1 coding system.
-
-@node Text Coding
-@section Specifying a Coding System for File Text
-
- In cases where Emacs does not automatically choose the right coding
-system for a file's contents, you can use these commands to specify
-one:
-
-@table @kbd
-@item C-x @key{RET} f @var{coding} @key{RET}
-Use coding system @var{coding} for saving or revisiting the visited
-file in the current buffer.
-
-@item C-x @key{RET} c @var{coding} @key{RET}
-Specify coding system @var{coding} for the immediately following
-command.
-
-@item C-x @key{RET} r @var{coding} @key{RET}
-Revisit the current file using the coding system @var{coding}.
-
-@item M-x recode-region @key{RET} @var{right} @key{RET} @var{wrong} @key{RET}
-Convert a region that was decoded using coding system @var{wrong},
-decoding it using coding system @var{right} instead.
-@end table
-
-@kindex C-x RET f
-@findex set-buffer-file-coding-system
- The command @kbd{C-x @key{RET} f}
-(@code{set-buffer-file-coding-system}) sets the file coding system for
-the current buffer---in other words, it says which coding system to
-use when saving or reverting the visited file. You specify which
-coding system using the minibuffer. If you specify a coding system
-that cannot handle all of the characters in the buffer, Emacs warns
-you about the troublesome characters when you actually save the
-buffer.
-
-@cindex specify end-of-line conversion
- You can also use this command to specify the end-of-line conversion
-(@pxref{Coding Systems, end-of-line conversion}) for encoding the
-current buffer. For example, @kbd{C-x @key{RET} f dos @key{RET}} will
-cause Emacs to save the current buffer's text with DOS-style CRLF line
-endings.
-
-@kindex C-x RET c
-@findex universal-coding-system-argument
- Another way to specify the coding system for a file is when you visit
-the file. First use the command @kbd{C-x @key{RET} c}
-(@code{universal-coding-system-argument}); this command uses the
-minibuffer to read a coding system name. After you exit the minibuffer,
-the specified coding system is used for @emph{the immediately following
-command}.
-
- So if the immediately following command is @kbd{C-x C-f}, for example,
-it reads the file using that coding system (and records the coding
-system for when you later save the file). Or if the immediately following
-command is @kbd{C-x C-w}, it writes the file using that coding system.
-When you specify the coding system for saving in this way, instead
-of with @kbd{C-x @key{RET} f}, there is no warning if the buffer
-contains characters that the coding system cannot handle.
-
- Other file commands affected by a specified coding system include
-@kbd{C-x i} and @kbd{C-x C-v}, as well as the other-window variants
-of @kbd{C-x C-f}. @kbd{C-x @key{RET} c} also affects commands that
-start subprocesses, including @kbd{M-x shell} (@pxref{Shell}). If the
-immediately following command does not use the coding system, then
-@kbd{C-x @key{RET} c} ultimately has no effect.
-
- An easy way to visit a file with no conversion is with the @kbd{M-x
-find-file-literally} command. @xref{Visiting}.
-
-@vindex default-buffer-file-coding-system
- The variable @code{default-buffer-file-coding-system} specifies the
-choice of coding system to use when you create a new file. It applies
-when you find a new file, and when you create a buffer and then save it
-in a file. Selecting a language environment typically sets this
-variable to a good choice of default coding system for that language
-environment.
-
-@kindex C-x RET r
-@findex revert-buffer-with-coding-system
- If you visit a file with a wrong coding system, you can correct this
-with @kbd{C-x @key{RET} r} (@code{revert-buffer-with-coding-system}).
-This visits the current file again, using a coding system you specify.
-
-@findex recode-region
- If a piece of text has already been inserted into a buffer using the
-wrong coding system, you can redo the decoding of it using @kbd{M-x
-recode-region}. This prompts you for the proper coding system, then
-for the wrong coding system that was actually used, and does the
-conversion. It first encodes the region using the wrong coding system,
-then decodes it again using the proper coding system.
-
-@node Communication Coding
-@section Coding Systems for Interprocess Communication
-
- This section explains how to specify coding systems for use
-in communication with other processes.
-
-@table @kbd
-@item C-x @key{RET} x @var{coding} @key{RET}
-Use coding system @var{coding} for transferring selections to and from
-other window-based applications.
-
-@item C-x @key{RET} X @var{coding} @key{RET}
-Use coding system @var{coding} for transferring @emph{one}
-selection---the next one---to or from another window-based application.
-
-@item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET}
-Use coding systems @var{input-coding} and @var{output-coding} for
-subprocess input and output in the current buffer.
-
-@item C-x @key{RET} c @var{coding} @key{RET}
-Specify coding system @var{coding} for the immediately following
-command.
-@end table
-
-@kindex C-x RET x
-@kindex C-x RET X
-@findex set-selection-coding-system
-@findex set-next-selection-coding-system
- The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system})
-specifies the coding system for sending selected text to other windowing
-applications, and for receiving the text of selections made in other
-applications. This command applies to all subsequent selections, until
-you override it by using the command again. The command @kbd{C-x
-@key{RET} X} (@code{set-next-selection-coding-system}) specifies the
-coding system for the next selection made in Emacs or read by Emacs.
-
-@kindex C-x RET p
-@findex set-buffer-process-coding-system
- The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system})
-specifies the coding system for input and output to a subprocess. This
-command applies to the current buffer; normally, each subprocess has its
-own buffer, and thus you can use this command to specify translation to
-and from a particular subprocess by giving the command in the
-corresponding buffer.
-
- You can also use @kbd{C-x @key{RET} c} just before the command that
-runs or starts a subprocess, to specify the coding system to use for
-communication with that subprocess.
-
- The default for translation of process input and output depends on the
-current language environment.
-
-@vindex locale-coding-system
-@cindex decoding non-@acronym{ASCII} keyboard input on X
- The variable @code{locale-coding-system} specifies a coding system
-to use when encoding and decoding system strings such as system error
-messages and @code{format-time-string} formats and time stamps. That
-coding system is also used for decoding non-@acronym{ASCII} keyboard input on X
-Window systems. You should choose a coding system that is compatible
-with the underlying system's text representation, which is normally
-specified by one of the environment variables @env{LC_ALL},
-@env{LC_CTYPE}, and @env{LANG}. (The first one, in the order
-specified above, whose value is nonempty is the one that determines
-the text representation.)
-
-@node File Name Coding
-@section Coding Systems for File Names
-
-@table @kbd
-@item C-x @key{RET} F @var{coding} @key{RET}
-Use coding system @var{coding} for encoding and decoding file
-@emph{names}.
-@end table
-
-@vindex file-name-coding-system
-@cindex file names with non-@acronym{ASCII} characters
- The variable @code{file-name-coding-system} specifies a coding
-system to use for encoding file names. It has no effect on reading
-and writing the @emph{contents} of files.
-
-@findex set-file-name-coding-system
-@kindex C-x @key{RET} F
- If you set the variable to a coding system name (as a Lisp symbol or
-a string), Emacs encodes file names using that coding system for all
-file operations. This makes it possible to use non-@acronym{ASCII}
-characters in file names---or, at least, those non-@acronym{ASCII}
-characters which the specified coding system can encode. Use @kbd{C-x
-@key{RET} F} (@code{set-file-name-coding-system}) to specify this
-interactively.
-
- If @code{file-name-coding-system} is @code{nil}, Emacs uses a
-default coding system determined by the selected language environment.
-In the default language environment, any non-@acronym{ASCII}
-characters in file names are not encoded specially; they appear in the
-file system using the internal Emacs representation.
-
- @strong{Warning:} if you change @code{file-name-coding-system} (or the
-language environment) in the middle of an Emacs session, problems can
-result if you have already visited files whose names were encoded using
-the earlier coding system and cannot be encoded (or are encoded
-differently) under the new coding system. If you try to save one of
-these buffers under the visited file name, saving may use the wrong file
-name, or it may get an error. If such a problem happens, use @kbd{C-x
-C-w} to specify a new file name for that buffer.
-
-@findex recode-file-name
- If a mistake occurs when encoding a file name, use the command
-@kbd{M-x recode-file-name} to change the file name's coding
-system. This prompts for an existing file name, its old coding
-system, and the coding system to which you wish to convert.
-
-@node Terminal Coding
-@section Coding Systems for Terminal I/O
-
-@table @kbd
-@item C-x @key{RET} k @var{coding} @key{RET}
-Use coding system @var{coding} for keyboard input.
-
-@item C-x @key{RET} t @var{coding} @key{RET}
-Use coding system @var{coding} for terminal output.
-@end table
-
-@kindex C-x RET t
-@findex set-terminal-coding-system
- The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system})
-specifies the coding system for terminal output. If you specify a
-character code for terminal output, all characters output to the
-terminal are translated into that coding system.
-
- This feature is useful for certain character-only terminals built to
-support specific languages or character sets---for example, European
-terminals that support one of the ISO Latin character sets. You need to
-specify the terminal coding system when using multibyte text, so that
-Emacs knows which characters the terminal can actually handle.
-
- By default, output to the terminal is not translated at all, unless
-Emacs can deduce the proper coding system from your terminal type or
-your locale specification (@pxref{Language Environments}).
-
-@kindex C-x RET k
-@findex set-keyboard-coding-system
-@vindex keyboard-coding-system
- The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system})
-or the variable @code{keyboard-coding-system} specifies the coding
-system for keyboard input. Character-code translation of keyboard
-input is useful for terminals with keys that send non-@acronym{ASCII}
-graphic characters---for example, some terminals designed for ISO
-Latin-1 or subsets of it.
-
- By default, keyboard input is translated based on your system locale
-setting. If your terminal does not really support the encoding
-implied by your locale (for example, if you find it inserts a
-non-@acronym{ASCII} character if you type @kbd{M-i}), you will need to set
-@code{keyboard-coding-system} to @code{nil} to turn off encoding.
-You can do this by putting
-
-@lisp
-(set-keyboard-coding-system nil)
-@end lisp
-
-@noindent
-in your @file{~/.emacs} file.
-
- There is a similarity between using a coding system translation for
-keyboard input, and using an input method: both define sequences of
-keyboard input that translate into single characters. However, input
-methods are designed to be convenient for interactive use by humans, and
-the sequences that are translated are typically sequences of @acronym{ASCII}
-printing characters. Coding systems typically translate sequences of
-non-graphic characters.
-
-@node Fontsets
-@section Fontsets
-@cindex fontsets
-
- A font typically defines shapes for a single alphabet or script.
-Therefore, displaying the entire range of scripts that Emacs supports
-requires a collection of many fonts. In Emacs, such a collection is
-called a @dfn{fontset}. A fontset is defined by a list of fonts, each
-assigned to handle a range of character codes.
-
- Each fontset has a name, like a font. However, while fonts are
-stored in the system and the available font names are defined by the
-system, fontsets are defined within Emacs itself. Once you have
-defined a fontset, you can use it within Emacs by specifying its name,
-anywhere that you could use a single font. Of course, Emacs fontsets
-can use only the fonts that the system supports; if certain characters
-appear on the screen as hollow boxes, this means that the fontset in
-use for them has no font for those characters.@footnote{The Emacs
-installation instructions have information on additional font
-support.}
-
- Emacs creates two fontsets automatically: the @dfn{standard fontset}
-and the @dfn{startup fontset}. The standard fontset is most likely to
-have fonts for a wide variety of non-@acronym{ASCII} characters;
-however, this is not the default for Emacs to use. (By default, Emacs
-tries to find a font that has bold and italic variants.) You can
-specify use of the standard fontset with the @samp{-fn} option. For
-example,
-
-@example
-emacs -fn fontset-standard
-@end example
-
-@noindent
-You can also specify a fontset with the @samp{Font} resource (@pxref{X
-Resources}).
-
- A fontset does not necessarily specify a font for every character
-code. If a fontset specifies no font for a certain character, or if it
-specifies a font that does not exist on your system, then it cannot
-display that character properly. It will display that character as an
-empty box instead.
-
-@node Defining Fontsets
-@section Defining fontsets
-
-@vindex standard-fontset-spec
-@cindex standard fontset
- Emacs creates a standard fontset automatically according to the value
-of @code{standard-fontset-spec}. This fontset's name is
-
-@example
--*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard
-@end example
-
-@noindent
-or just @samp{fontset-standard} for short.
-
- Bold, italic, and bold-italic variants of the standard fontset are
-created automatically. Their names have @samp{bold} instead of
-@samp{medium}, or @samp{i} instead of @samp{r}, or both.
-
-@cindex startup fontset
- If you specify a default @acronym{ASCII} font with the @samp{Font} resource or
-the @samp{-fn} argument, Emacs generates a fontset from it
-automatically. This is the @dfn{startup fontset} and its name is
-@code{fontset-startup}. It does this by replacing the @var{foundry},
-@var{family}, @var{add_style}, and @var{average_width} fields of the
-font name with @samp{*}, replacing @var{charset_registry} field with
-@samp{fontset}, and replacing @var{charset_encoding} field with
-@samp{startup}, then using the resulting string to specify a fontset.
-
- For instance, if you start Emacs this way,
-
-@example
-emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"
-@end example
-
-@noindent
-Emacs generates the following fontset and uses it for the initial X
-window frame:
-
-@example
--*-*-medium-r-normal-*-14-140-*-*-*-*-fontset-startup
-@end example
-
- With the X resource @samp{Emacs.Font}, you can specify a fontset name
-just like an actual font name. But be careful not to specify a fontset
-name in a wildcard resource like @samp{Emacs*Font}---that wildcard
-specification matches various other resources, such as for menus, and
-menus cannot handle fontsets.
-
- You can specify additional fontsets using X resources named
-@samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0.
-The resource value should have this form:
-
-@smallexample
-@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}}
-@end smallexample
-
-@noindent
-@var{fontpattern} should have the form of a standard X font name, except
-for the last two fields. They should have the form
-@samp{fontset-@var{alias}}.
-
- The fontset has two names, one long and one short. The long name is
-@var{fontpattern}. The short name is @samp{fontset-@var{alias}}. You
-can refer to the fontset by either name.
-
- The construct @samp{@var{charset}:@var{font}} specifies which font to
-use (in this fontset) for one particular character set. Here,
-@var{charset} is the name of a character set, and @var{font} is the
-font to use for that character set. You can use this construct any
-number of times in defining one fontset.
-
- For the other character sets, Emacs chooses a font based on
-@var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values
-that describe the character set. For the @acronym{ASCII} character font,
-@samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}.
-
- In addition, when several consecutive fields are wildcards, Emacs
-collapses them into a single wildcard. This is to prevent use of
-auto-scaled fonts. Fonts made by scaling larger fonts are not usable
-for editing, and scaling a smaller font is not useful because it is
-better to use the smaller font in its own size, which is what Emacs
-does.
-
- Thus if @var{fontpattern} is this,
-
-@example
--*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
-@end example
-
-@noindent
-the font specification for @acronym{ASCII} characters would be this:
-
-@example
--*-fixed-medium-r-normal-*-24-*-ISO8859-1
-@end example
-
-@noindent
-and the font specification for Chinese GB2312 characters would be this:
-
-@example
--*-fixed-medium-r-normal-*-24-*-gb2312*-*
-@end example
-
- You may not have any Chinese font matching the above font
-specification. Most X distributions include only Chinese fonts that
-have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In
-such a case, @samp{Fontset-@var{n}} can be specified as below:
-
-@smallexample
-Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
- chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
-@end smallexample
-
-@noindent
-Then, the font specifications for all but Chinese GB2312 characters have
-@samp{fixed} in the @var{family} field, and the font specification for
-Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
-field.
-
-@findex create-fontset-from-fontset-spec
- The function that processes the fontset resource value to create the
-fontset is called @code{create-fontset-from-fontset-spec}. You can also
-call this function explicitly to create a fontset.
-
- @xref{Font X}, for more information about font naming in X.
-
-@node Undisplayable Characters
-@section Undisplayable Characters
-
- There may be a some non-@acronym{ASCII} characters that your terminal cannot
-display. Most text-only terminals support just a single character
-set (use the variable @code{default-terminal-coding-system}
-(@pxref{Terminal Coding}) to tell Emacs which one); characters which
-can't be encoded in that coding system are displayed as @samp{?} by
-default.
-
- Graphical displays can display a broader range of characters, but
-you may not have fonts installed for all of them; characters that have
-no font appear as a hollow box.
-
- If you use Latin-1 characters but your terminal can't display
-Latin-1, you can arrange to display mnemonic @acronym{ASCII} sequences
-instead, e.g.@: @samp{"o} for o-umlaut. Load the library
-@file{iso-ascii} to do this.
-
-@vindex latin1-display
- If your terminal can display Latin-1, you can display characters
-from other European character sets using a mixture of equivalent
-Latin-1 characters and @acronym{ASCII} mnemonics. Customize the variable
-@code{latin1-display} to enable this. The mnemonic @acronym{ASCII}
-sequences mostly correspond to those of the prefix input methods.
-
-@node Unibyte Mode
-@section Unibyte Editing Mode
-
-@cindex European character sets
-@cindex accented characters
-@cindex ISO Latin character sets
-@cindex Unibyte operation
- The ISO 8859 Latin-@var{n} character sets define character codes in
-the range 0240 to 0377 octal (160 to 255 decimal) to handle the
-accented letters and punctuation needed by various European languages
-(and some non-European ones). If you disable multibyte characters,
-Emacs can still handle @emph{one} of these character codes at a time.
-To specify @emph{which} of these codes to use, invoke @kbd{M-x
-set-language-environment} and specify a suitable language environment
-such as @samp{Latin-@var{n}}.
-
- For more information about unibyte operation, see @ref{Enabling
-Multibyte}. Note particularly that you probably want to ensure that
-your initialization files are read as unibyte if they contain
-non-@acronym{ASCII} characters.
-
-@vindex unibyte-display-via-language-environment
- Emacs can also display those characters, provided the terminal or font
-in use supports them. This works automatically. Alternatively, on a
-graphical display, Emacs can also display single-byte characters
-through fontsets, in effect by displaying the equivalent multibyte
-characters according to the current language environment. To request
-this, set the variable @code{unibyte-display-via-language-environment}
-to a non-@code{nil} value.
-
-@cindex @code{iso-ascii} library
- If your terminal does not support display of the Latin-1 character
-set, Emacs can display these characters as @acronym{ASCII} sequences which at
-least give you a clear idea of what the characters are. To do this,
-load the library @code{iso-ascii}. Similar libraries for other
-Latin-@var{n} character sets could be implemented, but we don't have
-them yet.
-
-@findex standard-display-8bit
-@cindex 8-bit display
- Normally non-ISO-8859 characters (decimal codes between 128 and 159
-inclusive) are displayed as octal escapes. You can change this for
-non-standard ``extended'' versions of ISO-8859 character sets by using the
-function @code{standard-display-8bit} in the @code{disp-table} library.
-
- There are two ways to input single-byte non-@acronym{ASCII}
-characters:
-
-@itemize @bullet
-@cindex 8-bit input
-@item
-You can use an input method for the selected language environment.
-@xref{Input Methods}. When you use an input method in a unibyte buffer,
-the non-@acronym{ASCII} character you specify with it is converted to unibyte.
-
-@item
-If your keyboard can generate character codes 128 (decimal) and up,
-representing non-@acronym{ASCII} characters, you can type those character codes
-directly.
-
-On a graphical display, you should not need to do anything special to use
-these keys; they should simply work. On a text-only terminal, you
-should use the command @code{M-x set-keyboard-coding-system} or the
-variable @code{keyboard-coding-system} to specify which coding system
-your keyboard uses (@pxref{Terminal Coding}). Enabling this feature
-will probably require you to use @kbd{ESC} to type Meta characters;
-however, on a console terminal or in @code{xterm}, you can arrange for
-Meta to be converted to @kbd{ESC} and still be able type 8-bit
-characters present directly on the keyboard or using @kbd{Compose} or
-@kbd{AltGr} keys. @xref{User Input}.
-
-@kindex C-x 8
-@cindex @code{iso-transl} library
-@cindex compose character
-@cindex dead character
-@item
-For Latin-1 only, you can use the key @kbd{C-x 8} as a ``compose
-character'' prefix for entry of non-@acronym{ASCII} Latin-1 printing
-characters. @kbd{C-x 8} is good for insertion (in the minibuffer as
-well as other buffers), for searching, and in any other context where
-a key sequence is allowed.
-
-@kbd{C-x 8} works by loading the @code{iso-transl} library. Once that
-library is loaded, the @key{ALT} modifier key, if the keyboard has
-one, serves the same purpose as @kbd{C-x 8}: use @key{ALT} together
-with an accent character to modify the following letter. In addition,
-if the keyboard has keys for the Latin-1 ``dead accent characters,''
-they too are defined to compose with the following character, once
-@code{iso-transl} is loaded.
-
-Use @kbd{C-x 8 C-h} to list all the available @kbd{C-x 8} translations.
-@end itemize
-
-@node Charsets
-@section Charsets
-@cindex charsets
-
- Emacs groups all supported characters into disjoint @dfn{charsets}.
-Each character code belongs to one and only one charset. For
-historical reasons, Emacs typically divides an 8-bit character code
-for an extended version of @acronym{ASCII} into two charsets:
-@acronym{ASCII}, which covers the codes 0 through 127, plus another
-charset which covers the ``right-hand part'' (the codes 128 and up).
-For instance, the characters of Latin-1 include the Emacs charset
-@code{ascii} plus the Emacs charset @code{latin-iso8859-1}.
-
- Emacs characters belonging to different charsets may look the same,
-but they are still different characters. For example, the letter
-@samp{o} with acute accent in charset @code{latin-iso8859-1}, used for
-Latin-1, is different from the letter @samp{o} with acute accent in
-charset @code{latin-iso8859-2}, used for Latin-2.
-
-@findex list-charset-chars
-@cindex characters in a certain charset
-@findex describe-character-set
- There are two commands for obtaining information about Emacs
-charsets. The command @kbd{M-x list-charset-chars} prompts for a name
-of a character set, and displays all the characters in that character
-set. The command @kbd{M-x describe-character-set} prompts for a
-charset name and displays information about that charset, including
-its internal representation within Emacs.
-
- To find out which charset a character in the buffer belongs to,
-put point before it and type @kbd{C-u C-x =}.
-
-@ignore
- arch-tag: 310ba60d-31ef-4ce7-91f1-f282dd57b6b3
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@c
-@c This file is included either in emacs-xtra.texi (when producing the
-@c printed version) or in the main Emacs manual (for the on-line version).
-@node Picture Mode
-@chapter Editing Pictures
-@cindex pictures
-@cindex making pictures out of text characters
-@findex edit-picture
-
- To edit a picture made out of text characters (for example, a picture
-of the division of a register into fields, as a comment in a program),
-use the command @kbd{M-x edit-picture} to enter Picture mode.
-
- In Picture mode, editing is based on the @dfn{quarter-plane} model of
-text, according to which the text characters lie studded on an area that
-stretches infinitely far to the right and downward. The concept of the end
-of a line does not exist in this model; the most you can say is where the
-last nonblank character on the line is found.
-
- Of course, Emacs really always considers text as a sequence of
-characters, and lines really do have ends. But Picture mode replaces
-the most frequently-used commands with variants that simulate the
-quarter-plane model of text. They do this by inserting spaces or by
-converting tabs to spaces.
-
- Most of the basic editing commands of Emacs are redefined by Picture mode
-to do essentially the same thing but in a quarter-plane way. In addition,
-Picture mode defines various keys starting with the @kbd{C-c} prefix to
-run special picture editing commands.
-
- One of these keys, @kbd{C-c C-c}, is particularly important. Often a
-picture is part of a larger file that is usually edited in some other
-major mode. @kbd{M-x edit-picture} records the name of the previous
-major mode so you can use the @kbd{C-c C-c} command
-(@code{picture-mode-exit}) later to go back to that mode. @kbd{C-c C-c}
-also deletes spaces from the ends of lines, unless given a numeric
-argument.
-
- The special commands of Picture mode all work in other modes (provided
-the @file{picture} library is loaded), but are not bound to keys except
-in Picture mode. The descriptions below talk of moving ``one column''
-and so on, but all the picture mode commands handle numeric arguments as
-their normal equivalents do.
-
-@vindex picture-mode-hook
- Turning on Picture mode runs the hook @code{picture-mode-hook}.
-Additional extensions to Picture mode can be found in
-@file{artist.el}.
-
-@menu
-* Basic Picture:: Basic concepts and simple commands of Picture Mode.
-* Insert in Picture:: Controlling direction of cursor motion
- after "self-inserting" characters.
-* Tabs in Picture:: Various features for tab stops and indentation.
-* Rectangles in Picture:: Clearing and superimposing rectangles.
-@end menu
-
-@node Basic Picture
-@section Basic Editing in Picture Mode
-
-@findex picture-forward-column
-@findex picture-backward-column
-@findex picture-move-down
-@findex picture-move-up
-@cindex editing in Picture mode
-
- Most keys do the same thing in Picture mode that they usually do, but
-do it in a quarter-plane style. For example, @kbd{C-f} is rebound to
-run @code{picture-forward-column}, a command which moves point one
-column to the right, inserting a space if necessary so that the actual
-end of the line makes no difference. @kbd{C-b} is rebound to run
-@code{picture-backward-column}, which always moves point left one
-column, converting a tab to multiple spaces if necessary. @kbd{C-n} and
-@kbd{C-p} are rebound to run @code{picture-move-down} and
-@code{picture-move-up}, which can either insert spaces or convert tabs
-as necessary to make sure that point stays in exactly the same column.
-@kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last
-nonblank character on the line. There is no need to change @kbd{C-a},
-as the choice of screen model does not affect beginnings of
-lines.
-
-@findex picture-newline
- Insertion of text is adapted to the quarter-plane screen model
-through the use of Overwrite mode
-@iftex
-(@pxref{Minor Modes,,, emacs, the Emacs Manual}.)
-@end iftex
-@ifnottex
-(@pxref{Minor Modes}.)
-@end ifnottex
-Self-inserting characters replace existing text, column by column,
-rather than pushing existing text to the right. @key{RET} runs
-@code{picture-newline}, which just moves to the beginning of the
-following line so that new text will replace that line.
-
-@findex picture-backward-clear-column
-@findex picture-clear-column
-@findex picture-clear-line
- In Picture mode, the commands that normally delete or kill text,
-instead erase text (replacing it with spaces). @key{DEL}
-(@code{picture-backward-clear-column}) replaces the preceding
-character with a space rather than removing it; this moves point
-backwards. @kbd{C-d} (@code{picture-clear-column}) replaces the next
-character or characters with spaces, but does not move point. (If you
-want to clear characters to spaces and move forward over them, use
-@key{SPC}.) @kbd{C-k} (@code{picture-clear-line}) really kills the
-contents of lines, but does not delete the newlines from the buffer.
-
-@findex picture-open-line
- To do actual insertion, you must use special commands. @kbd{C-o}
-(@code{picture-open-line}) creates a blank line after the current
-line; it never splits a line. @kbd{C-M-o} (@code{split-line}) makes
-sense in Picture mode, so it is not changed. @kbd{C-j}
-(@code{picture-duplicate-line}) inserts another line with the same
-contents below the current line.
-
-@kindex C-c C-d @r{(Picture mode)}
- To do actual deletion in Picture mode, use @kbd{C-w}, @kbd{C-c C-d}
-(which is defined as @code{delete-char}, as @kbd{C-d} is in other
-modes), or one of the picture rectangle commands (@pxref{Rectangles in
-Picture}).
-
-@node Insert in Picture
-@section Controlling Motion after Insert
-
-@findex picture-movement-up
-@findex picture-movement-down
-@findex picture-movement-left
-@findex picture-movement-right
-@findex picture-movement-nw
-@findex picture-movement-ne
-@findex picture-movement-sw
-@findex picture-movement-se
-@kindex C-c < @r{(Picture mode)}
-@kindex C-c > @r{(Picture mode)}
-@kindex C-c ^ @r{(Picture mode)}
-@kindex C-c . @r{(Picture mode)}
-@kindex C-c ` @r{(Picture mode)}
-@kindex C-c ' @r{(Picture mode)}
-@kindex C-c / @r{(Picture mode)}
-@kindex C-c \ @r{(Picture mode)}
- Since ``self-inserting'' characters in Picture mode overwrite and move
-point, there is no essential restriction on how point should be moved.
-Normally point moves right, but you can specify any of the eight
-orthogonal or diagonal directions for motion after a ``self-inserting''
-character. This is useful for drawing lines in the buffer.
-
-@table @kbd
-@item C-c <
-@itemx C-c @key{LEFT}
-Move left after insertion (@code{picture-movement-left}).
-@item C-c >
-@itemx C-c @key{RIGHT}
-Move right after insertion (@code{picture-movement-right}).
-@item C-c ^
-@itemx C-c @key{UP}
-Move up after insertion (@code{picture-movement-up}).
-@item C-c .
-@itemx C-c @key{DOWN}
-Move down after insertion (@code{picture-movement-down}).
-@item C-c `
-@itemx C-c @key{HOME}
-Move up and left (``northwest'') after insertion (@code{picture-movement-nw}).
-@item C-c '
-@itemx C-c @key{PAGEUP}
-Move up and right (``northeast'') after insertion
-(@code{picture-movement-ne}).
-@item C-c /
-@itemx C-c @key{END}
-Move down and left (``southwest'') after insertion
-@*(@code{picture-movement-sw}).
-@item C-c \
-@itemx C-c @key{PAGEDOWN}
-Move down and right (``southeast'') after insertion
-@*(@code{picture-movement-se}).
-@end table
-
-@kindex C-c C-f @r{(Picture mode)}
-@kindex C-c C-b @r{(Picture mode)}
-@findex picture-motion
-@findex picture-motion-reverse
- Two motion commands move based on the current Picture insertion
-direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the
-same direction as motion after ``insertion'' currently does, while @kbd{C-c
-C-b} (@code{picture-motion-reverse}) moves in the opposite direction.
-
-@node Tabs in Picture
-@section Picture Mode Tabs
-
-@kindex M-TAB @r{(Picture mode)}
-@findex picture-tab-search
-@vindex picture-tab-chars
- Two kinds of tab-like action are provided in Picture mode. Use
-@kbd{M-@key{TAB}} (@code{picture-tab-search}) for context-based tabbing.
-With no argument, it moves to a point underneath the next
-``interesting'' character that follows whitespace in the previous
-nonblank line. ``Next'' here means ``appearing at a horizontal position
-greater than the one point starts out at.'' With an argument, as in
-@kbd{C-u M-@key{TAB}}, this command moves to the next such interesting
-character in the current line. @kbd{M-@key{TAB}} does not change the
-text; it only moves point. ``Interesting'' characters are defined by
-the variable @code{picture-tab-chars}, which should define a set of
-characters. The syntax for this variable is like the syntax used inside
-of @samp{[@dots{}]} in a regular expression---but without the @samp{[}
-and the @samp{]}. Its default value is @code{"!-~"}.
-
-@findex picture-tab
- @key{TAB} itself runs @code{picture-tab}, which operates based on the
-current tab stop settings; it is the Picture mode equivalent of
-@code{tab-to-tab-stop}. Normally it just moves point, but with a numeric
-argument it clears the text that it moves over.
-
-@kindex C-c TAB @r{(Picture mode)}
-@findex picture-set-tab-stops
- The context-based and tab-stop-based forms of tabbing are brought
-together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}).
-This command sets the tab stops to the positions which @kbd{M-@key{TAB}}
-would consider significant in the current line. The use of this command,
-together with @key{TAB}, can get the effect of context-based tabbing. But
-@kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient.
-
- It may be convenient to prevent use of actual tab characters in
-pictures. For example, this prevents @kbd{C-x @key{TAB}} from messing
-up the picture. You can do this by setting the variable
-@code{indent-tabs-mode} to @code{nil}.
-
-@node Rectangles in Picture
-@section Picture Mode Rectangle Commands
-@cindex rectangles and Picture mode
-@cindex Picture mode and rectangles
-
- Picture mode defines commands for working on rectangular pieces of
-the text in ways that fit with the quarter-plane model. The standard
-rectangle commands may also be useful.
-@iftex
-@xref{Rectangles,,, emacs, the Emacs Manual}.
-@end iftex
-@ifnottex
-@xref{Rectangles}.
-@end ifnottex
-
-@table @kbd
-@item C-c C-k
-Clear out the region-rectangle with spaces
-(@code{picture-clear-rectangle}). With argument, delete the text.
-@item C-c C-w @var{r}
-Similar, but save rectangle contents in register @var{r} first
-(@code{picture-clear-rectangle-to-register}).
-@item C-c C-y
-Copy last killed rectangle into the buffer by overwriting, with upper
-left corner at point (@code{picture-yank-rectangle}). With argument,
-insert instead.
-@item C-c C-x @var{r}
-Similar, but use the rectangle in register @var{r}
-(@code{picture-yank-rectangle-from-register}).
-@end table
-
-@kindex C-c C-k @r{(Picture mode)}
-@kindex C-c C-w @r{(Picture mode)}
-@findex picture-clear-rectangle
-@findex picture-clear-rectangle-to-register
- The picture rectangle commands @kbd{C-c C-k}
-(@code{picture-clear-rectangle}) and @kbd{C-c C-w}
-(@code{picture-clear-rectangle-to-register}) differ from the standard
-rectangle commands in that they normally clear the rectangle instead of
-deleting it; this is analogous with the way @kbd{C-d} is changed in Picture
-mode.
-
- However, deletion of rectangles can be useful in Picture mode, so
-these commands delete the rectangle if given a numeric argument.
-@kbd{C-c C-k} either with or without a numeric argument saves the
-rectangle for @kbd{C-c C-y}.
-
-@kindex C-c C-y @r{(Picture mode)}
-@kindex C-c C-x @r{(Picture mode)}
-@findex picture-yank-rectangle
-@findex picture-yank-rectangle-from-register
- The Picture mode commands for yanking rectangles differ from the
-standard ones in that they overwrite instead of inserting. This is
-the same way that Picture mode insertion of other text differs from
-other modes. @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts
-(by overwriting) the rectangle that was most recently killed, while
-@kbd{C-c C-x} (@code{picture-yank-rectangle-from-register}) does
-likewise for the rectangle found in a specified register.
-
-@ignore
- arch-tag: 10e423ad-d896-42f2-a7e8-7018adeaf8c2
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Programs, Building, Text, Top
-@chapter Editing Programs
-@cindex Lisp editing
-@cindex C editing
-@cindex program editing
-
- Emacs provides many features to facilitate editing programs. Some
-of these features can
-
-@itemize @bullet
-@item
-Find or move over top-level definitions (@pxref{Defuns}).
-@item
-Apply the usual indentation conventions of the language
-(@pxref{Program Indent}).
-@item
-Balance parentheses (@pxref{Parentheses}).
-@item
-Insert, kill or align comments (@pxref{Comments}).
-@item
-Highlight program syntax (@pxref{Font Lock}).
-@end itemize
-
- This chapter describes these features and many more.
-
-@menu
-* Program Modes:: Major modes for editing programs.
-* Defuns:: Commands to operate on major top-level parts
- of a program.
-* Program Indent:: Adjusting indentation to show the nesting.
-* Parentheses:: Commands that operate on parentheses.
-* Comments:: Inserting, killing, and aligning comments.
-* Documentation:: Getting documentation of functions you plan to call.
-* Hideshow:: Displaying blocks selectively.
-* Symbol Completion:: Completion on symbol names of your program or language.
-* Glasses:: Making identifiersLikeThis more readable.
-* Misc for Programs:: Other Emacs features useful for editing programs.
-* C Modes:: Special commands of C, C++, Objective-C,
- Java, and Pike modes.
-* Asm Mode:: Asm mode and its special features.
-@ifnottex
-* Fortran:: Fortran mode and its special features.
-@end ifnottex
-@end menu
-
-@node Program Modes
-@section Major Modes for Programming Languages
-@cindex modes for programming languages
-
- Emacs has specialized major modes for various programming languages.
-@xref{Major Modes}. A programming language major mode typically
-specifies the syntax of expressions, the customary rules for
-indentation, how to do syntax highlighting for the language, and how
-to find the beginning of a function definition. It often customizes
-or provides facilities for compiling and debugging programs as well.
-
- Ideally, Emacs should provide a major mode for each programming
-language that you might want to edit; if it doesn't have a mode for
-your favorite language, you can contribute one. But often the mode
-for one language can serve for other syntactically similar languages.
-The major mode for language @var{l} is called @code{@var{l}-mode},
-and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}.
-@xref{Choosing Modes}.
-
-@cindex Perl mode
-@cindex Icon mode
-@cindex Makefile mode
-@cindex Tcl mode
-@cindex CPerl mode
-@cindex DSSSL mode
-@cindex Octave mode
-@cindex Metafont mode
-@cindex Modula2 mode
-@cindex Prolog mode
-@cindex Python mode
-@cindex Simula mode
-@cindex VHDL mode
-@cindex M4 mode
-@cindex Shell-script mode
-@cindex Delphi mode
-@cindex PostScript mode
-@cindex Conf mode
-@cindex DNS mode
- The existing programming language major modes include Lisp, Scheme (a
-variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
-ASM, AWK, C, C++, Delphi (Object Pascal), Fortran (free format and fixed
-format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s
-companion for font creation), Modula2, Objective-C, Octave, Pascal,
-Perl, Pike, PostScript, Prolog, Python, Simula, Tcl, and VHDL. An
-alternative mode for Perl is called CPerl mode. Modes are available for
-the scripting languages of the common GNU and Unix shells, VMS DCL, and
-MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for
-editing makefiles, DNS master files, and various sorts of configuration
-files.
-
-@kindex DEL @r{(programming modes)}
-@findex c-electric-backspace
- In most programming languages, indentation should vary from line to
-line to illustrate the structure of the program. So the major modes
-for programming languages arrange for @key{TAB} to update the
-indentation of the current line. They also rebind @key{DEL} to treat
-a tab as if it were the equivalent number of spaces; this lets you
-delete one column of indentation without worrying whether the
-whitespace consists of spaces or tabs. Use @kbd{C-b C-d} to delete a
-tab character before point, in these modes.
-
- Separate manuals are available for the modes for Ada (@pxref{Top, , Ada
-Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK
-(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
-(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). For Fortran
-mode, see
-@iftex
-@ref{Fortran,,, emacs-xtra, Specialized Emacs Features}.
-@end iftex
-@ifnottex
-@ref{Fortran}.
-@end ifnottex
-
-
-@cindex mode hook
-@vindex c-mode-hook
-@vindex lisp-mode-hook
-@vindex emacs-lisp-mode-hook
-@vindex lisp-interaction-mode-hook
-@vindex scheme-mode-hook
- Turning on a major mode runs a normal hook called the @dfn{mode
-hook}, which is the value of a Lisp variable. Each major mode has a
-mode hook, and the hook's name is always made from the mode command's
-name by adding @samp{-hook}. For example, turning on C mode runs the
-hook @code{c-mode-hook}, while turning on Lisp mode runs the hook
-@code{lisp-mode-hook}. The purpose of the mode hook is to give you a
-place to set up customizations for that major mode. @xref{Hooks}.
-
-@node Defuns
-@section Top-Level Definitions, or Defuns
-
- In Emacs, a major definition at the top level in the buffer,
-something like a function, is called a @dfn{defun}. The name comes
-from Lisp, but in Emacs we use it for all languages.
-
-@menu
-* Left Margin Paren:: An open-paren or similar opening delimiter
- starts a defun if it is at the left margin.
-* Moving by Defuns:: Commands to move over or mark a major definition.
-* Imenu:: Making buffer indexes as menus.
-* Which Function:: Which Function mode shows which function you are in.
-@end menu
-
-@node Left Margin Paren
-@subsection Left Margin Convention
-
-@cindex open-parenthesis in leftmost column
-@cindex ( in leftmost column
- Emacs assumes by default that any opening delimiter found at the
-left margin is the start of a top-level definition, or defun.
-Therefore, @strong{don't put an opening delimiter at the left margin
-unless it should have that significance}. For instance, never put an
-open-parenthesis at the left margin in a Lisp file unless it is the
-start of a top-level list.
-
- If you don't follow this convention, not only will you have trouble
-when you explicitly use the commands for motion by defuns; other
-features that use them will also give you trouble. This includes
-the indentation commands (@pxref{Program Indent}) and Font Lock
-mode (@pxref{Font Lock}).
-
- The most likely problem case is when you want an opening delimiter
-at the start of a line inside a string. To avoid trouble, put an
-escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some
-other Lisp dialects) before the opening delimiter. This will not
-affect the contents of the string, but will prevent that opening
-delimiter from starting a defun. Here's an example:
-
-@example
- (insert "Foo:
-\(bar)
-")
-@end example
-
- To help you catch violations of this convention, Font Lock mode
-highlights confusing opening delimiters (those that ought to be
-quoted) in bold red.
-
-If you need to override this convention, you can so by setting this
-user option:
-
-@defvar open-paren-in-column-0-is-defun-start
-If this user option is set to @code{t} (the default), opening
-parentheses or braces at column zero always start defuns. When it's
-@code{nil}, defuns are found by searching for parens or braces at the
-outermost level.
-@end defvar
-
- Usually, you shouldn't need to set
-@code{open-paren-in-column-0-is-defun-start} to @code{nil}. However,
-if your buffer contains parentheses or braces in column zero which
-don't start defuns and this confuses Emacs, it sometimes helps to set
-the option to @code{nil}. Be aware, though, that this will make
-scrolling and display in large buffers quite sluggish, and that
-parentheses and braces must be correctly matched throughout the buffer
-for it to work properly.
-
- In the earliest days, the original Emacs found defuns by moving
-upward a level of parentheses or braces until there were no more
-levels to go up. This always required scanning all the way back to
-the beginning of the buffer, even for a small function. To speed up
-the operation, we changed Emacs to assume that any opening delimiter
-at the left margin is the start of a defun. This heuristic is nearly
-always right, and avoids the need to scan back to the beginning of the
-buffer. However, now that modern computers are so powerful, this
-scanning is rarely slow enough to annoy, so we've provided a way to
-disable the heuristic.
-
-@node Moving by Defuns
-@subsection Moving by Defuns
-@cindex defuns
-
- These commands move point or set up the region based on top-level
-major definitions, also called @dfn{defuns}.
-
-@table @kbd
-@item C-M-a
-Move to beginning of current or preceding defun
-(@code{beginning-of-defun}).
-@item C-M-e
-Move to end of current or following defun (@code{end-of-defun}).
-@item C-M-h
-Put region around whole current or following defun (@code{mark-defun}).
-@end table
-
-@cindex move to beginning or end of function
-@cindex function, move to beginning or end
-@kindex C-M-a
-@kindex C-M-e
-@kindex C-M-h
-@findex beginning-of-defun
-@findex end-of-defun
-@findex mark-defun
- The commands to move to the beginning and end of the current defun
-are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e}
-(@code{end-of-defun}). If you repeat one of these commands, or use a
-positive numeric argument, each repetition moves to the next defun in
-the direction of motion.
-
- @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward
-@var{n} times to the next beginning of a defun. This is not exactly
-the same place that @kbd{C-M-e} with argument @var{n} would move to;
-the end of this defun is not usually exactly the same place as the
-beginning of the following defun. (Whitespace, comments, and perhaps
-declarations can separate them.) Likewise, @kbd{C-M-e} with a
-negative argument moves back to an end of a defun, which is not quite
-the same as @kbd{C-M-a} with a positive argument.
-
-@kindex C-M-h @r{(C mode)}
-@findex c-mark-function
- To operate on the current defun, use @kbd{C-M-h} (@code{mark-defun})
-which puts point at the beginning and mark at the end of the current
-defun. This is the easiest way to get ready to kill the defun in
-order to move it to a different place in the file. If you use the
-command while point is between defuns, it uses the following defun.
-Successive uses of @kbd{C-M-h}, or using it in Transient Mark mode
-when the mark is active, extends the end of the region to include one
-more defun each time.
-
- In C mode, @kbd{C-M-h} runs the function @code{c-mark-function},
-which is almost the same as @code{mark-defun}; the difference is that
-it backs up over the argument declarations, function name and returned
-data type so that the entire C function is inside the region. This is
-an example of how major modes adjust the standard key bindings so that
-they do their standard jobs in a way better fitting a particular
-language. Other major modes may replace any or all of these key
-bindings for that purpose.
-
-@node Imenu
-@subsection Imenu
-@cindex index of buffer definitions
-@cindex buffer definitions index
-@cindex tags
-
- The Imenu facility offers a way to find the major definitions in
-a file by name. It is also useful in text formatter major modes,
-where it treats each chapter, section, etc., as a definition.
-(@xref{Tags}, for a more powerful feature that handles multiple files
-together.)
-
-@findex imenu
- If you type @kbd{M-x imenu}, it reads the name of a definition using
-the minibuffer, then moves point to that definition. You can use
-completion to specify the name; the command always displays the whole
-list of valid names.
-
-@findex imenu-add-menubar-index
- Alternatively, you can bind the command @code{imenu} to a mouse
-click. Then it displays mouse menus for you to select a definition
-name. You can also add the buffer's index to the menu bar by calling
-@code{imenu-add-menubar-index}. If you want to have this menu bar
-item available for all buffers in a certain major mode, you can do
-this by adding @code{imenu-add-menubar-index} to its mode hook. But
-if you have done that, you will have to wait a little while each time
-you visit a file in that mode, while Emacs finds all the definitions
-in that buffer.
-
-@vindex imenu-auto-rescan
- When you change the contents of a buffer, if you add or delete
-definitions, you can update the buffer's index based on the
-new contents by invoking the @samp{*Rescan*} item in the menu.
-Rescanning happens automatically if you set @code{imenu-auto-rescan} to
-a non-@code{nil} value. There is no need to rescan because of small
-changes in the text.
-
-@vindex imenu-sort-function
- You can customize the way the menus are sorted by setting the
-variable @code{imenu-sort-function}. By default, names are ordered as
-they occur in the buffer; if you want alphabetic sorting, use the
-symbol @code{imenu--sort-by-name} as the value. You can also
-define your own comparison function by writing Lisp code.
-
- Imenu provides the information to guide Which Function mode
-@ifnottex
-(@pxref{Which Function}).
-@end ifnottex
-@iftex
-(see below).
-@end iftex
-The Speedbar can also use it (@pxref{Speedbar}).
-
-@node Which Function
-@subsection Which Function Mode
-@cindex current function name in mode line
-
- Which Function mode is a minor mode that displays the current
-function name in the mode line, updating it as you move around in a
-buffer.
-
-@findex which-function-mode
-@vindex which-func-modes
- To either enable or disable Which Function mode, use the command
-@kbd{M-x which-function-mode}. This command is global; it applies to
-all buffers, both existing ones and those yet to be created. However,
-it takes effect only in certain major modes, those listed in the value
-of @code{which-func-modes}. If the value is @code{t}, then Which
-Function mode applies to all major modes that know how to support
-it---in other words, all the major modes that support Imenu.
-
-@node Program Indent
-@section Indentation for Programs
-@cindex indentation for programs
-
- The best way to keep a program properly indented is to use Emacs to
-reindent it as you change it. Emacs has commands to indent properly
-either a single line, a specified number of lines, or all of the lines
-inside a single parenthetical grouping.
-
-@menu
-* Basic Indent:: Indenting a single line.
-* Multi-line Indent:: Commands to reindent many lines at once.
-* Lisp Indent:: Specifying how each Lisp function should be indented.
-* C Indent:: Extra features for indenting C and related modes.
-* Custom C Indent:: Controlling indentation style for C and related modes.
-@end menu
-
-@cindex pretty-printer
- Emacs also provides a Lisp pretty-printer in the library @code{pp}.
-This program reformats a Lisp object with indentation chosen to look nice.
-
-@node Basic Indent
-@subsection Basic Program Indentation Commands
-
- The basic indentation commands indent a single line according to the
-usual conventions of the language you are editing.
-
-@need 1000
-@table @kbd
-@item @key{TAB}
-Adjust indentation of current line.
-@item C-j
-Insert a newline, then adjust indentation of following line
-(@code{newline-and-indent}).
-@end table
-
-@kindex TAB @r{(programming modes)}
-@findex c-indent-command
-@findex indent-line-function
-@findex indent-for-tab-command
- The basic indentation command is @key{TAB}, which gives the current line
-the correct indentation as determined from the previous lines. The
-function that @key{TAB} runs depends on the major mode; it is
-@code{lisp-indent-line}
-in Lisp mode, @code{c-indent-command} in C mode, etc. These functions
-understand the syntax and conventions of different languages, but they all do
-conceptually the same job: @key{TAB} in any programming-language major mode
-inserts or deletes whitespace at the beginning of the current line,
-independent of where point is in the line. If point was inside the
-whitespace at the beginning of the line, @key{TAB} puts it at the end of
-that whitespace; otherwise, @key{TAB} keeps point fixed with respect to
-the characters around it.
-
- Use @kbd{C-q @key{TAB}} to insert a tab character at point.
-
-@kindex C-j
-@findex newline-and-indent
- When entering lines of new code, use @kbd{C-j}
-(@code{newline-and-indent}), which inserts a newline and then adjusts
-indentation after it. (It also deletes any trailing whitespace which
-remains before the new newline.) Thus, @kbd{C-j} at the end of a line
-creates a blank line with appropriate indentation. In programming
-language modes, it is equivalent to @key{RET} @key{TAB}.
-
- @key{TAB} indents a line that starts within a parenthetical grouping
-under the preceding line within the grouping, or the text after the
-parenthesis. Therefore, if you manually give one of these lines a
-nonstandard indentation, the lines below will tend to follow it. This
-behavior is convenient in cases where you have overridden the standard
-result of @key{TAB} because you find it unaesthetic for a particular
-line.
-
- In some modes, an open-parenthesis, open-brace or other opening
-delimiter at the left margin is assumed by Emacs (including the
-indentation routines) to be the start of a function. This speeds up
-indentation commands. If you will be editing text which contains
-opening delimiters in column zero that aren't the beginning of a
-functions, even inside strings or comments, you must set
-@code{open-paren-in-column-0-is-defun-start}. @xref{Left Margin
-Paren}, for more information on this.
-
- Normally, lines are indented with tabs and spaces. If you want Emacs
-to use spaces only, set @code{indent-tabs-mode} (@pxref{Just Spaces}).
-
-@node Multi-line Indent
-@subsection Indenting Several Lines
-
- When you wish to reindent several lines of code which have been
-altered or moved to a different level in the parenthesis structure,
-you have several commands available.
-
-@table @kbd
-@item C-M-q
-Reindent all the lines within one parenthetical grouping (@code{indent-pp-sexp}).
-@item C-M-\
-Reindent all lines in the region (@code{indent-region}).
-@item C-u @key{TAB}
-Shift an entire parenthetical grouping rigidly sideways so that its
-first line is properly indented.
-@item M-x indent-code-rigidly
-Shift all the lines in the region rigidly sideways, but do not alter
-lines that start inside comments and strings.
-@end table
-
-@kindex C-M-q
-@findex indent-pp-sexp
- You can reindent the contents of a single parenthetical grouping by
-positioning point before the beginning of it and typing @kbd{C-M-q}
-(@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode; also
-bound to other suitable commands in other modes). The indentation of
-the line where the grouping starts is not changed; therefore this
-changes only the relative indentation within the grouping, not its
-overall indentation. To correct that as well, type @key{TAB} first.
-
- Another way to specify the range to be reindented is with the
-region. The command @kbd{C-M-\} (@code{indent-region}) applies
-@key{TAB} to every line whose first character is between point and
-mark.
-
-@kindex C-u TAB
- If you like the relative indentation within a grouping, but not the
-indentation of its first line, you can type @kbd{C-u @key{TAB}} to
-reindent the whole grouping as a rigid unit. (This works in Lisp
-modes and C and related modes.) @key{TAB} with a numeric argument
-reindents the current line as usual, then reindents by the same amount
-all the lines in the parenthetical grouping starting on the current
-line. It is clever, though, and does not alter lines that start
-inside strings. Neither does it alter C preprocessor lines when in C
-mode, but it does reindent any continuation lines that may be attached
-to them.
-
-@findex indent-code-rigidly
- You can also perform this operation on the region, using the command
-@kbd{M-x indent-code-rigidly}. It rigidly shifts all the lines in the
-region sideways, like @code{indent-rigidly} does (@pxref{Indentation
-Commands}). It doesn't alter the indentation of lines that start
-inside a string, unless the region also starts inside that string.
-The prefix arg specifies the number of columns to indent.
-
-@node Lisp Indent
-@subsection Customizing Lisp Indentation
-@cindex customizing Lisp indentation
-
- The indentation pattern for a Lisp expression can depend on the function
-called by the expression. For each Lisp function, you can choose among
-several predefined patterns of indentation, or define an arbitrary one with
-a Lisp program.
-
- The standard pattern of indentation is as follows: the second line of the
-expression is indented under the first argument, if that is on the same
-line as the beginning of the expression; otherwise, the second line is
-indented underneath the function name. Each following line is indented
-under the previous line whose nesting depth is the same.
-
-@vindex lisp-indent-offset
- If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
-the usual indentation pattern for the second line of an expression, so that
-such lines are always indented @code{lisp-indent-offset} more columns than
-the containing list.
-
-@vindex lisp-body-indent
- Certain functions override the standard pattern. Functions whose
-names start with @code{def} treat the second lines as the start of
-a @dfn{body}, by indenting the second line @code{lisp-body-indent}
-additional columns beyond the open-parenthesis that starts the
-expression.
-
-@cindex @code{lisp-indent-function} property
- You can override the standard pattern in various ways for individual
-functions, according to the @code{lisp-indent-function} property of
-the function name. Normally you would use this for macro definitions
-and specify it using the @code{declare} construct (@pxref{Defining
-Macros,,, elisp, the Emacs Lisp Reference Manual}).
-
-@node C Indent
-@subsection Commands for C Indentation
-
- Here are special features for indentation in C mode and related modes:
-
-@table @code
-@item C-c C-q
-@kindex C-c C-q @r{(C mode)}
-@findex c-indent-defun
-Reindent the current top-level function definition or aggregate type
-declaration (@code{c-indent-defun}).
-
-@item C-M-q
-@kindex C-M-q @r{(C mode)}
-@findex c-indent-exp
-Reindent each line in the balanced expression that follows point
-(@code{c-indent-exp}). A prefix argument inhibits warning messages
-about invalid syntax.
-
-@item @key{TAB}
-@findex c-indent-command
-Reindent the current line, and/or in some cases insert a tab character
-(@code{c-indent-command}).
-
-@vindex c-tab-always-indent
-If @code{c-tab-always-indent} is @code{t}, this command always reindents
-the current line and does nothing else. This is the default.
-
-If that variable is @code{nil}, this command reindents the current line
-only if point is at the left margin or in the line's indentation;
-otherwise, it inserts a tab (or the equivalent number of spaces,
-if @code{indent-tabs-mode} is @code{nil}).
-
-Any other value (not @code{nil} or @code{t}) means always reindent the
-line, and also insert a tab if within a comment or a string.
-@end table
-
- To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This
-first selects the whole buffer as the region, then reindents that
-region.
-
- To reindent the current block, use @kbd{C-M-u C-M-q}. This moves
-to the front of the block and then reindents it all.
-
-@node Custom C Indent
-@subsection Customizing C Indentation
-@cindex style (for indentation)
-
- C mode and related modes use a flexible mechanism for customizing
-indentation. C mode indents a source line in two steps: first it
-classifies the line syntactically according to its contents and
-context; second, it determines the indentation offset associated by
-your selected @dfn{style} with the syntactic construct and adds this
-onto the indentation of the @dfn{anchor statement}.
-
-@table @kbd
-@item C-c . @key{RET} @var{style} @key{RET}
-Select a predefined style @var{style} (@code{c-set-style}).
-@end table
-
- A @dfn{style} is a named collection of customizations that can be
-used in C mode and the related modes. @ref{Styles,,, ccmode, The CC
-Mode Manual}, for a complete description. Emacs comes with several
-predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
-@code{stroustrup}, @code{linux}, @code{python}, @code{java},
-@code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these
-styles are primarily intended for one language, but any of them can be
-used with any of the languages supported by these modes. To find out
-what a style looks like, select it and reindent some code, e.g., by
-typing @key{C-M-q} at the start of a function definition.
-
-@kindex C-c . @r{(C mode)}
-@findex c-set-style
- To choose a style for the current buffer, use the command @w{@kbd{C-c
-.}}. Specify a style name as an argument (case is not significant).
-This command affects the current buffer only, and it affects only
-future invocations of the indentation commands; it does not reindent
-the code already in the buffer. To reindent the whole buffer in the
-new style, you can type @kbd{C-x h C-M-\}.
-
-@vindex c-default-style
- You can also set the variable @code{c-default-style} to specify the
-default style for various major modes. Its value should be either the
-style's name (a string) or an alist, in which each element specifies
-one major mode and which indentation style to use for it. For
-example,
-
-@example
-(setq c-default-style
- '((java-mode . "java") (awk-mode . "awk") (other . "gnu")))
-@end example
-
-@noindent
-specifies explicit choices for Java and AWK modes, and the default
-@samp{gnu} style for the other C-like modes. (These settings are
-actually the defaults.) This variable takes effect when you select
-one of the C-like major modes; thus, if you specify a new default
-style for Java mode, you can make it take effect in an existing Java
-mode buffer by typing @kbd{M-x java-mode} there.
-
- The @code{gnu} style specifies the formatting recommended by the GNU
-Project for C; it is the default, so as to encourage use of our
-recommended style.
-
- @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and
-@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more
-information on customizing indentation for C and related modes,
-including how to override parts of an existing style and how to define
-your own styles.
-
-@node Parentheses
-@section Commands for Editing with Parentheses
-
-@findex check-parens
-@cindex unbalanced parentheses and quotes
- This section describes the commands and features that take advantage
-of the parenthesis structure in a program, or help you keep it
-balanced.
-
- When talking about these facilities, the term ``parenthesis'' also
-includes braces, brackets, or whatever delimiters are defined to match
-in pairs. The major mode controls which delimiters are significant,
-through the syntax table (@pxref{Syntax}). In Lisp, only parentheses
-count; in C, these commands apply to braces and brackets too.
-
- You can use @kbd{M-x check-parens} to find any unbalanced
-parentheses and unbalanced string quotes in the buffer.
-
-@menu
-* Expressions:: Expressions with balanced parentheses.
-* Moving by Parens:: Commands for moving up, down and across
- in the structure of parentheses.
-* Matching:: Insertion of a close-delimiter flashes matching open.
-@end menu
-
-@node Expressions
-@subsection Expressions with Balanced Parentheses
-
-@cindex sexp
-@cindex expression
-@cindex balanced expression
- These commands deal with balanced expressions, also called
-@dfn{sexps}@footnote{The word ``sexp'' is used to refer to an
-expression in Lisp.}.
-
-@table @kbd
-@item C-M-f
-Move forward over a balanced expression (@code{forward-sexp}).
-@item C-M-b
-Move backward over a balanced expression (@code{backward-sexp}).
-@item C-M-k
-Kill balanced expression forward (@code{kill-sexp}).
-@item C-M-t
-Transpose expressions (@code{transpose-sexps}).
-@item C-M-@@
-@itemx C-M-@key{SPC}
-Put mark after following expression (@code{mark-sexp}).
-@end table
-
- Each programming language major mode customizes the definition of
-balanced expressions to suit that language. Balanced expressions
-typically include symbols, numbers, and string constants, as well as
-any pair of matching delimiters and their contents. Some languages
-have obscure forms of expression syntax that nobody has bothered to
-implement in Emacs.
-
-@cindex Control-Meta
- By convention, the keys for these commands are all Control-Meta
-characters. They usually act on expressions just as the corresponding
-Meta characters act on words. For instance, the command @kbd{C-M-b}
-moves backward over a balanced expression, just as @kbd{M-b} moves
-back over a word.
-
-@kindex C-M-f
-@kindex C-M-b
-@findex forward-sexp
-@findex backward-sexp
- To move forward over a balanced expression, use @kbd{C-M-f}
-(@code{forward-sexp}). If the first significant character after point
-is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or
-@samp{@{} in C), @kbd{C-M-f} moves past the matching closing
-delimiter. If the character begins a symbol, string, or number,
-@kbd{C-M-f} moves over that.
-
- The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
-balanced expression. The detailed rules are like those above for
-@kbd{C-M-f}, but with directions reversed. If there are prefix
-characters (single-quote, backquote and comma, in Lisp) preceding the
-expression, @kbd{C-M-b} moves back over them as well. The balanced
-expression commands move across comments as if they were whitespace,
-in most modes.
-
- @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
-specified number of times; with a negative argument, it moves in the
-opposite direction.
-
-@cindex killing expressions
-@kindex C-M-k
-@findex kill-sexp
- Killing a whole balanced expression can be done with @kbd{C-M-k}
-(@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f}
-would move over.
-
-@cindex transposition of expressions
-@kindex C-M-t
-@findex transpose-sexps
- A somewhat random-sounding command which is nevertheless handy is
-@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous
-balanced expression across the next one. An argument serves as a
-repeat count, moving the previous expression over that many following
-ones. A negative argument drags the previous balanced expression
-backwards across those before it (thus canceling out the effect of
-@kbd{C-M-t} with a positive argument). An argument of zero, rather
-than doing nothing, transposes the balanced expressions ending at or
-after point and the mark.
-
-@kindex C-M-@@
-@kindex C-M-@key{SPC}
-@findex mark-sexp
- To set the region around the next balanced expression in the buffer,
-use @kbd{C-M-@@} (@code{mark-sexp}), which sets mark at the same place
-that @kbd{C-M-f} would move to. @kbd{C-M-@@} takes arguments like
-@kbd{C-M-f}. In particular, a negative argument is useful for putting
-the mark at the beginning of the previous balanced expression. The
-alias @kbd{C-M-@key{SPC}} is equivalent to @kbd{C-M-@@}. When you
-repeat this command, or use it in Transient Mark mode when the mark is
-active, it extends the end of the region by one sexp each time.
-
- In languages that use infix operators, such as C, it is not possible
-to recognize all balanced expressions as such because there can be
-multiple possibilities at a given position. For example, C mode does
-not treat @samp{foo + bar} as a single expression, even though it
-@emph{is} one C expression; instead, it recognizes @samp{foo} as one
-expression and @samp{bar} as another, with the @samp{+} as punctuation
-between them. Both @samp{foo + bar} and @samp{foo} are legitimate
-choices for ``the expression following point'' when point is at the
-@samp{f}, so the expression commands must perforce choose one or the
-other to operate on. Note that @samp{(foo + bar)} is recognized as a
-single expression in C mode, because of the parentheses.
-
-@node Moving by Parens
-@subsection Moving in the Parenthesis Structure
-
-@cindex parenthetical groupings
-@cindex parentheses, moving across
-@cindex matching parenthesis and braces, moving to
-@cindex braces, moving across
-@cindex list commands
- The Emacs commands for handling parenthetical groupings see nothing
-except parentheses (or whatever characters must balance in the
-language you are working with), and the escape characters that might
-be used to quote those. They are mainly intended for editing
-programs, but can be useful for editing any text that has parentheses.
-They are sometimes called ``list'' commands because in Lisp these
-groupings are lists.
-
-@table @kbd
-@item C-M-n
-Move forward over a parenthetical group (@code{forward-list}).
-@item C-M-p
-Move backward over a parenthetical group (@code{backward-list}).
-@item C-M-u
-Move up in parenthesis structure (@code{backward-up-list}).
-@item C-M-d
-Move down in parenthesis structure (@code{down-list}).
-@end table
-
-@kindex C-M-n
-@kindex C-M-p
-@findex forward-list
-@findex backward-list
- The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and
-@kbd{C-M-p} (@code{backward-list}) move over one (or @var{n})
-parenthetical groupings, skipping blithely over any amount of text
-that doesn't include meaningful parentheses (symbols, strings, etc.).
-
-@kindex C-M-u
-@findex backward-up-list
- @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
-parenthesis structure. To move @emph{up} one (or @var{n}) levels, use
-@kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up
-past one unmatched opening delimiter. A positive argument serves as a
-repeat count; a negative argument reverses the direction of motion, so
-that the command moves forward and up one or more levels.
-
-@kindex C-M-d
-@findex down-list
- To move @emph{down} in the parenthesis structure, use @kbd{C-M-d}
-(@code{down-list}). In Lisp mode, where @samp{(} is the only opening
-delimiter, this is nearly the same as searching for a @samp{(}. An
-argument specifies the number of levels to go down.
-
-@node Matching
-@subsection Automatic Display Of Matching Parentheses
-@cindex matching parentheses
-@cindex parentheses, displaying matches
-
- The Emacs parenthesis-matching feature is designed to show
-automatically how parentheses (and other matching delimiters) match in
-the text. Whenever you type a self-inserting character that is a
-closing delimiter, the cursor moves momentarily to the location of the
-matching opening delimiter, provided that is on the screen. If it is
-not on the screen, Emacs displays some of the text near it in the echo
-area. Either way, you can tell which grouping you are closing off.
-
- If the opening delimiter and closing delimiter are mismatched---such
-as in @samp{[x)}---a warning message is displayed in the echo area.
-
-@vindex blink-matching-paren
-@vindex blink-matching-paren-distance
-@vindex blink-matching-delay
- Three variables control parenthesis match display:
-
- @code{blink-matching-paren} turns the feature on or off: @code{nil}
-disables it, but the default is @code{t} to enable match display.
-
- @code{blink-matching-delay} says how many seconds to leave the
-cursor on the matching opening delimiter, before bringing it back to
-the real location of point; the default is 1, but on some systems it
-is useful to specify a fraction of a second.
-
- @code{blink-matching-paren-distance} specifies how many characters
-back to search to find the matching opening delimiter. If the match
-is not found in that distance, scanning stops, and nothing is displayed.
-This is to prevent the scan for the matching delimiter from wasting
-lots of time when there is no match. The default is 25600.
-
-@cindex Show Paren mode
-@cindex highlighting matching parentheses
-@findex show-paren-mode
- Show Paren mode provides a more powerful kind of automatic matching.
-Whenever point is after a closing delimiter, that delimiter and its
-matching opening delimiter are both highlighted; otherwise, if point
-is before an opening delimiter, the matching closing delimiter is
-highlighted. (There is no need to highlight the opening delimiter in
-that case, because the cursor appears on top of that character.) Use
-the command @kbd{M-x show-paren-mode} to enable or disable this mode.
-
- Show Paren mode uses the faces @code{show-paren-match} and
-@code{show-paren-mismatch} to highlight parentheses; you can customize
-them to control how highlighting looks. @xref{Face Customization}.
-
-@node Comments
-@section Manipulating Comments
-@cindex comments
-
- Because comments are such an important part of programming, Emacs
-provides special commands for editing and inserting comments. It can
-also do spell checking on comments with Flyspell Prog mode
-(@pxref{Spelling}).
-
-@menu
-* Comment Commands:: Inserting, killing, and aligning comments.
-* Multi-Line Comments:: Commands for adding and editing multi-line comments.
-* Options for Comments::Customizing the comment features.
-@end menu
-
-@node Comment Commands
-@subsection Comment Commands
-@cindex indentation for comments
-@cindex alignment for comments
-
- The comment commands in this table insert, kill and align comments.
-They are described in this section and following sections.
-
-@table @asis
-@item @kbd{M-;}
-Insert or realign comment on current line; alternatively, comment or
-uncomment the region (@code{comment-dwim}).
-@item @kbd{C-u M-;}
-Kill comment on current line (@code{comment-kill}).
-@item @kbd{C-x ;}
-Set comment column (@code{comment-set-column}).
-@item @kbd{C-M-j}
-@itemx @kbd{M-j}
-Like @key{RET} followed by inserting and aligning a comment
-(@code{comment-indent-new-line}). @xref{Multi-Line Comments}.
-@item @kbd{M-x comment-region}
-@itemx @kbd{C-c C-c} (in C-like modes)
-Add or remove comment delimiters on all the lines in the region.
-@end table
-
-@kindex M-;
-@findex comment-dwim
- The command to create or align a comment is @kbd{M-;}
-(@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What
-I Mean''; it indicates that this command can be used for many
-different jobs relating to comments, depending on the situation where
-you use it.
-
- If there is no comment already on the line, @kbd{M-;} inserts a new
-comment, aligned at a specific column called the @dfn{comment column}.
-The new comment begins with the string Emacs thinks comments should
-start with (the value of @code{comment-start}; see below). Point is
-after that string, so you can insert the text of the comment right
-away. If the major mode has specified a string to terminate comments,
-@kbd{M-;} inserts that after point, to keep the syntax valid.
-
- If the text of the line extends past the comment column, this
-command aligns the comment start string to a suitable boundary
-(usually, at least one space is inserted).
-
- You can also use @kbd{M-;} to align an existing comment. If a line
-already contains the comment-start string, @kbd{M-;} realigns it to
-the conventional alignment and moves point after it. (Exception:
-comments starting in column 0 are not moved.) Even when an existing
-comment is properly aligned, @kbd{M-;} is still useful for moving
-directly to the start of the text inside the comment.
-
-@findex comment-kill
-@kindex C-u M-;
- @kbd{C-u M-;} kills any comment on the current line, along with the
-whitespace before it. To reinsert the comment on another line, move
-to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to
-realign it.
-
- Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;}
-(@code{comment-dwim}) with a prefix argument. That command is
-programmed so that when it receives a prefix argument it calls
-@code{comment-kill}. However, @code{comment-kill} is a valid command
-in its own right, and you can bind it directly to a key if you wish.
-
- @kbd{M-;} does two other jobs when used with an active region in
-Transient Mark mode (@pxref{Transient Mark}). Then it either adds or
-removes comment delimiters on each line of the region. (If every line
-is a comment, it removes comment delimiters from each; otherwise, it
-adds comment delimiters to each.) If you are not using Transient Mark
-mode, then you should use the commands @code{comment-region} and
-@code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}),
-or else enable Transient Mark mode momentarily (@pxref{Momentary Mark}).
-A prefix argument used in these circumstances specifies how many
-comment delimiters to add or how many to delete.
-
- Some major modes have special rules for aligning certain kinds of
-comments in certain contexts. For example, in Lisp code, comments which
-start with two semicolons are indented as if they were lines of code,
-instead of at the comment column. Comments which start with three
-semicolons are supposed to start at the left margin and are often used
-for sectioning purposes. Emacs understands
-these conventions by indenting a double-semicolon comment using @key{TAB},
-and by not changing the indentation of a triple-semicolon comment at all.
-
-@example
-;; This function is just an example.
-;;; Here either two or three semicolons are appropriate.
-(defun foo (x)
-;;; And now, the first part of the function:
- ;; The following line adds one.
- (1+ x)) ; This line adds one.
-@end example
-
- For C-like modes, you can configure the exact effect of @kbd{M-;}
-more flexibly than for most buffers by setting the variables
-@code{c-indent-comment-alist} and
-@code{c-indent-comments-syntactically-p}. For example, on a line
-ending in a closing brace, @kbd{M-;} puts the comment one space after
-the brace rather than at @code{comment-column}. For full details see
-@ref{Comment Commands,,, ccmode, The CC Mode Manual}.
-
-@node Multi-Line Comments
-@subsection Multiple Lines of Comments
-
-@kindex C-M-j
-@kindex M-j
-@cindex blank lines in programs
-@findex comment-indent-new-line
-
- If you are typing a comment and wish to continue it on another line,
-you can use the command @kbd{C-M-j} or @kbd{M-j}
-(@code{comment-indent-new-line}). If @code{comment-multi-line}
-(@pxref{Options for Comments}) is non-@code{nil}, it moves to a new
-line within the comment. Otherwise it closes the comment and starts a
-new comment on a new line. When Auto Fill mode is on, going past the
-fill column while typing a comment causes the comment to be continued
-in just this fashion.
-
-@kindex C-c C-c (C mode)
-@findex comment-region
- To turn existing lines into comment lines, use the @kbd{M-x
-comment-region} command (or type @kbd{C-c C-c} in C-like modes). It
-adds comment delimiters to the lines that start in the region, thus
-commenting them out. With a negative argument, it does the
-opposite---it deletes comment delimiters from the lines in the region.
-
- With a positive argument, @code{comment-region} duplicates the last
-character of the comment start sequence it adds; the argument
-specifies how many copies of the character to insert. Thus, in Lisp
-mode, @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line.
-Duplicating the comment delimiter is a way of calling attention to the
-comment. It can also affect how the comment is aligned or indented.
-In Lisp, for proper indentation, you should use an argument of two or
-three, if between defuns; if within a defun, it must be three.
-
- You can configure C Mode such that when you type a @samp{/} at the
-start of a line in a multi-line block comment, this closes the
-comment. Enable the @code{comment-close-slash} clean-up for this.
-@xref{Clean-ups,,, ccmode, The CC Mode Manual}.
-
-@node Options for Comments
-@subsection Options Controlling Comments
-
-@vindex comment-column
-@kindex C-x ;
-@findex comment-set-column
- The @dfn{comment column}, the column at which Emacs tries to place
-comments, is stored in the variable @code{comment-column}. You can
-set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
-(@code{comment-set-column}) sets the comment column to the column
-point is at. @kbd{C-u C-x ;} sets the comment column to match the
-last comment before point in the buffer, and then does a @kbd{M-;} to
-align the current line's comment under the previous one.
-
- The variable @code{comment-column} is per-buffer: setting the variable
-in the normal fashion affects only the current buffer, but there is a
-default value which you can change with @code{setq-default}.
-@xref{Locals}. Many major modes initialize this variable for the
-current buffer.
-
-@vindex comment-start-skip
- The comment commands recognize comments based on the regular
-expression that is the value of the variable @code{comment-start-skip}.
-Make sure this regexp does not match the null string. It may match more
-than the comment starting delimiter in the strictest sense of the word;
-for example, in C mode the value of the variable is
-@c This stops M-q from breaking the line inside that @code.
-@code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces
-after the @samp{/*} itself, and accepts C++ style comments also.
-(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
-the string, which is needed to deny the first star its special meaning
-in regexp syntax. @xref{Regexp Backslash}.)
-
-@vindex comment-start
-@vindex comment-end
- When a comment command makes a new comment, it inserts the value of
-@code{comment-start} to begin it. The value of @code{comment-end} is
-inserted after point, so that it will follow the text that you will
-insert into the comment. When @code{comment-end} is non-empty, it
-should start with a space. For example, in C mode,
-@code{comment-start} has the value @w{@code{"/* "}} and
-@code{comment-end} has the value @w{@code{" */"}}.
-
-@vindex comment-padding
- The variable @code{comment-padding} specifies how many spaces
-@code{comment-region} should insert on each line between the comment
-delimiter and the line's original text. The default is 1, to insert
-one space. @code{nil} means 0. Alternatively, @code{comment-padding}
-can hold the actual string to insert.
-
-@vindex comment-multi-line
- The variable @code{comment-multi-line} controls how @kbd{C-M-j}
-(@code{indent-new-comment-line}) behaves when used inside a comment.
-Specifically, when @code{comment-multi-line} is @code{nil}, the
-command inserts a comment terminator, begins a new line, and finally
-inserts a comment starter. Otherwise it does not insert the
-terminator and starter, so it effectively continues the current
-comment across multiple lines. In languages that allow multi-line
-comments, the choice of value for this variable is a matter of taste.
-The default for this variable depends on the major mode.
-
-@vindex comment-indent-function
- The variable @code{comment-indent-function} should contain a function
-that will be called to compute the alignment for a newly inserted
-comment or for aligning an existing comment. It is set differently by
-various major modes. The function is called with no arguments, but with
-point at the beginning of the comment, or at the end of a line if a new
-comment is to be inserted. It should return the column in which the
-comment ought to start. For example, in Lisp mode, the indent hook
-function bases its decision on how many semicolons begin an existing
-comment, and on the code in the preceding lines.
-
-@node Documentation
-@section Documentation Lookup
-
- Emacs provides several features you can use to look up the
-documentation of functions, variables and commands that you plan to
-use in your program.
-
-@menu
-* Info Lookup:: Looking up library functions and commands
- in Info files.
-* Man Page:: Looking up man pages of library functions and commands.
-* Lisp Doc:: Looking up Emacs Lisp functions, etc.
-@end menu
-
-@node Info Lookup
-@subsection Info Documentation Lookup
-
-@findex info-lookup-symbol
-@findex info-lookup-file
-@kindex C-h S
- For many major modes, that apply to languages that have
-documentation in Info, you can use @kbd{C-h S}
-(@code{info-lookup-symbol}) to view the Info documentation for a
-symbol used in the program. You specify the symbol with the
-minibuffer; the default is the symbol appearing in the buffer at
-point. For example, in C mode this looks for the symbol in the C
-Library Manual. The command only works if the appropriate manual's
-Info files are installed.
-
- The major mode determines where to look for documentation for the
-symbol---which Info files to look in, and which indices to search.
-You can also use @kbd{M-x info-lookup-file} to look for documentation
-for a file name.
-
- If you use @kbd{C-h S} in a major mode that does not support it,
-it asks you to specify the ``symbol help mode.'' You should enter
-a command such as @code{c-mode} that would select a major
-mode which @kbd{C-h S} does support.
-
-@node Man Page
-@subsection Man Page Lookup
-
-@cindex manual page
- On Unix, the main form of on-line documentation was the @dfn{manual
-page} or @dfn{man page}. In the GNU operating system, we aim to
-replace man pages with better-organized manuals that you can browse
-with Info (@pxref{Misc Help}). This process is not finished, so it is
-still useful to read manual pages.
-
-@findex manual-entry
- You can read the man page for an operating system command, library
-function, or system call, with the @kbd{M-x man} command. It
-runs the @code{man} program to format the man page; if the system
-permits, it runs @code{man} asynchronously, so that you can keep on
-editing while the page is being formatted. (On MS-DOS and MS-Windows
-3, you cannot edit while Emacs waits for @code{man} to finish.) The
-result goes in a buffer named @samp{*Man @var{topic}*}. These buffers
-use a special major mode, Man mode, that facilitates scrolling and
-jumping to other manual pages. For details, type @kbd{C-h m} while in
-a man page buffer.
-
-@cindex sections of manual pages
- Each man page belongs to one of ten or more @dfn{sections}, each
-named by a digit or by a digit and a letter. Sometimes there are
-multiple man pages with the same name in different sections. To read
-a man page from a specific section, type
-@samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}}
-when @kbd{M-x manual-entry} prompts for the topic. For example, to
-read the man page for the C library function @code{chmod} (as opposed
-to a command of the same name), type @kbd{M-x manual-entry @key{RET}
-chmod(2) @key{RET}}. (@code{chmod} is a system call, so it is in
-section @samp{2}.)
-
-@vindex Man-switches
- If you do not specify a section, the results depend on how the
-@code{man} program works on your system. Some of them display only
-the first man page they find. Others display all man pages that have
-the specified name, so you can move between them with the @kbd{M-n}
-and @kbd{M-p} keys@footnote{On some systems, the @code{man} program
-accepts a @samp{-a} command-line option which tells it to display all
-the man pages for the specified topic. If you want this behavior, you
-can add this option to the value of the variable @code{Man-switches}.}.
-The mode line shows how many manual pages are present in the Man buffer.
-
-@vindex Man-fontify-manpage-flag
- By default, Emacs highlights the text in man pages. For a long man
-page, highlighting can take substantial time. You can turn off
-highlighting of man pages by setting the variable
-@code{Man-fontify-manpage-flag} to @code{nil}.
-
-@findex Man-fontify-manpage
- If you insert the text of a man page into an Emacs buffer in some
-other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
-perform the same conversions that @kbd{M-x manual-entry} does.
-
-@findex woman
-@cindex manual pages, on MS-DOS/MS-Windows
- An alternative way of reading manual pages is the @kbd{M-x woman}
-command@footnote{The name of the command, @code{woman}, is an acronym
-for ``w/o (without) man,'' since it doesn't use the @code{man}
-program.}. Unlike @kbd{M-x man}, it does not run any external
-programs to format and display the man pages; instead it does the job
-in Emacs Lisp, so it works on systems such as MS-Windows, where the
-@code{man} program (and other programs it uses) are not generally
-available.
-
- @kbd{M-x woman} prompts for a name of a manual page, and provides
-completion based on the list of manual pages that are installed on
-your machine; the list of available manual pages is computed
-automatically the first time you invoke @code{woman}. The word at
-point in the current buffer is used to suggest the default for the
-name the manual page.
-
- With a numeric argument, @kbd{M-x woman} recomputes the list of the
-manual pages used for completion. This is useful if you add or delete
-manual pages.
-
- If you type a name of a manual page and @kbd{M-x woman} finds that
-several manual pages by the same name exist in different sections, it
-pops up a window with possible candidates asking you to choose one of
-them.
-
- For more information about setting up and using @kbd{M-x woman}, see
-@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan
-Manual}.
-
-@node Lisp Doc
-@subsection Emacs Lisp Documentation Lookup
-
- As you edit Lisp code to be run in Emacs, you can use the commands
-@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v}
-(@code{describe-variable}) to view documentation of functions and
-variables that you want to use. These commands use the minibuffer to
-read the name of a function or variable to document, and display the
-documentation in a window. Their default arguments are based on the
-code in the neighborhood of point. For @kbd{C-h f}, the default is
-the function called in the innermost list containing point. @kbd{C-h
-v} uses the symbol name around or adjacent to point as its default.
-
-@cindex Eldoc mode
-@findex eldoc-mode
- A more automatic but less powerful method is Eldoc mode. This minor
-mode constantly displays in the echo area the argument list for the
-function being called at point. (In other words, it finds the
-function call that point is contained in, and displays the argument
-list of that function.) If point is over a documented variable, it
-shows the first line of the variable's docstring. Eldoc mode applies
-in Emacs Lisp and Lisp Interaction modes, and perhaps a few others
-that provide special support for looking up doc strings. Use the
-command @kbd{M-x eldoc-mode} to enable or disable this feature.
-
-@node Hideshow
-@section Hideshow minor mode
-
-@findex hs-minor-mode
- Hideshow minor mode provides selective display of portions of a
-program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode}
-to enable or disable this mode, or add @code{hs-minor-mode} to the
-mode hook for certain major modes in order to enable it automatically
-for those modes.
-
- Just what constitutes a block depends on the major mode. In C mode
-or C++ mode, they are delimited by braces, while in Lisp mode and
-similar modes they are delimited by parentheses. Multi-line comments
-also count as blocks.
-
-@findex hs-hide-all
-@findex hs-hide-block
-@findex hs-show-all
-@findex hs-show-block
-@findex hs-show-region
-@findex hs-hide-level
-@findex hs-minor-mode
-@kindex C-c @@ C-h
-@kindex C-c @@ C-s
-@kindex C-c @@ C-M-h
-@kindex C-c @@ C-M-s
-@kindex C-c @@ C-r
-@kindex C-c @@ C-l
-@kindex S-Mouse-2
-@table @kbd
-@item C-c @@ C-h
-Hide the current block (@code{hs-hide-block}).
-@item C-c @@ C-s
-Show the current block (@code{hs-show-block}).
-@item C-c @@ C-c
-Either hide or show the current block (@code{hs-toggle-hiding}).
-@item S-Mouse-2
-Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}).
-@item C-c @@ C-M-h
-Hide all top-level blocks (@code{hs-hide-all}).
-@item C-c @@ C-M-s
-Show everything in the buffer (@code{hs-show-all}).
-@item C-c @@ C-l
-Hide all blocks @var{n} levels below this block
-(@code{hs-hide-level}).
-@end table
-
-@vindex hs-hide-comments-when-hiding-all
-@vindex hs-isearch-open
-@vindex hs-special-modes-alist
- These variables exist for customizing Hideshow mode.
-
-@table @code
-@item hs-hide-comments-when-hiding-all
-Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.
-
-@item hs-isearch-open
-Specifies what kind of hidden blocks incremental search should make
-visible. The value should be one of these four symbols:
-
-@table @code
-@item code
-Open only code blocks.
-@item comment
-Open only comments.
-@item t
-Open both code blocks and comments.
-@item nil
-Open neither code blocks nor comments.
-@end table
-
-@item hs-special-modes-alist
-A list of elements, each specifying how to initialize Hideshow
-variables for one major mode. See the variable's documentation string
-for more information.
-@end table
-
-@node Symbol Completion
-@section Completion for Symbol Names
-@cindex completion (symbol names)
-
- In Emacs, completion is something you normally do in the minibuffer.
-But one kind of completion is available in all buffers: completion for
-symbol names.
-
-@kindex M-TAB
- The character @kbd{M-@key{TAB}} runs a command to complete the
-partial symbol before point against the set of meaningful symbol
-names. This command inserts at point any additional characters that
-it can determine from the partial name.
-
- If your window manager defines @kbd{M-@key{TAB}} to switch windows,
-you can type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i} instead.
-However, most window managers let you customize these shortcuts, and
-we recommend that you change any that get in the way of use of Emacs.
-
- If the partial name in the buffer has multiple possible completions
-that differ in the very next character, so that it is impossible to
-complete even one more character, @kbd{M-@key{TAB}} displays a list of
-all possible completions in another window.
-
-@cindex tags-based completion
-@cindex Info index completion
-@findex complete-symbol
- In most programming language major modes, @kbd{M-@key{TAB}} runs the
-command @code{complete-symbol}, which provides two kinds of completion.
-Normally it does completion based on a tags table (@pxref{Tags}); with a
-numeric argument (regardless of the value), it does completion based on
-the names listed in the Info file indexes for your language. Thus, to
-complete the name of a symbol defined in your own program, use
-@kbd{M-@key{TAB}} with no argument; to complete the name of a standard
-library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based
-completion works only if there is an Info file for the standard library
-functions of your language, and only if it is installed at your site.
-
-@cindex Lisp symbol completion
-@cindex completion (Lisp symbols)
-@findex lisp-complete-symbol
- In Emacs-Lisp mode, the name space for completion normally consists of
-nontrivial symbols present in Emacs---those that have function
-definitions, values or properties. However, if there is an
-open-parenthesis immediately before the beginning of the partial symbol,
-only symbols with function definitions are considered as completions.
-The command which implements this is @code{lisp-complete-symbol}.
-
- In Text mode and related modes, @kbd{M-@key{TAB}} completes words
-based on the spell-checker's dictionary. @xref{Spelling}.
-
-@node Glasses
-@section Glasses minor mode
-@cindex Glasses mode
-@cindex identifiers, making long ones readable
-@cindex StudlyCaps, making them readable
-@findex glasses-mode
-
- Glasses minor mode makes @samp{unreadableIdentifiersLikeThis}
-readable by altering the way they display. It knows two different
-ways to do this: by displaying underscores between a lower-case letter
-and the following capital letter, and by emboldening the capital
-letters. It does not alter the buffer text, only the way they
-display, so you can use it even on read-only buffers. You can use the
-command @kbd{M-x glasses-mode} to enable or disable the mode in the
-current buffer; you can also add @code{glasses-mode} to the mode hook
-of the programming language major modes in which you normally want
-to use Glasses mode.
-
-@node Misc for Programs
-@section Other Features Useful for Editing Programs
-
- A number of Emacs commands that aren't designed specifically for
-editing programs are useful for that nonetheless.
-
- The Emacs commands that operate on words, sentences and paragraphs
-are useful for editing code. Most symbols names contain words
-(@pxref{Words}); sentences can be found in strings and comments
-(@pxref{Sentences}). Paragraphs in the strict sense can be found in
-program code (in long comments), but the paragraph commands are useful
-in other places too, because programming language major modes define
-paragraphs to begin and end at blank lines (@pxref{Paragraphs}).
-Judicious use of blank lines to make the program clearer will also
-provide useful chunks of text for the paragraph commands to work on.
-Auto Fill mode, if enabled in a programming language major mode,
-indents the new lines which it creates.
-
- The selective display feature is useful for looking at the overall
-structure of a function (@pxref{Selective Display}). This feature
-hides the lines that are indented more than a specified amount.
-Programming modes often support Outline minor mode (@pxref{Outline
-Mode}). The Foldout package provides folding-editor features
-(@pxref{Foldout}).
-
- The ``automatic typing'' features may be useful for writing programs.
-@xref{Top,,Autotyping, autotype, Autotyping}.
-
-@node C Modes
-@section C and Related Modes
-@cindex C mode
-@cindex Java mode
-@cindex Pike mode
-@cindex IDL mode
-@cindex CORBA IDL mode
-@cindex Objective C mode
-@cindex C++ mode
-@cindex AWK mode
-@cindex mode, Java
-@cindex mode, C
-@cindex mode, C++
-@cindex mode, Objective C
-@cindex mode, CORBA IDL
-@cindex mode, Pike
-@cindex mode, AWK
-
- This section gives a brief description of the special features
-available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
-(These are called ``C mode and related modes.'') @xref{Top, , CC Mode,
-ccmode, CC Mode}, for a more extensive description of these modes
-and their special features.
-
-@menu
-* Motion in C:: Commands to move by C statements, etc.
-* Electric C:: Colon and other chars can automatically reindent.
-* Hungry Delete:: A more powerful DEL command.
-* Other C Commands:: Filling comments, viewing expansion of macros,
- and other neat features.
-@end menu
-
-@node Motion in C
-@subsection C Mode Motion Commands
-
- This section describes commands for moving point, in C mode and
-related modes.
-
-@table @code
-@item M-x c-beginning-of-defun
-@itemx M-x c-end-of-defun
-@findex c-beginning-of-defun
-@findex c-end-of-defun
-Move point to the beginning or end of the current function or
-top-level definition. These are found by searching for the least
-enclosing braces. (By contrast, @code{beginning-of-defun} and
-@code{end-of-defun} search for braces in column zero.) If you are
-editing code where the opening brace of a function isn't placed in
-column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to
-these commands. @xref{Moving by Defuns}.
-
-@item C-c C-u
-@kindex C-c C-u @r{(C mode)}
-@findex c-up-conditional
-Move point back to the containing preprocessor conditional, leaving the
-mark behind. A prefix argument acts as a repeat count. With a negative
-argument, move point forward to the end of the containing
-preprocessor conditional.
-
-@samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so
-the function will stop at a @samp{#elif} when going backward, but not
-when going forward.
-
-@item C-c C-p
-@kindex C-c C-p @r{(C mode)}
-@findex c-backward-conditional
-Move point back over a preprocessor conditional, leaving the mark
-behind. A prefix argument acts as a repeat count. With a negative
-argument, move forward.
-
-@item C-c C-n
-@kindex C-c C-n @r{(C mode)}
-@findex c-forward-conditional
-Move point forward across a preprocessor conditional, leaving the mark
-behind. A prefix argument acts as a repeat count. With a negative
-argument, move backward.
-
-@item M-a
-@kindex M-a (C mode)
-@findex c-beginning-of-statement
-Move point to the beginning of the innermost C statement
-(@code{c-beginning-of-statement}). If point is already at the beginning
-of a statement, move to the beginning of the preceding statement. With
-prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
-
-In comments or in strings which span more than one line, this command
-moves by sentences instead of statements.
-
-@item M-e
-@kindex M-e (C mode)
-@findex c-end-of-statement
-Move point to the end of the innermost C statement or sentence; like
-@kbd{M-a} except that it moves in the other direction
-(@code{c-end-of-statement}).
-@end table
-
-@node Electric C
-@subsection Electric C Characters
-
- In C mode and related modes, certain printing characters are
-@dfn{electric}---in addition to inserting themselves, they also
-reindent the current line, and optionally also insert newlines. The
-``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#},
-@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and
-@kbd{)}.
-
- You might find electric indentation inconvenient if you are editing
-chaotically indented code. If you are new to CC Mode, you might find
-it disconcerting. You can toggle electric action with the command
-@kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line
-after the mode name:
-
-@table @kbd
-@item C-c C-l
-@kindex C-c C-l @r{(C mode)}
-@findex c-toggle-electric-state
-Toggle electric action (@code{c-toggle-electric-state}). With a
-prefix argument, this command enables electric action if the argument
-is positive, disables it if it is negative.
-@end table
-
- Electric characters insert newlines only when, in addition to the
-electric state, the @dfn{auto-newline} feature is enabled (indicated
-by @samp{/la} in the mode line after the mode name). You can turn
-this feature on or off with the command @kbd{C-c C-a}:
-
-@table @kbd
-@item C-c C-a
-@kindex C-c C-a @r{(C mode)}
-@findex c-toggle-auto-newline
-Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a
-prefix argument, this command turns the auto-newline feature on if the
-argument is positive, and off if it is negative.
-@end table
-
- Usually the CC Mode style configures the exact circumstances in
-which Emacs inserts auto-newlines. You can also configure this
-directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}.
-
-@node Hungry Delete
-@subsection Hungry Delete Feature in C
-@cindex hungry deletion (C Mode)
-
- 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.
-@dfn{Whitespace} here includes tabs and newlines, but not comments or
-preprocessor commands.
-
-@table @kbd
-@item C-c C-@key{DEL}
-@itemx C-c @key{DEL}
-@findex c-hungry-delete-backwards
-@kindex C-c C-@key{DEL} (C Mode)
-@kindex C-c @key{DEL} (C Mode)
-@code{c-hungry-delete-backwards}---Delete the entire block of whitespace
-preceding point.
-
-@item C-c C-d
-@itemx C-c C-@key{DELETE}
-@itemx C-c @key{DELETE}
-@findex c-hungry-delete-forward
-@kindex C-c C-d (C Mode)
-@kindex C-c C-@key{DELETE} (C Mode)
-@kindex C-c @key{DELETE} (C Mode)
-@code{c-hungry-delete-forward}---Delete the entire block of whitespace
-following point.
-@end table
-
- As an alternative to the above commands, you can enable @dfn{hungry
-delete mode}. When this feature is enabled (indicated by @samp{/h} in
-the mode line after the mode name), a single @key{DEL} deletes all
-preceding whitespace, not just one space, and a single @kbd{C-c C-d}
-(but @emph{not} plain @key{DELETE}) deletes all following whitespace.
-
-@table @kbd
-@item M-x c-toggle-hungry-state
-@findex c-toggle-hungry-state
-Toggle the hungry-delete feature
-(@code{c-toggle-hungry-state})@footnote{This command had the binding
-@kbd{C-c C-d} in earlier versions of Emacs. @kbd{C-c C-d} is now
-bound to @code{c-hungry-delete-forward}.}. With a prefix argument,
-this command turns the hungry-delete feature on if the argument is
-positive, and off if it is negative.
-@end table
-
-@vindex c-hungry-delete-key
- The variable @code{c-hungry-delete-key} controls whether the
-hungry-delete feature is enabled.
-
-@node Other C Commands
-@subsection Other Commands for C Mode
-
-@table @kbd
-@item C-c C-w
-@itemx M-x c-subword-mode
-@findex c-subword-mode
-Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word
-commands recognize upper case letters in
-@samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by
-the flag @samp{/w} on the mode line after the mode name
-(e.g. @samp{C/law}). You can even use @kbd{M-x c-subword-mode} in
-non-CC Mode buffers.
-
-In the GNU project, we recommend using underscores to separate words
-within an identifier in C or C++, rather than using case distinctions.
-
-@item M-x c-context-line-break
-@findex c-context-line-break
-This command inserts a line break and indents the new line in a manner
-appropriate to the context. In normal code, it does the work of
-@kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it
-additionally inserts a @samp{\} at the line break, and within comments
-it's like @kbd{M-j} (@code{c-indent-new-comment-line}).
-
-@code{c-context-line-break} isn't bound to a key by default, but it
-needs a binding to be useful. The following code will bind it to
-@kbd{C-j}. We use @code{c-initialization-hook} here to make sure
-the keymap is loaded before we try to change it.
-
-@smallexample
-(defun my-bind-clb ()
- (define-key c-mode-base-map "\C-j" 'c-context-line-break))
-(add-hook 'c-initialization-hook 'my-bind-clb)
-@end smallexample
-
-@item C-M-h
-Put mark at the end of a function definition, and put point at the
-beginning (@code{c-mark-function}).
-
-@item M-q
-@kindex M-q @r{(C mode)}
-@findex c-fill-paragraph
-Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
-If any part of the current line is a comment or within a comment, this
-command fills the comment or the paragraph of it that point is in,
-preserving the comment indentation and comment delimiters.
-
-@item C-c C-e
-@cindex macro expansion in C
-@cindex expansion of C macros
-@findex c-macro-expand
-@kindex C-c C-e @r{(C mode)}
-Run the C preprocessor on the text in the region, and show the result,
-which includes the expansion of all the macro calls
-(@code{c-macro-expand}). The buffer text before the region is also
-included in preprocessing, for the sake of macros defined there, but the
-output from this part isn't shown.
-
-When you are debugging C code that uses macros, sometimes it is hard to
-figure out precisely how the macros expand. With this command, you
-don't have to figure it out; you can see the expansions.
-
-@item C-c C-\
-@findex c-backslash-region
-@kindex C-c C-\ @r{(C mode)}
-Insert or align @samp{\} characters at the ends of the lines of the
-region (@code{c-backslash-region}). This is useful after writing or
-editing a C macro definition.
-
-If a line already ends in @samp{\}, this command adjusts the amount of
-whitespace before it. Otherwise, it inserts a new @samp{\}. However,
-the last line in the region is treated specially; no @samp{\} is
-inserted on that line, and any @samp{\} there is deleted.
-
-@item M-x cpp-highlight-buffer
-@cindex preprocessor highlighting
-@findex cpp-highlight-buffer
-Highlight parts of the text according to its preprocessor conditionals.
-This command displays another buffer named @samp{*CPP Edit*}, which
-serves as a graphic menu for selecting how to display particular kinds
-of conditionals and their contents. After changing various settings,
-click on @samp{[A]pply these settings} (or go to that buffer and type
-@kbd{a}) to rehighlight the C mode buffer accordingly.
-
-@item C-c C-s
-@findex c-show-syntactic-information
-@kindex C-c C-s @r{(C mode)}
-Display the syntactic information about the current source line
-(@code{c-show-syntactic-information}). This information directs how
-the line is indented.
-
-@item M-x cwarn-mode
-@itemx M-x global-cwarn-mode
-@findex cwarn-mode
-@findex global-cwarn-mode
-@vindex global-cwarn-mode
-@cindex CWarn mode
-@cindex suspicious constructions in C, C++
-CWarn minor mode highlights certain suspicious C and C++ constructions:
-
-@itemize @bullet{}
-@item
-Assignments inside expressions.
-@item
-Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
-(except after a @samp{do @dots{} while} statement);
-@item
-C++ functions with reference parameters.
-@end itemize
-
-@noindent
-You can enable the mode for one buffer with the command @kbd{M-x
-cwarn-mode}, or for all suitable buffers with the command @kbd{M-x
-global-cwarn-mode} or by customizing the variable
-@code{global-cwarn-mode}. You must also enable Font Lock mode to make
-it work.
-
-@item M-x hide-ifdef-mode
-@findex hide-ifdef-mode
-@cindex Hide-ifdef mode
-Hide-ifdef minor mode hides selected code within @samp{#if} and
-@samp{#ifdef} preprocessor blocks. See the documentation string of
-@code{hide-ifdef-mode} for more information.
-
-@item M-x ff-find-related-file
-@cindex related files
-@findex ff-find-related-file
-@vindex ff-related-file-alist
-Find a file ``related'' in a special way to the file visited by the
-current buffer. Typically this will be the header file corresponding
-to a C/C++ source file, or vice versa. The variable
-@code{ff-related-file-alist} specifies how to compute related file
-names.
-@end table
-
-@node Asm Mode
-@section Asm Mode
-
-@cindex Asm mode
-@cindex assembler mode
-Asm mode is a major mode for editing files of assembler code. It
-defines these commands:
-
-@table @kbd
-@item @key{TAB}
-@code{tab-to-tab-stop}.
-@item C-j
-Insert a newline and then indent using @code{tab-to-tab-stop}.
-@item :
-Insert a colon and then remove the indentation from before the label
-preceding colon. Then do @code{tab-to-tab-stop}.
-@item ;
-Insert or align a comment.
-@end table
-
- The variable @code{asm-comment-char} specifies which character
-starts comments in assembler syntax.
-
-@ifnottex
-@include fortran-xtra.texi
-@end ifnottex
-
-@ignore
- arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Registers, Display, CUA Bindings, Top
-@chapter Registers
-@cindex registers
-
- Emacs @dfn{registers} are compartments where you can save text,
-rectangles, positions, and other things for later use. Once you save
-text or a rectangle in a register, you can copy it into the buffer
-once, or many times; you can move point to a position saved in a
-register once, or many times.
-
-@findex view-register
- Each register has a name, which consists of a single character. A
-register can store a number, a piece of text, a rectangle, a position,
-a window configuration, or a file name, but only one thing at any
-given time. Whatever you store in a register remains there until you
-store something else in that register. To see what a register @var{r}
-contains, use @kbd{M-x view-register}.
-
-@table @kbd
-@item M-x view-register @key{RET} @var{r}
-Display a description of what register @var{r} contains.
-@end table
-
- @dfn{Bookmarks} record files and positions in them, so you can
-return to those positions when you look at the file again.
-Bookmarks are similar enough in spirit to registers that they
-seem to belong in this chapter.
-
-@menu
-* Position: RegPos. Saving positions in registers.
-* Text: RegText. Saving text in registers.
-* Rectangle: RegRect. Saving rectangles in registers.
-* Configurations: RegConfig. Saving window configurations in registers.
-* Numbers: RegNumbers. Numbers in registers.
-* Files: RegFiles. File names in registers.
-* Bookmarks:: Bookmarks are like registers, but persistent.
-@end menu
-
-@node RegPos
-@section Saving Positions in Registers
-@cindex saving position in a register
-
- Saving a position records a place in a buffer so that you can move
-back there later. Moving to a saved position switches to that buffer
-and moves point to that place in it.
-
-@table @kbd
-@item C-x r @key{SPC} @var{r}
-Save position of point in register @var{r} (@code{point-to-register}).
-@item C-x r j @var{r}
-Jump to the position saved in register @var{r} (@code{jump-to-register}).
-@end table
-
-@kindex C-x r SPC
-@findex point-to-register
- To save the current position of point in a register, choose a name
-@var{r} and type @kbd{C-x r @key{SPC} @var{r}}. The register @var{r}
-retains the position thus saved until you store something else in that
-register.
-
-@kindex C-x r j
-@findex jump-to-register
- The command @kbd{C-x r j @var{r}} moves point to the position recorded
-in register @var{r}. The register is not affected; it continues to
-hold the same position. You can jump to the saved position any number
-of times.
-
- If you use @kbd{C-x r j} to go to a saved position, but the buffer it
-was saved from has been killed, @kbd{C-x r j} tries to create the buffer
-again by visiting the same file. Of course, this works only for buffers
-that were visiting files.
-
-@node RegText
-@section Saving Text in Registers
-@cindex saving text in a register
-
- When you want to insert a copy of the same piece of text several
-times, it may be inconvenient to yank it from the kill ring, since each
-subsequent kill moves that entry further down the ring. An alternative
-is to store the text in a register and later retrieve it.
-
-@table @kbd
-@item C-x r s @var{r}
-Copy region into register @var{r} (@code{copy-to-register}).
-@item C-x r i @var{r}
-Insert text from register @var{r} (@code{insert-register}).
-@item M-x append-to-register @key{RET} @var{r}
-Append region to text in register @var{r}.
-@item M-x prepend-to-register @key{RET} @var{r}
-Prepend region to text in register @var{r}.
-@end table
-
-@kindex C-x r s
-@kindex C-x r i
-@findex copy-to-register
-@findex insert-register
- @kbd{C-x r s @var{r}} stores a copy of the text of the region into
-the register named @var{r}. @kbd{C-u C-x r s @var{r}}, the same
-command with a numeric argument, deletes the text from the buffer as
-well; you can think of this as ``moving'' the region text into the register.
-
-@findex append-to-register
-@findex prepend-to-register
- @kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of
-the text in the region to the text already stored in the register
-named @var{r}. If invoked with a numeric argument, it deletes the
-region after appending it to the register. The command
-@code{prepend-to-register} is similar, except that it @emph{prepends}
-the region text to the text in the register, rather than
-@emph{appending} it.
-
- @kbd{C-x r i @var{r}} inserts in the buffer the text from register
-@var{r}. Normally it leaves point before the text and places the mark
-after, but with a numeric argument (@kbd{C-u}) it puts point after the
-text and the mark before.
-
-@node RegRect
-@section Saving Rectangles in Registers
-@cindex saving rectangle in a register
-
- A register can contain a rectangle instead of linear text. The
-rectangle is represented as a list of strings. @xref{Rectangles}, for
-basic information on how to specify a rectangle in the buffer.
-
-@table @kbd
-@findex copy-rectangle-to-register
-@kindex C-x r r
-@item C-x r r @var{r}
-Copy the region-rectangle into register @var{r}
-(@code{copy-rectangle-to-register}). With numeric argument, delete it as
-well.
-@item C-x r i @var{r}
-Insert the rectangle stored in register @var{r} (if it contains a
-rectangle) (@code{insert-register}).
-@end table
-
- The @kbd{C-x r i @var{r}} command inserts a text string if the
-register contains one, and inserts a rectangle if the register contains
-one.
-
- See also the command @code{sort-columns}, which you can think of
-as sorting a rectangle. @xref{Sorting}.
-
-@node RegConfig
-@section Saving Window Configurations in Registers
-@cindex saving window configuration in a register
-
-@findex window-configuration-to-register
-@findex frame-configuration-to-register
-@kindex C-x r w
-@kindex C-x r f
- You can save the window configuration of the selected frame in a
-register, or even the configuration of all windows in all frames, and
-restore the configuration later.
-
-@table @kbd
-@item C-x r w @var{r}
-Save the state of the selected frame's windows in register @var{r}
-(@code{window-configuration-to-register}).
-@item C-x r f @var{r}
-Save the state of all frames, including all their windows, in register
-@var{r} (@code{frame-configuration-to-register}).
-@end table
-
- Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
-This is the same command used to restore a cursor position. When you
-restore a frame configuration, any existing frames not included in the
-configuration become invisible. If you wish to delete these frames
-instead, use @kbd{C-u C-x r j @var{r}}.
-
-@node RegNumbers
-@section Keeping Numbers in Registers
-@cindex saving number in a register
-
- There are commands to store a number in a register, to insert
-the number in the buffer in decimal, and to increment it. These commands
-can be useful in keyboard macros (@pxref{Keyboard Macros}).
-
-@table @kbd
-@item C-u @var{number} C-x r n @var{r}
-@kindex C-x r n
-@findex number-to-register
-Store @var{number} into register @var{r} (@code{number-to-register}).
-@item C-u @var{number} C-x r + @var{r}
-@kindex C-x r +
-@findex increment-register
-Increment the number in register @var{r} by @var{number}
-(@code{increment-register}).
-@item C-x r i @var{r}
-Insert the number from register @var{r} into the buffer.
-@end table
-
- @kbd{C-x r i} is the same command used to insert any other sort of
-register contents into the buffer. @kbd{C-x r +} with no numeric
-argument increments the register value by 1; @kbd{C-x r n} with no
-numeric argument stores zero in the register.
-
-@node RegFiles
-@section Keeping File Names in Registers
-@cindex saving file name in a register
-
- If you visit certain file names frequently, you can visit them more
-conveniently if you put their names in registers. Here's the Lisp code
-used to put a file name in a register:
-
-@smallexample
-(set-register ?@var{r} '(file . @var{name}))
-@end smallexample
-
-@need 3000
-@noindent
-For example,
-
-@smallexample
-(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))
-@end smallexample
-
-@noindent
-puts the file name shown in register @samp{z}.
-
- To visit the file whose name is in register @var{r}, type @kbd{C-x r j
-@var{r}}. (This is the same command used to jump to a position or
-restore a frame configuration.)
-
-@node Bookmarks
-@section Bookmarks
-@cindex bookmarks
-
- @dfn{Bookmarks} are somewhat like registers in that they record
-positions you can jump to. Unlike registers, they have long names, and
-they persist automatically from one Emacs session to the next. The
-prototypical use of bookmarks is to record ``where you were reading'' in
-various files.
-
-@table @kbd
-@item C-x r m @key{RET}
-Set the bookmark for the visited file, at point.
-
-@item C-x r m @var{bookmark} @key{RET}
-@findex bookmark-set
-Set the bookmark named @var{bookmark} at point (@code{bookmark-set}).
-
-@item C-x r b @var{bookmark} @key{RET}
-@findex bookmark-jump
-Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}).
-
-@item C-x r l
-@findex list-bookmarks
-List all bookmarks (@code{list-bookmarks}).
-
-@item M-x bookmark-save
-@findex bookmark-save
-Save all the current bookmark values in the default bookmark file.
-@end table
-
-@kindex C-x r m
-@findex bookmark-set
-@kindex C-x r b
-@findex bookmark-jump
- The prototypical use for bookmarks is to record one current position
-in each of several files. So the command @kbd{C-x r m}, which sets a
-bookmark, uses the visited file name as the default for the bookmark
-name. If you name each bookmark after the file it points to, then you
-can conveniently revisit any of those files with @kbd{C-x r b}, and move
-to the position of the bookmark at the same time.
-
-@kindex C-x r l
- To display a list of all your bookmarks in a separate buffer, type
-@kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer,
-you can use it to edit your bookmark definitions or annotate the
-bookmarks. Type @kbd{C-h m} in the bookmark buffer for more
-information about its special editing commands.
-
- When you kill Emacs, Emacs offers to save your bookmark values in your
-default bookmark file, @file{~/.emacs.bmk}, if you have changed any
-bookmark values. You can also save the bookmarks at any time with the
-@kbd{M-x bookmark-save} command. The bookmark commands load your
-default bookmark file automatically. This saving and loading is how
-bookmarks persist from one Emacs session to the next.
-
-@vindex bookmark-save-flag
- If you set the variable @code{bookmark-save-flag} to 1, then each
-command that sets a bookmark will also save your bookmarks; this way,
-you don't lose any bookmark values even if Emacs crashes. (The value,
-if a number, says how many bookmark modifications should go by between
-saving.)
-
-@vindex bookmark-search-size
- Bookmark position values are saved with surrounding context, so that
-@code{bookmark-jump} can find the proper position even if the file is
-modified slightly. The variable @code{bookmark-search-size} says how
-many characters of context to record on each side of the bookmark's
-position.
-
- Here are some additional commands for working with bookmarks:
-
-@table @kbd
-@item M-x bookmark-load @key{RET} @var{filename} @key{RET}
-@findex bookmark-load
-Load a file named @var{filename} that contains a list of bookmark
-values. You can use this command, as well as @code{bookmark-write}, to
-work with other files of bookmark values in addition to your default
-bookmark file.
-
-@item M-x bookmark-write @key{RET} @var{filename} @key{RET}
-@findex bookmark-write
-Save all the current bookmark values in the file @var{filename}.
-
-@item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET}
-@findex bookmark-delete
-Delete the bookmark named @var{bookmark}.
-
-@item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET}
-@findex bookmark-insert-location
-Insert in the buffer the name of the file that bookmark @var{bookmark}
-points to.
-
-@item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET}
-@findex bookmark-insert
-Insert in the buffer the @emph{contents} of the file that bookmark
-@var{bookmark} points to.
-@end table
-
-@ignore
- arch-tag: b00af991-ebc3-4b3a-8e82-a3ac81ff2e64
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Rmail, Dired, Sending Mail, Top
-@chapter Reading Mail with Rmail
-@cindex Rmail
-@cindex reading mail
-@findex rmail
-@findex rmail-mode
-@vindex rmail-mode-hook
-
- Rmail is an Emacs subsystem for reading and disposing of mail that
-you receive. Rmail stores mail messages in files called Rmail files
-which use a special format. Reading the message in an Rmail file is
-done in a special major mode, Rmail mode, which redefines most letters
-to run commands for managing mail.
-@menu
-* Basic: Rmail Basics. Basic concepts of Rmail, and simple use.
-* Scroll: Rmail Scrolling. Scrolling through a message.
-* Motion: Rmail Motion. Moving to another message.
-* Deletion: Rmail Deletion. Deleting and expunging messages.
-* Inbox: Rmail Inbox. How mail gets into the Rmail file.
-* Files: Rmail Files. Using multiple Rmail files.
-* Output: Rmail Output. Copying message out to files.
-* Labels: Rmail Labels. Classifying messages by labeling them.
-* Attrs: Rmail Attributes. Certain standard labels, called attributes.
-* Reply: Rmail Reply. Sending replies to messages you are viewing.
-* Summary: Rmail Summary. Summaries show brief info on many messages.
-* Sort: Rmail Sorting. Sorting messages in Rmail.
-* Display: Rmail Display. How Rmail displays a message; customization.
-* Coding: Rmail Coding. How Rmail handles decoding character sets.
-* Editing: Rmail Editing. Editing message text and headers in Rmail.
-* Digest: Rmail Digest. Extracting the messages from a digest message.
-* Out of Rmail:: Converting an Rmail file to mailbox format.
-* Rot13: Rmail Rot13. Reading messages encoded in the rot13 code.
-* Movemail:: More details of fetching new mail.
-* Remote Mailboxes:: Retrieving Mail from Remote Mailboxes.
-* Other Mailbox Formats:: Retrieving Mail from Local Mailboxes in
- Various Formats
-@end menu
-
-@node Rmail Basics
-@section Basic Concepts of Rmail
-
-@cindex primary Rmail file
-@vindex rmail-file-name
- Using Rmail in the simplest fashion, you have one Rmail file
-@file{~/RMAIL} in which all of your mail is saved. It is called your
-@dfn{primary Rmail file}. The command @kbd{M-x rmail} reads your primary
-Rmail file, merges new mail in from your inboxes, displays the first
-message you haven't read yet, and lets you begin reading. The variable
-@code{rmail-file-name} specifies the name of the primary Rmail file.
-
- Rmail uses narrowing to hide all but one message in the Rmail file.
-The message that is shown is called the @dfn{current message}. Rmail
-mode's special commands can do such things as delete the current
-message, copy it into another file, send a reply, or move to another
-message. You can also create multiple Rmail files and use Rmail to move
-messages between them.
-
-@cindex message number
- Within the Rmail file, messages are normally arranged sequentially in
-order of receipt; you can specify other ways to sort them. Messages are
-identified by consecutive integers which are their @dfn{message numbers}.
-The number of the current message is displayed in Rmail's mode line,
-followed by the total number of messages in the file. You can move to
-a message by specifying its message number with the @kbd{j} key
-(@pxref{Rmail Motion}).
-
-@kindex s @r{(Rmail)}
-@findex rmail-expunge-and-save
- Following the usual conventions of Emacs, changes in an Rmail file
-become permanent only when you save the file. You can save it with
-@kbd{s} (@code{rmail-expunge-and-save}), which also expunges deleted
-messages from the file first (@pxref{Rmail Deletion}). To save the
-file without expunging, use @kbd{C-x C-s}. Rmail also saves the Rmail
-file after merging new mail from an inbox file (@pxref{Rmail Inbox}).
-
-@kindex q @r{(Rmail)}
-@findex rmail-quit
-@kindex b @r{(Rmail)}
-@findex rmail-bury
- You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges
-and saves the Rmail file, then buries the Rmail buffer as well as its
-summary buffer, if present (@pxref{Rmail Summary}). But there is no
-need to ``exit'' formally. If you switch from Rmail to editing in
-other buffers, and never switch back, you have exited. Just make sure
-to save the Rmail file eventually (like any other file you have
-changed). @kbd{C-x s} is a suitable way to do this (@pxref{Save
-Commands}). The Rmail command @kbd{b}, @code{rmail-bury}, buries the
-Rmail buffer and its summary buffer without expunging and saving the
-Rmail file.
-
-@node Rmail Scrolling
-@section Scrolling Within a Message
-
- When Rmail displays a message that does not fit on the screen, you
-must scroll through it to read the rest. You could do this with
-@kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so
-frequent that it deserves to be easier.
-
-@table @kbd
-@item @key{SPC}
-Scroll forward (@code{scroll-up}).
-@item @key{DEL}
-Scroll backward (@code{scroll-down}).
-@item .
-Scroll to start of message (@code{rmail-beginning-of-message}).
-@item /
-Scroll to end of message (@code{rmail-end-of-message}).
-@end table
-
-@kindex SPC @r{(Rmail)}
-@kindex DEL @r{(Rmail)}
- Since the most common thing to do while reading a message is to scroll
-through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of
-@kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down})
-
-@kindex . @r{(Rmail)}
-@kindex / @r{(Rmail)}
-@findex rmail-beginning-of-message
-@findex rmail-end-of-message
- The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the
-beginning of the selected message. This is not quite the same as @kbd{M-<}:
-for one thing, it does not set the mark; for another, it resets the buffer
-boundaries to the current message if you have changed them. Similarly,
-the command @kbd{/} (@code{rmail-end-of-message}) scrolls forward to the end
-of the selected message.
-
-@node Rmail Motion
-@section Moving Among Messages
-
- The most basic thing to do with a message is to read it. The way to
-do this in Rmail is to make the message current. The usual practice is
-to move sequentially through the file, since this is the order of
-receipt of messages. When you enter Rmail, you are positioned at the
-first message that you have not yet made current (that is, the first one
-that has the @samp{unseen} attribute; @pxref{Rmail Attributes}). Move
-forward to see the other new messages; move backward to re-examine old
-messages.
-
-@table @kbd
-@item n
-Move to the next nondeleted message, skipping any intervening deleted
-messages (@code{rmail-next-undeleted-message}).
-@item p
-Move to the previous nondeleted message
-(@code{rmail-previous-undeleted-message}).
-@item M-n
-Move to the next message, including deleted messages
-(@code{rmail-next-message}).
-@item M-p
-Move to the previous message, including deleted messages
-(@code{rmail-previous-message}).
-@item j
-Move to the first message. With argument @var{n}, move to
-message number @var{n} (@code{rmail-show-message}).
-@item >
-Move to the last message (@code{rmail-last-message}).
-@item <
-Move to the first message (@code{rmail-first-message}).
-
-@item M-s @var{regexp} @key{RET}
-Move to the next message containing a match for @var{regexp}
-(@code{rmail-search}).
-
-@item - M-s @var{regexp} @key{RET}
-Move to the previous message containing a match for @var{regexp}.
-@end table
-
-@kindex n @r{(Rmail)}
-@kindex p @r{(Rmail)}
-@kindex M-n @r{(Rmail)}
-@kindex M-p @r{(Rmail)}
-@findex rmail-next-undeleted-message
-@findex rmail-previous-undeleted-message
-@findex rmail-next-message
-@findex rmail-previous-message
- @kbd{n} and @kbd{p} are the usual way of moving among messages in
-Rmail. They move through the messages sequentially, but skip over
-deleted messages, which is usually what you want to do. Their command
-definitions are named @code{rmail-next-undeleted-message} and
-@code{rmail-previous-undeleted-message}. If you do not want to skip
-deleted messages---for example, if you want to move to a message to
-undelete it---use the variants @kbd{M-n} and @kbd{M-p}
-(@code{rmail-next-message} and @code{rmail-previous-message}). A
-numeric argument to any of these commands serves as a repeat
-count.
-
- In Rmail, you can specify a numeric argument by typing just the
-digits. You don't need to type @kbd{C-u} first.
-
-@kindex M-s @r{(Rmail)}
-@findex rmail-search
-@cindex searching in Rmail
- The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of
-search. The usual incremental search command @kbd{C-s} works in Rmail,
-but it searches only within the current message. The purpose of
-@kbd{M-s} is to search for another message. It reads a regular
-expression (@pxref{Regexps}) nonincrementally, then searches starting at
-the beginning of the following message for a match. It then selects
-that message. If @var{regexp} is empty, @kbd{M-s} reuses the regexp
-used the previous time.
-
- To search backward in the file for another message, give @kbd{M-s} a
-negative argument. In Rmail you can do this with @kbd{- M-s}.
-
- It is also possible to search for a message based on labels.
-@xref{Rmail Labels}.
-
-@kindex j @r{(Rmail)}
-@kindex > @r{(Rmail)}
-@kindex < @r{(Rmail)}
-@findex rmail-show-message
-@findex rmail-last-message
-@findex rmail-first-message
- To move to a message specified by absolute message number, use @kbd{j}
-(@code{rmail-show-message}) with the message number as argument. With
-no argument, @kbd{j} selects the first message. @kbd{<}
-(@code{rmail-first-message}) also selects the first message. @kbd{>}
-(@code{rmail-last-message}) selects the last message.
-
-@node Rmail Deletion
-@section Deleting Messages
-
-@cindex deletion (Rmail)
- When you no longer need to keep a message, you can @dfn{delete} it. This
-flags it as ignorable, and some Rmail commands pretend it is no longer
-present; but it still has its place in the Rmail file, and still has its
-message number.
-
-@cindex expunging (Rmail)
- @dfn{Expunging} the Rmail file actually removes the deleted messages.
-The remaining messages are renumbered consecutively. Expunging is the only
-action that changes the message number of any message, except for
-undigestifying (@pxref{Rmail Digest}).
-
-@table @kbd
-@item d
-Delete the current message, and move to the next nondeleted message
-(@code{rmail-delete-forward}).
-@item C-d
-Delete the current message, and move to the previous nondeleted
-message (@code{rmail-delete-backward}).
-@item u
-Undelete the current message, or move back to a deleted message and
-undelete it (@code{rmail-undelete-previous-message}).
-@item x
-Expunge the Rmail file (@code{rmail-expunge}).
-@end table
-
-@kindex d @r{(Rmail)}
-@kindex C-d @r{(Rmail)}
-@findex rmail-delete-forward
-@findex rmail-delete-backward
- There are two Rmail commands for deleting messages. Both delete the
-current message and select another message. @kbd{d}
-(@code{rmail-delete-forward}) moves to the following message, skipping
-messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward})
-moves to the previous nondeleted message. If there is no nondeleted
-message to move to in the specified direction, the message that was just
-deleted remains current. @kbd{d} with a numeric argument is
-equivalent to @kbd{C-d}.
-
-@vindex rmail-delete-message-hook
- Whenever Rmail deletes a message, it runs the hook
-@code{rmail-delete-message-hook}. When the hook functions are invoked,
-the message has been marked deleted, but it is still the current message
-in the Rmail buffer.
-
-@cindex undeletion (Rmail)
-@kindex x @r{(Rmail)}
-@findex rmail-expunge
-@kindex u @r{(Rmail)}
-@findex rmail-undelete-previous-message
- To make all the deleted messages finally vanish from the Rmail file,
-type @kbd{x} (@code{rmail-expunge}). Until you do this, you can still
-@dfn{undelete} the deleted messages. The undeletion command, @kbd{u}
-(@code{rmail-undelete-previous-message}), is designed to cancel the
-effect of a @kbd{d} command in most cases. It undeletes the current
-message if the current message is deleted. Otherwise it moves backward
-to previous messages until a deleted message is found, and undeletes
-that message.
-
- You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u}
-moves back to and undeletes the message that the @kbd{d} deleted. But
-this does not work when the @kbd{d} skips a few already-deleted messages
-that follow the message being deleted; then the @kbd{u} command
-undeletes the last of the messages that were skipped. There is no clean
-way to avoid this problem. However, by repeating the @kbd{u} command,
-you can eventually get back to the message that you intend to
-undelete. You can also select a particular deleted message with
-the @kbd{M-p} command, then type @kbd{u} to undelete it.
-
- A deleted message has the @samp{deleted} attribute, and as a result
-@samp{deleted} appears in the mode line when the current message is
-deleted. In fact, deleting or undeleting a message is nothing more than
-adding or removing this attribute. @xref{Rmail Attributes}.
-
-@node Rmail Inbox
-@section Rmail Files and Inboxes
-@cindex inbox file
-
- When you receive mail locally, the operating system places incoming
-mail for you in a file that we call your @dfn{inbox}. When you start
-up Rmail, it runs a C program called @code{movemail} to copy the new
-messages from your local inbox into your primary Rmail file, which
-also contains other messages saved from previous Rmail sessions. It
-is in this file that you actually read the mail with Rmail. This
-operation is called @dfn{getting new mail}. You can get new mail at
-any time in Rmail by typing @kbd{g}.
-
-@vindex rmail-primary-inbox-list
-@cindex @env{MAIL} environment variable
- The variable @code{rmail-primary-inbox-list} contains a list of the
-files which are inboxes for your primary Rmail file. If you don't set
-this variable explicitly, it is initialized from the @env{MAIL}
-environment variable, or, as a last resort, set to @code{nil}, which
-means to use the default inbox. The default inbox file depends on
-your operating system; often it is @file{/var/mail/@var{username}},
-@file{/usr/spool/mail/@var{username}}, or
-@file{/usr/mail/@var{username}}.
-
- You can specify the inbox file(s) for any Rmail file with the
-command @code{set-rmail-inbox-list}; see @ref{Rmail Files}.
-
- There are two reasons for having separate Rmail files and inboxes.
-
-@enumerate
-@item
-The inbox file format varies between operating systems and according to
-the other mail software in use. Only one part of Rmail needs to know
-about the alternatives, and it need only understand how to convert all
-of them to Rmail's own format.
-
-@item
-It is very cumbersome to access an inbox file without danger of losing
-mail, because it is necessary to interlock with mail delivery.
-Moreover, different operating systems use different interlocking
-techniques. The strategy of moving mail out of the inbox once and for
-all into a separate Rmail file avoids the need for interlocking in all
-the rest of Rmail, since only Rmail operates on the Rmail file.
-@end enumerate
-
- Rmail was written to use Babyl format as its internal format. Since
-then, we have recognized that the usual inbox format on Unix and GNU
-systems is adequate for the job, and we plan to change Rmail to use that
-as its internal format. However, the Rmail file will still be separate
-from the inbox file, even when their format is the same.
-
-@vindex rmail-preserve-inbox
- When getting new mail, Rmail first copies the new mail from the
-inbox file to the Rmail file; then it saves the Rmail file; then it
-clears out the inbox file. This way, a system crash may cause
-duplication of mail between the inbox and the Rmail file, but cannot
-lose mail. If @code{rmail-preserve-inbox} is non-@code{nil}, then
-Rmail does not clear out the inbox file when it gets new mail. You
-may wish to set this, for example, on a portable computer you use to
-check your mail via POP while traveling, so that your mail will remain
-on the server and you can save it later on your workstation.
-
- In some cases, Rmail copies the new mail from the inbox file
-indirectly. First it runs the @code{movemail} program to move the mail
-from the inbox to an intermediate file called
-@file{~/.newmail-@var{inboxname}}. Then Rmail merges the new mail from
-that file, saves the Rmail file, and only then deletes the intermediate
-file. If there is a crash at the wrong time, this file continues to
-exist, and Rmail will use it again the next time it gets new mail from
-that inbox.
-
- If Rmail is unable to convert the data in
-@file{~/.newmail-@var{inboxname}} into Babyl format, it renames the file
-to @file{~/RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the
-name unique) so that Rmail will not have trouble with the data again.
-You should look at the file, find whatever message confuses Rmail
-(probably one that includes the control-underscore character, octal code
-037), and delete it. Then you can use @kbd{1 g} to get new mail from
-the corrected file.
-
-@node Rmail Files
-@section Multiple Rmail Files
-
- Rmail operates by default on your @dfn{primary Rmail file}, which is named
-@file{~/RMAIL} and receives your incoming mail from your system inbox file.
-But you can also have other Rmail files and edit them with Rmail. These
-files can receive mail through their own inboxes, or you can move messages
-into them with explicit Rmail commands (@pxref{Rmail Output}).
-
-@table @kbd
-@item i @var{file} @key{RET}
-Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}).
-
-@item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET}
-Specify inbox file names for current Rmail file to get mail from.
-
-@item g
-Merge new mail from current Rmail file's inboxes
-(@code{rmail-get-new-mail}).
-
-@item C-u g @var{file} @key{RET}
-Merge new mail from inbox file @var{file}.
-@end table
-
-@kindex i @r{(Rmail)}
-@findex rmail-input
- To run Rmail on a file other than your primary Rmail file, you can use
-the @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file
-in Rmail mode. You can use @kbd{M-x rmail-input} even when not in
-Rmail, but it is easier to type @kbd{C-u M-x rmail}, which does the
-same thing.
-
- The file you read with @kbd{i} should normally be a valid Rmail file.
-If it is not, Rmail tries to decompose it into a stream of messages in
-various known formats. If it succeeds, it converts the whole file to an
-Rmail file. If you specify a file name that doesn't exist, @kbd{i}
-initializes a new buffer for creating a new Rmail file.
-
-@vindex rmail-secondary-file-directory
-@vindex rmail-secondary-file-regexp
- You can also select an Rmail file from a menu. In the Classify menu,
-choose the Input Rmail File item; then choose the Rmail file you want.
-The variables @code{rmail-secondary-file-directory} and
-@code{rmail-secondary-file-regexp} specify which files to offer in the
-menu: the first variable says which directory to find them in; the
-second says which files in that directory to offer (all those that
-match the regular expression). These variables also apply to choosing
-a file for output (@pxref{Rmail Output}).
-
-@findex set-rmail-inbox-list
- Each Rmail file can contain a list of inbox file names; you can specify
-this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files}
-@key{RET}}. The argument can contain any number of file names, separated
-by commas. It can also be empty, which specifies that this file should
-have no inboxes. Once you specify a list of inboxes in an Rmail file,
-the Rmail file remembers it permanently until you specify a different list.
-
- As a special exception, if your primary Rmail file does not specify any
-inbox files, it uses your standard system inbox.
-
-@kindex g @r{(Rmail)}
-@findex rmail-get-new-mail
- The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the
-current Rmail file from its inboxes. If the Rmail file has no
-inboxes, @kbd{g} does nothing. The command @kbd{M-x rmail} also
-merges new mail into your primary Rmail file.
-
- To merge mail from a file that is not the usual inbox, give the
-@kbd{g} key a numeric argument, as in @kbd{C-u g}. Then it reads a file
-name and merges mail from that file. The inbox file is not deleted or
-changed in any way when @kbd{g} with an argument is used. This is,
-therefore, a general way of merging one file of messages into another.
-
-@node Rmail Output
-@section Copying Messages Out to Files
-
- These commands copy messages from an Rmail file into another file.
-
-@table @kbd
-@item o @var{file} @key{RET}
-Append a copy of the current message to the file @var{file}, using Rmail
-file format by default (@code{rmail-output-to-rmail-file}).
-
-@item C-o @var{file} @key{RET}
-Append a copy of the current message to the file @var{file}, using
-system inbox file format by default (@code{rmail-output}).
-
-@item w @var{file} @key{RET}
-Output just the message body to the file @var{file}, taking the default
-file name from the message @samp{Subject} header.
-@end table
-
-@kindex o @r{(Rmail)}
-@findex rmail-output-to-rmail-file
-@kindex C-o @r{(Rmail)}
-@findex rmail-output
- The commands @kbd{o} and @kbd{C-o} copy the current message into a
-specified file. This file may be an Rmail file or it may be in system
-inbox format; the output commands ascertain the file's format and write
-the copied message in that format.
-
- The @kbd{o} and @kbd{C-o} commands differ in two ways: each has its
-own separate default file name, and each specifies a choice of format to
-use when the file does not already exist. The @kbd{o} command uses
-Rmail format when it creates a new file, while @kbd{C-o} uses system
-inbox format for a new file. The default file name for @kbd{o} is the
-file name used last with @kbd{o}, and the default file name for
-@kbd{C-o} is the file name used last with @kbd{C-o}.
-
- If the output file is an Rmail file currently visited in an Emacs buffer,
-the output commands copy the message into that buffer. It is up to you
-to save the buffer eventually in its file.
-
-@kindex w @r{(Rmail)}
-@findex rmail-output-body-to-file
- Sometimes you may receive a message whose body holds the contents of a
-file. You can save the body to a file (excluding the message header)
-with the @kbd{w} command (@code{rmail-output-body-to-file}). Often
-these messages contain the intended file name in the @samp{Subject}
-field, so the @kbd{w} command uses the @samp{Subject} field as the
-default for the output file name. However, the file name is read using
-the minibuffer, so you can specify a different name if you wish.
-
- You can also output a message to an Rmail file chosen with a menu.
-In the Classify menu, choose the Output Rmail File menu item; then
-choose the Rmail file you want. This outputs the current message to
-that file, like the @kbd{o} command. The variables
-@code{rmail-secondary-file-directory} and
-@code{rmail-secondary-file-regexp} specify which files to offer in the
-menu: the first variable says which directory to find them in; the
-second says which files in that directory to offer (all those that
-match the regular expression).
-
-@vindex rmail-delete-after-output
- Copying a message with @kbd{o} or @kbd{C-o} gives the original copy
-of the message the @samp{filed} attribute, so that @samp{filed}
-appears in the mode line when such a message is current. @kbd{w}
-gives it the @samp{stored} attribute. If you like to keep just a
-single copy of every mail message, set the variable
-@code{rmail-delete-after-output} to @code{t}; then the @kbd{o},
-@kbd{C-o} and @kbd{w} commands delete the original message after
-copying it. (You can undelete the original afterward if you wish.)
-
- Copying messages into files in system inbox format uses the header
-fields that are displayed in Rmail at the time. Thus, if you use the
-@kbd{t} command to view the entire header and then copy the message, the
-entire header is copied. @xref{Rmail Display}.
-
-@vindex rmail-output-file-alist
- The variable @code{rmail-output-file-alist} lets you specify
-intelligent defaults for the output file, based on the contents of the
-current message. The value should be a list whose elements have this
-form:
-
-@example
-(@var{regexp} . @var{name-exp})
-@end example
-
-@noindent
-If there's a match for @var{regexp} in the current message, then the
-default file name for output is @var{name-exp}. If multiple elements
-match the message, the first matching element decides the default file
-name. The subexpression @var{name-exp} may be a string constant giving
-the file name to use, or more generally it may be any Lisp expression
-that returns a file name as a string. @code{rmail-output-file-alist}
-applies to both @kbd{o} and @kbd{C-o}.
-
-@node Rmail Labels
-@section Labels
-@cindex label (Rmail)
-@cindex attribute (Rmail)
-
- Each message can have various @dfn{labels} assigned to it as a means
-of classification. Each label has a name; different names are different
-labels. Any given label is either present or absent on a particular
-message. A few label names have standard meanings and are given to
-messages automatically by Rmail when appropriate; these special labels
-are called @dfn{attributes}.
-@ifnottex
-(@xref{Rmail Attributes}.)
-@end ifnottex
-All other labels are assigned only by users.
-
-@table @kbd
-@item a @var{label} @key{RET}
-Assign the label @var{label} to the current message (@code{rmail-add-label}).
-@item k @var{label} @key{RET}
-Remove the label @var{label} from the current message (@code{rmail-kill-label}).
-@item C-M-n @var{labels} @key{RET}
-Move to the next message that has one of the labels @var{labels}
-(@code{rmail-next-labeled-message}).
-@item C-M-p @var{labels} @key{RET}
-Move to the previous message that has one of the labels @var{labels}
-(@code{rmail-previous-labeled-message}).
-@item l @var{labels} @key{RET}
-@itemx C-M-l @var{labels} @key{RET}
-Make a summary of all messages containing any of the labels @var{labels}
-(@code{rmail-summary-by-labels}).
-@end table
-
-@kindex a @r{(Rmail)}
-@kindex k @r{(Rmail)}
-@findex rmail-add-label
-@findex rmail-kill-label
- The @kbd{a} (@code{rmail-add-label}) and @kbd{k}
-(@code{rmail-kill-label}) commands allow you to assign or remove any
-label on the current message. If the @var{label} argument is empty, it
-means to assign or remove the same label most recently assigned or
-removed.
-
- Once you have given messages labels to classify them as you wish, there
-are two ways to use the labels: in moving and in summaries.
-
-@kindex C-M-n @r{(Rmail)}
-@kindex C-M-p @r{(Rmail)}
-@findex rmail-next-labeled-message
-@findex rmail-previous-labeled-message
- The command @kbd{C-M-n @var{labels} @key{RET}}
-(@code{rmail-next-labeled-message}) moves to the next message that has
-one of the labels @var{labels}. The argument @var{labels} specifies one
-or more label names, separated by commas. @kbd{C-M-p}
-(@code{rmail-previous-labeled-message}) is similar, but moves backwards
-to previous messages. A numeric argument to either command serves as a
-repeat count.
-
- The command @kbd{C-M-l @var{labels} @key{RET}}
-(@code{rmail-summary-by-labels}) displays a summary containing only the
-messages that have at least one of a specified set of labels. The
-argument @var{labels} is one or more label names, separated by commas.
-@xref{Rmail Summary}, for information on summaries.
-
- If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or
-@kbd{C-M-l} is empty, it means to use the last set of labels specified
-for any of these commands.
-
-@node Rmail Attributes
-@section Rmail Attributes
-
- Some labels such as @samp{deleted} and @samp{filed} have built-in
-meanings, and Rmail assigns them to messages automatically at
-appropriate times; these labels are called @dfn{attributes}. Here is
-a list of Rmail attributes:
-
-@table @samp
-@item unseen
-Means the message has never been current. Assigned to messages when
-they come from an inbox file, and removed when a message is made
-current. When you start Rmail, it initially shows the first message
-that has this attribute.
-@item deleted
-Means the message is deleted. Assigned by deletion commands and
-removed by undeletion commands (@pxref{Rmail Deletion}).
-@item filed
-Means the message has been copied to some other file. Assigned by the
-@kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}).
-@item stored
-Assigned by the @kbd{w} file output command (@pxref{Rmail Output}).
-@item answered
-Means you have mailed an answer to the message. Assigned by the @kbd{r}
-command (@code{rmail-reply}). @xref{Rmail Reply}.
-@item forwarded
-Means you have forwarded the message. Assigned by the @kbd{f} command
-(@code{rmail-forward}). @xref{Rmail Reply}.
-@item edited
-Means you have edited the text of the message within Rmail.
-@xref{Rmail Editing}.
-@item resent
-Means you have resent the message. Assigned by the command @kbd{M-x
-rmail-resend}. @xref{Rmail Reply}.
-@end table
-
- All other labels are assigned or removed only by users, and have no
-standard meaning.
-
-@node Rmail Reply
-@section Sending Replies
-
- Rmail has several commands that use Mail mode to send outgoing mail.
-@xref{Sending Mail}, for information on using Mail mode, including
-certain features meant to work with Rmail. What this section documents
-are the special commands of Rmail for entering Mail mode. Note that the
-usual keys for sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and @kbd{C-x 5
-m}---also work normally in Rmail mode.
-
-@table @kbd
-@item m
-Send a message (@code{rmail-mail}).
-@item c
-Continue editing the already started outgoing message (@code{rmail-continue}).
-@item r
-Send a reply to the current Rmail message (@code{rmail-reply}).
-@item f
-Forward the current message to other users (@code{rmail-forward}).
-@item C-u f
-Resend the current message to other users (@code{rmail-resend}).
-@item M-m
-Try sending a bounced message a second time (@code{rmail-retry-failure}).
-@end table
-
-@kindex r @r{(Rmail)}
-@findex rmail-reply
-@cindex reply to a message
- The most common reason to send a message while in Rmail is to reply
-to the message you are reading. To do this, type @kbd{r}
-(@code{rmail-reply}). This displays the @samp{*mail*} buffer in
-another window, much like @kbd{C-x 4 m}, but preinitializes the
-@samp{Subject}, @samp{To}, @samp{CC}, @samp{In-reply-to} and
-@samp{References} header fields based on the message you are replying
-to. The @samp{To} field starts out as the address of the person who
-sent the message you received, and the @samp{CC} field starts out with
-all the other recipients of that message.
-
-@vindex rmail-dont-reply-to-names
- You can exclude certain recipients from being placed automatically in
-the @samp{CC}, using the variable @code{rmail-dont-reply-to-names}. Its
-value should be a regular expression (as a string); any recipient that
-the regular expression matches, is excluded from the @samp{CC} field.
-The default value matches your own name, and any name starting with
-@samp{info-}. (Those names are excluded because there is a convention
-of using them for large mailing lists to broadcast announcements.)
-
- To omit the @samp{CC} field completely for a particular reply, enter
-the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}.
-This means to reply only to the sender of the original message.
-
- Once the @samp{*mail*} buffer has been initialized, editing and
-sending the mail goes as usual (@pxref{Sending Mail}). You can edit the
-presupplied header fields if they are not what you want. You can also
-use the commands of Mail mode (@pxref{Mail Mode}), including @kbd{C-c
-C-y} which yanks in the message that you are replying to. You can
-also switch to the Rmail buffer, select a different message there, switch
-back, and yank the new current message.
-
-@kindex M-m @r{(Rmail)}
-@findex rmail-retry-failure
-@cindex retrying a failed message
-@vindex rmail-retry-ignored-headers
- Sometimes a message does not reach its destination. Mailers usually
-send the failed message back to you, enclosed in a @dfn{failure
-message}. The Rmail command @kbd{M-m} (@code{rmail-retry-failure})
-prepares to send the same message a second time: it sets up a
-@samp{*mail*} buffer with the same text and header fields as before. If
-you type @kbd{C-c C-c} right away, you send the message again exactly
-the same as the first time. Alternatively, you can edit the text or
-headers and then send it. The variable
-@code{rmail-retry-ignored-headers}, in the same format as
-@code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which
-headers are stripped from the failed message when retrying it.
-
-@kindex f @r{(Rmail)}
-@findex rmail-forward
-@cindex forwarding a message
- Another frequent reason to send mail in Rmail is to @dfn{forward} the
-current message to other users. @kbd{f} (@code{rmail-forward}) makes
-this easy by preinitializing the @samp{*mail*} buffer with the current
-message as the text, and a subject designating a forwarded message. All
-you have to do is fill in the recipients and send. When you forward a
-message, recipients get a message which is ``from'' you, and which has
-the original message in its contents.
-
-@findex unforward-rmail-message
- Forwarding a message encloses it between two delimiter lines. It also
-modifies every line that starts with a dash, by inserting @w{@samp{- }}
-at the start of the line. When you receive a forwarded message, if it
-contains something besides ordinary text---for example, program source
-code---you might find it useful to undo that transformation. You can do
-this by selecting the forwarded message and typing @kbd{M-x
-unforward-rmail-message}. This command extracts the original forwarded
-message, deleting the inserted @w{@samp{- }} strings, and inserts it
-into the Rmail file as a separate message immediately following the
-current one.
-
-@findex rmail-resend
- @dfn{Resending} is an alternative similar to forwarding; the
-difference is that resending sends a message that is ``from'' the
-original sender, just as it reached you---with a few added header fields
-@samp{Resent-From} and @samp{Resent-To} to indicate that it came via
-you. To resend a message in Rmail, use @kbd{C-u f}. (@kbd{f} runs
-@code{rmail-forward}, which is programmed to invoke @code{rmail-resend}
-if you provide a numeric argument.)
-
-@kindex m @r{(Rmail)}
-@findex rmail-mail
- The @kbd{m} (@code{rmail-mail}) command is used to start editing an
-outgoing message that is not a reply. It leaves the header fields empty.
-Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
-accessible for @kbd{C-c C-y}, just as @kbd{r} does. Thus, @kbd{m} can be
-used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f}
-can do.
-
-@kindex c @r{(Rmail)}
-@findex rmail-continue
- The @kbd{c} (@code{rmail-continue}) command resumes editing the
-@samp{*mail*} buffer, to finish editing an outgoing message you were
-already composing, or to alter a message you have sent.
-
-@vindex rmail-mail-new-frame
- If you set the variable @code{rmail-mail-new-frame} to a
-non-@code{nil} value, then all the Rmail commands to start sending a
-message create a new frame to edit it in. This frame is deleted when
-you send the message, or when you use the @samp{Cancel} item in the
-@samp{Mail} menu.
-
- All the Rmail commands to send a message use the mail-composition
-method that you have chosen (@pxref{Mail Methods}).
-
-@node Rmail Summary
-@section Summaries
-@cindex summary (Rmail)
-
- A @dfn{summary} is a buffer containing one line per message to give
-you an overview of the mail in an Rmail file. Each line shows the
-message number and date, the sender, the line count, the labels, and
-the subject. Moving point in the summary buffer selects messages as
-you move to their summary lines. Almost all Rmail commands are valid
-in the summary buffer also; when used there, they apply to the message
-described by the current line of the summary.
-
- A summary buffer applies to a single Rmail file only; if you are
-editing multiple Rmail files, each one can have its own summary buffer.
-The summary buffer name is made by appending @samp{-summary} to the
-Rmail buffer's name. Normally only one summary buffer is displayed at a
-time.
-
-@menu
-* Rmail Make Summary:: Making various sorts of summaries.
-* Rmail Summary Edit:: Manipulating messages from the summary.
-@end menu
-
-@node Rmail Make Summary
-@subsection Making Summaries
-
- Here are the commands to create a summary for the current Rmail file.
-Once the Rmail file has a summary buffer, changes in the Rmail file
-(such as deleting or expunging messages, and getting new mail)
-automatically update the summary.
-
-@table @kbd
-@item h
-@itemx C-M-h
-Summarize all messages (@code{rmail-summary}).
-@item l @var{labels} @key{RET}
-@itemx C-M-l @var{labels} @key{RET}
-Summarize messages that have one or more of the specified labels
-(@code{rmail-summary-by-labels}).
-@item C-M-r @var{rcpts} @key{RET}
-Summarize messages that have one or more of the specified recipients
-(@code{rmail-summary-by-recipients}).
-@item C-M-t @var{topic} @key{RET}
-Summarize messages that have a match for the specified regexp
-@var{topic} in their subjects (@code{rmail-summary-by-topic}).
-@item C-M-s @var{regexp}
-Summarize messages whose headers and the subject line match the
-specified regular expression @var{regexp}
-(@code{rmail-summary-by-regexp}).
-@end table
-
-@kindex h @r{(Rmail)}
-@findex rmail-summary
- The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer
-for the current Rmail file with a summary of all the messages in the file.
-It then displays and selects the summary buffer in another window.
-
-@kindex l @r{(Rmail)}
-@kindex C-M-l @r{(Rmail)}
-@findex rmail-summary-by-labels
- @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes
-a partial summary mentioning only the messages that have one or more of the
-labels @var{labels}. @var{labels} should contain label names separated by
-commas.
-
-@kindex C-M-r @r{(Rmail)}
-@findex rmail-summary-by-recipients
- @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients})
-makes a partial summary mentioning only the messages that have one or more
-of the recipients @var{rcpts}. @var{rcpts} should contain mailing
-addresses separated by commas.
-
-@kindex C-M-t @r{(Rmail)}
-@findex rmail-summary-by-topic
- @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic})
-makes a partial summary mentioning only the messages whose subjects have
-a match for the regular expression @var{topic}.
-
-@kindex C-M-s @r{(Rmail)}
-@findex rmail-summary-by-regexp
- @kbd{C-M-s @var{regexp} @key{RET}} (@code{rmail-summary-by-regexp})
-makes a partial summary which mentions only the messages whose headers
-(including the date and the subject lines) match the regular
-expression @var{regexp}.
-
- Note that there is only one summary buffer for any Rmail file;
-making any kind of summary discards any previous summary.
-
-@vindex rmail-summary-window-size
-@vindex rmail-summary-line-count-flag
- The variable @code{rmail-summary-window-size} says how many lines to
-use for the summary window. The variable
-@code{rmail-summary-line-count-flag} controls whether the summary line
-for a message should include the line count of the message.
-
-@node Rmail Summary Edit
-@subsection Editing in Summaries
-
- You can use the Rmail summary buffer to do almost anything you can do
-in the Rmail buffer itself. In fact, once you have a summary buffer,
-there's no need to switch back to the Rmail buffer.
-
- You can select and display various messages in the Rmail buffer, from
-the summary buffer, just by moving point in the summary buffer to
-different lines. It doesn't matter what Emacs command you use to move
-point; whichever line point is on at the end of the command, that
-message is selected in the Rmail buffer.
-
- Almost all Rmail commands work in the summary buffer as well as in the
-Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the current
-message, @kbd{u} undeletes, and @kbd{x} expunges. (However, in the
-summary buffer, a numeric argument to @kbd{d}, @kbd{C-d} and @kbd{u}
-serves as a repeat count. A negative argument reverses the meaning of
-@kbd{d} and @kbd{C-d}.) @kbd{o} and @kbd{C-o} output the current
-message to a file; @kbd{r} starts a reply to it. You can scroll the
-current message while remaining in the summary buffer using @key{SPC}
-and @key{DEL}.
-
- The Rmail commands to move between messages also work in the summary
-buffer, but with a twist: they move through the set of messages included
-in the summary. They also ensure the Rmail buffer appears on the screen
-(unlike cursor motion commands, which update the contents of the Rmail
-buffer but don't display it in a window unless it already appears).
-Here is a list of these commands:
-
-@table @kbd
-@item n
-Move to next line, skipping lines saying `deleted', and select its
-message.
-@item p
-Move to previous line, skipping lines saying `deleted', and select
-its message.
-@item M-n
-Move to next line and select its message.
-@item M-p
-Move to previous line and select its message.
-@item >
-Move to the last line, and select its message.
-@item <
-Move to the first line, and select its message.
-@item j
-@itemx @key{RET}
-Select the message on the current line (ensuring that the RMAIL buffer
-appears on the screen). With argument @var{n}, select message number
-@var{n} and move to its line in the summary buffer; this signals an
-error if the message is not listed in the summary buffer.
-@item M-s @var{pattern} @key{RET}
-Search through messages for @var{pattern} starting with the current
-message; select the message found, and move point in the summary buffer
-to that message's line.
-@end table
-
-@vindex rmail-redisplay-summary
- Deletion, undeletion, and getting new mail, and even selection of a
-different message all update the summary buffer when you do them in the
-Rmail buffer. If the variable @code{rmail-redisplay-summary} is
-non-@code{nil}, these actions also bring the summary buffer back onto
-the screen.
-
-@kindex Q @r{(Rmail summary)}
-@findex rmail-summary-wipe
-@kindex q @r{(Rmail summary)}
-@findex rmail-summary-quit
- When you are finished using the summary, type @kbd{Q}
-(@code{rmail-summary-wipe}) to delete the summary buffer's window. You
-can also exit Rmail while in the summary: @kbd{q}
-(@code{rmail-summary-quit}) deletes the summary window, then exits from
-Rmail by saving the Rmail file and switching to another buffer.
-
-@node Rmail Sorting
-@section Sorting the Rmail File
-
-@table @kbd
-@item M-x rmail-sort-by-date
-Sort messages of current Rmail file by date.
-
-@item M-x rmail-sort-by-subject
-Sort messages of current Rmail file by subject.
-
-@item M-x rmail-sort-by-author
-Sort messages of current Rmail file by author's name.
-
-@item M-x rmail-sort-by-recipient
-Sort messages of current Rmail file by recipient's names.
-
-@item M-x rmail-sort-by-correspondent
-Sort messages of current Rmail file by the name of the other
-correspondent.
-
-@item M-x rmail-sort-by-lines
-Sort messages of current Rmail file by size (number of lines).
-
-@item M-x rmail-sort-by-keywords @key{RET} @var{labels} @key{RET}
-Sort messages of current Rmail file by labels. The argument
-@var{labels} should be a comma-separated list of labels. The order of
-these labels specifies the order of messages; messages with the first
-label come first, messages with the second label come second, and so on.
-Messages which have none of these labels come last.
-@end table
-
- The Rmail sort commands perform a @emph{stable sort}: if there is no
-reason to prefer either one of two messages, their order remains
-unchanged. You can use this to sort by more than one criterion. For
-example, if you use @code{rmail-sort-by-date} and then
-@code{rmail-sort-by-author}, messages from the same author appear in
-order by date.
-
- With a numeric argument, all these commands reverse the order of
-comparison. This means they sort messages from newest to oldest, from
-biggest to smallest, or in reverse alphabetical order.
-
-@node Rmail Display
-@section Display of Messages
-
- Rmail reformats the header of each message before displaying it for
-the first time. Reformatting hides uninteresting header fields to
-reduce clutter. You can use the @kbd{t} command to show the entire
-header or to repeat the header reformatting operation.
-
-@table @kbd
-@item t
-Toggle display of complete header (@code{rmail-toggle-header}).
-@end table
-
-@vindex rmail-ignored-headers
-@vindex rmail-nonignored-headers
- Reformatting the header involves deleting most header fields, on the
-grounds that they are not interesting. The variable
-@code{rmail-ignored-headers} holds a regular expression that specifies
-which header fields to hide in this way---if it matches the beginning
-of a header field, that whole field is hidden. However, the variable
-@code{rmail-nonignored-headers} provides a further override: a header
-matching that regular expression is shown even if it matches
-@code{rmail-ignored-headers} too.
-
-@kindex t @r{(Rmail)}
-@findex rmail-toggle-header
- Rmail saves the complete original header before reformatting; to see
-it, use the @kbd{t} command (@code{rmail-toggle-header}). This
-discards the reformatted headers of the current message and displays
-it with the original header. Repeating @kbd{t} reformats the message
-again, which shows only the interesting headers according to the
-current values of those variable. Selecting the message again also
-reformats it if necessary.
-
- One consequence of this is that if you edit the reformatted header
-(using @kbd{e}; @pxref{Rmail Editing}), subsequent use of @kbd{t} will
-discard your edits. On the other hand, if you use @kbd{e} after
-@kbd{t}, to edit the original (unreformatted) header, those changes are
-permanent.
-
- When the @kbd{t} command has a prefix argument, a positive argument
-means to show the reformatted header, and a zero or negative argument
-means to show the full header.
-
-@vindex rmail-highlighted-headers
- When the terminal supports multiple fonts or colors, Rmail
-highlights certain header fields that are especially interesting---by
-default, the @samp{From} and @samp{Subject} fields. The variable
-@code{rmail-highlighted-headers} holds a regular expression that
-specifies the header fields to highlight; if it matches the beginning
-of a header field, that whole field is highlighted.
-
- If you specify unusual colors for your text foreground and
-background, the colors used for highlighting may not go well with
-them. If so, specify different colors by setting the variable
-@code{rmail-highlight-face} to a suitable face. To turn off
-highlighting entirely in Rmail, set @code{rmail-highlighted-headers}
-to @code{nil}.
-
- You can highlight and activate URLs in incoming messages by adding
-the function @code{goto-address} to the hook
-@code{rmail-show-message-hook}. Then you can browse these URLs by
-clicking on them with @kbd{Mouse-2} (or @kbd{Mouse-1} quickly) or by
-moving to one and typing @kbd{C-c @key{RET}}. @xref{Goto-address,
-Activating URLs, Activating URLs}.
-
-@node Rmail Coding
-@section Rmail and Coding Systems
-
-@cindex decoding mail messages (Rmail)
- Rmail automatically decodes messages which contain non-@acronym{ASCII}
-characters, just as Emacs does with files you visit and with subprocess
-output. Rmail uses the standard @samp{charset=@var{charset}} header in
-the message, if any, to determine how the message was encoded by the
-sender. It maps @var{charset} into the corresponding Emacs coding
-system (@pxref{Coding Systems}), and uses that coding system to decode
-message text. If the message header doesn't have the @samp{charset}
-specification, or if @var{charset} is not recognized,
-Rmail chooses the coding system with the usual Emacs heuristics and
-defaults (@pxref{Recognize Coding}).
-
-@cindex fixing incorrectly decoded mail messages
- Occasionally, a message is decoded incorrectly, either because Emacs
-guessed the wrong coding system in the absence of the @samp{charset}
-specification, or because the specification was inaccurate. For
-example, a misconfigured mailer could send a message with a
-@samp{charset=iso-8859-1} header when the message is actually encoded
-in @code{koi8-r}. When you see the message text garbled, or some of
-its characters displayed as empty boxes, this may have happened.
-
-@findex rmail-redecode-body
- You can correct the problem by decoding the message again using the
-right coding system, if you can figure out or guess which one is
-right. To do this, invoke the @kbd{M-x rmail-redecode-body} command.
-It reads the name of a coding system, encodes the message body using
-whichever coding system was used to decode it before, then redecodes
-it using the coding system you specified. If you specified the right
-coding system, the result should be readable.
-
- Decoding and encoding using the wrong coding system is lossless for
-most encodings, in particular with 8-bit encodings such as iso-8859 or
-koi8. So, if the initial attempt to redecode the message didn't
-result in a legible text, you can try other coding systems until you
-succeed.
-
- With some coding systems, notably those from the iso-2022 family,
-information can be lost in decoding, so that encoding the message
-again won't bring back the original incoming text. In such a case,
-@code{rmail-redecode-body} cannot work. However, the problems that
-call for use of @code{rmail-redecode-body} rarely occur with those
-coding systems. So in practice the command works when you need it.
-
-@node Rmail Editing
-@section Editing Within a Message
-
- Most of the usual Emacs commands are available in Rmail mode, though a
-few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by Rmail for
-other purposes. However, the Rmail buffer is normally read only, and
-most of the letters are redefined as Rmail commands. If you want to
-edit the text of a message, you must use the Rmail command @kbd{e}.
-
-@table @kbd
-@item e
-Edit the current message as ordinary text.
-@end table
-
-@kindex e @r{(Rmail)}
-@findex rmail-edit-current-message
- The @kbd{e} command (@code{rmail-edit-current-message}) switches from
-Rmail mode into Rmail Edit mode, another major mode which is nearly the
-same as Text mode. The mode line indicates this change.
-
- In Rmail Edit mode, letters insert themselves as usual and the Rmail
-commands are not available. When you are finished editing the message and
-are ready to go back to Rmail, type @kbd{C-c C-c}, which switches back to
-Rmail mode. Alternatively, you can return to Rmail mode but cancel all the
-editing that you have done, by typing @kbd{C-c C-]}.
-
-@vindex rmail-edit-mode-hook
- Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then it
-runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}). It adds the
-attribute @samp{edited} to the message. It also displays the full
-headers of the message, so that you can edit the headers as well as the
-body of the message, and your changes in the headers will be
-permanent.
-
-@node Rmail Digest
-@section Digest Messages
-@cindex digest message
-@cindex undigestify
-
- A @dfn{digest message} is a message which exists to contain and carry
-several other messages. Digests are used on some moderated mailing
-lists; all the messages that arrive for the list during a period of time
-such as one day are put inside a single digest which is then sent to the
-subscribers. Transmitting the single digest uses much less computer
-time than transmitting the individual messages even though the total
-size is the same, because the per-message overhead in network mail
-transmission is considerable.
-
-@findex undigestify-rmail-message
- When you receive a digest message, the most convenient way to read it is
-to @dfn{undigestify} it: to turn it back into many individual messages.
-Then you can read and delete the individual messages as it suits you.
-To do this, select the digest message and type the command @kbd{M-x
-undigestify-rmail-message}. This extracts the submessages as separate
-Rmail messages, and inserts them following the digest. The digest
-message itself is flagged as deleted.
-
-@node Out of Rmail
-@section Converting an Rmail File to Inbox Format
-@cindex Babyl format to Inbox format
-@cindex converting Rmail file to mailbox format
-
-@findex unrmail
- The command @kbd{M-x unrmail} converts a file in Rmail format to inbox
-format (also known as the system mailbox, or mbox, format), so that
-you can use it with other mail-editing tools. You must specify two
-arguments, the name of the Rmail file and the name to use for the
-converted file. @kbd{M-x unrmail} does not alter the Rmail file itself.
-
-@pindex b2m
- @kbd{M-x unrmail} is useful if you can run Emacs on the machine
-where the Rmail file resides, or can access the Rmail file remotely
-(@pxref{Remote Files}) from a machine where Emacs is installed. If
-accessing Rmail files from Emacs is impossible, you can use the
-@command{b2m} program instead. @command{b2m} is part of the Emacs
-distribution, it is installed into the same directory where all the
-other auxiliary programs (@command{etags} etc.) are installed, and its
-source is available in the Emacs source distribution, so that you
-could copy the source to the target machine and compile it there.
-
- To convert a file @file{@var{babyl-file}} into @file{@var{mbox-file}},
-invoke @command{b2m} like this:
-
-@example
- b2m < @var{babyl-file} > @var{mbox-file}
-@end example
-
-@node Rmail Rot13
-@section Reading Rot13 Messages
-@cindex rot13 code
-
- Mailing list messages that might offend some readers are sometimes
-encoded in a simple code called @dfn{rot13}---so named because it
-rotates the alphabet by 13 letters. This code is not for secrecy, as it
-provides none; rather, it enables those who might be offended to avoid
-seeing the real text of the message.
-
-@findex rot13-other-window
- To view a buffer which uses the rot13 code, use the command @kbd{M-x
-rot13-other-window}. This displays the current buffer in another window
-which applies the code when displaying the text.
-
-@node Movemail
-@section @code{movemail} program
-@cindex @code{movemail} program
-
- When invoked for the first time, Rmail attempts to locate the
-@code{movemail} program and determine its version. There are two
-versions of @code{movemail} program: the native one, shipped with GNU
-Emacs (the ``emacs version'') and the one included in GNU mailutils
-(the ``mailutils version,'' @pxref{movemail,,,mailutils,GNU
-mailutils}). They support the same command line syntax and the same
-basic subset of options. However, the Mailutils version offers
-additional features.
-
- The Emacs version of @code{movemail} is able to retrieve mail from
-usual UNIX mailbox formats and from remote mailboxes using the POP3
-protocol.
-
- The Mailutils version is able to handle a wide set of mailbox
-formats, such as plain UNIX mailboxes, @code{maildir} and @code{MH}
-mailboxes, etc. It is able to retrieve remote mail using POP3 or
-IMAP4 protocol, and can retrieve mail from them using a TLS encrypted
-channel. It also accepts mailbox argument in the @acronym{URL} form.
-The detailed description of mailbox @acronym{URL}s can be found in
-@ref{URL,,,mailutils,Mailbox URL Formats}. In short, a @acronym{URL}
-is:
-
-@smallexample
-@var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name}
-@end smallexample
-
-@noindent
-where square brackets denote optional elements.
-
-@table @var
-@item proto
-Specifies the @dfn{mailbox protocol}, or @dfn{format} to
-use. The exact semantics of the rest of @acronym{URL} elements depends
-on the actual value of @var{proto} (see below).
-
-@item user
-User name to access the remote mailbox.
-
-@item password
-User password to access the remote mailbox.
-
-@item host-or-file-name
-Hostname of the remote server for remote mailboxes or file name of a
-local mailbox.
-@end table
-
-@noindent
-@var{Proto} can be one of:
-
-@table @code
-@item mbox
-Usual UNIX mailbox format. In this case, neither @var{user} nor
-@var{pass} are used, and @var{host-or-file-name} denotes the file name of
-the mailbox file, e.g., @code{mbox://var/spool/mail/smith}.
-
-@item mh
-A local mailbox in the @acronym{MH} format. @var{User} and
-@var{pass} are not used. @var{Host-or-file-name} denotes the name of
-@acronym{MH} folder, e.g., @code{mh://Mail/inbox}.
-
-@item maildir
-A local mailbox in the @acronym{maildir} format. @var{User} and
-@var{pass} are not used, and @var{host-or-file-name} denotes the name of
-@code{maildir} mailbox, e.g., @code{maildir://mail/inbox}.
-
-@item file
-Any local mailbox format. Its actual format is detected automatically
-by @code{movemail}.
-
-@item pop
-A remote mailbox to be accessed via POP3 protocol. @var{User}
-specifies the remote user name to use, @var{pass} may be used to
-specify the user password, @var{host-or-file-name} is the name or IP
-address of the remote mail server to connect to; e.g.,
-@code{pop://smith:guessme@@remote.server.net}.
-
-@item imap
-A remote mailbox to be accessed via IMAP4 protocol. @var{User}
-specifies the remote user name to use, @var{pass} may be used to
-specify the user password, @var{host-or-file-name} is the name or IP
-address of the remote mail server to connect to;
-e.g., @code{imap://smith:guessme@@remote.server.net}.
-@end table
-
- Alternatively, you can specify the file name of the mailbox to use.
-This is equivalent to specifying the @samp{file} protocol:
-
-@smallexample
-/var/spool/mail/@var{user} @equiv{} file://var/spool/mail/@var{user}
-@end smallexample
-
-@vindex rmail-movemail-program
-@vindex rmail-movemail-search-path
- The variable @code{rmail-movemail-program} controls which version of
-@code{movemail} to use. If that is a string, it specifies the
-absolute file name of the @code{movemail} executable. If it is
-@code{nil}, Rmail searches for @code{movemail} in the directories
-listed in @code{rmail-movemail-search-path} and @code{exec-path}, then
-in @code{exec-directory}.
-
-@node Remote Mailboxes
-@section Retrieving Mail from Remote Mailboxes
-@pindex movemail
-
- Some sites use a method called POP for accessing users' inbox data
-instead of storing the data in inbox files. The @code{Emacs
-movemail} can work with POP if you compile it with the macro
-@code{MAIL_USE_POP} defined. (You can achieve that by specifying
-@samp{--with-pop} when you run @code{configure} during the
-installation of Emacs.)
-
-The Mailutils @code{movemail} by default supports POP, unless it was
-configured with @samp{--disable-pop} option.
-
-Both versions of @code{movemail} only work with POP3, not with older
-versions of POP.
-
-@cindex @env{MAILHOST} environment variable
-@cindex POP mailboxes
- No matter which flavor of @code{movemail} you use, you can specify
-POP inbox by using POP @dfn{URL} (@pxref{Movemail}). A POP
-@acronym{URL} is a ``file name'' of the form
-@samp{pop://@var{username}@@@var{hostname}}, where
-@var{hostname} is the host name or IP address of the remote mail
-server and @var{username} is the user name on that server.
-Additionally, you may specify the password in the mailbox @acronym{URL}:
-@samp{pop://@var{username}:@var{password}@@@var{hostname}}. In this
-case, @var{password} takes preference over the one set by
-@code{rmail-remote-password}. This is especially useful if you have
-several remote mailboxes with different passwords.
-
- For backward compatibility, Rmail also supports two alternative ways
-of specifying remote POP mailboxes. First, specifying an inbox name
-in the form @samp{po:@var{username}:@var{hostname}} is equivalent to
-@samp{pop://@var{username}@@@var{hostname}}. Alternatively, you may
-set a ``file name'' of @samp{po:@var{username}} in the inbox list of
-an Rmail file. @code{movemail} will handle such a name by opening a
-connection to the POP server. In this case, the @env{MAILHOST}
-environment variable specifies the machine on which to look for the
-POP server.
-
-@cindex IMAP mailboxes
- Another method for accessing remote mailboxes is IMAP. This method is
-supported only by the Mailutils @code{movemail}. To specify an IMAP
-mailbox in the inbox list, use the following mailbox @acronym{URL}:
-@samp{imap://@var{username}[:@var{password}]@@@var{hostname}}. The
-@var{password} part is optional, as described above.
-
-@vindex rmail-remote-password
-@vindex rmail-remote-password-required
-@vindex rmail-pop-password
-@vindex rmail-pop-password-required
- Accessing a remote mailbox may require a password. Rmail uses the
-following algorithm to retrieve it:
-
-@enumerate
-@item
-If the @var{password} is present in mailbox URL (see above), it is
-used.
-@item
-If the variable @code{rmail-remote-password} is non-@code{nil}, its
-value is used.
-@item
-Otherwise, if @code{rmail-remote-password-required} is non-@code{nil},
-then Rmail will ask you for the password to use.
-@item
-Otherwise, Rmail assumes no password is required.
-@end enumerate
-
- For compatibility with previous versions, the variables
-@code{rmail-pop-password} and @code{rmail-pop-password-required} may
-be used instead of @code{rmail-remote-password} and
-@code{rmail-remote-password-required}.
-
-@vindex rmail-movemail-flags
- If you need to pass additional command-line flags to @code{movemail},
-set the variable @code{rmail-movemail-flags} a list of the flags you
-wish to use. Do not use this variable to pass the @samp{-p} flag to
-preserve your inbox contents; use @code{rmail-preserve-inbox} instead.
-
-@cindex Kerberos POP authentication
- The @code{movemail} program installed at your site may support
-Kerberos authentication. If it is
-supported, it is used by default whenever you attempt to retrieve
-POP mail when @code{rmail-pop-password} and
-@code{rmail-pop-password-required} are unset.
-
-@cindex reverse order in POP inboxes
- Some POP servers store messages in reverse order. If your server does
-this, and you would rather read your mail in the order in which it was
-received, you can tell @code{movemail} to reverse the order of
-downloaded messages by adding the @samp{-r} flag to
-@code{rmail-movemail-flags}.
-
-@cindex TLS encryption (Rmail)
- Mailutils @code{movemail} supports TLS encryption. If you wish to
-use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}.
-
-@node Other Mailbox Formats
-@section Retrieving Mail from Local Mailboxes in Various Formats
-
- If your incoming mail is stored on a local machine in a format other
-than UNIX mailbox, you will need the Mailutils @code{movemail} to
-retrieve it. @xref{Movemail}, for the detailed description of
-@code{movemail} versions. For example, to access mail from a inbox in
-@code{maildir} format located in @file{/var/spool/mail/in}, you would
-include the following in the Rmail inbox list:
-
-@smallexample
-maildir://var/spool/mail/in
-@end smallexample
-
-@ignore
- arch-tag: 034965f6-38df-47a2-a9f1-b8bc8ab37e23
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Screen, User Input, Acknowledgments, Top
-@chapter The Organization of the Screen
-@cindex screen
-@cindex parts of the screen
-
- On a text-only terminal, the Emacs display occupies the whole
-screen. On a graphical display, such as on GNU/Linux using the X
-Window System, Emacs creates its own windows to use. We use the term
-@dfn{frame} to mean the entire text-only screen or an entire
-system-level window used by Emacs. Emacs uses both kinds of frames,
-in the same way, to display your editing. Emacs normally starts out
-with just one frame, but you can create additional frames if you wish.
-@xref{Frames}.
-
- When you start Emacs, the main central area of the frame, all except
-for the top and bottom and sides, displays the text you are editing.
-This area is called @dfn{the window}. At the top there is normally a
-@dfn{menu bar} where you can access a series of menus; then there may
-be a @dfn{tool bar}, a row of icons that perform editing commands if
-you click on them. Below this, the window begins, often with a
-@dfn{scroll bar} on one side. Below the window comes the last line of
-the frame, a special @dfn{echo area} or @dfn{minibuffer window}, where
-prompts appear and you enter information when Emacs asks for it. See
-following sections for more information about these special lines.
-
- You can subdivide the window horizontally or vertically to make
-multiple text windows, each of which can independently display some
-file or text (@pxref{Windows}). In this manual, the word ``window''
-refers to the initial large window if not subdivided, or any one of
-the multiple windows you have subdivided it into.
-
- At any time, one window is the @dfn{selected window}. On graphical
-displays, the selected window normally shows a more prominent cursor
-(usually solid and blinking) while other windows show a weaker cursor
-(such as a hollow box). Text terminals have just one cursor, so it
-always appears in the selected window.
-
- Most Emacs commands implicitly apply to the text in the selected
-window; the text in unselected windows is mostly visible for
-reference. However, mouse commands generally operate on whatever
-window you click them in, whether selected or not. If you use
-multiple frames on a graphical display, then giving the input focus to
-a particular frame selects a window in that frame.
-
- Each window's last line is a @dfn{mode line}, which describes what
-is going on in that window. It appears in different color and/or a ``3D''
-box if the terminal supports them; its contents normally begin with
-@w{@samp{--:-- @ *scratch*}} when Emacs starts. The mode line
-displays status information such as what buffer is being displayed
-above it in the window, what major and minor modes are in use, and
-whether the buffer contains unsaved changes.
-
-@menu
-* Point:: The place in the text where editing commands operate.
-* Echo Area:: Short messages appear at the bottom of the screen.
-* Mode Line:: Interpreting the mode line.
-* Menu Bar:: How to use the menu bar.
-@end menu
-
-@node Point
-@section Point
-@cindex point
-@cindex cursor
-
- Within Emacs, the active cursor shows the location at which
-editing commands will take effect. This location is called @dfn{point}.
-Many Emacs commands move point through the text, so that you can edit at
-different places in it. You can also place point by clicking mouse
-button 1 (normally the left button).
-
- While the cursor appears to be @emph{on} a character, you should
-think of point as @emph{between} two characters; it points @emph{before}
-the character that appears under the cursor. For example, if your text
-looks like @samp{frob} with the cursor over the @samp{b}, then point is
-between the @samp{o} and the @samp{b}. If you insert the character
-@samp{!} at that position, the result is @samp{fro!b}, with point
-between the @samp{!} and the @samp{b}. Thus, the cursor remains over
-the @samp{b}, as before.
-
- Sometimes people speak of ``the cursor'' when they mean ``point,'' or
-speak of commands that move point as ``cursor motion'' commands.
-
- If you are editing several files in Emacs, each in its own buffer,
-each buffer has its own point location. A buffer that is not
-currently displayed remembers its point location in case you display
-it again later. When Emacs displays multiple windows, each window has
-its own point location. If the same buffer appears in more than one
-window, each window has its own point position in that buffer, and (when
-possible) its own cursor.
-
- A text-only terminal has just one cursor, in the selected window.
-The other windows do not show a cursor, even though they do have their
-own position of point. When Emacs updates the screen on a text-only
-terminal, it has to put the cursor temporarily at the place the output
-goes. This doesn't mean point is there, though. Once display
-updating finishes, Emacs puts the cursor where point is.
-
- On graphical displays, Emacs shows a cursor in each window; the
-selected window's cursor is solid and blinking, and the other cursors
-are just hollow. Thus, the most prominent cursor always shows you the
-selected window, on all kinds of terminals.
-
- @xref{Cursor Display}, for customizable variables that control display
-of the cursor or cursors.
-
- The term ``point'' comes from the character @samp{.}, which was the
-command in TECO (the language in which the original Emacs was written)
-for accessing the value now called ``point.''
-
-@node Echo Area
-@section The Echo Area
-@cindex echo area
-
- The line at the bottom of the frame (below the mode line) is the
-@dfn{echo area}. It is used to display small amounts of text for
-various purposes.
-
- @dfn{Echoing} means displaying the characters that you type. At the
-command line, the operating system normally echoes all your input.
-Emacs handles echoing differently.
-
- Single-character commands do not echo in Emacs, and multi-character
-commands echo only if you pause while typing them. As soon as you pause
-for more than a second in the middle of a command, Emacs echoes all the
-characters of the command so far. This is to @dfn{prompt} you for the
-rest of the command. Once echoing has started, the rest of the command
-echoes immediately as you type it. This behavior is designed to give
-confident users fast response, while giving hesitant users maximum
-feedback. You can change this behavior by setting a variable
-(@pxref{Display Custom}).
-
-@cindex error message in the echo area
- If a command cannot do its job, it may display an @dfn{error
-message} in the echo area. Error messages are accompanied by beeping
-or by flashing the screen. The error also discards any input you have
-typed ahead.
-
- Some commands display informative messages in the echo area. These
-messages look much like error messages, but they are not announced
-with a beep and do not throw away input. Sometimes the message tells
-you what the command has done, when this is not obvious from looking
-at the text being edited. Sometimes the sole purpose of a command is
-to show you a message giving you specific information---for example,
-@kbd{C-x =} (hold down @key{CTRL} and type @kbd{x}, then let go of
-@key{CTRL} and type @kbd{=}) displays a message describing the
-character position of point in the text and its current column in the
-window. Commands that take a long time often display messages ending
-in @samp{...} while they are working, and add @samp{done} at the end
-when they are finished. They may also indicate progress with
-percentages.
-
-@cindex @samp{*Messages*} buffer
-@cindex saved echo area messages
-@cindex messages saved from echo area
- Echo-area informative messages are saved in an editor buffer named
-@samp{*Messages*}. (We have not explained buffers yet; see
-@ref{Buffers}, for more information about them.) If you miss a message
-that appears briefly on the screen, you can switch to the
-@samp{*Messages*} buffer to see it again. (Successive progress messages
-are often collapsed into one in that buffer.)
-
-@vindex message-log-max
- The size of @samp{*Messages*} is limited to a certain number of
-lines. The variable @code{message-log-max} specifies how many lines.
-Once the buffer has that many lines, adding lines at the end deletes lines
-from the beginning, to keep the size constant. @xref{Variables}, for
-how to set variables such as @code{message-log-max}.
-
- The echo area is also used to display the @dfn{minibuffer}, a window
-where you can input arguments to commands, such as the name of a file
-to be edited. When the minibuffer is in use, the echo area begins
-with a prompt string that usually ends with a colon; also, the cursor
-appears in that line because it is the selected window. You can
-always get out of the minibuffer by typing @kbd{C-g}.
-@xref{Minibuffer}.
-
-@node Mode Line
-@section The Mode Line
-@cindex mode line
-@cindex top level
-@c
-
- Each text window's last line is a @dfn{mode line}, which describes
-what is going on in that window. The mode line starts and ends with
-dashes. When there is only one text window, the mode line appears
-right above the echo area; it is the next-to-last line in the frame.
-On a text-only terminal, the mode line is in inverse video if the
-terminal supports that; on a graphics display, the mode line has a 3D
-box appearance to help it stand out. The mode line of the selected
-window is highlighted if possible; see @ref{Optional Mode Line}, for
-more information.
-
- Normally, the mode line looks like this:
-
-@example
--@var{cs}:@var{ch}@var{R}-@var{fr} @var{buf} @var{pos} @var{line} (@var{major} @var{minor})------
-@end example
-
-@noindent
-This gives information about the window and the buffer it displays: the
-buffer's name, what major and minor modes are in use, whether the
-buffer's text has been changed, and how far down the buffer you are
-currently looking.
-
- @var{ch} contains two stars @samp{**} if the text in the buffer has
-been edited (the buffer is ``modified''), or @samp{--} if the buffer has
-not been edited. For a read-only buffer, it is @samp{%*} if the buffer
-is modified, and @samp{%%} otherwise.
-
- @var{R} is @samp{@@} if the default-directory for the current buffer
-is on a remote machine, or a hyphen otherwise.
-
- @var{fr} gives the selected frame name (@pxref{Frames}). It appears
-only on text-only terminals. The initial frame's name is @samp{F1}.
-
- @var{buf} is the name of the window's @dfn{buffer}. Usually this is
-the same as the name of a file you are editing. @xref{Buffers}.
-
- The buffer displayed in the selected window (the window with the
-cursor) is the @dfn{current buffer}, where editing happens. When a
-command's effect applies to ``the buffer,'' we mean it does those
-things to the current buffer.
-
- @var{pos} tells you whether there is additional text above the top of
-the window, or below the bottom. If your buffer is small and it is all
-visible in the window, @var{pos} is @samp{All}. Otherwise, it is
-@samp{Top} if you are looking at the beginning of the buffer, @samp{Bot}
-if you are looking at the end of the buffer, or @samp{@var{nn}%}, where
-@var{nn} is the percentage of the buffer above the top of the window.
-With Size Indication mode, you can display the size of the buffer as
-well. @xref{Optional Mode Line}.
-
- @var{line} is @samp{L} followed by the current line number of point.
-This is present when Line Number mode is enabled (it normally is).
-You can display the current column number too, by turning on Column
-Number mode. It is not enabled by default because it is somewhat
-slower. @xref{Optional Mode Line}.
-
- @var{major} is the name of the @dfn{major mode} in effect in the
-buffer. A buffer can only be in one major mode at a time. The major
-modes available include Fundamental mode (the least specialized), Text
-mode, Lisp mode, C mode, Texinfo mode, and many others. @xref{Major
-Modes}, for details of how the modes differ and how to select
-them.
-
- Some major modes display additional information after the major mode
-name. For example, Rmail buffers display the current message number and
-the total number of messages. Compilation buffers and Shell buffers
-display the status of the subprocess.
-
- @var{minor} is a list of some of the @dfn{minor modes} that are
-turned on at the moment in the window's chosen buffer. For example,
-@samp{Fill} means that Auto Fill mode is on. @samp{Abbrev} means that
-Word Abbrev mode is on. @samp{Ovwrt} means that Overwrite mode is on.
-@xref{Minor Modes}, for more information.
-
- @samp{Narrow} means that the buffer being displayed has editing
-restricted to only a portion of its text. (This is not really a minor
-mode, but is like one.) @xref{Narrowing}. @samp{Def} means that a
-keyboard macro is being defined. @xref{Keyboard Macros}.
-
- In addition, if Emacs is inside a recursive editing level, square
-brackets (@samp{[@dots{}]}) appear around the parentheses that
-surround the modes. If Emacs is in one recursive editing level within
-another, double square brackets appear, and so on. Since recursive
-editing levels affect Emacs globally, not just one buffer, the square
-brackets appear in every window's mode line or not in any of them.
-@xref{Recursive Edit}.@refill
-
- @var{cs} states the coding system used for the file you are editing.
-A dash indicates the default state of affairs: no code conversion,
-except for end-of-line translation if the file contents call for that.
-@samp{=} means no conversion whatsoever. Nontrivial code conversions
-are represented by various letters---for example, @samp{1} refers to ISO
-Latin-1. @xref{Coding Systems}, for more information.
-
- On a text-only terminal, @var{cs} includes two additional characters
-which describe the coding system for keyboard input and the coding
-system for terminal output. They come right before the coding system
-used for the file you are editing.
-
- If you are using an input method, a string of the form
-@samp{@var{i}>} is added to the beginning of @var{cs}; @var{i}
-identifies the input method. (Some input methods show @samp{+} or
-@samp{@@} instead of @samp{>}.) @xref{Input Methods}.
-
- When multibyte characters are not enabled, @var{cs} does not appear at
-all. @xref{Enabling Multibyte}.
-
-@cindex end-of-line conversion, mode-line indication
- The colon after @var{cs} changes to another string in some cases.
-Emacs uses newline characters to separate lines in the buffer. Some
-files use different conventions for separating lines: either
-carriage-return linefeed (the MS-DOS convention) or just
-carriage-return (the Macintosh convention). If the buffer's file uses
-carriage-return linefeed, the colon changes to either a backslash
-(@samp{\}) or @samp{(DOS)}, depending on the operating system. If the
-file uses just carriage-return, the colon indicator changes to either
-a forward slash (@samp{/}) or @samp{(Mac)}. On some systems, Emacs
-displays @samp{(Unix)} instead of the colon for files that use newline
-as the line separator.
-
- @xref{Optional Mode Line}, to add other handy information to the
-mode line, such as the size of the buffer, the current column number
-of point, and whether new mail for you has arrived.
-
- The mode line is mouse-sensitive; when you move the mouse across
-various parts of it, Emacs displays help text to say what a click in
-that place will do. @xref{Mode Line Mouse}.
-
-@node Menu Bar
-@section The Menu Bar
-@cindex menu bar
-
- Each Emacs frame normally has a @dfn{menu bar} at the top which you
-can use to perform common operations. There's no need to list them
-here, as you can more easily see them yourself.
-
-@kindex M-`
-@kindex F10
-@findex tmm-menubar
-@findex menu-bar-open
- On a graphical display, you can use the mouse to choose a command
-from the menu bar. A right-arrow at the end of the menu item means it
-leads to a subsidiary menu; @samp{...} at the end means that the
-command invoked will read arguments (further input from you) before it
-actually does anything.
-
- You can also invoke the first menu bar item by pressing @key{F10} (to run
-the command @code{menu-bar-open}). You can then navigate the menus with
-the arrow keys. You select an item by pressing @key{RET} and cancel menu
-navigation with @key{ESC}.
-
- To view the full command name and documentation for a menu item, type
-@kbd{C-h k}, and then select the menu bar with the mouse in the usual
-way (@pxref{Key Help}).
-
- On text-only terminals with no mouse, you can use the menu bar by
-typing @kbd{M-`} or @key{F10} (these run the command
-@code{tmm-menubar}). This lets you select a menu item with the
-keyboard. A provisional choice appears in the echo area. You can use
-the up and down arrow keys to move through the menu to different
-items, and then you can type @key{RET} to select the item.
-
- Each menu item also has an assigned letter or digit which designates
-that item; it is usually the initial of some word in the item's name.
-This letter or digit is separated from the item name by @samp{=>}. You
-can type the item's letter or digit to select the item.
-
- Some of the commands in the menu bar have ordinary key bindings as
-well; one such binding is shown in parentheses after the item itself.
-
-@ignore
- arch-tag: 104ba40e-d972-4866-a542-a98be94bdf2f
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Search, Fixit, Display, Top
-@chapter Searching and Replacement
-@cindex searching
-@cindex finding strings within text
-
- Like other editors, Emacs has commands for searching for occurrences of
-a string. The principal search command is unusual in that it is
-@dfn{incremental}; it begins to search before you have finished typing the
-search string. There are also nonincremental search commands more like
-those of other editors.
-
- Besides the usual @code{replace-string} command that finds all
-occurrences of one string and replaces them with another, Emacs has a
-more flexible replacement command called @code{query-replace}, which
-asks interactively which occurrences to replace. There are also
-commands to find and operate on all matches for a pattern.
-
- You can also search multiple files under control of a tags
-table (@pxref{Tags Search}) or through the Dired @kbd{A} command
-(@pxref{Operating on Files}), or ask the @code{grep} program to do it
-(@pxref{Grep Searching}).
-
-
-@menu
-* Incremental Search:: Search happens as you type the string.
-* Nonincremental Search:: Specify entire string and then search.
-* Word Search:: Search for sequence of words.
-* Regexp Search:: Search for match for a regexp.
-* Regexps:: Syntax of regular expressions.
-* Regexp Backslash:: Regular expression constructs starting with `\'.
-* Regexp Example:: A complex regular expression explained.
-* Search Case:: To ignore case while searching, or not.
-* Replace:: Search, and replace some or all matches.
-* Other Repeating Search:: Operating on all matches for some regexp.
-@end menu
-
-@node Incremental Search
-@section Incremental Search
-@cindex incremental search
-@cindex isearch
-
- An incremental search begins searching as soon as you type the first
-character of the search string. As you type in the search string, Emacs
-shows you where the string (as you have typed it so far) would be
-found. When you have typed enough characters to identify the place you
-want, you can stop. Depending on what you plan to do next, you may or
-may not need to terminate the search explicitly with @key{RET}.
-
-@table @kbd
-@item C-s
-Incremental search forward (@code{isearch-forward}).
-@item C-r
-Incremental search backward (@code{isearch-backward}).
-@end table
-
-@menu
-* Basic Isearch:: Basic incremental search commands.
-* Repeat Isearch:: Searching for the same string again.
-* Error in Isearch:: When your string is not found.
-* Special Isearch:: Special input in incremental search.
-* Non-ASCII Isearch:: How to search for non-ASCII characters.
-* Isearch Yank:: Commands that grab text into the search string
- or else edit the search string.
-* Highlight Isearch:: Isearch highlights the other possible matches.
-* Isearch Scroll:: Scrolling during an incremental search.
-* Slow Isearch:: Incremental search features for slow terminals.
-@end menu
-
-@node Basic Isearch
-@subsection Basics of Incremental Search
-
-@kindex C-s
-@findex isearch-forward
- @kbd{C-s} starts a forward incremental search. It reads characters
-from the keyboard, and moves point past the next occurrence of those
-characters. If you type @kbd{C-s} and then @kbd{F}, that puts the
-cursor after the first @samp{F} (the first following the starting point, since
-this is a forward search). Then if you type an @kbd{O}, you will see
-the cursor move to just after the first @samp{FO} (the @samp{F} in that
-@samp{FO} may or may not be the first @samp{F}). After another
-@kbd{O}, the cursor moves to just after the first @samp{FOO} after the place
-where you started the search. At each step, the buffer text that
-matches the search string is highlighted, if the terminal can do that;
-the current search string is always displayed in the echo area.
-
- If you make a mistake in typing the search string, you can cancel
-characters with @key{DEL}. Each @key{DEL} cancels the last character of
-search string. This does not happen until Emacs is ready to read another
-input character; first it must either find, or fail to find, the character
-you want to erase. If you do not want to wait for this to happen, use
-@kbd{C-g} as described below.
-
- When you are satisfied with the place you have reached, you can type
-@key{RET}, which stops searching, leaving the cursor where the search
-brought it. Also, any command not specially meaningful in searches
-stops the searching and is then executed. Thus, typing @kbd{C-a}
-would exit the search and then move to the beginning of the line.
-@key{RET} is necessary only if the next command you want to type is a
-printing character, @key{DEL}, @key{RET}, or another character that is
-special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s},
-@kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some other
-meta-characters).
-
- When you exit the incremental search, it sets the mark where point
-@emph{was} before the search. That is convenient for moving back
-there. In Transient Mark mode, incremental search sets the mark
-without activating it, and does so only if the mark is not already
-active.
-
-@node Repeat Isearch
-@subsection Repeating Incremental Search
-
- Sometimes you search for @samp{FOO} and find one, but not the one you
-expected to find. There was a second @samp{FOO} that you forgot
-about, before the one you were aiming for. In this event, type
-another @kbd{C-s} to move to the next occurrence of the search string.
-You can repeat this any number of times. If you overshoot, you can
-cancel some @kbd{C-s} characters with @key{DEL}.
-
- After you exit a search, you can search for the same string again by
-typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes
-incremental search, and the second @kbd{C-s} means ``search again.''
-
- If a search is failing and you ask to repeat it by typing another
-@kbd{C-s}, it starts again from the beginning of the buffer.
-Repeating a failing reverse search with @kbd{C-r} starts again from
-the end. This is called @dfn{wrapping around}, and @samp{Wrapped}
-appears in the search prompt once this has happened. If you keep on
-going past the original starting point of the search, it changes to
-@samp{Overwrapped}, which means that you are revisiting matches that
-you have already seen.
-
- To reuse earlier search strings, use the @dfn{search ring}. The
-commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a search
-string to reuse. These commands leave the selected search ring element
-in the minibuffer, where you can edit it. To edit the current search
-string in the minibuffer without replacing it with items from the
-search ring, type @kbd{M-e}. Type @kbd{C-s} or @kbd{C-r}
-to terminate editing the string and search for it.
-
- You can change to searching backwards with @kbd{C-r}. For instance,
-if you are searching forward but you realize you were looking for
-something above the starting point, you can do this. Repeated
-@kbd{C-r} keeps looking for more occurrences backwards. A @kbd{C-s}
-starts going forwards again. @kbd{C-r} in a search can be canceled
-with @key{DEL}.
-
-@kindex C-r
-@findex isearch-backward
- If you know initially that you want to search backwards, you can use
-@kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r}
-as a key runs a command (@code{isearch-backward}) to search backward.
-A backward search finds matches that end before the starting point,
-just as a forward search finds matches that begin after it.
-
-@node Error in Isearch
-@subsection Errors in Incremental Search
-
- If your string is not found at all, the echo area says @samp{Failing
-I-Search}. The cursor is after the place where Emacs found as much of your
-string as it could. Thus, if you search for @samp{FOOT}, and there is no
-@samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}.
-At this point there are several things you can do. If your string was
-mistyped, you can rub some of it out and correct it. If you like the place
-you have found, you can type @key{RET} or some other Emacs command to
-remain there. Or you can type @kbd{C-g}, which
-removes from the search string the characters that could not be found (the
-@samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in
-@samp{FOOT}). A second @kbd{C-g} at that point cancels the search
-entirely, returning point to where it was when the search started.
-
-@cindex quitting (in search)
- The @kbd{C-g} ``quit'' character does special things during searches;
-just what it does depends on the status of the search. If the search has
-found what you specified and is waiting for input, @kbd{C-g} cancels the
-entire search. The cursor moves back to where you started the search. If
-@kbd{C-g} is typed when there are characters in the search string that have
-not been found---because Emacs is still searching for them, or because it
-has failed to find them---then the search string characters which have not
-been found are discarded from the search string. With them gone, the
-search is now successful and waiting for more input, so a second @kbd{C-g}
-will cancel the entire search.
-
-@node Special Isearch
-@subsection Special Input for Incremental Search
-
- An upper-case letter in the search string makes the search
-case-sensitive. If you delete the upper-case character from the search
-string, it ceases to have this effect. @xref{Search Case}.
-
- To search for a newline, type @kbd{C-j}. To search for another
-control character, such as control-S or carriage return, you must quote
-it by typing @kbd{C-q} first. This function of @kbd{C-q} is analogous
-to its use for insertion (@pxref{Inserting Text}): it causes the
-following character to be treated the way any ``ordinary'' character is
-treated in the same context. You can also specify a character by its
-octal code: enter @kbd{C-q} followed by a sequence of octal digits.
-
- @kbd{M-%} typed in incremental search invokes @code{query-replace}
-or @code{query-replace-regexp} (depending on search mode) with the
-current search string used as the string to replace. @xref{Query
-Replace}.
-
- Entering @key{RET} when the search string is empty launches
-nonincremental search (@pxref{Nonincremental Search}).
-
-@vindex isearch-mode-map
- To customize the special characters that incremental search understands,
-alter their bindings in the keymap @code{isearch-mode-map}. For a list
-of bindings, look at the documentation of @code{isearch-mode} with
-@kbd{C-h f isearch-mode @key{RET}}.
-
-@node Non-ASCII Isearch
-@subsection Isearch for Non-@acronym{ASCII} Characters
-@cindex searching for non-@acronym{ASCII} characters
-@cindex input method, during incremental search
-
- To enter non-@acronym{ASCII} characters in an incremental search,
-you can use @kbd{C-q} (see the previous section), but it is easier to
-use an input method (@pxref{Input Methods}). If an input method is
-enabled in the current buffer when you start the search, you can use
-it in the search string also. Emacs indicates that by including the
-input method mnemonic in its prompt, like this:
-
-@example
-I-search [@var{im}]:
-@end example
-
-@noindent
-@findex isearch-toggle-input-method
-@findex isearch-toggle-specified-input-method
-where @var{im} is the mnemonic of the active input method.
-
- You can toggle (enable or disable) the input method while you type
-the search string with @kbd{C-\} (@code{isearch-toggle-input-method}).
-You can turn on a certain (non-default) input method with @kbd{C-^}
-(@code{isearch-toggle-specified-input-method}), which prompts for the
-name of the input method. The input method you enable during
-incremental search remains enabled in the current buffer afterwards.
-
-@node Isearch Yank
-@subsection Isearch Yanking
-
- The characters @kbd{C-w} and @kbd{C-y} can be used in incremental
-search to grab text from the buffer into the search string. This
-makes it convenient to search for another occurrence of text at point.
-@kbd{C-w} copies the character or word after point as part of the
-search string, advancing point over it. (The decision, whether to
-copy a character or a word, is heuristic.) Another @kbd{C-s} to
-repeat the search will then search for a string including that
-character or word.
-
- @kbd{C-y} is similar to @kbd{C-w} but copies all the rest of the
-current line into the search string. If point is already at the end
-of a line, it grabs the entire next line. Both @kbd{C-y} and
-@kbd{C-w} convert the text they copy to lower case if the search is
-currently not case-sensitive; this is so the search remains
-case-insensitive.
-
- @kbd{C-M-w} and @kbd{C-M-y} modify the search string by only one
-character at a time: @kbd{C-M-w} deletes the last character from the
-search string and @kbd{C-M-y} copies the character after point to the
-end of the search string. An alternative method to add the character
-after point into the search string is to enter the minibuffer by
-@kbd{M-e} and to type @kbd{C-f} at the end of the search string in the
-minibuffer.
-
- The character @kbd{M-y} copies text from the kill ring into the search
-string. It uses the same text that @kbd{C-y} as a command would yank.
-@kbd{Mouse-2} in the echo area does the same.
-@xref{Yanking}.
-
-@node Highlight Isearch
-@subsection Lazy Search Highlighting
-@cindex lazy search highlighting
-@vindex isearch-lazy-highlight
-
- When you pause for a little while during incremental search, it
-highlights all other possible matches for the search string. This
-makes it easier to anticipate where you can get to by typing @kbd{C-s}
-or @kbd{C-r} to repeat the search. The short delay before highlighting
-other matches helps indicate which match is the current one.
-If you don't like this feature, you can turn it off by setting
-@code{isearch-lazy-highlight} to @code{nil}.
-
-@cindex faces for highlighting search matches
- You can control how this highlighting looks by customizing the faces
-@code{isearch} (used for the current match) and @code{lazy-highlight}
-(for all the other matches).
-
-@node Isearch Scroll
-@subsection Scrolling During Incremental Search
-
- You can enable the use of vertical scrolling during incremental
-search (without exiting the search) by setting the customizable
-variable @code{isearch-allow-scroll} to a non-@code{nil} value. This
-applies to using the vertical scroll-bar and to certain keyboard
-commands such as @kbd{@key{PRIOR}} (@code{scroll-down}),
-@kbd{@key{NEXT}} (@code{scroll-up}) and @kbd{C-l} (@code{recenter}).
-You must run these commands via their key sequences to stay in the
-search---typing @kbd{M-x} will terminate the search. You can give
-prefix arguments to these commands in the usual way.
-
- This feature won't let you scroll the current match out of visibility,
-however.
-
- The feature also affects some other commands, such as @kbd{C-x 2}
-(@code{split-window-vertically}) and @kbd{C-x ^}
-(@code{enlarge-window}) which don't exactly scroll but do affect where
-the text appears on the screen. In general, it applies to any command
-whose name has a non-@code{nil} @code{isearch-scroll} property. So you
-can control which commands are affected by changing these properties.
-
- For example, to make @kbd{C-h l} usable within an incremental search
-in all future Emacs sessions, use @kbd{C-h c} to find what command it
-runs. (You type @kbd{C-h c C-h l}; it says @code{view-lossage}.)
-Then you can put the following line in your @file{.emacs} file
-(@pxref{Init File}):
-
-@example
-(put 'view-lossage 'isearch-scroll t)
-@end example
-
-@noindent
-This feature can be applied to any command that doesn't permanently
-change point, the buffer contents, the match data, the current buffer,
-or the selected window and frame. The command must not itself attempt
-an incremental search.
-
-@node Slow Isearch
-@subsection Slow Terminal Incremental Search
-
- Incremental search on a slow terminal uses a modified style of display
-that is designed to take less time. Instead of redisplaying the buffer at
-each place the search gets to, it creates a new single-line window and uses
-that to display the line that the search has found. The single-line window
-comes into play as soon as point moves outside of the text that is already
-on the screen.
-
- When you terminate the search, the single-line window is removed.
-Emacs then redisplays the window in which the search was done, to show
-its new position of point.
-
-@vindex search-slow-speed
- The slow terminal style of display is used when the terminal baud rate is
-less than or equal to the value of the variable @code{search-slow-speed},
-initially 1200. See also the discussion of the variable @code{baud-rate}
-(@pxref{baud-rate,, Customization of Display}).
-
-@vindex search-slow-window-lines
- The number of lines to use in slow terminal search display is controlled
-by the variable @code{search-slow-window-lines}. Its normal value is 1.
-
-@node Nonincremental Search
-@section Nonincremental Search
-@cindex nonincremental search
-
- Emacs also has conventional nonincremental search commands, which require
-you to type the entire search string before searching begins.
-
-@table @kbd
-@item C-s @key{RET} @var{string} @key{RET}
-Search for @var{string}.
-@item C-r @key{RET} @var{string} @key{RET}
-Search backward for @var{string}.
-@end table
-
- To do a nonincremental search, first type @kbd{C-s @key{RET}}. This
-enters the minibuffer to read the search string; terminate the string
-with @key{RET}, and then the search takes place. If the string is not
-found, the search command signals an error.
-
- When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental
-search as usual. That command is specially programmed to invoke
-nonincremental search, @code{search-forward}, if the string you
-specify is empty. (Such an empty argument would otherwise be
-useless.) But it does not call @code{search-forward} right away. First
-it checks the next input character to see if is @kbd{C-w},
-which specifies a word search.
-@ifnottex
-@xref{Word Search}.
-@end ifnottex
-@kbd{C-r @key{RET}} does likewise, for a reverse incremental search.
-
-@findex search-forward
-@findex search-backward
- Forward and backward nonincremental searches are implemented by the
-commands @code{search-forward} and @code{search-backward}. These
-commands may be bound to keys in the usual manner. The feature that you
-can get to them via the incremental search commands exists for
-historical reasons, and to avoid the need to find separate key sequences
-for them.
-
-@node Word Search
-@section Word Search
-@cindex word search
-
- Word search searches for a sequence of words without regard to how the
-words are separated. More precisely, you type a string of many words,
-using single spaces to separate them, and the string can be found even
-if there are multiple spaces, newlines, or other punctuation characters
-between these words.
-
- Word search is useful for editing a printed document made with a text
-formatter. If you edit while looking at the printed, formatted version,
-you can't tell where the line breaks are in the source file. With word
-search, you can search without having to know them.
-
-@table @kbd
-@item C-s @key{RET} C-w @var{words} @key{RET}
-Search for @var{words}, ignoring details of punctuation.
-@item C-r @key{RET} C-w @var{words} @key{RET}
-Search backward for @var{words}, ignoring details of punctuation.
-@end table
-
- Word search as a special case of nonincremental search is invoked
-with @kbd{C-s @key{RET} C-w}. This is followed by the search string,
-which must always be terminated with @key{RET}. Being nonincremental,
-this search does not start until the argument is terminated. It works
-by constructing a regular expression and searching for that; see
-@ref{Regexp Search}.
-
- Use @kbd{C-r @key{RET} C-w} to do backward word search.
-
- You can also invoke word search with @kbd{C-s M-e C-w} or @kbd{C-r
-M-e C-w} followed by the search string and terminated with @key{RET},
-@kbd{C-s} or @kbd{C-r}. This puts word search into incremental mode
-where you can use all keys available for incremental search. However,
-when you type more words in incremental word search, it will fail
-until you type complete words.
-
-@findex word-search-forward
-@findex word-search-backward
- Forward and backward word searches are implemented by the commands
-@code{word-search-forward} and @code{word-search-backward}. These
-commands may be bound to keys in the usual manner. They are available
-via the incremental search commands both for historical reasons and
-to avoid the need to find separate key sequences for them.
-
-@node Regexp Search
-@section Regular Expression Search
-@cindex regular expression
-@cindex regexp
-
- A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern
-that denotes a class of alternative strings to match, possibly
-infinitely many. GNU Emacs provides both incremental and
-nonincremental ways to search for a match for a regexp. The syntax of
-regular expressions is explained in the following section.
-
-@kindex C-M-s
-@findex isearch-forward-regexp
-@kindex C-M-r
-@findex isearch-backward-regexp
- Incremental search for a regexp is done by typing @kbd{C-M-s}
-(@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a
-prefix argument (whose value does not matter), or by typing @kbd{M-r}
-within a forward incremental search. This command reads a
-search string incrementally just like @kbd{C-s}, but it treats the
-search string as a regexp rather than looking for an exact match
-against the text in the buffer. Each time you add text to the search
-string, you make the regexp longer, and the new regexp is searched
-for. To search backward for a regexp, use @kbd{C-M-r}
-(@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument,
-or @kbd{M-r} within a backward incremental search.
-
- All of the control characters that do special things within an
-ordinary incremental search have the same function in incremental regexp
-search. Typing @kbd{C-s} or @kbd{C-r} immediately after starting the
-search retrieves the last incremental search regexp used; that is to
-say, incremental regexp and non-regexp searches have independent
-defaults. They also have separate search rings that you can access with
-@kbd{M-p} and @kbd{M-n}.
-
-@vindex search-whitespace-regexp
- If you type @key{SPC} in incremental regexp search, it matches any
-sequence of whitespace characters, including newlines. If you want to
-match just a space, type @kbd{C-q @key{SPC}}. You can control what a
-bare space matches by setting the variable
-@code{search-whitespace-regexp} to the desired regexp.
-
- In some cases, adding characters to the regexp in an incremental regexp
-search can make the cursor move back and start again. For example, if
-you have searched for @samp{foo} and you add @samp{\|bar}, the cursor
-backs up in case the first @samp{bar} precedes the first @samp{foo}.
-
- Forward and backward regexp search are not symmetrical, because
-regexp matching in Emacs always operates forward, starting with the
-beginning of the regexp. Thus, forward regexp search scans forward,
-trying a forward match at each possible starting position. Backward
-regexp search scans backward, trying a forward match at each possible
-starting position. These search methods are not mirror images.
-
-@findex re-search-forward
-@findex re-search-backward
- Nonincremental search for a regexp is done by the functions
-@code{re-search-forward} and @code{re-search-backward}. You can invoke
-these with @kbd{M-x}, or bind them to keys, or invoke them by way of
-incremental regexp search with @kbd{C-M-s @key{RET}} and @kbd{C-M-r
-@key{RET}}.
-
- If you use the incremental regexp search commands with a prefix
-argument, they perform ordinary string search, like
-@code{isearch-forward} and @code{isearch-backward}. @xref{Incremental
-Search}.
-
-@node Regexps
-@section Syntax of Regular Expressions
-@cindex syntax of regexps
-
- This manual describes regular expression features that users
-typically want to use. There are additional features that are
-mainly used in Lisp programs; see @ref{Regular Expressions,,,
-elisp, The Emacs Lisp Reference Manual}.
-
- Regular expressions have a syntax in which a few characters are
-special constructs and the rest are @dfn{ordinary}. An ordinary
-character is a simple regular expression which matches that same
-character and nothing else. The special characters are @samp{$},
-@samp{^}, @samp{.}, @samp{*}, @samp{+}, @samp{?}, @samp{[}, and
-@samp{\}. The character @samp{]} is special if it ends a character
-alternative (see later). The character @samp{-} is special inside a
-character alternative. Any other character appearing in a regular
-expression is ordinary, unless a @samp{\} precedes it. (When you use
-regular expressions in a Lisp program, each @samp{\} must be doubled,
-see the example near the end of this section.)
-
- For example, @samp{f} is not a special character, so it is ordinary, and
-therefore @samp{f} is a regular expression that matches the string
-@samp{f} and no other string. (It does @emph{not} match the string
-@samp{ff}.) Likewise, @samp{o} is a regular expression that matches
-only @samp{o}. (When case distinctions are being ignored, these regexps
-also match @samp{F} and @samp{O}, but we consider this a generalization
-of ``the same string,'' rather than an exception.)
-
- Any two regular expressions @var{a} and @var{b} can be concatenated. The
-result is a regular expression which matches a string if @var{a} matches
-some amount of the beginning of that string and @var{b} matches the rest of
-the string.@refill
-
- As a simple example, we can concatenate the regular expressions @samp{f}
-and @samp{o} to get the regular expression @samp{fo}, which matches only
-the string @samp{fo}. Still trivial. To do something nontrivial, you
-need to use one of the special characters. Here is a list of them.
-
-@table @asis
-@item @kbd{.}@: @r{(Period)}
-is a special character that matches any single character except a newline.
-Using concatenation, we can make regular expressions like @samp{a.b}, which
-matches any three-character string that begins with @samp{a} and ends with
-@samp{b}.@refill
-
-@item @kbd{*}
-is not a construct by itself; it is a postfix operator that means to
-match the preceding regular expression repetitively as many times as
-possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
-@samp{o}s).
-
-@samp{*} always applies to the @emph{smallest} possible preceding
-expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
-@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
-
-The matcher processes a @samp{*} construct by matching, immediately,
-as many repetitions as can be found. Then it continues with the rest
-of the pattern. If that fails, backtracking occurs, discarding some
-of the matches of the @samp{*}-modified construct in case that makes
-it possible to match the rest of the pattern. For example, in matching
-@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
-tries to match all three @samp{a}s; but the rest of the pattern is
-@samp{ar} and there is only @samp{r} left to match, so this try fails.
-The next alternative is for @samp{a*} to match only two @samp{a}s.
-With this choice, the rest of the regexp matches successfully.@refill
-
-@item @kbd{+}
-is a postfix operator, similar to @samp{*} except that it must match
-the preceding expression at least once. So, for example, @samp{ca+r}
-matches the strings @samp{car} and @samp{caaaar} but not the string
-@samp{cr}, whereas @samp{ca*r} matches all three strings.
-
-@item @kbd{?}
-is a postfix operator, similar to @samp{*} except that it can match the
-preceding expression either once or not at all. For example,
-@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
-
-@item @kbd{*?}, @kbd{+?}, @kbd{??}
-@cindex non-greedy regexp matching
-are non-greedy variants of the operators above. The normal operators
-@samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as
-much as they can, as long as the overall regexp can still match. With
-a following @samp{?}, they are non-greedy: they will match as little
-as possible.
-
-Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a}
-and the string @samp{abbbb}; but if you try to match them both against
-the text @samp{abbb}, @samp{ab*} will match it all (the longest valid
-match), while @samp{ab*?} will match just @samp{a} (the shortest
-valid match).
-
-Non-greedy operators match the shortest possible string starting at a
-given starting point; in a forward search, though, the earliest
-possible starting point for match is always the one chosen. Thus, if
-you search for @samp{a.*?$} against the text @samp{abbab} followed by
-a newline, it matches the whole string. Since it @emph{can} match
-starting at the first @samp{a}, it does.
-
-@item @kbd{\@{@var{n}\@}}
-is a postfix operator that specifies repetition @var{n} times---that
-is, the preceding regular expression must match exactly @var{n} times
-in a row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx}
-and nothing else.
-
-@item @kbd{\@{@var{n},@var{m}\@}}
-is a postfix operator that specifies repetition between @var{n} and
-@var{m} times---that is, the preceding regular expression must match
-at least @var{n} times, but no more than @var{m} times. If @var{m} is
-omitted, then there is no upper limit, but the preceding regular
-expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is
-equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to
-@samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}.
-
-@item @kbd{[ @dots{} ]}
-is a @dfn{character set}, which begins with @samp{[} and is terminated
-by @samp{]}. In the simplest case, the characters between the two
-brackets are what this set can match.
-
-Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
-@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
-(including the empty string), from which it follows that @samp{c[ad]*r}
-matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
-
-You can also include character ranges in a character set, by writing the
-starting and ending characters with a @samp{-} between them. Thus,
-@samp{[a-z]} matches any lower-case @acronym{ASCII} letter. Ranges may be
-intermixed freely with individual characters, as in @samp{[a-z$%.]},
-which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or
-period.
-
-Note that the usual regexp special characters are not special inside a
-character set. A completely different set of special characters exists
-inside character sets: @samp{]}, @samp{-} and @samp{^}.
-
-To include a @samp{]} in a character set, you must make it the first
-character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To
-include a @samp{-}, write @samp{-} as the first or last character of the
-set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]}
-and @samp{-}.
-
-To include @samp{^} in a set, put it anywhere but at the beginning of
-the set. (At the beginning, it complements the set---see below.)
-
-When you use a range in case-insensitive search, you should write both
-ends of the range in upper case, or both in lower case, or both should
-be non-letters. The behavior of a mixed-case range such as @samp{A-z}
-is somewhat ill-defined, and it may change in future Emacs versions.
-
-@item @kbd{[^ @dots{} ]}
-@samp{[^} begins a @dfn{complemented character set}, which matches any
-character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches
-all characters @emph{except} @acronym{ASCII} letters and digits.
-
-@samp{^} is not special in a character set unless it is the first
-character. The character following the @samp{^} is treated as if it
-were first (in other words, @samp{-} and @samp{]} are not special there).
-
-A complemented character set can match a newline, unless newline is
-mentioned as one of the characters not to match. This is in contrast to
-the handling of regexps in programs such as @code{grep}.
-
-@item @kbd{^}
-is a special character that matches the empty string, but only at the
-beginning of a line in the text being matched. Otherwise it fails to
-match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at
-the beginning of a line.
-
-For historical compatibility reasons, @samp{^} can be used with this
-meaning only at the beginning of the regular expression, or after
-@samp{\(} or @samp{\|}.
-
-@item @kbd{$}
-is similar to @samp{^} but matches only at the end of a line. Thus,
-@samp{x+$} matches a string of one @samp{x} or more at the end of a line.
-
-For historical compatibility reasons, @samp{$} can be used with this
-meaning only at the end of the regular expression, or before @samp{\)}
-or @samp{\|}.
-
-@item @kbd{\}
-has two functions: it quotes the special characters (including
-@samp{\}), and it introduces additional special constructs.
-
-Because @samp{\} quotes special characters, @samp{\$} is a regular
-expression that matches only @samp{$}, and @samp{\[} is a regular
-expression that matches only @samp{[}, and so on.
-
-See the following section for the special constructs that begin
-with @samp{\}.
-@end table
-
- Note: for historical compatibility, special characters are treated as
-ordinary ones if they are in contexts where their special meanings make no
-sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is
-no preceding expression on which the @samp{*} can act. It is poor practice
-to depend on this behavior; it is better to quote the special character anyway,
-regardless of where it appears.
-
-As a @samp{\} is not special inside a character alternative, it can
-never remove the special meaning of @samp{-} or @samp{]}. So you
-should not quote these characters when they have no special meaning
-either. This would not clarify anything, since backslashes can
-legitimately precede these characters where they @emph{have} special
-meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
-which matches any single character except a backslash.
-
-@node Regexp Backslash
-@section Backslash in Regular Expressions
-
- For the most part, @samp{\} followed by any character matches only
-that character. However, there are several exceptions: two-character
-sequences starting with @samp{\} that have special meanings. The
-second character in the sequence is always an ordinary character when
-used on its own. Here is a table of @samp{\} constructs.
-
-@table @kbd
-@item \|
-specifies an alternative. Two regular expressions @var{a} and @var{b}
-with @samp{\|} in between form an expression that matches some text if
-either @var{a} matches it or @var{b} matches it. It works by trying to
-match @var{a}, and if that fails, by trying to match @var{b}.
-
-Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
-but no other string.@refill
-
-@samp{\|} applies to the largest possible surrounding expressions. Only a
-surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
-@samp{\|}.@refill
-
-Full backtracking capability exists to handle multiple uses of @samp{\|}.
-
-@item \( @dots{} \)
-is a grouping construct that serves three purposes:
-
-@enumerate
-@item
-To enclose a set of @samp{\|} alternatives for other operations.
-Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
-
-@item
-To enclose a complicated expression for the postfix operators @samp{*},
-@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
-@samp{bananana}, etc., with any (zero or more) number of @samp{na}
-strings.@refill
-
-@item
-To record a matched substring for future reference.
-@end enumerate
-
-This last application is not a consequence of the idea of a
-parenthetical grouping; it is a separate feature that is assigned as a
-second meaning to the same @samp{\( @dots{} \)} construct. In practice
-there is usually no conflict between the two meanings; when there is
-a conflict, you can use a ``shy'' group.
-
-@item \(?: @dots{} \)
-@cindex shy group, in regexp
-specifies a ``shy'' group that does not record the matched substring;
-you can't refer back to it with @samp{\@var{d}}. This is useful
-in mechanically combining regular expressions, so that you
-can add groups for syntactic purposes without interfering with
-the numbering of the groups that are meant to be referred to.
-
-@item \@var{d}
-@cindex back reference, in regexp
-matches the same text that matched the @var{d}th occurrence of a
-@samp{\( @dots{} \)} construct. This is called a @dfn{back
-reference}.
-
-After the end of a @samp{\( @dots{} \)} construct, the matcher remembers
-the beginning and end of the text matched by that construct. Then,
-later on in the regular expression, you can use @samp{\} followed by the
-digit @var{d} to mean ``match the same text matched the @var{d}th time
-by the @samp{\( @dots{} \)} construct.''
-
-The strings matching the first nine @samp{\( @dots{} \)} constructs
-appearing in a regular expression are assigned numbers 1 through 9 in
-the order that the open-parentheses appear in the regular expression.
-So you can use @samp{\1} through @samp{\9} to refer to the text matched
-by the corresponding @samp{\( @dots{} \)} constructs.
-
-For example, @samp{\(.*\)\1} matches any newline-free string that is
-composed of two identical halves. The @samp{\(.*\)} matches the first
-half, which may be anything, but the @samp{\1} that follows must match
-the same exact text.
-
-If a particular @samp{\( @dots{} \)} construct matches more than once
-(which can easily happen if it is followed by @samp{*}), only the last
-match is recorded.
-
-@item \`
-matches the empty string, but only at the beginning of the string or
-buffer (or its accessible portion) being matched against.
-
-@item \'
-matches the empty string, but only at the end of the string or buffer
-(or its accessible portion) being matched against.
-
-@item \=
-matches the empty string, but only at point.
-
-@item \b
-matches the empty string, but only at the beginning or
-end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
-@samp{foo} as a separate word. @samp{\bballs?\b} matches
-@samp{ball} or @samp{balls} as a separate word.@refill
-
-@samp{\b} matches at the beginning or end of the buffer
-regardless of what text appears next to it.
-
-@item \B
-matches the empty string, but @emph{not} at the beginning or
-end of a word.
-
-@item \<
-matches the empty string, but only at the beginning of a word.
-@samp{\<} matches at the beginning of the buffer only if a
-word-constituent character follows.
-
-@item \>
-matches the empty string, but only at the end of a word. @samp{\>}
-matches at the end of the buffer only if the contents end with a
-word-constituent character.
-
-@item \w
-matches any word-constituent character. The syntax table
-determines which characters these are. @xref{Syntax}.
-
-@item \W
-matches any character that is not a word-constituent.
-
-@item \_<
-matches the empty string, but only at the beginning of a symbol.
-A symbol is a sequence of one or more symbol-constituent characters.
-A symbol-constituent character is a character whose syntax is either
-@samp{w} or @samp{_}. @samp{\_<} matches at the beginning of the
-buffer only if a symbol-constituent character follows.
-
-@item \_>
-matches the empty string, but only at the end of a symbol. @samp{\_>}
-matches at the end of the buffer only if the contents end with a
-symbol-constituent character.
-
-@item \s@var{c}
-matches any character whose syntax is @var{c}. Here @var{c} is a
-character that designates a particular syntax class: thus, @samp{w}
-for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.}
-for ordinary punctuation, etc. @xref{Syntax}.
-
-@item \S@var{c}
-matches any character whose syntax is not @var{c}.
-
-@cindex categories of characters
-@cindex characters which belong to a specific language
-@findex describe-categories
-@item \c@var{c}
-matches any character that belongs to the category @var{c}. For
-example, @samp{\cc} matches Chinese characters, @samp{\cg} matches
-Greek characters, etc. For the description of the known categories,
-type @kbd{M-x describe-categories @key{RET}}.
-
-@item \C@var{c}
-matches any character that does @emph{not} belong to category
-@var{c}.
-@end table
-
- The constructs that pertain to words and syntax are controlled by the
-setting of the syntax table (@pxref{Syntax}).
-
-@node Regexp Example
-@section Regular Expression Example
-
- Here is a complicated regexp---a simplified version of the regexp
-that Emacs uses, by default, to recognize the end of a sentence
-together with any whitespace that follows. We show its Lisp syntax to
-distinguish the spaces from the tab characters. In Lisp syntax, the
-string constant begins and ends with a double-quote. @samp{\"} stands
-for a double-quote as part of the regexp, @samp{\\} for a backslash as
-part of the regexp, @samp{\t} for a tab, and @samp{\n} for a newline.
-
-@example
-"[.?!][]\"')]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
-@end example
-
-@noindent
-This contains four parts in succession: a character set matching
-period, @samp{?}, or @samp{!}; a character set matching
-close-brackets, quotes, or parentheses, repeated zero or more times; a
-set of alternatives within backslash-parentheses that matches either
-end-of-line, a space at the end of a line, a tab, or two spaces; and a
-character set matching whitespace characters, repeated any number of
-times.
-
- To enter the same regexp in incremental search, you would type
-@key{TAB} to enter a tab, and @kbd{C-j} to enter a newline. You would
-also type single backslashes as themselves, instead of doubling them
-for Lisp syntax. In commands that use ordinary minibuffer input to
-read a regexp, you would quote the @kbd{C-j} by preceding it with a
-@kbd{C-q} to prevent @kbd{C-j} from exiting the minibuffer.
-
-@node Search Case
-@section Searching and Case
-
- Incremental searches in Emacs normally ignore the case of the text
-they are searching through, if you specify the text in lower case.
-Thus, if you specify searching for @samp{foo}, then @samp{Foo} and
-@samp{foo} are also considered a match. Regexps, and in particular
-character sets, are included: @samp{[ab]} would match @samp{a} or
-@samp{A} or @samp{b} or @samp{B}.@refill
-
- An upper-case letter anywhere in the incremental search string makes
-the search case-sensitive. Thus, searching for @samp{Foo} does not find
-@samp{foo} or @samp{FOO}. This applies to regular expression search as
-well as to string search. The effect ceases if you delete the
-upper-case letter from the search string.
-
- Typing @kbd{M-c} within an incremental search toggles the case
-sensitivity of that search. The effect does not extend beyond the
-current incremental search to the next one, but it does override the
-effect of including an upper-case letter in the current search.
-
-@vindex case-fold-search
-@vindex default-case-fold-search
- If you set the variable @code{case-fold-search} to @code{nil}, then
-all letters must match exactly, including case. This is a per-buffer
-variable; altering the variable affects only the current buffer, but
-there is a default value in @code{default-case-fold-search} that you
-can also set. @xref{Locals}. This variable applies to nonincremental
-searches also, including those performed by the replace commands
-(@pxref{Replace}) and the minibuffer history matching commands
-(@pxref{Minibuffer History}).
-
- Several related variables control case-sensitivity of searching and
-matching for specific commands or activities. For instance,
-@code{tags-case-fold-search} controls case sensitivity for
-@code{find-tag}. To find these variables, do @kbd{M-x
-apropos-variable @key{RET} case-fold-search @key{RET}}.
-
-@node Replace
-@section Replacement Commands
-@cindex replacement
-@cindex search-and-replace commands
-@cindex string substitution
-@cindex global substitution
-
- Global search-and-replace operations are not needed often in Emacs,
-but they are available. In addition to the simple @kbd{M-x
-replace-string} command which replaces all occurrences,
-there is @kbd{M-%} (@code{query-replace}), which presents each occurrence
-of the pattern and asks you whether to replace it.
-
- The replace commands normally operate on the text from point to the
-end of the buffer; however, in Transient Mark mode (@pxref{Transient
-Mark}), when the mark is active, they operate on the region. The
-basic replace commands replace one string (or regexp) with one
-replacement string. It is possible to perform several replacements in
-parallel using the command @code{expand-region-abbrevs}
-(@pxref{Expanding Abbrevs}).
-
-@menu
-* Unconditional Replace:: Replacing all matches for a string.
-* Regexp Replace:: Replacing all matches for a regexp.
-* Replacement and Case:: How replacements preserve case of letters.
-* Query Replace:: How to use querying.
-@end menu
-
-@node Unconditional Replace, Regexp Replace, Replace, Replace
-@subsection Unconditional Replacement
-@findex replace-string
-
-@table @kbd
-@item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
-Replace every occurrence of @var{string} with @var{newstring}.
-@end table
-
- To replace every instance of @samp{foo} after point with @samp{bar},
-use the command @kbd{M-x replace-string} with the two arguments
-@samp{foo} and @samp{bar}. Replacement happens only in the text after
-point, so if you want to cover the whole buffer you must go to the
-beginning first. All occurrences up to the end of the buffer are
-replaced; to limit replacement to part of the buffer, narrow to that
-part of the buffer before doing the replacement (@pxref{Narrowing}).
-In Transient Mark mode, when the region is active, replacement is
-limited to the region (@pxref{Transient Mark}).
-
- When @code{replace-string} exits, it leaves point at the last
-occurrence replaced. It sets the mark to the prior position of point
-(where the @code{replace-string} command was issued); use @kbd{C-u
-C-@key{SPC}} to move back there.
-
- A numeric argument restricts replacement to matches that are surrounded
-by word boundaries. The argument's value doesn't matter.
-
- @xref{Replacement and Case}, for details about case-sensitivity in
-replace commands.
-
- What if you want to exchange @samp{x} and @samp{y}: replace every @samp{x} with a @samp{y} and vice versa? You can do it this way:
-
-@example
-M-x replace-string @key{RET} x @key{RET} @@TEMP@@ @key{RET}
-M-< M-x replace-string @key{RET} y @key{RET} x @key{RET}
-M-< M-x replace-string @key{RET} @@TEMP@@ @key{RET} y @key{RET}
-@end example
-
-@noindent
-This works provided the string @samp{@@TEMP@@} does not appear
-in your text.
-
-@node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
-@subsection Regexp Replacement
-@findex replace-regexp
-
- The @kbd{M-x replace-string} command replaces exact matches for a
-single string. The similar command @kbd{M-x replace-regexp} replaces
-any match for a specified pattern.
-
-@table @kbd
-@item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
-Replace every match for @var{regexp} with @var{newstring}.
-@end table
-
-@cindex back reference, in regexp replacement
- In @code{replace-regexp}, the @var{newstring} need not be constant:
-it can refer to all or part of what is matched by the @var{regexp}.
-@samp{\&} in @var{newstring} stands for the entire match being
-replaced. @samp{\@var{d}} in @var{newstring}, where @var{d} is a
-digit, stands for whatever matched the @var{d}th parenthesized
-grouping in @var{regexp}. (This is called a ``back reference.'')
-@samp{\#} refers to the count of replacements already made in this
-command, as a decimal number. In the first replacement, @samp{\#}
-stands for @samp{0}; in the second, for @samp{1}; and so on. For
-example,
-
-@example
-M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
-@end example
-
-@noindent
-replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
-with @samp{cddr-safe}.
-
-@example
-M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
-@end example
-
-@noindent
-performs the inverse transformation. To include a @samp{\} in the
-text to replace with, you must enter @samp{\\}.
-
- If you want to enter part of the replacement string by hand each
-time, use @samp{\?} in the replacement string. Each replacement will
-ask you to edit the replacement string in the minibuffer, putting
-point where the @samp{\?} was.
-
- The remainder of this subsection is intended for specialized tasks
-and requires knowledge of Lisp. Most readers can skip it.
-
- You can use Lisp expressions to calculate parts of the
-replacement string. To do this, write @samp{\,} followed by the
-expression in the replacement string. Each replacement calculates the
-value of the expression and converts it to text without quoting (if
-it's a string, this means using the string's contents), and uses it in
-the replacement string in place of the expression itself. If the
-expression is a symbol, one space in the replacement string after the
-symbol name goes with the symbol name, so the value replaces them
-both.
-
- Inside such an expression, you can use some special sequences.
-@samp{\&} and @samp{\@var{n}} refer here, as usual, to the entire
-match as a string, and to a submatch as a string. @var{n} may be
-multiple digits, and the value of @samp{\@var{n}} is @code{nil} if
-subexpression @var{n} did not match. You can also use @samp{\#&} and
-@samp{\#@var{n}} to refer to those matches as numbers (this is valid
-when the match or submatch has the form of a numeral). @samp{\#} here
-too stands for the number of already-completed replacements.
-
- Repeating our example to exchange @samp{x} and @samp{y}, we can thus
-do it also this way:
-
-@example
-M-x replace-regexp @key{RET} \(x\)\|y @key{RET}
-\,(if \1 "y" "x") @key{RET}
-@end example
-
- For computing replacement strings for @samp{\,}, the @code{format}
-function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs
-Lisp Reference Manual}). For example, to add consecutively numbered
-strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are
-already occupied), you can use
-
-@example
-M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET}
-\,(format "%-72sABC%05d" \& \#) @key{RET}
-@end example
-
-@node Replacement and Case, Query Replace, Regexp Replace, Replace
-@subsection Replace Commands and Case
-
- If the first argument of a replace command is all lower case, the
-command ignores case while searching for occurrences to
-replace---provided @code{case-fold-search} is non-@code{nil}. If
-@code{case-fold-search} is set to @code{nil}, case is always significant
-in all searches.
-
-@vindex case-replace
- In addition, when the @var{newstring} argument is all or partly lower
-case, replacement commands try to preserve the case pattern of each
-occurrence. Thus, the command
-
-@example
-M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
-@end example
-
-@noindent
-replaces a lower case @samp{foo} with a lower case @samp{bar}, an
-all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with
-@samp{Bar}. (These three alternatives---lower case, all caps, and
-capitalized, are the only ones that @code{replace-string} can
-distinguish.)
-
- If upper-case letters are used in the replacement string, they remain
-upper case every time that text is inserted. If upper-case letters are
-used in the first argument, the second argument is always substituted
-exactly as given, with no case conversion. Likewise, if either
-@code{case-replace} or @code{case-fold-search} is set to @code{nil},
-replacement is done without case conversion.
-
-@node Query Replace,, Replacement and Case, Replace
-@subsection Query Replace
-@cindex query replace
-
-@table @kbd
-@item M-% @var{string} @key{RET} @var{newstring} @key{RET}
-@itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
-Replace some occurrences of @var{string} with @var{newstring}.
-@item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET}
-@itemx M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
-Replace some matches for @var{regexp} with @var{newstring}.
-@end table
-
-@kindex M-%
-@findex query-replace
- If you want to change only some of the occurrences of @samp{foo} to
-@samp{bar}, not all of them, then you cannot use an ordinary
-@code{replace-string}. Instead, use @kbd{M-%} (@code{query-replace}).
-This command finds occurrences of @samp{foo} one by one, displays each
-occurrence and asks you whether to replace it. Aside from querying,
-@code{query-replace} works just like @code{replace-string}. It
-preserves case, like @code{replace-string}, provided
-@code{case-replace} is non-@code{nil}, as it normally is
-(@pxref{Replacement and Case}). A numeric argument means consider
-only occurrences that are bounded by word-delimiter characters.
-
-@kindex C-M-%
-@findex query-replace-regexp
- @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}).
-It works like @code{replace-regexp} except that it queries
-like @code{query-replace}.
-
-@cindex faces for highlighting query replace
- These commands highlight the current match using the face
-@code{query-replace}. They highlight other matches using
-@code{lazy-highlight} just like incremental search (@pxref{Incremental
-Search}).
-
- The characters you can type when you are shown a match for the string
-or regexp are:
-
-@ignore @c Not worth it.
-@kindex SPC @r{(query-replace)}
-@kindex DEL @r{(query-replace)}
-@kindex , @r{(query-replace)}
-@kindex RET @r{(query-replace)}
-@kindex . @r{(query-replace)}
-@kindex ! @r{(query-replace)}
-@kindex ^ @r{(query-replace)}
-@kindex C-r @r{(query-replace)}
-@kindex C-w @r{(query-replace)}
-@kindex C-l @r{(query-replace)}
-@end ignore
-
-@c WideCommands
-@table @kbd
-@item @key{SPC}
-to replace the occurrence with @var{newstring}.
-
-@item @key{DEL}
-to skip to the next occurrence without replacing this one.
-
-@item , @r{(Comma)}
-to replace this occurrence and display the result. You are then asked
-for another input character to say what to do next. Since the
-replacement has already been made, @key{DEL} and @key{SPC} are
-equivalent in this situation; both move to the next occurrence.
-
-You can type @kbd{C-r} at this point (see below) to alter the replaced
-text. You can also type @kbd{C-x u} to undo the replacement; this exits
-the @code{query-replace}, so if you want to do further replacement you
-must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart
-(@pxref{Repetition}).
-
-@item @key{RET}
-to exit without doing any more replacements.
-
-@item .@: @r{(Period)}
-to replace this occurrence and then exit without searching for more
-occurrences.
-
-@item !
-to replace all remaining occurrences without asking again.
-
-@item ^
-to go back to the position of the previous occurrence (or what used to
-be an occurrence), in case you changed it by mistake or want to
-reexamine it.
-
-@item C-r
-to enter a recursive editing level, in case the occurrence needs to be
-edited rather than just replaced with @var{newstring}. When you are
-done, exit the recursive editing level with @kbd{C-M-c} to proceed to
-the next occurrence. @xref{Recursive Edit}.
-
-@item C-w
-to delete the occurrence, and then enter a recursive editing level as in
-@kbd{C-r}. Use the recursive edit to insert text to replace the deleted
-occurrence of @var{string}. When done, exit the recursive editing level
-with @kbd{C-M-c} to proceed to the next occurrence.
-
-@item e
-to edit the replacement string in the minibuffer. When you exit the
-minibuffer by typing @key{RET}, the minibuffer contents replace the
-current occurrence of the pattern. They also become the new
-replacement string for any further occurrences.
-
-@item C-l
-to redisplay the screen. Then you must type another character to
-specify what to do with this occurrence.
-
-@item C-h
-to display a message summarizing these options. Then you must type
-another character to specify what to do with this occurrence.
-@end table
-
- Some other characters are aliases for the ones listed above: @kbd{y},
-@kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and
-@key{RET}.
-
- Aside from this, any other character exits the @code{query-replace},
-and is then reread as part of a key sequence. Thus, if you type
-@kbd{C-k}, it exits the @code{query-replace} and then kills to end of
-line.
-
- To restart a @code{query-replace} once it is exited, use @kbd{C-x
-@key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it
-used the minibuffer to read its arguments. @xref{Repetition, C-x ESC
-ESC}.
-
- @xref{Operating on Files}, for the Dired @kbd{Q} command which
-performs query replace on selected files. See also @ref{Transforming
-File Names}, for Dired commands to rename, copy, or link files by
-replacing regexp matches in file names.
-
-@node Other Repeating Search
-@section Other Search-and-Loop Commands
-
- Here are some other commands that find matches for a regular
-expression. They all ignore case in matching, if the pattern contains
-no upper-case letters and @code{case-fold-search} is non-@code{nil}.
-Aside from @code{occur} and its variants, all operate on the text from
-point to the end of the buffer, or on the active region in Transient
-Mark mode.
-
-@findex list-matching-lines
-@findex occur
-@findex multi-occur
-@findex multi-occur-in-matching-buffers
-@findex how-many
-@findex delete-non-matching-lines
-@findex delete-matching-lines
-@findex flush-lines
-@findex keep-lines
-
-@table @kbd
-@item M-x occur @key{RET} @var{regexp} @key{RET}
-Display a list showing each line in the buffer that contains a match
-for @var{regexp}. To limit the search to part of the buffer, narrow
-to that part (@pxref{Narrowing}). A numeric argument @var{n}
-specifies that @var{n} lines of context are to be displayed before and
-after each matching line. Currently, @code{occur} can not correctly
-handle multiline matches.
-
-@kindex RET @r{(Occur mode)}
-@kindex o @r{(Occur mode)}
-@kindex C-o @r{(Occur mode)}
-The buffer @samp{*Occur*} containing the output serves as a menu for
-finding the occurrences in their original context. Click
-@kbd{Mouse-2} on an occurrence listed in @samp{*Occur*}, or position
-point there and type @key{RET}; this switches to the buffer that was
-searched and moves point to the original of the chosen occurrence.
-@kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o}
-does not select it.
-
-After using @kbd{M-x occur}, you can use @code{next-error} to visit
-the occurrences found, one by one. @ref{Compilation Mode}.
-
-@item M-x list-matching-lines
-Synonym for @kbd{M-x occur}.
-
-@item M-x multi-occur @key{RET} @var{buffers} @key{RET} @var{regexp} @key{RET}
-This function is just like @code{occur}, except it is able to search
-through multiple buffers. It asks you to specify the buffer names one by one.
-
-@item M-x multi-occur-in-matching-buffers @key{RET} @var{bufregexp} @key{RET} @var{regexp} @key{RET}
-This function is similar to @code{multi-occur}, except the buffers to
-search are specified by a regular expression that matches visited
-file names. With a prefix argument, it uses the regular expression to match
-buffer names instead.
-
-@item M-x how-many @key{RET} @var{regexp} @key{RET}
-Print the number of matches for @var{regexp} that exist in the buffer
-after point. In Transient Mark mode, if the region is active, the
-command operates on the region instead.
-
-@item M-x flush-lines @key{RET} @var{regexp} @key{RET}
-This command deletes each line that contains a match for @var{regexp},
-operating on the text after point; it deletes the current line
-if it contains a match starting after point. In Transient Mark mode,
-if the region is active, the command operates on the region instead;
-it deletes a line partially contained in the region if it contains a
-match entirely contained in the region.
-
-If a match is split across lines, @code{flush-lines} deletes all those
-lines. It deletes the lines before starting to look for the next
-match; hence, it ignores a match starting on the same line at which
-another match ended.
-
-@item M-x keep-lines @key{RET} @var{regexp} @key{RET}
-This command deletes each line that @emph{does not} contain a match for
-@var{regexp}, operating on the text after point; if point is not at the
-beginning of a line, it always keeps the current line. In Transient
-Mark mode, if the region is active, the command operates on the region
-instead; it never deletes lines that are only partially contained in
-the region (a newline that ends a line counts as part of that line).
-
-If a match is split across lines, this command keeps all those lines.
-@end table
-
-@ignore
- arch-tag: fd9d8e77-66af-491c-b212-d80999613e3e
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Sending Mail
-@chapter Sending Mail
-@cindex sending mail
-@cindex mail
-@cindex message
-
- To send a message in Emacs, you start by typing a command (@kbd{C-x m})
-to select and initialize the @samp{*mail*} buffer. Then you edit the text
-and headers of the message in this buffer, and type another command
-(@kbd{C-c C-s} or @kbd{C-c C-c}) to send the message.
-
-@table @kbd
-@item C-x m
-Begin composing a message to send (@code{compose-mail}).
-@item C-x 4 m
-Likewise, but display the message in another window
-(@code{compose-mail-other-window}).
-@item C-x 5 m
-Likewise, but make a new frame (@code{compose-mail-other-frame}).
-@item C-c C-s
-In Mail mode, send the message (@code{mail-send}).
-@item C-c C-c
-Send the message and bury the mail buffer (@code{mail-send-and-exit}).
-@end table
-
-@kindex C-x m
-@findex compose-mail
-@kindex C-x 4 m
-@findex compose-mail-other-window
-@kindex C-x 5 m
-@findex compose-mail-other-frame
- The command @kbd{C-x m} (@code{compose-mail}) selects a buffer named
-@samp{*mail*} and initializes it with the skeleton of an outgoing
-message. @kbd{C-x 4 m} (@code{compose-mail-other-window}) selects the
-@samp{*mail*} buffer in a different window, leaving the previous current
-buffer visible. @kbd{C-x 5 m} (@code{compose-mail-other-frame}) creates
-a new frame to select the @samp{*mail*} buffer.
-
- Because the mail-composition buffer is an ordinary Emacs buffer, you can
-switch to other buffers while in the middle of composing mail, and switch
-back later (or never). If you use the @kbd{C-x m} command again when you
-have been composing another message but have not sent it, you are asked to
-confirm before the old message is erased. If you answer @kbd{n}, the
-@samp{*mail*} buffer remains selected with its old contents, so you can
-finish the old message and send it. @kbd{C-u C-x m} is another way to do
-this. Sending the message marks the @samp{*mail*} buffer ``unmodified,''
-which avoids the need for confirmation when @kbd{C-x m} is next used.
-
- If you are composing a message in the @samp{*mail*} buffer and want to
-send another message before finishing the first, rename the
-@samp{*mail*} buffer using @kbd{M-x rename-uniquely} (@pxref{Misc
-Buffer}). Then you can use @kbd{C-x m} or its variants described above
-to make a new @samp{*mail*} buffer. Once you've done that, you can work
-with each mail buffer independently.
-
-@vindex mail-default-directory
- The variable @code{mail-default-directory} controls the default
-directory for mail buffers, and also says where to put their auto-save
-files.
-
-@ignore
-@c Commented out because it is not user-oriented;
-@c it doesn't say how to do some job. -- rms.
-@cindex directory servers
-@cindex LDAP
-@cindex PH/QI
-@cindex names and addresses
-There is an interface to directory servers using various protocols such
-as LDAP or the CCSO white pages directory system (PH/QI), described in a
-separate manual. It may be useful for looking up names and addresses.
-@xref{Top,,EUDC, eudc, EUDC Manual}.
-@end ignore
-
-@menu
-* Format: Mail Format. Format of the mail being composed.
-* Headers: Mail Headers. Details of permitted mail header fields.
-* Aliases: Mail Aliases. Abbreviating and grouping mail addresses.
-* Mode: Mail Mode. Special commands for editing mail being composed.
-* Amuse: Mail Amusements. Distracting the NSA; adding fortune messages.
-* Methods: Mail Methods. Using alternative mail-composition methods.
-@end menu
-
-@node Mail Format
-@section The Format of the Mail Buffer
-
- In addition to the @dfn{text} or @dfn{body}, a message has @dfn{header
-fields} which say who sent it, when, to whom, why, and so on. Some
-header fields, such as @samp{Date} and @samp{Sender}, are created
-automatically when you send the message. Others, such as the recipient
-names, must be specified by you in order to send the message properly.
-
- In the mail buffer, you can insert and edit header fields using
-ordinary editing commands. Mail mode provides a commands to help you
-edit some header fields, and some are preinitialized in the buffer
-automatically when appropriate.
-
- The line in the buffer that says
-
-@example
---text follows this line--
-@end example
-
-@noindent
-is a special delimiter that separates the headers you have specified from
-the text. Whatever follows this line is the text of the message; the
-headers precede it. The delimiter line itself does not appear in the
-message actually sent. The text used for the delimiter line is controlled
-by the variable @code{mail-header-separator}.
-
- Here is an example of what the headers and text in the mail buffer
-might look like.
-
-@example
-To: gnu@@gnu.org
-CC: lungfish@@spam.org, byob@@spam.org
-Subject: The Emacs Manual
---Text follows this line--
-Please ignore this message.
-@end example
-
-@node Mail Headers
-@section Mail Header Fields
-@cindex headers (of mail message)
-
- A header field in the mail buffer starts with a field name at the
-beginning of a line, terminated by a colon. Upper and lower case are
-equivalent in field names (and in mailing addresses also). After the
-colon and optional whitespace comes the contents of the field.
-
- You can use any name you like for a header field, but normally people
-use only standard field names with accepted meanings. Here is a table
-of fields commonly used in outgoing messages.
-
-@table @samp
-@item To
-This field contains the mailing addresses to which the message is
-addressed. If you list more than one address, use commas, not spaces,
-to separate them.
-
-@item Subject
-The contents of the @samp{Subject} field should be a piece of text
-that says what the message is about. The reason @samp{Subject} fields
-are useful is that most mail-reading programs can provide a summary of
-messages, listing the subject of each message but not its text.
-
-@item CC
-This field contains additional mailing addresses to send the message to,
-like @samp{To} except that these readers should not regard the message
-as directed at them.
-
-@item BCC
-This field contains additional mailing addresses to send the message to,
-which should not appear in the header of the message actually sent.
-Copies sent this way are called @dfn{blind carbon copies}.
-
-@vindex mail-self-blind
-@cindex copy of every outgoing message
-To send a blind carbon copy of every outgoing message to yourself, set
-the variable @code{mail-self-blind} to @code{t}. To send a blind carbon
-copy of every message to some other @var{address}, set the variable
-@code{mail-default-headers} to @code{"Bcc: @var{address}\n"}.
-
-@item FCC
-This field contains the name of one file and directs Emacs to append a
-copy of the message to that file when you send the message. If the file
-is in Rmail format, Emacs writes the message in Rmail format; otherwise,
-Emacs writes the message in system mail file format. To specify
-more than one file, use several @samp{FCC} fields, with one file
-name in each field.
-
-@vindex mail-archive-file-name
-To put a fixed file name in the @samp{FCC} field each time you start
-editing an outgoing message, set the variable
-@code{mail-archive-file-name} to that file name. Unless you remove the
-@samp{FCC} field before sending, the message will be written into that
-file when it is sent.
-
-@item From
-Use the @samp{From} field to say who you are, when the account you are
-using to send the mail is not your own. The contents of the @samp{From}
-field should be a valid mailing address, since replies will normally go
-there. If you don't specify the @samp{From} field yourself, Emacs uses
-the value of @code{user-mail-address} as the default.
-
-@item Reply-to
-Use this field to direct replies to a different address. Most
-mail-reading programs (including Rmail) automatically send replies to
-the @samp{Reply-to} address in preference to the @samp{From} address.
-By adding a @samp{Reply-to} field to your header, you can work around
-any problems your @samp{From} address may cause for replies.
-
-@cindex @env{REPLYTO} environment variable
-@vindex mail-default-reply-to
-To put a fixed @samp{Reply-to} address into every outgoing message, set
-the variable @code{mail-default-reply-to} to that address (as a string).
-Then @code{mail} initializes the message with a @samp{Reply-to} field as
-specified. You can delete or alter that header field before you send
-the message, if you wish. When Emacs starts up, if the environment
-variable @env{REPLYTO} is set, @code{mail-default-reply-to} is
-initialized from that environment variable.
-
-@item In-reply-to
-This field contains a piece of text describing the message you are
-replying to. Some mail systems can use this information to correlate
-related pieces of mail. Normally this field is filled in by Rmail
-when you reply to a message in Rmail, and you never need to
-think about it (@pxref{Rmail}).
-
-@item References
-This field lists the message IDs of related previous messages. Rmail
-sets up this field automatically when you reply to a message.
-@end table
-
- The @samp{To}, @samp{CC}, and @samp{BCC} header fields can appear
-any number of times, and each such header field can contain multiple
-addresses, separated by commas. This way, you can specify any number
-of places to send the message. These fields can also have
-continuation lines: one or more lines starting with whitespace,
-following the starting line of the field, are considered part of the
-field. Here's an example of a @samp{To} field with a continuation
-line:
-
-@example
-@group
-To: foo@@here.net, this@@there.net,
- me@@gnu.cambridge.mass.usa.earth.spiral3281
-@end group
-@end example
-
-@vindex mail-from-style
- When you send the message, if you didn't write a @samp{From} field
-yourself, Emacs puts in one for you. The variable
-@code{mail-from-style} controls the format:
-
-@table @code
-@item nil
-Use just the email address, as in @samp{king@@grassland.com}.
-@item parens
-Use both email address and full name, as in:@*
-@samp{king@@grassland.com (Elvis Parsley)}.
-@item angles
-Use both email address and full name, as in:@*
-@samp{Elvis Parsley <king@@grassland.com>}.
-@item system-default
-Allow the system to insert the @samp{From} field.
-@end table
-
-@vindex mail-default-headers
- You can direct Emacs to insert certain default headers into the
-outgoing message by setting the variable @code{mail-default-headers}
-to a string. Then @code{C-x m} inserts this string into the message
-headers. If the default header fields are not appropriate for a
-particular message, edit them as appropriate before sending the
-message.
-
-@node Mail Aliases
-@section Mail Aliases
-@cindex mail aliases
-@cindex @file{.mailrc} file
-@cindex mailrc file
-
- You can define @dfn{mail aliases} in a file named @file{~/.mailrc}.
-These are short mnemonic names which stand for mail addresses or groups of
-mail addresses. Like many other mail programs, Emacs expands aliases
-when they occur in the @samp{To}, @samp{From}, @samp{CC}, @samp{BCC}, and
-@samp{Reply-to} fields, plus their @samp{Resent-} variants.
-
- To define an alias in @file{~/.mailrc}, write a line in the following
-format:
-
-@example
-alias @var{shortaddress} @var{fulladdresses}
-@end example
-
-@noindent
-Here @var{fulladdresses} stands for one or more mail addresses for
-@var{shortaddress} to expand into. Separate multiple addresses with
-spaces; if an address contains a space, quote the whole address with a
-pair of double-quotes.
-
-For instance, to make @code{maingnu} stand for
-@code{gnu@@gnu.org} plus a local address of your own, put in
-this line:@refill
-
-@example
-alias maingnu gnu@@gnu.org local-gnu
-@end example
-
-@noindent
-Addresses specified in this way should use doublequotes around an
-entire address when the address contains spaces. But you need not
-include doublequotes around parts of the address, such as the person's
-full name. Emacs puts them in if they are needed. For example,
-
-@example
-alias chief-torturer "George W. Bush <bush@@whitehouse.gov>"
-@end example
-
-@noindent
-is correct in @samp{.mailrc}. Emacs will insert the address as
-@samp{"George W. Bush" <bush@@whitehouse.gov>}.
-
- Emacs also recognizes ``include'' commands in @samp{.mailrc} files.
-They look like this:
-
-@example
-source @var{filename}
-@end example
-
-@noindent
-The file @file{~/.mailrc} is used primarily by other mail-reading
-programs; it can contain various other commands. Emacs ignores
-everything in it except for alias definitions and include commands.
-
-@findex define-mail-alias
- Another way to define a mail alias, within Emacs alone, is with the
-@code{define-mail-alias} command. It prompts for the alias and then the
-full address. You can use it to define aliases in your @file{.emacs}
-file, like this:
-
-@example
-(define-mail-alias "maingnu" "gnu@@gnu.org")
-@end example
-
-@vindex mail-aliases
- @code{define-mail-alias} records aliases by adding them to a
-variable named @code{mail-aliases}. If you are comfortable with
-manipulating Lisp lists, you can set @code{mail-aliases} directly. The
-initial value of @code{mail-aliases} is @code{t}, which means that
-Emacs should read @file{.mailrc} to get the proper value.
-
-@vindex mail-personal-alias-file
- You can specify a different file name to use instead of
-@file{~/.mailrc} by setting the variable
-@code{mail-personal-alias-file}.
-
-@findex expand-mail-aliases
- Normally, Emacs expands aliases when you send the message. You do not
-need to expand mail aliases before sending the message, but you can
-expand them if you want to see where the mail will actually go. To do
-this, use the command @kbd{M-x expand-mail-aliases}; it expands all mail
-aliases currently present in the mail headers that hold addresses.
-
- If you like, you can have mail aliases expand as abbrevs, as soon as
-you type them in (@pxref{Abbrevs}). To enable this feature, execute the
-following:
-
-@example
-(add-hook 'mail-mode-hook 'mail-abbrevs-setup)
-@end example
-
-@noindent
-@findex define-mail-abbrev
-@vindex mail-abbrevs
-This can go in your @file{.emacs} file. @xref{Hooks}. If you use this
-feature, you must use @code{define-mail-abbrev} instead of
-@code{define-mail-alias}; the latter does not work with this package.
-Note that the mail abbreviation package uses the variable
-@code{mail-abbrevs} instead of @code{mail-aliases}, and that all alias
-names are converted to lower case.
-
-@kindex C-c C-a @r{(Mail mode)}
-@findex mail-interactive-insert-alias
- The mail abbreviation package also provides the @kbd{C-c C-a}
-(@code{mail-interactive-insert-alias}) command, which reads an alias
-name (with completion) and inserts its definition at point. This is
-useful when editing the message text itself or a header field such as
-@samp{Subject} in which Emacs does not normally expand aliases.
-
- Note that abbrevs expand only if you insert a word-separator character
-afterward. However, you can rebind @kbd{C-n} and @kbd{M->} to cause
-expansion as well. Here's how to do that:
-
-@smallexample
-(add-hook 'mail-mode-hook
- (lambda ()
- (define-key
- mail-mode-map [remap next-line] 'mail-abbrev-next-line)
- (define-key
- mail-mode-map [remap end-of-buffer] 'mail-abbrev-end-of-buffer)))
-@end smallexample
-
-@node Mail Mode
-@section Mail Mode
-@cindex Mail mode
-@cindex mode, Mail
-
- The major mode used in the mail buffer is Mail mode, which is much
-like Text mode except that various special commands are provided on the
-@kbd{C-c} prefix. These commands all have to do specifically with
-editing or sending the message. In addition, Mail mode defines the
-character @samp{%} as a word separator; this is helpful for using the
-word commands to edit mail addresses.
-
- Mail mode is normally used in buffers set up automatically by the
-@code{mail} command and related commands. However, you can also switch
-to Mail mode in a file-visiting buffer. This is a useful thing to do if
-you have saved the text of a draft message in a file.
-
-@menu
-* Mail Sending:: Commands to send the message.
-* Header Editing:: Commands to move to header fields and edit them.
-* Citing Mail:: Copying all or part of a message you are replying to.
-* Mail Mode Misc:: Spell checking, signatures, etc.
-@end menu
-
-@node Mail Sending
-@subsection Mail Sending
-
- Mail mode has two commands for sending the message you have been
-editing:
-
-@table @kbd
-@item C-c C-s
-Send the message, and leave the mail buffer selected (@code{mail-send}).
-@item C-c C-c
-Send the message, and select some other buffer (@code{mail-send-and-exit}).
-@end table
-
-@kindex C-c C-s @r{(Mail mode)}
-@kindex C-c C-c @r{(Mail mode)}
-@findex mail-send
-@findex mail-send-and-exit
- @kbd{C-c C-s} (@code{mail-send}) sends the message and marks the mail
-buffer unmodified, but leaves that buffer selected so that you can
-modify the message (perhaps with new recipients) and send it again.
-@kbd{C-c C-c} (@code{mail-send-and-exit}) sends and then deletes the
-window or switches to another buffer. It puts the mail buffer at the
-lowest priority for reselection by default, since you are finished with
-using it. This is the usual way to send the message.
-
- In a file-visiting buffer, sending the message does not clear the
-modified flag, because only saving the file should do that. Also, you
-don't get a warning if you try to send the same message twice.
-
-@c This is indexed in mule.texi, node "Recognize Coding".
-@c @vindex sendmail-coding-system
- When you send a message that contains non-@acronym{ASCII} characters, they need
-to be encoded with a coding system (@pxref{Coding Systems}). Usually
-the coding system is specified automatically by your chosen language
-environment (@pxref{Language Environments}). You can explicitly specify
-the coding system for outgoing mail by setting the variable
-@code{sendmail-coding-system} (@pxref{Recognize Coding}).
-
- If the coding system thus determined does not handle the characters in
-a particular message, Emacs asks you to select the coding system to use,
-showing a list of possible coding systems.
-
-@cindex SMTP
-@cindex Feedmail
-@cindex Sendmail
-@vindex send-mail-function
- The variable @code{send-mail-function} controls how the default mail
-user agent sends mail. It should be set to a function. The default
-is @code{sendmail-send-it}, which delivers mail using the Sendmail
-installation on the local host. To send mail through a SMTP server,
-set it to @code{smtpmail-send-it} and set up the Emacs SMTP library
-(@pxref{Top,,Emacs SMTP Library, smtpmail, Sending mail via SMTP}). A
-third option is @code{feedmail-send-it}, see the commentary section of
-the @file{feedmail.el} package for more information.
-
-@node Header Editing
-@subsection Mail Header Editing
-
- Mail mode provides special commands to move to particular header
-fields and to complete addresses in headers.
-
-@table @kbd
-@item C-c C-f C-t
-Move to the @samp{To} header field, creating one if there is none
-(@code{mail-to}).
-@item C-c C-f C-s
-Move to the @samp{Subject} header field, creating one if there is
-none (@code{mail-subject}).
-@item C-c C-f C-c
-Move to the @samp{CC} header field, creating one if there is none
-(@code{mail-cc}).
-@item C-c C-f C-b
-Move to the @samp{BCC} header field, creating one if there is none
-(@code{mail-bcc}).
-@item C-c C-f C-f
-Move to the @samp{FCC} header field, creating one if there is none
-(@code{mail-fcc}).
-@item M-@key{TAB}
-Complete a mailing address (@code{mail-complete}).
-@end table
-
-@kindex C-c C-f C-t @r{(Mail mode)}
-@findex mail-to
-@kindex C-c C-f C-s @r{(Mail mode)}
-@findex mail-subject
-@kindex C-c C-f C-c @r{(Mail mode)}
-@findex mail-cc
-@kindex C-c C-f C-b @r{(Mail mode)}
-@findex mail-bcc
-@kindex C-c C-f C-f @r{(Mail mode)}
-@findex mail-fcc
- There are five commands to move point to particular header fields, all
-based on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field''). They
-are listed in the table above. If the field in question does not exist,
-these commands create one. We provide special motion commands for these
-particular fields because they are the fields users most often want to
-edit.
-
-@findex mail-complete
-@kindex M-TAB @r{(Mail mode)}
- While editing a header field that contains mailing addresses, such
-as @samp{To:}, @samp{CC:} and @samp{BCC:}, you can complete a mailing
-address by typing @kbd{M-@key{TAB}} (@code{mail-complete}). It
-inserts the full name corresponding to the address, if it can
-determine the full name. The variable @code{mail-complete-style}
-controls whether to insert the full name, and what style to use, as in
-@code{mail-from-style} (@pxref{Mail Headers}). (If your window
-manager defines @kbd{M-@key{TAB}} to switch windows, you can type
-@kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.)
-
- For completion purposes, the valid mailing addresses are taken to be
-the local users' names plus your personal mail aliases. You can
-specify additional sources of valid addresses; see the customization
-group @samp{mailalias} to see the variables for customizing this
-feature (@pxref{Customization Groups}).
-
- If you type @kbd{M-@key{TAB}} in the body of the message,
-@code{mail-complete} invokes @code{ispell-complete-word}, as in Text
-mode.
-
-@node Citing Mail
-@subsection Citing Mail
-@cindex citing mail
-
- Mail mode also has commands for yanking or @dfn{citing} all or part of
-a message that you are replying to. These commands are active only when
-you started sending a message using an Rmail command.
-
-@table @kbd
-@item C-c C-y
-Yank the selected message from Rmail (@code{mail-yank-original}).
-@item C-c C-r
-Yank the region from the Rmail buffer (@code{mail-yank-region}).
-@item C-c C-q
-Fill each paragraph cited from another message
-(@code{mail-fill-yanked-message}).
-@end table
-
-@kindex C-c C-y @r{(Mail mode)}
-@findex mail-yank-original
- When mail sending is invoked from the Rmail mail reader using an Rmail
-command, @kbd{C-c C-y} can be used inside the mail buffer to insert
-the text of the message you are replying to. Normally it indents each line
-of that message three spaces and eliminates most header fields. A numeric
-argument specifies the number of spaces to indent. An argument of just
-@kbd{C-u} says not to indent at all and not to eliminate anything.
-@kbd{C-c C-y} always uses the current message from the Rmail buffer,
-so you can insert several old messages by selecting one in Rmail,
-switching to @samp{*mail*} and yanking it, then switching back to
-Rmail to select another.
-
-@vindex mail-yank-prefix
- You can specify the text for @kbd{C-c C-y} to insert at the beginning
-of each line: set @code{mail-yank-prefix} to the desired string. (A
-value of @code{nil} means to use indentation; this is the default.)
-However, @kbd{C-u C-c C-y} never adds anything at the beginning of the
-inserted lines, regardless of the value of @code{mail-yank-prefix}.
-
-@kindex C-c C-r @r{(Mail mode)}
-@findex mail-yank-region
- To yank just a part of an incoming message, set the region in Rmail to
-the part you want; then go to the @samp{*Mail*} message and type
-@kbd{C-c C-r} (@code{mail-yank-region}). Each line that is copied is
-indented or prefixed according to @code{mail-yank-prefix}.
-
-@kindex C-c C-q @r{(Mail mode)}
-@findex mail-fill-yanked-message
- After using @kbd{C-c C-y} or @kbd{C-c C-r}, you can type @kbd{C-c C-q}
-(@code{mail-fill-yanked-message}) to fill the paragraphs of the yanked
-old message or messages. One use of @kbd{C-c C-q} fills all such
-paragraphs, each one individually. To fill a single paragraph of the
-quoted message, use @kbd{M-q}. If filling does not automatically
-handle the type of citation prefix you use, try setting the fill prefix
-explicitly. @xref{Filling}.
-
-@node Mail Mode Misc
-@subsection Mail Mode Miscellany
-
-@table @kbd
-@item C-c C-t
-Move to the beginning of the message body text (@code{mail-text}).
-@item C-c C-w
-Insert the file @file{~/.signature} at the end of the message text
-(@code{mail-signature}).
-@item C-c C-i @var{file} @key{RET}
-Insert the contents of @var{file} at the end of the outgoing message
-(@code{mail-attach-file}).
-@item M-x ispell-message
-Perform spelling correction on the message text, but not on citations from
-other messages.
-@end table
-
-@kindex C-c C-t @r{(Mail mode)}
-@findex mail-text
- @kbd{C-c C-t} (@code{mail-text}) moves point to just after the header
-separator line---that is, to the beginning of the message body text.
-
-@kindex C-c C-w @r{(Mail mode)}
-@findex mail-signature
-@vindex mail-signature
- @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece of text at
-the end of the message to say more about who you are. The text comes
-from the file @file{~/.signature} in your home directory. To insert
-your signature automatically, set the variable @code{mail-signature} to
-@code{t}; after that, starting a mail message automatically inserts the
-contents of your @file{~/.signature} file. If you want to omit your
-signature from a particular message, delete it from the buffer before
-you send the message.
-
- You can also set @code{mail-signature} to a string; then that string
-is inserted automatically as your signature when you start editing a
-message to send. If you set it to some other Lisp expression, the
-expression is evaluated each time, and its value (which should be a
-string) specifies the signature.
-
-@findex ispell-message
- You can do spelling correction on the message text you have written
-with the command @kbd{M-x ispell-message}. If you have yanked an
-incoming message into the outgoing draft, this command skips what was
-yanked, but it checks the text that you yourself inserted. (It looks
-for indentation or @code{mail-yank-prefix} to distinguish the cited
-lines from your input.) @xref{Spelling}.
-
-@kindex C-c C-i @r{(Mail mode)}
-@findex mail-attach-file
- To include a file in the outgoing message, you can use @kbd{C-x i},
-the usual command to insert a file in the current buffer. But it is
-often more convenient to use a special command, @kbd{C-c C-i}
-(@code{mail-attach-file}). This command inserts the file contents at
-the end of the buffer, after your signature if any, with a delimiter
-line that includes the file name. Note that this is not a MIME
-attachment.
-
-@vindex mail-mode-hook
-@vindex mail-setup-hook
- Turning on Mail mode (which @kbd{C-x m} does automatically) runs the
-normal hooks @code{text-mode-hook} and @code{mail-mode-hook}.
-Initializing a new outgoing message runs the normal hook
-@code{mail-setup-hook}; if you want to add special fields to your mail
-header or make other changes to the appearance of the mail buffer, use
-that hook. @xref{Hooks}.
-
- The main difference between these hooks is just when they are
-invoked. Whenever you type @kbd{M-x mail}, @code{mail-mode-hook} runs
-as soon as the @samp{*mail*} buffer is created. Then the
-@code{mail-setup} function inserts the default contents of the buffer.
-After these default contents are inserted, @code{mail-setup-hook} runs.
-
-@node Mail Amusements
-@section Mail Amusements
-
-@findex spook
-@cindex NSA
- @kbd{M-x spook} adds a line of randomly chosen keywords to an outgoing
-mail message. The keywords are chosen from a list of words that suggest
-you are discussing something subversive.
-
- The idea behind this feature is the suspicion that the
-NSA@footnote{The US National Security Agency.} snoops on
-all electronic mail messages that contain keywords suggesting they might
-find them interesting. (The NSA says they don't, but that's what they
-@emph{would} say.) The idea is that if lots of people add suspicious
-words to their messages, the NSA will get so busy with spurious input
-that they will have to give up reading it all.
-
- Here's how to insert spook keywords automatically whenever you start
-entering an outgoing message:
-
-@example
-(add-hook 'mail-setup-hook 'spook)
-@end example
-
- Whether or not this confuses the NSA, it at least amuses people.
-
-@findex fortune-to-signature
-@cindex fortune cookies
- You can use the @code{fortune} program to put a ``fortune cookie''
-message into outgoing mail. To do this, add
-@code{fortune-to-signature} to @code{mail-setup-hook}:
-
-@example
-(add-hook 'mail-setup-hook 'fortune-to-signature)
-@end example
-
-@node Mail Methods
-@section Mail-Composition Methods
-@cindex mail-composition methods
-
-@cindex MH mail interface
-@cindex Message mode for sending mail
- In this chapter we have described the usual Emacs mode for editing
-and sending mail---Mail mode. Emacs has alternative facilities for
-editing and sending mail, including
-MH-E and Message mode, not documented in this manual.
-@xref{Top,,MH-E,mh-e, The Emacs Interface to MH}. @xref{Top,,Message,message,
-Message Manual}. You can choose any of them as your preferred method.
-The commands @code{C-x m}, @code{C-x 4 m} and @code{C-x 5 m} use
-whichever agent you have specified, as do various other Emacs commands
-and facilities that send mail.
-
-@vindex mail-user-agent
- To specify your mail-composition method, customize the variable
-@code{mail-user-agent}. Currently legitimate values include
-@code{sendmail-user-agent} (Mail mode), @code{mh-e-user-agent},
-@code{message-user-agent} and @code{gnus-user-agent}.
-
- If you select a different mail-composition method, the information
-in this chapter about the @samp{*mail*} buffer and Mail mode does not
-apply; the other methods use a different format of text in a different
-buffer, and their commands are different as well.
-
-@ignore
- arch-tag: d8a3dfc3-5d87-45c5-a7f2-69871b8e4fd6
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Text, Programs, Indentation, Top
-@chapter Commands for Human Languages
-@cindex text
-@cindex manipulating text
-
- The term @dfn{text} has two widespread meanings in our area of the
-computer field. One is data that is a sequence of characters. Any file
-that you edit with Emacs is text, in this sense of the word. The other
-meaning is more restrictive: a sequence of characters in a human language
-for humans to read (possibly after processing by a text formatter), as
-opposed to a program or binary data. This chapter is concerned with
-editing text in the narrower sense.
-
- Human languages have syntactic/stylistic conventions that can be
-supported or used to advantage by editor commands: conventions involving
-words, sentences, paragraphs, and capital letters. This chapter
-describes Emacs commands for all of these things. There are also
-commands for @dfn{filling}, which means rearranging the lines of a
-paragraph to be approximately equal in length. The commands for moving
-over and killing words, sentences and paragraphs, while intended
-primarily for editing text, are also often useful for editing programs.
-
- Emacs has several major modes for editing human-language text. If the
-file contains text pure and simple, use Text mode, which customizes
-Emacs in small ways for the syntactic conventions of text. Outline mode
-provides special commands for operating on text with an outline
-structure.
-@iftex
-@xref{Outline Mode}.
-@end iftex
-
- For text which contains embedded commands for text formatters, Emacs
-has other major modes, each for a particular formatter. Thus, for
-input to @TeX{}, you would use @TeX{}
-@iftex
-mode (@pxref{TeX Mode,,@TeX{} Mode}).
-@end iftex
-@ifnottex
-mode.
-@end ifnottex
-For input to groff or nroff, use Nroff mode.
-
- Instead of using a text formatter, you can edit formatted text in
-WYSIWYG style (``what you see is what you get''), with Enriched mode.
-Then the formatting appears on the screen in Emacs while you edit.
-@iftex
-@xref{Formatted Text}.
-@end iftex
-
-@cindex ASCII art
- If you need to edit pictures made out of text characters (commonly
-referred to as ``ASCII art''), use @kbd{M-x edit-picture} to enter
-Picture mode, a special major mode for editing such pictures.
-@iftex
-@xref{Picture Mode,,, emacs-xtra, Specialized Emacs Features}.
-@end iftex
-@ifnottex
-@xref{Picture Mode}.
-@end ifnottex
-
-
-@cindex skeletons
-@cindex templates
-@cindex autotyping
-@cindex automatic typing
- The ``automatic typing'' features may be useful when writing text.
-@inforef{Top,, autotype}.
-
-@menu
-* Words:: Moving over and killing words.
-* Sentences:: Moving over and killing sentences.
-* Paragraphs:: Moving over paragraphs.
-* Pages:: Moving over pages.
-* Filling:: Filling or justifying text.
-* Case:: Changing the case of text.
-* Text Mode:: The major modes for editing text files.
-* Outline Mode:: Editing outlines.
-* TeX Mode:: Editing input to the formatter TeX.
-* HTML Mode:: Editing HTML, SGML, and XML files.
-* Nroff Mode:: Editing input to the formatter nroff.
-* Formatted Text:: Editing formatted text directly in WYSIWYG fashion.
-* Text Based Tables:: Editing text-based tables in WYSIWYG fashion.
-@end menu
-
-@node Words
-@section Words
-@cindex words
-@cindex Meta commands and words
-
- Emacs has commands for moving over or operating on words. By convention,
-the keys for them are all Meta characters.
-
-@table @kbd
-@item M-f
-Move forward over a word (@code{forward-word}).
-@item M-b
-Move backward over a word (@code{backward-word}).
-@item M-d
-Kill up to the end of a word (@code{kill-word}).
-@item M-@key{DEL}
-Kill back to the beginning of a word (@code{backward-kill-word}).
-@item M-@@
-Mark the end of the next word (@code{mark-word}).
-@item M-t
-Transpose two words or drag a word across others
-(@code{transpose-words}).
-@end table
-
- Notice how these keys form a series that parallels the character-based
-@kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}. @kbd{M-@@} is
-cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}.
-
-@kindex M-f
-@kindex M-b
-@findex forward-word
-@findex backward-word
- The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b}
-(@code{backward-word}) move forward and backward over words. These
-Meta characters are thus analogous to the corresponding control
-characters, @kbd{C-f} and @kbd{C-b}, which move over single characters
-in the text. The analogy extends to numeric arguments, which serve as
-repeat counts. @kbd{M-f} with a negative argument moves backward, and
-@kbd{M-b} with a negative argument moves forward. Forward motion
-stops right after the last letter of the word, while backward motion
-stops right before the first letter.
-
-@kindex M-d
-@findex kill-word
- @kbd{M-d} (@code{kill-word}) kills the word after point. To be
-precise, it kills everything from point to the place @kbd{M-f} would
-move to. Thus, if point is in the middle of a word, @kbd{M-d} kills
-just the part after point. If some punctuation comes between point and the
-next word, it is killed along with the word. (If you wish to kill only the
-next word but not the punctuation before it, simply do @kbd{M-f} to get
-the end, and kill the word backwards with @kbd{M-@key{DEL}}.)
-@kbd{M-d} takes arguments just like @kbd{M-f}.
-
-@findex backward-kill-word
-@kindex M-DEL
- @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before
-point. It kills everything from point back to where @kbd{M-b} would
-move to. For instance, if point is after the space in @w{@samp{FOO,
-BAR}}, it kills @w{@samp{FOO, }}. If you wish to kill just
-@samp{FOO}, and not the comma and the space, use @kbd{M-b M-d} instead
-of @kbd{M-@key{DEL}}.
-
-@c Don't index M-t and transpose-words here, they are indexed in
-@c fixit.texi, in the node "Transpose".
-@c @kindex M-t
-@c @findex transpose-words
- @kbd{M-t} (@code{transpose-words}) exchanges the word before or
-containing point with the following word. The delimiter characters between
-the words do not move. For example, @w{@samp{FOO, BAR}} transposes into
-@w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for
-more on transposition.
-
-@kindex M-@@
-@findex mark-word
- To operate on the next @var{n} words with an operation which applies
-between point and mark, you can either set the mark at point and then move
-over the words, or you can use the command @kbd{M-@@} (@code{mark-word})
-which does not move point, but sets the mark where @kbd{M-f} would move
-to. @kbd{M-@@} accepts a numeric argument that says how many words to
-scan for the place to put the mark. In Transient Mark mode, this command
-activates the mark.
-
- The word commands' understanding of word boundaries is controlled
-by the syntax table. Any character can, for example, be declared to
-be a word delimiter. @xref{Syntax}.
-
-@node Sentences
-@section Sentences
-@cindex sentences
-@cindex manipulating sentences
-
- The Emacs commands for manipulating sentences and paragraphs are mostly
-on Meta keys, so as to be like the word-handling commands.
-
-@table @kbd
-@item M-a
-Move back to the beginning of the sentence (@code{backward-sentence}).
-@item M-e
-Move forward to the end of the sentence (@code{forward-sentence}).
-@item M-k
-Kill forward to the end of the sentence (@code{kill-sentence}).
-@item C-x @key{DEL}
-Kill back to the beginning of the sentence (@code{backward-kill-sentence}).
-@end table
-
-@kindex M-a
-@kindex M-e
-@findex backward-sentence
-@findex forward-sentence
- The commands @kbd{M-a} and @kbd{M-e} (@code{backward-sentence} and
-@code{forward-sentence}) move to the beginning and end of the current
-sentence, respectively. They were chosen to resemble @kbd{C-a} and
-@kbd{C-e}, which move to the beginning and end of a line. Unlike
-them, @kbd{M-a} and @kbd{M-e} move over successive sentences if
-repeated.
-
- Moving backward over a sentence places point just before the first
-character of the sentence; moving forward places point right after the
-punctuation that ends the sentence. Neither one moves over the
-whitespace at the sentence boundary.
-
-@kindex M-k
-@kindex C-x DEL
-@findex kill-sentence
-@findex backward-kill-sentence
- Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to go
-with them, so @kbd{M-a} and @kbd{M-e} have a corresponding kill command
-@kbd{M-k} (@code{kill-sentence}) which kills from point to the end of
-the sentence. With minus one as an argument it kills back to the
-beginning of the sentence. Larger arguments serve as a repeat count.
-There is also a command, @kbd{C-x @key{DEL}}
-(@code{backward-kill-sentence}), for killing back to the beginning of a
-sentence. This command is useful when you change your mind in the
-middle of composing text.
-
- The sentence commands assume that you follow the American typist's
-convention of putting two spaces at the end of a sentence; they consider
-a sentence to end wherever there is a @samp{.}, @samp{?} or @samp{!}
-followed by the end of a line or two spaces, with any number of
-@samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in between.
-A sentence also begins or ends wherever a paragraph begins or ends.
-It is useful to follow this convention, because it makes a distinction
-between periods that end a sentence and periods that indicate
-abbreviations; that enables the Emacs sentence commands to distinguish,
-too. These commands do not stop for periods that indicate abbreviations.
-
-@vindex sentence-end-double-space
- If you want to use just one space between sentences, you can set the
-variable @code{sentence-end-double-space} to @code{nil} to make the
-sentence commands stop for single spaces. However, this mode has a
-drawback: there is no way to distinguish between periods that end
-sentences and those that indicate abbreviations. For convenient and
-reliable editing, we therefore recommend you follow the two-space
-convention. The variable @code{sentence-end-double-space} also
-affects filling (@pxref{Fill Commands}) in related ways.
-
-@vindex sentence-end
- The variable @code{sentence-end} controls how to recognize the end
-of a sentence. If non-@code{nil}, it is a regexp that matches the
-last few characters of a sentence, together with the whitespace
-following the sentence. If the value is @code{nil}, the default, then
-Emacs computes the regexp according to various criteria such as the
-value of @code{sentence-end-double-space}. @xref{Regexp Example}, for
-a detailed explanation of one of the regular expressions Emacs uses
-for this purpose.
-
-@vindex sentence-end-without-period
- Some languages do not use periods to indicate the end of a sentence.
-For example, sentences in Thai end with a double space but without a
-period. Set the variable @code{sentence-end-without-period} to
-@code{t} in such cases.
-
-@node Paragraphs
-@section Paragraphs
-@cindex paragraphs
-@cindex manipulating paragraphs
-@kindex M-@{
-@kindex M-@}
-@findex backward-paragraph
-@findex forward-paragraph
-
- The Emacs commands for manipulating paragraphs are also on Meta keys.
-
-@table @kbd
-@item M-@{
-Move back to previous paragraph beginning (@code{backward-paragraph}).
-@item M-@}
-Move forward to next paragraph end (@code{forward-paragraph}).
-@item M-h
-Put point and mark around this or next paragraph (@code{mark-paragraph}).
-@end table
-
- @kbd{M-@{} moves to the beginning of the current or previous
-paragraph, while @kbd{M-@}} moves to the end of the current or next
-paragraph. Blank lines and text-formatter command lines separate
-paragraphs and are not considered part of any paragraph. If there is
-a blank line before the paragraph, @kbd{M-@{} moves to the blank line,
-because that is convenient in practice.
-
- In Text mode, an indented line is not a paragraph break. If you
-want indented lines to have this effect, use Paragraph-Indent Text
-mode instead. @xref{Text Mode}.
-
- In major modes for programs, paragraphs begin and end only at blank
-lines. This makes the paragraph commands useful, even though there
-are no paragraphs as such in a program.
-
- When you have set a fill prefix, then paragraphs are delimited by
-all lines which don't start with the fill prefix. @xref{Filling}.
-
-@kindex M-h
-@findex mark-paragraph
- When you wish to operate on a paragraph, you can use the command
-@kbd{M-h} (@code{mark-paragraph}) to set the region around it. Thus,
-for example, @kbd{M-h C-w} kills the paragraph around or after point.
-The @kbd{M-h} command puts point at the beginning and mark at the end of
-the paragraph point was in. In Transient Mark mode, it activates the
-mark. If point is between paragraphs (in a run of blank lines, or at a
-boundary), the paragraph following point is surrounded by point and
-mark. If there are blank lines preceding the first line of the
-paragraph, one of these blank lines is included in the region.
-
-@vindex paragraph-start
-@vindex paragraph-separate
- The precise definition of a paragraph boundary is controlled by the
-variables @code{paragraph-separate} and @code{paragraph-start}. The
-value of @code{paragraph-start} is a regexp that should match any line
-that either starts or separates paragraphs. The value of
-@code{paragraph-separate} is another regexp that should match only lines
-that separate paragraphs without being part of any paragraph (for
-example, blank lines). Lines that start a new paragraph and are
-contained in it must match only @code{paragraph-start}, not
-@code{paragraph-separate}. Each regular expression must match at the
-left margin. For example, in Fundamental mode, @code{paragraph-start}
-is @w{@code{"\f\\|[ \t]*$"}}, and @code{paragraph-separate} is
-@w{@code{"[ \t\f]*$"}}.
-
- Normally it is desirable for page boundaries to separate paragraphs.
-The default values of these variables recognize the usual separator for
-pages.
-
-@node Pages
-@section Pages
-
-@cindex pages
-@cindex formfeed
- Files are often thought of as divided into @dfn{pages} by the
-@dfn{formfeed} character (@acronym{ASCII} control-L, octal code 014).
-When you print hardcopy for a file, this character forces a page break;
-thus, each page of the file goes on a separate page on paper. Most Emacs
-commands treat the page-separator character just like any other
-character: you can insert it with @kbd{C-q C-l}, and delete it with
-@key{DEL}. Thus, you are free to paginate your file or not. However,
-since pages are often meaningful divisions of the file, Emacs provides
-commands to move over them and operate on them.
-
-@table @kbd
-@item C-x [
-Move point to previous page boundary (@code{backward-page}).
-@item C-x ]
-Move point to next page boundary (@code{forward-page}).
-@item C-x C-p
-Put point and mark around this page (or another page) (@code{mark-page}).
-@item C-x l
-Count the lines in this page (@code{count-lines-page}).
-@end table
-
-@kindex C-x [
-@kindex C-x ]
-@findex forward-page
-@findex backward-page
- The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
-after the previous page delimiter. If point is already right after a page
-delimiter, it skips that one and stops at the previous one. A numeric
-argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page})
-command moves forward past the next page delimiter.
-
-@kindex C-x C-p
-@findex mark-page
- The @kbd{C-x C-p} command (@code{mark-page}) puts point at the
-beginning of the current page and the mark at the end. The page
-delimiter at the end is included (the mark follows it). The page
-delimiter at the front is excluded (point follows it). In Transient
-Mark mode, this command activates the mark.
-
- @kbd{C-x C-p C-w} is a handy way to kill a page to move it
-elsewhere. If you move to another page delimiter with @kbd{C-x [} and
-@kbd{C-x ]}, then yank the killed page, all the pages will be properly
-delimited once again. The reason @kbd{C-x C-p} includes only the
-following page delimiter in the region is to ensure that.
-
- A numeric argument to @kbd{C-x C-p} is used to specify which page to go
-to, relative to the current one. Zero means the current page. One means
-the next page, and @minus{}1 means the previous one.
-
-@kindex C-x l
-@findex count-lines-page
- The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
-where to break a page in two. It displays in the echo area the total number
-of lines in the current page, and then divides it up into those preceding
-the current line and those following, as in
-
-@example
-Page has 96 (72+25) lines
-@end example
-
-@noindent
- Notice that the sum is off by one; this is correct if point is not at the
-beginning of a line.
-
-@vindex page-delimiter
- The variable @code{page-delimiter} controls where pages begin. Its
-value is a regexp that matches the beginning of a line that separates
-pages. The normal value of this variable is @code{"^\f"}, which
-matches a formfeed character at the beginning of a line.
-
-@node Filling
-@section Filling Text
-@cindex filling text
-
- @dfn{Filling} text means breaking it up into lines that fit a
-specified width. Emacs does filling in two ways. In Auto Fill mode,
-inserting text with self-inserting characters also automatically fills
-it. There are also explicit fill commands that you can use when editing
-text leaves it unfilled. When you edit formatted text, you can specify
-a style of filling for each portion of the text (@pxref{Formatted
-Text}).
-
-@menu
-* Auto Fill:: Auto Fill mode breaks long lines automatically.
-* Fill Commands:: Commands to refill paragraphs and center lines.
-* Fill Prefix:: Filling paragraphs that are indented
- or in a comment, etc.
-* Adaptive Fill:: How Emacs can determine the fill prefix automatically.
-* Refill:: Keeping paragraphs filled.
-* Longlines:: Editing text with very long lines.
-@end menu
-
-@node Auto Fill
-@subsection Auto Fill Mode
-@cindex Auto Fill mode
-@cindex mode, Auto Fill
-
- @dfn{Auto Fill} mode is a minor mode in which lines are broken
-automatically when they become too wide. Breaking happens only when
-you type a @key{SPC} or @key{RET}.
-
-@table @kbd
-@item M-x auto-fill-mode
-Enable or disable Auto Fill mode.
-@item @key{SPC}
-@itemx @key{RET}
-In Auto Fill mode, break lines when appropriate.
-@end table
-
-@findex auto-fill-mode
- @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off
-if it was on. With a positive numeric argument it always turns Auto
-Fill mode on, and with a negative argument always turns it off. You can
-see when Auto Fill mode is in effect by the presence of the word
-@samp{Fill} in the mode line, inside the parentheses. Auto Fill mode is
-a minor mode which is enabled or disabled for each buffer individually.
-@xref{Minor Modes}.
-
- In Auto Fill mode, lines are broken automatically at spaces when they
-get longer than the desired width. Line breaking and rearrangement
-takes place only when you type @key{SPC} or @key{RET}. If you wish to
-insert a space or newline without permitting line-breaking, type
-@kbd{C-q @key{SPC}} or @kbd{C-q C-j} (recall that a newline is really a
-control-J). Also, @kbd{C-o} inserts a newline without line breaking.
-
- Auto Fill mode works well with programming-language modes, because it
-indents new lines with @key{TAB}. If a line ending in a comment gets
-too long, the text of the comment is split into two comment lines.
-Optionally, new comment delimiters are inserted at the end of the first
-line and the beginning of the second so that each line is a separate
-comment; the variable @code{comment-multi-line} controls the choice
-(@pxref{Comments}).
-
- Adaptive filling (@pxref{Adaptive Fill}) works for Auto Filling as
-well as for explicit fill commands. It takes a fill prefix
-automatically from the second or first line of a paragraph.
-
- Auto Fill mode does not refill entire paragraphs; it can break lines but
-cannot merge lines. So editing in the middle of a paragraph can result in
-a paragraph that is not correctly filled. The easiest way to make the
-paragraph properly filled again is usually with the explicit fill commands.
-@ifnottex
-@xref{Fill Commands}.
-@end ifnottex
-
- Many users like Auto Fill mode and want to use it in all text files.
-The section on init files says how to arrange this permanently for yourself.
-@xref{Init File}.
-
-@node Fill Commands
-@subsection Explicit Fill Commands
-
-@table @kbd
-@item M-q
-Fill current paragraph (@code{fill-paragraph}).
-@item C-x f
-Set the fill column (@code{set-fill-column}).
-@item M-x fill-region
-Fill each paragraph in the region (@code{fill-region}).
-@item M-x fill-region-as-paragraph
-Fill the region, considering it as one paragraph.
-@item M-s
-Center a line.
-@end table
-
-@kindex M-q
-@findex fill-paragraph
- To refill a paragraph, use the command @kbd{M-q}
-(@code{fill-paragraph}). This operates on the paragraph that point is
-inside, or the one after point if point is between paragraphs.
-Refilling works by removing all the line-breaks, then inserting new ones
-where necessary.
-
-@findex fill-region
- To refill many paragraphs, use @kbd{M-x fill-region}, which
-finds the paragraphs in the region and fills each of them.
-
-@findex fill-region-as-paragraph
- @kbd{M-q} and @code{fill-region} use the same criteria as @kbd{M-h}
-for finding paragraph boundaries (@pxref{Paragraphs}). For more
-control, you can use @kbd{M-x fill-region-as-paragraph}, which refills
-everything between point and mark as a single paragraph. This command
-deletes any blank lines within the region, so separate blocks of text
-end up combined into one block.
-
-@cindex justification
- A numeric argument to @kbd{M-q} tells it to @dfn{justify} the text
-as well as filling it. This means that extra spaces are inserted to
-make the right margin line up exactly at the fill column. To remove
-the extra spaces, use @kbd{M-q} with no argument. (Likewise for
-@code{fill-region}.) Another way to control justification, and choose
-other styles of filling, is with the @code{justification} text
-property; see @ref{Format Justification}.
-
-@kindex M-s @r{(Text mode)}
-@cindex centering
-@findex center-line
- The command @kbd{M-s} (@code{center-line}) centers the current line
-within the current fill column. With an argument @var{n}, it centers
-@var{n} lines individually and moves past them. This binding is
-made by Text mode and is available only in that and related modes
-(@pxref{Text Mode}).
-
-@vindex fill-column
-@kindex C-x f
-@findex set-fill-column
- The maximum line width for filling is in the variable
-@code{fill-column}. Altering the value of @code{fill-column} makes it
-local to the current buffer; until that time, the default value is in
-effect. The default is initially 70. @xref{Locals}. The easiest way
-to set @code{fill-column} is to use the command @kbd{C-x f}
-(@code{set-fill-column}). With a numeric argument, it uses that as the
-new fill column. With just @kbd{C-u} as argument, it sets
-@code{fill-column} to the current horizontal position of point.
-
- Emacs commands normally consider a period followed by two spaces or by
-a newline as the end of a sentence; a period followed by just one space
-indicates an abbreviation and not the end of a sentence. To preserve
-the distinction between these two ways of using a period, the fill
-commands do not break a line after a period followed by just one space.
-
- If the variable @code{sentence-end-double-space} is @code{nil}, the
-fill commands expect and leave just one space at the end of a sentence.
-Ordinarily this variable is @code{t}, so the fill commands insist on
-two spaces for the end of a sentence, as explained above. @xref{Sentences}.
-
-@vindex colon-double-space
- If the variable @code{colon-double-space} is non-@code{nil}, the
-fill commands put two spaces after a colon.
-
-@vindex fill-nobreak-predicate
- The variable @code{fill-nobreak-predicate} is a hook (an abnormal
-hook, @pxref{Hooks}) specifying additional conditions where
-line-breaking is not allowed. Each function is called with no
-arguments, with point at a place where Emacs is considering breaking
-the line. If a function returns a non-@code{nil} value, then that's
-a bad place to break the line. Two standard functions you can use are
-@code{fill-single-word-nobreak-p} (don't break after the first word of
-a sentence or before the last) and @code{fill-french-nobreak-p} (don't
-break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}).
-
-@node Fill Prefix
-@subsection The Fill Prefix
-
-@cindex fill prefix
- To fill a paragraph in which each line starts with a special marker
-(which might be a few spaces, giving an indented paragraph), you can use
-the @dfn{fill prefix} feature. The fill prefix is a string that Emacs
-expects every line to start with, and which is not included in filling.
-You can specify a fill prefix explicitly; Emacs can also deduce the
-fill prefix automatically (@pxref{Adaptive Fill}).
-
-@table @kbd
-@item C-x .
-Set the fill prefix (@code{set-fill-prefix}).
-@item M-q
-Fill a paragraph using current fill prefix (@code{fill-paragraph}).
-@item M-x fill-individual-paragraphs
-Fill the region, considering each change of indentation as starting a
-new paragraph.
-@item M-x fill-nonuniform-paragraphs
-Fill the region, considering only paragraph-separator lines as starting
-a new paragraph.
-@end table
-
-@kindex C-x .
-@findex set-fill-prefix
- To specify a fill prefix for the current buffer, move to a line that
-starts with the desired prefix, put point at the end of the prefix,
-and type @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). (That's a period
-after the @kbd{C-x}.) To turn off the fill prefix, specify an empty
-prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line.
-
- When a fill prefix is in effect, the fill commands remove the fill
-prefix from each line of the paragraph before filling and insert it on
-each line after filling. (The beginning of the first line of the
-paragraph is left unchanged, since often that is intentionally
-different.) Auto Fill mode also inserts the fill prefix automatically
-when it makes a new line. The @kbd{C-o} command inserts the fill
-prefix on new lines it creates, when you use it at the beginning of a
-line (@pxref{Blank Lines}). Conversely, the command @kbd{M-^} deletes
-the prefix (if it occurs) after the newline that it deletes
-(@pxref{Indentation}).
-
- For example, if @code{fill-column} is 40 and you set the fill prefix
-to @samp{;; }, then @kbd{M-q} in the following text
-
-@example
-;; This is an
-;; example of a paragraph
-;; inside a Lisp-style comment.
-@end example
-
-@noindent
-produces this:
-
-@example
-;; This is an example of a paragraph
-;; inside a Lisp-style comment.
-@end example
-
- Lines that do not start with the fill prefix are considered to start
-paragraphs, both in @kbd{M-q} and the paragraph commands; this gives
-good results for paragraphs with hanging indentation (every line
-indented except the first one). Lines which are blank or indented once
-the prefix is removed also separate or start paragraphs; this is what
-you want if you are writing multi-paragraph comments with a comment
-delimiter on each line.
-
-@findex fill-individual-paragraphs
- You can use @kbd{M-x fill-individual-paragraphs} to set the fill
-prefix for each paragraph automatically. This command divides the
-region into paragraphs, treating every change in the amount of
-indentation as the start of a new paragraph, and fills each of these
-paragraphs. Thus, all the lines in one ``paragraph'' have the same
-amount of indentation. That indentation serves as the fill prefix for
-that paragraph.
-
-@findex fill-nonuniform-paragraphs
- @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides
-the region into paragraphs in a different way. It considers only
-paragraph-separating lines (as defined by @code{paragraph-separate}) as
-starting a new paragraph. Since this means that the lines of one
-paragraph may have different amounts of indentation, the fill prefix
-used is the smallest amount of indentation of any of the lines of the
-paragraph. This gives good results with styles that indent a paragraph's
-first line more or less that the rest of the paragraph.
-
-@vindex fill-prefix
- The fill prefix is stored in the variable @code{fill-prefix}. Its value
-is a string, or @code{nil} when there is no fill prefix. This is a
-per-buffer variable; altering the variable affects only the current buffer,
-but there is a default value which you can change as well. @xref{Locals}.
-
- The @code{indentation} text property provides another way to control
-the amount of indentation paragraphs receive. @xref{Format Indentation}.
-
-@node Adaptive Fill
-@subsection Adaptive Filling
-
-@cindex adaptive filling
- The fill commands can deduce the proper fill prefix for a paragraph
-automatically in certain cases: either whitespace or certain punctuation
-characters at the beginning of a line are propagated to all lines of the
-paragraph.
-
- If the paragraph has two or more lines, the fill prefix is taken from
-the paragraph's second line, but only if it appears on the first line as
-well.
-
- If a paragraph has just one line, fill commands @emph{may} take a
-prefix from that line. The decision is complicated because there are
-three reasonable things to do in such a case:
-
-@itemize @bullet
-@item
-Use the first line's prefix on all the lines of the paragraph.
-
-@item
-Indent subsequent lines with whitespace, so that they line up under the
-text that follows the prefix on the first line, but don't actually copy
-the prefix from the first line.
-
-@item
-Don't do anything special with the second and following lines.
-@end itemize
-
- All three of these styles of formatting are commonly used. So the
-fill commands try to determine what you would like, based on the prefix
-that appears and on the major mode. Here is how.
-
-@vindex adaptive-fill-first-line-regexp
- If the prefix found on the first line matches
-@code{adaptive-fill-first-line-regexp}, or if it appears to be a
-comment-starting sequence (this depends on the major mode), then the
-prefix found is used for filling the paragraph, provided it would not
-act as a paragraph starter on subsequent lines.
-
- Otherwise, the prefix found is converted to an equivalent number of
-spaces, and those spaces are used as the fill prefix for the rest of the
-lines, provided they would not act as a paragraph starter on subsequent
-lines.
-
- In Text mode, and other modes where only blank lines and page
-delimiters separate paragraphs, the prefix chosen by adaptive filling
-never acts as a paragraph starter, so it can always be used for filling.
-
-@vindex adaptive-fill-mode
-@vindex adaptive-fill-regexp
- The variable @code{adaptive-fill-regexp} determines what kinds of line
-beginnings can serve as a fill prefix: any characters at the start of
-the line that match this regular expression are used. If you set the
-variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is
-never chosen automatically.
-
-@vindex adaptive-fill-function
- You can specify more complex ways of choosing a fill prefix
-automatically by setting the variable @code{adaptive-fill-function} to a
-function. This function is called with point after the left margin of a
-line, and it should return the appropriate fill prefix based on that
-line. If it returns @code{nil}, @code{adaptive-fill-regexp} gets
-a chance to find a prefix.
-
-@node Refill
-@subsection Refill Mode
-@cindex refilling text, word processor style
-@cindex modes, Refill
-@cindex Refill minor mode
-
- Refill minor mode provides support for keeping paragraphs filled as
-you type or modify them in other ways. It provides an effect similar
-to typical word processor behavior. This works by running a
-paragraph-filling command at suitable times.
-
- To toggle the use of Refill mode in the current buffer, type
-@kbd{M-x refill-mode}. When you are typing text, only characters
-which normally trigger auto filling, like the space character, will
-trigger refilling. This is to avoid making it too slow. Apart from
-self-inserting characters, other commands which modify the text cause
-refilling.
-
- The current implementation is preliminary and not robust. You can
-get better ``line wrapping'' behavior using Longlines mode.
-@xref{Longlines}. However, Longlines mode has an important
-side-effect: the newlines that it inserts for you are not saved to
-disk, so the files that you make with Longlines mode will appear to be
-completely unfilled if you edit them without Longlines mode.
-
-@node Longlines
-@subsection Long Lines Mode
-@cindex refilling text, word processor style
-@cindex modes, Long Lines
-@cindex word wrap
-@cindex Long Lines minor mode
-
- Long Lines mode is a minor mode for @dfn{word wrapping}; it lets you
-edit ``unfilled'' text files, which Emacs would normally display as a
-bunch of extremely long lines. Many text editors, such as those built
-into many web browsers, normally do word wrapping.
-
-@findex longlines-mode
- To enable Long Lines mode, type @kbd{M-x longlines-mode}. If the
-text is full of long lines, this will ``wrap'' them
-immediately---i.e., break up to fit in the window. As you edit the
-text, Long Lines mode automatically re-wraps lines by inserting or
-deleting @dfn{soft newlines} as necessary (@pxref{Hard and Soft
-Newlines}.) These soft newlines won't show up when you save the
-buffer into a file, or when you copy the text into the kill ring,
-clipboard, or a register.
-
-@findex longlines-auto-wrap
- Word wrapping is @emph{not} the same as ordinary filling
-(@pxref{Fill Commands}). It does not contract multiple spaces into a
-single space, recognize fill prefixes (@pxref{Fill Prefix}), or
-perform adaptive filling (@pxref{Adaptive Fill}). The reason for this
-is that a wrapped line is still, conceptually, a single line. Each
-soft newline is equivalent to exactly one space in that long line, and
-vice versa. However, you can still call filling functions such as
-@kbd{M-q}, and these will work as expected, inserting soft newlines
-that won't show up on disk or when the text is copied. You can even
-rely entirely on the normal fill commands by turning off automatic
-line wrapping, with @kbd{C-u M-x longlines-auto-wrap}. To turn
-automatic line wrapping back on, type @kbd{M-x longlines-auto-wrap}.
-
-@findex longlines-show-hard-newlines
- Type @kbd{RET} to insert a hard newline, one which automatic
-refilling will not remove. If you want to see where all the hard
-newlines are, type @kbd{M-x longlines-show-hard-newlines}. This will
-mark each hard newline with a special symbol. The same command with a
-prefix argument turns this display off.
-
- Long Lines mode does not change normal text files that are already
-filled, since the existing newlines are considered hard newlines.
-Before Long Lines can do anything, you need to transform each
-paragraph into a long line. One way is to set @code{fill-column} to a
-large number (e.g., @kbd{C-u 9999 C-x f}), re-fill all the paragraphs,
-and then set @code{fill-column} back to its original value.
-
-@node Case
-@section Case Conversion Commands
-@cindex case conversion
-
- Emacs has commands for converting either a single word or any arbitrary
-range of text to upper case or to lower case.
-
-@table @kbd
-@item M-l
-Convert following word to lower case (@code{downcase-word}).
-@item M-u
-Convert following word to upper case (@code{upcase-word}).
-@item M-c
-Capitalize the following word (@code{capitalize-word}).
-@item C-x C-l
-Convert region to lower case (@code{downcase-region}).
-@item C-x C-u
-Convert region to upper case (@code{upcase-region}).
-@end table
-
-@kindex M-l
-@kindex M-u
-@kindex M-c
-@cindex words, case conversion
-@cindex converting text to upper or lower case
-@cindex capitalizing words
-@findex downcase-word
-@findex upcase-word
-@findex capitalize-word
- The word conversion commands are the most useful. @kbd{M-l}
-(@code{downcase-word}) converts the word after point to lower case, moving
-past it. Thus, repeating @kbd{M-l} converts successive words.
-@kbd{M-u} (@code{upcase-word}) converts to all capitals instead, while
-@kbd{M-c} (@code{capitalize-word}) puts the first letter of the word
-into upper case and the rest into lower case. All these commands convert
-several words at once if given an argument. They are especially convenient
-for converting a large amount of text from all upper case to mixed case,
-because you can move through the text using @kbd{M-l}, @kbd{M-u} or
-@kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead
-to skip a word.
-
- When given a negative argument, the word case conversion commands apply
-to the appropriate number of words before point, but do not move point.
-This is convenient when you have just typed a word in the wrong case: you
-can give the case conversion command and continue typing.
-
- If a word case conversion command is given in the middle of a word,
-it applies only to the part of the word which follows point. (This is
-comparable to what @kbd{M-d} (@code{kill-word}) does.) With a
-negative argument, case conversion applies only to the part of the
-word before point.
-
-@kindex C-x C-l
-@kindex C-x C-u
-@findex downcase-region
-@findex upcase-region
- The other case conversion commands are @kbd{C-x C-u}
-(@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
-convert everything between point and mark to the specified case. Point and
-mark do not move.
-
- The region case conversion commands @code{upcase-region} and
-@code{downcase-region} are normally disabled. This means that they ask
-for confirmation if you try to use them. When you confirm, you may
-enable the command, which means it will not ask for confirmation again.
-@xref{Disabling}.
-
-@node Text Mode
-@section Text Mode
-@cindex Text mode
-@cindex mode, Text
-@findex text-mode
-
- When you edit files of text in a human language, it's more convenient
-to use Text mode rather than Fundamental mode. To enter Text mode, type
-@kbd{M-x text-mode}.
-
- In Text mode, only blank lines and page delimiters separate
-paragraphs. As a result, paragraphs can be indented, and adaptive
-filling determines what indentation to use when filling a paragraph.
-@xref{Adaptive Fill}.
-
-@kindex TAB @r{(Text mode)}
- Text mode defines @key{TAB} to run @code{indent-relative}
-(@pxref{Indentation}), so that you can conveniently indent a line like
-the previous line.
-
- Text mode turns off the features concerned with comments except when
-you explicitly invoke them. It changes the syntax table so that
-single-quotes are considered part of words. However, if a word starts
-with single-quotes, these are treated as a prefix for purposes such as
-capitalization. That is, @kbd{M-c} will convert @samp{'hello'} into
-@samp{'Hello'}, as expected.
-
-@cindex Paragraph-Indent Text mode
-@cindex mode, Paragraph-Indent Text
-@findex paragraph-indent-text-mode
-@findex paragraph-indent-minor-mode
- If you indent the first lines of paragraphs, then you should use
-Paragraph-Indent Text mode rather than Text mode. In this mode, you
-do not need to have blank lines between paragraphs, because the
-first-line indentation is sufficient to start a paragraph; however
-paragraphs in which every line is indented are not supported. Use
-@kbd{M-x paragraph-indent-text-mode} to enter this mode. Use @kbd{M-x
-paragraph-indent-minor-mode} to enable an equivalent minor mode in
-situations where you can't change the major mode---in mail
-composition, for instance.
-
-@kindex M-TAB @r{(Text mode)}
- Text mode, and all the modes based on it, define @kbd{M-@key{TAB}}
-as the command @code{ispell-complete-word}, which performs completion
-of the partial word in the buffer before point, using the spelling
-dictionary as the space of possible words. @xref{Spelling}. If your
-window manager defines @kbd{M-@key{TAB}} to switch windows, you can
-type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.
-
-@vindex text-mode-hook
- Entering Text mode runs the hook @code{text-mode-hook}. Other major
-modes related to Text mode also run this hook, followed by hooks of
-their own; this includes Paragraph-Indent Text mode, Nroff mode, @TeX{}
-mode, Outline mode, and Mail mode. Hook functions on
-@code{text-mode-hook} can look at the value of @code{major-mode} to see
-which of these modes is actually being entered. @xref{Hooks}.
-
-@ifnottex
- Emacs provides two other modes for editing text that is to be passed
-through a text formatter to produce fancy formatted printed output.
-@xref{Nroff Mode}, for editing input to the formatter nroff.
-@xref{TeX Mode,,@TeX{} Mode}, for editing input to the formatter TeX.
-
- Another mode is used for editing outlines. It allows you to view the
-text at various levels of detail. You can view either the outline
-headings alone or both headings and text; you can also hide some of the
-headings at lower levels from view to make the high level structure more
-visible. @xref{Outline Mode}.
-@end ifnottex
-
-@node Outline Mode
-@section Outline Mode
-@cindex Outline mode
-@cindex mode, Outline
-@cindex invisible lines
-
-@findex outline-mode
-@findex outline-minor-mode
-@vindex outline-minor-mode-prefix
- Outline mode is a major mode much like Text mode but intended for
-editing outlines. It allows you to make parts of the text temporarily
-invisible so that you can see the outline structure. Type @kbd{M-x
-outline-mode} to switch to Outline mode as the major mode of the current
-buffer.
-
- When Outline mode makes a line invisible, the line does not appear
-on the screen. The screen appears exactly as if the invisible line
-were deleted, except that an ellipsis (three periods in a row) appears
-at the end of the previous visible line. (Multiple consecutive
-invisible lines produce just one ellipsis.)
-
- Editing commands that operate on lines, such as @kbd{C-n} and
-@kbd{C-p}, treat the text of the invisible line as part of the previous
-visible line. Killing the ellipsis at the end of a visible line
-really kills all the following invisible lines.
-
- Outline minor mode provides the same commands as the major mode,
-Outline mode, but you can use it in conjunction with other major modes.
-Type @kbd{M-x outline-minor-mode} to enable the Outline minor mode in
-the current buffer. You can also specify this in the text of a file,
-with a file local variable of the form @samp{mode: outline-minor}
-(@pxref{File Variables}).
-
-@kindex C-c @@ @r{(Outline minor mode)}
- The major mode, Outline mode, provides special key bindings on the
-@kbd{C-c} prefix. Outline minor mode provides similar bindings with
-@kbd{C-c @@} as the prefix; this is to reduce the conflicts with the
-major mode's special commands. (The variable
-@code{outline-minor-mode-prefix} controls the prefix used.)
-
-@vindex outline-mode-hook
- Entering Outline mode runs the hook @code{text-mode-hook} followed by
-the hook @code{outline-mode-hook} (@pxref{Hooks}).
-
-@menu
-* Format: Outline Format. What the text of an outline looks like.
-* Motion: Outline Motion. Special commands for moving through
- outlines.
-* Visibility: Outline Visibility. Commands to control what is visible.
-* Views: Outline Views. Outlines and multiple views.
-* Foldout:: Folding means zooming in on outlines.
-@end menu
-
-@node Outline Format
-@subsection Format of Outlines
-
-@cindex heading lines (Outline mode)
-@cindex body lines (Outline mode)
- Outline mode assumes that the lines in the buffer are of two types:
-@dfn{heading lines} and @dfn{body lines}. A heading line represents a
-topic in the outline. Heading lines start with one or more stars; the
-number of stars determines the depth of the heading in the outline
-structure. Thus, a heading line with one star is a major topic; all the
-heading lines with two stars between it and the next one-star heading
-are its subtopics; and so on. Any line that is not a heading line is a
-body line. Body lines belong with the preceding heading line. Here is
-an example:
-
-@example
-* Food
-This is the body,
-which says something about the topic of food.
-
-** Delicious Food
-This is the body of the second-level header.
-
-** Distasteful Food
-This could have
-a body too, with
-several lines.
-
-*** Dormitory Food
-
-* Shelter
-Another first-level topic with its header line.
-@end example
-
- A heading line together with all following body lines is called
-collectively an @dfn{entry}. A heading line together with all following
-deeper heading lines and their body lines is called a @dfn{subtree}.
-
-@vindex outline-regexp
- You can customize the criterion for distinguishing heading lines by
-setting the variable @code{outline-regexp}. (The recommended ways to
-do this are in a major mode function or with a file local variable.)
-Any line whose beginning has a match for this regexp is considered a
-heading line. Matches that start within a line (not at the left
-margin) do not count.
-
- The length of the matching text determines the level of the heading;
-longer matches make a more deeply nested level. Thus, for example, if
-a text formatter has commands @samp{@@chapter}, @samp{@@section} and
-@samp{@@subsection} to divide the document into chapters and sections,
-you could make those lines count as heading lines by setting
-@code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}. Note
-the trick: the two words @samp{chapter} and @samp{section} are equally
-long, but by defining the regexp to match only @samp{chap} we ensure
-that the length of the text matched on a chapter heading is shorter,
-so that Outline mode will know that sections are contained in
-chapters. This works as long as no other command starts with
-@samp{@@chap}.
-
-@vindex outline-level
- You can explicitly specify a rule for calculating the level of a
-heading line by setting the variable @code{outline-level}. The value
-of @code{outline-level} should be a function that takes no arguments
-and returns the level of the current heading. The recommended ways to
-set this variable are in a major mode command or with a file local
-variable.
-
-@node Outline Motion
-@subsection Outline Motion Commands
-
- Outline mode provides special motion commands that move backward and
-forward to heading lines.
-
-@table @kbd
-@item C-c C-n
-Move point to the next visible heading line
-(@code{outline-next-visible-heading}).
-@item C-c C-p
-Move point to the previous visible heading line
-(@code{outline-previous-visible-heading}).
-@item C-c C-f
-Move point to the next visible heading line at the same level
-as the one point is on (@code{outline-forward-same-level}).
-@item C-c C-b
-Move point to the previous visible heading line at the same level
-(@code{outline-backward-same-level}).
-@item C-c C-u
-Move point up to a lower-level (more inclusive) visible heading line
-(@code{outline-up-heading}).
-@end table
-
-@findex outline-next-visible-heading
-@findex outline-previous-visible-heading
-@kindex C-c C-n @r{(Outline mode)}
-@kindex C-c C-p @r{(Outline mode)}
- @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to the next
-heading line. @kbd{C-c C-p} (@code{outline-previous-visible-heading}) moves
-similarly backward. Both accept numeric arguments as repeat counts. The
-names emphasize that invisible headings are skipped, but this is not really
-a special feature. All editing commands that look for lines ignore the
-invisible lines automatically.
-
-@findex outline-up-heading
-@findex outline-forward-same-level
-@findex outline-backward-same-level
-@kindex C-c C-f @r{(Outline mode)}
-@kindex C-c C-b @r{(Outline mode)}
-@kindex C-c C-u @r{(Outline mode)}
- More powerful motion commands understand the level structure of headings.
-@kbd{C-c C-f} (@code{outline-forward-same-level}) and
-@kbd{C-c C-b} (@code{outline-backward-same-level}) move from one
-heading line to another visible heading at the same depth in
-the outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves
-backward to another heading that is less deeply nested.
-
-@node Outline Visibility
-@subsection Outline Visibility Commands
-
- The other special commands of outline mode are used to make lines visible
-or invisible. Their names all start with @code{hide} or @code{show}.
-Most of them fall into pairs of opposites. They are not undoable; instead,
-you can undo right past them. Making lines visible or invisible is simply
-not recorded by the undo mechanism.
-
- Many of these commands act on the ``current'' heading line. If
-point is on a heading line, that is the current heading line; if point
-is on a body line, the current heading line is the nearest preceding
-header line.
-
-@table @kbd
-@item C-c C-c
-Make the current heading line's body invisible (@code{hide-entry}).
-@item C-c C-e
-Make the current heading line's body visible (@code{show-entry}).
-@item C-c C-d
-Make everything under the current heading invisible, not including the
-heading itself (@code{hide-subtree}).
-@item C-c C-s
-Make everything under the current heading visible, including body,
-subheadings, and their bodies (@code{show-subtree}).
-@item C-c C-l
-Make the body of the current heading line, and of all its subheadings,
-invisible (@code{hide-leaves}).
-@item C-c C-k
-Make all subheadings of the current heading line, at all levels,
-visible (@code{show-branches}).
-@item C-c C-i
-Make immediate subheadings (one level down) of the current heading
-line visible (@code{show-children}).
-@item C-c C-t
-Make all body lines in the buffer invisible (@code{hide-body}).
-@item C-c C-a
-Make all lines in the buffer visible (@code{show-all}).
-@item C-c C-q
-Hide everything except the top @var{n} levels of heading lines
-(@code{hide-sublevels}).
-@item C-c C-o
-Hide everything except for the heading or body that point is in, plus
-the headings leading up from there to the top level of the outline
-(@code{hide-other}).
-@end table
-
-@findex hide-entry
-@findex show-entry
-@kindex C-c C-c @r{(Outline mode)}
-@kindex C-c C-e @r{(Outline mode)}
- Two commands that are exact opposites are @kbd{C-c C-c}
-(@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}). They apply
-to the body lines directly following the current heading line.
-Subheadings and their bodies are not affected.
-
-@findex hide-subtree
-@findex show-subtree
-@kindex C-c C-s @r{(Outline mode)}
-@kindex C-c C-d @r{(Outline mode)}
-@cindex subtree (Outline mode)
- Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree})
-and @kbd{C-c C-s} (@code{show-subtree}). Both apply to the current
-heading line's @dfn{subtree}: its body, all its subheadings, both
-direct and indirect, and all of their bodies. In other words, the
-subtree contains everything following the current heading line, up to
-and not including the next heading of the same or higher rank.
-
-@findex hide-leaves
-@findex show-branches
-@kindex C-c C-l @r{(Outline mode)}
-@kindex C-c C-k @r{(Outline mode)}
- Intermediate between a visible subtree and an invisible one is having
-all the subheadings visible but none of the body. There are two
-commands for doing this, depending on whether you want to hide the
-bodies or make the subheadings visible. They are @kbd{C-c C-l}
-(@code{hide-leaves}) and @kbd{C-c C-k} (@code{show-branches}).
-
-@kindex C-c C-i @r{(Outline mode)}
-@findex show-children
- A little weaker than @code{show-branches} is @kbd{C-c C-i}
-(@code{show-children}). It makes just the direct subheadings
-visible---those one level down. Deeper subheadings remain invisible, if
-they were invisible.
-
-@findex hide-body
-@findex show-all
-@kindex C-c C-t @r{(Outline mode)}
-@kindex C-c C-a @r{(Outline mode)}
- Two commands have a blanket effect on the whole file. @kbd{C-c C-t}
-(@code{hide-body}) makes all body lines invisible, so that you see just
-the outline structure (as a special exception, it will not hide lines
-at the top of the file, preceding the first header line, even though
-these are technically body lines). @kbd{C-c C-a} (@code{show-all})
-makes all lines visible. These commands can be thought of as a pair
-of opposites even though @kbd{C-c C-a} applies to more than just body
-lines.
-
-@findex hide-sublevels
-@kindex C-c C-q @r{(Outline mode)}
- The command @kbd{C-c C-q} (@code{hide-sublevels}) hides all but the
-top level headings. With a numeric argument @var{n}, it hides everything
-except the top @var{n} levels of heading lines.
-
-@findex hide-other
-@kindex C-c C-o @r{(Outline mode)}
- The command @kbd{C-c C-o} (@code{hide-other}) hides everything except
-the heading and body text that point is in, plus its parents (the headers
-leading up from there to top level in the outline) and the top level
-headings.
-
-@findex reveal-mode
- When incremental search finds text that is hidden by Outline mode,
-it makes that part of the buffer visible. If you exit the search
-at that position, the text remains visible. You can also
-automatically make text visible as you navigate in it by using
-@kbd{M-x reveal-mode}.
-
-@node Outline Views
-@subsection Viewing One Outline in Multiple Views
-
-@cindex multiple views of outline
-@cindex views of an outline
-@cindex outline with multiple views
-@cindex indirect buffers and outlines
- You can display two views of a single outline at the same time, in
-different windows. To do this, you must create an indirect buffer using
-@kbd{M-x make-indirect-buffer}. The first argument of this command is
-the existing outline buffer name, and its second argument is the name to
-use for the new indirect buffer. @xref{Indirect Buffers}.
-
- Once the indirect buffer exists, you can display it in a window in the
-normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline
-mode commands to show and hide parts of the text operate on each buffer
-independently; as a result, each buffer can have its own view. If you
-want more than two views on the same outline, create additional indirect
-buffers.
-
-@node Foldout
-@subsection Folding Editing
-
-@cindex folding editing
- The Foldout package extends Outline mode and Outline minor mode with
-``folding'' commands. The idea of folding is that you zoom in on a
-nested portion of the outline, while hiding its relatives at higher
-levels.
-
- Consider an Outline mode buffer with all the text and subheadings under
-level-1 headings hidden. To look at what is hidden under one of these
-headings, you could use @kbd{C-c C-e} (@kbd{M-x show-entry}) to expose
-the body, or @kbd{C-c C-i} to expose the child (level-2) headings.
-
-@kindex C-c C-z
-@findex foldout-zoom-subtree
- With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}).
-This exposes the body and child subheadings, and narrows the buffer so
-that only the @w{level-1} heading, the body and the level-2 headings are
-visible. Now to look under one of the level-2 headings, position the
-cursor on it and use @kbd{C-c C-z} again. This exposes the level-2 body
-and its level-3 child subheadings and narrows the buffer again. Zooming
-in on successive subheadings can be done as much as you like. A string
-in the mode line shows how deep you've gone.
-
- When zooming in on a heading, to see only the child subheadings specify
-a numeric argument: @kbd{C-u C-c C-z}. The number of levels of children
-can be specified too (compare @kbd{M-x show-children}), e.g.@: @kbd{M-2
-C-c C-z} exposes two levels of child subheadings. Alternatively, the
-body can be specified with a negative argument: @kbd{M-- C-c C-z}. The
-whole subtree can be expanded, similarly to @kbd{C-c C-s} (@kbd{M-x
-show-subtree}), by specifying a zero argument: @kbd{M-0 C-c C-z}.
-
- While you're zoomed in, you can still use Outline mode's exposure and
-hiding functions without disturbing Foldout. Also, since the buffer is
-narrowed, ``global'' editing actions will only affect text under the
-zoomed-in heading. This is useful for restricting changes to a
-particular chapter or section of your document.
-
-@kindex C-c C-x
-@findex foldout-exit-fold
- To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}).
-This hides all the text and subheadings under the top-level heading and
-returns you to the previous view of the buffer. Specifying a numeric
-argument exits that many levels of folds. Specifying a zero argument
-exits all folds.
-
- To cancel the narrowing of a fold without hiding the text and
-subheadings, specify a negative argument. For example, @kbd{M--2 C-c
-C-x} exits two folds and leaves the text and subheadings exposed.
-
- Foldout mode also provides mouse commands for entering and exiting
-folds, and for showing and hiding text:
-
-@table @asis
-@item @kbd{C-M-Mouse-1} zooms in on the heading clicked on
-@itemize @asis
-@item
-single click: expose body.
-@item
-double click: expose subheadings.
-@item
-triple click: expose body and subheadings.
-@item
-quad click: expose entire subtree.
-@end itemize
-@item @kbd{C-M-Mouse-2} exposes text under the heading clicked on
-@itemize @asis
-@item
-single click: expose body.
-@item
-double click: expose subheadings.
-@item
-triple click: expose body and subheadings.
-@item
-quad click: expose entire subtree.
-@end itemize
-@item @kbd{C-M-Mouse-3} hides text under the heading clicked on or exits fold
-@itemize @asis
-@item
-single click: hide subtree.
-@item
-double click: exit fold and hide text.
-@item
-triple click: exit fold without hiding text.
-@item
-quad click: exit all folds and hide text.
-@end itemize
-@end table
-
-@vindex foldout-mouse-modifiers
- You can specify different modifier keys (instead of
-@kbd{Control-Meta-}) by setting @code{foldout-mouse-modifiers}; but if
-you have already loaded the @file{foldout.el} library, you must reload
-it in order for this to take effect.
-
- To use the Foldout package, you can type @kbd{M-x load-library
-@key{RET} foldout @key{RET}}; or you can arrange for to do that
-automatically by putting this in your @file{.emacs} file:
-
-@example
-(eval-after-load "outline" '(require 'foldout))
-@end example
-
-@node TeX Mode
-@section @TeX{} Mode
-@cindex @TeX{} mode
-@cindex La@TeX{} mode
-@cindex Sli@TeX{} mode
-@cindex Doc@TeX{} mode
-@cindex mode, @TeX{}
-@cindex mode, La@TeX{}
-@cindex mode, Sli@TeX{}
-@cindex mode, Doc@TeX{}
-@findex tex-mode
-@findex plain-tex-mode
-@findex latex-mode
-@findex slitex-mode
-@findex doctex-mode
-
- @TeX{} is a powerful text formatter written by Donald Knuth; it is
-also free software, like GNU Emacs. La@TeX{} is a simplified input
-format for @TeX{}, implemented by @TeX{} macros; it comes with @TeX{}.
-Sli@TeX{} is a special form of La@TeX{}.@footnote{Sli@TeX{} is
-obsoleted by the @samp{slides} document class and other alternative
-packages in recent La@TeX{} versions.} Doc@TeX{} (@file{.dtx}) is a
-special file format in which the La@TeX{} sources are written,
-combining sources with documentation.
-
- Emacs has a special @TeX{} mode for editing @TeX{} input files.
-It provides facilities for checking the balance of delimiters and for
-invoking @TeX{} on all or part of the file.
-
-@vindex tex-default-mode
- @TeX{} mode has four variants: Plain @TeX{} mode, La@TeX{} mode,
-Sli@TeX{} mode, and Doc@TeX{} mode (these distinct major modes differ
-only slightly). They are designed for editing the four different
-formats. The command @kbd{M-x tex-mode} looks at the contents of the
-buffer to determine whether the contents appear to be either La@TeX{}
-input, Sli@TeX{}, or Doc@TeX{} input; if so, it selects the
-appropriate mode. If the file contents do not appear to be La@TeX{},
-Sli@TeX{} or Doc@TeX{}, it selects Plain @TeX{} mode. If the contents
-are insufficient to determine this, the variable
-@code{tex-default-mode} controls which mode is used.
-
- When @kbd{M-x tex-mode} does not guess right, you can use the commands
-@kbd{M-x plain-tex-mode}, @kbd{M-x latex-mode}, @kbd{M-x slitex-mode},
-and @kbd{doctex-mode} to select explicitly the particular variants of
-@TeX{} mode.
-
-@menu
-* Editing: TeX Editing. Special commands for editing in TeX mode.
-* LaTeX: LaTeX Editing. Additional commands for LaTeX input files.
-* Printing: TeX Print. Commands for printing part of a file with TeX.
-* Misc: TeX Misc. Customization of TeX mode, and related features.
-@end menu
-
-@node TeX Editing
-@subsection @TeX{} Editing Commands
-
- Here are the special commands provided in @TeX{} mode for editing the
-text of the file.
-
-@table @kbd
-@item "
-Insert, according to context, either @samp{``} or @samp{"} or
-@samp{''} (@code{tex-insert-quote}).
-@item C-j
-Insert a paragraph break (two newlines) and check the previous
-paragraph for unbalanced braces or dollar signs
-(@code{tex-terminate-paragraph}).
-@item M-x tex-validate-region
-Check each paragraph in the region for unbalanced braces or dollar signs.
-@item C-c @{
-Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}).
-@item C-c @}
-Move forward past the next unmatched close brace (@code{up-list}).
-@end table
-
-@findex tex-insert-quote
-@kindex " @r{(@TeX{} mode)}
- In @TeX{}, the character @samp{"} is not normally used; we use
-@samp{``} to start a quotation and @samp{''} to end one. To make
-editing easier under this formatting convention, @TeX{} mode overrides
-the normal meaning of the key @kbd{"} with a command that inserts a pair
-of single-quotes or backquotes (@code{tex-insert-quote}). To be
-precise, this command inserts @samp{``} after whitespace or an open
-brace, @samp{"} after a backslash, and @samp{''} after any other
-character.
-
- If you need the character @samp{"} itself in unusual contexts, use
-@kbd{C-q} to insert it. Also, @kbd{"} with a numeric argument always
-inserts that number of @samp{"} characters. You can turn off the
-feature of @kbd{"} expansion by eliminating that binding in the local
-map (@pxref{Key Bindings}).
-
- In @TeX{} mode, @samp{$} has a special syntax code which attempts to
-understand the way @TeX{} math mode delimiters match. When you insert a
-@samp{$} that is meant to exit math mode, the position of the matching
-@samp{$} that entered math mode is displayed for a second. This is the
-same feature that displays the open brace that matches a close brace that
-is inserted. However, there is no way to tell whether a @samp{$} enters
-math mode or leaves it; so when you insert a @samp{$} that enters math
-mode, the previous @samp{$} position is shown as if it were a match, even
-though they are actually unrelated.
-
-@findex tex-insert-braces
-@kindex C-c @{ @r{(@TeX{} mode)}
-@findex up-list
-@kindex C-c @} @r{(@TeX{} mode)}
- @TeX{} uses braces as delimiters that must match. Some users prefer
-to keep braces balanced at all times, rather than inserting them
-singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of
-braces. It leaves point between the two braces so you can insert the
-text that belongs inside. Afterward, use the command @kbd{C-c @}}
-(@code{up-list}) to move forward past the close brace.
-
-@findex tex-validate-region
-@findex tex-terminate-paragraph
-@kindex C-j @r{(@TeX{} mode)}
- There are two commands for checking the matching of braces. @kbd{C-j}
-(@code{tex-terminate-paragraph}) checks the paragraph before point, and
-inserts two newlines to start a new paragraph. It outputs a message in
-the echo area if any mismatch is found. @kbd{M-x tex-validate-region}
-checks a region, paragraph by paragraph. The errors are listed in the
-@samp{*Occur*} buffer, and you can use @kbd{C-c C-c} or @kbd{Mouse-2} in
-that buffer to go to a particular mismatch.
-
- Note that Emacs commands count square brackets and parentheses in
-@TeX{} mode, not just braces. This is not strictly correct for the
-purpose of checking @TeX{} syntax. However, parentheses and square
-brackets are likely to be used in text as matching delimiters and it is
-useful for the various motion commands and automatic match display to
-work with them.
-
-@node LaTeX Editing
-@subsection La@TeX{} Editing Commands
-
- La@TeX{} mode, and its variant, Sli@TeX{} mode, provide a few extra
-features not applicable to plain @TeX{}.
-
-@table @kbd
-@item C-c C-o
-Insert @samp{\begin} and @samp{\end} for La@TeX{} block and position
-point on a line between them (@code{tex-latex-block}).
-@item C-c C-e
-Close the innermost La@TeX{} block not yet closed
-(@code{tex-close-latex-block}).
-@end table
-
-@findex tex-latex-block
-@kindex C-c C-o @r{(La@TeX{} mode)}
-@vindex latex-block-names
- In La@TeX{} input, @samp{\begin} and @samp{\end} commands are used to
-group blocks of text. To insert a @samp{\begin} and a matching
-@samp{\end} (on a new line following the @samp{\begin}), use @kbd{C-c
-C-o} (@code{tex-latex-block}). A blank line is inserted between the
-two, and point is left there. You can use completion when you enter the
-block type; to specify additional block type names beyond the standard
-list, set the variable @code{latex-block-names}. For example, here's
-how to add @samp{theorem}, @samp{corollary}, and @samp{proof}:
-
-@example
-(setq latex-block-names '("theorem" "corollary" "proof"))
-@end example
-
-@findex tex-close-latex-block
-@kindex C-c C-e @r{(La@TeX{} mode)}
- In La@TeX{} input, @samp{\begin} and @samp{\end} commands must
-balance. You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to
-insert automatically a matching @samp{\end} to match the last unmatched
-@samp{\begin}. It indents the @samp{\end} to match the corresponding
-@samp{\begin}. It inserts a newline after @samp{\end} if point is at
-the beginning of a line.
-
-@node TeX Print
-@subsection @TeX{} Printing Commands
-
- You can invoke @TeX{} as an inferior of Emacs on either the entire
-contents of the buffer or just a region at a time. Running @TeX{} in
-this way on just one chapter is a good way to see what your changes
-look like without taking the time to format the entire file.
-
-@table @kbd
-@item C-c C-r
-Invoke @TeX{} on the current region, together with the buffer's header
-(@code{tex-region}).
-@item C-c C-b
-Invoke @TeX{} on the entire current buffer (@code{tex-buffer}).
-@item C-c @key{TAB}
-Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}).
-@item C-c C-f
-Invoke @TeX{} on the current file (@code{tex-file}).
-@item C-c C-l
-Recenter the window showing output from the inferior @TeX{} so that
-the last line can be seen (@code{tex-recenter-output-buffer}).
-@item C-c C-k
-Kill the @TeX{} subprocess (@code{tex-kill-job}).
-@item C-c C-p
-Print the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
-C-f} command (@code{tex-print}).
-@item C-c C-v
-Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
-C-f} command (@code{tex-view}).
-@item C-c C-q
-Show the printer queue (@code{tex-show-print-queue}).
-@item C-c C-c
-Invoke some other compilation command on the entire current buffer
-(@code{tex-compile}).
-@end table
-
-@findex tex-buffer
-@kindex C-c C-b @r{(@TeX{} mode)}
-@findex tex-print
-@kindex C-c C-p @r{(@TeX{} mode)}
-@findex tex-view
-@kindex C-c C-v @r{(@TeX{} mode)}
-@findex tex-show-print-queue
-@kindex C-c C-q @r{(@TeX{} mode)}
- You can pass the current buffer through an inferior @TeX{} by means of
-@kbd{C-c C-b} (@code{tex-buffer}). The formatted output appears in a
-temporary file; to print it, type @kbd{C-c C-p} (@code{tex-print}).
-Afterward, you can use @kbd{C-c C-q} (@code{tex-show-print-queue}) to
-view the progress of your output towards being printed. If your terminal
-has the ability to display @TeX{} output files, you can preview the
-output on the terminal with @kbd{C-c C-v} (@code{tex-view}).
-
-@cindex @env{TEXINPUTS} environment variable
-@vindex tex-directory
- You can specify the directory to use for running @TeX{} by setting the
-variable @code{tex-directory}. @code{"."} is the default value. If
-your environment variable @env{TEXINPUTS} contains relative directory
-names, or if your files contains @samp{\input} commands with relative
-file names, then @code{tex-directory} @emph{must} be @code{"."} or you
-will get the wrong results. Otherwise, it is safe to specify some other
-directory, such as @code{"/tmp"}.
-
-@vindex tex-run-command
-@vindex latex-run-command
-@vindex slitex-run-command
-@vindex tex-dvi-print-command
-@vindex tex-dvi-view-command
-@vindex tex-show-queue-command
- If you want to specify which shell commands are used in the inferior @TeX{},
-you can do so by setting the values of the variables @code{tex-run-command},
-@code{latex-run-command}, @code{slitex-run-command},
-@code{tex-dvi-print-command}, @code{tex-dvi-view-command}, and
-@code{tex-show-queue-command}. The default values may
-(or may not) be appropriate for your system.
-
- Normally, the file name given to these commands comes at the end of
-the command string; for example, @samp{latex @var{filename}}. In some
-cases, however, the file name needs to be embedded in the command; an
-example is when you need to provide the file name as an argument to one
-command whose output is piped to another. You can specify where to put
-the file name with @samp{*} in the command string. For example,
-
-@example
-(setq tex-dvi-print-command "dvips -f * | lpr")
-@end example
-
-@findex tex-kill-job
-@kindex C-c C-k @r{(@TeX{} mode)}
-@findex tex-recenter-output-buffer
-@kindex C-c C-l @r{(@TeX{} mode)}
- The terminal output from @TeX{}, including any error messages, appears
-in a buffer called @samp{*tex-shell*}. If @TeX{} gets an error, you can
-switch to this buffer and feed it input (this works as in Shell mode;
-@pxref{Interactive Shell}). Without switching to this buffer you can
-scroll it so that its last line is visible by typing @kbd{C-c
-C-l}.
-
- Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if
-you see that its output is no longer useful. Using @kbd{C-c C-b} or
-@kbd{C-c C-r} also kills any @TeX{} process still running.
-
-@findex tex-region
-@kindex C-c C-r @r{(@TeX{} mode)}
- You can also pass an arbitrary region through an inferior @TeX{} by typing
-@kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because most files
-of @TeX{} input contain commands at the beginning to set parameters and
-define macros, without which no later part of the file will format
-correctly. To solve this problem, @kbd{C-c C-r} allows you to designate a
-part of the file as containing essential commands; it is included before
-the specified region as part of the input to @TeX{}. The designated part
-of the file is called the @dfn{header}.
-
-@cindex header (@TeX{} mode)
- To indicate the bounds of the header in Plain @TeX{} mode, you insert two
-special strings in the file. Insert @samp{%**start of header} before the
-header, and @samp{%**end of header} after it. Each string must appear
-entirely on one line, but there may be other text on the line before or
-after. The lines containing the two strings are included in the header.
-If @samp{%**start of header} does not appear within the first 100 lines of
-the buffer, @kbd{C-c C-r} assumes that there is no header.
-
- In La@TeX{} mode, the header begins with @samp{\documentclass} or
-@samp{\documentstyle} and ends with @samp{\begin@{document@}}. These
-are commands that La@TeX{} requires you to use in any case, so nothing
-special needs to be done to identify the header.
-
-@findex tex-file
-@kindex C-c C-f @r{(@TeX{} mode)}
- The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their
-work in a temporary directory, and do not have available any of the auxiliary
-files needed by @TeX{} for cross-references; these commands are generally
-not suitable for running the final copy in which all of the cross-references
-need to be correct.
-
- When you want the auxiliary files for cross references, use @kbd{C-c
-C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file,
-in that file's directory. Before running @TeX{}, it offers to save any
-modified buffers. Generally, you need to use (@code{tex-file}) twice to
-get the cross-references right.
-
-@vindex tex-start-options
- The value of the variable @code{tex-start-options} specifies
-options for the @TeX{} run.
-
-@vindex tex-start-commands
- The value of the variable @code{tex-start-commands} specifies @TeX{}
-commands for starting @TeX{}. The default value causes @TeX{} to run
-in nonstop mode. To run @TeX{} interactively, set the variable to
-@code{""}.
-
-@vindex tex-main-file
- Large @TeX{} documents are often split into several files---one main
-file, plus subfiles. Running @TeX{} on a subfile typically does not
-work; you have to run it on the main file. In order to make
-@code{tex-file} useful when you are editing a subfile, you can set the
-variable @code{tex-main-file} to the name of the main file. Then
-@code{tex-file} runs @TeX{} on that file.
-
- The most convenient way to use @code{tex-main-file} is to specify it
-in a local variable list in each of the subfiles. @xref{File
-Variables}.
-
-@findex tex-bibtex-file
-@kindex C-c TAB @r{(@TeX{} mode)}
-@vindex tex-bibtex-command
- For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary
-file for the current buffer's file. Bib@TeX{} looks up bibliographic
-citations in a data base and prepares the cited references for the
-bibliography section. The command @kbd{C-c @key{TAB}}
-(@code{tex-bibtex-file}) runs the shell command
-(@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the
-current buffer's file. Generally, you need to do @kbd{C-c C-f}
-(@code{tex-file}) once to generate the @samp{.aux} file, then do
-@kbd{C-c @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f}
-(@code{tex-file}) twice more to get the cross-references correct.
-
-@findex tex-compile
-@kindex C-c C-c @r{(@TeX{} mode)}
- To invoke some other compilation program on the current @TeX{}
-buffer, type @kbd{C-c C-c} (@code{tex-compile}). This command knows
-how to pass arguments to many common programs, including
-@file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}. You can
-select your desired compilation program using the standard completion
-keys (@pxref{Completion}).
-
-@node TeX Misc
-@subsection @TeX{} Mode Miscellany
-
-@vindex tex-shell-hook
-@vindex tex-mode-hook
-@vindex latex-mode-hook
-@vindex slitex-mode-hook
-@vindex plain-tex-mode-hook
- Entering any variant of @TeX{} mode runs the hooks
-@code{text-mode-hook} and @code{tex-mode-hook}. Then it runs either
-@code{plain-tex-mode-hook}, @code{latex-mode-hook}, or
-@code{slitex-mode-hook}, whichever is appropriate. Starting the
-@TeX{} shell runs the hook @code{tex-shell-hook}. @xref{Hooks}.
-
-@findex iso-iso2tex
-@findex iso-tex2iso
-@findex iso-iso2gtex
-@findex iso-gtex2iso
-@cindex Latin-1 @TeX{} encoding
-@cindex @TeX{} encoding
- The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x
-iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert
-between Latin-1 encoded files and @TeX{}-encoded equivalents.
-@ignore
-@c Too cryptic to be useful, too cryptic for me to make it better -- rms.
- They
-are included by default in the @code{format-alist} variable, so they
-can be used with @kbd{M-x format-find-file}, for instance.
-@end ignore
-
-@ignore @c Not worth documenting if it is only for Czech -- rms.
-@findex tildify-buffer
-@findex tildify-region
-@cindex ties, @TeX{}, inserting
-@cindex hard spaces, @TeX{}, inserting
- The commands @kbd{M-x tildify-buffer} and @kbd{M-x tildify-region}
-insert @samp{~} (@dfn{tie}) characters where they are conventionally
-required. This is set up for Czech---customize the group
-@samp{tildify} for other languages or for other sorts of markup.
-@end ignore
-
-@cindex Ref@TeX{} package
-@cindex references, La@TeX{}
-@cindex La@TeX{} references
- For managing all kinds of references for La@TeX{}, you can use
-Ref@TeX{}. @inforef{Top,, reftex}.
-
-@node HTML Mode
-@section SGML, XML, and HTML Modes
-
- The major modes for SGML and HTML include indentation support and
-commands to operate on tags. This section describes the special
-commands of these modes. (HTML mode is a slightly customized variant
-of SGML mode.)
-
-@table @kbd
-@item C-c C-n
-@kindex C-c C-n @r{(SGML mode)}
-@findex sgml-name-char
-Interactively specify a special character and insert the SGML
-@samp{&}-command for that character.
-
-@item C-c C-t
-@kindex C-c C-t @r{(SGML mode)}
-@findex sgml-tag
-Interactively specify a tag and its attributes (@code{sgml-tag}).
-This command asks you for a tag name and for the attribute values,
-then inserts both the opening tag and the closing tag, leaving point
-between them.
-
-With a prefix argument @var{n}, the command puts the tag around the
-@var{n} words already present in the buffer after point. With
-@minus{}1 as argument, it puts the tag around the region. (In
-Transient Mark mode, it does this whenever a region is active.)
-
-@item C-c C-a
-@kindex C-c C-a @r{(SGML mode)}
-@findex sgml-attributes
-Interactively insert attribute values for the current tag
-(@code{sgml-attributes}).
-
-@item C-c C-f
-@kindex C-c C-f @r{(SGML mode)}
-@findex sgml-skip-tag-forward
-Skip across a balanced tag group (which extends from an opening tag
-through its corresponding closing tag) (@code{sgml-skip-tag-forward}).
-A numeric argument acts as a repeat count.
-
-@item C-c C-b
-@kindex C-c C-b @r{(SGML mode)}
-@findex sgml-skip-tag-backward
-Skip backward across a balanced tag group (which extends from an
-opening tag through its corresponding closing tag)
-(@code{sgml-skip-tag-forward}). A numeric argument acts as a repeat
-count.
-
-@item C-c C-d
-@kindex C-c C-d @r{(SGML mode)}
-@findex sgml-delete-tag
-Delete the tag at or after point, and delete the matching tag too
-(@code{sgml-delete-tag}). If the tag at or after point is an opening
-tag, delete the closing tag too; if it is a closing tag, delete the
-opening tag too.
-
-@item C-c ? @var{tag} @key{RET}
-@kindex C-c ? @r{(SGML mode)}
-@findex sgml-tag-help
-Display a description of the meaning of tag @var{tag}
-(@code{sgml-tag-help}). If the argument @var{tag} is empty, describe
-the tag at point.
-
-@item C-c /
-@kindex C-c / @r{(SGML mode)}
-@findex sgml-close-tag
-Insert a close tag for the innermost unterminated tag
-(@code{sgml-close-tag}). If called from within a tag or a comment,
-close this element instead of inserting a close tag.
-
-@item C-c 8
-@kindex C-c 8 @r{(SGML mode)}
-@findex sgml-name-8bit-mode
-Toggle a minor mode in which Latin-1 characters insert the
-corresponding SGML commands that stand for them, instead of the
-characters themselves (@code{sgml-name-8bit-mode}).
-
-@item C-c C-v
-@kindex C-c C-v @r{(SGML mode)}
-@findex sgml-validate
-Run a shell command (which you must specify) to validate the current
-buffer as SGML (@code{sgml-validate}).
-
-@item C-c TAB
-@kindex C-c TAB @r{(SGML mode)}
-@findex sgml-tags-invisible
-Toggle the visibility of existing tags in the buffer. This can be
-used as a cheap preview.
-@end table
-
-@vindex sgml-xml-mode
- SGML mode and HTML mode support XML also. In XML, every opening tag
-must have an explicit closing tag. When @code{sgml-xml-mode} is
-non-@code{nil}, SGML mode and HTML mode always insert explicit
-closing tags. When you visit a file, these modes determine from the
-file contents whether it is XML or not, and set @code{sgml-xml-mode}
-accordingly, so that they do the right thing for the file in either
-case.
-
-@node Nroff Mode
-@section Nroff Mode
-
-@cindex nroff
-@findex nroff-mode
- Nroff mode is a mode like Text mode but modified to handle nroff commands
-present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It
-differs from Text mode in only a few ways. All nroff command lines are
-considered paragraph separators, so that filling will never garble the
-nroff commands. Pages are separated by @samp{.bp} commands. Comments
-start with backslash-doublequote. Also, three special commands are
-provided that are not in Text mode:
-
-@findex forward-text-line
-@findex backward-text-line
-@findex count-text-lines
-@kindex M-n @r{(Nroff mode)}
-@kindex M-p @r{(Nroff mode)}
-@kindex M-? @r{(Nroff mode)}
-@table @kbd
-@item M-n
-Move to the beginning of the next line that isn't an nroff command
-(@code{forward-text-line}). An argument is a repeat count.
-@item M-p
-Like @kbd{M-n} but move up (@code{backward-text-line}).
-@item M-?
-Displays in the echo area the number of text lines (lines that are not
-nroff commands) in the region (@code{count-text-lines}).
-@end table
-
-@findex electric-nroff-mode
- The other feature of Nroff mode is that you can turn on Electric Nroff
-mode. This is a minor mode that you can turn on or off with @kbd{M-x
-electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each
-time you use @key{RET} to end a line that contains an nroff command that
-opens a kind of grouping, the matching nroff command to close that
-grouping is automatically inserted on the following line. For example,
-if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}},
-this inserts the matching command @samp{.)b} on a new line following
-point.
-
- If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}),
-heading lines are lines of the form @samp{.H} followed by a number (the
-header level).
-
-@vindex nroff-mode-hook
- Entering Nroff mode runs the hook @code{text-mode-hook}, followed by
-the hook @code{nroff-mode-hook} (@pxref{Hooks}).
-
-@node Formatted Text
-@section Editing Formatted Text
-
-@cindex Enriched mode
-@cindex mode, Enriched
-@cindex formatted text
-@cindex WYSIWYG
-@cindex word processing
- @dfn{Enriched mode} is a minor mode for editing files that contain
-formatted text in WYSIWYG fashion, as in a word processor. Currently,
-formatted text in Enriched mode can specify fonts, colors, underlining,
-margins, and types of filling and justification. In the future, we plan
-to implement other formatting features as well.
-
- Enriched mode is a minor mode (@pxref{Minor Modes}). It is
-typically used in conjunction with Text mode (@pxref{Text Mode}), but
-you can also use it with other major modes such as Outline mode and
-Paragraph-Indent Text mode.
-
-@cindex text/enriched MIME format
- Potentially, Emacs can store formatted text files in various file
-formats. Currently, only one format is implemented: @dfn{text/enriched}
-format, which is defined by the MIME protocol. @xref{Format
-Conversion,, Format Conversion, elisp, the Emacs Lisp Reference Manual},
-for details of how Emacs recognizes and converts file formats.
-
- The Emacs distribution contains a formatted text file that can serve as
-an example. Its name is @file{etc/enriched.doc}. It contains samples
-illustrating all the features described in this section. It also
-contains a list of ideas for future enhancements.
-
-@menu
-* Requesting Formatted Text:: Entering and exiting Enriched mode.
-* Hard and Soft Newlines:: There are two different kinds of newlines.
-* Editing Format Info:: How to edit text properties.
-* Faces: Format Faces. Bold, italic, underline, etc.
-* Color: Format Colors. Changing the color of text.
-* Indent: Format Indentation. Changing the left and right margins.
-* Justification: Format Justification.
- Centering, setting text flush with the
- left or right margin, etc.
-* Other: Format Properties. The "special" text properties submenu.
-* Forcing Enriched Mode:: How to force use of Enriched mode.
-@end menu
-
-@node Requesting Formatted Text
-@subsection Requesting to Edit Formatted Text
-
- Whenever you visit a file that Emacs saved in the text/enriched
-format, Emacs automatically converts the formatting information in the
-file into Emacs's own internal format (known as @dfn{text
-properties}), and turns on Enriched mode.
-
-@findex enriched-mode
- To create a new file of formatted text, first visit the nonexistent
-file, then type @kbd{M-x enriched-mode} before you start inserting text.
-This command turns on Enriched mode. Do this before you begin inserting
-text, to ensure that the text you insert is handled properly.
-
- More generally, the command @code{enriched-mode} turns Enriched mode
-on if it was off, and off if it was on. With a prefix argument, this
-command turns Enriched mode on if the argument is positive, and turns
-the mode off otherwise.
-
- When you save a buffer while Enriched mode is enabled in it, Emacs
-automatically converts the text to text/enriched format while writing it
-into the file. When you visit the file again, Emacs will automatically
-recognize the format, reconvert the text, and turn on Enriched mode
-again.
-
-@vindex enriched-translations
- You can add annotations for saving additional text properties, which
-Emacs normally does not save, by adding to @code{enriched-translations}.
-Note that the text/enriched standard requires any non-standard
-annotations to have names starting with @samp{x-}, as in
-@samp{x-read-only}. This ensures that they will not conflict with
-standard annotations that may be added later.
-
- @xref{Text Properties,,, elisp, the Emacs Lisp Reference Manual},
-for more information about text properties.
-
-@node Hard and Soft Newlines
-@subsection Hard and Soft Newlines
-@cindex hard newline
-@cindex soft newline
-@cindex newlines, hard and soft
-
-@cindex use-hard-newlines
- In formatted text, Emacs distinguishes between two different kinds of
-newlines, @dfn{hard} newlines and @dfn{soft} newlines. (You can enable
-or disable this feature separately in any buffer with the command
-@code{use-hard-newlines}.)
-
- Hard newlines are used to separate paragraphs, or items in a list, or
-anywhere that there should always be a line break regardless of the
-margins. The @key{RET} command (@code{newline}) and @kbd{C-o}
-(@code{open-line}) insert hard newlines.
-
- Soft newlines are used to make text fit between the margins. All the
-fill commands, including Auto Fill, insert soft newlines---and they
-delete only soft newlines.
-
- Although hard and soft newlines look the same, it is important to bear
-the difference in mind. Do not use @key{RET} to break lines in the
-middle of filled paragraphs, or else you will get hard newlines that are
-barriers to further filling. Instead, let Auto Fill mode break lines,
-so that if the text or the margins change, Emacs can refill the lines
-properly. @xref{Auto Fill}.
-
- On the other hand, in tables and lists, where the lines should always
-remain as you type them, you can use @key{RET} to end lines. For these
-lines, you may also want to set the justification style to
-@code{unfilled}. @xref{Format Justification}.
-
-@node Editing Format Info
-@subsection Editing Format Information
-
- There are two ways to alter the formatting information for a formatted
-text file: with keyboard commands, and with the mouse.
-
- The easiest way to add properties to your document is with the Text
-Properties menu. You can get to this menu in two ways: from the Edit
-menu in the menu bar (use @kbd{@key{F10} e t} if you have no mouse),
-or with @kbd{C-Mouse-2} (hold the @key{CTRL} key and press the middle
-mouse button). There are also keyboard commands described in the
-following section.
-
- Most of the items in the Text Properties menu lead to other submenus.
-These are described in the sections that follow. Some items run
-commands directly:
-
-@table @code
-@findex facemenu-remove-face-props
-@item Remove Face Properties
-Delete from the region all face and color text properties
-(@code{facemenu-remove-face-props}).
-
-@findex facemenu-remove-all
-@item Remove Text Properties
-Delete @emph{all} text properties from the region
-(@code{facemenu-remove-all}).
-
-@findex describe-text-properties
-@cindex text properties of characters
-@cindex overlays at character position
-@cindex widgets at buffer position
-@cindex buttons at buffer position
-@item Describe Properties
-List all the text properties, widgets, buttons, and overlays of the
-character following point (@code{describe-text-properties}).
-
-@item Display Faces
-Display a list of all the defined faces (@code{list-faces-display}).
-
-@item Display Colors
-Display a list of all the defined colors (@code{list-colors-display}).
-@end table
-
-@node Format Faces
-@subsection Faces in Formatted Text
-
- The Faces submenu lists various Emacs faces including @code{bold},
-@code{italic}, and @code{underline} (@pxref{Faces}). These menu items
-operate on the region if it is active and nonempty. Otherwise, they
-specify to use that face for an immediately following self-inserting
-character. Instead of the menu, you can use these keyboard commands:
-
-@table @kbd
-@kindex M-o d @r{(Enriched mode)}
-@findex facemenu-set-default
-@item M-o d
-Remove all @code{face} properties from the region (which includes
-specified colors), or force the following inserted character to have no
-@code{face} property (@code{facemenu-set-default}).
-@kindex M-o b @r{(Enriched mode)}
-@findex facemenu-set-bold
-@item M-o b
-Add the face @code{bold} to the region or to the following inserted
-character (@code{facemenu-set-bold}).
-@kindex M-o i @r{(Enriched mode)}
-@findex facemenu-set-italic
-@item M-o i
-Add the face @code{italic} to the region or to the following inserted
-character (@code{facemenu-set-italic}).
-@kindex M-o l @r{(Enriched mode)}
-@findex facemenu-set-bold-italic
-@item M-o l
-Add the face @code{bold-italic} to the region or to the following
-inserted character (@code{facemenu-set-bold-italic}).
-@kindex M-o u @r{(Enriched mode)}
-@findex facemenu-set-underline
-@item M-o u
-Add the face @code{underline} to the region or to the following inserted
-character (@code{facemenu-set-underline}).
-@kindex M-o o @r{(Enriched mode)}
-@findex facemenu-set-face
-@item M-o o @var{face} @key{RET}
-Add the face @var{face} to the region or to the following inserted
-character (@code{facemenu-set-face}).
-@end table
-
- With a prefix argument, all these commands apply to an immediately
-following self-inserting character, disregarding the region.
-
- A self-inserting character normally inherits the @code{face}
-property (and most other text properties) from the preceding character
-in the buffer. If you use the above commands to specify face for the
-next self-inserting character, or the next section's commands to
-specify a foreground or background color for it, then it does not
-inherit the @code{face} property from the preceding character; instead
-it uses whatever you specified. It will still inherit other text
-properties, though.
-
- Strictly speaking, these commands apply only to the first following
-self-inserting character that you type. But if you insert additional
-characters after it, they will inherit from the first one. So it
-appears that these commands apply to all of them.
-
- Enriched mode defines two additional faces: @code{excerpt} and
-@code{fixed}. These correspond to codes used in the text/enriched file
-format.
-
- The @code{excerpt} face is intended for quotations. This face is the
-same as @code{italic} unless you customize it (@pxref{Face Customization}).
-
- The @code{fixed} face means, ``Use a fixed-width font for this part
-of the text.'' Applying the @code{fixed} face to a part of the text
-will cause that part of the text to appear in a fixed-width font, even
-if the default font is variable-width. This applies to Emacs and to
-other systems that display text/enriched format. So if you
-specifically want a certain part of the text to use a fixed-width
-font, you should specify the @code{fixed} face for that part.
-
- By default, the @code{fixed} face looks the same as @code{bold}.
-This is an attempt to distinguish it from @code{default}. You may
-wish to customize @code{fixed} to some other fixed-width medium font.
-@xref{Face Customization}.
-
- If your terminal cannot display different faces, you will not be
-able to see them, but you can still edit documents containing faces,
-and even add faces and colors to documents. The faces you specify
-will be visible when the file is viewed on a terminal that can display
-them.
-
-@node Format Colors
-@subsection Colors in Formatted Text
-
- You can specify foreground and background colors for portions of the
-text. There is a menu for specifying the foreground color and a menu
-for specifying the background color. Each color menu lists all the
-colors that you have used in Enriched mode in the current Emacs session.
-
- If you specify a color with a prefix argument---or, in Transient
-Mark mode, if the region is not active---then it applies to any
-immediately following self-inserting input. Otherwise, the command
-applies to the region.
-
- Each color menu contains one additional item: @samp{Other}. You can use
-this item to specify a color that is not listed in the menu; it reads
-the color name with the minibuffer. To display a list of available colors
-and their names, use the @samp{Display Colors} menu item in the Text
-Properties menu (@pxref{Editing Format Info}).
-
- Any color that you specify in this way, or that is mentioned in a
-formatted text file that you read in, is added to the corresponding
-color menu for the duration of the Emacs session.
-
-@findex facemenu-set-foreground
-@findex facemenu-set-background
- There are no predefined key bindings for specifying colors, but you can do so
-with the extended commands @kbd{M-x facemenu-set-foreground} and
-@kbd{M-x facemenu-set-background}. Both of these commands read the name
-of the color with the minibuffer.
-
-@node Format Indentation
-@subsection Indentation in Formatted Text
-
- When editing formatted text, you can specify different amounts of
-indentation for the right or left margin of an entire paragraph or a
-part of a paragraph. The margins you specify automatically affect the
-Emacs fill commands (@pxref{Filling}) and line-breaking commands.
-
- The Indentation submenu provides a convenient interface for specifying
-these properties. The submenu contains four items:
-
-@table @code
-@kindex C-x TAB @r{(Enriched mode)}
-@findex increase-left-margin
-@item Indent More
-Indent the region by 4 columns (@code{increase-left-margin}). In
-Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if
-you supply a numeric argument, that says how many columns to add to the
-margin (a negative argument reduces the number of columns).
-
-@item Indent Less
-Remove 4 columns of indentation from the region.
-
-@item Indent Right More
-Make the text narrower by indenting 4 columns at the right margin.
-
-@item Indent Right Less
-Remove 4 columns of indentation from the right margin.
-@end table
-
- You can use these commands repeatedly to increase or decrease the
-indentation.
-
- The most common way to use them is to change the indentation of an
-entire paragraph. For other uses, the effects of refilling can be
-hard to predict, except in some special cases like the one described
-next.
-
- The most common other use is to format paragraphs with @dfn{hanging
-indents}, which means that the first line is indented less than
-subsequent lines. To set up a hanging indent, increase the
-indentation of the region starting after the first word of the
-paragraph and running until the end of the paragraph.
-
- Indenting the first line of a paragraph is easier. Set the margin for
-the whole paragraph where you want it to be for the body of the
-paragraph, then indent the first line by inserting extra spaces or tabs.
-
-@vindex standard-indent
- The variable @code{standard-indent} specifies how many columns these
-commands should add to or subtract from the indentation. The default
-value is 4. The overall default right margin for Enriched mode is
-controlled by the variable @code{fill-column}, as usual.
-
-@kindex C-c [ @r{(Enriched mode)}
-@kindex C-c ] @r{(Enriched mode)}
-@findex set-left-margin
-@findex set-right-margin
- There are also two commands for setting the left or right margin of
-the region absolutely: @code{set-left-margin} and
-@code{set-right-margin}. Enriched mode binds these commands to
-@kbd{C-c [} and @kbd{C-c ]}, respectively. You can specify the
-margin width either with a numeric argument or in the minibuffer.
-
- Sometimes, as a result of editing, the filling of a paragraph becomes
-messed up---parts of the paragraph may extend past the left or right
-margins. When this happens, use @kbd{M-q} (@code{fill-paragraph}) to
-refill the paragraph.
-
- The fill prefix, if any, works in addition to the specified paragraph
-indentation: @kbd{C-x .} does not include the specified indentation's
-whitespace in the new value for the fill prefix, and the fill commands
-look for the fill prefix after the indentation on each line. @xref{Fill
-Prefix}.
-
-@node Format Justification
-@subsection Justification in Formatted Text
-
- When editing formatted text, you can specify various styles of
-justification for a paragraph. The style you specify automatically
-affects the Emacs fill commands.
-
- The Justification submenu provides a convenient interface for specifying
-the style. The submenu contains five items:
-
-@table @code
-@item Left
-This is the most common style of justification (at least for English).
-Lines are aligned at the left margin but left uneven at the right.
-
-@item Right
-This aligns each line with the right margin. Spaces and tabs are added
-on the left, if necessary, to make lines line up on the right.
-
-@item Full
-This justifies the text, aligning both edges of each line. Justified
-text looks very nice in a printed book, where the spaces can all be
-adjusted equally, but it does not look as nice with a fixed-width font
-on the screen. Perhaps a future version of Emacs will be able to adjust
-the width of spaces in a line to achieve elegant justification.
-
-@item Center
-This centers every line between the current margins.
-
-@item Unfilled
-This turns off filling entirely. Each line will remain as you wrote it;
-the fill and auto-fill functions will have no effect on text which has
-this setting. You can, however, still indent the left margin. In
-unfilled regions, all newlines are treated as hard newlines (@pxref{Hard
-and Soft Newlines}) .
-@end table
-
- In Enriched mode, you can also specify justification from the keyboard
-using the @kbd{M-j} prefix character:
-
-@table @kbd
-@kindex M-j l @r{(Enriched mode)}
-@findex set-justification-left
-@item M-j l
-Make the region left-filled (@code{set-justification-left}).
-@kindex M-j r @r{(Enriched mode)}
-@findex set-justification-right
-@item M-j r
-Make the region right-filled (@code{set-justification-right}).
-@kindex M-j b @r{(Enriched mode)}
-@findex set-justification-full
-@item M-j b
-Make the region fully justified (@code{set-justification-full}).
-@kindex M-j c @r{(Enriched mode)}
-@kindex M-S @r{(Enriched mode)}
-@findex set-justification-center
-@item M-j c
-@itemx M-S
-Make the region centered (@code{set-justification-center}).
-@kindex M-j u @r{(Enriched mode)}
-@findex set-justification-none
-@item M-j u
-Make the region unfilled (@code{set-justification-none}).
-@end table
-
- Justification styles apply to entire paragraphs. All the
-justification-changing commands operate on the paragraph containing
-point, or, if the region is active, on all paragraphs which overlap the
-region.
-
-@vindex default-justification
- The default justification style is specified by the variable
-@code{default-justification}. Its value should be one of the symbols
-@code{left}, @code{right}, @code{full}, @code{center}, or @code{none}.
-This is a per-buffer variable. Setting the variable directly affects
-only the current buffer. However, customizing it in a Custom buffer
-sets (as always) the default value for buffers that do not override it.
-@xref{Locals}, and @ref{Easy Customization}.
-
-@node Format Properties
-@subsection Setting Other Text Properties
-
- The Special Properties menu lets you add or remove three other useful text
-properties: @code{read-only}, @code{invisible} and @code{intangible}.
-The @code{intangible} property disallows moving point within the text,
-the @code{invisible} text property hides text from display, and the
-@code{read-only} property disallows alteration of the text.
-
- Each of these special properties has a menu item to add it to the
-region. The last menu item, @samp{Remove Special}, removes all of these
-special properties from the text in the region.
-
- Currently, the @code{invisible} and @code{intangible} properties are
-@emph{not} saved in the text/enriched format. The @code{read-only}
-property is saved, but it is not a standard part of the text/enriched
-format, so other editors may not respect it.
-
-@node Forcing Enriched Mode
-@subsection Forcing Enriched Mode
-
- Normally, Emacs knows when you are editing formatted text because it
-recognizes the special annotations used in the file that you visited.
-However, sometimes you must take special actions to convert file
-contents or turn on Enriched mode:
-
-@itemize @bullet
-@item
-When you visit a file that was created with some other editor, Emacs may
-not recognize the file as being in the text/enriched format. In this
-case, when you visit the file you will see the formatting commands
-rather than the formatted text. Type @kbd{M-x format-decode-buffer} to
-translate it. This also automatically turns on Enriched mode.
-
-@item
-When you @emph{insert} a file into a buffer, rather than visiting it,
-Emacs does the necessary conversions on the text which you insert, but
-it does not enable Enriched mode. If you wish to do that, type @kbd{M-x
-enriched-mode}.
-@end itemize
-
- The command @code{format-decode-buffer} translates text in various
-formats into Emacs's internal format. It asks you to specify the format
-to translate from; however, normally you can type just @key{RET}, which
-tells Emacs to guess the format.
-
-@findex format-find-file
- If you wish to look at a text/enriched file in its raw form, as a
-sequence of characters rather than as formatted text, use the @kbd{M-x
-find-file-literally} command. This visits a file, like
-@code{find-file}, but does not do format conversion. It also inhibits
-character code conversion (@pxref{Coding Systems}) and automatic
-uncompression (@pxref{Compressed Files}). To disable format conversion
-but allow character code conversion and/or automatic uncompression if
-appropriate, use @code{format-find-file} with suitable arguments.
-
-@node Text Based Tables
-@section Editing Text-based Tables
-@cindex table mode
-@cindex text-based tables
-
- Table mode provides an easy and intuitive way to create and edit WYSIWYG
-text-based tables. Here is an example of such a table:
-
-@smallexample
-@group
-+-----------------+--------------------------------+-----------------+
-| Command | Description | Key Binding |
-+-----------------+--------------------------------+-----------------+
-| forward-char |Move point right N characters | C-f |
-| |(left if N is negative). | |
-| | | |
-| |On reaching end of buffer, stop | |
-| |and signal error. | |
-+-----------------+--------------------------------+-----------------+
-| backward-char |Move point left N characters | C-b |
-| |(right if N is negative). | |
-| | | |
-| |On attempt to pass beginning or | |
-| |end of buffer, stop and signal | |
-| |error. | |
-+-----------------+--------------------------------+-----------------+
-@end group
-@end smallexample
-
- Table mode allows the contents of the table such as this one to be
-easily manipulated by inserting or deleting characters inside a cell.
-A cell is effectively a localized rectangular edit region and edits to
-a cell do not affect the contents of the surrounding cells. If the
-contents do not fit into a cell, then the cell is automatically
-expanded in the vertical and/or horizontal directions and the rest of
-the table is restructured and reformatted in accordance with the
-growth of the cell.
-
-@menu
-* Table Definition:: What is a text based table.
-* Table Creation:: How to create a table.
-* Table Recognition:: How to activate and deactivate tables.
-* Cell Commands:: Cell-oriented commands in a table.
-* Cell Justification:: Justifying cell contents.
-* Row Commands:: Manipulating rows of table cell.
-* Column Commands:: Manipulating columns of table cell.
-* Fixed Width Mode:: Fixing cell width.
-* Table Conversion:: Converting between plain text and tables.
-* Measuring Tables:: Analyzing table dimension.
-* Table Misc:: Table miscellany.
-@end menu
-
-@node Table Definition
-@subsection What is a Text-based Table?
-
- Keep the following examples of valid tables in mind as a reference
-while you read this section:
-
-@example
- +--+----+---+ +-+ +--+-----+
- | | | | | | | | |
- +--+----+---+ +-+ | +--+--+
- | | | | | | | |
- +--+----+---+ +--+--+ |
- | | |
- +-----+--+
-@end example
-
- A table consists of a rectangular frame whose inside is divided into
-cells. Each cell must be at least one character wide and one
-character high, not counting its border lines. A cell can be
-subdivided into multiple rectangular cells, but cells cannot overlap.
-
- The table frame and cell border lines are made of three special
-characters. These variables specify those characters:
-
-@table @code
-@vindex table-cell-vertical-char
-@item table-cell-vertical-char
-Holds the character used for vertical lines. The default value is
-@samp{|}.
-
-@vindex table-cell-horizontal-char
-@item table-cell-horizontal-char
-Holds the character used for horizontal lines. The default value is
-@samp{-}.
-
-@vindex table-cell-intersection-char
-@item table-cell-intersection-char
-Holds the character used at where horizontal line and vertical line
-meet. The default value is @samp{+}.
-@end table
-
-@noindent
-Based on this definition, the following five tables are examples of invalid
-tables:
-
-@example
- +-----+ +-----+ +--+ +-++--+ ++
- | | | | | | | || | ++
- | +-+ | | | | | | || |
- | | | | +--+ | +--+--+ +-++--+
- | +-+ | | | | | | | +-++--+
- | | | | | | | | | || |
- +-----+ +--+--+ +--+--+ +-++--+
- a b c d e
-@end example
-
-From left to right:
-
-@enumerate a
-@item
-Overlapped cells or non-rectangular cells are not allowed.
-@item
-Same as a.
-@item
-The border must be rectangular.
-@item
-Cells must have a minimum width/height of one character.
-@item
-Same as d.
-@end enumerate
-
-@node Table Creation
-@subsection How to Create a Table?
-@cindex create a text-based table
-@cindex table creation
-
-@findex table-insert
- The command to create a table is @code{table-insert}. When called
-interactively, it asks for the number of columns, number of rows, cell
-width and cell height. The number of columns is the number of cells
-horizontally side by side. The number of rows is the number of cells
-vertically within the table's height. The cell width is a number of
-characters that each cell holds, left to right. The cell height is a
-number of lines each cell holds. The cell width and the cell height
-can be either an integer (when the value is constant across the table)
-or a series of integer, separated by spaces or commas, where each
-number corresponds to the next cell within a row from left to right,
-or the next cell within a column from top to bottom.
-
-@node Table Recognition
-@subsection Table Recognition
-@cindex table recognition
-
-@findex table-recognize
-@findex table-unrecognize
- Table mode maintains special text properties in the buffer to allow
-editing in a convenient fashion. When a buffer with tables is saved
-to its file, these text properties are lost, so when you visit this
-file again later, Emacs does not see a table, but just formatted text.
-To resurrect the table text properties, issue the @kbd{M-x
-table-recognize} command. It scans the current buffer, recognizes
-valid table cells, and attaches appropriate text properties to allow
-for table editing. The converse command, @code{table-unrecognize}, is
-used to remove the special text properties and convert the buffer back
-to plain text.
-
- Special commands exist to enable or disable tables within a region,
-enable or disable individual tables, and enable/disable individual
-cells. These commands are:
-
-@table @kbd
-@findex table-recognize-region
-@item M-x table-recognize-region
-Recognize tables within the current region and activate them.
-@findex table-unrecognize-region
-@item M-x table-unrecognize-region
-Deactivate tables within the current region.
-@findex table-recognize-table
-@item M-x table-recognize-table
-Recognize the table under point and activate it.
-@findex table-unrecognize-table
-@item M-x table-unrecognize-table
-Deactivate the table under point.
-@findex table-recognize-cell
-@item M-x table-recognize-cell
-Recognize the cell under point and activate it.
-@findex table-unrecognize-cell
-@item M-x table-unrecognize-cell
-Deactivate the cell under point.
-@end table
-
- For another way of converting text into tables, see @ref{Table
-Conversion}.
-
-@node Cell Commands
-@subsection Commands for Table Cells
-
-@findex table-forward-cell
-@findex table-backward-cell
- The commands @code{table-forward-cell} and
-@code{table-backward-cell} move point from the current cell to an
-adjacent cell forward and backward respectively. The order of the
-cells is cyclic: when point is in the last cell of a table, typing
-@kbd{M-x table-forward-cell} moves to the first cell in the table.
-Likewise @kbd{M-x table-backward-cell} from the first cell in a table
-moves to the last cell.
-
-@findex table-span-cell
- The command @code{table-span-cell} merges the current cell with the
-adjacent cell in a specified direction---right, left, above or below.
-You specify the direction with the minibuffer. It does not allow
-merges which don't result in a legitimate cell layout.
-
-@findex table-split-cell
-@cindex text-based tables, split a cell
-@cindex split table cell
- The command @code{table-split-cell} splits the current cell
-vertically or horizontally. This command is a wrapper to the
-direction specific commands @code{table-split-cell-vertically} and
-@code{table-split-cell-horizontally}. You specify the direction with
-a minibuffer argument.
-
-@findex table-split-cell-vertically
- The command @code{table-split-cell-vertically} splits the current
-cell vertically and creates a pair of cells above and below where
-point is located. The content in the original cell is split as well.
-
-@findex table-split-cell-horizontally
- The command @code{table-split-cell-horizontally} splits the current
-cell horizontally and creates a pair of cells right and left of where
-point is located. If the cell being split is not empty, this asks you
-how to handle the cell contents. The three options are: @code{split},
-@code{left}, or @code{right}. @code{split} splits the contents at
-point literally, while the @code{left} and @code{right} options move
-the entire contents into the left or right cell respectively.
-
-@cindex enlarge a table cell
-@cindex shrink a table cell
- The next four commands enlarge or shrink a cell. They use numeric
-arguments (@pxref{Arguments}) to specify how many columns or rows to
-enlarge or shrink a particular table.
-
-@table @kbd
-@findex table-heighten-cell
-@item M-x table-heighten-cell
-Enlarge the current cell vertically.
-@findex table-shorten-cell
-@item M-x table-shorten-cell
-Shrink the current cell vertically.
-@findex table-widen-cell
-@item M-x table-widen-cell
-Enlarge the current cell horizontally.
-@findex table-narrow-cell
-@item M-x table-narrow-cell
-Shrink the current cell horizontally.
-@end table
-
-@node Cell Justification
-@subsection Cell Justification
-@cindex cell text justification
-
- You can specify text justification for each cell. The justification
-is remembered independently for each cell and the subsequent editing
-of cell contents is subject to the specified justification.
-
-@findex table-justify
- The command @code{table-justify} ask you to specify what to justify:
-a cell, a column, or a row. If you select cell justification, this
-command sets the justification only for the current cell. Selecting
-column or row justification sets the justification for all the cells
-within a column or row respectively. The command then ask you which
-kind of justification to apply: @code{left}, @code{center},
-@code{right}, @code{top}, @code{middle}, @code{bottom}, or
-@code{none}. Horizontal justification and vertical justification are
-specified independently. The options @code{left}, @code{center}, and
-@code{right} specify horizontal justification while the options
-@code{top}, @code{middle}, @code{bottom}, and @code{none} specify
-vertical justification. The vertical justification @code{none}
-effectively removes vertical justification. Horizontal justification
-must be one of @code{left}, @code{center}, or @code{right}.
-
-@vindex table-detect-cell-alignment
- Justification information is stored in the buffer as a part of text
-property. Therefore, this information is ephemeral and does not
-survive through the loss of the buffer (closing the buffer and
-revisiting the buffer erase any previous text properties). To
-countermand for this, the command @code{table-recognize} and other
-recognition commands (@pxref{Table Recognition}) are equipped with a
-convenience feature (turned on by default). During table recognition,
-the contents of a cell are examined to determine which justification
-was originally applied to the cell and then applies this justification
-to the cell. This is a speculative algorithm and is therefore not
-perfect, however, the justification is deduced correctly most of the
-time. To disable this feature, customize the variable
-@code{table-detect-cell-alignment} and set it to @code{nil}.
-
-@node Row Commands
-@subsection Commands for Table Rows
-@cindex table row commands
-
-@cindex insert row in table
-@findex table-insert-row
- The command @code{table-insert-row} inserts a row of cells before
-the current row in a table. The current row where point is located is
-pushed down after the newly inserted row. A numeric prefix argument
-specifies the number of rows to insert. Note that in order to insert
-rows @emph{after} the last row at the bottom of a table, you must
-place point below the table---that is, outside the table---prior to
-invoking this command.
-
-@cindex delete row in table
-@findex table-delete-row
- The command @code{table-delete-row} deletes a row of cells at point.
-A numeric prefix argument specifies the number of rows to delete.
-
-@node Column Commands
-@subsection Commands for Table Columns
-@cindex table column commands
-
-@cindex insert column in table
-@findex table-insert-column
- The command @code{table-insert-column} inserts a column of cells to
-the left of the current row in a table. This pushes the current
-column to the right. To insert a column to the right side of the
-rightmost column, place point to the right of the rightmost column,
-which is outside of the table, prior to invoking this command. A
-numeric prefix argument specifies the number of columns to insert.
-
-@cindex delete column in table
- A command @code{table-delete-column} deletes a column of cells at
-point. A numeric prefix argument specifies the number of columns to
-delete.
-
-@node Fixed Width Mode
-@subsection Fix Width of Cells
-@cindex fix width of table cells
-
-@findex table-fixed-width-mode
- The command @code{table-fixed-width-mode} toggles fixed width mode
-on and off. When fixed width mode is turned on, editing inside a
-cell never changes the cell width; when it is off, the cell width
-expands automatically in order to prevent a word from being folded
-into multiple lines. By default, fixed width mode is disabled.
-
-@node Table Conversion
-@subsection Conversion Between Plain Text and Tables
-@cindex text to table
-@cindex table to text
-
-@findex table-capture
- The command @code{table-capture} captures plain text in a region and
-turns it into a table. Unlike @code{table-recognize} (@pxref{Table
-Recognition}), the original text does not have a table appearance but
-may hold a logical table structure. For example, some elements
-separated by known patterns form a two dimensional structure which can
-be turned into a table.
-
- Here's an example of data that @code{table-capture} can operate on.
-The numbers are horizontally separated by a comma and vertically
-separated by a newline character.
-
-@example
-1, 2, 3, 4
-5, 6, 7, 8
-, 9, 10
-@end example
-
-@noindent
-Invoking @kbd{M-x table-capture} on that text produces this table:
-
-@example
-+-----+-----+-----+-----+
-|1 |2 |3 |4 |
-+-----+-----+-----+-----+
-|5 |6 |7 |8 |
-+-----+-----+-----+-----+
-| |9 |10 | |
-+-----+-----+-----+-----+
-@end example
-
-@noindent
-The conversion uses @samp{,} for the column delimiter and newline for
-a row delimiter, cells are left justified, and minimum cell width is
-5.
-
-@findex table-release
- The command @code{table-release} does the opposite of
-@code{table-capture}. It releases a table by removing the table frame
-and cell borders. This leaves the table contents as plain text. One
-of the useful applications of @code{table-capture} and
-@code{table-release} is to edit a text in layout. Look at the
-following three paragraphs (the latter two are indented with header
-lines):
-
-@example
-@samp{table-capture} is a powerful command, but mastering its
-power requires some practice. Here are some things it can do:
-
-Parse Cell Items By using column delimiter regular
- expression and raw delimiter regular
- expression, it parses the specified text
- area and extracts cell items from
- non-table text and then forms a table out
- of them.
-
-Capture Text Area When no delimiters are specified it
- creates a single cell table. The text in
- the specified region is placed in that
- cell.
-@end example
-
-@noindent
-Applying @code{table-capture} to a region containing the above three
-paragraphs, with empty strings for column delimiter regexp and row
-delimiter regexp, creates a table with a single cell like the
-following one.
-
-@c The first line's right-hand frame in the following two examples
-@c sticks out to accommodate for the removal of @samp in the
-@c produced output!!
-@smallexample
-@group
-+-----------------------------------------------------------------+
-|@samp{table-capture} is a powerful command, but mastering its |
-|power requires some practice. Here are some things it can do: |
-| |
-|Parse Cell Items By using column delimiter regular |
-| expression and raw delimiter regular |
-| expression, it parses the specified text |
-| area and extracts cell items from |
-| non-table text and then forms a table out |
-| of them. |
-| |
-|Capture Text Area When no delimiters are specified it |
-| creates a single cell table. The text in |
-| the specified region is placed in that |
-| cell. |
-+-----------------------------------------------------------------+
-@end group
-@end smallexample
-
-@noindent
-By splitting the cell appropriately we now have a table consisting of
-paragraphs occupying its own cell. Each cell can now be edited
-independently without affecting the layout of other cells.
-
-@smallexample
-+-----------------------------------------------------------------+
-|@samp{table-capture} is a powerful command, but mastering its |
-|power requires some practice. Here are some things it can do: |
-+---------------------+-------------------------------------------+
-|Parse Cell Items |By using column delimiter regular |
-| |expression and raw delimiter regular |
-| |expression, it parses the specified text |
-| |area and extracts cell items from |
-| |non-table text and then forms a table out |
-| |of them. |
-+---------------------+-------------------------------------------+
-|Capture Text Area |When no delimiters are specified it |
-| |creates a single cell table. The text in |
-| |the specified region is placed in that |
-| |cell. |
-+---------------------+-------------------------------------------+
-@end smallexample
-
-@noindent
-By applying @code{table-release}, which does the opposite process, the
-contents become once again plain text. @code{table-release} works as
-a companion command to @code{table-capture}.
-
-@node Measuring Tables
-@subsection Analyzing Table Dimensions
-@cindex table dimensions
-
-@findex table-query-dimension
- The command @code{table-query-dimension} analyzes a table structure
-and reports information regarding its dimensions. In case of the
-above example table, the @code{table-query-dimension} command displays
-in echo area:
-
-@smallexample
-Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5
-@end smallexample
-
-@noindent
-This indicates that the current cell is 21 character wide and 6 lines
-high, the entire table is 67 characters wide and 16 lines high. The
-table has 2 columns and 3 rows. It has a total of 5 cells, since the
-first row has a spanned cell.
-
-@node Table Misc
-@subsection Table Miscellany
-
-@cindex insert string into table cells
-@findex table-insert-sequence
- The command @code{table-insert-sequence} inserts a string into each
-cell. Each string is a part of a sequence i.e.@: a series of
-increasing integer numbers.
-
-@cindex table in language format
-@cindex table for HTML and LaTeX
-@findex table-generate-source
- The command @code{table-generate-source} generates a table formatted
-for a specific markup language. It asks for a language (which must be
-one of @code{html}, @code{latex}, or @code{cals}), a destination
-buffer where to put the result, and the table caption (a string), and
-then inserts the generated table in the proper syntax into the
-destination buffer. The default destination buffer is
-@code{table.@var{lang}}, where @var{lang} is the language you
-specified.
-
-@ignore
- arch-tag: 8db54ed8-2036-49ca-b0df-23811d03dc70
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@iftex
-@chapter Dealing with Common Problems
-
- If you type an Emacs command you did not intend, the results are often
-mysterious. This chapter tells what you can do to cancel your mistake or
-recover from a mysterious situation. Emacs bugs and system crashes are
-also considered.
-@end iftex
-
-@ifnottex
-@raisesections
-@end ifnottex
-
-@node Quitting, Lossage, Customization, Top
-@section Quitting and Aborting
-@cindex quitting
-
-@table @kbd
-@item C-g
-@itemx C-@key{BREAK} @r{(MS-DOS only)}
-Quit: cancel running or partially typed command.
-@item C-]
-Abort innermost recursive editing level and cancel the command which
-invoked it (@code{abort-recursive-edit}).
-@item @key{ESC} @key{ESC} @key{ESC}
-Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}).
-@item M-x top-level
-Abort all recursive editing levels that are currently executing.
-@item C-x u
-Cancel a previously made change in the buffer contents (@code{undo}).
-@end table
-
- There are two ways of canceling a command before it has finished:
-@dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]} or
-@kbd{M-x top-level}. Quitting cancels a partially typed command, or
-one which is still running. Aborting exits a recursive editing level
-and cancels the command that invoked the recursive edit.
-(@xref{Recursive Edit}.)
-
-@cindex quitting
-@kindex C-g
- Quitting with @kbd{C-g} is the way to get rid of a partially typed
-command, or a numeric argument that you don't want. It also stops a
-running command in the middle in a relatively safe way, so you can use
-it if you accidentally give a command which takes a long time. In
-particular, it is safe to quit out of a kill command; either your text
-will @emph{all} still be in the buffer, or it will @emph{all} be in
-the kill ring, or maybe both. Quitting an incremental search does
-special things, documented under searching; it may take two successive
-@kbd{C-g} characters to get out of a search (@pxref{Incremental
-Search}).
-
- On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit character
-like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to
-recognize @kbd{C-g} while a command is running, between interactions
-with the user. By contrast, it @emph{is} feasible to recognize
-@kbd{C-@key{BREAK}} at all times.
-@iftex
-@xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}.
-@end iftex
-@ifnottex
-@xref{MS-DOS Keyboard}.
-@end ifnottex
-
-
-@findex keyboard-quit
- @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t}
-the instant @kbd{C-g} is typed; Emacs Lisp checks this variable
-frequently, and quits if it is non-@code{nil}. @kbd{C-g} is only
-actually executed as a command if you type it while Emacs is waiting for
-input. In that case, the command it runs is @code{keyboard-quit}.
-
- On a text terminal, if you quit with @kbd{C-g} a second time before
-the first @kbd{C-g} is recognized, you activate the ``emergency
-escape'' feature and return to the shell. @xref{Emergency Escape}.
-
-@cindex NFS and quitting
- There are some situations where you cannot quit. When Emacs is
-waiting for the operating system to do something, quitting is
-impossible unless special pains are taken for the particular system
-call within Emacs where the waiting occurs. We have done this for the
-system calls that users are likely to want to quit from, but it's
-possible you will a case not handled. In one very common
-case---waiting for file input or output using NFS---Emacs itself knows
-how to quit, but many NFS implementations simply do not allow user
-programs to stop waiting for NFS when the NFS server is hung.
-
-@cindex aborting recursive edit
-@findex abort-recursive-edit
-@kindex C-]
- Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get
-out of a recursive editing level and cancel the command which invoked
-it. Quitting with @kbd{C-g} does not do this, and could not do this,
-because it is used to cancel a partially typed command @emph{within} the
-recursive editing level. Both operations are useful. For example, if
-you are in a recursive edit and type @kbd{C-u 8} to enter a numeric
-argument, you can cancel that argument with @kbd{C-g} and remain in the
-recursive edit.
-
-@findex keyboard-escape-quit
-@kindex ESC ESC ESC
- The sequence @kbd{@key{ESC} @key{ESC} @key{ESC}}
-(@code{keyboard-escape-quit}) can either quit or abort. (We defined
-it this way because @key{ESC} means ``get out'' in many PC programs.)
-It can cancel a prefix argument, clear a selected region, or get out
-of a Query Replace, like @kbd{C-g}. It can get out of the minibuffer
-or a recursive edit, like @kbd{C-]}. It can also get out of splitting
-the frame into multiple windows, as with @kbd{C-x 1}. One thing it
-cannot do, however, is stop a command that is running. That's because
-it executes as an ordinary command, and Emacs doesn't notice it until
-it is ready for the next command.
-
-@findex top-level
- The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]}
-commands to get you out of all the levels of recursive edits that you
-are in. @kbd{C-]} gets you out one level at a time, but @kbd{M-x
-top-level} goes out all levels at once. Both @kbd{C-]} and @kbd{M-x
-top-level} are like all other commands, and unlike @kbd{C-g}, in that
-they take effect only when Emacs is ready for a command. @kbd{C-]} is
-an ordinary key and has its meaning only because of its binding in the
-keymap. @xref{Recursive Edit}.
-
- @kbd{C-x u} (@code{undo}) is not strictly speaking a way of canceling
-a command, but you can think of it as canceling a command that already
-finished executing. @xref{Undo}, for more information
-about the undo facility.
-
-@node Lossage, Bugs, Quitting, Top
-@section Dealing with Emacs Trouble
-
- This section describes various conditions in which Emacs fails to work
-normally, and how to recognize them and correct them. For a list of
-additional problems you might encounter, see @ref{Bugs and problems, ,
-Bugs and problems, efaq, GNU Emacs FAQ}, and the file @file{etc/PROBLEMS}
-in the Emacs distribution. Type @kbd{C-h C-f} to read the FAQ; type
-@kbd{C-h C-e} to read the @file{PROBLEMS} file.
-
-@menu
-* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete.
-* Stuck Recursive:: `[...]' in mode line around the parentheses.
-* Screen Garbled:: Garbage on the screen.
-* Text Garbled:: Garbage in the text.
-* Memory Full:: How to cope when you run out of memory.
-* After a Crash:: Recovering editing in an Emacs session that crashed.
-* Emergency Escape:: Emergency escape---
- What to do if Emacs stops responding.
-* Total Frustration:: When you are at your wits' end.
-@end menu
-
-@node DEL Does Not Delete
-@subsection If @key{DEL} Fails to Delete
-@cindex @key{DEL} vs @key{BACKSPACE}
-@cindex @key{BACKSPACE} vs @key{DEL}
-@cindex usual erasure key
-
- Every keyboard has a large key, a little ways above the @key{RET} or
-@key{ENTER} key, which you normally use outside Emacs to erase the
-last character that you typed. We call this key @dfn{the usual
-erasure key}. In Emacs, it is supposed to be equivalent to @key{DEL},
-and when Emacs is properly configured for your terminal, it translates
-that key into the character @key{DEL}.
-
- When Emacs starts up on a graphical display, it determines
-automatically which key should be @key{DEL}. In some unusual cases
-Emacs gets the wrong information from the system. If the usual
-erasure key deletes forwards instead of backwards, that is probably
-what happened---Emacs ought to be treating the @key{DELETE} key as
-@key{DEL}, but it isn't.
-
- On a graphical display, if the usual erasure key is labeled
-@key{BACKSPACE} and there is a @key{DELETE} key elsewhere, but the
-@key{DELETE} key deletes backward instead of forward, that too
-suggests Emacs got the wrong information---but in the opposite sense.
-It ought to be treating the @key{BACKSPACE} key as @key{DEL}, and
-treating @key{DELETE} differently, but it isn't.
-
- On a text-only terminal, if you find the usual erasure key prompts
-for a Help command, like @kbd{Control-h}, instead of deleting a
-character, it means that key is actually sending the @key{BS}
-character. Emacs ought to be treating @key{BS} as @key{DEL}, but it
-isn't.
-
- In all of those cases, the immediate remedy is the same: use the
-command @kbd{M-x normal-erase-is-backspace-mode}. This toggles
-between the two modes that Emacs supports for handling @key{DEL}, so
-if Emacs starts in the wrong mode, this should switch to the right
-mode. On a text-only terminal, if you want to ask for help when
-@key{BS} is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also
-work, if it sends character code 127.
-
-@findex normal-erase-is-backspace-mode
- To fix the problem automatically for every Emacs session, you can
-put one of the following lines into your @file{.emacs} file
-(@pxref{Init File}). For the first case above, where @key{DELETE}
-deletes forwards instead of backwards, use this line to make
-@key{DELETE} act as @key{DEL} (resulting in behavior compatible
-with Emacs 20 and previous versions):
-
-@lisp
-(normal-erase-is-backspace-mode 0)
-@end lisp
-
-@noindent
-For the other two cases, where @key{BACKSPACE} ought to act as
-@key{DEL}, use this line:
-
-@lisp
-(normal-erase-is-backspace-mode 1)
-@end lisp
-
-@vindex normal-erase-is-backspace
- Another way to fix the problem for every Emacs session is to
-customize the variable @code{normal-erase-is-backspace}: the value
-@code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is
-@key{DEL}, and @code{nil} specifies the other mode. @xref{Easy
-Customization}.
-
- On a graphical display, it can also happen that the usual erasure key
-is labeled @key{BACKSPACE}, there is a @key{DELETE} key elsewhere, and
-both keys delete forward. This probably means that someone has
-redefined your @key{BACKSPACE} key as a @key{DELETE} key. With X,
-this is typically done with a command to the @code{xmodmap} program
-when you start the server or log in. The most likely motive for this
-customization was to support old versions of Emacs, so we recommend
-you simply remove it now.
-
-@node Stuck Recursive
-@subsection Recursive Editing Levels
-
- Recursive editing levels are important and useful features of Emacs, but
-they can seem like malfunctions if you do not understand them.
-
- If the mode line has square brackets @samp{[@dots{}]} around the parentheses
-that contain the names of the major and minor modes, you have entered a
-recursive editing level. If you did not do this on purpose, or if you
-don't understand what that means, you should just get out of the recursive
-editing level. To do so, type @kbd{M-x top-level}. This is called getting
-back to top level. @xref{Recursive Edit}.
-
-@node Screen Garbled
-@subsection Garbage on the Screen
-
- If the text on a text terminal looks wrong, the first thing to do is
-see whether it is wrong in the buffer. Type @kbd{C-l} to redisplay
-the entire screen. If the screen appears correct after this, the
-problem was entirely in the previous screen update. (Otherwise, see
-the following section.)
-
- Display updating problems often result from an incorrect terminfo
-entry for the terminal you are using. The file @file{etc/TERMS} in
-the Emacs distribution gives the fixes for known problems of this
-sort. @file{INSTALL} contains general advice for these problems in
-one of its sections. To investigate the possibility that you have
-this sort of problem, try Emacs on another terminal made by a
-different manufacturer. If problems happen frequently on one kind of
-terminal but not another kind, it is likely to be a bad terminfo entry,
-though it could also be due to a bug in Emacs that appears for
-terminals that have or that lack specific features.
-
-@node Text Garbled
-@subsection Garbage in the Text
-
- If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l} to
-see what commands you typed to produce the observed results. Then try
-undoing the changes step by step using @kbd{C-x u}, until it gets back
-to a state you consider correct.
-
- If a large portion of text appears to be missing at the beginning or
-end of the buffer, check for the word @samp{Narrow} in the mode line.
-If it appears, the text you don't see is probably still present, but
-temporarily off-limits. To make it accessible again, type @kbd{C-x n
-w}. @xref{Narrowing}.
-
-@node Memory Full
-@subsection Running out of Memory
-@cindex memory full
-@cindex out of memory
-
- If you get the error message @samp{Virtual memory exceeded}, save
-your modified buffers with @kbd{C-x s}. This method of saving them
-has the smallest need for additional memory. Emacs keeps a reserve of
-memory which it makes available when this error happens; that should
-be enough to enable @kbd{C-x s} to complete its work. When the
-reserve has been used, @samp{!MEM FULL!} appears at the beginning of
-the mode line, indicating there is no more reserve.
-
- Once you have saved your modified buffers, you can exit this Emacs
-session and start another, or you can use @kbd{M-x kill-some-buffers}
-to free space in the current Emacs job. If this frees up sufficient
-space, Emacs will refill its memory reserve, and @samp{!MEM FULL!}
-will disappear from the mode line. That means you can safely go on
-editing in the same Emacs session.
-
- Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run
-out of memory, because the buffer menu needs a fair amount of memory
-itself, and the reserve supply may not be enough.
-
-@node After a Crash
-@subsection Recovery After a Crash
-
- If Emacs or the computer crashes, you can recover the files you were
-editing at the time of the crash from their auto-save files. To do
-this, start Emacs again and type the command @kbd{M-x recover-session}.
-
- This command initially displays a buffer which lists interrupted
-session files, each with its date. You must choose which session to
-recover from. Typically the one you want is the most recent one. Move
-point to the one you choose, and type @kbd{C-c C-c}.
-
- Then @code{recover-session} considers each of the files that you
-were editing during that session; for each such file, it asks whether
-to recover that file. If you answer @kbd{y} for a file, it shows the
-dates of that file and its auto-save file, then asks once again
-whether to recover that file. For the second question, you must
-confirm with @kbd{yes}. If you do, Emacs visits the file but gets the
-text from the auto-save file.
-
- When @code{recover-session} is done, the files you've chosen to
-recover are present in Emacs buffers. You should then save them. Only
-this---saving them---updates the files themselves.
-
- As a last resort, if you had buffers with content which were not
-associated with any files, or if the autosave was not recent enough to
-have recorded important changes, you can use the
-@file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) to
-retrieve them from a core dump--provided that a core dump was saved,
-and that the Emacs executable was not stripped of its debugging
-symbols.
-
- As soon as you get the core dump, rename it to another name such as
-@file{core.emacs}, so that another crash won't overwrite it.
-
- To use this script, run @code{gdb} with the file name of your Emacs
-executable and the file name of the core dump, e.g. @samp{gdb
-/usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load the
-recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}.
-Then type the command @code{ybuffer-list} to see which buffers are
-available. For each buffer, it lists a buffer number. To save a
-buffer, use @code{ysave-buffer}; you specify the buffer number, and
-the file name to write that buffer into. You should use a file name
-which does not already exist; if the file does exist, the script does
-not make a backup of its old contents.
-
-@node Emergency Escape
-@subsection Emergency Escape
-
- On text-only terminals, the @dfn{emergency escape} feature suspends
-Emacs immediately if you type @kbd{C-g} a second time before Emacs can
-actually respond to the first one by quitting. This is so you can
-always get out of GNU Emacs no matter how badly it might be hung.
-When things are working properly, Emacs recognizes and handles the
-first @kbd{C-g} so fast that the second one won't trigger emergency
-escape. However, if some problem prevents Emacs from handling the
-first @kbd{C-g} properly, then the second one will get you back to the
-shell.
-
- When you resume Emacs after a suspension caused by emergency escape,
-it asks two questions before going back to what it had been doing:
-
-@example
-Auto-save? (y or n)
-Abort (and dump core)? (y or n)
-@end example
-
-@noindent
-Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}.
-
- Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of
-all modified buffers in which auto-saving is enabled. Saying @kbd{n}
-skips this.
-
- Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs to
-crash, dumping core. This is to enable a wizard to figure out why
-Emacs was failing to quit in the first place. Execution does not
-continue after a core dump.
-
- If you answer this question @kbd{n}, Emacs execution resumes. With
-luck, Emacs will ultimately do the requested quit. If not, each
-subsequent @kbd{C-g} invokes emergency escape again.
-
- If Emacs is not really hung, just slow, you may invoke the double
-@kbd{C-g} feature without really meaning to. Then just resume and
-answer @kbd{n} to both questions, and you will get back to the former
-state. The quit you requested will happen by and by.
-
- Emergency escape is active only for text terminals. On graphical
-displays, you can use the mouse to kill Emacs or switch to another
-program.
-
- On MS-DOS, you must type @kbd{C-@key{BREAK}} (twice) to cause
-emergency escape---but there are cases where it won't work, when
-system call hangs or when Emacs is stuck in a tight loop in C code.
-
-@node Total Frustration
-@subsection Help for Total Frustration
-@cindex Eliza
-@cindex doctor
-
- If using Emacs (or something else) becomes terribly frustrating and none
-of the techniques described above solve the problem, Emacs can still help
-you.
-
- First, if the Emacs you are using is not responding to commands, type
-@kbd{C-g C-g} to get out of it and then start a new one.
-
-@findex doctor
- Second, type @kbd{M-x doctor @key{RET}}.
-
- The Emacs psychotherapist will help you feel better. Each time you
-say something to the psychotherapist, you must end it by typing
-@key{RET} @key{RET}. This indicates you are finished typing.
-
-@node Bugs, Contributing, Lossage, Top
-@section Reporting Bugs
-
-@cindex bugs
- Sometimes you will encounter a bug in Emacs. Although we cannot
-promise we can or will fix the bug, and we might not even agree that it
-is a bug, we want to hear about problems you encounter. Often we agree
-they are bugs and want to fix them.
-
- To make it possible for us to fix a bug, you must report it. In order
-to do so effectively, you must know when and how to do it.
-
- Before reporting a bug, it is a good idea to see if it is already
-known. You can find the list of known problems in the file
-@file{etc/PROBLEMS} in the Emacs distribution; type @kbd{C-h C-e} to read
-it. Some additional user-level problems can be found in @ref{Bugs and
-problems, , Bugs and problems, efaq, GNU Emacs FAQ}. Looking up your
-problem in these two documents might provide you with a solution or a
-work-around, or give you additional information about related issues.
-
-@menu
-* Criteria: Bug Criteria. Have you really found a bug?
-* Understanding Bug Reporting:: How to report a bug effectively.
-* Checklist:: Steps to follow for a good bug report.
-* Sending Patches:: How to send a patch for GNU Emacs.
-@end menu
-
-@node Bug Criteria
-@subsection When Is There a Bug
-
- If Emacs accesses an invalid memory location (``segmentation
-fault''), or exits with an operating system error message that
-indicates a problem in the program (as opposed to something like
-``disk full''), then it is certainly a bug.
-
- If Emacs updates the display in a way that does not correspond to what is
-in the buffer, then it is certainly a bug. If a command seems to do the
-wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a
-case of incorrect display updating.
-
- Taking forever to complete a command can be a bug, but you must make
-certain that it was really Emacs's fault. Some commands simply take a
-long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) and then @kbd{C-h l}
-to see whether the input Emacs received was what you intended to type;
-if the input was such that you @emph{know} it should have been processed
-quickly, report a bug. If you don't know whether the command should
-take a long time, find out by looking in the manual or by asking for
-assistance.
-
- If a command you are familiar with causes an Emacs error message in a
-case where its usual definition ought to be reasonable, it is probably a
-bug.
-
- If a command does the wrong thing, that is a bug. But be sure you know
-for certain what it ought to have done. If you aren't familiar with the
-command, or don't know for certain how the command is supposed to work,
-then it might actually be working right. Rather than jumping to
-conclusions, show the problem to someone who knows for certain.
-
- Finally, a command's intended definition may not be the best
-possible definition for editing with. This is a very important sort
-of problem, but it is also a matter of judgment. Also, it is easy to
-come to such a conclusion out of ignorance of some of the existing
-features. It is probably best not to complain about such a problem
-until you have checked the documentation in the usual ways, feel
-confident that you understand it, and know for certain that what you
-want is not available. Ask other Emacs users, too. If you are not
-sure what the command is supposed to do after a careful reading of the
-manual, check the index and glossary for any terms that may be
-unclear.
-
- If after careful rereading of the manual you still do not understand
-what the command should do, that indicates a bug in the manual, which
-you should report. The manual's job is to make everything clear to
-people who are not Emacs experts---including you. It is just as
-important to report documentation bugs as program bugs.
-
- If the on-line documentation string of a function or variable disagrees
-with the manual, one of them must be wrong; that is a bug.
-
-@node Understanding Bug Reporting
-@subsection Understanding Bug Reporting
-
-@findex emacs-version
- When you decide that there is a bug, it is important to report it and to
-report it in a way which is useful. What is most useful is an exact
-description of what commands you type, starting with the shell command to
-run Emacs, until the problem happens.
-
- The most important principle in reporting a bug is to report
-@emph{facts}. Hypotheses and verbal descriptions are no substitute for
-the detailed raw data. Reporting the facts is straightforward, but many
-people strain to posit explanations and report them instead of the
-facts. If the explanations are based on guesses about how Emacs is
-implemented, they will be useless; meanwhile, lacking the facts, we will
-have no real information about the bug.
-
- For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh
-@key{RET}}, visiting a file which (you know) happens to be rather
-large, and Emacs displays @samp{I feel pretty today}. The best way to
-report the bug is with a sentence like the preceding one, because it
-gives all the facts.
-
- A bad way would be to assume that the problem is due to the size of
-the file and say, ``I visited a large file, and Emacs displayed @samp{I
-feel pretty today}.'' This is what we mean by ``guessing
-explanations.'' The problem is just as likely to be due to the fact
-that there is a @samp{z} in the file name. If this is so, then when we
-got your report, we would try out the problem with some ``large file,''
-probably with no @samp{z} in its name, and not see any problem. There
-is no way in the world that we could guess that we should try visiting a
-file with a @samp{z} in its name.
-
- Alternatively, the problem might be due to the fact that the file starts
-with exactly 25 spaces. For this reason, you should make sure that you
-inform us of the exact contents of any file that is needed to reproduce the
-bug. What if the problem only occurs when you have typed the @kbd{C-x C-a}
-command previously? This is why we ask you to give the exact sequence of
-characters you typed since starting the Emacs session.
-
- You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless
-you @emph{know} that it makes no difference which visiting command is used.
-Similarly, rather than saying ``if I have three characters on the line,''
-say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is
-the way you entered the text.
-
- So please don't guess any explanations when you report a bug. If you
-want to actually @emph{debug} the problem, and report explanations that
-are more than guesses, that is useful---but please include the facts as
-well.
-
-@node Checklist
-@subsection Checklist for Bug Reports
-
-@cindex reporting bugs
- The best way to send a bug report is to mail it electronically to the
-Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}, or to
-@email{emacs-pretest-bug@@gnu.org} if you are pretesting an Emacs beta
-release. (If you want to suggest a change as an improvement, use the
-same address.)
-
- If you'd like to read the bug reports, you can find them on the
-newsgroup @samp{gnu.emacs.bug}; keep in mind, however, that as a
-spectator you should not criticize anything about what you see there.
-The purpose of bug reports is to give information to the Emacs
-maintainers. Spectators are welcome only as long as they do not
-interfere with this. In particular, some bug reports contain fairly
-large amounts of data; spectators should not complain about this.
-
- Please do not post bug reports using netnews; mail is more reliable
-than netnews about reporting your correct address, which we may need
-in order to ask you for more information. If your data is more than
-500,000 bytes, please don't include it directly in the bug report;
-instead, offer to send it on request, or make it available by ftp and
-say where.
-
-@findex report-emacs-bug
- A convenient way to send a bug report for Emacs is to use the command
-@kbd{M-x report-emacs-bug}. This sets up a mail buffer (@pxref{Sending
-Mail}) and automatically inserts @emph{some} of the essential
-information. However, it cannot supply all the necessary information;
-you should still read and follow the guidelines below, so you can enter
-the other crucial information by hand before you send the message.
-
- To enable maintainers to investigate a bug, your report
-should include all these things:
-
-@itemize @bullet
-@item
-The version number of Emacs. Without this, we won't know whether there
-is any point in looking for the bug in the current version of GNU
-Emacs.
-
-You can get the version number by typing @kbd{M-x emacs-version
-@key{RET}}. If that command does not work, you probably have something
-other than GNU Emacs, so you will have to report the bug somewhere
-else.
-
-@item
-The type of machine you are using, and the operating system name and
-version number. @kbd{M-x emacs-version @key{RET}} provides this
-information too. Copy its output from the @samp{*Messages*} buffer, so
-that you get it all and get it accurately.
-
-@item
-The operands given to the @code{configure} command when Emacs was
-installed.
-
-@item
-A complete list of any modifications you have made to the Emacs source.
-(We may not have time to investigate the bug unless it happens in an
-unmodified Emacs. But if you've made modifications and you don't tell
-us, you are sending us on a wild goose chase.)
-
-Be precise about these changes. A description in English is not
-enough---send a context diff for them.
-
-Adding files of your own, or porting to another machine, is a
-modification of the source.
-
-@item
-Details of any other deviations from the standard procedure for installing
-GNU Emacs.
-
-@item
-The complete text of any files needed to reproduce the bug.
-
- If you can tell us a way to cause the problem without visiting any files,
-please do so. This makes it much easier to debug. If you do need files,
-make sure you arrange for us to see their exact contents. For example, it
-can matter whether there are spaces at the ends of lines, or a
-newline after the last line in the buffer (nothing ought to care whether
-the last line is terminated, but try telling the bugs that).
-
-@item
-The precise commands we need to type to reproduce the bug.
-
-@findex open-dribble-file
-@cindex dribble file
-@cindex logging keystrokes
-The easy way to record the input to Emacs precisely is to write a
-dribble file. To start the file, execute the Lisp expression
-
-@example
-(open-dribble-file "~/dribble")
-@end example
-
-@noindent
-using @kbd{M-:} or from the @samp{*scratch*} buffer just after
-starting Emacs. From then on, Emacs copies all your input to the
-specified dribble file until the Emacs process is killed.
-
-@item
-@findex open-termscript
-@cindex termscript file
-@cindex @env{TERM} environment variable
-For possible display bugs, the terminal type (the value of environment
-variable @env{TERM}), the complete termcap entry for the terminal from
-@file{/etc/termcap} (since that file is not identical on all machines),
-and the output that Emacs actually sent to the terminal.
-
-The way to collect the terminal output is to execute the Lisp expression
-
-@example
-(open-termscript "~/termscript")
-@end example
-
-@noindent
-using @kbd{M-:} or from the @samp{*scratch*} buffer just after
-starting Emacs. From then on, Emacs copies all terminal output to the
-specified termscript file as well, until the Emacs process is killed.
-If the problem happens when Emacs starts up, put this expression into
-your @file{.emacs} file so that the termscript file will be open when
-Emacs displays the screen for the first time.
-
-Be warned: it is often difficult, and sometimes impossible, to fix a
-terminal-dependent bug without access to a terminal of the type that
-stimulates the bug.
-
-@item
-If non-@acronym{ASCII} text or internationalization is relevant, the locale that
-was current when you started Emacs. On GNU/Linux and Unix systems, or
-if you use a Posix-style shell such as Bash, you can use this shell
-command to view the relevant values:
-
-@smallexample
-echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \
- LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG
-@end smallexample
-
-Alternatively, use the @command{locale} command, if your system has it,
-to display your locale settings.
-
-You can use the @kbd{M-!} command to execute these commands from
-Emacs, and then copy the output from the @samp{*Messages*} buffer into
-the bug report. Alternatively, @kbd{M-x getenv @key{RET} LC_ALL
-@key{RET}} will display the value of @code{LC_ALL} in the echo area, and
-you can copy its output from the @samp{*Messages*} buffer.
-
-@item
-A description of what behavior you observe that you believe is
-incorrect. For example, ``The Emacs process gets a fatal signal,'' or,
-``The resulting text is as follows, which I think is wrong.''
-
-Of course, if the bug is that Emacs gets a fatal signal, then one can't
-miss it. But if the bug is incorrect text, the maintainer might fail to
-notice what is wrong. Why leave it to chance?
-
-Even if the problem you experience is a fatal signal, you should still
-say so explicitly. Suppose something strange is going on, such as, your
-copy of the source is out of sync, or you have encountered a bug in the
-C library on your system. (This has happened!) Your copy might crash
-and the copy here might not. If you @emph{said} to expect a crash, then
-when Emacs here fails to crash, we would know that the bug was not
-happening. If you don't say to expect a crash, then we would not know
-whether the bug was happening---we would not be able to draw any
-conclusion from our observations.
-
-@item
-If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual
-fails to describe the actual behavior of Emacs, or that the text is
-confusing, copy in the text from the online manual which you think is
-at fault. If the section is small, just the section name is enough.
-
-@item
-If the manifestation of the bug is an Emacs error message, it is
-important to report the precise text of the error message, and a
-backtrace showing how the Lisp program in Emacs arrived at the error.
-
-To get the error message text accurately, copy it from the
-@samp{*Messages*} buffer into the bug report. Copy all of it, not just
-part.
-
-@findex toggle-debug-on-error
-@pindex Edebug
-To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error}
-before the error happens (that is to say, you must give that command
-and then make the bug happen). This causes the error to start the Lisp
-debugger, which shows you a backtrace. Copy the text of the
-debugger's backtrace into the bug report. @xref{Debugger,, The Lisp
-Debugger, elisp, the Emacs Lisp Reference Manual}, for information on
-debugging Emacs Lisp programs with the Edebug package.
-
-This use of the debugger is possible only if you know how to make the
-bug happen again. If you can't make it happen again, at least copy
-the whole error message.
-
-@item
-Check whether any programs you have loaded into the Lisp world,
-including your @file{.emacs} file, set any variables that may affect the
-functioning of Emacs. Also, see whether the problem happens in a
-freshly started Emacs without loading your @file{.emacs} file (start
-Emacs with the @code{-q} switch to prevent loading the init file). If
-the problem does @emph{not} occur then, you must report the precise
-contents of any programs that you must load into the Lisp world in order
-to cause the problem to occur.
-
-@item
-If the problem does depend on an init file or other Lisp programs that
-are not part of the standard Emacs system, then you should make sure it
-is not a bug in those programs by complaining to their maintainers
-first. After they verify that they are using Emacs in a way that is
-supposed to work, they should report the bug.
-
-@item
-If you wish to mention something in the GNU Emacs source, show the line
-of code with a few lines of context. Don't just give a line number.
-
-The line numbers in the development sources don't match those in your
-sources. It would take extra work for the maintainers to determine what
-code is in your version at a given line number, and we could not be
-certain.
-
-@item
-Additional information from a C debugger such as GDB might enable
-someone to find a problem on a machine which he does not have available.
-If you don't know how to use GDB, please read the GDB manual---it is not
-very long, and using GDB is easy. You can find the GDB distribution,
-including the GDB manual in online form, in most of the same places you
-can find the Emacs distribution. To run Emacs under GDB, you should
-switch to the @file{src} subdirectory in which Emacs was compiled, then
-do @samp{gdb emacs}. It is important for the directory @file{src} to be
-current so that GDB will read the @file{.gdbinit} file in this
-directory.
-
-However, you need to think when you collect the additional information
-if you want it to show what causes the bug.
-
-@cindex backtrace for bug reports
-For example, many people send just a backtrace, but that is not very
-useful by itself. A simple backtrace with arguments often conveys
-little about what is happening inside GNU Emacs, because most of the
-arguments listed in the backtrace are pointers to Lisp objects. The
-numeric values of these pointers have no significance whatever; all that
-matters is the contents of the objects they point to (and most of the
-contents are themselves pointers).
-
-@findex debug_print
-To provide useful information, you need to show the values of Lisp
-objects in Lisp notation. Do this for each variable which is a Lisp
-object, in several stack frames near the bottom of the stack. Look at
-the source to see which variables are Lisp objects, because the debugger
-thinks of them as integers.
-
-To show a variable's value in Lisp syntax, first print its value, then
-use the user-defined GDB command @code{pr} to print the Lisp object in
-Lisp syntax. (If you must use another debugger, call the function
-@code{debug_print} with the object as an argument.) The @code{pr}
-command is defined by the file @file{.gdbinit}, and it works only if you
-are debugging a running process (not with a core dump).
-
-To make Lisp errors stop Emacs and return to GDB, put a breakpoint at
-@code{Fsignal}.
-
-For a short listing of Lisp functions running, type the GDB
-command @code{xbacktrace}.
-
-The file @file{.gdbinit} defines several other commands that are useful
-for examining the data types and contents of Lisp objects. Their names
-begin with @samp{x}. These commands work at a lower level than
-@code{pr}, and are less convenient, but they may work even when
-@code{pr} does not, such as when debugging a core dump or when Emacs has
-had a fatal signal.
-
-@cindex debugging Emacs, tricks and techniques
-More detailed advice and other useful techniques for debugging Emacs
-are available in the file @file{etc/DEBUG} in the Emacs distribution.
-That file also includes instructions for investigating problems
-whereby Emacs stops responding (many people assume that Emacs is
-``hung,'' whereas in fact it might be in an infinite loop).
-
-To find the file @file{etc/DEBUG} in your Emacs installation, use the
-directory name stored in the variable @code{data-directory}.
-@end itemize
-
-Here are some things that are not necessary in a bug report:
-
-@itemize @bullet
-@item
-A description of the envelope of the bug---this is not necessary for a
-reproducible bug.
-
-Often people who encounter a bug spend a lot of time investigating
-which changes to the input file will make the bug go away and which
-changes will not affect it.
-
-This is often time-consuming and not very useful, because the way we
-will find the bug is by running a single example under the debugger
-with breakpoints, not by pure deduction from a series of examples.
-You might as well save time by not searching for additional examples.
-It is better to send the bug report right away, go back to editing,
-and find another bug to report.
-
-Of course, if you can find a simpler example to report @emph{instead} of
-the original one, that is a convenience. Errors in the output will be
-easier to spot, running under the debugger will take less time, etc.
-
-However, simplification is not vital; if you can't do this or don't have
-time to try, please report the bug with your original test case.
-
-@item
-A core dump file.
-
-Debugging the core dump might be useful, but it can only be done on
-your machine, with your Emacs executable. Therefore, sending the core
-dump file to the Emacs maintainers won't be useful. Above all, don't
-include the core file in an email bug report! Such a large message
-can be extremely inconvenient.
-
-@item
-A system-call trace of Emacs execution.
-
-System-call traces are very useful for certain special kinds of
-debugging, but in most cases they give little useful information. It is
-therefore strange that many people seem to think that @emph{the} way to
-report information about a crash is to send a system-call trace. Perhaps
-this is a habit formed from experience debugging programs that don't
-have source code or debugging symbols.
-
-In most programs, a backtrace is normally far, far more informative than
-a system-call trace. Even in Emacs, a simple backtrace is generally
-more informative, though to give full information you should supplement
-the backtrace by displaying variable values and printing them as Lisp
-objects with @code{pr} (see above).
-
-@item
-A patch for the bug.
-
-A patch for the bug is useful if it is a good one. But don't omit the
-other information that a bug report needs, such as the test case, on the
-assumption that a patch is sufficient. We might see problems with your
-patch and decide to fix the problem another way, or we might not
-understand it at all. And if we can't understand what bug you are
-trying to fix, or why your patch should be an improvement, we mustn't
-install it.
-
-@ifnottex
-@xref{Sending Patches}, for guidelines on how to make it easy for us to
-understand and install your patches.
-@end ifnottex
-
-@item
-A guess about what the bug is or what it depends on.
-
-Such guesses are usually wrong. Even experts can't guess right about
-such things without first using the debugger to find the facts.
-@end itemize
-
-@node Sending Patches
-@subsection Sending Patches for GNU Emacs
-
-@cindex sending patches for GNU Emacs
-@cindex patches, sending
- If you would like to write bug fixes or improvements for GNU Emacs,
-that is very helpful. When you send your changes, please follow these
-guidelines to make it easy for the maintainers to use them. If you
-don't follow these guidelines, your information might still be useful,
-but using it will take extra work. Maintaining GNU Emacs is a lot of
-work in the best of circumstances, and we can't keep up unless you do
-your best to help.
-
-@itemize @bullet
-@item
-Send an explanation with your changes of what problem they fix or what
-improvement they bring about. For a bug fix, just include a copy of the
-bug report, and explain why the change fixes the bug.
-
-(Referring to a bug report is not as good as including it, because then
-we will have to look it up, and we have probably already deleted it if
-we've already fixed the bug.)
-
-@item
-Always include a proper bug report for the problem you think you have
-fixed. We need to convince ourselves that the change is right before
-installing it. Even if it is correct, we might have trouble
-understanding it if we don't have a way to reproduce the problem.
-
-@item
-Include all the comments that are appropriate to help people reading the
-source in the future understand why this change was needed.
-
-@item
-Don't mix together changes made for different reasons.
-Send them @emph{individually}.
-
-If you make two changes for separate reasons, then we might not want to
-install them both. We might want to install just one. If you send them
-all jumbled together in a single set of diffs, we have to do extra work
-to disentangle them---to figure out which parts of the change serve
-which purpose. If we don't have time for this, we might have to ignore
-your changes entirely.
-
-If you send each change as soon as you have written it, with its own
-explanation, then two changes never get tangled up, and we can consider
-each one properly without any extra work to disentangle them.
-
-@item
-Send each change as soon as that change is finished. Sometimes people
-think they are helping us by accumulating many changes to send them all
-together. As explained above, this is absolutely the worst thing you
-could do.
-
-Since you should send each change separately, you might as well send it
-right away. That gives us the option of installing it immediately if it
-is important.
-
-@item
-Use @samp{diff -c} to make your diffs. Diffs without context are hard
-to install reliably. More than that, they are hard to study; we must
-always study a patch to decide whether we want to install it. Unidiff
-format is better than contextless diffs, but not as easy to read as
-@samp{-c} format.
-
-If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when
-making diffs of C code. This shows the name of the function that each
-change occurs in.
-
-@item
-Avoid any ambiguity as to which is the old version and which is the new.
-Please make the old version the first argument to diff, and the new
-version the second argument. And please give one version or the other a
-name that indicates whether it is the old version or your new changed
-one.
-
-@item
-Write the change log entries for your changes. This is both to save us
-the extra work of writing them, and to help explain your changes so we
-can understand them.
-
-The purpose of the change log is to show people where to find what was
-changed. So you need to be specific about what functions you changed;
-in large functions, it's often helpful to indicate where within the
-function the change was.
-
-On the other hand, once you have shown people where to find the change,
-you need not explain its purpose in the change log. Thus, if you add a
-new function, all you need to say about it is that it is new. If you
-feel that the purpose needs explaining, it probably does---but put the
-explanation in comments in the code. It will be more useful there.
-
-Please read the @file{ChangeLog} files in the @file{src} and
-@file{lisp} directories to see what sorts of information to put in,
-and to learn the style that we use. @xref{Change Log}.
-
-@item
-When you write the fix, keep in mind that we can't install a change that
-would break other systems. Please think about what effect your change
-will have if compiled on another type of system.
-
-Sometimes people send fixes that @emph{might} be an improvement in
-general---but it is hard to be sure of this. It's hard to install
-such changes because we have to study them very carefully. Of course,
-a good explanation of the reasoning by which you concluded the change
-was correct can help convince us.
-
-The safest changes are changes to the configuration files for a
-particular machine. These are safe because they can't create new bugs
-on other machines.
-
-Please help us keep up with the workload by designing the patch in a
-form that is clearly safe to install.
-@end itemize
-
-@node Contributing, Service, Bugs, Top
-@section Contributing to Emacs Development
-
-If you would like to help pretest Emacs releases to assure they work
-well, or if you would like to work on improving Emacs, please contact
-the maintainers at @email{emacs-devel@@gnu.org}. A pretester
-should be prepared to investigate bugs as well as report them. If you'd
-like to work on improving Emacs, please ask for suggested projects or
-suggest your own ideas.
-
-If you have already written an improvement, please tell us about it. If
-you have not yet started work, it is useful to contact
-@email{emacs-devel@@gnu.org} before you start; it might be
-possible to suggest ways to make your extension fit in better with the
-rest of Emacs.
-
-The development version of Emacs can be downloaded from the CVS
-repository where it is actively maintained by a group of developers.
-See the Emacs project page
-@url{http://savannah.gnu.org/projects/emacs/} for details.
-
-@node Service, Copying, Contributing, Top
-@section How To Get Help with GNU Emacs
-
-If you need help installing, using or changing GNU Emacs, there are two
-ways to find it:
-
-@itemize @bullet
-@item
-Send a message to the mailing list
-@email{help-gnu-emacs@@gnu.org}, or post your request on
-newsgroup @code{gnu.emacs.help}. (This mailing list and newsgroup
-interconnect, so it does not matter which one you use.)
-
-@item
-Look in the service directory for someone who might help you for a fee.
-The service directory is found in the file named @file{etc/SERVICE} in the
-Emacs distribution.
-@end itemize
-
-@ifnottex
-@lowersections
-@end ifnottex
-
-@ignore
- arch-tag: c9cba76d-b2cb-4e0c-ae3f-19d5ef35817c
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@c
-@c This file is included in emacs-xtra.texi when producing the printed
-@c version.
-@iftex
-@node Advanced VC Usage
-@section Advanced VC Usage
-
- Commonly used features of Emacs' version control (VC) support are
-described in the main Emacs manual (@pxref{Version Control,,,emacs,
-the Emacs Manual}). This chapter describes more advanced VC usage.
-
-@menu
-* VC Dired Mode:: Listing files managed by version control.
-* VC Dired Commands:: Commands to use in a VC Dired buffer.
-* Remote Repositories:: Efficient access to remote CVS servers.
-* Snapshots:: Sets of file versions treated as a unit.
-* Miscellaneous VC:: Various other commands and features of VC.
-* Customizing VC:: Variables that change VC's behavior.
-@end menu
-@end iftex
-
-@iftex
-@include vc1-xtra.texi
-@include vc2-xtra.texi
-@end iftex
-
-@ignore
- arch-tag: 11a18d0e-1baf-49da-8e38-f61195ae4dc3
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@c
-@c This file is included either in vc-xtra.texi (when producing the
-@c printed version) or in the main Emacs manual (for the on-line version).
-@node VC Dired Mode
-@subsection Dired under VC
-
-@cindex PCL-CVS
-@pindex cvs
-@cindex CVS Dired Mode
- The VC Dired Mode described here works with all the version control
-systems that VC supports. Another more powerful facility, designed
-specifically for CVS, is called PCL-CVS. @xref{Top, , About PCL-CVS,
-pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
-
-@kindex C-x v d
-@findex vc-directory
- When you are working on a large program, it is often useful to find
-out which files have changed within an entire directory tree, or to view
-the status of all files under version control at once, and to perform
-version control operations on collections of files. You can use the
-command @kbd{C-x v d} (@code{vc-directory}) to make a directory listing
-that includes only files relevant for version control.
-
-@vindex vc-dired-terse-display
- @kbd{C-x v d} creates a buffer which uses VC Dired Mode. This looks
-much like an ordinary Dired buffer
-@iftex
-(@pxref{Dired,,,emacs, the Emacs Manual});
-@end iftex
-@ifnottex
-(@pxref{Dired});
-@end ifnottex
-however, normally it shows only the noteworthy files (those locked or
-not up-to-date). This is called @dfn{terse display}. If you set the
-variable @code{vc-dired-terse-display} to @code{nil}, then VC Dired
-shows all relevant files---those managed under version control, plus
-all subdirectories (@dfn{full display}). The command @kbd{v t} in a
-VC Dired buffer toggles between terse display and full display
-(@pxref{VC Dired Commands}).
-
-@vindex vc-dired-recurse
- By default, VC Dired produces a recursive listing of noteworthy or
-relevant files at or below the given directory. You can change this by
-setting the variable @code{vc-dired-recurse} to @code{nil}; then VC
-Dired shows only the files in the given directory.
-
- The line for an individual file shows the version control state in the
-place of the hard link count, owner, group, and size of the file. If
-the file is unmodified, in sync with the master file, the version
-control state shown is blank. Otherwise it consists of text in
-parentheses. Under RCS and SCCS, the name of the user locking the file
-is shown; under CVS, an abbreviated version of the @samp{cvs status}
-output is used. Here is an example using RCS:
-
-@smallexample
-@group
- /home/jim/project:
-
- -rw-r--r-- (jim) Apr 2 23:39 file1
- -r--r--r-- Apr 5 20:21 file2
-@end group
-@end smallexample
-
-@noindent
-The files @samp{file1} and @samp{file2} are under version control,
-@samp{file1} is locked by user jim, and @samp{file2} is unlocked.
-
- Here is an example using CVS:
-
-@smallexample
-@group
- /home/joe/develop:
-
- -rw-r--r-- (modified) Aug 2 1997 file1.c
- -rw-r--r-- Apr 4 20:09 file2.c
- -rw-r--r-- (merge) Sep 13 1996 file3.c
-@end group
-@end smallexample
-
- Here @samp{file1.c} is modified with respect to the repository, and
-@samp{file2.c} is not. @samp{file3.c} is modified, but other changes
-have also been checked in to the repository---you need to merge them
-with the work file before you can check it in.
-
-@vindex vc-stay-local
-@vindex vc-cvs-stay-local
- In the above, if the repository were on a remote machine, VC would
-only contact it when the variable @code{vc-stay-local} (or
-@code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}). This is
-because access to the repository may be slow, or you may be working
-offline and not have access to the repository at all. As a
-consequence, VC would not be able to tell you that @samp{file3.c} is
-in the ``merge'' state; you would learn that only when you try to
-check-in your modified copy of the file, or use a command such as
-@kbd{C-x v m}.
-
- In practice, this is not a problem because CVS handles this case
-consistently whenever it arises. In VC, you'll simply get prompted to
-merge the remote changes into your work file first. The benefits of
-less network communication usually outweigh the disadvantage of not
-seeing remote changes immediately.
-
-@vindex vc-directory-exclusion-list
- When VC Dired displays subdirectories (in the ``full'' display mode),
-it omits some that should never contain any files under version control.
-By default, this includes Version Control subdirectories such as
-@samp{RCS} and @samp{CVS}; you can customize this by setting the
-variable @code{vc-directory-exclusion-list}.
-
- You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in
-ordinary Dired, that allows you to specify additional switches for the
-@samp{ls} command.
-
-@node VC Dired Commands
-@subsection VC Dired Commands
-
- All the usual Dired commands work normally in VC Dired mode, except
-for @kbd{v}, which is redefined as the version control prefix. You can
-invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by
-typing @kbd{v =}, or @kbd{v l}, and so on. Most of these commands apply
-to the file name on the current line.
-
- The command @kbd{v v} (@code{vc-next-action}) operates on all the
-marked files, so that you can lock or check in several files at once.
-If it operates on more than one file, it handles each file according to
-its current state; thus, it might lock one file, but check in another
-file. This could be confusing; it is up to you to avoid confusing
-behavior by marking a set of files that are in a similar state. If no
-files are marked, @kbd{v v} operates on the file in the current line.
-
- If any files call for check-in, @kbd{v v} reads a single log entry,
-then uses it for all the files being checked in. This is convenient for
-registering or checking in several files at once, as part of the same
-change.
-
-@findex vc-dired-toggle-terse-mode
-@findex vc-dired-mark-locked
- You can toggle between terse display (only locked files, or files not
-up-to-date) and full display at any time by typing @kbd{v t}
-(@code{vc-dired-toggle-terse-mode}). There is also a special command
-@kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently
-locked (or, with CVS, all files not up-to-date). Thus, typing @kbd{* l
-t k} is another way to delete from the buffer all files except those
-currently locked.
-
-@ignore
- arch-tag: 8e8c2a01-ad41-4e61-a89a-60131ad67263
-@end ignore
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@c
-@c This file is included either in vc-xtra.texi (when producing the
-@c printed version) or in the main Emacs manual (for the on-line version).
-@node Remote Repositories
-@subsection Remote Repositories
-@cindex remote repositories (CVS)
-
- A common way of using CVS is to set up a central CVS repository on
-some Internet host, then have each developer check out a personal
-working copy of the files on his local machine. Committing changes to
-the repository, and picking up changes from other users into one's own
-working area, then works by direct interactions with the CVS server.
-
- One difficulty is that access to the CVS server is often slow, and
-that developers might need to work off-line as well. VC is designed
-to reduce the amount of network interaction necessary.
-
-@menu
-* Version Backups:: Keeping local copies of repository versions.
-* Local Version Control:: Using another version system for local editing.
-@end menu
-
-@node Version Backups
-@subsubsection Version Backups
-@cindex version backups
-
-@cindex automatic version backups
- When VC sees that the CVS repository for a file is on a remote
-machine, it automatically makes local backups of unmodified versions
-of the file---@dfn{automatic version backups}. This means that you
-can compare the file to the repository version (@kbd{C-x v =}), or
-revert to that version (@kbd{C-x v u}), without any network
-interactions.
-
- The local copy of the unmodified file is called a @dfn{version
-backup} to indicate that it corresponds exactly to a version that is
-stored in the repository. Note that version backups are not the same
-as ordinary Emacs backup files
-@iftex
-(@pxref{Backup,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Backup}).
-@end ifnottex
-But they follow a similar naming convention.
-
- For a file that comes from a remote CVS repository, VC makes a
-version backup whenever you save the first changes to the file, and
-removes it after you have committed your modified version to the
-repository. You can disable the making of automatic version backups by
-setting @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS Options}).
-
-@cindex manual version backups
- The name of the automatic version backup for version @var{version}
-of file @var{file} is @code{@var{file}.~@var{version}.~}. This is
-almost the same as the name used by @kbd{C-x v ~}
-@iftex
-(@pxref{Old Versions,,,emacs, the Emacs Manual}),
-@end iftex
-@ifnottex
-(@pxref{Old Versions}),
-@end ifnottex
-the only difference being the additional dot (@samp{.}) after the
-version number. This similarity is intentional, because both kinds of
-files store the same kind of information. The file made by @kbd{C-x v
-~} acts as a @dfn{manual version backup}.
-
- All the VC commands that operate on old versions of a file can use
-both kinds of version backups. For instance, @kbd{C-x v ~} uses
-either an automatic or a manual version backup, if possible, to get
-the contents of the version you request. Likewise, @kbd{C-x v =} and
-@kbd{C-x v u} use either an automatic or a manual version backup, if
-one of them exists, to get the contents of a version to compare or
-revert to. If you changed a file outside of Emacs, so that no
-automatic version backup was created for the previous text, you can
-create a manual backup of that version using @kbd{C-x v ~}, and thus
-obtain the benefit of the local copy for Emacs commands.
-
- The only difference in Emacs's handling of manual and automatic
-version backups, once they exist, is that Emacs deletes automatic
-version backups when you commit to the repository. By contrast,
-manual version backups remain until you delete them.
-
-@node Local Version Control
-@subsubsection Local Version Control
-@cindex local version control
-@cindex local back end (version control)
-
-When you make many changes to a file that comes from a remote
-repository, it can be convenient to have version control on your local
-machine as well. You can then record intermediate versions, revert to
-a previous state, etc., before you actually commit your changes to the
-remote server.
-
-VC lets you do this by putting a file under a second, local version
-control system, so that the file is effectively registered in two
-systems at the same time. For the description here, we will assume
-that the remote system is CVS, and you use RCS locally, although the
-mechanism works with any combination of version control systems
-(@dfn{back ends}).
-
-To make it work with other back ends, you must make sure that the
-``more local'' back end comes before the ``more remote'' back end in
-the setting of @code{vc-handled-backends} (@pxref{Customizing VC}). By
-default, this variable is set up so that you can use remote CVS and
-local RCS as described here.
-
-To start using local RCS for a file that comes from a remote CVS
-server, you must @emph{register the file in RCS}, by typing @kbd{C-u
-C-x v v rcs @key{RET}}. (In other words, use @code{vc-next-action} with a
-prefix argument, and specify RCS as the back end.)
-
-You can do this at any time; it does not matter whether you have
-already modified the file with respect to the version in the CVS
-repository. If possible, VC tries to make the RCS master start with
-the unmodified repository version, then checks in any local changes
-as a new version. This works if you have not made any changes yet, or
-if the unmodified repository version exists locally as a version
-backup (@pxref{Version Backups}). If the unmodified version is not
-available locally, the RCS master starts with the modified version;
-the only drawback to this is that you cannot compare your changes
-locally to what is stored in the repository.
-
-The version number of the RCS master is derived from the current CVS
-version, starting a branch from it. For example, if the current CVS
-version is 1.23, the local RCS branch will be 1.23.1. Version 1.23 in
-the RCS master will be identical to version 1.23 under CVS; your first
-changes are checked in as 1.23.1.1. (If the unmodified file is not
-available locally, VC will check in the modified file twice, both as
-1.23 and 1.23.1.1, to make the revision numbers consistent.)
-
-If you do not use locking under CVS (the default), locking is also
-disabled for RCS, so that editing under RCS works exactly as under
-CVS.
-
-When you are done with local editing, you can commit the final version
-back to the CVS repository by typing @kbd{C-u C-x v v cvs @key{RET}}.
-This initializes the log entry buffer
-@iftex
-(@pxref{Log Buffer,,,emacs, the Emacs Manual})
-@end iftex
-@ifnottex
-(@pxref{Log Buffer})
-@end ifnottex
-to contain all the log entries you have recorded in the RCS master;
-you can edit them as you wish, and then commit in CVS by typing
-@kbd{C-c C-c}. If the commit is successful, VC removes the RCS
-master, so that the file is once again registered under CVS only.
-(The RCS master is not actually deleted, just renamed by appending
-@samp{~} to the name, so that you can refer to it later if you wish.)
-
-While using local RCS, you can pick up recent changes from the CVS
-repository into your local file, or commit some of your changes back
-to CVS, without terminating local RCS version control. To do this,
-switch to the CVS back end temporarily, with the @kbd{C-x v b} command:
-
-@table @kbd
-@item C-x v b
-Switch to another back end that the current file is registered
-under (@code{vc-switch-backend}).
-
-@item C-u C-x v b @var{backend} @key{RET}
-Switch to @var{backend} for the current file.
-@end table
-
-@kindex C-x v b
-@findex vc-switch-backend
-@kbd{C-x v b} does not change the buffer contents, or any files; it
-only changes VC's perspective on how to handle the file. Any
-subsequent VC commands for that file will operate on the back end that
-is currently selected.
-
-If the current file is registered in more than one back end, typing
-@kbd{C-x v b} ``cycles'' through all of these back ends. With a
-prefix argument, it asks for the back end to use in the minibuffer.
-
-Thus, if you are using local RCS, and you want to pick up some recent
-changes in the file from remote CVS, first visit the file, then type
-@kbd{C-x v b} to switch to CVS, and finally use @kbd{C-x v m
-@key{RET}} to merge the news
-@iftex
-(@pxref{Merging,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Merging}).
-@end ifnottex
-You can then switch back to RCS by typing @kbd{C-x v b} again, and
-continue to edit locally.
-
-But if you do this, the revision numbers in the RCS master no longer
-correspond to those of CVS. Technically, this is not a problem, but
-it can become difficult to keep track of what is in the CVS repository
-and what is not. So we suggest that you return from time to time to
-CVS-only operation, by committing your local changes back to the
-repository using @kbd{C-u C-x v v cvs @key{RET}}.
-
-@node Snapshots
-@subsection Snapshots
-@cindex snapshots and version control
-
- A @dfn{snapshot} is a named set of file versions (one for each
-registered file) that you can treat as a unit. One important kind of
-snapshot is a @dfn{release}, a (theoretically) stable version of the
-system that is ready for distribution to users.
-
-@menu
-* Making Snapshots:: The snapshot facilities.
-* Snapshot Caveats:: Things to be careful of when using snapshots.
-@end menu
-
-@node Making Snapshots
-@subsubsection Making and Using Snapshots
-
- There are two basic commands for snapshots; one makes a
-snapshot with a given name, the other retrieves a named snapshot.
-
-@table @code
-@kindex C-x v s
-@findex vc-create-snapshot
-@item C-x v s @var{name} @key{RET}
-Define the last saved versions of every registered file in or under the
-current directory as a snapshot named @var{name}
-(@code{vc-create-snapshot}).
-
-@kindex C-x v r
-@findex vc-retrieve-snapshot
-@item C-x v r @var{name} @key{RET}
-For all registered files at or below the current directory level, select
-whatever versions correspond to the snapshot @var{name}
-(@code{vc-retrieve-snapshot}).
-
-This command reports an error if any files are locked at or below the
-current directory, without changing anything; this is to avoid
-overwriting work in progress.
-@end table
-
- A snapshot uses a very small amount of resources---just enough to record
-the list of file names and which version belongs to the snapshot. Thus,
-you need not hesitate to create snapshots whenever they are useful.
-
- You can give a snapshot name as an argument to @kbd{C-x v =} or
-@kbd{C-x v ~}
-@iftex
-(@pxref{Old Versions,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Old Versions}).
-@end ifnottex
-Thus, you can use it to compare a snapshot against the current files,
-or two snapshots against each other, or a snapshot against a named
-version.
-
-@node Snapshot Caveats
-@subsubsection Snapshot Caveats
-
-@cindex named configurations (RCS)
- VC's snapshot facilities are modeled on RCS's named-configuration
-support. They use RCS's native facilities for this, so
-snapshots made using RCS through VC are visible even when you bypass VC.
-
- With CVS, Meta-CVS, and Subversion, VC also uses the native
-mechanism provided by that back end to make snapshots and retrieve them
-(@dfn{tags} for CVS and Meta-CVS, @dfn{copies} for Subversion).
-
-@c worded verbosely to avoid overfull hbox.
- For SCCS, VC implements snapshots itself. The files it uses contain
-name/file/version-number triples. These snapshots are visible only
-through VC.
-
- There is no support for VC snapshots using GNU Arch yet.
-
- A snapshot is a set of checked-in versions. So make sure that all the
-files are checked in and not locked when you make a snapshot.
-
- File renaming and deletion can create some difficulties with snapshots.
-This is not a VC-specific problem, but a general design issue in version
-control systems that no one has solved very well yet.
-
- If you rename a registered file, you need to rename its master along
-with it (the command @code{vc-rename-file} does this automatically). If
-you are using SCCS, you must also update the records of the snapshot, to
-mention the file by its new name (@code{vc-rename-file} does this,
-too). An old snapshot that refers to a master file that no longer
-exists under the recorded name is invalid; VC can no longer retrieve
-it. It would be beyond the scope of this manual to explain enough about
-RCS and SCCS to explain how to update the snapshots by hand.
-
- Using @code{vc-rename-file} makes the snapshot remain valid for
-retrieval, but it does not solve all problems. For example, some of the
-files in your program probably refer to others by name. At the very
-least, the makefile probably mentions the file that you renamed. If you
-retrieve an old snapshot, the renamed file is retrieved under its new
-name, which is not the name that the makefile expects. So the program
-won't really work as retrieved.
-
-@node Miscellaneous VC
-@subsection Miscellaneous Commands and Features of VC
-
- This section explains the less-frequently-used features of VC.
-
-@menu
-* Change Logs and VC:: Generating a change log file from log entries.
-* Renaming and VC:: A command to rename both the source and master
- file correctly.
-* Version Headers:: Inserting version control headers into working files.
-@end menu
-
-@node Change Logs and VC
-@subsubsection Change Logs and VC
-
- If you use RCS or CVS for a program and also maintain a change log
-file for it
-@iftex
-(@pxref{Change Log,,,emacs, the Emacs Manual}),
-@end iftex
-@ifnottex
-(@pxref{Change Log}),
-@end ifnottex
-you can generate change log entries automatically from the version
-control log entries:
-
-@table @kbd
-@item C-x v a
-@kindex C-x v a
-@findex vc-update-change-log
-Visit the current directory's change log file and, for registered files
-in that directory, create new entries for versions checked in since the
-most recent entry in the change log file.
-(@code{vc-update-change-log}).
-
-This command works with RCS or CVS only, not with any of the other
-back ends.
-
-@item C-u C-x v a
-As above, but only find entries for the current buffer's file.
-
-@item M-1 C-x v a
-As above, but find entries for all the currently visited files that are
-maintained with version control. This works only with RCS, and it puts
-all entries in the log for the default directory, which may not be
-appropriate.
-@end table
-
- For example, suppose the first line of @file{ChangeLog} is dated
-1999-04-10, and that the only check-in since then was by Nathaniel
-Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log
-messages that start with `#'.}. Then @kbd{C-x v a} visits
-@file{ChangeLog} and inserts text like this:
-
-@iftex
-@medbreak
-@end iftex
-@smallexample
-@group
-1999-05-22 Nathaniel Bowditch <nat@@apn.org>
-
- * rcs2log: Ignore log messages that start with `#'.
-@end group
-@end smallexample
-@iftex
-@medbreak
-@end iftex
-
-@noindent
-You can then edit the new change log entry further as you wish.
-
- Some of the new change log entries may duplicate what's already in
-ChangeLog. You will have to remove these duplicates by hand.
-
- Normally, the log entry for file @file{foo} is displayed as @samp{*
-foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted
-if the text of the log entry starts with @w{@samp{(@var{functionname}):
-}}. For example, if the log entry for @file{vc.el} is
-@samp{(vc-do-command): Check call-process status.}, then the text in
-@file{ChangeLog} looks like this:
-
-@iftex
-@medbreak
-@end iftex
-@smallexample
-@group
-1999-05-06 Nathaniel Bowditch <nat@@apn.org>
-
- * vc.el (vc-do-command): Check call-process status.
-@end group
-@end smallexample
-@iftex
-@medbreak
-@end iftex
-
- When @kbd{C-x v a} adds several change log entries at once, it groups
-related log entries together if they all are checked in by the same
-author at nearly the same time. If the log entries for several such
-files all have the same text, it coalesces them into a single entry.
-For example, suppose the most recent check-ins have the following log
-entries:
-
-@flushleft
-@bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.}
-@bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.}
-@bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.}
-@end flushleft
-
-@noindent
-They appear like this in @file{ChangeLog}:
-
-@iftex
-@medbreak
-@end iftex
-@smallexample
-@group
-1999-04-01 Nathaniel Bowditch <nat@@apn.org>
-
- * vc.texinfo: Fix expansion typos.
-
- * vc.el, vc-hooks.el: Don't call expand-file-name.
-@end group
-@end smallexample
-@iftex
-@medbreak
-@end iftex
-
- Normally, @kbd{C-x v a} separates log entries by a blank line, but you
-can mark several related log entries to be clumped together (without an
-intervening blank line) by starting the text of each related log entry
-with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label
-itself is not copied to @file{ChangeLog}. For example, suppose the log
-entries are:
-
-@flushleft
-@bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.}
-@bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.}
-@bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.}
-@end flushleft
-
-@noindent
-Then the text in @file{ChangeLog} looks like this:
-
-@iftex
-@medbreak
-@end iftex
-@smallexample
-@group
-1999-04-01 Nathaniel Bowditch <nat@@apn.org>
-
- * vc.texinfo: Fix expansion typos.
- * vc.el, vc-hooks.el: Don't call expand-file-name.
-@end group
-@end smallexample
-@iftex
-@medbreak
-@end iftex
-
- A log entry whose text begins with @samp{#} is not copied to
-@file{ChangeLog}. For example, if you merely fix some misspellings in
-comments, you can log the change with an entry beginning with @samp{#}
-to avoid putting such trivia into @file{ChangeLog}.
-
-@node Renaming and VC
-@subsubsection Renaming VC Work Files and Master Files
-
-@findex vc-rename-file
- When you rename a registered file, you must also rename its master
-file correspondingly to get proper results. Use @code{vc-rename-file}
-to rename the source file as you specify, and rename its master file
-accordingly. It also updates any snapshots (@pxref{Snapshots}) that
-mention the file, so that they use the new name; despite this, the
-snapshot thus modified may not completely work (@pxref{Snapshot
-Caveats}).
-
- Some back ends do not provide an explicit rename operation to their
-repositories. After issuing @code{vc-rename-file}, use @kbd{C-x v v}
-on the original and renamed buffers and provide the necessary edit
-log.
-
- You cannot use @code{vc-rename-file} on a file that is locked by
-someone else.
-
-@node Version Headers
-@subsubsection Inserting Version Control Headers
-
- Sometimes it is convenient to put version identification strings
-directly into working files. Certain special strings called
-@dfn{version headers} are replaced in each successive version by the
-number of that version, the name of the user who created it, and other
-relevant information. All of the back ends that VC supports have such
-a mechanism, except GNU Arch.
-
- VC does not normally use the information contained in these headers.
-The exception is RCS---with RCS, version headers are sometimes more
-reliable than the master file to determine which version of the file
-you are editing. Note that in a multi-branch environment, version
-headers are necessary to make VC behave correctly
-@iftex
-(@pxref{Multi-User Branching,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-(@pxref{Multi-User Branching}).
-@end ifnottex
-
- Searching for RCS version headers is controlled by the variable
-@code{vc-consult-headers}. If it is non-@code{nil} (the default),
-Emacs searches for headers to determine the version number you are
-editing. Setting it to @code{nil} disables this feature.
-
- Note that although CVS uses the same kind of version headers as RCS
-does, VC never searches for these headers if you are using CVS,
-regardless of the above setting.
-
-@kindex C-x v h
-@findex vc-insert-headers
- You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to
-insert a suitable header string.
-
-@table @kbd
-@item C-x v h
-Insert headers in a file for use with your version-control system.
-@end table
-
-@vindex vc-@var{backend}-header
- The default header string is @samp{@w{$}Id$} for RCS and
-@samp{@w{%}W%} for SCCS. You can specify other headers to insert by
-setting the variables @code{vc-@var{backend}-header} where
-@var{backend} is @code{rcs} or @code{sccs}.
-
- Instead of a single string, you can specify a list of strings; then
-each string in the list is inserted as a separate header on a line of
-its own.
-
- It may be necessary to use apparently-superfluous backslashes when
-writing the strings that you put in this variable. For instance, you
-might write @code{"$Id\$"} rather than @code{"$Id@w{$}"}. The extra
-backslash prevents the string constant from being interpreted as a
-header, if the Emacs Lisp file containing it is maintained with
-version control.
-
-@vindex vc-comment-alist
- Each header is inserted surrounded by tabs, inside comment delimiters,
-on a new line at point. Normally the ordinary comment
-start and comment end strings of the current mode are used, but for
-certain modes, there are special comment delimiters for this purpose;
-the variable @code{vc-comment-alist} specifies them. Each element of
-this list has the form @code{(@var{mode} @var{starter} @var{ender})}.
-
-@vindex vc-static-header-alist
- The variable @code{vc-static-header-alist} specifies further strings
-to add based on the name of the buffer. Its value should be a list of
-elements of the form @code{(@var{regexp} . @var{format})}. Whenever
-@var{regexp} matches the buffer name, @var{format} is inserted as part
-of the header. A header line is inserted for each element that matches
-the buffer name, and for each string specified by
-@code{vc-@var{backend}-header}. The header line is made by processing the
-string from @code{vc-@var{backend}-header} with the format taken from the
-element. The default value for @code{vc-static-header-alist} is as follows:
-
-@example
-@group
-(("\\.c$" .
- "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
-#endif /* lint */\n"))
-@end group
-@end example
-
-@noindent
-It specifies insertion of text of this form:
-
-@example
-@group
-
-#ifndef lint
-static char vcid[] = "@var{string}";
-#endif /* lint */
-@end group
-@end example
-
-@noindent
-Note that the text above starts with a blank line.
-
- If you use more than one version header in a file, put them close
-together in the file. The mechanism in @code{revert-buffer} that
-preserves markers may not handle markers positioned between two version
-headers.
-
-@node Customizing VC
-@subsection Customizing VC
-
-@vindex vc-handled-backends
-The variable @code{vc-handled-backends} determines which version
-control systems VC should handle. The default value is @code{(RCS CVS
-SVN SCCS BZR GIT HG Arch MCVS)}, so it contains all the version systems
-that are currently supported. If you want VC to ignore one or more of
-these systems, exclude its name from the list. To disable VC entirely,
-set this variable to @code{nil}.
-
-The order of systems in the list is significant: when you visit a file
-registered in more than one system (@pxref{Local Version Control}), VC
-uses the system that comes first in @code{vc-handled-backends} by
-default. The order is also significant when you register a file for
-the first time, see
-@iftex
-@ref{Registering,,,emacs, the Emacs Manual},
-@end iftex
-@ifnottex
-@ref{Registering},
-@end ifnottex
-for details.
-
-@menu
-* General VC Options:: Options that apply to multiple back ends.
-* RCS and SCCS:: Options for RCS and SCCS.
-* CVS Options:: Options for CVS.
-@end menu
-
-@node General VC Options
-@subsubsection General Options
-
-@vindex vc-make-backup-files
- Emacs normally does not save backup files for source files that are
-maintained with version control. If you want to make backup files even
-for files that use version control, set the variable
-@code{vc-make-backup-files} to a non-@code{nil} value.
-
-@vindex vc-keep-workfiles
- Normally the work file exists all the time, whether it is locked or
-not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking
-in a new version with @kbd{C-x v v} deletes the work file; but any
-attempt to visit the file with Emacs creates it again. (With CVS, work
-files are always kept.)
-
-@vindex vc-follow-symlinks
- Editing a version-controlled file through a symbolic link can be
-dangerous. It bypasses the version control system---you can edit the
-file without locking it, and fail to check your changes in. Also,
-your changes might overwrite those of another user. To protect against
-this, VC checks each symbolic link that you visit, to see if it points
-to a file under version control.
-
- The variable @code{vc-follow-symlinks} controls what to do when a
-symbolic link points to a version-controlled file. If it is @code{nil},
-VC only displays a warning message. If it is @code{t}, VC automatically
-follows the link, and visits the real file instead, telling you about
-this in the echo area. If the value is @code{ask} (the default), VC
-asks you each time whether to follow the link.
-
-@vindex vc-suppress-confirm
- If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v}
-and @kbd{C-x v i} can save the current buffer without asking, and
-@kbd{C-x v u} also operates without asking for confirmation. (This
-variable does not affect @kbd{C-x v c}; that operation is so drastic
-that it should always ask for confirmation.)
-
-@vindex vc-command-messages
- VC mode does much of its work by running the shell commands for RCS,
-CVS and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC
-displays messages to indicate which shell commands it runs, and
-additional messages when the commands finish.
-
-@vindex vc-path
- You can specify additional directories to search for version control
-programs by setting the variable @code{vc-path}. These directories
-are searched before the usual search path. It is rarely necessary to
-set this variable, because VC normally finds the proper files
-automatically.
-
-@node RCS and SCCS
-@subsubsection Options for RCS and SCCS
-
-@cindex non-strict locking (RCS)
-@cindex locking, non-strict (RCS)
- By default, RCS uses locking to coordinate the activities of several
-users, but there is a mode called @dfn{non-strict locking} in which
-you can check-in changes without locking the file first. Use
-@samp{rcs -U} to switch to non-strict locking for a particular file,
-see the @code{rcs} manual page for details.
-
- When deducing the version control state of an RCS file, VC first
-looks for an RCS version header string in the file (@pxref{Version
-Headers}). If there is no header string, VC normally looks at the
-file permissions of the work file; this is fast. But there might be
-situations when the file permissions cannot be trusted. In this case
-the master file has to be consulted, which is rather expensive. Also
-the master file can only tell you @emph{if} there's any lock on the
-file, but not whether your work file really contains that locked
-version.
-
-@vindex vc-consult-headers
- You can tell VC not to use version headers to determine the file
-status by setting @code{vc-consult-headers} to @code{nil}. VC then
-always uses the file permissions (if it is supposed to trust them), or
-else checks the master file.
-
-@vindex vc-mistrust-permissions
- You can specify the criterion for whether to trust the file
-permissions by setting the variable @code{vc-mistrust-permissions}.
-Its value can be @code{t} (always mistrust the file permissions and
-check the master file), @code{nil} (always trust the file
-permissions), or a function of one argument which makes the decision.
-The argument is the directory name of the @file{RCS} subdirectory. A
-non-@code{nil} value from the function says to mistrust the file
-permissions. If you find that the file permissions of work files are
-changed erroneously, set @code{vc-mistrust-permissions} to @code{t}.
-Then VC always checks the master file to determine the file's status.
-
- VC determines the version control state of files under SCCS much as
-with RCS. It does not consider SCCS version headers, though. Thus,
-the variable @code{vc-mistrust-permissions} affects SCCS use, but
-@code{vc-consult-headers} does not.
-
-@node CVS Options
-@subsubsection Options specific for CVS
-
-@cindex locking (CVS)
- By default, CVS does not use locking to coordinate the activities of
-several users; anyone can change a work file at any time. However,
-there are ways to restrict this, resulting in behavior that resembles
-locking.
-
-@cindex CVSREAD environment variable (CVS)
- For one thing, you can set the @env{CVSREAD} environment variable
-(the value you use makes no difference). If this variable is defined,
-CVS makes your work files read-only by default. In Emacs, you must
-type @kbd{C-x v v} to make the file writable, so that editing works
-in fact similar as if locking was used. Note however, that no actual
-locking is performed, so several users can make their files writable
-at the same time. When setting @env{CVSREAD} for the first time, make
-sure to check out all your modules anew, so that the file protections
-are set correctly.
-
-@cindex cvs watch feature
-@cindex watching files (CVS)
- Another way to achieve something similar to locking is to use the
-@dfn{watch} feature of CVS. If a file is being watched, CVS makes it
-read-only by default, and you must also use @kbd{C-x v v} in Emacs to
-make it writable. VC calls @code{cvs edit} to make the file writable,
-and CVS takes care to notify other developers of the fact that you
-intend to change the file. See the CVS documentation for details on
-using the watch feature.
-
-@vindex vc-stay-local
-@vindex vc-cvs-stay-local
-@cindex remote repositories (CVS)
- When a file's repository is on a remote machine, VC tries to keep
-network interactions to a minimum. This is controlled by the variable
-@code{vc-cvs-stay-local}. There is another variable,
-@code{vc-stay-local}, which enables the feature also for other back
-ends that support it, including CVS. In the following, we will talk
-only about @code{vc-cvs-stay-local}, but everything applies to
-@code{vc-stay-local} as well.
-
-If @code{vc-cvs-stay-local} is @code{t} (the default), then VC uses
-only the entry in the local CVS subdirectory to determine the file's
-state (and possibly information returned by previous CVS commands).
-One consequence of this is that when you have modified a file, and
-somebody else has already checked in other changes to the file, you
-are not notified of it until you actually try to commit. (But you can
-try to pick up any recent changes from the repository first, using
-@kbd{C-x v m @key{RET}},
-@iftex
-@pxref{Merging,,,emacs, the Emacs Manual}).
-@end iftex
-@ifnottex
-@pxref{Merging}).
-@end ifnottex
-
- When @code{vc-cvs-stay-local} is @code{t}, VC also makes local
-version backups, so that simple diff and revert operations are
-completely local (@pxref{Version Backups}).
-
- On the other hand, if you set @code{vc-cvs-stay-local} to @code{nil},
-then VC queries the remote repository @emph{before} it decides what to
-do in @code{vc-next-action} (@kbd{C-x v v}), just as it does for local
-repositories. It also does not make any version backups.
-
- You can also set @code{vc-cvs-stay-local} to a regular expression
-that is matched against the repository host name; VC then stays local
-only for repositories from hosts that match the pattern.
-
-@vindex vc-cvs-global-switches
- You can specify additional command line options to pass to all CVS
-operations in the variable @code{vc-cvs-global-switches}. These
-switches are inserted immediately after the @code{cvs} command, before
-the name of the operation to invoke.
-
-@ignore
- arch-tag: 140b8629-4339-4b5e-9e50-72453e51615e
-@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
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Windows, Frames, Buffers, Top
-@chapter Multiple Windows
-@cindex windows in Emacs
-@cindex multiple windows in Emacs
-
- Emacs can split a frame into two or many windows. Multiple windows
-can display parts of different buffers, or different parts of one
-buffer. Multiple frames always imply multiple windows, because each
-frame has its own set of windows. Each window belongs to one and only
-one frame.
-
-@menu
-* Basic Window:: Introduction to Emacs windows.
-* Split Window:: New windows are made by splitting existing windows.
-* Other Window:: Moving to another window or doing something to it.
-* Pop Up Window:: Finding a file or buffer in another window.
-* Force Same Window:: Forcing certain buffers to appear in the selected
- window rather than in another window.
-* Change Window:: Deleting windows and changing their sizes.
-* Window Convenience:: Convenience functions for window handling.
-@end menu
-
-@node Basic Window
-@section Concepts of Emacs Windows
-
- Each Emacs window displays one Emacs buffer at any time. A single
-buffer may appear in more than one window; if it does, any changes in
-its text are displayed in all the windows where it appears. But these
-windows can show different parts of the buffer, because each window
-has its own value of point.
-
-@cindex selected window
- At any time, one Emacs window is the @dfn{selected window}; the
-buffer this window is displaying is the current buffer. The terminal's
-cursor shows the location of point in this window. Each other window
-has a location of point as well. On text-only terminals, there is no
-way to show where those locations are, since the terminal has only one
-cursor. On a graphical display, the location of point in a
-non-selected window is indicated by a hollow box; the cursor in the
-selected window is blinking or solid.
-
- Commands to move point affect the value of point for the selected Emacs
-window only. They do not change the value of point in other Emacs
-windows, even those showing the same buffer. The same is true for commands
-such as @kbd{C-x b} to switch buffers in the selected window;
-they do not affect other windows at all. However, there are other commands
-such as @kbd{C-x 4 b} that select a different window and switch buffers in
-it. Also, all commands that display information in a window, including
-(for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b}
-(@code{list-buffers}), work by switching buffers in a nonselected window
-without affecting the selected window.
-
- When multiple windows show the same buffer, they can have different
-regions, because they can have different values of point. However,
-they all have the same value for the mark, because each buffer has
-only one mark position.
-
- Each window has its own mode line, which displays the buffer name,
-modification status and major and minor modes of the buffer that is
-displayed in the window. The selected window's mode line appears in a
-different color. @xref{Mode Line}, for full details on the mode line.
-
-@node Split Window
-@section Splitting Windows
-
-@table @kbd
-@item C-x 2
-Split the selected window into two windows, one above the other
-(@code{split-window-vertically}).
-@item C-x 3
-Split the selected window into two windows positioned side by side
-(@code{split-window-horizontally}).
-@item C-Mouse-2
-In the mode line or scroll bar of a window, split that window.
-@end table
-
-@kindex C-x 2
-@findex split-window-vertically
- The command @kbd{C-x 2} (@code{split-window-vertically}) breaks the
-selected window into two windows, one above the other. Both windows start
-out displaying the same buffer, with the same value of point. By default
-the two windows each get half the height of the window that was split; a
-numeric argument specifies how many lines to give to the top window.
-
-@kindex C-x 3
-@findex split-window-horizontally
- @kbd{C-x 3} (@code{split-window-horizontally}) breaks the selected
-window into two side-by-side windows. A numeric argument specifies how
-many columns to give the one on the left. If you are not using
-scrollbars, a vertical line separates the two windows.
-You can customize its color with the face @code{vertical-border}.
-Windows that are not the full width of the screen have mode lines, but
-they are truncated. On terminals where Emacs does not support
-highlighting, truncated mode lines sometimes do not appear in inverse
-video.
-
-@kindex C-Mouse-2 @r{(scroll bar)}
- You can split a window horizontally or vertically by clicking
-@kbd{C-Mouse-2} in the mode line or the scroll bar. The line of
-splitting goes through the place where you click: if you click on the
-mode line, the new scroll bar goes above the spot; if you click in the
-scroll bar, the mode line of the split window is side by side with
-your click.
-
-@vindex truncate-partial-width-windows
- When a window is less than the full width, text lines too long to
-fit are frequent. Continuing all those lines might be confusing, so
-if the variable @code{truncate-partial-width-windows} is
-non-@code{nil}, that forces truncation in all windows less than the
-full width of the screen, independent of the buffer being displayed
-and its value for @code{truncate-lines}. @xref{Line Truncation}.
-
- Horizontal scrolling is often used in side-by-side windows.
-@xref{Horizontal Scrolling}.
-
-@vindex split-window-keep-point
- If @code{split-window-keep-point} is non-@code{nil}, the default,
-both of the windows resulting from @kbd{C-x 2} inherit the value of
-point from the window that was split. This means that scrolling is
-inevitable. If this variable is @code{nil}, then @kbd{C-x 2} tries to
-avoid scrolling the text currently visible on the screen, by putting
-point in each window at a position already visible in the window. It
-also selects whichever window contains the screen line that the cursor
-was previously on. Some users prefer that mode on slow terminals.
-
-@node Other Window
-@section Using Other Windows
-
-@table @kbd
-@item C-x o
-Select another window (@code{other-window}). That is @kbd{o}, not zero.
-@item C-M-v
-Scroll the next window (@code{scroll-other-window}).
-@item M-x compare-windows
-Find next place where the text in the selected window does not match
-the text in the next window.
-@item Mouse-1
-@kbd{Mouse-1}, in a window's mode line, selects that window
-but does not move point in it (@code{mouse-select-window}).
-@end table
-
-@kindex C-x o
-@findex other-window
- To select a different window, click with @kbd{Mouse-1} on its mode
-line. With the keyboard, you can switch windows by typing @kbd{C-x o}
-(@code{other-window}). That is an @kbd{o}, for ``other,'' not a zero.
-When there are more than two windows, this command moves through all the
-windows in a cyclic order, generally top to bottom and left to right.
-After the rightmost and bottommost window, it goes back to the one at
-the upper left corner. A numeric argument means to move several steps
-in the cyclic order of windows. A negative argument moves around the
-cycle in the opposite order. When the minibuffer is active, the
-minibuffer is the last window in the cycle; you can switch from the
-minibuffer window to one of the other windows, and later switch back and
-finish supplying the minibuffer argument that is requested.
-@xref{Minibuffer Edit}.
-
-@kindex C-M-v
-@findex scroll-other-window
- The usual scrolling commands (@pxref{Display}) apply to the selected
-window only, but there is one command to scroll the next window.
-@kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that
-@kbd{C-x o} would select. It takes arguments, positive and negative,
-like @kbd{C-v}. (In the minibuffer, @kbd{C-M-v} scrolls the window
-that contains the minibuffer help display, if any, rather than the
-next window in the standard cyclic order.)
-
- The command @kbd{M-x compare-windows} lets you compare two files or
-buffers visible in two windows, by moving through them to the next
-mismatch. @xref{Comparing Files}, for details.
-
-@vindex mouse-autoselect-window
- If you set @code{mouse-autoselect-window} to a non-@code{nil} value,
-moving the mouse into a different window selects that window. This
-feature is off by default.
-
-@node Pop Up Window
-@section Displaying in Another Window
-
-@cindex selecting buffers in other windows
-@kindex C-x 4
- @kbd{C-x 4} is a prefix key for commands that select another window
-(splitting the window if there is only one) and select a buffer in that
-window. Different @kbd{C-x 4} commands have different ways of finding the
-buffer to select.
-
-@table @kbd
-@item C-x 4 b @var{bufname} @key{RET}
-Select buffer @var{bufname} in another window. This runs
-@code{switch-to-buffer-other-window}.
-@item C-x 4 C-o @var{bufname} @key{RET}
-Display buffer @var{bufname} in another window, but
-don't select that buffer or that window. This runs
-@code{display-buffer}.
-@item C-x 4 f @var{filename} @key{RET}
-Visit file @var{filename} and select its buffer in another window. This
-runs @code{find-file-other-window}. @xref{Visiting}.
-@item C-x 4 d @var{directory} @key{RET}
-Select a Dired buffer for directory @var{directory} in another window.
-This runs @code{dired-other-window}. @xref{Dired}.
-@item C-x 4 m
-Start composing a mail message in another window. This runs
-@code{mail-other-window}; its same-window analogue is @kbd{C-x m}
-(@pxref{Sending Mail}).
-@item C-x 4 .
-Find a tag in the current tags table, in another window. This runs
-@code{find-tag-other-window}, the multiple-window variant of @kbd{M-.}
-(@pxref{Tags}).
-@item C-x 4 r @var{filename} @key{RET}
-Visit file @var{filename} read-only, and select its buffer in another
-window. This runs @code{find-file-read-only-other-window}.
-@xref{Visiting}.
-@end table
-
-@node Force Same Window
-@section Forcing Display in the Same Window
-
- Certain Emacs commands switch to a specific buffer with special
-contents. For example, @kbd{M-x shell} switches to a buffer named
-@samp{*shell*}. By convention, all these commands are written to pop up
-the buffer in a separate window. But you can specify that certain of
-these buffers should appear in the selected window.
-
-@vindex same-window-buffer-names
- If you add a buffer name to the list @code{same-window-buffer-names},
-the effect is that such commands display that particular buffer by
-switching to it in the selected window. For example, if you add the
-element @code{"*grep*"} to the list, the @code{grep} command will
-display its output buffer in the selected window.
-
- The default value of @code{same-window-buffer-names} is not
-@code{nil}: it specifies buffer names @samp{*info*}, @samp{*mail*} and
-@samp{*shell*} (as well as others used by more obscure Emacs packages).
-This is why @kbd{M-x shell} normally switches to the @samp{*shell*}
-buffer in the selected window. If you delete this element from the
-value of @code{same-window-buffer-names}, the behavior of @kbd{M-x
-shell} will change---it will pop up the buffer in another window
-instead.
-
-@vindex same-window-regexps
- You can specify these buffers more generally with the variable
-@code{same-window-regexps}. Set it to a list of regular expressions;
-then any buffer whose name matches one of those regular expressions is
-displayed by switching to it in the selected window. (Once again, this
-applies only to buffers that normally get displayed for you in a
-separate window.) The default value of this variable specifies Telnet
-and rlogin buffers.
-
- An analogous feature lets you specify buffers which should be
-displayed in their own individual frames. @xref{Special Buffer Frames}.
-
-@node Change Window
-@section Deleting and Rearranging Windows
-
-@table @kbd
-@item C-x 0
-Delete the selected window (@code{delete-window}). The last character
-in this key sequence is a zero.
-@item C-x 1
-Delete all windows in the selected frame except the selected window
-(@code{delete-other-windows}).
-@item C-x 4 0
-Delete the selected window and kill the buffer that was showing in it
-(@code{kill-buffer-and-window}). The last character in this key
-sequence is a zero.
-@item C-x ^
-Make selected window taller (@code{enlarge-window}).
-@item C-x @}
-Make selected window wider (@code{enlarge-window-horizontally}).
-@item C-x @{
-Make selected window narrower (@code{shrink-window-horizontally}).
-@item C-x -
-Shrink this window if its buffer doesn't need so many lines
-(@code{shrink-window-if-larger-than-buffer}).
-@item C-x +
-Make all windows the same height (@code{balance-windows}).
-@end table
-
-@kindex C-x 0
-@findex delete-window
- To delete a window, type @kbd{C-x 0} (@code{delete-window}). (That is
-a zero.) The space occupied by the deleted window is given to an
-adjacent window (but not the minibuffer window, even if that is active
-at the time). Once a window is deleted, its attributes are forgotten;
-only restoring a window configuration can bring it back. Deleting the
-window has no effect on the buffer it used to display; the buffer
-continues to exist, and you can select it in any window with @kbd{C-x
-b}.
-
-@findex kill-buffer-and-window
-@kindex C-x 4 0
- @kbd{C-x 4 0} (@code{kill-buffer-and-window}) is a stronger command
-than @kbd{C-x 0}; it kills the current buffer and then deletes the
-selected window.
-
-@kindex C-x 1
-@findex delete-other-windows
- @kbd{C-x 1} (@code{delete-other-windows}) is more powerful in a
-different way; it deletes all the windows except the selected one (and
-the minibuffer); the selected window expands to use the whole frame
-except for the echo area.
-
-@kindex C-x ^
-@findex enlarge-window
-@kindex C-x @}
-@findex enlarge-window-horizontally
-@vindex window-min-height
-@vindex window-min-width
- To readjust the division of space among vertically adjacent windows,
-use @kbd{C-x ^} (@code{enlarge-window}). It makes the currently
-selected window one line bigger, or as many lines as is specified
-with a numeric argument. With a negative argument, it makes the
-selected window smaller. @kbd{C-x @}}
-(@code{enlarge-window-horizontally}) makes the selected window wider by
-the specified number of columns. @kbd{C-x @{}
-(@code{shrink-window-horizontally}) makes the selected window narrower
-by the specified number of columns.
-
- When you make a window bigger, the space comes from its peers. If
-this makes any window too small, it is deleted and its space is given
-to an adjacent window. The minimum size is specified by the variables
-@code{window-min-height} and @code{window-min-width}.
-
-@kindex C-x -
-@findex shrink-window-if-larger-than-buffer
- The command @kbd{C-x -} (@code{shrink-window-if-larger-than-buffer})
-reduces the height of the selected window, if it is taller than
-necessary to show the whole text of the buffer it is displaying. It
-gives the extra lines to other windows in the frame.
-
-@kindex C-x +
-@findex balance-windows
- You can also use @kbd{C-x +} (@code{balance-windows}) to even out the
-heights of all the windows in the selected frame.
-
- Mouse clicks on the mode line provide another way to change window
-heights and to delete windows. @xref{Mode Line Mouse}.
-
-@node Window Convenience
-@section Window Handling Convenience Features and Customization
-
-@findex winner-mode
-@cindex Winner mode
-@cindex mode, Winner
-@cindex undoing window configuration changes
-@cindex window configuration changes, undoing
- @kbd{M-x winner-mode} is a global minor mode that records the
-changes in the window configuration (i.e. how the frames are
-partitioned into windows), so that you can ``undo'' them. To undo,
-use @kbd{C-c left} (@code{winner-undo}). If you change your mind
-while undoing, you can redo the changes you had undone using @kbd{C-c
-right} (@code{M-x winner-redo}). Another way to enable Winner mode is
-by customizing the variable @code{winner-mode}.
-
-@cindex Windmove package
-@cindex directional window selection
-@findex windmove-right
-@findex windmove-default-keybindings
- The Windmove commands move directionally between neighboring windows in
-a frame. @kbd{M-x windmove-right} selects the window immediately to the
-right of the currently selected one, and similarly for the ``left,'' ``up,''
-and ``down'' counterparts. @kbd{M-x windmove-default-keybindings} binds
-these commands to @kbd{S-right} etc. (Not all terminals support shifted
-arrow keys, however.)
-
- Follow minor mode (@kbd{M-x follow-mode}) synchronizes several
-windows on the same buffer so that they always display adjacent
-sections of that buffer. @xref{Follow Mode}.
-
-@vindex scroll-all-mode
-@cindex scrolling windows together
-@cindex Scroll-all mode
-@cindex mode, Scroll-all
- @kbd{M-x scroll-all-mode} provides commands to scroll all visible
-windows together. You can also turn it on by customizing the variable
-@code{scroll-all-mode}. The commands provided are @kbd{M-x
-scroll-all-scroll-down-all}, @kbd{M-x scroll-all-page-down-all} and
-their corresponding ``up'' equivalents. To make this mode useful,
-you should bind these commands to appropriate keys.
-
-@ignore
- arch-tag: 8bea7453-d4b1-49b1-9bf4-cfe4383e1113
-@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
+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003,
-@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node X Resources, Antinews, Emacs Invocation, Top
-@appendix X Options and Resources
-
- You can customize some X-related aspects of Emacs behavior using X
-resources, as is usual for programs that use X. On MS-Windows, you
-can customize some of the same aspects using the system registry.
-@xref{MS-Windows Registry}. Likewise, Emacs on MacOS Carbon emulates X
-resources using the Preferences system. @xref{Mac Environment Variables}.
-
- When Emacs is built using an ``X toolkit'', such as Lucid or
-LessTif, you need to use X resources to customize the appearance of
-the widgets, including the menu-bar, scroll-bar, and dialog boxes.
-This is because the libraries that implement these don't provide for
-customization through Emacs. GTK+ widgets use a separate system of
-@ifnottex
-``GTK resources'', which we will also describe.
-@end ifnottex
-@iftex
-``GTK resources.'' In this chapter we describe the most commonly used
-resource specifications. For full documentation, see the online
-manual.
-
-@c Add xref for LessTif/Motif menu resources.
-@end iftex
-
-
-@menu
-* Resources:: Using X resources with Emacs (in general).
-* Table of Resources:: Table of specific X resources that affect Emacs.
-* Face Resources:: X resources for customizing faces.
-* Lucid Resources:: X resources for Lucid menus.
-* LessTif Resources:: X resources for LessTif and Motif menus.
-* GTK resources:: Resources for GTK widgets.
-@end menu
-
-@node Resources
-@appendixsec X Resources
-@cindex resources
-@cindex X resources
-@cindex @file{~/.Xdefaults} file
-@cindex @file{~/.Xresources} file
-
- Programs running under the X Window System organize their user
-options under a hierarchy of classes and resources. You can specify
-default values for these options in your X resources file, usually
-named @file{~/.Xdefaults} or @file{~/.Xresources}.
-If changes in @file{~/.Xdefaults} do not
-take effect, it is because your X server stores its own list of
-resources; to update them, use the shell command @command{xrdb}---for
-instance, @samp{xrdb ~/.Xdefaults}.
-
- Each line in the file specifies a value for one option or for a
-collection of related options, for one program or for several programs
-(optionally even for all programs).
-
-@cindex Registry (MS-Windows)
- MS-Windows systems do not support @file{~/.Xdefaults} files, so
-instead Emacs compiled for Windows looks for X resources in the
-Windows Registry, first under the key
-@samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} and then under the key
-@samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}. The menu and scroll
-bars are native widgets on MS-Windows, so they are only customizable
-via the system-wide settings in the Display Control Panel. You can
-also set resources using the @samp{-xrm} command line option (see
-below.)
-
-@iftex
- Applications such as Emacs look for resources with specific names
-and their particular meanings. Case distinctions are significant in
-these names. Each resource specification in @file{~/.Xdefaults}
-states the name of the program and the name of the resource. For
-Emacs, the program name is @samp{Emacs}. It looks like this:
-
-@example
-Emacs.borderWidth: 2
-@end example
-@end iftex
-@ifnottex
- Programs define named resources with particular meanings. They also
-define how to group resources into named classes. For instance, in
-Emacs, the @samp{internalBorder} resource controls the width of the
-internal border, and the @samp{borderWidth} resource controls the width
-of the external border. Both of these resources are part of the
-@samp{BorderWidth} class. Case distinctions are significant in these
-names.
-
- Every resource definition is associated with a specific program
-name---the name of the executable file that you ran. For Emacs, that
-is normally @samp{emacs}. To specify a definition for all instances
-of Emacs, regardless of their names, use @samp{Emacs}.
-
- In @file{~/.Xdefaults}, you can specify a value for a single resource
-on one line, like this:
-
-@example
-emacs.borderWidth: 2
-@end example
-
-@noindent
-Or you can use a class name to specify the same value for all resources
-in that class. Here's an example:
-
-@example
-emacs.BorderWidth: 2
-@end example
-
- If you specify a value for a class, it becomes the default for all
-resources in that class. You can specify values for individual
-resources as well; these override the class value, for those particular
-resources. Thus, this example specifies 2 as the default width for all
-borders, but overrides this value with 4 for the external border:
-
-@example
-emacs.BorderWidth: 2
-emacs.borderWidth: 4
-@end example
-@end ifnottex
-
- The order in which the lines appear in the file does not matter.
-Also, command-line options always override the X resources file.
-
-@ifnottex
-Here is a list of X command-line options and their corresponding
-resource names.
-
-@table @samp
-@item -name @var{name}
-@opindex --name
-@itemx --name=@var{name}
-@cindex resource name, command-line argument
-Use @var{name} as the resource name (and the title) for the initial
-Emacs frame. This option does not affect subsequent frames, but Lisp
-programs can specify frame names when they create frames.
-
-If you don't specify this option, the default is to use the Emacs
-executable's name as the resource name.
-
-@item -xrm @var{resource-values}
-@opindex --xrm
-@itemx --xrm=@var{resource-values}
-@cindex resource values, command-line argument
-Specify X resource values for this Emacs job (see below).
-@end table
-
- For consistency, @samp{-name} also specifies the name to use for
-other resource values that do not belong to any particular frame.
-
- The resources that name Emacs invocations also belong to a class; its
-name is @samp{Emacs}. If you write @samp{Emacs} instead of
-@samp{emacs}, the resource applies to all frames in all Emacs jobs,
-regardless of frame titles and regardless of the name of the executable
-file. Here is an example:
-
-@example
-Emacs.BorderWidth: 2
-Emacs.borderWidth: 4
-@end example
-
- You can specify a string of additional resource values for Emacs to
-use with the command line option @samp{-xrm @var{resources}}. The text
-@var{resources} should have the same format that you would use inside a file
-of X resources. To include multiple resource specifications in
-@var{resources}, put a newline between them, just as you would in a file.
-You can also use @samp{#include "@var{filename}"} to include a file full
-of resource specifications. Resource values specified with @samp{-xrm}
-take precedence over all other resource specifications.
-
- One way to experiment with the effect of different resource settings
-is to use the @code{editres} program. Select @samp{Get Tree} from the
-@end ifnottex
-@iftex
- You can experiment with the effect of different resource settings
-with the @code{editres} program. Select @samp{Get Tree} from the
-@end iftex
-@samp{Commands} menu, then click on an Emacs frame. This will display
-a tree showing the structure of X toolkit widgets used in an Emacs
-frame. Select one of them, such as @samp{menubar}, then select
-@samp{Show Resource Box} from the @samp{Commands} menu. This displays
-a list of all the meaningful X resources for that widget, and allows
-you to edit them. Changes take effect when you click on the
-@samp{Apply} button. (See the @code{editres} man page for more
-details.)
-
-@node Table of Resources
-@appendixsec Table of X Resources for Emacs
-
- This table lists the resource names that designate options for
-Emacs, not counting those for the appearance of the menu bar, each
-with the class that it belongs to:
-
-@table @asis
-@item @code{background} (class @code{Background})
-Background color name.
-
-@ifnottex
-@item @code{bitmapIcon} (class @code{BitmapIcon})
-Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window
-manager choose an icon if @samp{off}.
-@end ifnottex
-
-@item @code{borderColor} (class @code{BorderColor})
-Color name for the external border.
-
-@ifnottex
-@item @code{borderWidth} (class @code{BorderWidth})
-Width in pixels of the external border.
-@end ifnottex
-
-@item @code{cursorColor} (class @code{Foreground})
-Color name for text cursor (point).
-
-@ifnottex
-@item @code{cursorBlink} (class @code{CursorBlink})
-Specifies whether to make the cursor blink. The default is @samp{on}. Use
-@samp{off} or @samp{false} to turn cursor blinking off.
-@end ifnottex
-
-@item @code{font} (class @code{Font})
-Font name (or fontset name, @pxref{Fontsets}) for @code{default} font.
-
-@item @code{foreground} (class @code{Foreground})
-Color name for text.
-
-@item @code{geometry} (class @code{Geometry})
-Window size and position. Be careful not to specify this resource as
-@samp{emacs*geometry}, because that may affect individual menus as well
-as the Emacs frame itself.
-
-If this resource specifies a position, that position applies only to the
-initial Emacs frame (or, in the case of a resource for a specific frame
-name, only that frame). However, the size, if specified here, applies to
-all frames.
-
-@ifnottex
-@item @code{fullscreen} (class @code{Fullscreen})
-The desired fullscreen size. The value can be one of @code{fullboth},
-@code{fullwidth} or @code{fullheight}, which correspond to
-the command-line options @samp{-fs}, @samp{-fw}, and @samp{-fh}
-(@pxref{Window Size X}).
-
-Note that this applies to the initial frame only.
-@end ifnottex
-
-@item @code{iconName} (class @code{Title})
-Name to display in the icon.
-
-@item @code{internalBorder} (class @code{BorderWidth})
-Width in pixels of the internal border.
-
-@item @code{lineSpacing} (class @code{LineSpacing})
-@cindex line spacing
-@cindex leading
-Additional space (@dfn{leading}) between lines, in pixels.
-
-@item @code{menuBar} (class @code{MenuBar})
-@cindex menu bar
-Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}.
-@ifnottex
-@xref{Lucid Resources}, and @ref{LessTif Resources},
-@end ifnottex
-@iftex
-@xref{Lucid Resources},
-@end iftex
-for how to control the appearance of the menu bar if you have one.
-
-@ifnottex
-@item @code{minibuffer} (class @code{Minibuffer})
-If @samp{none}, don't make a minibuffer in this frame.
-It will use a separate minibuffer frame instead.
-
-@item @code{paneFont} (class @code{Font})
-@cindex font for menus
-Font name for menu pane titles, in non-toolkit versions of Emacs.
-@end ifnottex
-
-@item @code{pointerColor} (class @code{Foreground})
-Color of the mouse cursor.
-
-@ifnottex
-@item @code{privateColormap} (class @code{PrivateColormap})
-If @samp{on}, use a private color map, in the case where the ``default
-visual'' of class PseudoColor and Emacs is using it.
-
-@item @code{reverseVideo} (class @code{ReverseVideo})
-Switch foreground and background default colors if @samp{on}, use colors as
-specified if @samp{off}.
-@end ifnottex
-
-@item @code{screenGamma} (class @code{ScreenGamma})
-@cindex gamma correction
-Gamma correction for colors, equivalent to the frame parameter
-@code{screen-gamma}.
-
-@item @code{scrollBarWidth} (class @code{ScrollBarWidth})
-@cindex scrollbar width
-The scroll bar width in pixels, equivalent to the frame parameter
-@code{scroll-bar-width}.
-
-@ifnottex
-@item @code{selectionFont} (class @code{SelectionFont})
-Font name for pop-up menu items, in non-toolkit versions of Emacs. (For
-toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif
-Resources}.)
-
-@item @code{selectionTimeout} (class @code{SelectionTimeout})
-Number of milliseconds to wait for a selection reply.
-If the selection owner doesn't reply in this time, we give up.
-A value of 0 means wait as long as necessary.
-
-@item @code{synchronous} (class @code{Synchronous})
-@cindex debugging X problems
-@cindex synchronous X mode
-Run Emacs in synchronous mode if @samp{on}. Synchronous mode is
-useful for debugging X problems.
-@end ifnottex
-
-@item @code{title} (class @code{Title})
-Name to display in the title bar of the initial Emacs frame.
-
-@item @code{toolBar} (class @code{ToolBar})
-@cindex tool bar
-Number of lines to reserve for the tool bar. A zero value suppresses
-the tool bar. If the value is non-zero and
-@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size
-will be changed automatically so that all tool bar items are visible.
- If the value of @code{auto-resize-tool-bars} is @code{grow-only},
-the tool bar expands automatically, but does not contract automatically.
-To contract the tool bar, you must redraw the frame by entering @kbd{C-l}.
-
-@item @code{useXIM} (class @code{UseXIM})
-@cindex XIM
-@cindex X input methods
-@cindex input methods, X
-Turn off use of X input methods (XIM) if @samp{false} or @samp{off}.
-This is only relevant if your Emacs is actually built with XIM
-support. It is potentially useful to turn off XIM for efficiency,
-especially slow X client/server links.
-
-@item @code{verticalScrollBars} (class @code{ScrollBars})
-Give frames scroll bars if @samp{on}; don't have scroll bars if
-@samp{off}.
-
-@ifnottex
-@item @code{visualClass} (class @code{VisualClass})
-Specify the ``visual'' that X should use. This tells X how to handle
-colors.
-
-The value should start with one of @samp{TrueColor},
-@samp{PseudoColor}, @samp{DirectColor}, @samp{StaticColor},
-@samp{GrayScale}, and @samp{StaticGray}, followed by
-@samp{-@var{depth}}, where @var{depth} is the number of color planes.
-Most terminals only allow a few ``visuals,'' and the @samp{dpyinfo}
-program outputs information saying which ones.
-@end ifnottex
-@end table
-
-@node Face Resources
-@appendixsec X Resources for Faces
-
- You can use resources to customize the appearance of particular
-faces (@pxref{Faces}):
-
-@table @code
-@item @var{face}.attributeForeground
-Foreground color for face @var{face}.
-@item @var{face}.attributeBackground
-Background color for face @var{face}.
-@item @var{face}.attributeUnderline
-Underline flag for face @var{face}. Use @samp{on} or @samp{true} for
-yes.
-@item @var{face}.attributeStrikeThrough
-@itemx @var{face}.attributeOverline
-@itemx @var{face}.attributeBox
-@itemx @var{face}.attributeInverse
-Likewise, for other boolean font attributes.
-@item @var{face}.attributeStipple
-The name of a pixmap data file to use for the stipple pattern, or
-@code{false} to not use stipple for the face @var{face}.
-@item @var{face}.attributeBackgroundPixmap
-The background pixmap for the face @var{face}. Should be a name of a
-pixmap file or @code{false}.
-@item @var{face}.attributeFont
-Font name (full XFD name or valid X abbreviation) for face @var{face}.
-Instead of this, you can specify the font through separate attributes.
-@end table
-
- Instead of using @code{attributeFont} to specify a font name, you can
-select a font through these separate attributes:
-
-@table @code
-@item @var{face}.attributeFamily
-Font family for face @var{face}.
-@item @var{face}.attributeHeight
-Height of the font to use for face @var{face}: either an integer
-specifying the height in units of 1/10@dmn{pt}, or a floating point
-number that specifies a scale factor to scale the underlying face's
-default font, or a function to be called with the default height which
-will return a new height.
-@item @var{face}.attributeWidth
-@itemx @var{face}.attributeWeight
-@itemx @var{face}.attributeSlant
-Each of these resources corresponds to a like-named font attribute,
-and you write the resource value the same as the symbol you would use
-for the font attribute value.
-@item @var{face}.attributeBold
-Bold flag for face @var{face}---instead of @code{attributeWeight}. Use @samp{on} or @samp{true} for
-yes.
-@item @var{face}.attributeItalic
-Italic flag for face @var{face}---instead of @code{attributeSlant}.
-@end table
-
-@node Lucid Resources
-@appendixsec Lucid Menu X Resources
-@cindex Menu X Resources (Lucid widgets)
-@cindex Lucid Widget X Resources
-
-@ifnottex
- If the Emacs installed at your site was built to use the X toolkit
-with the Lucid menu widgets, then the menu bar is a separate widget and
-has its own resources. The resource names contain @samp{pane.menubar}
-(following, as always, the name of the Emacs invocation, or @samp{Emacs},
-which stands for all Emacs invocations). Specify them like this:
-
-@example
-Emacs.pane.menubar.@var{resource}: @var{value}
-@end example
-
-@noindent
-For example, to specify the font @samp{8x16} for the menu-bar items,
-write this:
-@end ifnottex
-@iftex
- If the Emacs installed at your site was built to use the X toolkit
-with the Lucid menu widgets, then the menu bar is a separate widget
-and has its own resources. The resource specifications start with
-@samp{Emacs.pane.menubar}---for instance, to specify the font
-@samp{8x16} for the menu-bar items, write this:
-@end iftex
-
-@example
-Emacs.pane.menubar.font: 8x16
-@end example
-
-@noindent
-Resources for @emph{non-menubar} toolkit pop-up menus have
-@samp{menu*} instead of @samp{pane.menubar}. For example, to specify
-the font @samp{8x16} for the pop-up menu items, write this:
-
-@example
-Emacs.menu*.font: 8x16
-@end example
-
-@noindent
-For dialog boxes, use @samp{dialog*}:
-
-@example
-Emacs.dialog*.font: 8x16
-@end example
-
-@noindent
-The Lucid menus can display multilingual text in your locale. For
-more information about fontsets see the man page for
-@code{XCreateFontSet}. To enable multilingual menu text you specify a
-@code{fontSet} resource instead of the font resource. If both
-@code{font} and @code{fontSet} resources are specified, the
-@code{fontSet} resource is used.
-
- Thus, to specify @samp{-*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*}
-for both the popup and menu bar menus, write this:
-
-@example
-Emacs*menu*fontSet: -*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*
-@end example
-
-@noindent
-The @samp{*menu*} as a wildcard matches @samp{pane.menubar} and
-@samp{menu@dots{}}.
-
-Experience shows that on some systems you may need to add
-@samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On
-some other systems, you must not add @samp{shell.}. The generic wildcard
-approach should work on both kinds of systems.
-
- Here is a list of the specific resources for menu bars and pop-up menus:
-
-@table @code
-@item font
-Font for menu item text.
-@item fontSet
-Fontset for menu item text.
-@item foreground
-Color of the foreground.
-@item background
-Color of the background.
-@item buttonForeground
-In the menu bar, the color of the foreground for a selected item.
-@ifnottex
-@item horizontalSpacing
-Horizontal spacing in pixels between items. Default is 3.
-@item verticalSpacing
-Vertical spacing in pixels between items. Default is 2.
-@item arrowSpacing
-Horizontal spacing between the arrow (which indicates a submenu) and
-the associated text. Default is 10.
-@item shadowThickness
-Thickness of shadow line around the widget. Default is 1.
-
-Also determines the thickness of shadow lines around other objects,
-for instance 3D buttons and arrows. If you have the impression that
-the arrows in the menus do not stand out clearly enough or that the
-difference between ``in'' and ``out'' buttons is difficult to see, set
-this to 2. If you have no problems with visibility, the default
-probably looks better. The background color may also have some effect
-on the contrast.
-@end ifnottex
-@item margin
-The margin of the menu bar, in characters. Default is 1.
-@end table
-
-@ifnottex
-@node LessTif Resources
-@appendixsec LessTif Menu X Resources
-@cindex Menu X Resources (LessTif widgets)
-@cindex LessTif Widget X Resources
-
- If the Emacs installed at your site was built to use the X toolkit
-with the LessTif or Motif widgets, then the menu bar, the dialog
-boxes, the pop-up menus, and the file-selection box are separate
-widgets and have their own resources.
-
- The resource names for the menu bar contain @samp{pane.menubar}
-(following, as always, the name of the Emacs invocation, or
-@samp{Emacs}, which stands for all Emacs invocations). Specify them
-like this:
-
-@smallexample
-Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value}
-@end smallexample
-
- Each individual string in the menu bar is a subwidget; the subwidget's
-name is the same as the menu item string. For example, the word
-@samp{File} in the menu bar is part of a subwidget named
-@samp{emacs.pane.menubar.File}. Most likely, you want to specify the
-same resources for the whole menu bar. To do this, use @samp{*} instead
-of a specific subwidget name. For example, to specify the font
-@samp{8x16} for the menu-bar items, write this:
-
-@smallexample
-Emacs.pane.menubar.*.fontList: 8x16
-@end smallexample
-
-@noindent
-This also specifies the resource value for submenus.
-
- Each item in a submenu in the menu bar also has its own name for X
-resources; for example, the @samp{File} submenu has an item named
-@samp{Save (current buffer)}. A resource specification for a submenu
-item looks like this:
-
-@smallexample
-Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value}
-@end smallexample
-
-@noindent
-For example, here's how to specify the font for the @samp{Save (current
-buffer)} item:
-
-@smallexample
-Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16
-@end smallexample
-
-@noindent
-For an item in a second-level submenu, such as @samp{Complete Word}
-under @samp{Spell Checking} under @samp{Tools}, the resource fits this
-template:
-
-@smallexample
-Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value}
-@end smallexample
-
-@noindent
-For example,
-
-@smallexample
-Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value}
-@end smallexample
-
-@noindent
-(This should be one long line.)
-
- It's impossible to specify a resource for all the menu-bar items
-without also specifying it for the submenus as well. So if you want the
-submenu items to look different from the menu bar itself, you must ask
-for that in two steps. First, specify the resource for all of them;
-then, override the value for submenus alone. Here is an example:
-
-@smallexample
-Emacs.pane.menubar.*.fontList: 8x16
-Emacs.pane.menubar.popup_*.fontList: 8x16
-@end smallexample
-
-@noindent
-For LessTif pop-up menus, use @samp{menu*} instead of
-@samp{pane.menubar}. For example, to specify the font @samp{8x16} for
-the pop-up menu items, write this:
-
-@smallexample
-Emacs.menu*.fontList: 8x16
-@end smallexample
-
-@noindent
-For LessTif dialog boxes, use @samp{dialog} instead of @samp{menu}:
-
-@example
-Emacs.dialog*.fontList: 8x16
-Emacs.dialog*.foreground: hotpink
-@end example
-
-To specify resources for the LessTif file-selection box, use
-@samp{fsb*}, like this:
-
-@example
-Emacs.fsb*.fontList: 8x16
-@end example
-
-@iftex
-@medbreak
-@end iftex
- Here is a list of the specific resources for LessTif menu bars and
-pop-up menus:
-
-@table @code
-@item armColor
-The color to show in an armed button.
-@item fontList
-The font to use.
-@item marginBottom
-@itemx marginHeight
-@itemx marginLeft
-@itemx marginRight
-@itemx marginTop
-@itemx marginWidth
-Amount of space to leave around the item, within the border.
-@item borderWidth
-The width of the border around the menu item, on all sides.
-@item shadowThickness
-The width of the border shadow.
-@item bottomShadowColor
-The color for the border shadow, on the bottom and the right.
-@item topShadowColor
-The color for the border shadow, on the top and the left.
-@end table
-@end ifnottex
-
-
-@node GTK resources
-@appendixsec GTK resources
-@iftex
- The most common way to customize the GTK widgets Emacs uses (menus, dialogs
-tool bars and scroll bars) is by choosing an appropriate theme, for example
-with the GNOME theme selector. You can also do Emacs specific customization
-by inserting GTK style directives in the file @file{~/.emacs.d/gtkrc}. Some GTK
-themes ignore customizations in @file{~/.emacs.d/gtkrc} so not everything
-works with all themes. To customize Emacs font, background, faces, etc., use
-the normal X resources (@pxref{Resources}). We will present some examples of
-customizations here, but for a more detailed description, see the online manual
-
- The first example is just one line. It changes the font on all GTK widgets
-to courier with size 12:
-
-@smallexample
-gtk-font-name = "courier 12"
-@end smallexample
-
- The thing to note is that the font name is not an X font name, like
--*-helvetica-medium-r-*--*-120-*-*-*-*-*-*, but a Pango font name. A Pango
-font name is basically of the format "family style size", where the style
-is optional as in the case above. A name with a style could be for example:
-
-@smallexample
-gtk-font-name = "helvetica bold 10"
-@end smallexample
-
- To customize widgets you first define a style and then apply the style to
-the widgets. Here is an example that sets the font for menus, but not
-for other widgets:
-
-@smallexample
-# @r{Define the style @samp{menufont}.}
-style "menufont"
-@{
- font_name = "helvetica bold 14" # This is a Pango font name
-@}
-
-# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.}
-widget "*emacs-menuitem*" style "menufont"
-@end smallexample
-
-The widget name in this example contains wildcards, so the style will be
-applied to all widgets that match "*emacs-menuitem*". The widgets are
-named by the way they are contained, from the outer widget to the inner widget.
-So to apply the style "my_style" (not shown) with the full, absolute name, for
-the menubar and the scroll bar in Emacs we use:
-
-@smallexample
-widget "Emacs.pane.menubar" style "my_style"
-widget "Emacs.pane.emacs.verticalScrollBar" style "my_style"
-@end smallexample
-
-But to avoid having to type it all, wildcards are often used. @samp{*}
-matches zero or more characters and @samp{?} matches one character. So "*"
-matches all widgets.
-
- Each widget has a class (for example GtkMenuItem) and a name (emacs-menuitem).
-You can assign styles by name or by class. In this example we have used the
-class:
-
-@smallexample
-style "menufont"
-@{
- font_name = "helvetica bold 14"
-@}
-
-widget_class "*GtkMenuBar" style "menufont"
-@end smallexample
-
-@noindent
-The names and classes for the GTK widgets Emacs uses are:
-
-@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some}
-@item @code{emacs-filedialog}
-@tab @code{GtkFileSelection}
-@item @code{emacs-dialog}
-@tab @code{GtkDialog}
-@item @code{Emacs}
-@tab @code{GtkWindow}
-@item @code{pane}
-@tab @code{GtkVHbox}
-@item @code{emacs}
-@tab @code{GtkFixed}
-@item @code{verticalScrollBar}
-@tab @code{GtkVScrollbar}
-@item @code{emacs-toolbar}
-@tab @code{GtkToolbar}
-@item @code{menubar}
-@tab @code{GtkMenuBar}
-@item @code{emacs-menuitem}
-@tab anything in menus
-@end multitable
-
- GTK absolute names are quite strange when it comes to menus
-and dialogs. The names do not start with @samp{Emacs}, as they are
-free-standing windows and not contained (in the GTK sense) by the
-Emacs GtkWindow. To customize the dialogs and menus, use wildcards like this:
-
-@smallexample
-widget "*emacs-dialog*" style "my_dialog_style"
-widget "*emacs-filedialog* style "my_file_style"
-widget "*emacs-menuitem* style "my_menu_style"
-@end smallexample
-
- If you specify a customization in @file{~/.emacs.d/gtkrc}, then it
-automatically applies only to Emacs, since other programs don't read
-that file. For example, the drop down menu in the file dialog can not
-be customized by any absolute widget name, only by an absolute class
-name. This is because the widgets in the drop down menu do not
-have names and the menu is not contained in the Emacs GtkWindow. To
-have all menus in Emacs look the same, use this in
-@file{~/.emacs.d/gtkrc}:
-
-@smallexample
-widget_class "*Menu*" style "my_menu_style"
-@end smallexample
-
- Here is a more elaborate example, showing how to change the parts of
-the scroll bar:
-
-@smallexample
-style "scroll"
-@{
- fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.}
- bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.}
- bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.}
- bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.}
-@}
-
-widget "*verticalScrollBar*" style "scroll"
-@end smallexample
-@end iftex
-
-@ifnottex
-@cindex GTK resources and customization
-@cindex resource files for GTK
-@cindex @file{~/.gtkrc-2.0} file
-@cindex @file{~/.emacs.d/gtkrc} file
-
- If Emacs was built to use the GTK widget set, then the menu bar, tool bar,
-scroll bar and the dialogs are customized with the standard GTK
-customization file, @file{~/.gtkrc-2.0}, or with the Emacs specific
-file @file{~/.emacs.d/gtkrc}. We recommend that you use
-@file{~/.emacs.d/gtkrc} for customizations, since @file{~/.gtkrc-2.0}
-seems to be ignored when running GConf with GNOME. These files apply
-only to GTK widget features. To customize Emacs font, background,
-faces, etc., use the normal X resources (@pxref{Resources}).
-
- Some GTK themes override these mechanisms, which means that using
-these mechanisms will not work to customize them.
-
- In these files you first define a style and say what it means; then
-you specify to apply the style to various widget types (@pxref{GTK
-widget names}). Here is an example of how to change the font for
-Emacs menus:
-
-@smallexample
-# @r{Define the style @samp{menufont}.}
-style "menufont"
-@{
- font_name = "helvetica bold 14" # This is a Pango font name
-@}
-
-# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.}
-widget "*emacs-menuitem*" style "menufont"
-@end smallexample
-
- Here is a more elaborate example, showing how to change the parts of
-the scroll bar:
-
-@smallexample
-style "scroll"
-@{
- fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.}
- bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.}
- bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.}
- bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.}
-@}
-
-widget "*verticalScrollBar*" style "scroll"
-@end smallexample
-
- There are also parameters that affect GTK as a whole. For example,
-the property @code{gtk-font-name} sets the default font for GTK. You
-must use Pango font names (@pxref{GTK styles}). A GTK resources file
-that just sets a default font looks like this:
-
-@smallexample
-gtk-font-name = "courier 12"
-@end smallexample
-
- The GTK resources file is fully described in the GTK API document.
-This can be found in
-@file{@var{prefix}/share/gtk-doc/html/gtk/gtk-resource-files.html},
-where @file{prefix} is the directory in which the GTK libraries were
-installed (usually @file{/usr} or @file{/usr/local}). You can also
-find the document online, at
-@uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}.
-
-@menu
-* GTK widget names:: How widgets in GTK are named in general.
-* GTK Names in Emacs:: GTK widget names in Emacs.
-* GTK styles:: What can be customized in a GTK widget.
-@end menu
-
-@node GTK widget names
-@appendixsubsec GTK widget names
-@cindex GTK widget names
-
- A GTK widget is specified by its @dfn{widget class} and
-@dfn{widget name}. The widget class is the type of the widget: for
-example, @code{GtkMenuBar}. The widget name is the name given to a
-specific widget. A widget always has a class, but need not have a
-name.
-
- @dfn{Absolute names} are sequences of widget names or widget
-classes, corresponding to hierarchies of widgets embedded within
-other widgets. For example, if a @code{GtkWindow} named @code{top}
-contains a @code{GtkVBox} named @code{box}, which in turn contains
-a @code{GtkMenuBar} called @code{menubar}, the absolute class name
-of the menu-bar widget is @code{GtkWindow.GtkVBox.GtkMenuBar}, and
-its absolute widget name is @code{top.box.menubar}.
-
- When assigning a style to a widget, you can use the absolute class
-name or the absolute widget name.
-
- There are two commands to specify changes for widgets:
-
-@table @asis
-@item @code{widget_class}
-specifies a style for widgets based on the absolute class name.
-
-@item @code{widget}
-specifies a style for widgets based on the absolute class name,
-or just the class.
-@end table
-
-@noindent
-You must specify the class and the style in double-quotes, and put
-these commands at the top level in the GTK customization file, like
-this:
-
-@smallexample
-style "menufont"
-@{
- font_name = "helvetica bold 14"
-@}
-
-widget "top.box.menubar" style "menufont"
-widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "menufont"
-@end smallexample
-
- Matching of absolute names uses shell wildcard syntax: @samp{*}
-matches zero or more characters and @samp{?} matches one character.
-This example assigns @code{base_style} to all widgets:
-
-@smallexample
-widget "*" style "base_style"
-@end smallexample
-
- Given the absolute class name @code{GtkWindow.GtkVBox.GtkMenuBar}
-and the corresponding absolute widget name @code{top.box.menubar}, all
-these examples specify @code{my_style} for the menu bar:
-
-@smallexample
-widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
-widget_class "GtkWindow.*.GtkMenuBar" style "my_style"
-widget_class "*GtkMenuBar" style "my_style"
-widget "top.box.menubar" style "my_style"
-widget "*box*menubar" style "my_style"
-widget "*menubar" style "my_style"
-widget "*menu*" style "my_style"
-@end smallexample
-
-@node GTK Names in Emacs
-@appendixsubsec GTK Widget Names in Emacs
-@cindex GTK widget names
-@cindex GTK widget classes
-
- In Emacs, the top level widget for a frame is a @code{GtkWindow}
-that contains a @code{GtkVBox}. The @code{GtkVBox} contains the
-@code{GtkMenuBar} and a @code{GtkFixed} widget. The vertical scroll
-bars, @code{GtkVScrollbar}, are contained in the @code{GtkFixed}
-widget. The text you write in Emacs is drawn in the @code{GtkFixed}
-widget.
-
- Dialogs in Emacs are @code{GtkDialog} widgets. The file dialog is a
-@code{GtkFileSelection} widget.
-
-@noindent
-To set a style for the menu bar using the absolute class name, use:
-
-@smallexample
-widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
-@end smallexample
-
-@noindent
-For the scroll bar, the absolute class name is:
-
-@smallexample
-widget_class
- "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar"
- style "my_style"
-@end smallexample
-
-@noindent
-The names for the emacs widgets, and their classes, are:
-
-@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some}
-@item @code{emacs-filedialog}
-@tab @code{GtkFileSelection}
-@item @code{emacs-dialog}
-@tab @code{GtkDialog}
-@item @code{Emacs}
-@tab @code{GtkWindow}
-@item @code{pane}
-@tab @code{GtkVHbox}
-@item @code{emacs}
-@tab @code{GtkFixed}
-@item @code{verticalScrollBar}
-@tab @code{GtkVScrollbar}
-@item @code{emacs-toolbar}
-@tab @code{GtkToolbar}
-@item @code{menubar}
-@tab @code{GtkMenuBar}
-@item @code{emacs-menuitem}
-@tab anything in menus
-@end multitable
-
-@noindent
-Thus, for Emacs you can write the two examples above as:
-
-@smallexample
-widget "Emacs.pane.menubar" style "my_style"
-widget "Emacs.pane.emacs.verticalScrollBar" style "my_style"
-@end smallexample
-
- GTK absolute names are quite strange when it comes to menus
-and dialogs. The names do not start with @samp{Emacs}, as they are
-free-standing windows and not contained (in the GTK sense) by the
-Emacs GtkWindow. To customize the dialogs and menus, use wildcards like this:
-
-@smallexample
-widget "*emacs-dialog*" style "my_dialog_style"
-widget "*emacs-filedialog* style "my_file_style"
-widget "*emacs-menuitem* style "my_menu_style"
-@end smallexample
-
- If you specify a customization in @file{~/.emacs.d/gtkrc}, then it
-automatically applies only to Emacs, since other programs don't read
-that file. For example, the drop down menu in the file dialog can not
-be customized by any absolute widget name, only by an absolute class
-name. This is because the widgets in the drop down menu do not
-have names and the menu is not contained in the Emacs GtkWindow. To
-have all menus in Emacs look the same, use this in
-@file{~/.emacs.d/gtkrc}:
-
-@smallexample
-widget_class "*Menu*" style "my_menu_style"
-@end smallexample
-
-@node GTK styles
-@appendixsubsec GTK styles
-@cindex GTK styles
-
- In a GTK style you specify the appearance widgets shall have. You
-can specify foreground and background color, background pixmap and
-font. The edit widget (where you edit the text) in Emacs is a GTK
-widget, but trying to specify a style for the edit widget will have no
-effect. This is so that Emacs compiled for GTK is compatible with
-Emacs compiled for other X toolkits. The settings for foreground,
-background and font for the edit widget is taken from the X resources;
-@pxref{Resources}. Here is an example of two style declarations,
-@samp{default} and @samp{ruler}:
-
-@smallexample
-pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps"
-
-style "default"
-@{
- font_name = "helvetica 12"
-
- bg[NORMAL] = @{ 0.83, 0.80, 0.73 @}
- bg[SELECTED] = @{ 0.0, 0.55, 0.55 @}
- bg[INSENSITIVE] = @{ 0.77, 0.77, 0.66 @}
- bg[ACTIVE] = @{ 0.0, 0.55, 0.55 @}
- bg[PRELIGHT] = @{ 0.0, 0.55, 0.55 @}
-
- fg[NORMAL] = "black"
- fg[SELECTED] = @{ 0.9, 0.9, 0.9 @}
- fg[ACTIVE] = "black"
- fg[PRELIGHT] = @{ 0.9, 0.9, 0.9 @}
-
- base[INSENSITIVE] = "#777766"
- text[INSENSITIVE] = @{ 0.60, 0.65, 0.57 @}
-
- bg_pixmap[NORMAL] = "background.xpm"
- bg_pixmap[INSENSITIVE] = "background.xpm"
- bg_pixmap[ACTIVE] = "background.xpm"
- bg_pixmap[PRELIGHT] = "<none>"
-
-@}
-
-style "ruler" = "default"
-@{
- font_name = "helvetica 8"
-@}
-
-@end smallexample
-
- The style @samp{ruler} inherits from @samp{default}. This way you can build
-on existing styles. The syntax for fonts and colors is described below.
-
- As this example shows, it is possible to specify several values for
-foreground and background depending on the widget's @dfn{state}. The
-possible states are:
-
-@table @code
-@item NORMAL
-This is the default state for widgets.
-@item ACTIVE
-This is the state for a widget that is ready to do something. It is
-also for the trough of a scroll bar, i.e. @code{bg[ACTIVE] = "red"}
-sets the scroll bar trough to red. Buttons that have been pressed but
-not released yet (``armed'') are in this state.
-@item PRELIGHT
-This is the state for a widget that can be manipulated, when the mouse
-pointer is over it---for example when the mouse is over the thumb in
-the scroll bar or over a menu item. When the mouse is over a button
-that is not pressed, the button is in this state.
-@item SELECTED
-This is the state for data that has been selected by the user. It can
-be selected text or items selected in a list. This state is not used
-in Emacs.
-@item INSENSITIVE
-This is the state for widgets that are visible, but they can not be
-manipulated in the usual way---for example, buttons that can't be
-pressed, and disabled menu items. To display disabled menu items in
-yellow, use @code{fg[INSENSITIVE] = "yellow"}.
-@end table
-
- Here are the things that can go in a style declaration:
-
-@table @code
-@item bg[@var{state}] = @var{color}
-This specifies the background color for the widget. Note that
-editable text doesn't use @code{bg}; it uses @code{base} instead.
-
-@item base[@var{state}] = @var{color}
-This specifies the background color for editable text. In Emacs, this
-color is used for the background of the text fields in the file
-dialog.
-
-@item bg_pixmap[@var{state}] = "@var{pixmap}"
-This specifies an image background (instead of a background color).
-@var{pixmap} should be the image file name. GTK can use a number of
-image file formats, including XPM, XBM, GIF, JPEG and PNG. If you
-want a widget to use the same image as its parent, use
-@samp{<parent>}. If you don't want any image, use @samp{<none>}.
-@samp{<none>} is the way to cancel a background image inherited from a
-parent style.
-
-You can't specify the file by its absolute file name. GTK looks for
-the pixmap file in directories specified in @code{pixmap_path}.
-@code{pixmap_path} is a colon-separated list of directories within
-double quotes, specified at the top level in a @file{gtkrc} file
-(i.e. not inside a style definition; see example above):
-
-@smallexample
-pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps"
-@end smallexample
-
-@item fg[@var{state}] = @var{color}
-This specifies the foreground color for widgets to use. It is the
-color of text in menus and buttons, and the color for the arrows in
-the scroll bar. For editable text, use @code{text}.
-
-@item text[@var{state}] = @var{color}
-This is the color for editable text. In Emacs, this color is used for the
-text fields in the file dialog.
-
-@item font_name = "@var{font}"
-This specifies the font for text in the widget. @var{font} is a
-Pango font name, for example @samp{Sans Italic 10}, @samp{Helvetica
-Bold 12}, @samp{Courier 14}, @samp{Times 18}. See below for exact
-syntax. The names are case insensitive.
-@end table
-
- There are three ways to specify a color: by name, in hexadecimal
-form, and with an RGB triplet.
-
-@noindent
-A color name is written within double quotes, for example @code{"red"}.
-
-@noindent
-Hexadecimal form is the same as in X:
-@code{#@var{rrrr}@var{gggg}@var{bbbb}}, where all three color specs
-must have the same number of hex digits (1, 2, 3 or 4).
-
-@noindent
-An RGB triplet looks like @code{@{ @var{r}, @var{g}, @var{b} @}},
-where @var{r}, @var{g} and @var{b} are either integers in the range
-0-65535 or floats in the range 0.0-1.0.
-
- Pango font names have the form ``@var{family-list} @var{style-options}
-@var{size}.''
-@cindex Pango font name
-@noindent
-@var{family-list} is a comma separated list of font families optionally
-terminated by a comma. This way you can specify several families and the
-first one found will be used. @var{family} corresponds to the second part in
-an X font name, for example in
-
-@smallexample
--adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1
-@end smallexample
-
-@noindent
-the family name is @samp{times}.
-
-@noindent
-@var{style-options} is a whitespace separated list of words where each word
-is a style, variant, weight, or stretch. The default value for all of
-these is @code{normal}.
-
-@noindent
-A `style' corresponds to the fourth part of an X font name. In X font
-names it is the character @samp{r}, @samp{i} or @samp{o}; in Pango
-font names the corresponding values are @code{normal}, @code{italic},
-or @code{oblique}.
-
-@noindent
-A `variant' is either @code{normal} or @code{small-caps}.
-Small caps is a font with the lower case characters replaced by
-smaller variants of the capital characters.
-
-@noindent
-Weight describes the ``boldness'' of a font. It corresponds to the third
-part of an X font name. It is one of @code{ultra-light}, @code{light},
-@code{normal}, @code{bold}, @code{ultra-bold}, or @code{heavy}.
-
-@noindent
-Stretch gives the width of the font relative to other designs within a
-family. It corresponds to the fifth part of an X font name. It is one of
-@code{ultra-condensed}, @code{extra-condensed}, @code{condensed},
-@code{semi-condensed}, @code{normal}, @code{semi-expanded},
-@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}.
-
-@noindent
-@var{size} is a decimal number that describes the font size in points.
-@end ifnottex
-
-@ignore
- arch-tag: 9b6ff773-48b6-41f6-b2f9-f114b8bdd97f
-@end ignore
projects / emacs.git / commitdiff